loopforge 3.9.2 → 4.0.7

package/dist/mcp/submission-handle.js

@@ -0,0 +1,173 @@
+/** v4.0.0: the ONE submission-handle projection and validator.
+ *
+ *  A handle bundles the three identities a held-round call needs. It is derived
+ *  from the persisted session snapshot on every response and is never written
+ *  to durable state. This module is deliberately free of I/O and of the
+ *  `McpSession` import: `round-lifecycle.ts` needs the factory, so importing
+ *  that module here would create a cycle.
+ */
+/** THE held-prompt predicate. A snapshot is held only when it names the current
+ *  round and the exact prompted attempt the artifact was rendered for. A
+ *  committed/terminated/stopped/retrying snapshot must never expose a handle:
+ *  returning a stale prompt as "held" is the failure mode this predicate
+ *  closes. */
+export function heldPromptSnapshot(session) {
+    if (!session || session.status === "stopped")
+        return null;
+    const snapshot = session.roundSnapshot;
+    if (!snapshot)
+        return null;
+    if (snapshot.kind !== "evaluation")
+        return null;
+    if (snapshot.round !== session.currentRound)
+        return null;
+    if (snapshot.phase !== "prompted")
+        return null;
+    const artifact = snapshot.promptArtifact;
+    if (!artifact)
+        return null;
+    if (artifact.roundId !== snapshot.roundId)
+        return null;
+    if (artifact.round !== snapshot.round)
+        return null;
+    if (artifact.attempt !== snapshot.attempt)
+        return null;
+    if (typeof artifact.renderedPrompt !== "string" || artifact.renderedPrompt.length === 0) {
+        return null;
+    }
+    return snapshot;
+}
+/** Derive the handle from the held snapshot. Never recomputes the transaction
+ *  id (the snapshot's identity is the authority), never reads the vault, and
+ *  never mutates the session. */
+export function makeSubmissionHandle(session) {
+    const snapshot = heldPromptSnapshot(session);
+    if (!snapshot || !session)
+        return null;
+    const { roundId, transactionId } = snapshot;
+    if (typeof session.sessionId !== "string" || session.sessionId.length === 0)
+        return null;
+    if (typeof roundId !== "string" || roundId.length === 0)
+        return null;
+    if (typeof transactionId !== "string" || transactionId.length === 0)
+        return null;
+    return {
+        sessionId: session.sessionId,
+        roundId,
+        transactionId,
+    };
+}
+/** Strict shape parsing: a plain object with exactly the three non-empty
+ *  string fields. No trimming, case folding, prefix matching, or defaults. */
+export function parseSubmissionHandle(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    const keys = Object.keys(record);
+    if (keys.length !== 3)
+        return null;
+    if (!keys.includes("sessionId") || !keys.includes("roundId") ||
+        !keys.includes("transactionId")) {
+        return null;
+    }
+    const { sessionId, roundId, transactionId } = record;
+    if (typeof sessionId !== "string" || sessionId.length === 0)
+        return null;
+    if (typeof roundId !== "string" || roundId.length === 0)
+        return null;
+    if (typeof transactionId !== "string" || transactionId.length === 0)
+        return null;
+    return { sessionId, roundId, transactionId };
+}
+/** Exact comparison against the held snapshot. The caller resolves the session
+ *  by `handle.sessionId`; this function owns every field comparison so no
+ *  second anchor rule can appear in the lifecycle or transport. */
+export function validateSubmissionHandle(raw, session) {
+    const parsed = parseSubmissionHandle(raw);
+    if (!parsed) {
+        return {
+            ok: false,
+            code: "submission_handle_required",
+            reason: "shape",
+            mismatched: [],
+            current: null,
+            detail: "submissionHandle must be an object with exactly sessionId, roundId, " +
+                "and transactionId as non-empty strings.",
+        };
+    }
+    if (!session) {
+        return {
+            ok: false,
+            code: "session_not_found",
+            reason: "session",
+            mismatched: [],
+            current: null,
+            detail: `No session exists for sessionId "${parsed.sessionId}". Call ` +
+                `loopforge_status with view="all" to find the loopId; if the held ` +
+                `prompt is still in context, call loopforge_status with that loopId ` +
+                `to fetch the current handle; otherwise call loopforge_resume with it.`,
+        };
+    }
+    const current = makeSubmissionHandle(session);
+    if (!current) {
+        return {
+            ok: false,
+            code: "submission_handle_mismatch",
+            reason: "no_held_prompt",
+            mismatched: [],
+            current: null,
+            detail: "No held prompt exists for this session. Call loopforge_resume with " +
+                "the loopId to recover the current prompt; loopforge_status is " +
+                "read-only and cannot create one.",
+        };
+    }
+    const mismatched = [];
+    if (parsed.sessionId !== current.sessionId)
+        mismatched.push("sessionId");
+    if (parsed.roundId !== current.roundId)
+        mismatched.push("roundId");
+    if (parsed.transactionId !== current.transactionId)
+        mismatched.push("transactionId");
+    if (mismatched.length === 0) {
+        const snapshot = heldPromptSnapshot(session);
+        // `current` is non-null only when the predicate holds; the assertion is
+        // local and keeps the success branch total.
+        if (!snapshot) {
+            return {
+                ok: false,
+                code: "submission_handle_mismatch",
+                reason: "no_held_prompt",
+                mismatched: [],
+                current: null,
+                detail: "No held prompt exists for this session. Call loopforge_resume with " +
+                    "the loopId to recover the current prompt; loopforge_status is " +
+                    "read-only and cannot create one.",
+            };
+        }
+        return { ok: true, handle: current, snapshot };
+    }
+    const reason = mismatched.length > 1
+        ? "attempt"
+        : mismatched[0] === "sessionId"
+            ? "session"
+            : mismatched[0] === "roundId"
+                ? "round"
+                : "transaction";
+    return {
+        ok: false,
+        code: "submission_handle_mismatch",
+        reason,
+        mismatched,
+        current,
+        detail: "submissionHandle does not match the current held attempt " +
+            `(mismatched: ${mismatched.join(", ")}). Use the submissionHandle ` +
+            "returned with the current prompt; do not reconstruct it.",
+    };
+}
+/** The one deterministic warning used whenever a stale handle returns the
+ *  held prompt. It names no ids and never changes with the attempt. */
+export function staleHandleWarning() {
+    return ("Submitted submissionHandle does not match the current held attempt — " +
+        "returning the current prompt. Use the submissionHandle returned with it.");
+}
+//# sourceMappingURL=submission-handle.js.map

