@claudexor/orchestrator 3.0.4 → 3.1.0

package/dist/attemptFinalize.d.ts

@@ -0,0 +1,162 @@
+/**
+ * D-16 unified attempt finalizer.
+ *
+ * ONE owner for the "did this attempt deliver, and in what work_state?" decision
+ * — replacing the three divergent deliverable predicates (candidate diff||answer;
+ * planner no-error⇒delivered; read-only nonempty-report). It folds the raw
+ * intent-specific deliverable evidence with the model-authored WorkReport, the
+ * typed context signals, the harness error state, and the gates into:
+ *   - a final `deliverablePresent`,
+ *   - a `work_state` axis (orthogonal to lifecycle, INV-116),
+ *   - a typed reason,
+ *   - and the class of outcome (clean / veto / contract-failure / interrupted).
+ *
+ * The module is PURE (no I/O, no clock). The envelope compile/unwrap helpers
+ * live here too so the spec-build decision and the finalizer read one contract.
+ */
+import { WorkReport, type HarnessCapabilities, type RunReason, type WorkReportSource, type WorkState } from "@claudexor/schema";
+/**
+ * How the WorkReport rides the wire for an active envelope (D-16c):
+ * - `constrained_json`: the whole final answer IS the `{work_report, output}`
+ *   JSON (codex `--output-schema`; claude `--json-schema` WITH a caller schema).
+ * - `side_tool`: a `{work_report}`-only schema arms claude's StructuredOutput
+ *   TOOL; the markdown final message stays the deliverable and the report rides
+ *   the tool payload (surfaced on the final message's `work_report_side_tool`).
+ * - `instructed_fence`: no native constraint — the model is INSTRUCTED to end
+ *   its answer with a fenced `{work_report, output}` JSON block, validated off
+ *   the last fenced JSON (cursor).
+ */
+export type WorkReportChannel = "constrained_json" | "side_tool" | "instructed_fence";
+/** The per-attempt envelope decision made at spec build and consumed by the
+ * unwrap. `active` means the orchestrator actually armed a WorkReport transport
+ * for this route, so a missing/malformed report is a typed contract failure. */
+export interface WorkReportEnvelopeMode {
+    active: boolean;
+    source: WorkReportSource;
+    hasCallerSchema: boolean;
+    channel: WorkReportChannel;
+    /** Instruction to APPEND to the spec (instructed_fence only); null otherwise. */
+    instruction: string | null;
+}
+/**
+ * The instruction appended to an `instructed_fence` (cursor) route so the model
+ * emits the WorkReport envelope the finalizer validates. No native schema
+ * constrains cursor, so the contract is instructed and validated off the last
+ * fenced JSON block (D-16c). The `output` string carries the deliverable prose.
+ */
+export declare const WORK_REPORT_FENCE_INSTRUCTION: string;
+/** Result of the spec-build envelope decision. */
+export interface ResolvedWorkReportEnvelope {
+    /** What rides HarnessRunSpec.output_schema (undefined = leave unset). */
+    outputSchema: Record<string, unknown> | undefined;
+    mode: WorkReportEnvelopeMode;
+}
+/**
+ * Decide the transport envelope for one route at spec build (D-16 §2). The
+ * caller's ORIGINAL schema stays the conformance authority for `output` (it is
+ * NOT passed here strictified for validation — only the transport copy is).
+ *
+ * Activated HERE directly for `constrained` routes that natively constrain
+ * output and are not interactive-gated (the WorkReport rides the
+ * `{work_report, output}` envelope; claude's no-caller `side_tool` case instead
+ * arms a `{work_report}`-only schema on the StructuredOutput tool so the markdown
+ * final stays the deliverable — the D-16c seam), and for `validated` routes
+ * (cursor), where the report rides an INSTRUCTED fenced envelope. Only
+ * interactive-gated and schema-incapable routes stay inactive here (disclosed
+ * `absent` work_state).
+ */
+export declare function resolveWorkReportEnvelope(opts: {
+    transport: HarnessCapabilities["work_report_transport"];
+    channel: HarnessCapabilities["structured_output_channel"];
+    supportsJsonSchemaOutput: boolean;
+    interactive: boolean;
+    callerSchema: Record<string, unknown> | null;
+}): ResolvedWorkReportEnvelope;
+/** The unwrapped attempt answer plus the extracted WorkReport (or a typed
+ * contract violation). `deliverable` is what answer.md / the caller-schema
+ * validator must see — never the envelope. */
+export interface UnwrappedAnswer {
+    deliverable: string;
+    workReport: WorkReport | null;
+    source: WorkReportSource;
+    /** Non-null when an active route failed to carry a valid WorkReport. */
+    contractViolation: string | null;
+}
+/**
+ * Un-nest the WorkReport envelope from an active route's answer (D-16 §2). The
+ * behavior forks on `mode.channel`:
+ * - `constrained_json`: the whole answer IS `{work_report, output}` JSON.
+ * - `instructed_fence`: the envelope is the LAST fenced JSON block; prose
+ *   before it is discarded (the `output` string is the deliverable).
+ * - `side_tool`: the answer text IS the markdown deliverable; the report rides
+ *   `opts.sideToolReport` (the tool payload the adapter surfaced).
+ * A non-active mode passes the answer through untouched. The WorkReport
+ * cross-field rules (completed ⇒ no required_inputs; needs_input ⇒ ≥1) are
+ * enforced HERE so a broken report is a typed contract violation.
+ *
+ * For a `constrained_json` route `answerText` is the raw `{work_report, output}`
+ * envelope (codex #19816 / QA-009: the orchestrator passes `answer.machineText()`,
+ * which yields the raw envelope even when the codex adapter pre-unwrapped the
+ * DISPLAY copy of the final message — the visible stream sees the output, the
+ * un-nest here still sees the envelope).
+ */
+export declare function unwrapWorkReportEnvelope(answerText: string, mode: WorkReportEnvelopeMode, opts?: {
+    sideToolReport?: unknown;
+}): UnwrappedAnswer;
+/**
+ * QA-036: the terminal outcome facts for a read-only (ask) run that produced NO
+ * successful attempt. The D8 legacy mapping treated ANY web-blocked run as a
+ * succeeded/review_blocked terminal (exit 0, "Needs review"); a blocked Ask that
+ * delivered nothing then read as done. This re-checks the DELIVERABLE: only a
+ * blocked attempt that actually produced a partial answer is a review-blocked
+ * SUCCESS; an empty blocked (or plain failed) run is a failure (exit 1).
+ */
+export declare function readOnlyNoSuccessTerminal(opts: {
+    webBlocked: boolean;
+    hasDeliverable: boolean;
+    budgetStopped: boolean;
+    attemptsCount: number;
+}): {
+    lifecycle: "succeeded" | "failed";
+    review?: "blocked";
+    reason: RunReason;
+};
+/** Everything the finalizer folds for one attempt. The gate/web/belt axes are
+ * NOT folded here — the finalizer decides deliverable+work_state, and
+ * `setAttemptOutcome` runs the status math over gates/web/belt on top (so a
+ * `completed` claim with a failed gate still yields a failed status there). */
+export interface FinalizeAttemptInput {
+    /** Raw intent-specific deliverable evidence (diff/answer/report present). */
+    deliverableEvidence: boolean;
+    harnessErrored: boolean;
+    workReport: WorkReport | null;
+    workReportSource: WorkReportSource;
+    /** Non-null when an active route failed its WorkReport contract. */
+    workReportViolation: string | null;
+    /** A terminal capacity_exhausted context signal was observed this attempt. */
+    contextTerminalExhausted: boolean;
+}
+/** Outcome class the run-level terminal maps onto lifecycle/facts. */
+export type AttemptOutcomeClass = "clean" | "veto" | "contract_failure" | "interrupted";
+export interface FinalizeAttemptResult {
+    /** Final deliverable presence (a completed claim never invents evidence). */
+    deliverablePresent: boolean;
+    /** Final harness-error state (a contract failure elevates it). */
+    harnessErrored: boolean;
+    workState: WorkState;
+    /** Typed reason for the veto/failure; null on a clean outcome. */
+    reason: RunReason | null;
+    outcomeClass: AttemptOutcomeClass;
+}
+/**
+ * The unified finalizer. Precedence (hardest signal wins):
+ *   1. terminal context exhaustion with no completed report ⇒ interrupted;
+ *   2. a broken WorkReport contract on a constrained route ⇒ hard failure
+ *      (never prose-success);
+ *   3. a valid needs_input/incomplete report ⇒ veto (lifecycle stays, run is
+ *      non-applyable, exit non-zero) — a `completed` claim NEVER overrides a
+ *      harness error / failed gate / missing evidence;
+ *   4. otherwise the disclosed work_state (completed or unverified).
+ */
+export declare function finalizeAttempt(input: FinalizeAttemptInput): FinalizeAttemptResult;
+//# sourceMappingURL=attemptFinalize.d.ts.map

