temporary-id-safe-output

# Adding Temporary ID Support to Safe Output Jobs This document outlines the implementation plan for adding temporary ID support to safe output jobs. Temporary IDs allow agents to reference newly created issues within the same workflow run before they have actual GitHub issue numbers. ## Problem Statement When an agent needs to create a parent issue and immediately link sub-issues to it in the same workflow run, the agent doesn't know the actual issue number until the `create_issue` job completes. Temporary IDs bridge this gap by allowing the agent to use placeholder IDs that are resolved to actual issue numbers at execution time. ## Temporary ID Format Temporary IDs follow the pattern `aw_[A-Za-z0-9]{3,8}` where: - `aw_` is a fixed prefix identifying agentic workflow temporary IDs - `XXXXXXXX` is a 3-8 character alphanumeric string (A-Za-z0-9) Example: `aw_abc`, `aw_abc123`, `aw_Test123` ## Implementation Components ### 1. Shared Module: `temporary_id.cjs` Location: `pkg/workflow/js/temporary_id.cjs` This module provides shared utilities for temporary ID handling: ```javascript // Core functions generateTemporaryId() // Generate new temporary ID isTemporaryId(value) // Check if value is a temporary ID normalizeTemporaryId(tempId) // Normalize to lowercase for map lookups loadTemporaryIdMap() // Load map from GH_AW_TEMPORARY_ID_MAP env var resolveIssueNumber(value, map) // Resolve value to issue number (supports temp IDs) replaceTemporaryIdReferences(text, map) // Replace #aw_XXX references in text ``` ### 2. Producer Job: `create_issue` The `create_issue` job outputs a temporary ID map that other jobs can consume: **Go changes** (`pkg/workflow/create_issue.go`): - No changes needed - already outputs `temporary_id_map` **JavaScript changes** (`pkg/workflow/js/create_issue.cjs`): - Generate temporary ID for each created issue - Build map of `temporary_id -> issue_number` - Output map via `core.setOutput("temporary_id_map", JSON.stringify(map))` ### 3. Consumer Job: Adding Temporary ID Support For each safe output job that needs to resolve temporary IDs: #### Step 1: Update Go Job Builder In `pkg/workflow/<job_name>.go`: 1. Add `createIssueJobName` parameter to the build function: ```go func (c *Compiler) build<JobName>Job(data *WorkflowData, mainJobName string, createIssueJobName string) (*Job, error) { ``` 2. Add environment variable to pass the temporary ID map: ```go if createIssueJobName != "" { customEnvVars = append(customEnvVars, fmt.Sprintf(" GH_AW_TEMPORARY_ID_MAP: ${{ needs.%s.outputs.temporary_id_map }}\n", createIssueJobName)) } ``` 3. Add `create_issue` to the job's `needs` array: ```go needs := []string{mainJobName} if createIssueJobName != "" { needs = append(needs, createIssueJobName) } ``` 4. Update the `SafeOutputJobConfig` to use the dynamic needs: ```go return c.buildSafeOutputJob(data, SafeOutputJobConfig{ // ... Needs: needs, // ... }) ``` #### Step 2: Update Compiler Jobs In `pkg/workflow/compiler_jobs.go`: Pass the `createIssueJobName` when building the job: ```go job, err := c.build<JobName>Job(data, mainJobName, createIssueJobName) ``` #### Step 3: Update JavaScript Script In `pkg/workflow/js/<job_name>.cjs`: 1. Import the temporary ID utilities: ```javascript const { loadTemporaryIdMap, resolveIssueNumber } = require("./temporary_id.cjs"); ``` 2. Load the temporary ID map at the start of main(): ```javascript const temporaryIdMap = loadTemporaryIdMap(); if (temporaryIdMap.size > 0) { core.info(`Loaded temporary ID map with ${temporaryIdMap.size} entries`); } ``` 3. Use `resolveIssueNumber()` to resolve issue numbers: ```javascript const resolved = resolveIssueNumber(item.issue_number, temporaryIdMap); if (resolved.errorMessage) { core.warning(`Failed to resolve issue: ${resolved.errorMessage}`); continue; } const issueNumber = resolved.resolved; if (resolved.wasTemporaryId) { core.info(`Resolved temporary ID '${item.issue_number}' to issue #${issueNumber}`); } ``` #### Step 4: Update Agent Ingestion Validation In `pkg/workflow/js/collect_ndjson_output.cjs`: Add validation for fields that accept temporary IDs: ```javascript function isValidIssueNumberOrTemporaryId(value) { if (typeof value === "number" && Number.isInteger(value) && value > 0) { return true; } if (typeof value === "string" && /^aw_[0-9a-f]{12}$/i.test(value)) { return true; } return false; } ``` Use this validation for fields like `parent_issue_number`, `sub_issue_number`, etc. ### 4. Failure Handling When temporary ID resolution fails, the job should: - Log a warning with `core.warning()` instead of failing with `core.setFailed()` - Continue processing other items - Include failures in the step summary - Complete successfully with warnings This ensures that: - Partial success is possible (some links may work while others fail) - The workflow doesn't fail catastrophically due to a single resolution failure - Users can review warnings in the step summary ## Example Usage ### Workflow Configuration ```yaml safe-outputs: create-issue: title-prefix: "[Parent] " labels: [tracking] max: 3 link-sub-issue: max: 10 ``` ### Agent Output ```json {"type": "create_issue", "temporary_id": "aw_abc123", "title": "Parent: Feature X", "body": "..."} {"type": "link_sub_issue", "parent_issue_number": "aw_abc123", "sub_issue_number": 42} {"type": "link_sub_issue", "parent_issue_number": "aw_abc123", "sub_issue_number": 43} ``` ### Execution Flow 1. `main` job: Agent generates output with temporary ID `aw_abc123` 2. `create_issue` job: Creates issue #100, outputs `{"aw_abc123": 100}` 3. `link_sub_issue` job: - Loads temporary ID map - Resolves `aw_abc123` → `100` - Links issues #42 and #43 as sub-issues of #100 ## Jobs That Support Temporary IDs | Job | Field(s) | Status | |-----|----------|--------| | `link_sub_issue` | `parent_issue_number`, `sub_issue_number` | ✅ Implemented | | `add_comment` | `issue_number` (via text replacement) | ✅ Implemented | | `update_issue` | `issue_number` | 🔄 Can be added | | `close_pull_request` | - | N/A (uses PR numbers) | ## Testing ### Unit Tests Add tests in `pkg/workflow/js/temporary_id.test.cjs` for: - `isTemporaryId()` with valid and invalid inputs - `resolveIssueNumber()` with temporary IDs and regular numbers - `loadTemporaryIdMap()` with various JSON inputs ### Integration Tests Add tests in `pkg/workflow/<job_name>_dependencies_test.go` to verify: - Job includes `create_issue` in needs when configured - `GH_AW_TEMPORARY_ID_MAP` env var is set correctly - Job works without `create_issue` dependency ## Security Considerations 1. Temporary IDs are only valid within a single workflow run 2. The map is passed via environment variables (not exposed externally) 3. Agents cannot forge temporary IDs to reference issues from other workflows 4. Resolution failures are logged but don't expose the temporary ID map contents ## Checklist for Adding Support to a New Job - [ ] Update Go job builder to accept `createIssueJobName` parameter - [ ] Add `GH_AW_TEMPORARY_ID_MAP` environment variable - [ ] Update needs array to include `create_issue` conditionally - [ ] Update compiler_jobs.go to pass `createIssueJobName` - [ ] Import temporary ID utilities in JavaScript script - [ ] Use `resolveIssueNumber()` for issue number fields - [ ] Update validation in `collect_ndjson_output.cjs` if needed - [ ] Add unit tests for the resolution logic - [ ] Add integration tests for job dependencies - [ ] Update documentation --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/github) — claim your Tome and manage your conversions. <!-- tomevault:4.0:skill_md:2026-04-11 -->