@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

package/dist/workflows/dag/frontend-provider-capability-matrix.js

@@ -0,0 +1,159 @@
+import { randomUUID } from "node:crypto";
+import { TYPED_EVENT_FACT_KINDS, stageTypedEventRecord, } from "./frontend-typed-event-store.js";
+import { createDagEventObserver } from "./event-observer.js";
+/**
+ * M1 shadow-only provider/model capability matrix (AC-003).
+ *
+ * Records seven provider/model capability facts as read-only observations:
+ *   - `terminal-commit`
+ *   - `disconnect`
+ *   - `duplicate-tool-call`
+ *   - `length-before-terminal`
+ *   - `reasoning-timeout`
+ *   - `provider-ended-without-terminal`
+ *   - `read-only-fact-channel`
+ *
+ * This matrix is intentionally shadow-only: `recordProviderCapabilityFact`
+ * returns a record for audit, never a branch-control signal, and this module
+ * must never be imported into `node-execution.ts`'s model-selection / branch
+ * control path. It is deliberately distinct from `frontend-project-capability`
+ * (framework / mock discovery).
+ *
+ * The read-only fact channel composes the existing `createDagEventObserver`
+ * (which already swallows its own write errors) so that a shadow-channel
+ * failure can never affect canonical DAG execution.
+ */
+export const PROVIDER_CAPABILITY_FACT_KINDS = TYPED_EVENT_FACT_KINDS;
+/** Terminal finish-reason shapes, modeled after
+ * `src/executors/pi-event-serializer.ts`'s private `TERMINAL_FINISH_REASON_TYPES`
+ * / `readExplicitFinishReason` (those symbols are not exported, so the matrix
+ * keeps its own local projection). */
+const TERMINAL_FINISH_REASON_TYPES = new Set([
+    "message_end",
+    "turn_end",
+    "assistant_message",
+]);
+function readExplicitFinishReason(source) {
+    const message = isRecord(source.message) ? source.message : undefined;
+    const candidates = [
+        source.finish_reason,
+        source.finishReason,
+        source.stop_reason,
+        source.stopReason,
+        message?.finish_reason,
+        message?.finishReason,
+        message?.stop_reason,
+        message?.stopReason,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim().length > 0) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** True when an observed provider event is terminal-shaped. Shadow-only: the
+ * result is a fact, not a control decision. */
+export function isTerminalProviderEventShape(event) {
+    const type = typeof event.type === "string" ? event.type : undefined;
+    return type !== undefined && TERMINAL_FINISH_REASON_TYPES.has(type);
+}
+/** Build a `terminal-commit` fact from a provider event, if the event carries a
+ * terminal shape or an explicit finish reason. Returns undefined when the event
+ * has no terminal evidence (the caller records nothing in that case). */
+export function buildTerminalCommitFact(event) {
+    if (!isTerminalProviderEventShape(event)) {
+        const reason = readExplicitFinishReason(event);
+        if (reason === undefined)
+            return undefined;
+        return { kind: "terminal-commit", finishReason: reason };
+    }
+    return {
+        kind: "terminal-commit",
+        finishReason: readExplicitFinishReason(event),
+    };
+}
+/**
+ * A+B (AC-005): route a requested fact kind through the frozen provider
+ * capability matrix. Kinds outside the seven-value matrix fail closed to
+ * `unsupported-provider-capability` so a plan retry can select a bounded
+ * tool-only / backup-model step instead of repeating an unsupported tool.
+ */
+export function routeFrontendProviderCapability(input) {
+    if (TYPED_EVENT_FACT_KINDS.includes(input.factKind)) {
+        return { ok: true, kind: input.factKind };
+    }
+    return { ok: false, reason: "unsupported-provider-capability" };
+}
+/**
+ * Append a capability fact as a staged read-only observation. Returns the
+ * record (for audit) and never a branch-control signal. Unknown fact kinds are
+ * rejected fail-closed so the matrix cannot silently widen its own catalog.
+ */
+export function recordProviderCapabilityFact(options) {
+    const kind = options.fact.kind;
+    if (!TYPED_EVENT_FACT_KINDS.includes(kind)) {
+        throw new Error(`unknown provider capability fact kind: ${String(kind)}`);
+    }
+    const eventId = options.eventId ?? randomUUID();
+    const record = stageTypedEventRecord(options.store, {
+        eventId,
+        requestId: options.requestId,
+        attemptId: options.attemptId,
+        fact: options.fact,
+        recordedAt: options.recordedAt,
+    });
+    return { eventId, record };
+}
+/**
+ * Attach a shadow observer that records `read-only-fact-channel` facts while
+ * delegating the canonical event JSONL to the existing `createDagEventObserver`.
+ * The shadow channel never throws into the caller: any recording failure is
+ * swallowed so canonical execution is unaffected.
+ */
+export function createProviderCapabilityShadowObserver(options) {
+    const base = createDagEventObserver({
+        eventsJsonlPath: options.eventsJsonlPath,
+        dagRunId: options.dagRunId,
+        spec: options.spec,
+    });
+    const recordReadOnlyFact = (eventType) => {
+        try {
+            recordProviderCapabilityFact({
+                store: options.store,
+                attemptId: options.attemptId,
+                requestId: options.requestId,
+                fact: { kind: "read-only-fact-channel", eventType },
+            });
+        }
+        catch {
+            // Shadow channel must never affect canonical execution.
+        }
+    };
+    const observer = {
+        onRunStart: async (state) => {
+            recordReadOnlyFact("dag.run.started");
+            await base.observer.onRunStart?.(state);
+        },
+        onNodeStart: async (nodeId, state) => {
+            recordReadOnlyFact("dag.node.started");
+            await base.observer.onNodeStart?.(nodeId, state);
+        },
+        onNodeOutput: async (nodeId, chunk, state) => {
+            recordReadOnlyFact("dag.node.output");
+            await base.observer.onNodeOutput?.(nodeId, chunk, state);
+        },
+        onNodeFinish: async (nodeId, state) => {
+            recordReadOnlyFact("dag.node.finished");
+            await base.observer.onNodeFinish?.(nodeId, state);
+        },
+        onRunFinish: async (state) => {
+            recordReadOnlyFact("dag.run.finished");
+            await base.observer.onRunFinish?.(state);
+        },
+    };
+    return { observer, flush: base.flush };
+}

package/dist/workflows/dag/frontend-recovery-capsule.js

@@ -0,0 +1,455 @@
+import { z } from "zod";
+import { normalizeDagFailureCategory, } from "./failure-category.js";
+import { routeDagFailure, } from "./failure-routing.js";
+import { computeNormalizedFailureFingerprint, } from "./frontend-recovery-lineage.js";
+/**
+ * M6 failure capsule + deterministic ownership classifier + fact invalidation
+ * matrix + frozen command reuse validation (pure functions).
+ *
+ * AC-001 invariant: `restartPhase` is always the runtime classifier output.
+ * `modelSuggestedRestartPhase` is recorded separately and NEVER overrides it.
+ *
+ * AC-001/AC-002: canonical frontend recovery taxonomy. Operation state and the
+ * optional terminal are separate fields; legacy Console states
+ * (`queued|running|succeeded|failed|timed-out|needs-reconcile`), boolean
+ * terminal markers, and legacy owner/mode strings never appear in the capsule.
+ *
+ * All schemas are self-contained and `.strict()`: this module never extends
+ * `DagRunState`/`DagSpec` and only imports the existing recovery modules.
+ */
+const hash64 = z.string().regex(/^[a-f0-9]{64}$/);
+/* ------------------------------------------------------------------ *
+ * Restart phase + ownership.                                          *
+ * ------------------------------------------------------------------ */
+export const restartPhaseSchema = z.enum([
+    "contract",
+    "scout",
+    "plan",
+    "implement",
+]);
+export const RESTART_PHASE_ORDER = [
+    "contract",
+    "scout",
+    "plan",
+    "implement",
+];
+export const failureOwnerSchema = z.enum([
+    "contract",
+    "scout",
+    "plan",
+    "implementation",
+    "verification-config",
+    "environment",
+    "scope",
+    "unknown",
+]);
+export const recoveryModeSchema = z.enum([
+    "node-retry",
+    "continuation",
+    "new-dag",
+    "wait-external",
+    "human-decision",
+    "none",
+]);
+/* ------------------------------------------------------------------ *
+ * Canonical operation state / terminal / protocol failure.            *
+ * ------------------------------------------------------------------ */
+export const frontendOperationTerminalSchema = z.enum([
+    "success",
+    "non-converging",
+    "cancelled",
+    "superseded",
+    "failed-internal",
+]);
+export const frontendOperationStateSchema = z.enum([
+    "active",
+    "orchestrating-split",
+    "recoverable",
+    "blocked-human",
+    "blocked-external",
+    "success",
+    "non-converging",
+    "cancelled",
+    "superseded",
+    "failed-internal",
+]);
+const FRONTEND_OPERATION_TERMINAL_VALUES = frontendOperationTerminalSchema.options;
+/** True when the canonical state is one of the five terminal values. */
+export function isFrontendOperationTerminalState(state) {
+    return FRONTEND_OPERATION_TERMINAL_VALUES.includes(state);
+}
+export const frontendNodeProtocolFailureReasonSchema = z.enum([
+    "length-before-terminal",
+    "terminal-event-missing",
+    "reasoning-timeout",
+    "provider-ended-without-terminal",
+    "terminal-conflict",
+    "unsupported-tool-capability",
+    "typed-fact-invalid",
+]);
+const PROTOCOL_REASON_ALIASES = {
+    "frontend candidate contract invalid": "typed-fact-invalid",
+};
+/**
+ * Project a free-form protocol failure string to the canonical 7-value enum.
+ * Known aliases map to their canonical value; the 7 enum values pass through;
+ * anything else (including `frontend writer transient partial write` and
+ * `unknown failure`) fails closed to `undefined`.
+ */
+export function projectProtocolFailureReason(reason) {
+    const alias = PROTOCOL_REASON_ALIASES[reason];
+    if (alias)
+        return alias;
+    const parsed = frontendNodeProtocolFailureReasonSchema.safeParse(reason);
+    return parsed.success ? parsed.data : undefined;
+}
+function ownerFromNodeId(nodeId) {
+    const id = nodeId.toLowerCase();
+    if (id.includes("contract"))
+        return "contract";
+    if (id.includes("scout"))
+        return "scout";
+    if (id.includes("plan"))
+        return "plan";
+    if (id.includes("implement"))
+        return "implementation";
+    return undefined;
+}
+function ownerFromProductLine(productLine) {
+    if (!productLine)
+        return "unknown";
+    switch (productLine) {
+        case "SpecUnclear":
+            return "contract";
+        case "ContractMismatch":
+            return "plan";
+        case "ProductBug":
+        case "TestBug":
+        case "RiskyChange":
+            return "implementation";
+        case "EnvFailure":
+        case "FlakyTest":
+        case "DependencyFailure":
+            return "environment";
+        case "NeedsHuman":
+        case "Unknown":
+            return "unknown";
+        default: {
+            const exhaustive = productLine;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Deterministic ownership classifier. Priority order:
+ *   1. explicit failure source/nodeId phase substring;
+ *   2. verification-config signals (frozen command drift, stale verification
+ *      plan, unresolved entrypoint);
+ *   3. environment signals (env/flaky/dependency/network/rate-limit/provider
+ *      unavailable);
+ *   4. scope signals (path/write/forbidden/write-guard/writeSet violations);
+ *   5. product-line routing fallback;
+ *   6. fail-closed `unknown`.
+ *
+ * `verification-config`, `environment`, `scope`, and `unknown` never resolve to
+ * `implementation` (AC-003): writer recovery is never auto-selected for them.
+ */
+export function classifyFailureOwner(input) {
+    const source = (input.failureSource ?? input.nodeId ?? "").toLowerCase();
+    const fromSource = ownerFromNodeId(source);
+    if (fromSource)
+        return fromSource;
+    const raw = (input.rawFailureCategory ?? "").toLowerCase();
+    const nodeId = (input.nodeId ?? "").toLowerCase();
+    const normalized = input.normalizedFailureCategory ??
+        normalizeDagFailureCategory(input.rawFailureCategory);
+    // 2. verification-config signals.
+    if (raw.includes("verification-plan-stale") ||
+        raw.includes("verification-plan") ||
+        raw.includes("frozen") ||
+        raw.includes("drift") ||
+        raw.includes("entrypoint") ||
+        nodeId.includes("verification-config")) {
+        return "verification-config";
+    }
+    // 3. environment signals.
+    if (raw.includes("env-failure") ||
+        raw.includes("env failure") ||
+        raw.includes("flaky") ||
+        raw.includes("dependency") ||
+        raw.includes("network") ||
+        raw.includes("rate-limit") ||
+        raw.includes("rate_limit") ||
+        raw.includes("quota") ||
+        raw.includes("unavailable") ||
+        normalized === "executor") {
+        return "environment";
+    }
+    // 4. scope signals.
+    if (raw.includes("path") ||
+        raw.includes("forbidden") ||
+        raw.includes("write-guard") ||
+        raw.includes("write_guard") ||
+        raw.includes("writeset") ||
+        normalized === "write-guard") {
+        return "scope";
+    }
+    if (normalized === "success")
+        return "unknown";
+    const routing = routeDagFailure({
+        rawFailureCategory: input.rawFailureCategory,
+        normalizedFailureCategory: normalized,
+        nodeId: input.nodeId,
+    });
+    return ownerFromProductLine(routing.productLineFailureCategory);
+}
+/**
+ * Deterministic owner → restart phase mapping. `environment` and `unknown`
+ * have no restart phase (fail closed to `undefined`); `verification-config`
+ * and `scope` restart from contract (the only rebuild path — new-dag from
+ * contract, §6.1.2). The parameter accepts a legacy/unknown string so existing
+ * shell-executor call sites that pass legacy owner names still typecheck and
+ * fail closed to `undefined`.
+ */
+export function classifyRestartPhase(owner) {
+    switch (owner) {
+        case "contract":
+            return "contract";
+        case "scout":
+            return "scout";
+        case "plan":
+            return "plan";
+        case "implementation":
+            return "implement";
+        case "verification-config":
+        case "scope":
+            return "contract";
+        case "environment":
+        case "unknown":
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * A+B (AC-009): deterministic issueCategory → restart phase mapping (§4.10).
+ * `approved-design-defect` restarts at `plan` (design decisions live in the
+ * plan phase); `unknown` fails closed to `undefined` so the runtime classifier
+ * never trusts an untyped category.
+ */
+export function classifyIssueCategoryRestartPhase(issueCategory) {
+    switch (issueCategory) {
+        case "implementation-mismatch":
+            return "implement";
+        case "approved-design-defect":
+            return "plan";
+        case "target-surface-defect":
+            return "scout";
+        case "contract-requirement-gap":
+            return "contract";
+        case "unknown":
+        default:
+            return undefined;
+    }
+}
+function factPhaseOf(factId) {
+    const id = factId.toLowerCase();
+    if (id.includes("contract"))
+        return "contract";
+    if (id.includes("scout"))
+        return "scout";
+    if (id.includes("plan"))
+        return "plan";
+    if (id.includes("implement"))
+        return "implement";
+    return undefined;
+}
+/**
+ * Deterministic fact invalidation matrix. Restarting at a phase invalidates
+ * that phase and everything downstream, while upstream facts stay reusable.
+ * Unknown fact ids fail closed to `invalidated`. At the exact restart phase,
+ * a committed candidate survives (reusable); an uncommitted partial write does
+ * not.
+ */
+export function evaluateFactInvalidation(input) {
+    const factPhase = factPhaseOf(input.factId);
+    if (factPhase === undefined)
+        return "invalidated";
+    const factIndex = RESTART_PHASE_ORDER.indexOf(factPhase);
+    const restartIndex = RESTART_PHASE_ORDER.indexOf(input.restartPhase);
+    if (factIndex < restartIndex)
+        return "reusable";
+    if (factIndex > restartIndex)
+        return "invalidated";
+    return input.commitState === "committed-candidate" ? "reusable" : "invalidated";
+}
+/**
+ * Hash/fingerprint-driven frozen command reuse check. Unknown/malformed
+ * command hash → refuse (fail-closed). Any invalidated input fact (by matrix
+ * or explicit set) → refuse. All facts reusable + known hash → reuse.
+ */
+export function validateFrozenCommandReuse(input) {
+    if (!/^[a-f0-9]{64}$/.test(input.commandHash)) {
+        return {
+            decision: "refuse",
+            reason: "unknown or malformed command hash; fail-closed",
+        };
+    }
+    const explicitlyInvalidated = new Set(input.invalidatedFactIds);
+    for (const factId of input.inputFactIds) {
+        const disposition = evaluateFactInvalidation({
+            factId,
+            restartPhase: input.restartPhase,
+            commitState: input.commitState,
+        });
+        if (disposition === "invalidated" || explicitlyInvalidated.has(factId)) {
+            return {
+                decision: "refuse",
+                reason: `input fact ${factId} is invalidated; frozen command cannot be reused`,
+            };
+        }
+    }
+    return {
+        decision: "reuse",
+        reason: "all input facts reusable and command hash is known",
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Failure capsule (AC-001).                                           *
+ * ------------------------------------------------------------------ */
+export const failureCapsuleV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    parentRunId: z.string().min(1),
+    operationState: frontendOperationStateSchema,
+    operationTerminal: frontendOperationTerminalSchema.optional(),
+    recoveryMode: recoveryModeSchema,
+    protocolFailureReason: frontendNodeProtocolFailureReasonSchema.optional(),
+    failureOwner: failureOwnerSchema,
+    restartPhase: restartPhaseSchema.optional(),
+    modelSuggestedRestartPhase: restartPhaseSchema.optional(),
+    invalidatedFactIds: z.array(z.string().min(1)),
+    reusableFactIds: z.array(z.string().min(1)),
+    evidenceRefs: z.array(z.string().min(1)),
+    normalizedFingerprint: hash64,
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    // Cross-field invariant 1: terminal state ⇔ matching terminal present;
+    // non-terminal state ⇔ terminal absent.
+    if (isFrontendOperationTerminalState(value.operationState)) {
+        if (value.operationTerminal === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `terminal operation state ${value.operationState} requires operationTerminal`,
+                path: ["operationTerminal"],
+            });
+        }
+        else if (value.operationTerminal !== value.operationState) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `operationTerminal must equal operationState for terminal state (${value.operationState})`,
+                path: ["operationTerminal"],
+            });
+        }
+    }
+    else if (value.operationTerminal !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `non-terminal operation state ${value.operationState} must not carry operationTerminal`,
+            path: ["operationTerminal"],
+        });
+    }
+    // Cross-field invariant 2: continuation/new-dag require a restart phase;
+    // all other modes forbid one.
+    const modeRequiresRestart = value.recoveryMode === "continuation" || value.recoveryMode === "new-dag";
+    if (modeRequiresRestart && value.restartPhase === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `recoveryMode ${value.recoveryMode} requires restartPhase`,
+            path: ["restartPhase"],
+        });
+    }
+    if (!modeRequiresRestart && value.restartPhase !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `recoveryMode ${value.recoveryMode} must not carry restartPhase`,
+            path: ["restartPhase"],
+        });
+    }
+    // Cross-field invariant 3: when present, restartPhase must equal the
+    // runtime classifier output (a model suggestion never overrides it).
+    if (value.restartPhase !== undefined) {
+        const expectedRestartPhase = classifyRestartPhase(value.failureOwner);
+        if (value.restartPhase !== expectedRestartPhase) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `restartPhase must equal runtime classifier output (${expectedRestartPhase ?? "undefined"})`,
+                path: ["restartPhase"],
+            });
+        }
+    }
+    const invalidated = new Set(value.invalidatedFactIds);
+    const overlap = value.reusableFactIds.filter((id) => invalidated.has(id));
+    if (overlap.length > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `fact ids cannot be both invalidated and reusable: ${overlap.join(",")}`,
+            path: ["reusableFactIds"],
+        });
+    }
+    const expectedFingerprint = computeNormalizedFailureFingerprint({
+        failureOwner: value.failureOwner,
+        protocolFailureReason: value.protocolFailureReason ?? "",
+        restartPhase: value.restartPhase,
+        invalidatedFactIds: value.invalidatedFactIds,
+    });
+    if (value.normalizedFingerprint !== expectedFingerprint) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "normalizedFingerprint must match the deterministic fingerprint",
+            path: ["normalizedFingerprint"],
+        });
+    }
+});
+/**
+ * Assemble a validated failure capsule. `restartPhase` is derived from the
+ * runtime classifier only when the mode requires one; a model suggestion is
+ * only recorded, never applied. The schema then enforces the cross-field
+ * invariants (terminal/state, mode/phase, classifier authority).
+ */
+export function buildFailureCapsule(input) {
+    const modeRequiresRestart = input.recoveryMode === "continuation" || input.recoveryMode === "new-dag";
+    const restartPhase = modeRequiresRestart
+        ? classifyRestartPhase(input.failureOwner)
+        : undefined;
+    const operationTerminal = isFrontendOperationTerminalState(input.operationState)
+        ? input.operationState
+        : undefined;
+    const invalidatedFactIds = [...new Set(input.invalidatedFactIds ?? [])].sort();
+    const reusableFactIds = [...new Set(input.reusableFactIds ?? [])].sort();
+    return failureCapsuleV1Schema.parse({
+        schemaVersion: 1,
+        parentRunId: input.parentRunId,
+        operationState: input.operationState,
+        ...(operationTerminal !== undefined ? { operationTerminal } : {}),
+        recoveryMode: input.recoveryMode,
+        ...(input.protocolFailureReason !== undefined
+            ? { protocolFailureReason: input.protocolFailureReason }
+            : {}),
+        failureOwner: input.failureOwner,
+        ...(restartPhase !== undefined ? { restartPhase } : {}),
+        ...(input.modelSuggestedRestartPhase !== undefined
+            ? { modelSuggestedRestartPhase: input.modelSuggestedRestartPhase }
+            : {}),
+        invalidatedFactIds,
+        reusableFactIds,
+        evidenceRefs: [...new Set(input.evidenceRefs ?? [])].sort(),
+        normalizedFingerprint: computeNormalizedFailureFingerprint({
+            failureOwner: input.failureOwner,
+            protocolFailureReason: input.protocolFailureReason ?? "",
+            restartPhase,
+            invalidatedFactIds,
+        }),
+    });
+}