Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions pkg/parser/import_field_extractor.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ type importAccumulator struct {
envBuilder strings.Builder // env vars from imported workflows (JSON, one object per line)
envSources map[string]string // env var name → source import path (for conflict detection and header listing)
observabilityBuilder strings.Builder // observability config (first-wins for OTLP endpoint)
structuredOutput string // structured-output config (first-wins)
engines []string
safeOutputs []string
mcpScripts []string
Expand Down Expand Up @@ -449,6 +450,17 @@ func (acc *importAccumulator) extractAllImportFields(content []byte, item import
}
}

// Extract structured-output from imported file (first-wins: only set if not yet populated).
// This enables a shared workflow to declare the output schema without each consuming
// workflow having to repeat it.
if acc.structuredOutput == "" {
structuredOutputContent, structuredOutputErr := extractFieldJSONFromMap(fm, "structured-output", "{}")
if structuredOutputErr == nil && structuredOutputContent != "" && structuredOutputContent != "{}" {
acc.structuredOutput = structuredOutputContent
log.Printf("Extracted structured-output from import: %s", item.fullPath)
}
}

return nil
}

Expand Down Expand Up @@ -486,6 +498,7 @@ func (acc *importAccumulator) toImportsResult(topologicalOrder []string) *Import
MergedEnvSources: acc.envSources,
MergedFeatures: acc.features,
MergedObservability: acc.observabilityBuilder.String(),
MergedStructuredOutput: acc.structuredOutput,
ImportedFiles: topologicalOrder,
AgentFile: acc.agentFile,
AgentImportSpec: acc.agentImportSpec,
Expand Down
1 change: 1 addition & 0 deletions pkg/parser/import_processor.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ type ImportsResult struct {
MergedEnvSources map[string]string // env var name → source import path (for conflict detection and lock file header listing)
MergedFeatures []map[string]any // Merged features configuration from all imports (parsed YAML structures)
MergedObservability string // Observability config (JSON) from first import that defines it (first-wins)
MergedStructuredOutput string // Structured-output config (JSON) from first import that defines it (first-wins)
ImportedFiles []string // List of imported file paths (for manifest)
AgentFile string // Path to custom agent file (if imported)
AgentImportSpec string // Original import specification for agent file (e.g., "owner/repo/path@ref")
Expand Down
54 changes: 54 additions & 0 deletions pkg/parser/schemas/main_workflow_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -4548,6 +4548,60 @@
}
]
},
"structured-output": {
"type": "object",
"description": "Constrains the agent's final response to a declared JSON schema. Only supported with the codex engine, which natively enforces the schema via --output-schema.",
"properties": {
"schema": {
"type": "object",
"description": "Inline JSON Schema (draft-07 or 2020-12) that the agent's final response must conform to. Use this for small schemas defined directly in the workflow frontmatter.",
"examples": [
{
"type": "object",
"properties": {
"decision": {
"type": "string",
"enum": ["APPROVE", "REQUEST_CHANGES", "ESCALATE"]
},
"reasoning": {
"type": "string",
"minLength": 10
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": ["decision", "reasoning", "confidence"],
"additionalProperties": false
}
]
},
"schema-file": {
"type": "string",
"description": "Path to a JSON Schema file relative to the repository root. Use this for larger schemas stored in a separate file (e.g., .github/schemas/triage-output.schema.json).",
"examples": [".github/schemas/triage-output.schema.json", ".github/schemas/pr-review.schema.json"]
}
},
"additionalProperties": false,
"examples": [
{
"schema": {
"type": "object",
"properties": {
"decision": { "type": "string", "enum": ["APPROVE", "REQUEST_CHANGES", "ESCALATE"] },
"reasoning": { "type": "string" }
},
"required": ["decision", "reasoning"],
"additionalProperties": false
}
},
{
"schema-file": ".github/schemas/triage-output.schema.json"
}
]
},
"safe-outputs": {
"type": "object",
"$comment": "Required if workflow creates or modifies GitHub resources. Operations requiring safe-outputs: autofix-code-scanning-alert, add-comment, add-labels, add-reviewer, assign-milestone, assign-to-agent, assign-to-user, close-discussion, close-issue, close-pull-request, create-agent-session, create-agent-task (deprecated, use create-agent-session), create-code-scanning-alert, create-discussion, create-issue, create-project, create-project-status-update, create-pull-request, create-pull-request-review-comment, dispatch-workflow, hide-comment, link-sub-issue, mark-pull-request-as-ready-for-review, merge-pull-request, missing-data, missing-tool, noop, push-to-pull-request-branch, remove-labels, reply-to-pull-request-review-comment, resolve-pull-request-review-thread, set-issue-type, submit-pull-request-review, threat-detection, unassign-from-user, update-discussion, update-issue, update-project, update-pull-request, update-release, upload-artifact, upload-asset. See documentation for complete details.",
Expand Down
43 changes: 39 additions & 4 deletions pkg/workflow/codex_engine.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
package workflow

import (
"encoding/base64"
"encoding/json"
"fmt"
"maps"
"regexp"
Expand Down Expand Up @@ -192,6 +194,31 @@ func (e *CodexEngine) GetExecutionSteps(workflowData *WorkflowData, logFile stri
customArgsParam += customArgsParamSb.String()
}

// Build structured output parameter if configured.
// The Codex CLI supports --output-schema <FILE> to constrain the agent's final
// response to a declared JSON schema (see openai/codex codex-rs/exec/src/cli.rs).
const codexOutputSchemaPath = "/tmp/gh-aw/output-schema.json"
var outputSchemaSetup string
var outputSchemaParam string
if workflowData.StructuredOutput != nil {
if len(workflowData.StructuredOutput.Schema) > 0 {
// Inline schema: marshal to JSON, base64-encode, and write to a temp file at runtime.
// Base64 encoding avoids shell quoting issues with arbitrary JSON content.
schemaJSON, err := json.Marshal(workflowData.StructuredOutput.Schema)
if err == nil {
schemaBase64 := base64.StdEncoding.EncodeToString(schemaJSON)
outputSchemaSetup = fmt.Sprintf("printf '%%s' '%s' | base64 --decode > %s",
schemaBase64, codexOutputSchemaPath)
outputSchemaParam = " --output-schema " + codexOutputSchemaPath
codexEngineLog.Printf("Structured output: inline schema with %d fields, path=%s", len(workflowData.StructuredOutput.Schema), codexOutputSchemaPath)
}
} else if workflowData.StructuredOutput.SchemaFile != "" {
// Schema file: reference the file from the workspace directly.
outputSchemaParam = fmt.Sprintf(` --output-schema "$GITHUB_WORKSPACE/%s"`, workflowData.StructuredOutput.SchemaFile)
codexEngineLog.Printf("Structured output: schema-file=%s", workflowData.StructuredOutput.SchemaFile)
}
}

// Build the Codex command
// Determine which command to use
var commandName string
Expand All @@ -203,8 +230,8 @@ func (e *CodexEngine) GetExecutionSteps(workflowData *WorkflowData, logFile stri
commandName = "codex"
}

codexCommand := fmt.Sprintf("%s %sexec%s%s%s%s\"$INSTRUCTION\"",
commandName, modelParam, webSearchParam, webFetchParam, fullAutoParam, customArgsParam)
codexCommand := fmt.Sprintf("%s %sexec%s%s%s%s%s\"$INSTRUCTION\"",
commandName, modelParam, webSearchParam, webFetchParam, fullAutoParam, customArgsParam, outputSchemaParam)

// Build the full command with agent file handling and AWF wrapping if enabled
var command string
Expand Down Expand Up @@ -235,6 +262,10 @@ func (e *CodexEngine) GetExecutionSteps(workflowData *WorkflowData, logFile stri
if mcpCLIPath := GetMCPCLIPathSetup(workflowData); mcpCLIPath != "" {
codexCommandWithSetup = fmt.Sprintf("%s && %s", mcpCLIPath, codexCommandWithSetup)
}
// Prepend schema file setup when structured output is configured
if outputSchemaSetup != "" {
codexCommandWithSetup = fmt.Sprintf("%s && %s", outputSchemaSetup, codexCommandWithSetup)
}

command = BuildAWFCommand(AWFCommandConfig{
EngineName: "codex",
Expand All @@ -256,12 +287,16 @@ func (e *CodexEngine) GetExecutionSteps(workflowData *WorkflowData, logFile stri
// For engines that do not support native agent-file handling (including Codex),
// the compiler prepends the agent file content to prompt.txt so no special
// shell variable juggling is needed here.
schemaSetupLine := ""
if outputSchemaSetup != "" {
schemaSetupLine = "\n" + outputSchemaSetup
}
command = fmt.Sprintf(`set -o pipefail
touch %s
(umask 177 && touch %s)
INSTRUCTION="$(cat "$GH_AW_PROMPT")"
mkdir -p "$CODEX_HOME/logs"
%s 2>&1 | tee %s`, AgentStepSummaryPath, logFile, codexCommand, logFile)
mkdir -p "$CODEX_HOME/logs"%s
%s 2>&1 | tee %s`, AgentStepSummaryPath, logFile, schemaSetupLine, codexCommand, logFile)
}

// Get effective GitHub token based on precedence: custom token > default
Expand Down
92 changes: 92 additions & 0 deletions pkg/workflow/codex_engine_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -1007,3 +1007,95 @@ func TestCodexEngineWithExpressionVersion(t *testing.T) {
t.Errorf("Expression should NOT be embedded directly in npm install command, got:\n%s", installStep)
}
}

func TestCodexEngineStructuredOutputInlineSchema(t *testing.T) {
engine := NewCodexEngine()

workflowData := &WorkflowData{
Name: "test-structured-output",
AI: "codex",
StructuredOutput: &StructuredOutputConfig{
Schema: map[string]any{
"type": "object",
"properties": map[string]any{
"decision": map[string]any{
"type": "string",
"enum": []any{"APPROVE", "REQUEST_CHANGES", "ESCALATE"},
},
"reasoning": map[string]any{
"type": "string",
},
},
"required": []any{"decision", "reasoning"},
"additionalProperties": false,
},
},
}

steps := engine.GetExecutionSteps(workflowData, "/tmp/codex.log")
if len(steps) == 0 {
t.Fatal("Expected execution steps, got none")
}

stepContent := strings.Join([]string(steps[0]), "\n")

// Should include --output-schema flag
if !strings.Contains(stepContent, "--output-schema /tmp/gh-aw/output-schema.json") {
t.Errorf("Expected --output-schema flag in execution step, got:\n%s", stepContent)
}

// Should include base64 decode command to write the schema file
if !strings.Contains(stepContent, "base64 --decode > /tmp/gh-aw/output-schema.json") {
t.Errorf("Expected base64 decode command for schema file setup, got:\n%s", stepContent)
}
}

func TestCodexEngineStructuredOutputSchemaFile(t *testing.T) {
engine := NewCodexEngine()

workflowData := &WorkflowData{
Name: "test-structured-output-file",
AI: "codex",
StructuredOutput: &StructuredOutputConfig{
SchemaFile: ".github/schemas/output.schema.json",
},
}

steps := engine.GetExecutionSteps(workflowData, "/tmp/codex.log")
if len(steps) == 0 {
t.Fatal("Expected execution steps, got none")
}

stepContent := strings.Join([]string(steps[0]), "\n")

// Should include --output-schema flag referencing the workspace file
if !strings.Contains(stepContent, `--output-schema "$GITHUB_WORKSPACE/.github/schemas/output.schema.json"`) {
t.Errorf("Expected --output-schema flag with workspace path, got:\n%s", stepContent)
}

// Should NOT include base64 setup for schema-file case
if strings.Contains(stepContent, "base64 --decode") {
t.Errorf("Should not have base64 decode for schema-file case, got:\n%s", stepContent)
}
}

func TestCodexEngineNoStructuredOutput(t *testing.T) {
engine := NewCodexEngine()

workflowData := &WorkflowData{
Name: "test-no-structured-output",
AI: "codex",
}

steps := engine.GetExecutionSteps(workflowData, "/tmp/codex.log")
if len(steps) == 0 {
t.Fatal("Expected execution steps, got none")
}

stepContent := strings.Join([]string(steps[0]), "\n")

// Should NOT include --output-schema flag when no structured output is configured
if strings.Contains(stepContent, "--output-schema") {
t.Errorf("Expected no --output-schema flag when structured output not configured, got:\n%s", stepContent)
}
}
29 changes: 29 additions & 0 deletions pkg/workflow/compiler_orchestrator_workflow.go
Original file line number Diff line number Diff line change
Expand Up @@ -302,6 +302,35 @@ func (c *Compiler) extractAdditionalConfigurations(
workflowData.MCPScripts = c.mergeMCPScripts(workflowData.MCPScripts, importsResult.MergedMCPScripts)
}

// Extract structured-output configuration from frontmatter (main workflow takes precedence).
// Fall back to the first imported workflow that defines it (first-wins from imports).
if structuredOutputRaw, exists := frontmatter["structured-output"]; exists {
if structuredOutputMap, ok := structuredOutputRaw.(map[string]any); ok {
config := &StructuredOutputConfig{}
if schema, ok := structuredOutputMap["schema"].(map[string]any); ok {
config.Schema = schema
}
if schemaFile, ok := structuredOutputMap["schema-file"].(string); ok {
config.SchemaFile = schemaFile
}
workflowData.StructuredOutput = config
}
} else if importsResult.MergedStructuredOutput != "" {
// Fall back to first imported workflow that defines structured-output
var structuredOutputMap map[string]any
if err := json.Unmarshal([]byte(importsResult.MergedStructuredOutput), &structuredOutputMap); err == nil {
config := &StructuredOutputConfig{}
if schema, ok := structuredOutputMap["schema"].(map[string]any); ok {
config.Schema = schema
}
if schemaFile, ok := structuredOutputMap["schema-file"].(string); ok {
config.SchemaFile = schemaFile
}
workflowData.StructuredOutput = config
orchestratorWorkflowLog.Print("Inherited structured-output from imported workflow")
}
}

// Extract safe-jobs from safe-outputs.jobs location
topSafeJobs := extractSafeJobsFromFrontmatter(frontmatter)

Expand Down
1 change: 1 addition & 0 deletions pkg/workflow/compiler_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,7 @@ type WorkflowData struct {
SandboxConfig *SandboxConfig // parsed sandbox configuration (AWF or SRT)
SafeOutputs *SafeOutputsConfig // output configuration for automatic output routes
MCPScripts *MCPScriptsConfig // mcp-scripts configuration for custom MCP tools
StructuredOutput *StructuredOutputConfig // structured output configuration for constraining agent responses to a JSON schema
LabelNames []string // label names that must match for pull_request_target labeled events (on.labels)
Roles []string // permission levels required to trigger workflow
Bots []string // allow list of bot identifiers that can trigger workflow
Expand Down
6 changes: 6 additions & 0 deletions pkg/workflow/compiler_validators.go
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,12 @@ func (c *Compiler) validateToolConfiguration(workflowData *WorkflowData, markdow
return err
}

// Validate structured-output configuration
log.Printf("Validating structured-output configuration")
if err := validateStructuredOutput(workflowData); err != nil {
return formatCompilerError(markdownPath, "error", err.Error(), err)
}

// Validate sandbox configuration
log.Printf("Validating sandbox configuration")
if err := validateSandboxConfig(workflowData); err != nil {
Expand Down
17 changes: 17 additions & 0 deletions pkg/workflow/frontmatter_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,10 @@ type FrontmatterConfig struct {
InlinedImports bool `json:"inlined-imports,omitempty"` // If true, inline all imports at compile time instead of using runtime-import macros
Resources []string `json:"resources,omitempty"` // Additional workflow .md or action .yml files to fetch alongside this workflow

// Structured output configuration for constraining agent responses to a JSON schema.
// Only supported with the codex engine.
StructuredOutput *StructuredOutputConfig `json:"structured-output,omitempty"`

// Metadata
Metadata map[string]string `json:"metadata,omitempty"` // Custom metadata key-value pairs
SecretMasking *SecretMaskingConfig `json:"secret-masking,omitempty"`
Expand All @@ -223,3 +227,16 @@ type FrontmatterConfig struct {
CheckoutConfigs []*CheckoutConfig `json:"-"` // Parsed checkout configs (not in JSON)
CheckoutDisabled bool `json:"-"` // true when checkout: false is set in frontmatter
}

// StructuredOutputConfig holds configuration for constraining the agent's response
// to a declared JSON schema. Only supported with the codex engine, which natively
// enforces the schema via --output-schema.
type StructuredOutputConfig struct {
// Schema is an inline JSON Schema that the agent's final response must conform to.
// Use this for small schemas defined directly in the workflow frontmatter.
Schema map[string]any `json:"schema,omitempty"`

// SchemaFile is a path to a JSON Schema file relative to the repository root.
// Use this for larger schemas stored in a separate file (e.g., .github/schemas/triage.schema.json).
SchemaFile string `json:"schema-file,omitempty"`
}
Loading