summer-engine 2.8.2 → 3.0.0

package/dist/{lib → core}/store.js

@@ -11,6 +11,10 @@ export class SummerStoreError extends Error {
         this.name = "SummerStoreError";
     }
 }
+/** The OS error code (EACCES, ENOSPC, EROFS, ...) — the one detail a user needs to fix a store failure. */
+function errnoCode(error) {
+    return error?.code ?? "unknown";
+}
 export function getSummerDir() {
     return summerDirOverride ?? join(homedir(), ".summer");
 }
@@ -49,7 +53,7 @@ export async function ensureSummerStore() {
     catch (error) {
         if (error instanceof SummerStoreError)
             throw error;
-        throw new SummerStoreError("store_unavailable", `Cannot secure ${dir}. Recovery: make sure the directory is owned and writable by your user, then run the command again.`);
+        throw new SummerStoreError("store_unavailable", `Cannot secure ${dir} (${errnoCode(error)}). Recovery: make sure the directory is owned and writable by your user, then run the command again.`);
     }
 }
 async function assertSafeExistingFile(path) {
@@ -77,7 +81,7 @@ export async function readStoreText(name) {
     catch (error) {
         if (error instanceof SummerStoreError)
             throw error;
-        throw new SummerStoreError("store_read_failed", `Cannot read ${path}. Recovery: make sure the file is owned and readable by your user, then run the command again.`);
+        throw new SummerStoreError("store_read_failed", `Cannot read ${path} (${errnoCode(error)}). Recovery: make sure the file is owned and readable by your user, then run the command again.`);
     }
 }
 export async function readStoreJson(name) {
@@ -110,7 +114,7 @@ export async function writeStoreText(name, value) {
         await rm(temporary, { force: true }).catch(() => undefined);
         if (error instanceof SummerStoreError)
             throw error;
-        throw new SummerStoreError("store_write_failed", `Cannot write ${destination}. Recovery: make sure ${dir} is owned and writable by your user, then run the command again.`);
+        throw new SummerStoreError("store_write_failed", `Cannot write ${destination} (${errnoCode(error)}). Recovery: make sure ${dir} is owned and writable by your user, then run the command again.`);
     }
 }
 export async function writeStoreJson(name, value) {
@@ -127,8 +131,8 @@ export async function appendStoreJsonLine(name, value) {
         });
         await hardenMode(path, 0o600);
     }
