synorch 0.2.0 → 0.4.0-beta.0

package/dist/harness/orchestration/budget.d.ts

@@ -0,0 +1,110 @@
+import { HarnessError, type ApprovalBroker, type ApprovalDecision, type ApprovalRequest, type PolicyMode, type RunId, type SessionId, type Usage } from "../contracts/index.ts";
+/**
+ * Run budget (ADR-14). Before every model request the remaining budget is checked; at the limit no
+ * new request starts (`stop-new-requests`), at 120% of a metered limit or at the wall-time limit the
+ * active request is cancelled (`cancel-active`). A budget increase is a human-only approval.
+ */
+export declare const BUDGET_METRICS: readonly ["cost_usd", "wall_time_seconds", "steps", "tool_calls"];
+export type BudgetMetric = (typeof BUDGET_METRICS)[number];
+export interface BudgetLimits {
+    readonly maxCostUsd: number | undefined;
+    readonly maxWallTimeSeconds: number | undefined;
+    readonly maxSteps: number | undefined;
+    readonly maxToolCalls: number | undefined;
+}
+export declare const CANCEL_THRESHOLD = 1.2;
+export interface BudgetExceeded {
+    readonly scope: "run" | "task";
+    readonly metric: BudgetMetric;
+    readonly limit: number;
+    readonly used: number;
+    readonly action: "stop-new-requests" | "cancel-active";
+}
+export type BudgetAdmission = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly metric: BudgetMetric;
+    readonly limit: number;
+    readonly used: number;
+};
+export interface AdmitOptions {
+    readonly grace?: boolean;
+}
+export interface UsageObservation {
+    readonly sessionId: SessionId;
+    readonly seq: number;
+    readonly usage: Usage;
+}
+export interface BudgetUsage {
+    readonly costUsd: number;
+    readonly wallTimeSeconds: number;
+    readonly steps: number;
+    readonly toolCalls: number;
+}
+export interface BudgetTracker {
+    readonly scope: "run" | "task";
+    limits(): BudgetLimits;
+    usage(): BudgetUsage;
+    /** Folds provider-reported usage in; observations are de-duplicated by session and seq. */
+    observe(observations: readonly UsageObservation[]): void;
+    recordToolCalls(count: number): void;
+    /**
+     * Called right before a model request; a successful admission counts one step. With `grace` (the
+     * one forced report-only turn of an attempt, bounded by the worker manager) a request is still
+     * admitted when `steps` is the only exhausted metric, so an attempt can always hand in its report;
+     * a graced request is not counted as a step and cost and wall time are never graced.
+     */
+    admit(options?: AdmitOptions): BudgetAdmission;
+    /** Non-consuming check used before dispatching new work. */
+    exhausted(): BudgetAdmission;
+    /** Re-evaluates wall time and the 120% rule; fires cancel listeners at most once. */
+    check(): void;
+    onCancel(listener: (reason: BudgetExceeded) => void): () => void;
+    /** Applies a raise only when a human allowed exactly these limits. */
+    applyIncrease(decision: ApprovalDecision, subjectDigest: string, limits: BudgetLimits): boolean;
+}
+export interface BudgetTrackerOptions {
+    readonly scope: "run" | "task";
+    readonly limits: BudgetLimits;
+    readonly now?: () => number;
+    readonly onExceeded?: (exceeded: BudgetExceeded) => void;
+}
+export declare function createBudgetTracker(options: BudgetTrackerOptions): BudgetTracker;
+/** A budget raise is honoured only for an allowing decision made by a user for this exact subject. */
+export declare function isHumanBudgetGrant(decision: ApprovalDecision, subjectDigest: string): boolean;
+export interface BudgetIncreaseRequest {
+    readonly tracker: BudgetTracker;
+    readonly broker: ApprovalBroker;
+    readonly runId: RunId;
+    readonly mode: PolicyMode;
+    readonly limits: BudgetLimits;
+    readonly now: () => Date;
+    readonly record?: (request: ApprovalRequest, decision: ApprovalDecision | undefined) => Promise<void>;
+}
+export interface BudgetIncreaseOutcome {
+    readonly granted: boolean;
+    readonly request: ApprovalRequest;
+    readonly decision: ApprovalDecision | undefined;
+    readonly reason: string;
+}
+/**
+ * Asks a human to raise the budget. There is no orchestrator path: a decision that is not a user
+ * grant for these exact limits (including a malformed or orchestrator-made one) leaves them as is.
+ */
+export declare function requestBudgetIncrease(input: BudgetIncreaseRequest, signal: AbortSignal): Promise<BudgetIncreaseOutcome>;
+/** Converts a denied admission into the error the context builder surfaces to the driver. */
+export declare function budgetError(admission: Extract<BudgetAdmission, {
+    ok: false;
+}>): HarnessError;
+/**
+ * A late-bound gate shared by the coordinator (which owns the tracker for the active run) and the
+ * context builder (which calls it before every model request).
+ */
+export interface BudgetGateSlot {
+    set(tracker: BudgetTracker | undefined): void;
+    current(): BudgetTracker | undefined;
+    admit(observations: readonly UsageObservation[], options?: AdmitOptions): BudgetAdmission;
+}
+export declare function createBudgetGateSlot(): BudgetGateSlot;
+//# sourceMappingURL=budget.d.ts.map

