summer-engine 2.8.2 → 3.1.0

package/dist/core/skills-registry.js

@@ -0,0 +1,106 @@
+/**
+ * Skill registry — loaded from the generated registry (CONTRACT.md §6, §12).
+ *
+ * The single source of truth for installable skills is the library:
+ * `library/skills/<slug>/` (resource.yaml + SKILL.md), compiled by
+ * `npm run generate:registry` into `registry/generated/skills-registry.json`.
+ * This module reads that generated file at runtime; nothing here is
+ * hand-maintained per skill anymore. The old hand-written SKILL_REGISTRY
+ * (skills/<category>/<name> paths) was deleted at the v3 cutover.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "./package-root.js";
+/**
+ * Clients `summer skills install --agent` accepts: "summer" (the toolkit's
+ * own ~/.summer/skills) plus every agent in the installer's agent table that
+ * has a skills or rules folder. core/ cannot import installer/, so this list
+ * is written out; agent-table.test.ts fails if the two drift.
+ */
+export const AGENT_CLIENTS = [
+    "summer",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "antigravity",
+    "gemini",
+    "cline",
+    "cline-cli",
+    "roo-code",
+    "kilo-code",
+    "github-copilot",
+    "vscode-copilot",
+    "opencode",
+    "zed",
+    "kiro",
+    "goose",
+    "hermes",
+    "qwen-code",
+    "kimi-code",
+    "crush",
+    "amp",
+    "factory",
+    "warp",
+    "rovo-dev",
+    "qoder",
+    "grok-build",
+    "mistral-vibe",
+];
+const packageRoot = PACKAGE_ROOT;
+const REGISTRY_RELPATH = join("registry", "generated", "skills-registry.json");
+let cache = null;
+/**
+ * Load the generated skill registry (cached after first read).
+ * Throws if the generated file is missing or unparsable — the npm package
+ * always ships it, so a failure here means a broken build, not user error.
+ */
+export function getSkillRegistry() {
+    if (cache)
+        return cache;
+    const file = join(packageRoot, REGISTRY_RELPATH);
+    cache = parseSkillRegistry(JSON.parse(readFileSync(file, "utf-8")));
+    return cache;
+}
+/** Shape-tolerant parse of skills-registry.json. Exported for unit tests. */
+export function parseSkillRegistry(json) {
+    const raw = (json ?? {});
+    const skills = Array.isArray(raw.skills) ? raw.skills : [];
+    return skills
+        .filter((s) => typeof s.id === "string" &&
+        typeof s.name === "string" &&
+        typeof s.path === "string")
+        .map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: typeof s.description === "string" ? s.description : "",
+        recommended: s.recommended === true,
+        status: s.status === "preview" || s.status === "deprecated" ? s.status : "stable",
+        path: s.path,
+        domains: Array.isArray(s.domains) ? s.domains.filter((d) => typeof d === "string") : [],
+    }));
+}
+/**
+ * The one bulk-install rule (`skills install --all/--recommended` and
+ * `summer setup` both use it): `stable` and `preview` skills install —
+ * preview is a label ("not yet exercised in-engine by the Summer team"),
+ * carried in each skill's own guidance, not a reason to hide contributed work;
+ * `deprecated` never installs in bulk. `stableOnly` opts out of preview.
+ * The counts let the caller say how many preview skills it installed (or, with
+ * stableOnly, left out) instead of printing a bare total.
+ */
+export function selectSkillsForBulkInstall(skills, options) {
+    const candidates = options.recommended ? skills.filter((skill) => skill.recommended) : [...skills];
+    const stableOnly = options.stableOnly === true;
+    const selected = candidates.filter((skill) => skill.status === "stable" || (!stableOnly && skill.status === "preview"));
+    const preview = candidates.filter((skill) => skill.status === "preview").length;
+    return {
+        selected,
+        previewIncluded: stableOnly ? 0 : preview,
+        previewSkipped: stableOnly ? preview : 0,
+    };
+}
+/** Absolute directory of a skill's library files (contains SKILL.md). */
+export function resolveSkillDir(entry) {
+    return join(packageRoot, entry.path);
+}

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;
+}