planpong 0.3.0 → 0.4.2

package/dist/src/prompts/reviewer.d.ts

@@ -1,7 +1,7 @@
 import type { IssueResponse } from "../schemas/revision.js";
 export type ReviewPhase = "direction" | "risk" | "detail";
 export declare function getReviewPhase(round: number): ReviewPhase;
-export declare function buildReviewPrompt(planContent: string, priorDecisions: string | null, phase?: ReviewPhase): string;
+export declare function buildReviewPrompt(planContent: string, priorDecisions: string | null, phase?: ReviewPhase, structuredOutput?: boolean): string;
 export declare function formatPriorDecisions(rounds: Array<{
     round: number;
     responses: IssueResponse[];

package/dist/src/prompts/reviewer.js

@@ -180,7 +180,7 @@ If the plan is approved with no issues, use:
 { "verdict": "approved", "summary": "...", "issues": [] }
 \`\`\``;
 }
-export function buildReviewPrompt(planContent, priorDecisions, phase = "detail") {
+export function buildReviewPrompt(planContent, priorDecisions, phase = "detail", structuredOutput = false) {
     const instructions = phase === "direction"
         ? buildDirectionReviewInstructions()
         : phase === "risk"
@@ -191,6 +191,24 @@ export function buildReviewPrompt(planContent, priorDecisions, phase = "detail")
         : phase === "risk"
             ? buildRiskJsonSchema()
             : buildDetailJsonSchema();
+    if (structuredOutput) {
+        // Structured-output mode. Some providers (OpenAI/Codex) constrain output
+        // at the token level; others (Claude) only validate post-hoc. Emphatic
+        // JSON-only instructions help the advisory case comply; the constrained
+        // case ignores them harmlessly.
+        return `${instructions}
+## Plan to Review
+
+${planContent}
+
+## Your Task
+
+Output ONLY a single JSON object conforming to the schema below. The first character of your response must be \`{\` and the last must be \`}\`. No prose. No markdown. No code fences. No preamble or explanation. No trailing text.
+
+Schema:
+
+${jsonSchema}`;
+    }
     return `${instructions}
 ## Plan to Review
 

package/dist/src/prompts/reviewer.js.map

@@ -1 +1 @@
-{"version":3,"file":"reviewer.js","sourceRoot":"","sources":["../../../src/prompts/reviewer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reviewer.js","sourceRoot":"","sources":["../../../src/prompts/reviewer.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/claude.d.ts

@@ -1,8 +1,11 @@
 import type { Provider, InvokeOptions, ProviderResponse } from "./types.js";
 export declare class ClaudeProvider implements Provider {
     name: string;
+    private capabilityCache;
     invoke(prompt: string, options: InvokeOptions): Promise<ProviderResponse>;
     isAvailable(): Promise<boolean>;
+    checkStructuredOutputSupport(): Promise<boolean>;
+    markNonCapable(): void;
     getModels(): string[];
     getEffortLevels(): string[];
 }

package/dist/src/providers/claude.js

@@ -13,11 +13,82 @@ function cleanEnv() {
     }
     return env;
 }
+/**
+ * Parse claude's `--output-format json` envelope and extract the
+ * `structured_output` field as a JSON string ready for downstream parsing.
+ * Returns null if the envelope is malformed or the field is missing.
+ *
+ * Envelope shape (subset):
+ * {
+ *   "type": "result",
+ *   "is_error": false,
+ *   "result": "",
+ *   "structured_output": { ...model's constrained JSON... },
+ *   ...
+ * }
+ */
+function extractStructuredOutput(stdout) {
+    try {
+        const envelope = JSON.parse(stdout);
+        if (envelope &&
+            typeof envelope === "object" &&
+            "structured_output" in envelope &&
+            envelope.structured_output !== null &&
+            typeof envelope.structured_output === "object") {
+            return JSON.stringify(envelope.structured_output);
+        }
+    }
+    catch {
+        // Not JSON — may indicate a pre-envelope error or auth failure
+    }
+    return null;
+}
+/**
+ * Classify a CLI invocation failure as `capability` (downgrade-eligible) or
+ * `fatal` (terminal). Capability errors indicate the CLI doesn't support the
+ * requested structured output flag; fatal errors are everything else.
+ */
+function classifyError(stderr, exitCode) {
+    const lower = stderr.toLowerCase();
+    const capabilityIndicators = [
+        "unknown flag",
+        "unknown option",
+        "unrecognized",
+        "invalid schema",
+        "invalid json schema",
+        "json-schema",
+        "unsupported",
+    ];
+    const isCapability = capabilityIndicators.some((indicator) => lower.includes(indicator));
+    return {
+        kind: isCapability ? "capability" : "fatal",
+        message: stderr.slice(0, 500) || `claude exited with code ${exitCode}`,
+        exitCode,
+        stderr,
+    };
+}
 export class ClaudeProvider {
     name = "claude";
+    capabilityCache = null;
     async invoke(prompt, options) {
-        // claude -p reads prompt from stdin when no positional arg is given
-        const args = ["-p", "--output-format", "text"];
+        // claude -p reads prompt from stdin when no positional arg is given.
+        // --bare skips hooks/MCP/auto-memory/CLAUDE.md/plugin-sync for faster
+        // subprocess startup, but it bypasses OAuth/keychain — only safe to use
+        // when ANTHROPIC_API_KEY is set.
+        const args = ["-p"];
+        if (process.env.ANTHROPIC_API_KEY) {
+            args.push("--bare");
+        }
+        if (options.jsonSchema) {
+            // With a schema, use --output-format json so the response envelope
+            // includes a `structured_output` field containing the model's
+            // constrained JSON as a native object. --output-format text drops
+            // the structured_output field entirely.
+            args.push("--output-format", "json", "--json-schema", JSON.stringify(options.jsonSchema));
+        }
+        else {
+            args.push("--output-format", "text");
+        }
         if (options.model) {
             args.push("--model", options.model);
         }
@@ -32,22 +103,45 @@ export class ClaudeProvider {
                 extendEnv: false,
                 input: prompt,
             });
-            if (result.exitCode !== 0) {
-                process.stderr.write(`[claude-provider] exit=${result.exitCode} stderr=${result.stderr?.slice(0, 500)}\n`);
+            const duration = Date.now() - start;
+            const exitCode = result.exitCode ?? 1;
+            // claude -p can exit non-zero with valid stdout. Treat presence of
+            // stdout as success even on non-zero exit.
+            if (result.stdout && result.stdout.trim().length > 0) {
+                if (options.jsonSchema) {
+                    // Parse claude's envelope and extract structured_output.
+                    const extracted = extractStructuredOutput(result.stdout);
+                    if (extracted === null) {
+                        return {
+                            ok: false,
+                            error: {
+                                kind: "capability",
+                                message: `claude returned envelope without structured_output field: ${result.stdout.slice(0, 300)}`,
+                                exitCode,
+                                stderr: result.stderr,
+                            },
+                            duration,
+                        };
+                    }
+                    return { ok: true, output: extracted, duration };
+                }
+                return { ok: true, output: result.stdout, duration };
             }
+            // No usable output — classify the failure
+            process.stderr.write(`[claude-provider] exit=${exitCode} stderr=${result.stderr?.slice(0, 500)}\n`);
             return {
-                content: result.stdout,
-                exitCode: result.exitCode ?? 1,
-                duration: Date.now() - start,
+                ok: false,
+                error: classifyError(result.stderr ?? "", exitCode),
+                duration,
             };
         }
         catch (error) {
+            const duration = Date.now() - start;
+            const message = error instanceof Error ? error.message : "Unknown error invoking claude";
             return {
-                content: error instanceof Error
-                    ? error.message
-                    : "Unknown error invoking claude",
-                exitCode: 1,
-                duration: Date.now() - start,
+                ok: false,
+                error: { kind: "fatal", message, exitCode: 1 },
+                duration,
             };
         }
     }
@@ -66,6 +160,34 @@ export class ClaudeProvider {
             return false;
         }
     }
+    async checkStructuredOutputSupport() {
+        if (this.capabilityCache !== null) {
+            return this.capabilityCache;
+        }
+        try {
+            const result = await execa("claude", ["--help"], {
+                preferLocal: true,
+                timeout: 5_000,
+                reject: false,
+                env: cleanEnv(),
+                extendEnv: false,
+            });
+            const helpText = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+            const supported = helpText.includes("--json-schema");
+            this.capabilityCache = supported;
+            if (!supported) {
+                process.stderr.write(`[planpong] Structured output not supported by claude — using legacy parsing\n`);
+            }
+            return supported;
+        }
+        catch {
+            this.capabilityCache = false;
+            return false;
+        }
+    }
+    markNonCapable() {
+        this.capabilityCache = false;
+    }
     getModels() {
         return MODELS;
     }

package/dist/src/providers/claude.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../src/providers/claude.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAG9B,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAE3C;;;GAGG;AACH,SAAS,QAAQ;IACf,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,KAAK,YAAY,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAChD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,cAAc;IACzB,IAAI,GAAG,QAAQ,CAAC;IAEhB,KAAK,CAAC,MAAM,CACV,MAAc,EACd,OAAsB;QAEtB,oEAAoE;QACpE,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;QAE/C,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE;gBACzC,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,WAAW,EAAE,IAAI;gBACjB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,OAAO;gBACnC,MAAM,EAAE,KAAK;gBACb,GAAG,EAAE,QAAQ,EAAE;gBACf,SAAS,EAAE,KAAK;gBAChB,KAAK,EAAE,MAAM;aACd,CAAC,CAAC;YAEH,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0BAA0B,MAAM,CAAC,QAAQ,WAAW,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CACrF,CAAC;YACJ,CAAC;YAED,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,MAAM;gBACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC;gBAC9B,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC7B,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EACL,KAAK,YAAY,KAAK;oBACpB,CAAC,CAAC,KAAK,CAAC,OAAO;oBACf,CAAC,CAAC,+BAA+B;gBACrC,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC7B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE;gBAClD,WAAW,EAAE,IAAI;gBACjB,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,KAAK;gBACb,GAAG,EAAE,QAAQ,EAAE;gBACf,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;YACH,OAAO,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,SAAS;QACP,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,eAAe;QACb,oEAAoE;QACpE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../src/providers/claude.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/codex.d.ts

@@ -1,8 +1,11 @@
 import type { Provider, InvokeOptions, ProviderResponse } from "./types.js";
 export declare class CodexProvider implements Provider {
     name: string;
+    private capabilityCache;
     invoke(prompt: string, options: InvokeOptions): Promise<ProviderResponse>;
     isAvailable(): Promise<boolean>;
+    checkStructuredOutputSupport(): Promise<boolean>;
+    markNonCapable(): void;
     getModels(): string[];
     getEffortLevels(): string[];
 }

package/dist/src/providers/codex.js

@@ -1,12 +1,40 @@
 import { randomBytes } from "node:crypto";
-import { readFileSync, unlinkSync } from "node:fs";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execa } from "execa";
 const MODELS = ["gpt-5.3-codex", "o3-pro", "o3", "o4-mini"];
 const EFFORT_LEVELS = ["low", "medium", "high", "xhigh"];
+/**
+ * Classify a CLI invocation failure as `capability` (downgrade-eligible) or
+ * `fatal` (terminal). Capability errors indicate the CLI doesn't support the
+ * requested structured output flag; fatal errors are everything else.
+ *
+ * Patterns must be narrow — codex's normal session header includes flag
+ * names like "output-schema:" in its info output, so substring matches on
+ * the flag name alone produce false positives.
+ */
+function classifyError(stderr, exitCode) {
+    const lower = stderr.toLowerCase();
+    const capabilityPatterns = [
+        /\bunknown (?:flag|option|argument)\b/,
+        /\bunrecognized (?:flag|option|argument)\b/,
+        /\binvalid_json_schema\b/,
+        /\binvalid schema\b/,
+        /\bschema is not supported\b/,
+        /\bstructured output (?:not|isn't) supported\b/,
+    ];
+    const isCapability = capabilityPatterns.some((pattern) => pattern.test(lower));
+    return {
+        kind: isCapability ? "capability" : "fatal",
+        message: stderr.slice(0, 500) || `codex exited with code ${exitCode}`,
+        exitCode,
+        stderr,
+    };
+}
 export class CodexProvider {
     name = "codex";
+    capabilityCache = null;
     async invoke(prompt, options) {
         const args = ["exec"];
         if (options.model) {
@@ -18,6 +46,19 @@ export class CodexProvider {
         // Write clean output to a temp file to avoid parsing header/footer
         const outFile = join(tmpdir(), `planpong-codex-${randomBytes(6).toString("hex")}.txt`);
         args.push("-o", outFile);
+        // Optional structured output schema
+        let schemaFile = null;
+        if (options.jsonSchema) {
+            schemaFile = join(tmpdir(), `planpong-codex-schema-${randomBytes(6).toString("hex")}.json`);
+            try {
+                writeFileSync(schemaFile, JSON.stringify(options.jsonSchema));
+                args.push("--output-schema", schemaFile);
+            }
+            catch (error) {
+                // If we can't write the schema file, fall through without structured output
+                schemaFile = null;
+            }
+        }
         // Use stdin for prompt (CLI arg has length limits)
         args.push("-");
         const start = Date.now();
@@ -29,34 +70,56 @@ export class CodexProvider {
                 reject: false,
                 input: prompt,
             });
-            let content;
+            const duration = Date.now() - start;
+            const exitCode = result.exitCode ?? 1;
+            let content = "";
             try {
                 content = readFileSync(outFile, "utf-8");
             }
             catch {
                 // Fall back to stdout if output file wasn't created
-                content = result.stdout;
+                content = result.stdout ?? "";
             }
-            // Clean up temp file
+            // Clean up temp files
             try {
                 unlinkSync(outFile);
             }
             catch {
                 // ignore
             }
+            if (schemaFile) {
+                try {
+                    unlinkSync(schemaFile);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (content && content.trim().length > 0) {
+                return { ok: true, output: content, duration };
+            }
             return {
-                content,
-                exitCode: result.exitCode ?? 1,
-                duration: Date.now() - start,
+                ok: false,
+                error: classifyError(result.stderr ?? "", exitCode),
+                duration,
             };
         }
         catch (error) {
+            const duration = Date.now() - start;
+            // Cleanup on error path
+            if (schemaFile) {
+                try {
+                    unlinkSync(schemaFile);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            const message = error instanceof Error ? error.message : "Unknown error invoking codex";
             return {
-                content: error instanceof Error
-                    ? error.message
-                    : "Unknown error invoking codex",
-                exitCode: 1,
-                duration: Date.now() - start,
+                ok: false,
+                error: { kind: "fatal", message, exitCode: 1 },
+                duration,
             };
         }
     }
@@ -73,6 +136,32 @@ export class CodexProvider {
             return false;
         }
     }
+    async checkStructuredOutputSupport() {
+        if (this.capabilityCache !== null) {
+            return this.capabilityCache;
+        }
+        try {
+            const result = await execa("codex", ["exec", "--help"], {
+                preferLocal: true,
+                timeout: 5_000,
+                reject: false,
+            });
+            const helpText = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+            const supported = helpText.includes("--output-schema");
+            this.capabilityCache = supported;
+            if (!supported) {
+                process.stderr.write(`[planpong] Structured output not supported by codex — using legacy parsing\n`);
+            }
+            return supported;
+        }
+        catch {
+            this.capabilityCache = false;
+            return false;
+        }
+    }
+    markNonCapable() {
+        this.capabilityCache = false;
+    }
     getModels() {
         return MODELS;
     }

package/dist/src/providers/codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../../src/providers/codex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../../src/providers/codex.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/types.d.ts

@@ -3,16 +3,62 @@ export interface InvokeOptions {
     model?: string;
     effort?: string;
     timeout?: number;
+    /**
+     * JSON Schema to constrain model output. When set, providers pass this to
+     * their respective structured-output flags (`--json-schema` for claude,
+     * `--output-schema` for codex).
+     */
+    jsonSchema?: Record<string, unknown>;
 }
-export interface ProviderResponse {
-    content: string;
+/**
+ * Provider invocation error categories. Used by the operations-layer state
+ * machine to decide whether to downgrade or fail terminally.
+ *
+ * - `capability`: schema rejected, flag unrecognized at runtime, structured
+ *   output format error. Indicates the CLI doesn't support the requested
+ *   structured output mode. Downgrade-eligible.
+ * - `fatal`: auth failure, timeout, network/transport error, non-zero exit
+ *   with no output. Unrelated to structured output capability. Terminal.
+ */
+export type ProviderErrorKind = "capability" | "fatal";
+export interface ProviderError {
+    kind: ProviderErrorKind;
+    message: string;
     exitCode: number;
-    duration: number;
+    stderr?: string;
 }
+/**
+ * Discriminated result of a single provider invocation. Providers are
+ * single-shot — they perform one invocation and return either the output
+ * or a typed error. They do NOT retry or downgrade internally; that is
+ * the operations-layer state machine's job.
+ */
+export type ProviderResponse = {
+    ok: true;
+    output: string;
+    duration: number;
+} | {
+    ok: false;
+    error: ProviderError;
+    duration: number;
+};
 export interface Provider {
     name: string;
     invoke(prompt: string, options: InvokeOptions): Promise<ProviderResponse>;
     isAvailable(): Promise<boolean>;
     getModels(): string[];
     getEffortLevels(): string[];
+    /**
+     * Probe the underlying CLI to determine whether structured output is
+     * supported. Result is cached for the session lifetime. If the probe
+     * fails or times out, returns false (use legacy path).
+     */
+    checkStructuredOutputSupport(): Promise<boolean>;
+    /**
+     * Mark this provider as non-capable for the remainder of the session.
+     * Called by the state machine after a runtime structured-output failure
+     * (capability error or JSON.parse failure) to prevent re-attempting
+     * structured output on subsequent rounds.
+     */
+    markNonCapable(): void;
 }

package/dist/src/schemas/json-schema.d.ts

@@ -0,0 +1,9 @@
+import type { ReviewPhase } from "../prompts/reviewer.js";
+export declare const DirectionFeedbackJsonSchema: Record<string, unknown>;
+export declare const RiskFeedbackJsonSchema: Record<string, unknown>;
+export declare const ReviewFeedbackJsonSchema: Record<string, unknown>;
+export declare const PlannerRevisionJsonSchema: Record<string, unknown>;
+/**
+ * Get the JSON Schema appropriate for a given review phase.
+ */
+export declare function getFeedbackJsonSchemaForPhase(phase: ReviewPhase): Record<string, unknown>;