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_XXXXXXXXXXXX where:

• aw_ is a fixed prefix identifying agentic workflow temporary IDs
• XXXXXXXXXXXX is a 12-character lowercase hexadecimal string (6 random bytes)

Example: aw_abc123def456

Implementation Components

1. Shared Module: temporary_id.cjs

Location: pkg/workflow/js/temporary_id.cjs

This module provides shared utilities for temporary ID handling:

// 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:

func (c *Compiler) build<JobName>Job(data *WorkflowData, mainJobName string, createIssueJobName string) (*Job, error) {

2. Add environment variable to pass the temporary ID map:

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:

needs := []string{mainJobName}
if createIssueJobName != "" {
    needs = append(needs, createIssueJobName)
}

4. Update the SafeOutputJobConfig to use the dynamic needs:

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:

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:

const { loadTemporaryIdMap, resolveIssueNumber } = require("./temporary_id.cjs");

2. Load the temporary ID map at the start of main():

const temporaryIdMap = loadTemporaryIdMap();
if (temporaryIdMap.size > 0) {
    core.info(`Loaded temporary ID map with ${temporaryIdMap.size} entries`);
}

3. Use resolveIssueNumber() to resolve issue numbers:

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:

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

safe-outputs:
  create-issue:
    title-prefix: "[Parent] "
    labels: [tracking]
    max: 3
  link-sub-issue:
    max: 10

Agent Output

{"type": "create_issue", "temporary_id": "aw_abc123def456", "title": "Parent: Feature X", "body": "..."}
{"type": "link_sub_issue", "parent_issue_number": "aw_abc123def456", "sub_issue_number": 42}
{"type": "link_sub_issue", "parent_issue_number": "aw_abc123def456", "sub_issue_number": 43}

Execution Flow

1. main job: Agent generates output with temporary ID aw_abc123def456
2. create_issue job: Creates issue #100, outputs {"aw_abc123def456": 100}
3. link_sub_issue job:
   • Loads temporary ID map
   • Resolves aw_abc123def456 → 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