package/dist/harness/orchestration/budget.d.ts.map

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

package/dist/harness/orchestration/budget.js

@@ -0,0 +1,197 @@
+import { ALLOWING_OUTCOMES, approvalDecisionSchema, createId, digestOf, HarnessError, } from "../contracts/index.js";
+/**
+ * Run budget (ADR-14). Before every model request the remaining budget is checked; at the limit no
+ * new request starts (`stop-new-requests`), at 120% of a metered limit or at the wall-time limit the
+ * active request is cancelled (`cancel-active`). A budget increase is a human-only approval.
+ */
+export const BUDGET_METRICS = ["cost_usd", "wall_time_seconds", "steps", "tool_calls"];
+export const CANCEL_THRESHOLD = 1.2;
+function limitOf(limits, metric) {
+    switch (metric) {
+        case "cost_usd":
+            return limits.maxCostUsd;
+        case "wall_time_seconds":
+            return limits.maxWallTimeSeconds;
+        case "steps":
+            return limits.maxSteps;
+        case "tool_calls":
+            return limits.maxToolCalls;
+    }
+}
+export function createBudgetTracker(options) {
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    let limits = options.limits;
+    let costUsd = 0;
+    let steps = 0;
+    let toolCalls = 0;
+    const seen = new Set();
+    const reported = new Set();
+    const cancelListeners = new Set();
+    let cancelled = false;
+    const usedOf = (metric) => {
+        switch (metric) {
+            case "cost_usd":
+                return costUsd;
+            case "wall_time_seconds":
+                return (now() - startedAt) / 1000;
+            case "steps":
+                return steps;
+            case "tool_calls":
+                return toolCalls;
+        }
+    };
+    const report = (exceeded) => {
+        const key = `${exceeded.metric}:${exceeded.action}:${exceeded.limit}`;
+        if (reported.has(key))
+            return;
+        reported.add(key);
+        options.onExceeded?.(exceeded);
+    };
+    const exhausted = () => {
+        for (const metric of BUDGET_METRICS) {
+            const limit = limitOf(limits, metric);
+            if (limit === undefined)
+                continue;
+            const used = usedOf(metric);
+            if (used >= limit)
+                return { ok: false, metric, limit, used };
+        }
+        return { ok: true };
+    };
+    /** Every metric but `steps` is still below its limit. */
+    const graceable = () => BUDGET_METRICS.every((metric) => {
+        const limit = limitOf(limits, metric);
+        return metric === "steps" || limit === undefined || usedOf(metric) < limit;
+    });
+    const check = () => {
+        for (const metric of BUDGET_METRICS) {
+            const limit = limitOf(limits, metric);
+            if (limit === undefined)
+                continue;
+            const used = usedOf(metric);
+            const threshold = metric === "wall_time_seconds" ? limit : limit * CANCEL_THRESHOLD;
+            if (used >= threshold) {
+                const exceeded = { scope: options.scope, metric, limit, used, action: "cancel-active" };
+                report(exceeded);
+                if (!cancelled) {
+                    cancelled = true;
+                    for (const listener of cancelListeners)
+                        listener(exceeded);
+                }
+                return;
+            }
+        }
+    };
+    return {
+        scope: options.scope,
+        limits: () => limits,
+        usage: () => ({ costUsd, wallTimeSeconds: usedOf("wall_time_seconds"), steps, toolCalls }),
+        observe(observations) {
+            for (const observation of observations) {
+                const key = `${observation.sessionId}#${observation.seq}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                costUsd += observation.usage.cost_usd_estimate ?? 0;
+            }
+            check();
+        },
+        recordToolCalls(count) {
+            toolCalls += count;
+            check();
+        },
+        admit(admission) {
+            check();
+            const verdict = exhausted();
+            if (!verdict.ok) {
+                report({ scope: options.scope, metric: verdict.metric, limit: verdict.limit, used: verdict.used, action: "stop-new-requests" });
+                if (admission?.grace !== true || !graceable())
+                    return verdict;
+                return { ok: true };
+            }
+            steps += 1;
+            return verdict;
+        },
+        exhausted,
+        check,
+        onCancel(listener) {
+            cancelListeners.add(listener);
+            return () => cancelListeners.delete(listener);
+        },
+        applyIncrease(decision, subjectDigest, next) {
+            if (!isHumanBudgetGrant(decision, subjectDigest))
+                return false;
+            limits = next;
+            cancelled = false;
+            return true;
+        },
+    };
+}
+/** A budget raise is honoured only for an allowing decision made by a user for this exact subject. */
+export function isHumanBudgetGrant(decision, subjectDigest) {
+    if (!approvalDecisionSchema.safeParse(decision).success)
+        return false;
+    return (decision.subject_kind === "budget" &&
+        decision.decided_by === "user" &&
+        decision.subject_digest === subjectDigest &&
+        ALLOWING_OUTCOMES.includes(decision.outcome));
+}
+/**
+ * Asks a human to raise the budget. There is no orchestrator path: a decision that is not a user
+ * grant for these exact limits (including a malformed or orchestrator-made one) leaves them as is.
+ */
+export async function requestBudgetIncrease(input, signal) {
+    const subjectDigest = digestOf({ kind: "budget", run_id: input.runId, limits: input.limits });
+    const request = {
+        approval_id: createId("approval"),
+        run_id: input.runId,
+        subject_kind: "budget",
+        subject_digest: subjectDigest,
+        summary: `Raise run budget to ${JSON.stringify(input.limits)}`,
+        scope: "once",
+        requested_at: input.now().toISOString(),
+    };
+    let decision;
+    try {
+        decision = await input.broker.request(request, signal);
+    }
+    catch (error) {
+        await input.record?.(request, undefined);
+        return { granted: false, request, decision: undefined, reason: error instanceof Error ? error.message : String(error) };
+    }
+    await input.record?.(request, approvalDecisionSchema.safeParse(decision).success ? decision : undefined);
+    const granted = input.tracker.applyIncrease(decision, subjectDigest, input.limits);
+    return {
+        granted,
+        request,
+        decision,
+        reason: granted ? "raised by a user decision" : `not raised: ${decision.decided_by} decided ${decision.outcome}`,
+    };
+}
+/** Converts a denied admission into the error the context builder surfaces to the driver. */
+export function budgetError(admission) {
+    return new HarnessError({
+        code: "budget_exceeded",
+        message: `budget exhausted: ${admission.metric} used ${admission.used.toFixed(2)} of ${admission.limit}`,
+        workspace_effect: "none",
+        retry_safe: false,
+        next_command: "syn run --budget <higher limit> (a raise needs a human decision)",
+    });
+}
+export function createBudgetGateSlot() {
+    let tracker;
+    return {
+        set(next) {
+            tracker = next;
+        },
+        current: () => tracker,
+        admit(observations, options) {
+            if (tracker === undefined)
+                return { ok: true };
+            tracker.observe(observations);
+            return tracker.admit(options);
+        },
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/harness/orchestration/budget.js.map

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

package/dist/harness/orchestration/capabilities.d.ts

@@ -0,0 +1,6 @@
+import { type Plan } from "../contracts/index.ts";
+/** The command a statement asks to run, when it names one of `commands` or an obvious command line. */
+export declare function commandMentioned(statement: string, commands: readonly string[]): string | undefined;
+/** Human- and model-readable problems of a structurally valid plan; empty when roles fit their tasks. */
+export declare function roleCapabilityIssues(plan: Plan): string[];
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/harness/orchestration/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/harness/orchestration/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,IAAI,EAAiB,MAAM,uBAAuB,CAAC;AAoBpG,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAOnG;AAwBD,yGAAyG;AACzG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAwCzD"}

package/dist/harness/orchestration/capabilities.js

@@ -0,0 +1,80 @@
+import { canRunCommands, ROLE_CAPABILITIES } from "../contracts/index.js";
+/**
+ * Plan checks against what each role can actually do (`ROLE_CAPABILITIES`). The first live run
+ * failed because the plan gave an explorer (no exec tool) a verification command and a criterion
+ * that demanded running it: the explorer could only report `partial`, and the run failed. A plan
+ * like that is now rejected with a reason the orchestrator can act on, before anything runs.
+ *
+ * The criterion check is deliberately narrow and deterministic: a statement is flagged only when it
+ * names a verification command of the plan or an unmistakable command line (`node check.mjs`,
+ * `pnpm test`, `go test ./...`). Anything subtler is left to the orchestrator's triage at runtime.
+ */
+const RUNNERS = ["node", "npm", "pnpm", "yarn", "npx", "bun", "deno", "python", "python3", "pytest", "go", "cargo", "dotnet", "mvn", "gradle", "gradlew", "jest", "vitest", "tsc"];
+const SUBCOMMANDS = ["test", "run", "build", "exec", "install", "check", "lint", "start", "ci", "verify"];
+const COMMAND_LINE = new RegExp(`(?:^|[\\s\`'"(])((?:${RUNNERS.join("|")})\\s+(?:-{1,2}[\\w-]+\\s+)*(?:[\\w@-]*[./\\\\][\\w@./\\\\-]*|(?:${SUBCOMMANDS.join("|")})\\b))`, "i");
+/** The command a statement asks to run, when it names one of `commands` or an obvious command line. */
+export function commandMentioned(statement, commands) {
+    const lowered = statement.toLowerCase();
+    for (const command of commands) {
+        const needle = command.trim().toLowerCase();
+        if (needle.length > 0 && lowered.includes(needle))
+            return command.trim();
+    }
+    return COMMAND_LINE.exec(statement)?.[1]?.trim();
+}
+function dependentsOf(plan, key) {
+    const reach = new Set([key]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const task of plan.tasks) {
+            if (!reach.has(task.key) && task.depends_on.some((dependency) => reach.has(dependency))) {
+                reach.add(task.key);
+                grew = true;
+            }
+        }
+    }
+    return plan.tasks.filter((task) => task.key !== key && reach.has(task.key));
+}
+function runnerHint(plan, task) {
+    const candidates = dependentsOf(plan, task.key).filter((other) => other.role === "implementer" || (other.role === "debugger" && other.owned_paths.length > 0));
+    return candidates.length > 0
+        ? `move it to ${candidates.map((other) => other.key).join(" or ")} (a task whose role can run commands)`
+        : "move it to an implementer task that depends on this one";
+}
+/** Human- and model-readable problems of a structurally valid plan; empty when roles fit their tasks. */
+export function roleCapabilityIssues(plan) {
+    const issues = [];
+    const byKey = new Map(plan.tasks.map((task) => [task.key, task]));
+    const knownCommands = [...new Set([...plan.verification, ...plan.tasks.flatMap((task) => task.verification)])];
+    for (const [index, task] of plan.tasks.entries()) {
+        const at = `tasks[${index}] ${task.key} (${task.role})`;
+        if (!canRunCommands(task.role)) {
+            if (task.verification.length > 0) {
+                issues.push(`${at}: the ${task.role} role cannot run commands (command capability ${ROLE_CAPABILITIES[task.role].commands}), so verification [${task.verification.join(", ")}] could never run; ${runnerHint(plan, task)} and leave this task's verification empty`);
+            }
+            for (const criterion of task.acceptance_criteria) {
+                const command = commandMentioned(criterion.statement, knownCommands);
+                if (command !== undefined) {
+                    issues.push(`${at} ${criterion.id}: it requires running "${command}", which the ${task.role} role cannot do; phrase the criterion as something to find by reading, and ${runnerHint(plan, task)}`);
+                }
+            }
+        }
+        if (task.role === "reviewer") {
+            if (task.depends_on.length === 0) {
+                issues.push(`${at}: a reviewer task configures the independent review of the tasks it depends on; add depends_on with the standard/high-risk task to review (to inspect existing code, use an explorer)`);
+            }
+            for (const key of task.depends_on) {
+                const dependency = byKey.get(key);
+                if (dependency === undefined)
+                    continue;
+                // An integration review (2+ dependencies) may cover trivial tasks: it checks the combined result.
+                if (dependency.role === "reviewer" || (dependency.risk === "trivial" && task.depends_on.length < 2)) {
+                    issues.push(`${at}: it depends on ${key}, which is ${dependency.role === "reviewer" ? "another reviewer task" : "trivial"} and gets no independent review; raise ${key}'s risk to standard or drop the reviewer task`);
+                }
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/harness/orchestration/capabilities.js.map

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

package/dist/harness/orchestration/claims.d.ts

@@ -0,0 +1,148 @@
+import type { z } from "zod";
+import { type ReportToolName, type ReviewReportInput, type TaskReportInput } from "../contracts/index.ts";
+import { type AttemptLog } from "./attempt-log.ts";
+/**
+ * What a worker or reviewer *claims*. The channel is the structured report tool (`task_report`,
+ * `review_report`): its input is validated by the gateway and recorded in the attempt log, and the
+ * last succeeded call wins. A final fenced JSON block is accepted only as a fallback when no report
+ * call succeeded; it is parsed with the same contract schema. Either way the claim carries only
+ * narrative and evidence pointers: identity, changed paths, the artifact digest and tool call ids
+ * come from the log and the real diff, and every pointer is verified against the log.
+ */
+export declare const workerClaimSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        needs_context: "needs_context";
+        blocked: "blocked";
+        partial: "partial";
+    }>;
+    summary: z.ZodString;
+    acceptance_evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        criterion_id: z.ZodString;
+        evidence: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                file: "file";
+                artifact: "artifact";
+                event: "event";
+                "harness-verification": "harness-verification";
+                "harness-diff": "harness-diff";
+                "tool-call": "tool-call";
+                "test-run": "test-run";
+                review: "review";
+            }>;
+            ref: z.ZodString;
+            digest: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "Digest", "out">>;
+            produced_by: z.ZodEnum<{
+                orchestrator: "orchestrator";
+                reviewer: "reviewer";
+                user: "user";
+                worker: "worker";
+                harness: "harness";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    commands_run: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        exit_code: z.ZodInt;
+        evidence: z.ZodObject<{
+            kind: z.ZodEnum<{
+                file: "file";
+                artifact: "artifact";
+                event: "event";
+                "harness-verification": "harness-verification";
+                "harness-diff": "harness-diff";
+                "tool-call": "tool-call";
+                "test-run": "test-run";
+                review: "review";
+            }>;
+            ref: z.ZodString;
+            digest: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "Digest", "out">>;
+            produced_by: z.ZodEnum<{
+                orchestrator: "orchestrator";
+                reviewer: "reviewer";
+                user: "user";
+                worker: "worker";
+                harness: "harness";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    decisions_made: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    skipped_checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        check: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    unresolved_risks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    recommended_context_updates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    root_cause: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WorkerClaim = TaskReportInput;
+export declare const reviewerClaimSchema: z.ZodObject<{
+    criteria: z.ZodArray<z.ZodObject<{
+        criterion_id: z.ZodString;
+        verdict: z.ZodEnum<{
+            met: "met";
+            not_met: "not_met";
+            unverifiable: "unverifiable";
+        }>;
+        note: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                file: "file";
+                artifact: "artifact";
+                event: "event";
+                "harness-verification": "harness-verification";
+                "harness-diff": "harness-diff";
+                "tool-call": "tool-call";
+                "test-run": "test-run";
+                review: "review";
+            }>;
+            ref: z.ZodString;
+            digest: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "Digest", "out">>;
+            produced_by: z.ZodEnum<{
+                orchestrator: "orchestrator";
+                reviewer: "reviewer";
+                user: "user";
+                worker: "worker";
+                harness: "harness";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            blocker: "blocker";
+            major: "major";
+            minor: "minor";
+        }>;
+        summary: z.ZodString;
+        path: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        line: z.ZodOptional<z.ZodInt>;
+        reproduction: z.ZodOptional<z.ZodString>;
+        recommendation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    decision: z.ZodEnum<{
+        accept: "accept";
+        revise: "revise";
+        block: "block";
+    }>;
+}, z.core.$strict>;
+export type ReviewerClaim = ReviewReportInput;
+/** The last ```json fenced block, or the whole text when it is a bare JSON object. */
+export declare function extractJsonBlock(text: string): unknown;
+export type ClaimResult<T> = {
+    readonly ok: true;
+    readonly claim: T;
+    readonly channel: "tool" | "json-block";
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/** Parses a claim from a final message's JSON block (the fallback channel). */
+export declare function parseClaim<T>(schema: z.ZodType<T>, text: string | undefined): ClaimResult<T>;
+/** Reads the claim from the last succeeded report tool call, falling back to the final JSON block. */
+export declare function readClaim<T>(schema: z.ZodType<T>, log: AttemptLog, tool: ReportToolName): ClaimResult<T>;
+export declare const WORKER_REPORT_INSTRUCTIONS: string;
+export declare const REVIEWER_REPORT_INSTRUCTIONS: string;
+//# sourceMappingURL=claims.d.ts.map

package/dist/harness/orchestration/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../../src/harness/orchestration/claims.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEjE;;;;;;;GAOG;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAAwB,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC;AAC1C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA0B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAE9C,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAatD;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAUjE,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAK5F;AAED,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,CAAC,CAAC,CAAC,CAIxG;AAED,eAAO,MAAM,0BAA0B,QAK3B,CAAC;AAEb,eAAO,MAAM,4BAA4B,QAI7B,CAAC"}

package/dist/harness/orchestration/claims.js

@@ -0,0 +1,64 @@
+import { REPORT_TOOL_NAMES, reviewReportInputSchema, taskReportInputSchema, } from "../contracts/index.js";
+import { latestReport } from "./attempt-log.js";
+/**
+ * What a worker or reviewer *claims*. The channel is the structured report tool (`task_report`,
+ * `review_report`): its input is validated by the gateway and recorded in the attempt log, and the
+ * last succeeded call wins. A final fenced JSON block is accepted only as a fallback when no report
+ * call succeeded; it is parsed with the same contract schema. Either way the claim carries only
+ * narrative and evidence pointers: identity, changed paths, the artifact digest and tool call ids
+ * come from the log and the real diff, and every pointer is verified against the log.
+ */
+export const workerClaimSchema = taskReportInputSchema;
+export const reviewerClaimSchema = reviewReportInputSchema;
+/** The last ```json fenced block, or the whole text when it is a bare JSON object. */
+export function extractJsonBlock(text) {
+    const fences = [...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)];
+    const candidates = fences.map((match) => match[1] ?? "").reverse();
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}"))
+        candidates.push(trimmed);
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+function validate(schema, raw, channel) {
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, problems: parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`) };
+    }
+    return { ok: true, claim: parsed.data, channel };
+}
+/** Parses a claim from a final message's JSON block (the fallback channel). */
+export function parseClaim(schema, text) {
+    if (text === undefined || text.trim() === "")
+        return { ok: false, problems: ["no report tool call and the final message is empty"] };
+    const raw = extractJsonBlock(text);
+    if (raw === undefined)
+        return { ok: false, problems: ["no report tool call and the final message has no JSON block"] };
+    return validate(schema, raw, "json-block");
+}
+/** Reads the claim from the last succeeded report tool call, falling back to the final JSON block. */
+export function readClaim(schema, log, tool) {
+    const reported = latestReport(log, tool);
+    if (reported !== undefined)
+        return validate(schema, reported, "tool");
+    return parseClaim(schema, log.finalAssistantText);
+}
+export const WORKER_REPORT_INSTRUCTIONS = [
+    `When you are done, call the \`${REPORT_TOOL_NAMES.task}\` tool exactly once as your last action with your status, summary and`,
+    'acceptance_evidence per criterion (evidence kinds: tool-call|test-run|file; ref = the [#n] shown before a tool result of this attempt, written "#n"; produced_by: worker).',
+    "The harness runs the packet's verification commands itself after your turn and computes the diff; do not list changed files. If a ref does not resolve, the tool tells you which refs are valid.",
+    "If the tool is unavailable, reply with the same object in one ```json block.",
+].join("\n");
+export const REVIEWER_REPORT_INSTRUCTIONS = [
+    `Finish by calling the \`${REPORT_TOOL_NAMES.review}\` tool exactly once with a verdict (met|not_met|unverifiable) per criterion,`,
+    "findings (F-<n>, blocker|major|minor|info) and decision accept|revise|block. If the tool is unavailable, reply with the same object in one ```json block.",
+    'A met verdict needs independent evidence: a tool call you made in this review (ref "#n", produced_by: reviewer) or a passed harness-verification record not marked [supporting only] (its ref, produced_by: harness). Worker evidence, a harness-diff or a read-only check alone is not enough; with no such record, run the check yourself.',
+].join("\n");
+//# sourceMappingURL=claims.js.map