summer-engine 3.8.0 → 4.2.0

package/dist/core/library-search.js

@@ -27,6 +27,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
+import { summerRequestHeaders } from "./agent-host.js";
 import { getAuthToken } from "./auth.js";
 import { resolveGatewayUrl } from "./config.js";
 import { EMBED_PATH, EMBEDDINGS_FILE, cosineSimilarity, createEmbedProvider, decodeVector, parseEmbeddingsFile, reciprocalRankFusion, } from "./embeddings.js";
@@ -167,7 +168,7 @@ export async function embedQueryWithConfiguredProvider(query, env = process.env)
         catch {
             token = null;
         }
-        const provider = createEmbedProvider({ url, token, timeoutMs: QUERY_EMBED_TIMEOUT_MS });
+        const provider = createEmbedProvider({ url, token, timeoutMs: QUERY_EMBED_TIMEOUT_MS, headers: summerRequestHeaders() });
         return (await provider(query)).vector;
     }
     catch {

package/dist/core/oauth.js

@@ -115,6 +115,10 @@ async function postForm(deps, url, form) {
     const body = (json && typeof json === "object" ? json : {});
     if (!response.ok) {
         const reason = typeof body.error === "string" ? body.error : `http_${response.status}`;
+        // A 5xx is the sign-in server failing, not the sign-in being wrong.
+        if (response.status >= 500) {
+            throw new OAuthError("oauth_server_failed", `The sign-in server failed (${reason}).`, "Recovery: try again in a minute.");
+        }
         throw new OAuthError(reason === "invalid_grant" ? "oauth_grant_invalid" : "oauth_token_refused", `The sign-in server refused the token request (${reason}).`, 'Recovery: run "summer login --store --force" and approve access again.');
     }
     return body;

package/dist/core/ops/areas.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Where operations live and run, the part scripts/ needs too. No imports:
+ * scripts/validate-library loads this file as plain TypeScript to write the
+ * shell command of each tool a skill names.
+ */
+/**
+ * Areas with operations today: each is one `summer <area> <action>` command
+ * (src/cli/commands/ops.ts). CLI command words stay out of this list.
+ */
+export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account"];
+export declare function isLocalOp(op: string): boolean;

package/dist/core/ops/areas.js

@@ -0,0 +1,24 @@
+/**
+ * Where operations live and run, the part scripts/ needs too. No imports:
+ * scripts/validate-library loads this file as plain TypeScript to write the
+ * shell command of each tool a skill names.
+ */
+/**
+ * Areas with operations today: each is one `summer <area> <action>` command
+ * (src/cli/commands/ops.ts). CLI command words stay out of this list.
+ */
+export const CLI_AREAS = [
+    "team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing",
+    "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories",
+    "plugins", "engine", "account",
+];
+/**
+ * Operations that run in this package: everything in `engine`, the library
+ * (`docs`, apart from the Studio workflows, which are cloud), opening a
+ * page or an editor surface, docking an App in the editor, and uploading a
+ * local export. Everything else runs on the hosted server.
+ */
+const LOCAL_OPS = new Set(["docs.search", "docs.read", "docs.feedback", "docs.plan", "docs.engine_api", "studio.open", "apps.dock", "apps.publish_folder", "store.upload_file"]);
+export function isLocalOp(op) {
+    return op.startsWith("engine.") || LOCAL_OPS.has(op);
+}

package/dist/core/ops/catalog.d.ts

@@ -0,0 +1,45 @@
+import { type Approval, type Effect, type Provider } from "./contract.js";
+/**
+ * One searchable row per operation, the same shape the hosted server's
+ * summer_search answers with, so local and cloud hits merge into one list.
+ */
+export interface CatalogEntry {
+    name: string;
+    title: string;
+    summary: string;
+    effect: Effect;
+    approval: Approval;
+    provider: Provider;
+    status: "stable" | "preview" | "deprecated";
+    available: boolean;
+    /** The MCP tool that runs it directly in this session, when there is one. */
+    mcpTool?: string;
+    tags?: string[];
+    legacy?: string[];
+    /** The exact input JSON Schema (search results and describe carry it). */
+    input?: Record<string, unknown>;
+    /** A cloud operation listed from the shipped catalog while no one is signed in: it runs after `summer login`. */
+    needsSignIn?: true;
+    /** Search words only, never printed: the library's topics for docs.search ("add multiplayer" is a how-to). */
+    topics?: string[];
+}
+/**
+ * The operations this package runs (engine and local), from the shipped
+ * library index and legacy-names.json. Their MCP tool is the 3.x name the
+ * local server registers (engine tools keep their names in 4.0), except the
+ * operations split out of a mixed 3.x tool (engine.ts), which are their own.
+ */
+export declare function localEntries(): CatalogEntry[];
+/** The input JSON Schema of a local operation, from its library descriptor (a split operation: cut from its tool's). */
+export declare function localInputSchema(op: string): Record<string, unknown> | null;
+/**
+ * A local operation in the contract's wire form (registry/schemas/operation.schema.json):
+ * what ops.describe answers and what the contract test validates.
+ */
+export declare function localWireForm(op: string): Record<string, unknown> | null;
+/**
+ * The first problem a JSON Schema's top level finds in an input: a missing
+ * required field or, when the schema is closed, an unknown one. Null when
+ * there is none (deeper checks are the tool's own).
+ */
+export declare function missingInput(schema: Record<string, unknown> | null, input: Record<string, unknown>): string | null;

package/dist/core/ops/catalog.js

@@ -0,0 +1,157 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { loadLibraryIndex } from "../library-search.js";
+import { PACKAGE_ROOT } from "../package-root.js";
+import { CONTRACT_VERSION, isLocalOp, legacyNames, LOCAL_RUNNERS, mcpNameOf, MIN_APPROVAL } from "./contract.js";
+import { ENGINE_SPLIT_OPS, engineOpDef, isSplitOp, splitInputSchema } from "./engine.js";
+import { shippedTitle } from "./public-catalog.js";
+/** A local tool's effect from its registry authority: scene edits and project files are writes. */
+function effectOf(authority) {
+    if (authority?.publish)
+        return "publish";
+    if (authority?.editor_mutation || authority?.filesystem || authority?.credentials)
+        return "write";
+    return "read";
+}
+const titleOf = (summary, op) => {
+    const sentence = summary.split(/(?<=\.)\s/)[0]?.replace(/\.$/, "") ?? "";
+    return sentence && sentence.length <= 60 ? sentence : op.replace(/^[a-z]+\./, "").replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+};
+let entriesCache = null;
+function entryFor(op, toolName, tool, legacy) {
+    // Engine operations carry their own title, summary and effect (engine.ts);
+    // other local operations fall back to the descriptor.
+    const def = engineOpDef(op);
+    const effect = def?.effect ?? effectOf(tool.authority);
+    const summary = def?.summary ?? (tool.summary ?? "").slice(0, 300);
+    return {
+        name: op,
+        // The hosted catalog's title when it has the op too (docs.search: "Search Summer docs", not "Search").
+        title: def?.title ?? shippedTitle(op) ?? titleOf(summary, op),
+        summary,
+        effect,
+        approval: MIN_APPROVAL[effect],
+        provider: op.startsWith("engine.") ? "engine" : "local",
+        status: tool.status === "preview" ? "preview" : "stable",
+        available: true,
+        // A split operation is its own tool; every other one runs under its 3.x name.
+        mcpTool: isSplitOp(op) ? mcpNameOf(op) : toolName,
+        tags: [...(tool.use_when ?? []), ...(tool.facets?.domains ?? [])],
+        legacy: [legacy],
+    };
+}
+/**
+ * The operations this package runs (engine and local), from the shipped
+ * library index and legacy-names.json. Their MCP tool is the 3.x name the
+ * local server registers (engine tools keep their names in 4.0), except the
+ * operations split out of a mixed 3.x tool (engine.ts), which are their own.
+ */
+export function localEntries() {
+    if (entriesCache)
+        return entriesCache;
+    const tools = new Map(loadLibraryIndex().filter((entry) => entry.kind === "tool" && entry.mcp_tool_name).map((entry) => [entry.mcp_tool_name, entry]));
+    const out = new Map();
+    // The tool an operation was renamed from comes before the tools merged into it;
+    // then the local operations a 3.x tool runs although its 3.x name maps to a cloud one.
+    const rows = [
+        ...Object.entries(legacyNames()).sort(([, a], [, b]) => Number(a.kind === "merge") - Number(b.kind === "merge")),
+        ...Object.entries(LOCAL_RUNNERS).map(([op, name]) => [name, { op }]),
+    ];
+    for (const [name, row] of rows) {
+        if (!isLocalOp(row.op) || out.has(row.op))
+            continue;
+        const toolName = name.split("#")[0];
+        const tool = tools.get(toolName);
+        if (!tool)
+            continue;
+        if (name.includes("#") && !isSplitOp(row.op))
+            continue;
+        out.set(row.op, entryFor(row.op, toolName, tool, name));
+    }
+    const docsSearch = out.get("docs.search");
+    if (docsSearch)
+        out.set("docs.search", { ...docsSearch, topics: libraryTopics() });
+    entriesCache = [...out.values()];
+    return entriesCache;
+}
+/** The words of every skill, template and example slug (multiplayer, fps, lighting...): what the library teaches. */
+function libraryTopics() {
+    const slugs = loadLibraryIndex()
+        .filter((entry) => entry.kind !== "tool" && entry.kind !== "reference")
+        .flatMap((entry) => entry.id.replace(/^[a-z]+\//, "").split("-"));
+    return [...new Set(slugs)].filter((word) => word.length > 2 && !/^\d/.test(word));
+}
+function descriptorSchema(toolName) {
+    const record = loadLibraryIndex().find((candidate) => candidate.kind === "tool" && candidate.mcp_tool_name === toolName);
+    const slug = record?.id.replace(/^tool\//, "");
+    if (!slug)
+        return null;
+    try {
+        const descriptor = parseYaml(readFileSync(join(PACKAGE_ROOT, "library", "tools", slug, "resource.yaml"), "utf8"));
+        return descriptor.input_schema ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The input JSON Schema of a local operation, from its library descriptor (a split operation: cut from its tool's). */
+export function localInputSchema(op) {
+    const split = ENGINE_SPLIT_OPS[op];
+    if (split)
+        return splitInputSchema(split, descriptorSchema(split.tool));
+    const toolName = localEntries().find((candidate) => candidate.name === op)?.mcpTool;
+    return toolName ? descriptorSchema(toolName) : null;
+}
+/**
+ * A local operation in the contract's wire form (registry/schemas/operation.schema.json):
+ * what ops.describe answers and what the contract test validates.
+ */
+export function localWireForm(op) {
+    const entry = localEntries().find((candidate) => candidate.name === op);
+    if (!entry)
+        return null;
+    const def = engineOpDef(op);
+    const legacy = Object.entries(legacyNames())
+        .filter(([, row]) => row.op === op)
+        .map(([name]) => name)
+        .sort();
+    return {
+        contract: CONTRACT_VERSION,
+        name: op,
+        title: entry.title,
+        summary: entry.summary,
+        effect: entry.effect,
+        approval: entry.approval,
+        provider: entry.provider,
+        auth: def?.auth ?? "none",
+        input: localInputSchema(op) ?? { type: "object" },
+        output: { type: "object" },
+        ...(legacy.length ? { legacy } : {}),
+        ...(entry.mcpTool && entry.mcpTool !== mcpNameOf(op) ? { mcpName: entry.mcpTool } : {}),
+        status: entry.status,
+        since: "4.0",
+        ...(entry.tags?.length ? { tags: entry.tags } : {}),
+        examples: def ? [def.example] : [{ input: {}, note: entry.title }],
+    };
+}
+/**
+ * The first problem a JSON Schema's top level finds in an input: a missing
+ * required field or, when the schema is closed, an unknown one. Null when
+ * there is none (deeper checks are the tool's own).
+ */
+export function missingInput(schema, input) {
+    if (!schema)
+        return null;
+    const properties = (schema.properties ?? {});
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    const absent = required.find((field) => input[field] === undefined);
+    if (absent)
+        return `${absent}: required.`;
+    if (schema.additionalProperties === false) {
+        const unknown = Object.keys(input).find((field) => !(field in properties));
+        if (unknown)
+            return `${unknown}: not a field of this operation.`;
+    }
+    return null;
+}

package/dist/core/ops/cloud.d.ts

@@ -0,0 +1,64 @@
+import { type HostedConnectDependencies } from "../hosted-mcp.js";
+import { type CatalogEntry } from "./catalog.js";
+import { type Answer } from "./contract.js";
+/**
+ * The hosted Summer server's v4 surface: the same address with `?surface=v4`
+ * (it keeps serving 3.x tools to every request that does not ask). Cloud
+ * operations run there with the person's sign-in (summer login). The assets
+ * profile also asks for its own direct tools (`profile=assets`: the asset
+ * reads and generators, jobs and whoami); every other profile gets the
+ * hosted set.
+ */
+export declare function withV4Surface(url: string, profile?: string): string;
+/** Where a profile's v4 session mounts the hosted server. */
+export declare function v4HostedUrl(profile?: string): () => string;
+export declare const v4HostedDependencies: HostedConnectDependencies;
+/**
+ * One call to a tool on the hosted v4 surface (the CLI's path; the MCP uses
+ * its mounted client). A failure before the call is sent is an OAuthError
+ * (sign-in) or a HostedUnreachableError; one after it may have run.
+ */
+export declare function callHostedV4(name: string, args: Record<string, unknown>, deps?: HostedConnectDependencies): Promise<Record<string, unknown>>;
+/** True for operations that only read (`games.list`, `jobs.wait`, `whoami`). */
+export declare function isReadOp(op: string): boolean;
+/**
+ * The one answer for a hosted call that threw, decided by what is known to
+ * have happened:
+ * - a sign-in problem (an OAuthError, a 401) is not_signed_in; an account
+ *   the server refuses (403) is forbidden;
+ * - nothing sent (never connected, connection refused, a 503 or another 4xx
+ *   the server answers before it runs anything) is unavailable;
+ * - a call cut off after it was sent may have run: outcome_unknown, retried
+ *   only with the same idempotencyKey, else checked first. A read or a dry
+ *   run changes nothing, so a cut-off one is unavailable.
+ */
+export declare function hostedCallFailure(error: unknown, call: {
+    op: string;
+    dryRun?: boolean;
+    idempotencyKey?: string;
+    read?: boolean;
+}): Answer;
+/** The answer a hosted v4 tool result carries (its JSON text), or the one error shape. */
+export declare function answerOfHosted(result: Record<string, unknown>): Answer;
+/** Runs a tool on the hosted v4 surface: the MCP's mounted client or the CLI's one-shot call. */
+export type HostedCall = (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * ops.describe of a cloud operation when Summer's server could not answer it
+ * (no sign-in, no network): the operation from the shipped catalog, with a
+ * warning. Null when the catalog has no such operation; the failure stands.
+ */
+export declare function describeFromShipped(name: string, failure: Answer): Answer | null;
+/**
+ * One ranked list of local and cloud operations for a plain-words query.
+ * Every cloud operation comes from the shipped catalog (public-catalog.ts),
+ * so search finds it signed out, marked needsSignIn; signed in, the server's
+ * own search lays its live rows over the shipped ones (and adds newer
+ * operations). Local hits carry their input schema from the library descriptor.
+ */
+export declare function searchEverywhere(query: string, filters: {
+    area?: string;
+    limit: number;
+}, call: HostedCall, isDirect?: (toolName: string) => boolean): Promise<{
+    items: CatalogEntry[];
+    warning: string | null;
+}>;

package/dist/core/ops/cloud.js

@@ -0,0 +1,198 @@
+import { defaultHostedConnectDependencies, hostedConnectFailure, HostedUnreachableError, httpStatusOf } from "../hosted-mcp.js";
+import { OAuthError, resolveMcpResourceUrl } from "../oauth.js";
+import { localEntries, localInputSchema } from "./catalog.js";
+import { errorAnswer, isLocalOp, resolveOpName } from "./contract.js";
+import { shippedCloudEntries, shippedWireForm } from "./public-catalog.js";
+import { withOutField } from "./save-files.js";
+import { searchEntries } from "./search.js";
+/**
+ * The hosted Summer server's v4 surface: the same address with `?surface=v4`
+ * (it keeps serving 3.x tools to every request that does not ask). Cloud
+ * operations run there with the person's sign-in (summer login). The assets
+ * profile also asks for its own direct tools (`profile=assets`: the asset
+ * reads and generators, jobs and whoami); every other profile gets the
+ * hosted set.
+ */
+export function withV4Surface(url, profile) {
+    const parsed = new URL(url);
+    parsed.searchParams.set("surface", "v4");
+    if (profile === "assets")
+        parsed.searchParams.set("profile", "assets");
+    return parsed.href;
+}
+/** Where a profile's v4 session mounts the hosted server. */
+export function v4HostedUrl(profile) {
+    return () => withV4Surface(resolveMcpResourceUrl(), profile);
+}
+export const v4HostedDependencies = {
+    ...defaultHostedConnectDependencies,
+    url: v4HostedUrl(),
+};
+/**
+ * One call to a tool on the hosted v4 surface (the CLI's path; the MCP uses
+ * its mounted client). A failure before the call is sent is an OAuthError
+ * (sign-in) or a HostedUnreachableError; one after it may have run.
+ */
+export async function callHostedV4(name, args, deps = v4HostedDependencies) {
+    let client;
+    try {
+        const url = deps.url();
+        await deps.token();
+        client = await deps.connect(url, deps.token);
+    }
+    catch (error) {
+        throw hostedConnectFailure(error, "Recovery: check the network and try again.");
+    }
+    try {
+        return await client.callTool({ name, arguments: args });
+    }
+    finally {
+        await client.close?.().catch(() => undefined);
+    }
+}
+/** OAuth failures that mean a server did not answer, not that the person must sign in again. */
+const OAUTH_UNREACHABLE = new Set(["oauth_network_failed", "oauth_discovery_failed", "oauth_server_failed"]);
+/** Connection errors raised before a request is written: nothing reached the server. */
+const NOT_SENT_CAUSES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
+/** Actions that only read; a cut-off read can simply run again. */
+const READ_ACTIONS = new Set(["list", "get", "search", "describe", "status", "wait"]);
+/** True for operations that only read (`games.list`, `jobs.wait`, `whoami`). */
+export function isReadOp(op) {
+    return op === "whoami" || READ_ACTIONS.has(op.split(".")[1] ?? "");
+}
+function causeCode(error) {
+    for (let e = error, depth = 0; e && depth < 4; e = e.cause, depth++) {
+        const code = e.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return undefined;
+}
+/**
+ * The one answer for a hosted call that threw, decided by what is known to
+ * have happened:
+ * - a sign-in problem (an OAuthError, a 401) is not_signed_in; an account
+ *   the server refuses (403) is forbidden;
+ * - nothing sent (never connected, connection refused, a 503 or another 4xx
+ *   the server answers before it runs anything) is unavailable;
+ * - a call cut off after it was sent may have run: outcome_unknown, retried
+ *   only with the same idempotencyKey, else checked first. A read or a dry
+ *   run changes nothing, so a cut-off one is unavailable.
+ */
+export function hostedCallFailure(error, call) {
+    const known = error instanceof OAuthError || error instanceof HostedUnreachableError;
+    const cause = known ? error.message.replace(` ${error.recovery}`, "") : error instanceof Error ? error.message : String(error);
+    const status = httpStatusOf(error);
+    const details = { was: error instanceof OAuthError ? error.code : error instanceof HostedUnreachableError ? "unreachable" : status !== undefined ? `http_${status}` : causeCode(error) ?? "no_answer" };
+    // A bad SUMMER_MCP_RESOURCE: nothing was sent, and signing in again would not help.
+    if (error instanceof OAuthError && error.code === "oauth_resource_invalid") {
+        return errorAnswer("unavailable", cause, { retry: "no", next: { say: error.recovery.replace(/^Recovery:\s*/, "") }, details });
+    }
+    if (status === 401 || (error instanceof OAuthError && !OAUTH_UNREACHABLE.has(error.code) && error.code !== "store_access_denied") || (!known && /invalid_token/.test(cause))) {
+        // A missing store sign-in needs a sign-in; an expired or refused one needs a fresh store sign-in.
+        const fresh = !(error instanceof OAuthError && error.code === "store_login_required");
+        return errorAnswer("not_signed_in", `Cloud operations need the Summer sign-in: ${cause}`, { next: { say: fresh ? "Run: npx -y summer-engine login --store --force" : "Run: npx -y summer-engine login" }, details });
+    }
+    if (status === 403 || (error instanceof OAuthError && error.code === "store_access_denied")) {
+        return errorAnswer("forbidden", error instanceof OAuthError ? cause : `Summer's hosted server refused this account: ${cause}`, { next: { say: "Check the account in Summer Studio (for example confirm the email), then try again." }, details });
+    }
+    if (status === 429) {
+        return errorAnswer("rate_limited", `Summer's hosted server asked to slow down: ${cause}`, { next: { say: "Wait a minute, then call it again." }, details });
+    }
+    const notSent = known || status === 503 || (status !== undefined && status >= 400 && status < 500) || NOT_SENT_CAUSES.has(causeCode(error) ?? "");
+    if (notSent) {
+        const rejected = status !== undefined && status >= 400 && status < 500;
+        return errorAnswer("unavailable", `Summer's hosted server did not run ${call.op}: ${cause}`, {
+            retry: rejected ? "no" : "after",
+            next: { say: rejected ? "Summer's hosted server refused the request. If it repeats, report it to Summer with this message." : "Try again in a minute. If it repeats, check the network." },
+            details,
+        });
+    }
+    if (call.dryRun || call.read || isReadOp(call.op)) {
+        return errorAnswer("unavailable", `Summer's hosted server did not answer ${call.op} in time: ${cause}`, { retry: "safe", next: { say: "Call it again; it only reads." }, details });
+    }
+    return call.idempotencyKey
+        ? errorAnswer("outcome_unknown", `Summer's hosted server did not answer in time, so it is not known whether ${call.op} ran: ${cause}`, {
+            retry: "same_key",
+            next: { say: "Call it again with the same idempotencyKey: Summer runs a change once per key." },
+            details,
+        })
+        : errorAnswer("outcome_unknown", `Summer's hosted server did not answer in time, so it is not known whether ${call.op} ran: ${cause}`, {
+            retry: "no",
+            next: { say: "Check what it would have changed (or jobs.list) before you try again." },
+            details,
+        });
+}
+/** The answer a hosted v4 tool result carries (its JSON text), or the one error shape. */
+export function answerOfHosted(result) {
+    const content = Array.isArray(result.content) ? result.content : [];
+    const first = content.find((part) => part.type === "text" && typeof part.text === "string")?.text ?? "";
+    try {
+        const parsed = JSON.parse(first);
+        if (parsed && typeof parsed === "object" && "ok" in parsed)
+            return parsed;
+    }
+    catch {
+        // not an answer: fall through
+    }
+    if (/summer_(call|search)\b.*(not found|disabled)/i.test(first)) {
+        return errorAnswer("unavailable", "The Summer server's operation catalog is not switched on yet.", { next: { say: "Use the 3.x tools for now: summer mcp --surface v3 (or SUMMER_SURFACE=v3)." } });
+    }
+    return result.isError === true ? errorAnswer("unavailable", first.slice(0, 300) || "The Summer server did not answer.") : { ok: true, status: "done", result: { text: first } };
+}
+/** Failures that mean Summer's server did not describe the operation, so the shipped catalog may. */
+const DID_NOT_ANSWER = new Set(["not_signed_in", "forbidden", "rate_limited", "unavailable"]);
+/**
+ * ops.describe of a cloud operation when Summer's server could not answer it
+ * (no sign-in, no network): the operation from the shipped catalog, with a
+ * warning. Null when the catalog has no such operation; the failure stands.
+ */
+export function describeFromShipped(name, failure) {
+    // The server's own answer stands (not_found: it no longer has the operation).
+    if (failure.ok || !DID_NOT_ANSWER.has(failure.error.code))
+        return null;
+    const operation = shippedWireForm(resolveOpName(name));
+    if (!operation)
+        return null;
+    const warning = failure.error.code === "not_signed_in"
+        ? "Not signed in: this is the catalog in this version; the operation runs after `summer login`."
+        : `Summer's server did not answer (${failure.error.message}); this is the catalog in this version.`;
+    return { ok: true, status: "done", result: { operation }, warnings: [warning] };
+}
+/** The warning when cloud operations come from the shipped catalog, and whether that is because no one is signed in. */
+function shippedReason(answer) {
+    if (!answer.ok && answer.error.code === "not_signed_in") {
+        return { warning: "Not signed in: cloud operations are listed from the catalog in this version and run after `summer login` (needsSignIn).", signedOut: true };
+    }
+    return { warning: `Cloud operations are listed from the catalog in this version; Summer's server did not search: ${answer.ok ? "no answer" : answer.error.message}`, signedOut: false };
+}
+/**
+ * One ranked list of local and cloud operations for a plain-words query.
+ * Every cloud operation comes from the shipped catalog (public-catalog.ts),
+ * so search finds it signed out, marked needsSignIn; signed in, the server's
+ * own search lays its live rows over the shipped ones (and adds newer
+ * operations). Local hits carry their input schema from the library descriptor.
+ */
+export async function searchEverywhere(query, filters, call, isDirect = () => false) {
+    let live = [];
+    let reason = null;
+    try {
+        const answer = answerOfHosted(await call("summer_search", { query, ...(filters.area ? { area: filters.area } : {}), limit: 20 }));
+        if (answer.ok && answer.status === "done")
+            live = (answer.result.items ?? []).filter((entry) => !isLocalOp(entry.name));
+        else
+            reason = shippedReason(answer);
+    }
+    catch (error) {
+        reason = shippedReason(hostedCallFailure(error, { op: "ops.search", read: true }));
+    }
+    const cloud = new Map(shippedCloudEntries().map((entry) => [entry.name, reason?.signedOut ? { ...entry, needsSignIn: true } : entry]));
+    // The operations that save files take `out` here (save-files.ts), so their input shows it.
+    for (const entry of live) {
+        cloud.set(entry.name, { ...cloud.get(entry.name), ...entry, ...(entry.input ? { input: withOutField(entry.name, entry.input) } : {}) });
+    }
+    const items = searchEntries([...localEntries(), ...cloud.values()], query, filters).map(({ topics: _topics, ...entry }) => isLocalOp(entry.name)
+        ? { ...entry, input: localInputSchema(entry.name) ?? { type: "object" }, mcpTool: entry.mcpTool && isDirect(entry.mcpTool) ? entry.mcpTool : undefined }
+        : entry);
+    return { items, warning: reason?.warning ?? null };
+}

package/dist/core/ops/contract.d.ts

@@ -0,0 +1,120 @@
+import { isLocalOp } from "./areas.js";
+/**
+ * The Summer operation catalog, the part this package needs (contract 1).
+ * Every Summer operation has one name (`area.action`), one effect, one
+ * approval rule and one answer shape; the MCP surface, the CLI and the
+ * store profiles are views of it. The machine contract is
+ * registry/schemas/operation.schema.json; old 3.x tool names map to
+ * operations in registry/operations/legacy-names.json.
+ *
+ * Engine and local operations run in this package. Cloud operations run on
+ * the hosted Summer server; this package reaches them through its v4
+ * surface (summer_search, summer_call) with the person's sign-in.
+ */
+export declare const CONTRACT_VERSION = 1;
+export declare const EFFECTS: readonly ["read", "write", "spend", "publish", "player_facing", "destructive"];
+export type Effect = (typeof EFFECTS)[number];
+export type Approval = "none" | "confirm" | "owner";
+export type Provider = "engine" | "local" | "cloud";
+export declare const MIN_APPROVAL: Record<Effect, Approval>;
+export type ErrorCode = "invalid_input" | "not_signed_in" | "forbidden" | "not_found" | "conflict" | "idempotency_conflict" | "in_progress" | "rate_limited" | "no_credits" | "over_limit" | "engine_not_running" | "engine_lacks_op" | "unsupported" | "not_in_profile" | "moved" | "outcome_unknown" | "unavailable" | "internal";
+export type NextStep = {
+    op: string;
+    input?: Record<string, unknown>;
+} | {
+    url: string;
+    label: string;
+} | {
+    say: string;
+};
+export type Retry = "no" | "safe" | "same_key" | "after";
+export type OpErrorBody = {
+    code: ErrorCode;
+    message: string;
+    next?: NextStep;
+    retry: Retry;
+    details?: Record<string, unknown>;
+    requestId?: string;
+};
+export type JobState = "queued" | "running" | "awaiting_approval" | "done" | "failed" | "cancelled" | "declined" | "expired" | "stale";
+export type JobRef = {
+    id: string;
+    op?: string;
+    state: JobState;
+    progress?: number;
+    pollAfterSeconds?: number;
+};
+/** The one answer shape every operation gives, in every view. */
+export type Answer = {
+    ok: true;
+    status: "done";
+    result: unknown;
+    warnings?: string[];
+} | {
+    ok: true;
+    status: "running";
+    job: JobRef;
+    warnings?: string[];
+} | {
+    ok: true;
+    status: "needs_approval";
+    approval: {
+        id: string;
+        url: string;
+        who: "owner" | "person";
+        summary: string;
+        expiresAt?: string;
+    };
+    job: JobRef;
+    warnings?: string[];
+} | {
+    ok: true;
+    status: "dry_run";
+    preview: Record<string, unknown>;
+    warnings?: string[];
+} | {
+    ok: false;
+    error: OpErrorBody;
+};
+export declare function errorAnswer(code: ErrorCode, message: string, options?: {
+    next?: NextStep;
+    retry?: Retry;
+    details?: Record<string, unknown>;
+}): Answer;
+export declare const OP_NAME: RegExp;
+/** `games.list` -> `summer_games_list`. */
+export declare function mcpNameOf(op: string): string;
+/** `assets generate-image` -> `assets.generate_image`; `whoami` stays. */
+export declare function opFromCli(area: string, action?: string): string;
+export type LegacyRow = {
+    op: string;
+    kind: "same" | "merge" | "split" | "keep";
+    note: string;
+};
+/** registry/operations/legacy-names.json: every 3.x tool name (and `#action`) to its operation. */
+export declare function legacyNames(): Record<string, LegacyRow>;
+/** A 3.x name as its operation name; an operation name unchanged. */
+export declare function resolveOpName(name: string): string;
+/**
+ * Local operations a 3.x tool runs although legacy-names.json maps that
+ * tool to a cloud operation: the local-only input is its own operation
+ * (apps.publish_folder reads a folder on disk; apps.publish takes files).
+ */
+export declare const LOCAL_RUNNERS: Readonly<Record<string, string>>;
+export { isLocalOp };
+/**
+ * The local 3.x tools that run an operation here, first choice first: the
+ * tool the op was renamed from before the tools merged into it.
+ */
+export declare function localToolsFor(op: string): string[];
+/** `<kind>:<backend id>`; an id without a known kind is a 3.x generation job. */
+export declare function parseJobId(id: string): {
+    kind: string;
+    parts: string[];
+} | null;
+/**
+ * The operation a tool call ran, for usage telemetry: summer_call's `op`,
+ * summer_search's own op, a 3.x name's op, or a v4 tool's op from its name
+ * (areas are single words, so the first underscore after `summer_` is the dot).
+ */
+export declare function opForToolCall(tool: string, args: unknown): string | null;