package/dist/attemptFinalize.d.ts.map

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

package/dist/attemptFinalize.js

@@ -0,0 +1,368 @@
+/**
+ * D-16 unified attempt finalizer.
+ *
+ * ONE owner for the "did this attempt deliver, and in what work_state?" decision
+ * — replacing the three divergent deliverable predicates (candidate diff||answer;
+ * planner no-error⇒delivered; read-only nonempty-report). It folds the raw
+ * intent-specific deliverable evidence with the model-authored WorkReport, the
+ * typed context signals, the harness error state, and the gates into:
+ *   - a final `deliverablePresent`,
+ *   - a `work_state` axis (orthogonal to lifecycle, INV-116),
+ *   - a typed reason,
+ *   - and the class of outcome (clean / veto / contract-failure / interrupted).
+ *
+ * The module is PURE (no I/O, no clock). The envelope compile/unwrap helpers
+ * live here too so the spec-build decision and the finalizer read one contract.
+ */
+import { buildWorkReportEnvelope, strictifyOutputSchema, WorkReport, } from "@claudexor/schema";
+import { redactSecrets } from "@claudexor/util";
+/**
+ * The instruction appended to an `instructed_fence` (cursor) route so the model
+ * emits the WorkReport envelope the finalizer validates. No native schema
+ * constrains cursor, so the contract is instructed and validated off the last
+ * fenced JSON block (D-16c). The `output` string carries the deliverable prose.
+ */
+export const WORK_REPORT_FENCE_INSTRUCTION = [
+    "When you have finished, end your reply with a single fenced ```json code block",
+    "containing exactly this object and nothing after it:",
+    '{"work_report": {"state": "completed" | "needs_input" | "incomplete",',
+    '"required_inputs": [{"kind": "file"|"context"|"credential"|"permission"|"decision"|"external_dependency",',
+    '"locator": string|null, "description": string}]}, "output": "<your final answer as a string>"}.',
+    'Use state "completed" only when the task is fully done with an empty required_inputs list;',
+    'use "needs_input" (with at least one required_inputs entry) when you are blocked on a missing input;',
+    'use "incomplete" when partial work remains. This block is mandatory.',
+].join(" ");
+/**
+ * Decide the transport envelope for one route at spec build (D-16 §2). The
+ * caller's ORIGINAL schema stays the conformance authority for `output` (it is
+ * NOT passed here strictified for validation — only the transport copy is).
+ *
+ * Activated HERE directly for `constrained` routes that natively constrain
+ * output and are not interactive-gated (the WorkReport rides the
+ * `{work_report, output}` envelope; claude's no-caller `side_tool` case instead
+ * arms a `{work_report}`-only schema on the StructuredOutput tool so the markdown
+ * final stays the deliverable — the D-16c seam), and for `validated` routes
+ * (cursor), where the report rides an INSTRUCTED fenced envelope. Only
+ * interactive-gated and schema-incapable routes stay inactive here (disclosed
+ * `absent` work_state).
+ */
+export function resolveWorkReportEnvelope(opts) {
+    const hasCallerSchema = opts.callerSchema !== null;
+    const callerStrict = hasCallerSchema
+        ? strictifyOutputSchema(opts.callerSchema)
+        : null;
+    // claude's `--json-schema` × interactive stream-json is an unverified combo:
+    // disclose the WorkReport transport as unsupported for that lane (§1).
+    const interactiveGated = opts.channel === "side_tool" && opts.interactive;
+    // `validated` transport (cursor): no native schema constrains the output —
+    // the WorkReport rides an INSTRUCTED fenced envelope validated off the last
+    // fenced JSON (D-16c). Caller schemas on such routes were already refused by
+    // the mandatory-schema gate upstream, so this is the WorkReport-only case.
+    if (opts.transport === "validated" && !interactiveGated) {
+        return {
+            outputSchema: callerStrict ?? undefined,
+            mode: {
+                active: true,
+                source: "validated",
+                hasCallerSchema,
+                channel: "instructed_fence",
+                instruction: WORK_REPORT_FENCE_INSTRUCTION,
+            },
+        };
+    }
+    const active = opts.transport === "constrained" && opts.supportsJsonSchemaOutput && !interactiveGated;
+    if (active) {
+        // claude side_tool WITHOUT a caller schema (D-16c): arm a {work_report}-only
+        // schema on the StructuredOutput tool; the markdown final message stays the
+        // deliverable and the report rides the tool payload. Every other constrained
+        // case carries the output INSIDE the `{work_report, output}` envelope
+        // (caller schema → the strict S; no-caller final_message → output:string).
+        if (opts.channel === "side_tool" && !hasCallerSchema) {
+            return {
+                outputSchema: buildWorkReportEnvelope(null),
+                mode: {
+                    active: true,
+                    source: "constrained",
+                    hasCallerSchema,
+                    channel: "side_tool",
+                    instruction: null,
+                },
+            };
+        }
+        const output = hasCallerSchema
+            ? callerStrict
+            : "string";
+        return {
+            outputSchema: buildWorkReportEnvelope(output),
+            mode: {
+                active: true,
+                source: "constrained",
+                hasCallerSchema,
+                channel: "constrained_json",
+                instruction: null,
+            },
+        };
+    }
+    return {
+        // Legacy path preserved: a caller schema still rides (strictified) on a
+        // non-activated route (the mandatory-schema gate already refused
+        // schema-incapable routes upstream).
+        outputSchema: callerStrict ?? undefined,
+        mode: {
+            active: false,
+            source: "absent",
+            hasCallerSchema,
+            channel: "constrained_json",
+            instruction: null,
+        },
+    };
+}
+function extractOutput(obj, mode) {
+    const output = obj["output"];
+    if (mode.hasCallerSchema) {
+        // Re-serialize the S-conformant object so finalizeStructuredOutput can
+        // JSON.parse + validate it against the caller schema (the caller schema is
+        // the conformance authority for `output`, so any shape rides through here).
+        return { deliverable: output === undefined ? "" : JSON.stringify(output) };
+    }
+    // No caller schema: `output` MUST be a string deliverable. A non-string
+    // (object/array/null/number/bool) or missing `output` is a BROKEN envelope —
+    // coercing it (String({...}) => "[object Object]") would let a bogus payload
+    // like {"work_report":{"state":"completed"},"output":{}} finalize CLEAN
+    // instead of failing the WorkReport contract. Fail it here (D-16 §2).
+    if (typeof output !== "string") {
+        return { violation: "work_report envelope output must be a string" };
+    }
+    return { deliverable: output };
+}
+/** Extract the LAST fenced ```…``` block's body (its optional language tag
+ * stripped), or null when the text has no closed fence. No-regex, mechanical
+ * transport parsing (INV-049 governs the typed WorkReport, not this seam). */
+function lastFencedBlock(text) {
+    const FENCE = "```";
+    const end = text.lastIndexOf(FENCE);
+    if (end <= 0)
+        return null;
+    const start = text.lastIndexOf(FENCE, end - 1);
+    if (start < 0)
+        return null;
+    let inner = text.slice(start + FENCE.length, end);
+    const nl = inner.indexOf("\n");
+    if (nl >= 0) {
+        const firstLine = inner.slice(0, nl).trim();
+        // A bare language tag (letters/digits/±_-, no whitespace) on the opening
+        // line is dropped; a first line that is already JSON content is kept.
+        const isLangTag = firstLine.length > 0 &&
+            firstLine.length <= 20 &&
+            ![...firstLine].some((ch) => ch === " " || ch === "{" || ch === "[" || ch === '"');
+        if (firstLine === "" || isLangTag)
+            inner = inner.slice(nl + 1);
+    }
+    return inner.trim();
+}
+/**
+ * Un-nest the WorkReport envelope from an active route's answer (D-16 §2). The
+ * behavior forks on `mode.channel`:
+ * - `constrained_json`: the whole answer IS `{work_report, output}` JSON.
+ * - `instructed_fence`: the envelope is the LAST fenced JSON block; prose
+ *   before it is discarded (the `output` string is the deliverable).
+ * - `side_tool`: the answer text IS the markdown deliverable; the report rides
+ *   `opts.sideToolReport` (the tool payload the adapter surfaced).
+ * A non-active mode passes the answer through untouched. The WorkReport
+ * cross-field rules (completed ⇒ no required_inputs; needs_input ⇒ ≥1) are
+ * enforced HERE so a broken report is a typed contract violation.
+ *
+ * For a `constrained_json` route `answerText` is the raw `{work_report, output}`
+ * envelope (codex #19816 / QA-009: the orchestrator passes `answer.machineText()`,
+ * which yields the raw envelope even when the codex adapter pre-unwrapped the
+ * DISPLAY copy of the final message — the visible stream sees the output, the
+ * un-nest here still sees the envelope).
+ */
+export function unwrapWorkReportEnvelope(answerText, mode, opts = {}) {
+    if (!mode.active) {
+        return {
+            deliverable: answerText,
+            workReport: null,
+            source: mode.source,
+            contractViolation: null,
+        };
+    }
+    // side_tool: the markdown answer stays the deliverable; the report is the tool
+    // payload. A missing/malformed tool report is a typed contract failure.
+    if (mode.channel === "side_tool") {
+        if (opts.sideToolReport === undefined) {
+            return {
+                deliverable: answerText,
+                workReport: null,
+                source: mode.source,
+                contractViolation: "the StructuredOutput tool did not carry a work_report",
+            };
+        }
+        return validateWorkReport(answerText, opts.sideToolReport, mode.source);
+    }
+    let text = answerText.trim();
+    if (mode.channel === "instructed_fence") {
+        const fenced = lastFencedBlock(answerText);
+        if (fenced === null) {
+            return {
+                deliverable: answerText,
+                workReport: null,
+                source: mode.source,
+                contractViolation: "final answer has no fenced work_report envelope",
+            };
+        }
+        text = fenced;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return {
+            deliverable: answerText,
+            workReport: null,
+            source: mode.source,
+            contractViolation: "final answer is not the JSON work_report envelope",
+        };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            deliverable: answerText,
+            workReport: null,
+            source: mode.source,
+            contractViolation: "work_report envelope is not a JSON object",
+        };
+    }
+    const obj = parsed;
+    const extracted = extractOutput(obj, mode);
+    if ("violation" in extracted) {
+        return {
+            deliverable: answerText,
+            workReport: null,
+            source: mode.source,
+            contractViolation: extracted.violation,
+        };
+    }
+    return validateWorkReport(extracted.deliverable, obj["work_report"], mode.source);
+}
+/** Parse + cross-field-validate a raw work_report value against a resolved
+ * deliverable. The cross-field rules (completed ⇒ no required_inputs;
+ * needs_input ⇒ ≥1) live HERE, not on the permissive Zod wire type. */
+function validateWorkReport(deliverable, rawReport, source) {
+    const wr = WorkReport.safeParse(rawReport);
+    if (!wr.success) {
+        return {
+            deliverable,
+            workReport: null,
+            source,
+            contractViolation: `work_report missing or malformed: ${wr.error.issues[0]?.message ?? "invalid"}`,
+        };
+    }
+    // ONE redaction owner for every WorkReport transport: the model-authored
+    // locator/description strings flow VERBATIM into telemetry yaml, decision
+    // facts, and the CLI needsInputLabel — the last reads the local artifact and
+    // bypasses serve-time redaction — so a token pasted into a required_input
+    // would otherwise persist unredacted at rest. Redact here, before the report
+    // is handed to any of them. (The cross-field checks below read only state and
+    // list length, so redaction order does not affect them.)
+    const report = {
+        ...wr.data,
+        required_inputs: wr.data.required_inputs.map((ri) => ({
+            ...ri,
+            locator: ri.locator === null ? null : redactSecrets(ri.locator),
+            description: redactSecrets(ri.description),
+        })),
+    };
+    if (report.state === "completed" && report.required_inputs.length > 0) {
+        return {
+            deliverable,
+            workReport: null,
+            source,
+            contractViolation: "a completed work_report must not list required_inputs",
+        };
+    }
+    if (report.state === "needs_input" && report.required_inputs.length === 0) {
+        return {
+            deliverable,
+            workReport: null,
+            source,
+            contractViolation: "a needs_input work_report must list at least one required_input",
+        };
+    }
+    return { deliverable, workReport: report, source, contractViolation: null };
+}
+/**
+ * QA-036: the terminal outcome facts for a read-only (ask) run that produced NO
+ * successful attempt. The D8 legacy mapping treated ANY web-blocked run as a
+ * succeeded/review_blocked terminal (exit 0, "Needs review"); a blocked Ask that
+ * delivered nothing then read as done. This re-checks the DELIVERABLE: only a
+ * blocked attempt that actually produced a partial answer is a review-blocked
+ * SUCCESS; an empty blocked (or plain failed) run is a failure (exit 1).
+ */
+export function readOnlyNoSuccessTerminal(opts) {
+    if (opts.webBlocked && opts.hasDeliverable) {
+        return { lifecycle: "succeeded", review: "blocked", reason: "review_blocked" };
+    }
+    if (opts.budgetStopped && opts.attemptsCount === 0) {
+        return { lifecycle: "failed", reason: "budget_exhausted" };
+    }
+    return { lifecycle: "failed", reason: "harness_failed" };
+}
+/**
+ * The unified finalizer. Precedence (hardest signal wins):
+ *   1. terminal context exhaustion with no completed report ⇒ interrupted;
+ *   2. a broken WorkReport contract on a constrained route ⇒ hard failure
+ *      (never prose-success);
+ *   3. a valid needs_input/incomplete report ⇒ veto (lifecycle stays, run is
+ *      non-applyable, exit non-zero) — a `completed` claim NEVER overrides a
+ *      harness error / failed gate / missing evidence;
+ *   4. otherwise the disclosed work_state (completed or unverified).
+ */
+export function finalizeAttempt(input) {
+    const completed = input.workReport?.state === "completed";
+    if (input.contextTerminalExhausted && !completed) {
+        return {
+            deliverablePresent: input.deliverableEvidence,
+            harnessErrored: input.harnessErrored,
+            workState: { state: "unverified", source: input.workReportSource },
+            reason: "context_capacity_exhausted",
+            outcomeClass: "interrupted",
+        };
+    }
+    if (input.workReportViolation) {
+        return {
+            deliverablePresent: false,
+            // A constrained route that promised a WorkReport and broke the contract
+            // failed the attempt — it must never terminalize as a prose success.
+            harnessErrored: true,
+            workState: { state: "unverified", source: input.workReportSource },
+            reason: "work_report_contract",
+            outcomeClass: "contract_failure",
+        };
+    }
+    const report = input.workReport;
+    if (report && (report.state === "needs_input" || report.state === "incomplete")) {
+        return {
+            deliverablePresent: input.deliverableEvidence,
+            harnessErrored: input.harnessErrored,
+            workState: {
+                state: report.state,
+                source: input.workReportSource,
+                ...(report.required_inputs.length > 0 ? { required_inputs: report.required_inputs } : {}),
+            },
+            reason: report.state === "needs_input" ? "input_required" : "work_incomplete",
+            outcomeClass: "veto",
+        };
+    }
+    return {
+        deliverablePresent: input.deliverableEvidence,
+        harnessErrored: input.harnessErrored,
+        workState: {
+            state: report?.state === "completed" ? "completed" : "unverified",
+            source: report ? input.workReportSource : "absent",
+        },
+        reason: null,
+        outcomeClass: "clean",
+    };
+}
+//# sourceMappingURL=attemptFinalize.js.map

package/dist/attemptFinalize.js.map

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