-    catch {
-        throw new SummerStoreError("store_append_failed", `Cannot append to ${path}. Recovery: make sure the file is owned and writable by your user, then run the command again.`);
+    catch (error) {
+        throw new SummerStoreError("store_append_failed", `Cannot append to ${path} (${errnoCode(error)}). Recovery: make sure the file is owned and writable by your user, then run the command again.`);
     }
 }
 export async function removeStoreFile(name) {
@@ -139,7 +143,7 @@ export async function removeStoreFile(name) {
         await rm(path);
         return true;
     }
-    catch {
-        throw new SummerStoreError("store_remove_failed", `Cannot remove ${path}. Recovery: make sure the file is owned and writable by your user, then run the command again.`);
+    catch (error) {
+        throw new SummerStoreError("store_remove_failed", `Cannot remove ${path} (${errnoCode(error)}). Recovery: make sure the file is owned and writable by your user, then run the command again.`);
     }
 }

package/dist/{lib → core}/summer-compatibility.js

@@ -2,9 +2,9 @@
  * Summer CLI compatibility values.
  *
  * Keep the current technical base in one place. The project feature tag is
- * derived from it so `summer create` cannot drift to a different line. This
- * source is cross-checked against the repository compatibility contract by
- * `summer-compatibility.test.ts`.
+ * derived from it so `summer create` cannot drift to a different line. The
+ * only consumer is src/cli/commands/create.ts; create.test.ts pins the
+ * rendered "Technical base <version>" line and config/features tag.
  */
 const CURRENT_TECHNICAL_BASE_VERSION = "4.6.1";
 function featureTagFor(version) {

package/dist/{lib → core}/telemetry.js

@@ -7,7 +7,7 @@
  * ignored entirely on the CLI side.
  */
 import { getAuthToken } from "./auth.js";
-const TELEMETRY_URL = process.env.SUMMER_GATEWAY_URL?.replace(/\/+$/, "") ?? "https://www.summerengine.com";
+import { resolveGatewayUrl } from "./config.js";
 const TELEMETRY_PATH = "/api/mcp/log-local-call";
 const TIMEOUT_MS = 5000;
 let pinged = false;
@@ -30,10 +30,13 @@ export function recordMcpSession() {
             const token = await getAuthToken();
             if (!token)
                 return; // unauthenticated MCP usage is allowed; we just can't attribute it
+            // Resolved per call, not at import: the gateway the token belongs to is
+            // whatever env/config says NOW (see config.resolveGatewayUrl).
+            const gatewayUrl = await resolveGatewayUrl();
             const ctrl = new AbortController();
             const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
             try {
-                await fetch(`${TELEMETRY_URL}${TELEMETRY_PATH}`, {
+                await fetch(`${gatewayUrl}${TELEMETRY_PATH}`, {
                     method: "POST",
                     signal: ctrl.signal,
                     headers: {

package/dist/core/templates.d.ts

@@ -0,0 +1,98 @@
+export type TemplateStatus = "stable" | "preview" | "deprecated";
+export interface TemplatePin {
+    /** Clone URL of the satellite repo. */
+    repo: string;
+    /** Exact 40-hex commit. The only thing ever checked out. */
+    commit: string;
+    /** sha256 of `git ls-tree -r <commit> --format='%(objectname) %(path)'`. */
+    tree_digest: string;
+    /** Informational only — never resolved at runtime. */
+    default_branch?: string;
+}
+export interface TemplateEntry {
+    /** Library id, e.g. "template/2d-platformer". */
+    id: string;
+    /** Library slug (directory name), e.g. "2d-platformer". */
+    slug: string;
+    version: string;
+    summary: string;
+    status: TemplateStatus;
+    /** Legacy names that still resolve, e.g. "template-2d-platformer". */
+    aliases: string[];
+    systems: string[];
+    do_not_use_when: string[];
+    /** Package-root-relative manifest dir, e.g. "library/templates/2d-platformer/". */
+    path: string;
+    /** Generated in-process by the CLI; carries no pin. */
+    builtin: boolean;
+    /** Present iff `builtin` is false. */
+    pin: TemplatePin | null;
+}
+export type TemplateResolution = {
+    kind: "match";
+    entry: TemplateEntry;
+    via: "id" | "slug" | "alias" | "prefix";
+} | {
+    kind: "ambiguous";
+    candidates: TemplateEntry[];
+} | {
+    kind: "none";
+};
+/** Normalize one raw generated entry; returns null when it is not usable. */
+export declare function normalizeTemplateEntry(raw: unknown): TemplateEntry | null;
+/**
+ * Load the generated template registry (cached after first read).
+ * Throws if the file is missing or unparsable — the npm package always ships
+ * it, so a failure here means a broken build, not user error.
+ */
+export declare function getTemplateRegistry(): readonly TemplateEntry[];
+/**
+ * Resolve a user-supplied template name. Exact matches win in order
+ * id > slug > alias; otherwise a prefix of a slug or alias must identify
+ * exactly one template.
+ */
+export declare function resolveTemplate(query: string, entries: readonly TemplateEntry[]): TemplateResolution;
+/** Seconds a network git call (`fetch`) may take before it is killed.
+ *  `summer create` once hung 42 minutes inside a fetch
+ *  (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 4). */
+export declare const FETCH_TIMEOUT_ENV = "SUMMER_FETCH_TIMEOUT_S";
+export declare const DEFAULT_FETCH_TIMEOUT_S = 120;
+/** The bound in force: FETCH_TIMEOUT_ENV when it is a positive number of
+ *  seconds, else the default. */
+export declare function fetchTimeoutSeconds(env?: NodeJS.ProcessEnv): number;
+export declare class GitTimeoutError extends Error {
+    readonly repo: string;
+    readonly seconds: number;
+    constructor(repo: string, seconds: number);
+}
+/**
+ * The documented tree digest (library/templates/README.md):
+ * sha256 over the exact bytes of
+ *   git ls-tree -r <commit> --format='%(objectname) %(path)'
+ * Requires git >= 2.36 (ls-tree --format).
+ */
+export declare function computeTreeDigest(gitDir: string, commit: string): string;
+export declare class TemplateDigestMismatchError extends Error {
+    readonly entry: TemplateEntry;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(entry: TemplateEntry, expected: string, actual: string);
+}
+export interface MaterializeOptions {
+    /** Where to put the project. Must not already exist. */
+    targetDir: string;
+    /** Keep the fetched .git (detached at the pinned commit). Default: remove it. */
+    keepGit?: boolean;
+    /** Progress lines. */
+    log?: (line: string) => void;
+}
+export interface MaterializedTemplate {
+    commit: string;
+    tree_digest: string;
+}
+/**
+ * Fetch exactly the pinned commit into `targetDir`, verify the tree digest,
+ * then check the tree out. On ANY failure the target directory is removed so
+ * a half-fetched template never looks like a project.
+ */
+export declare function materializePinnedTemplate(entry: TemplateEntry, opts: MaterializeOptions): MaterializedTemplate;

package/dist/core/templates.js

@@ -0,0 +1,241 @@
+/**
+ * Template resolution — CONTRACT.md §7 ("Templates: pinned, always").
+ *
+ * `summer create <slug>` resolves a template ONLY through its library pin
+ * manifest (`library/templates/<slug>/resource.yaml`), compiled by
+ * `npm run generate:registry` into `registry/generated/templates-registry.json`
+ * (same pattern as skills-registry.json). This module:
+ *
+ *   1. loads that generated file relative to the package root,
+ *   2. resolves a user query by id, slug, alias, or unambiguous prefix,
+ *   3. materializes a pinned template: fetch exactly `commit` from `repo`,
+ *      recompute `tree_digest` with the documented formula and REFUSE on any
+ *      mismatch, then check out the pinned tree (detached unless keepGit).
+ *
+ * A default branch is never consulted. Nothing here lists a GitHub org.
+ *
+ * Built-in templates (`builtin: true`) carry no pin; the CLI generates them
+ * in-process. This module only identifies them.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "./package-root.js";
+const REGISTRY_RELPATH = join("registry", "generated", "templates-registry.json");
+let cache = null;
+function strList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function isStatus(value) {
+    return value === "stable" || value === "preview" || value === "deprecated";
+}
+/** Normalize one raw generated entry; returns null when it is not usable. */
+export function normalizeTemplateEntry(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const r = raw;
+    if (typeof r.id !== "string" || typeof r.slug !== "string" || typeof r.version !== "string")
+        return null;
+    const builtin = r.builtin === true;
+    let pin = null;
+    if (!builtin) {
+        const p = r.pin;
+        if (typeof p !== "object" || p === null)
+            return null;
+        const pr = p;
+        if (typeof pr.repo !== "string" || typeof pr.commit !== "string" || typeof pr.tree_digest !== "string") {
+            return null;
+        }
+        pin = {
+            repo: pr.repo,
+            commit: pr.commit,
+            tree_digest: pr.tree_digest,
+            ...(typeof pr.default_branch === "string" ? { default_branch: pr.default_branch } : {}),
+        };
+    }
+    return {
+        id: r.id,
+        slug: r.slug,
+        version: r.version,
+        summary: typeof r.summary === "string" ? r.summary : "",
+        status: isStatus(r.status) ? r.status : "stable",
+        aliases: strList(r.aliases),
+        systems: strList(r.systems),
+        do_not_use_when: strList(r.do_not_use_when),
+        path: typeof r.path === "string" ? r.path : `library/templates/${r.slug}/`,
+        builtin,
+        pin,
+    };
+}
+/**
+ * Load the generated template registry (cached after first read).
+ * Throws if the file is missing or unparsable — the npm package always ships
+ * it, so a failure here means a broken build, not user error.
+ */
+export function getTemplateRegistry() {
+    if (cache)
+        return cache;
+    const file = join(PACKAGE_ROOT, REGISTRY_RELPATH);
+    const json = JSON.parse(readFileSync(file, "utf-8"));
+    const raw = Array.isArray(json.templates) ? json.templates : [];
+    cache = raw.map(normalizeTemplateEntry).filter((e) => e !== null);
+    return cache;
+}
+/**
+ * Resolve a user-supplied template name. Exact matches win in order
+ * id > slug > alias; otherwise a prefix of a slug or alias must identify
+ * exactly one template.
+ */
+export function resolveTemplate(query, entries) {
+    const q = query.trim();
+    if (q === "")
+        return { kind: "none" };
+    const byId = entries.find((e) => e.id === q);
+    if (byId)
+        return { kind: "match", entry: byId, via: "id" };
+    const bySlug = entries.find((e) => e.slug === q);
+    if (bySlug)
+        return { kind: "match", entry: bySlug, via: "slug" };
+    const byAlias = entries.find((e) => e.aliases.includes(q));
+    if (byAlias)
+        return { kind: "match", entry: byAlias, via: "alias" };
+    const byPrefix = entries.filter((e) => e.slug.startsWith(q) || e.aliases.some((a) => a.startsWith(q)));
+    if (byPrefix.length === 1)
+        return { kind: "match", entry: byPrefix[0], via: "prefix" };
+    if (byPrefix.length > 1)
+        return { kind: "ambiguous", candidates: byPrefix };
+    return { kind: "none" };
+}
+// ---------- git ----------
+/** Seconds a network git call (`fetch`) may take before it is killed.
+ *  `summer create` once hung 42 minutes inside a fetch
+ *  (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 4). */
+export const FETCH_TIMEOUT_ENV = "SUMMER_FETCH_TIMEOUT_S";
+export const DEFAULT_FETCH_TIMEOUT_S = 120;
+/** The bound in force: FETCH_TIMEOUT_ENV when it is a positive number of
+ *  seconds, else the default. */
+export function fetchTimeoutSeconds(env = process.env) {
+    const raw = env[FETCH_TIMEOUT_ENV]?.trim();
+    if (!raw)
+        return DEFAULT_FETCH_TIMEOUT_S;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FETCH_TIMEOUT_S;
+}
+/** Never prompt: a private repo (one template's is) fails at once instead of
+ *  waiting on a credential prompt nobody can see. Built per call so a test can
+ *  put a fake `git` on PATH. */
+function gitEnv() {
+    return { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "" };
+}
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, env: gitEnv(), stdio: ["ignore", "pipe", "pipe"] });
+}
+/** A git call that talks to the network: bounded by fetchTimeoutSeconds(); on
+ *  expiry the child is killed (SIGTERM) and a GitTimeoutError is thrown. */
+function gitNetwork(cwd, args, repo) {
+    const seconds = fetchTimeoutSeconds();
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            env: gitEnv(),
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: seconds * 1000,
+            killSignal: "SIGTERM",
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ETIMEDOUT" || (e.killed && e.signal === "SIGTERM")) {
+            throw new GitTimeoutError(repo, seconds);
+        }
+        throw err;
+    }
+}
+export class GitTimeoutError extends Error {
+    repo;
+    seconds;
+    constructor(repo, seconds) {
+        super(`Timed out after ${seconds}s fetching ${repo}; the git process was killed.\n` +
+            "Nothing was written and the template pin is unchanged. Check that this machine can reach the repository " +
+            "(network, VPN, and access — credential prompts are disabled, so a private repository fails here too), " +
+            `then retry \`summer create\`. A slow network can raise the limit with ${FETCH_TIMEOUT_ENV}=<seconds>.`);
+        this.repo = repo;
+        this.seconds = seconds;
+        this.name = "GitTimeoutError";
+    }
+}
+function gitErrorText(err) {
+    const e = err;
+    const stderr = e.stderr ? e.stderr.toString().trim() : "";
+    return stderr || e.message || String(err);
+}
+/**
+ * The documented tree digest (library/templates/README.md):
+ * sha256 over the exact bytes of
+ *   git ls-tree -r <commit> --format='%(objectname) %(path)'
+ * Requires git >= 2.36 (ls-tree --format).
+ */
+export function computeTreeDigest(gitDir, commit) {
+    const out = git(gitDir, ["ls-tree", "-r", commit, "--format=%(objectname) %(path)"]);
+    return createHash("sha256").update(out).digest("hex");
+}
+export class TemplateDigestMismatchError extends Error {
+    entry;
+    expected;
+    actual;
+    constructor(entry, expected, actual) {
+        super(`Refusing to create project: tree digest mismatch for ${entry.id} at ${entry.pin?.commit ?? "?"}.\n` +
+            `  expected ${expected}\n` +
+            `  actual   ${actual}\n` +
+            "The pinned commit does not contain the reviewed tree. Nothing was written. " +
+            "Re-pin the template deliberately (library/templates/README.md) instead of trusting this checkout.");
+        this.entry = entry;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "TemplateDigestMismatchError";
+    }
+}
+/**
+ * Fetch exactly the pinned commit into `targetDir`, verify the tree digest,
+ * then check the tree out. On ANY failure the target directory is removed so
+ * a half-fetched template never looks like a project.
+ */
+export function materializePinnedTemplate(entry, opts) {
+    const pin = entry.pin;
+    if (!pin)
+        throw new Error(`${entry.id} is a built-in template and has no pin to materialize.`);
+    if (existsSync(opts.targetDir))
+        throw new Error(`Directory already exists: ${opts.targetDir}`);
+    const log = opts.log ?? (() => { });
+    mkdirSync(opts.targetDir, { recursive: true });
+    const cleanup = () => rmSync(opts.targetDir, { recursive: true, force: true });
+    try {
+        git(opts.targetDir, ["init", "-q"]);
+        git(opts.targetDir, ["remote", "add", "origin", pin.repo]);
+        log(`Fetching ${pin.repo} at ${pin.commit.slice(0, 12)} ...`);
+        try {
+            gitNetwork(opts.targetDir, ["fetch", "-q", "--depth", "1", "origin", pin.commit], pin.repo);
+        }
+        catch (err) {
+            if (err instanceof GitTimeoutError)
+                throw err;
+            throw new Error(`Could not fetch ${pin.repo} at ${pin.commit}.\n  ${gitErrorText(err)}\n` +
+                "Either the repository is unreachable/private from this machine, git is missing, " +
+                "or upstream history was rewritten so the pinned commit no longer exists. " +
+                "The pin only moves through a reviewed change to library/templates/.");
+        }
+        const actual = computeTreeDigest(opts.targetDir, pin.commit);
+        if (actual !== pin.tree_digest)
+            throw new TemplateDigestMismatchError(entry, pin.tree_digest, actual);
+        log(`Verified tree digest ${actual.slice(0, 12)}`);
+        git(opts.targetDir, ["checkout", "-q", pin.commit]);
+    }
+    catch (err) {
+        cleanup();
+        throw err;
+    }
+    if (!opts.keepGit)
+        rmSync(join(opts.targetDir, ".git"), { recursive: true, force: true });
+    return { commit: pin.commit, tree_digest: pin.tree_digest };
+}

package/dist/core/tool-errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Thrown-error classes the MCP layer (withEngine) can tell apart from a
+ * transport failure. Lives in core so the headless worker facade can tag its
+ * own throws without importing the MCP layer.
+ *
+ * Why: withEngine used to treat EVERY throw inside a tool closure as
+ * "transport" — reset the cached client and tell the model the mutation "may
+ * have partially applied, don't blind-retry". For an argument-validation
+ * throw (nothing was ever sent) that is false and expensive: the agent goes
+ * off to inspect the scene for a change that never happened.
+ *
+ * Tagging is by symbol rather than instanceof so a copy of this module loaded
+ * twice (dist + src in tests, or a duplicated dependency) still classifies.
+ */
+export declare const THROWN_ERROR_CLASS: unique symbol;
+export type ThrownErrorClass = "input" | "unsupported";
+/** Argument validation failed BEFORE anything was sent to the engine. */
+export declare class ToolInputError extends Error {
+    readonly [THROWN_ERROR_CLASS]: ThrownErrorClass;
+    constructor(message: string);
+}
+/** The client serving this call cannot perform the operation at all (e.g. the
+ *  headless worker facade has no equivalent). Nothing was sent or applied. */
+export declare class UnsupportedOperationError extends Error {
+    readonly [THROWN_ERROR_CLASS]: ThrownErrorClass;
+    constructor(message: string);
+}
+/** The pre-apply class of a thrown error, or null for anything unclassified
+ *  (which withEngine keeps treating as transport). */
+export declare function thrownErrorClass(err: unknown): ThrownErrorClass | null;

package/dist/core/tool-errors.js

@@ -0,0 +1,40 @@
+/**
+ * Thrown-error classes the MCP layer (withEngine) can tell apart from a
+ * transport failure. Lives in core so the headless worker facade can tag its
+ * own throws without importing the MCP layer.
+ *
+ * Why: withEngine used to treat EVERY throw inside a tool closure as
+ * "transport" — reset the cached client and tell the model the mutation "may
+ * have partially applied, don't blind-retry". For an argument-validation
+ * throw (nothing was ever sent) that is false and expensive: the agent goes
+ * off to inspect the scene for a change that never happened.
+ *
+ * Tagging is by symbol rather than instanceof so a copy of this module loaded
+ * twice (dist + src in tests, or a duplicated dependency) still classifies.
+ */
+export const THROWN_ERROR_CLASS = Symbol.for("summer.thrownErrorClass");
+/** Argument validation failed BEFORE anything was sent to the engine. */
+export class ToolInputError extends Error {
+    [THROWN_ERROR_CLASS] = "input";
+    constructor(message) {
+        super(message);
+        this.name = "ToolInputError";
+    }
+}
+/** The client serving this call cannot perform the operation at all (e.g. the
+ *  headless worker facade has no equivalent). Nothing was sent or applied. */
+export class UnsupportedOperationError extends Error {
+    [THROWN_ERROR_CLASS] = "unsupported";
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedOperationError";
+    }
+}
+/** The pre-apply class of a thrown error, or null for anything unclassified
+ *  (which withEngine keeps treating as transport). */
+export function thrownErrorClass(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const tag = err[THROWN_ERROR_CLASS];
+    return tag === "input" || tag === "unsupported" ? tag : null;
+}

package/dist/core/trajectory.d.ts

@@ -0,0 +1,80 @@
+export declare const TRAJECTORY_EVAL_ENV = "SUMMER_TRAJECTORY_EVAL";
+export declare function getTrajectoryDir(): string | null;
+/** True only when capture is on AND the eval flag is set — the flag alone
+ *  does nothing (design rule: eval mode never changes the default). */
+export declare function isTrajectoryEvalMode(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Keep the SHAPE of a tool call's arguments, drop the bodies: any string over
+ * REDACT_STRING_LIMIT chars (script sources, file contents, notes pasted in)
+ * becomes a "[redacted N chars]" marker. Objects/arrays are walked with depth
+ * and entry caps so a pathological payload cannot balloon the record.
+ * Exported for unit tests.
+ */
+export declare function redactTrajectoryArgs(value: unknown, depth?: number): unknown;
+/** The complete set of result scalars the full stream may carry. Anything
+ *  else in a result body stays out — the stream records that a perception
+ *  call happened and what it confessed, never what it saw. */
+export declare const TRAJECTORY_RESULT_FIELD_ALLOWLIST: readonly string[];
+export interface TrajectoryMediaSummary {
+    mime: string;
+    bytes: number;
+    sha256: string;
+}
+export interface TrajectoryResultSummary {
+    ok: boolean;
+    terminalState?: string;
+    failureReason?: string;
+    errorClass?: string;
+    /** Top-level keys of the result payload (≤ FULL_MAX_KEYS). */
+    keys: string[];
+    /** Allowlisted scalars found at the payload top level or inside its first
+     *  results[] entry (the engine op dict), plus derived counts. */
+    fields: Record<string, string | number | boolean>;
+    /** Image/audio blocks by hash — never inline. */
+    media: TrajectoryMediaSummary[];
+}
+/** Bounded, allowlisted summary of a tool result. Exported for unit tests and
+ *  for the outcome-eval runner, which records replayed calls through the same
+ *  function so a replay run yields the same stream shape a live session does. */
+export declare function summarizeToolResult(result: unknown, classifiers: {
+    ok: boolean;
+    terminalState?: string;
+    failureReason?: string;
+    errorClass?: string;
+}): TrajectoryResultSummary;
+export interface TrajectoryToolCall {
+    tool: string;
+    /** The tool's parsed arguments; `null` means the tool takes no input
+     *  schema (recorded as argsRedacted: null, never as the SDK's request extra). */
+    args?: unknown;
+    isError?: boolean;
+    terminalState?: string;
+    errorClass?: string;
+    failureReason?: string;
+    /** Message of a handler THROW (as opposed to an isError result). Recorded
+     *  with ok:false, errorClass "exception". Redacted like any other string. */
+    exception?: string;
+    durationMs?: number;
+    /** The tool's raw result (MCP content envelope or CLI-face object). Read
+     *  ONLY in eval mode, and only through summarizeToolResult — the redacted
+     *  default stream never sees it. */
+    result?: unknown;
+}
+/**
+ * Does a server.tool(...) registration carry an input schema? The MCP SDK
+ * accepts tool(name, description?, paramsSchema?, annotations?, cb): when a
+ * paramsSchema is present the callback receives (args, extra); when it is
+ * absent the callback receives (extra) ONLY — and recording extra as the
+ * tool's args would write {signal, requestId, ...} junk into the stream. A
+ * paramsSchema is a zod raw shape (record of zod schemas, or {} for "no
+ * parameters") or a zod object instance; a flat object of primitives is
+ * ToolAnnotations. Exported for unit tests.
+ */
+export declare function registrationHasInputSchema(registrationArgs: readonly unknown[]): boolean;
+/** The args to record for one handler invocation: the parsed args when the
+ *  tool has an input schema, else null (the SDK passes only `extra`). */
+export declare function trajectoryArgsFor(hasInputSchema: boolean, handlerArgs: readonly unknown[]): unknown | null;
+/** One line per MCP tool call. No-op (false) when capture is off. In eval
+ *  mode a second, unredacted line goes to trajectory.full.jsonl; its failure
+ *  never affects the return value (the redacted stream is the contract). */
+export declare function recordToolCall(call: TrajectoryToolCall): boolean;