planpong 0.2.1 → 0.4.2

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/feedback.d.ts

@@ -22,7 +22,7 @@ export declare const FeedbackIssueSchema: z.ZodObject<{
     suggestion: string;
 }>;
 export declare const ReviewFeedbackSchema: z.ZodEffects<z.ZodObject<{
-    verdict: z.ZodEnum<["needs_revision", "approved", "approved_with_notes"]>;
+    verdict: z.ZodEnum<["needs_revision", "approved", "approved_with_notes", "blocked"]>;
     summary: z.ZodString;
     issues: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -46,6 +46,8 @@ export declare const ReviewFeedbackSchema: z.ZodEffects<z.ZodObject<{
         description: string;
         suggestion: string;
     }>, "many">;
+    fallback_used: z.ZodOptional<z.ZodBoolean>;
+    missing_phase_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     issues: {
         id: string;
@@ -55,8 +57,10 @@ export declare const ReviewFeedbackSchema: z.ZodEffects<z.ZodObject<{
         description: string;
         suggestion: string;
     }[];
-    verdict: "needs_revision" | "approved" | "approved_with_notes";
+    verdict: "needs_revision" | "approved" | "approved_with_notes" | "blocked";
     summary: string;
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
 }, {
     issues: {
         id: string;
@@ -66,8 +70,10 @@ export declare const ReviewFeedbackSchema: z.ZodEffects<z.ZodObject<{
         description: string;
         suggestion: string;
     }[];
-    verdict: "needs_revision" | "approved" | "approved_with_notes";
+    verdict: "needs_revision" | "approved" | "approved_with_notes" | "blocked";
     summary: string;
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
 }>, {
     issues: {
         id: string;
@@ -77,8 +83,10 @@ export declare const ReviewFeedbackSchema: z.ZodEffects<z.ZodObject<{
         description: string;
         suggestion: string;
     }[];
-    verdict: "needs_revision" | "approved" | "approved_with_notes";
+    verdict: "needs_revision" | "approved" | "approved_with_notes" | "blocked";
     summary: string;
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
 }, {
     issues: {
         id: string;
@@ -88,8 +96,231 @@ export declare const ReviewFeedbackSchema: z.ZodEffects<z.ZodObject<{
         description: string;
         suggestion: string;
     }[];
-    verdict: "needs_revision" | "approved" | "approved_with_notes";
+    verdict: "needs_revision" | "approved" | "approved_with_notes" | "blocked";
     summary: string;
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
+}>;
+export declare const AlternativeSchema: z.ZodObject<{
+    approach: z.ZodString;
+    tradeoff: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    approach: string;
+    tradeoff: string;
+}, {
+    approach: string;
+    tradeoff: string;
+}>;
+export declare const DirectionFeedbackSchema: z.ZodObject<{
+    verdict: z.ZodEnum<["needs_revision", "blocked"]>;
+    summary: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<["P1", "P2", "P3"]>;
+        section: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        suggestion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }, {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }>, "many">;
+    confidence: z.ZodEnum<["high", "medium", "low"]>;
+    approach_assessment: z.ZodString;
+    alternatives: z.ZodArray<z.ZodObject<{
+        approach: z.ZodString;
+        tradeoff: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        approach: string;
+        tradeoff: string;
+    }, {
+        approach: string;
+        tradeoff: string;
+    }>, "many">;
+    assumptions: z.ZodArray<z.ZodString, "many">;
+    fallback_used: z.ZodOptional<z.ZodBoolean>;
+    missing_phase_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    issues: {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }[];
+    verdict: "needs_revision" | "blocked";
+    summary: string;
+    confidence: "high" | "medium" | "low";
+    approach_assessment: string;
+    alternatives: {
+        approach: string;
+        tradeoff: string;
+    }[];
+    assumptions: string[];
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
+}, {
+    issues: {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }[];
+    verdict: "needs_revision" | "blocked";
+    summary: string;
+    confidence: "high" | "medium" | "low";
+    approach_assessment: string;
+    alternatives: {
+        approach: string;
+        tradeoff: string;
+    }[];
+    assumptions: string[];
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
+}>;
+export declare const RiskEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodEnum<["dependency", "integration", "operational", "assumption", "external"]>;
+    likelihood: z.ZodEnum<["high", "medium", "low"]>;
+    impact: z.ZodEnum<["high", "medium", "low"]>;
+    title: z.ZodString;
+    description: z.ZodString;
+    mitigation: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    description: string;
+    category: "dependency" | "integration" | "operational" | "assumption" | "external";
+    likelihood: "high" | "medium" | "low";
+    impact: "high" | "medium" | "low";
+    mitigation: string;
+}, {
+    id: string;
+    title: string;
+    description: string;
+    category: "dependency" | "integration" | "operational" | "assumption" | "external";
+    likelihood: "high" | "medium" | "low";
+    impact: "high" | "medium" | "low";
+    mitigation: string;
+}>;
+export declare const RiskFeedbackSchema: z.ZodObject<{
+    verdict: z.ZodEnum<["needs_revision", "blocked"]>;
+    summary: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<["P1", "P2", "P3"]>;
+        section: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        suggestion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }, {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }>, "many">;
+    risk_level: z.ZodEnum<["high", "medium", "low"]>;
+    risks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        category: z.ZodEnum<["dependency", "integration", "operational", "assumption", "external"]>;
+        likelihood: z.ZodEnum<["high", "medium", "low"]>;
+        impact: z.ZodEnum<["high", "medium", "low"]>;
+        title: z.ZodString;
+        description: z.ZodString;
+        mitigation: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        description: string;
+        category: "dependency" | "integration" | "operational" | "assumption" | "external";
+        likelihood: "high" | "medium" | "low";
+        impact: "high" | "medium" | "low";
+        mitigation: string;
+    }, {
+        id: string;
+        title: string;
+        description: string;
+        category: "dependency" | "integration" | "operational" | "assumption" | "external";
+        likelihood: "high" | "medium" | "low";
+        impact: "high" | "medium" | "low";
+        mitigation: string;
+    }>, "many">;
+    fallback_used: z.ZodOptional<z.ZodBoolean>;
+    missing_phase_fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    issues: {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }[];
+    verdict: "needs_revision" | "blocked";
+    summary: string;
+    risk_level: "high" | "medium" | "low";
+    risks: {
+        id: string;
+        title: string;
+        description: string;
+        category: "dependency" | "integration" | "operational" | "assumption" | "external";
+        likelihood: "high" | "medium" | "low";
+        impact: "high" | "medium" | "low";
+        mitigation: string;
+    }[];
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
+}, {
+    issues: {
+        id: string;
+        severity: "P1" | "P2" | "P3";
+        section: string;
+        title: string;
+        description: string;
+        suggestion: string;
+    }[];
+    verdict: "needs_revision" | "blocked";
+    summary: string;
+    risk_level: "high" | "medium" | "low";
+    risks: {
+        id: string;
+        title: string;
+        description: string;
+        category: "dependency" | "integration" | "operational" | "assumption" | "external";
+        likelihood: "high" | "medium" | "low";
+        impact: "high" | "medium" | "low";
+        mitigation: string;
+    }[];
+    fallback_used?: boolean | undefined;
+    missing_phase_fields?: string[] | undefined;
 }>;
 export type FeedbackIssue = z.infer<typeof FeedbackIssueSchema>;
 export type ReviewFeedback = z.infer<typeof ReviewFeedbackSchema>;