package/dist/mcp/submission-handle.js.map

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

package/dist/mcp/tools.d.ts

@@ -1,16 +1,21 @@
 /** LoopForge MCP — Tool definitions and handlers.
  *
- * 9 tools: start, next, status, stop, pause, resume, replay,
- *          gate_check, gate_resolve.
- * status is the unified inspection tool (view=session|loop|all|audit).
+ * 10 tools: start, next, status, stop, pause, resume, replay,
+ *           checkpoint, gate_check, gate_resolve.
+ * status is the unified inspection tool (view=session|loop|all|audit|explain).
  * Each handler receives SessionManager + parsed input, returns the output object.
  */
 import type { SessionManager } from "./session.js";
+/** The closed argument set for `loopforge_start`.
+ *
+ *  The handler's unknown-argument guard reads this list; `schema-sync.test`
+ *  asserts that the advertised tool schema exposes exactly the same keys. A
+ *  field removed from the protocol (for example `domain` in 4.0.1) must not
+ *  survive in only one of them: the schema says what clients may send, and
+ *  the guard makes a stale caller fail loudly instead of silently dropping
+ *  the field. */
+export declare const START_INPUT_KEYS: readonly ["task", "loopId", "maxRounds", "planSource", "constraints", "criteria"];
 type JsonSchema = Record<string, unknown>;
-/** Declared structured-output contracts for every tool. The MCP server
- *  validates each handler's output against these before returning it —
- *  a mismatch is a contract bug, surfaced as a JSON-RPC error instead of
- *  silently shipping an output that violates the declared schema. */
 export declare const TOOL_OUTPUT_SCHEMAS: Record<string, JsonSchema>;
 /** MCP tool contracts include strict input and structured output schemas. */
 export declare const TOOL_SCHEMAS: ({
@@ -53,6 +58,11 @@ export declare const TOOL_SCHEMAS: ({
     outputSchema: JsonSchema;
     name: string;
     description: string;
+} | {
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    name: string;
+    description: string;
 })[];
 export declare class ToolInputValidationError extends Error {
     constructor(message: string);

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAkgB/D,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA6C1C;;;qEAGqE;AACrE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAkG1D,CAAC;AAqDF,6EAA6E;AAC7E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAOtB,CAAC;AAEJ,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AA8ED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAIN;AAED;;;;;2DAK2D;AAC3D,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAoBN;AAED;;;4CAG4C;AAC5C,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAIN;AAMD,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAapH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAiZrD,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAkE/D;;;;;;;iBAOiB;AACjB,eAAO,MAAM,gBAAgB,mFAOnB,CAAC;AAunBX,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAiI1C,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAiI1D,CAAC;AA+CF,6EAA6E;AAC7E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAOtB,CAAC;AAEJ,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AA8ED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAIN;AAED;;;;;2DAK2D;AAC3D,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAoBN;AAED;;;4CAG4C;AAC5C,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAIN;AAMD,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AA6CpH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CA4nBrD,CAAC"}