feat(workflow): native-first schema for codex/claude agent()

Hardcode NATIVE_SCHEMA_PROVIDERS; attempt 0 uses adapter schema without
prompt bloat, then prompt-repair retries with Ajv. Wire schema through
runProvider / CLI worker. Document in skill.

Author: Waishnav

skills/dynamic-workflows/SKILL.md

@@ -77,6 +77,7 @@ const out = await agent('Return JSON findings', {
   },
 })
 // out is validated object; engine retries ≤2 on invalid JSON
+// codex/claude: native structured output first, then prompt repair; others: prompt+Ajv
 ```
 
 ### Providers

src/workflow-api.ts

@@ -25,11 +25,15 @@ export interface WorkflowProviderRunInput {
   signal?: AbortSignal;
   label?: string;
   phase?: string;
+  /** JSON Schema for native structured output (codex/claude). */
+  schema?: object;
 }
 
 export interface WorkflowProviderRunResult {
   finalResponse: string;
   providerSessionId?: string;
+  /** Provider-native structured object when schema was requested. */
+  structured?: unknown;
 }
 
 export type WorkflowRunProvider = (
@@ -346,14 +350,21 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
         const enforced = await enforceAgentSchema({
           schema: agentOpts.schema,
           prompt,
-          run: (p) => deps.runProvider({ ...providerBase, prompt: p }),
-          onRetry: ({ attempt, errors }) => {
+          provider,
+          run: (p) =>
+            deps.runProvider({
+              ...providerBase,
+              prompt: p,
+              // Keep schema on adapter for codex/claude native+repair attempts.
+              schema: agentOpts.schema,
+            }),
+          onRetry: ({ attempt, errors, mode }) => {
             deps.journal.appendEvent({
               runId: deps.runId,
               type: "schema_retry",
               phase,
               label: agentOpts.label,
-              data: { callIndex: index, attempt, errors },
+              data: { callIndex: index, attempt, errors, mode },
             });
           },
         });
@@ -362,6 +373,7 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
         result = {
           finalResponse: enforced.finalResponse,
           providerSessionId: enforced.providerSessionId,
+          structured: enforced.value,
         };
       } else {
         result = await deps.runProvider(providerBase);

src/workflow-cli.ts

@@ -329,10 +329,12 @@ export async function runWorkflowWorker(
           model: input.model,
           effort: input.effort,
           writeMode: "allowed",
+          schema: input.schema,
         });
         return {
           finalResponse: providerResult.finalResponse,
           providerSessionId: providerResult.providerSessionId ?? undefined,
+          structured: providerResult.structured,
         };
       },
       resolveNestedSource: async (ref) => {

src/workflow-schema.test.ts

@@ -3,6 +3,7 @@ import {
   augmentPromptForSchema,
   enforceAgentSchema,
   formatAjvErrors,
+  NATIVE_SCHEMA_PROVIDERS,
 } from "./workflow-schema.js";
 import { WorkflowEngineError } from "./workflow-api.js";
 
@@ -21,6 +22,10 @@ assert.equal(
   "/n must be number",
 );
 
+assert.ok(NATIVE_SCHEMA_PROVIDERS.has("codex"));
+assert.ok(NATIVE_SCHEMA_PROVIDERS.has("claude"));
+assert.ok(!NATIVE_SCHEMA_PROVIDERS.has("opencode"));
+
 {
   let attempts = 0;
   const result = await enforceAgentSchema({
@@ -40,6 +45,7 @@ assert.equal(
   assert.deepEqual(result.value, { n: 2 });
   assert.equal(result.attempts, 2);
   assert.equal(result.providerSessionId, "sess");
+  assert.equal(result.mode, "prompt");
 }
 
 {
@@ -56,4 +62,85 @@ assert.equal(
   );
 }
 
+// Native provider: structured on attempt 0 → single attempt, raw prompt.
+{
+  const seen: Array<{ prompt: string; mode?: string }> = [];
+  const result = await enforceAgentSchema({
+    schema: {
+      type: "object",
+      properties: { n: { type: "number" } },
+      required: ["n"],
+      additionalProperties: false,
+    },
+    prompt: "give n",
+    provider: "codex",
+    run: async (prompt, opts) => {
+      seen.push({ prompt, mode: opts?.mode });
+      return { finalResponse: "noise", structured: { n: 7 } };
+    },
+  });
+  assert.deepEqual(result.value, { n: 7 });
+  assert.equal(result.attempts, 1);
+  assert.equal(result.mode, "native");
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0]?.prompt, "give n");
+  assert.equal(seen[0]?.mode, "native");
+  assert.ok(!seen[0]?.prompt.includes("ONLY a JSON"));
+}
+
+// Native fail then prompt repair.
+{
+  const seen: Array<{ prompt: string; mode?: string }> = [];
+  const retries: Array<{ attempt: number; mode: string }> = [];
+  const result = await enforceAgentSchema({
+    schema: {
+      type: "object",
+      properties: { n: { type: "number" } },
+      required: ["n"],
+      additionalProperties: false,
+    },
+    prompt: "give n",
+    provider: "claude",
+    onRetry: ({ attempt, mode }) => {
+      retries.push({ attempt, mode });
+    },
+    run: async (prompt, opts) => {
+      seen.push({ prompt, mode: opts?.mode });
+      if (opts?.mode === "native") {
+        return { finalResponse: '{"n":"bad"}', structured: { n: "bad" } };
+      }
+      return { finalResponse: '{"n":3}', structured: { n: 3 } };
+    },
+  });
+  assert.deepEqual(result.value, { n: 3 });
+  assert.equal(result.attempts, 2);
+  assert.equal(result.mode, "prompt");
+  assert.equal(seen[0]?.mode, "native");
+  assert.equal(seen[1]?.mode, "prompt");
+  assert.ok(seen[1]?.prompt.includes("ONLY a JSON"));
+  assert.deepEqual(retries[0], { attempt: 1, mode: "native" });
+}
+
+// Non-native never gets native mode.
+{
+  const modes: string[] = [];
+  const result = await enforceAgentSchema({
+    schema: {
+      type: "object",
+      properties: { n: { type: "number" } },
+      required: ["n"],
+    },
+    prompt: "give n",
+    provider: "opencode",
+    run: async (prompt, opts) => {
+      modes.push(opts?.mode ?? "missing");
+      assert.ok(prompt.includes("ONLY a JSON"));
+      return { finalResponse: '{"n":1}' };
+    },
+  });
+  assert.deepEqual(result.value, { n: 1 });
+  assert.deepEqual(modes, ["prompt"]);
+  assert.equal(result.mode, "prompt");
+}
+
 console.log("workflow-schema.test.ts: ok");

src/workflow-schema.ts

@@ -5,6 +5,9 @@ import type { WorkflowProviderRunResult, WorkflowRunProvider } from "./workflow-
 
 const require = createRequire(import.meta.url);
 
+/** Providers with a real structured-output API (hardcoded — no capability probe). */
+export const NATIVE_SCHEMA_PROVIDERS = new Set(["codex", "claude"]);
+
 type AjvLike = new (opts?: object) => {
   compile: (schema: object) => ((data: unknown) => boolean) & {
     errors?: Array<{ instancePath?: string; message?: string }> | null;
@@ -23,11 +26,25 @@ function loadAjv(): AjvLike {
   }
 }
 
+export type SchemaEnforceMode = "native" | "prompt";
+
 export interface EnforceSchemaInput {
   schema: object;
   prompt: string;
-  run: (prompt: string) => Promise<WorkflowProviderRunResult>;
-  onRetry?: (info: { attempt: number; errors: string }) => void;
+  /**
+   * Provider id for native-vs-prompt policy. When in NATIVE_SCHEMA_PROVIDERS,
+   * attempt 0 uses raw prompt + native structured path; later attempts repair via prompt.
+   */
+  provider?: string;
+  run: (
+    prompt: string,
+    opts?: { mode: SchemaEnforceMode },
+  ) => Promise<WorkflowProviderRunResult>;
+  onRetry?: (info: {
+    attempt: number;
+    errors: string;
+    mode: SchemaEnforceMode;
+  }) => void;
   maxRetries?: number;
 }
 
@@ -36,10 +53,12 @@ export interface EnforceSchemaResult {
   finalResponse: string;
   providerSessionId?: string;
   attempts: number;
+  mode: SchemaEnforceMode;
 }
 
 /**
- * Augment prompt → run → extract JSON → Ajv validate → retry ≤2.
+ * Native-first for codex/claude; otherwise prompt+extract+Ajv. Always Ajv-validate.
+ * Retries ≤ WORKFLOW_MAX_SCHEMA_RETRIES after the first attempt.
  */
 export async function enforceAgentSchema(
   input: EnforceSchemaInput,
@@ -48,26 +67,31 @@ export async function enforceAgentSchema(
   const ajv = new Ajv({ allErrors: true, strict: false });
   const validate = ajv.compile(input.schema);
   const maxRetries = input.maxRetries ?? WORKFLOW_MAX_SCHEMA_RETRIES;
+  const native = Boolean(input.provider && NATIVE_SCHEMA_PROVIDERS.has(input.provider));
   const basePrompt = augmentPromptForSchema(input.prompt, input.schema);
 
-  let lastResponse = "";
-  let lastSession: string | undefined;
   let lastErrors = "unknown validation error";
 
   for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    const mode: SchemaEnforceMode = native && attempt === 0 ? "native" : "prompt";
+
     const prompt =
-      attempt === 0
-        ? basePrompt
-        : `${basePrompt}\n\nPrevious JSON failed validation:\n${lastErrors}\nReturn only corrected JSON.`;
+      mode === "native"
+        ? input.prompt
+        : attempt === 0
+          ? basePrompt
+          : `${basePrompt}\n\nPrevious JSON failed validation:\n${lastErrors}\nReturn only corrected JSON.`;
+
+    const result = await input.run(prompt, { mode });
 
-    const result = await input.run(prompt);
-    lastResponse = result.finalResponse;
-    lastSession = result.providerSessionId ?? lastSession;
+    const extracted =
+      result.structured !== undefined
+        ? result.structured
+        : tryExtractJson(result.finalResponse);
 
-    const extracted = tryExtractJson(result.finalResponse);
     if (extracted === undefined) {
       lastErrors = "Response was not valid JSON";
-      input.onRetry?.({ attempt: attempt + 1, errors: lastErrors });
+      input.onRetry?.({ attempt: attempt + 1, errors: lastErrors, mode });
       continue;
     }
 
@@ -78,11 +102,12 @@ export async function enforceAgentSchema(
         finalResponse: result.finalResponse,
         providerSessionId: result.providerSessionId,
         attempts: attempt + 1,
+        mode,
       };
     }
 
     lastErrors = formatAjvErrors(validate.errors);
-    input.onRetry?.({ attempt: attempt + 1, errors: lastErrors });
+    input.onRetry?.({ attempt: attempt + 1, errors: lastErrors, mode });
   }
 
   throw new WorkflowEngineError(
@@ -122,11 +147,13 @@ export function schemaAwareRunProvider(
   return enforceAgentSchema({
     schema,
     prompt: base.prompt,
+    provider: base.provider,
     onRetry,
     run: (prompt) =>
       runProvider({
         ...base,
         prompt,
+        schema,
       }),
   });
 }