+export type DirectionFeedback = z.infer<typeof DirectionFeedbackSchema>;
+export type RiskFeedback = z.infer<typeof RiskFeedbackSchema>;
+export type RiskEntry = z.infer<typeof RiskEntrySchema>;
+export type Alternative = z.infer<typeof AlternativeSchema>;
+export type PhaseFeedback = DirectionFeedback | RiskFeedback | ReviewFeedback;

package/dist/src/schemas/feedback.js

@@ -7,11 +7,21 @@ export const FeedbackIssueSchema = z.object({
     description: z.string(),
     suggestion: z.string(),
 });
+// Base verdict enum includes `blocked` so fallback parsing can accept it
+// from direction/risk phases when phase-specific parsing fails.
 export const ReviewFeedbackSchema = z
     .object({
-    verdict: z.enum(["needs_revision", "approved", "approved_with_notes"]),
+    verdict: z.enum([
+        "needs_revision",
+        "approved",
+        "approved_with_notes",
+        "blocked",
+    ]),
     summary: z.string(),
     issues: z.array(FeedbackIssueSchema),
+    // Fallback observability — set by parseFeedbackForPhase when fallback is used
+    fallback_used: z.boolean().optional(),
+    missing_phase_fields: z.array(z.string()).optional(),
 })
     .refine((data) => {
     if (data.verdict === "approved_with_notes") {
@@ -21,4 +31,45 @@ export const ReviewFeedbackSchema = z
 }, {
     message: "approved_with_notes is only valid when all issues are P3. Either downgrade issues to P3 or change verdict to needs_revision.",
 });
+// --- Direction phase schema ---
+export const AlternativeSchema = z.object({
+    approach: z.string(),
+    tradeoff: z.string(),
+});
+export const DirectionFeedbackSchema = z.object({
+    verdict: z.enum(["needs_revision", "blocked"]),
+    summary: z.string(),
+    issues: z.array(FeedbackIssueSchema),
+    confidence: z.enum(["high", "medium", "low"]),
+    approach_assessment: z.string(),
+    alternatives: z.array(AlternativeSchema),
+    assumptions: z.array(z.string()),
+    fallback_used: z.boolean().optional(),
+    missing_phase_fields: z.array(z.string()).optional(),
+});
+// --- Risk phase schema ---
+export const RiskEntrySchema = z.object({
+    id: z.string(),
+    category: z.enum([
+        "dependency",
+        "integration",
+        "operational",
+        "assumption",
+        "external",
+    ]),
+    likelihood: z.enum(["high", "medium", "low"]),
+    impact: z.enum(["high", "medium", "low"]),
+    title: z.string(),
+    description: z.string(),
+    mitigation: z.string(),
+});
+export const RiskFeedbackSchema = z.object({
+    verdict: z.enum(["needs_revision", "blocked"]),
+    summary: z.string(),
+    issues: z.array(FeedbackIssueSchema),
+    risk_level: z.enum(["high", "medium", "low"]),
+    risks: z.array(RiskEntrySchema),
+    fallback_used: z.boolean().optional(),
+    missing_phase_fields: z.array(z.string()).optional(),
+});
 //# sourceMappingURL=feedback.js.map

package/dist/src/schemas/feedback.js.map

@@ -1 +1 @@
-{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../../src/schemas/feedback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,UAAU,EAAE,qBAAqB,CAAC,CAAC;IACtE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CACrC,CAAC;KACD,MAAM,CACL,CAAC,IAAI,EAAE,EAAE;IACP,IAAI,IAAI,CAAC,OAAO,KAAK,qBAAqB,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,EACD;IACE,OAAO,EACL,8HAA8H;CACjI,CACF,CAAC"}
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../../src/schemas/feedback.ts"],"names":[],"mappings":"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"}

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>;