@thenavidm/slipway 0.1.0

package/dist/server.js

@@ -0,0 +1,244 @@
+/**
+ * The MCP surface.
+ *
+ * Every tool is registered from its definition with the annotations its risk
+ * implies, so a client that auto-approves reads or prompts on writes gets an
+ * honest answer from every tool, not only the ones someone remembered to mark.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod";
+import { clientView, confirmRoute, personApproval, verifyApprovalState } from "./confirm.js";
+import { toSlipwayError, UsageError } from "./errors.js";
+import { errorResult, isPlainObject, toCallToolResult } from "./result.js";
+import { outputJsonSchema } from "./schema.js";
+import { firstSentence, searchTools } from "./search.js";
+/** Claude Code shows a person a permission prompt on every call to a tool carrying this, in any mode. */
+export const REQUIRES_USER_INTERACTION = "anthropic/requiresUserInteraction";
+/** Claude Code raises its result-size limit for a tool carrying this. */
+export const MAX_RESULT_SIZE_CHARS = "anthropic/maxResultSizeChars";
+export function annotationsFor(tool) {
+    return {
+        title: tool.title,
+        readOnlyHint: tool.risk === "read",
+        destructiveHint: tool.risk === "destructive",
+        idempotentHint: tool.idempotent,
+        openWorldHint: tool.openWorld,
+    };
+}
+export function metaFor(tool, policy) {
+    const meta = { ...(tool.meta ?? {}) };
+    if (tool.requireConfirm && policy.confirm === "human")
+        meta[REQUIRES_USER_INTERACTION] = true;
+    if (tool.maxResultChars)
+        meta[MAX_RESULT_SIZE_CHARS] = tool.maxResultChars;
+    return Object.keys(meta).length > 0 ? meta : undefined;
+}
+/** The `_meta` key that marks a result served from the local cache, with its age. */
+export const CACHE_META = "slipway/cache";
+function withCacheNote(result, cached) {
+    return cached ? { ...result, _meta: { ...(result._meta ?? {}), [CACHE_META]: { age_seconds: cached.ageSeconds } } } : result;
+}
+/** Progress goes to a client only when its request asked for it with a progress token. */
+function progressFor(ctx) {
+    const token = ctx.mcpReq._meta?.progressToken;
+    if (token === undefined)
+        return undefined;
+    return async ({ progress, total, message }) => {
+        await ctx.mcpReq.notify({
+            method: "notifications/progress",
+            params: { progressToken: token, progress, ...(total === undefined ? {} : { total }), ...(message ? { message } : {}) },
+        });
+    };
+}
+export function buildServer(app, env) {
+    const policy = app.policy(env);
+    const server = new McpServer({
+        name: app.name,
+        title: app.title,
+        version: app.version,
+        ...(app.definition.icons ? { icons: app.definition.icons } : {}),
+    }, {
+        ...(app.instructions ? { instructions: app.instructions } : {}),
+        // Approval forms carry signed state; anything Slipway did not sign is refused before a handler sees it.
+        requestState: { verify: verifyApprovalState },
+    });
+    if (policy.surface === "search")
+        registerSearchSurface(server, app, env, policy);
+    else
+        for (const tool of app.tools(env))
+            registerTool(server, app, tool, env, policy);
+    for (const resource of app.definition.resources ?? [])
+        registerResource(server, app, resource, env);
+    for (const prompt of app.definition.prompts ?? [])
+        registerPrompt(server, app, prompt, env);
+    return server;
+}
+/**
+ * Confirm a call the way this client allows, before it runs.
+ *
+ * Returns the approval form to send while a person has not answered, or the
+ * options `run` needs once the call may go ahead. `listedForPerson` is true
+ * when the tool's own `tools/list` entry asked the client for a person, which
+ * is what makes Claude Code prompt for it.
+ */
+async function confirmFirst(server, app, tool, args, ctx, env, policy, listedForPerson) {
+    if (!tool.requireConfirm)
+        return {};
+    const route = confirmRoute(policy.confirm, clientView(server, ctx), listedForPerson);
+    if (route === "client")
+        return { approvedBy: "client" };
+    if (route === "flag")
+        return {};
+    const ask = await personApproval(app, tool, args, ctx, env);
+    return ask ? { ask } : { approvedBy: "person" };
+}
+function registerTool(server, app, tool, env, policy) {
+    const meta = metaFor(tool, policy);
+    server.registerTool.bind(server)(tool.name, {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.schema,
+        ...(tool.output ? { outputSchema: tool.output } : {}),
+        annotations: annotationsFor(tool),
+        ...(tool.icons ? { icons: tool.icons } : {}),
+        ...(meta ? { _meta: meta } : {}),
+    }, async (args, ctx) => {
+        try {
+            const raw = (args ?? {});
+            const confirmed = await confirmFirst(server, app, tool, raw, ctx, env, policy, meta?.[REQUIRES_USER_INTERACTION] === true);
+            if ("ask" in confirmed)
+                return confirmed.ask;
+            let cached;
+            const value = await app.run(tool, raw, {
+                surface: "mcp",
+                approvedBy: confirmed.approvedBy,
+                signal: ctx.mcpReq.signal,
+                env,
+                onProgress: progressFor(ctx),
+                onCache: (hit) => (cached = hit),
+            });
+            return withCacheNote(toCallToolResult(tool, value, app.secrets), cached);
+        }
+        catch (error) {
+            return errorResult(toSlipwayError(error), app.secrets);
+        }
+    });
+}
+/**
+ * Three tools that stand in for a large catalog.
+ *
+ * A client that loads every tool definition up front pays for all of them on
+ * every message. With `<PREFIX>_SURFACE=search` the model finds a tool by what
+ * it does, reads that one schema, and calls it through the same guard.
+ */
+function registerSearchSurface(server, app, env, policy) {
+    const register = server.registerTool.bind(server);
+    const visible = () => app.tools(env);
+    register("search_tools", {
+        title: "Find a tool",
+        description: `Search ${app.title}'s tools by what they do. Returns names, titles and risk. Call describe_tool on a result for its arguments, then call_tool to run it.`,
+        inputSchema: z.object({
+            query: z.string().min(1).describe("What you want to do, in plain words: 'schedule a post', 'list subscribers'."),
+            limit: z.number().int().min(1).max(50).optional().describe("How many results, 1-50. Defaults to 10."),
+        }),
+        annotations: { title: "Find a tool", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ query, limit }) => {
+        const matches = searchTools(visible(), query, limit ?? 10).map(({ tool }) => ({
+            name: tool.name,
+            title: tool.title,
+            risk: tool.risk,
+            requires_confirm: tool.requireConfirm,
+            summary: firstSentence(tool.description),
+        }));
+        const data = { query, count: matches.length, tools: matches };
+        return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+    });
+    register("describe_tool", {
+        title: "Describe a tool",
+        description: "The full description, argument schema and examples of one tool found with search_tools.",
+        inputSchema: z.object({ name: z.string().min(1).describe("The tool name from search_tools.") }),
+        annotations: { title: "Describe a tool", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ name }) => {
+        const tool = visible().find((candidate) => candidate.name === name);
+        if (!tool)
+            return errorResult(new UsageError(`No tool named '${name}'. Use search_tools to find one.`), app.secrets);
+        const data = {
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            risk: tool.risk,
+            requires_confirm: tool.requireConfirm,
+            input_schema: tool.jsonSchema,
+            ...(tool.output ? { output_schema: outputJsonSchema(tool.output) } : {}),
+            ...(tool.examples.length ? { examples: tool.examples } : {}),
+        };
+        return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+    });
+    register("call_tool", {
+        title: "Run a tool",
+        description: "Run a tool found with search_tools, with arguments that match its schema from describe_tool. A tool marked requires_confirm needs confirming: the user is asked to approve it where the client can ask, and otherwise it runs only with confirm: true, which you pass only when the user asked for that exact action.",
+        inputSchema: z.object({
+            name: z.string().min(1).describe("The tool name."),
+            arguments: z.record(z.string(), z.unknown()).optional().describe("The tool's arguments, as its schema describes them."),
+            confirm: z.boolean().optional().describe("Required for tools marked requires_confirm."),
+        }),
+        annotations: { title: "Run a tool", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async ({ name, arguments: args, confirm }, ctx) => {
+        const tool = visible().find((candidate) => candidate.name === name);
+        if (!tool)
+            return errorResult(new UsageError(`No tool named '${name}'. Use search_tools to find one.`), app.secrets);
+        try {
+            const parsed = await app.parse(tool, args ?? {});
+            // call_tool's own entry carries no request for a person, so Claude Code did not prompt for this tool.
+            const confirmed = await confirmFirst(server, app, tool, parsed, ctx, env, policy, false);
+            if ("ask" in confirmed)
+                return confirmed.ask;
+            let cached;
+            const value = await app.run(tool, parsed, {
+                surface: "mcp",
+                confirmed: confirm === true,
+                approvedBy: confirmed.approvedBy,
+                signal: ctx.mcpReq.signal,
+                env,
+                onProgress: progressFor(ctx),
+                onCache: (hit) => (cached = hit),
+            });
+            const result = withCacheNote(toCallToolResult(tool, value, app.secrets), cached);
+            // This tool declares no output schema, so only an object may travel as structured content.
+            if (result.structuredContent !== undefined && !isPlainObject(result.structuredContent))
+                delete result.structuredContent;
+            return result;
+        }
+        catch (error) {
+            return errorResult(toSlipwayError(error), app.secrets);
+        }
+    });
+}
+function registerResource(server, app, resource, env) {
+    const mimeType = resource.mimeType ?? "application/json";
+    server.registerResource(resource.name, resource.uri, {
+        ...(resource.title ? { title: resource.title } : {}),
+        ...(resource.description ? { description: resource.description } : {}),
+        mimeType,
+    }, async (uri) => {
+        const value = await resource.read(await app.context(env));
+        const body = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+        return { contents: [{ uri: uri.href, mimeType, text: app.secrets.redact(body) }] };
+    });
+}
+function registerPrompt(server, app, prompt, env) {
+    const respond = async (args) => {
+        const text = await prompt.render(args, await app.context(env));
+        return { messages: [{ role: "user", content: { type: "text", text } }] };
+    };
+    const config = {
+        ...(prompt.title ? { title: prompt.title } : {}),
+        ...(prompt.description ? { description: prompt.description } : {}),
+    };
+    const register = server.registerPrompt.bind(server);
+    // Without an argument schema the SDK passes only its context, so the callback shape differs.
+    if (prompt.args)
+        register(prompt.name, { ...config, argsSchema: prompt.args }, (args) => respond(args ?? {}));
+    else
+        register(prompt.name, config, () => respond({}));
+}

package/dist/sync.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copying lists to this machine, and the MCP tools that search and refresh them.
+ *
+ * `data sync <command>` in a terminal and `local_sync` over MCP do the same
+ * thing: follow every page of a list tool and keep each item, keyed by its id,
+ * in the local data file. A sync with no filters mirrors the list, so records
+ * the service no longer lists are removed. A filtered sync only adds and
+ * updates, because what it did not see may still exist outside the filter.
+ */
+import type { App, InvokeOptions } from "./app.js";
+import { type Tool } from "./tool.js";
+export type SyncReport = {
+    tool: string;
+    command: string;
+    /** Records kept from this run. */
+    records: number;
+    /** Items with no id at the sync's id path, which could not be kept. */
+    skipped: number;
+    /** Records removed because a complete, unfiltered sync no longer saw them. */
+    removed: number;
+    pages: number;
+    /** The list ended, rather than the run stopping early. */
+    complete: boolean;
+    /** Filters were given, so nothing was removed. */
+    filtered: boolean;
+    seconds: number;
+};
+export declare function syncTool(app: App, tool: Tool, args: Record<string, unknown>, options: InvokeOptions & {
+    env: NodeJS.ProcessEnv;
+}): Promise<SyncReport>;
+/**
+ * `local_search` and `local_sync`, for an app with at least one synced list.
+ * They are in the `local` toolset, so an operator can switch them off.
+ */
+export declare function localDataTools<Ctx>(synced: readonly Tool<Ctx>[], getApp: () => App<Ctx>): Tool<Ctx>[];

package/dist/sync.js

@@ -0,0 +1,119 @@
+/**
+ * Copying lists to this machine, and the MCP tools that search and refresh them.
+ *
+ * `data sync <command>` in a terminal and `local_sync` over MCP do the same
+ * thing: follow every page of a list tool and keep each item, keyed by its id,
+ * in the local data file. A sync with no filters mirrors the list, so records
+ * the service no longer lists are removed. A filtered sync only adds and
+ * updates, because what it did not see may still exist outside the filter.
+ */
+import * as z from "zod";
+import { UsageError } from "./errors.js";
+import { eachPage, getPath } from "./pages.js";
+import { defineTool } from "./tool.js";
+import { stableJson } from "./util.js";
+/** A sync's filters: its arguments without the cursor and page size, which only say which page. */
+function filtersOf(tool, args) {
+    const { [tool.paginate?.cursorArg ?? "\0"]: _cursor, [tool.paginate?.limitArg ?? "\0"]: _limit, ...filters } = args;
+    return filters;
+}
+export async function syncTool(app, tool, args, options) {
+    if (!tool.sync) {
+        throw new UsageError(`${tool.command} is not a list that can be synced.`, { hint: `Synced lists: ${app.allTools.filter((candidate) => candidate.sync).map((candidate) => candidate.command).join(", ") || "none"}.` });
+    }
+    const sync = tool.sync;
+    const store = await app.localData(options.env);
+    const scope = app.dataScope(await app.context(options.env));
+    const filters = filtersOf(tool, args);
+    const startedAt = Date.now();
+    let skipped = 0;
+    let kept = 0;
+    // A copy made from cached pages would be as old as the cache, so a sync always asks the service.
+    const run = await eachPage(app, tool, args, { ...options, refresh: true }, sync.items, Number.POSITIVE_INFINITY, async (items) => {
+        const records = [];
+        for (const item of items) {
+            const id = getPath(item, sync.id);
+            if ((typeof id !== "string" || !id) && typeof id !== "number") {
+                skipped++;
+                continue;
+            }
+            // Records are kept as clients would see them, with credentials masked.
+            records.push({ id: String(id), data: app.secrets.redactDeep(item) });
+        }
+        store.putRecords(scope, tool.name, records, startedAt);
+        kept += records.length;
+        await options.onProgress?.({ progress: kept, message: `${kept} records` });
+    });
+    const filtered = Object.keys(filters).length > 0;
+    const removed = run.complete && !filtered ? store.removeUnseen(scope, tool.name, startedAt) : 0;
+    store.recordSync(scope, tool.name, stableJson(filters), { startedAt, records: kept, pages: run.pages, complete: run.complete });
+    return {
+        tool: tool.name,
+        command: tool.command,
+        records: kept,
+        skipped,
+        removed,
+        pages: run.pages,
+        complete: run.complete,
+        filtered,
+        seconds: Math.round((Date.now() - startedAt) / 100) / 10,
+    };
+}
+/**
+ * `local_search` and `local_sync`, for an app with at least one synced list.
+ * They are in the `local` toolset, so an operator can switch them off.
+ */
+export function localDataTools(synced, getApp) {
+    const names = synced.map((tool) => tool.name);
+    const listed = names.join(", ");
+    const searchInput = z.object({
+        query: z.string().min(1).describe("The words to find. Every word must appear; the last may be the start of a word."),
+        tool: z.enum(names).optional().describe("Only records synced from this tool."),
+        limit: z.number().int().min(1).max(50).optional().describe("How many results, 1-50. Defaults to 10."),
+    });
+    const search = defineTool({
+        name: "local_search",
+        title: "Search synced data",
+        description: `Search the records synced to this machine from ${listed}. Fast, offline, and costs no API calls. If nothing is found, or the data may be old, run local_sync first.`,
+        input: searchInput,
+        risk: "read",
+        openWorld: false,
+        tags: ["local"],
+        handler: async ({ query, tool, limit }, ctx) => {
+            const app = getApp();
+            const store = await app.localData(ctx.env);
+            const hits = store.search(app.dataScope(ctx), query, { ...(tool ? { tool } : {}), limit: limit ?? 10 });
+            return {
+                query,
+                count: hits.length,
+                results: hits,
+                ...(hits.length ? {} : { hint: `Nothing synced matches. Sync with local_sync first, from one of: ${listed}.` }),
+            };
+        },
+    });
+    const syncInput = z.object({
+        tool: z.enum(names).describe("The list tool to copy."),
+        arguments: z.record(z.string(), z.unknown()).optional().describe("Filters for that tool, as its own arguments. With none, records the service no longer lists are removed."),
+    });
+    const syncData = defineTool({
+        name: "local_sync",
+        title: "Sync data locally",
+        description: `Copy every record one of ${listed} lists to this machine, page by page, so local_search can find them offline. Runs in the background, since a long list takes a while.`,
+        input: syncInput,
+        risk: "read",
+        idempotent: true,
+        tags: ["local"],
+        job: { background: true },
+        handler: async ({ tool, arguments: args }, ctx) => {
+            const app = getApp();
+            const target = app.find(tool);
+            return syncTool(app, target, await app.parse(target, args ?? {}), {
+                surface: ctx.surface,
+                signal: ctx.signal,
+                env: ctx.env,
+                onProgress: ({ progress, total, message }) => ctx.progress(progress, total, message),
+            });
+        },
+    });
+    return [search, syncData];
+}

package/dist/testing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Helpers for testing an app the way its users reach it.
+ *
+ *     import { connect, cli } from "@thenavidm/slipway/testing";
+ *
+ *     const mcp = await connect(app, { env });
+ *     const result = await mcp.callTool("get_profile", { actor: "alice" });
+ *
+ *     const { code, stdout } = await cli(app, ["get-profile", "alice", "--json"], { env });
+ */
+import type { App } from "./app.js";
+import { type ConnectOptions, type RpcClient } from "./rpc.js";
+export { checkApp, type CheckOptions, type CheckReport, type Finding } from "./check.js";
+export type { ConnectOptions, ElicitAnswer, ElicitRequest, ListedTool, RpcClient } from "./rpc.js";
+/**
+ * An MCP client connected to the app's real server, in memory.
+ *
+ *     // A person who approves every form the server shows them:
+ *     const mcp = await connect(app, { elicit: () => ({ action: "accept", content: { approve: true } }) });
+ */
+export declare function connect(app: App, options?: ConnectOptions & {
+    env?: NodeJS.ProcessEnv;
+}): Promise<RpcClient>;
+export type CliRun = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/** Run the CLI with captured output. Nothing reaches the real terminal. */
+export declare function cli(app: App, argv: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+    stdin?: string;
+    isTTY?: boolean;
+    cwd?: string;
+}): Promise<CliRun>;

package/dist/testing.js

@@ -0,0 +1,41 @@
+/**
+ * Helpers for testing an app the way its users reach it.
+ *
+ *     import { connect, cli } from "@thenavidm/slipway/testing";
+ *
+ *     const mcp = await connect(app, { env });
+ *     const result = await mcp.callTool("get_profile", { actor: "alice" });
+ *
+ *     const { code, stdout } = await cli(app, ["get-profile", "alice", "--json"], { env });
+ */
+import { connectInMemory } from "./rpc.js";
+export { checkApp } from "./check.js";
+/**
+ * An MCP client connected to the app's real server, in memory.
+ *
+ *     // A person who approves every form the server shows them:
+ *     const mcp = await connect(app, { elicit: () => ({ action: "accept", content: { approve: true } }) });
+ */
+export function connect(app, options = {}) {
+    const { env, ...rest } = options;
+    return connectInMemory(app, env ?? {}, rest);
+}
+/** Run the CLI with captured output. Nothing reaches the real terminal. */
+export async function cli(app, argv, options = {}) {
+    let stdout = "";
+    let stderr = "";
+    const code = await app.runCli(argv, {
+        stdout: (text) => {
+            stdout += text;
+        },
+        stderr: (text) => {
+            stderr += text;
+        },
+        stdin: async () => options.stdin ?? "",
+        env: options.env ?? {},
+        isTTY: options.isTTY ?? false,
+        bin: app.bins.cli,
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+    });
+    return { code, stdout, stderr };
+}

package/dist/tool.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The one definition both surfaces read.
+ *
+ * A tool is described once: its name, what it is for, the shape of its input,
+ * how risky it is and what it does. The MCP server and the CLI are both
+ * generated from that object, so a tool added today is a command today, and
+ * neither surface can describe it differently from the other.
+ */
+import type { Icon } from "@modelcontextprotocol/server";
+import { type JobDefinition } from "./jobs.js";
+import type { Secrets } from "./redact.js";
+import { type InferInput, type InferOutput, type JsonSchema, type Schema } from "./schema.js";
+/**
+ * How much a call can change.
+ *
+ * - `read` changes nothing.
+ * - `write` changes something that is easy to undo: a like, a label, a draft.
+ * - `destructive` is public the moment it runs, cannot be undone, or both.
+ */
+export type Risk = "read" | "write" | "destructive";
+export type Surface = "mcp" | "cli";
+export type Logger = {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+};
+/** What Slipway hands every handler, next to the app's own context. */
+export type RunContext = {
+    /** Aborts when the client cancels, the call times out, or Ctrl-C reaches the CLI. Pass it to fetch. */
+    readonly signal: AbortSignal;
+    readonly surface: Surface;
+    /** The environment this call runs with: the one `context(env)` was built from. */
+    readonly env: NodeJS.ProcessEnv;
+    /** True when the CLI ran with --dry-run. Handlers only see it through `preview`. */
+    readonly dryRun: boolean;
+    readonly tool: {
+        readonly name: string;
+        readonly risk: Risk;
+    };
+    /** Register credentials here and they are masked in every result and error. */
+    readonly secrets: Secrets;
+    /** Writes to stderr. stdout is the protocol channel on stdio, so nothing may print there. */
+    readonly log: Logger;
+    /** Report progress. Sent to an MCP client that asked for it, shown on stderr in a terminal. */
+    progress(progress: number, total?: number, message?: string): Promise<void>;
+};
+export type ToolContext<Ctx> = Ctx & RunContext;
+export type ToolExample = {
+    /** What the example does, in the words a person would use to ask for it. */
+    description: string;
+    /** Arguments, exactly as an MCP client would send them. Validated by `slipway check`. */
+    args: Record<string, unknown>;
+};
+/**
+ * How a cursor-paginated tool pages, so the CLI can follow every page with
+ * `--all` instead of leaving the loop to a script or a model.
+ */
+export type Paginate = {
+    /** The input argument that takes the cursor. */
+    cursorArg: string;
+    /** Dotted path to the next cursor in a result. Empty or missing means the last page. */
+    nextCursor: string;
+    /** Dotted path to the array of items in a result. */
+    items: string;
+    /** The input argument for page size, set to the largest page when following every page. */
+    limitArg?: string;
+    /** The largest page the API serves. */
+    maxLimit?: number;
+};
+/** Keep results of a read on this machine for a while, so asking twice costs one call. */
+export type CacheOptions = {
+    /** How long a result stays fresh, in seconds. Any write through the same app clears it sooner. */
+    ttlSeconds: number;
+};
+/** Copy every item a list tool returns into local data, where it can be searched offline. */
+export type SyncOptions = {
+    /** Dotted path to each item's id: `id`, `uri`, `user.id`. */
+    id: string;
+    /** Dotted path to the list in a result. Defaults to the `paginate.items` path. */
+    items?: string;
+};
+type Returns<O> = O extends Schema ? InferInput<O> : unknown;
+export type ToolDefinition<Ctx, I extends Schema, O extends Schema | undefined> = {
+    /** snake_case. The MCP tool name; the CLI command is the same name with dashes. */
+    name: string;
+    /** A few words for pickers and the command list: "Delete a post". */
+    title: string;
+    /** What it does and when to reach for it. The only documentation a model reads before calling. */
+    description: string;
+    /** A Zod object, or `jsonSchema({...})` for a tool generated from an API contract. */
+    input?: I;
+    /** Declare it and results are validated and sent as typed `structuredContent`. */
+    output?: O;
+    risk: Risk;
+    /** Calling twice has the same effect as once. Defaults to true for reads. */
+    idempotent?: boolean;
+    /** Reaches outside this machine. Defaults to true; set false for local helpers. */
+    openWorld?: boolean;
+    /**
+     * Require `confirm: true` (MCP) or `--confirm` (CLI). Defaults to true for
+     * destructive tools. Set it on a write that spends money, such as a paid
+     * generation.
+     */
+    requireConfirm?: boolean;
+    /** Toolsets this tool belongs to. A tool with no tags is always on. */
+    tags?: string[];
+    /** One line for the audit log and the refusal message: "post 'Hello' as @alice". */
+    summary?: (args: InferOutput<I>) => string;
+    /** What --dry-run prints instead of running. Defaults to the validated arguments. */
+    preview?: (args: InferOutput<I>, ctx: ToolContext<Ctx>) => unknown;
+    examples?: ToolExample[];
+    /** Input names that may be given as bare words on the command line, in order. */
+    positional?: string[];
+    /** Abort the call after this long. */
+    timeoutMs?: number;
+    /** Results this tool returns are legitimately large. Raises Claude Code's limit for this tool. */
+    maxResultChars?: number;
+    icons?: Icon[];
+    /** Extra `_meta` for the tool's `tools/list` entry. */
+    meta?: Record<string, unknown>;
+    paginate?: Paginate;
+    /**
+     * The tool starts work that outlasts one call. Slipway adds `wait_seconds`,
+     * waits that long, and generates `<name>_status` to check on the job later.
+     * Describe a job the service runs with `id`, `status` and `done`, or pass
+     * `{ background: true }` for a handler that is slow on its own.
+     */
+    job?: JobDefinition<Ctx>;
+    /** Cache this read's results locally. Only for reads whose results can be a little stale. */
+    cache?: CacheOptions;
+    /** This read lists records worth keeping locally: `data sync` copies every page, `data search` finds them. */
+    sync?: SyncOptions;
+    /** Text for the result, when JSON is not the best way to read it. Typed data still goes out as `structuredContent`. */
+    render?: (result: Returns<O>) => string;
+    handler: (args: InferOutput<I>, ctx: ToolContext<Ctx>) => Returns<O> | Promise<Returns<O>>;
+};
+export type Tool<Ctx = any> = {
+    readonly kind: "slipway.tool";
+    readonly name: string;
+    /** The CLI command: the name with dashes. */
+    readonly command: string;
+    readonly title: string;
+    readonly description: string;
+    readonly risk: Risk;
+    readonly idempotent: boolean;
+    readonly openWorld: boolean;
+    readonly requireConfirm: boolean;
+    readonly tags: readonly string[];
+    readonly examples: readonly ToolExample[];
+    readonly positional: readonly string[];
+    readonly timeoutMs?: number;
+    readonly maxResultChars?: number;
+    readonly icons?: Icon[];
+    readonly meta?: Record<string, unknown>;
+    readonly paginate?: Paginate;
+    readonly job?: JobDefinition<Ctx>;
+    readonly cache?: CacheOptions;
+    /** The sync settings, with `items` always filled in. */
+    readonly sync?: Required<SyncOptions>;
+    /** On the status tool Slipway generates for a job tool: the job tool's name. */
+    readonly statusOf?: string;
+    /** The author's input schema. */
+    readonly input: Schema;
+    /** What clients see: the input plus `confirm` when the tool requires it. */
+    readonly schema: Schema;
+    readonly output?: Schema;
+    readonly summary?: (args: any) => string;
+    readonly preview?: (args: any, ctx: ToolContext<Ctx>) => unknown;
+    readonly render?: (result: any) => string;
+    readonly handler: (args: any, ctx: ToolContext<Ctx>) => unknown;
+    /** The advertised input as JSON Schema, computed once. */
+    readonly jsonSchema: JsonSchema;
+};
+/** Define a tool. Throws at load time on a definition that cannot work, not on the first call. */
+export declare function defineTool<Ctx = unknown, I extends Schema = Schema<Record<string, never>>, O extends Schema | undefined = undefined>(definition: ToolDefinition<Ctx, I, O>): Tool<Ctx>;
+/**
+ * Bind `defineTool` to an app's context type once, so every handler in the
+ * repo gets `ctx.client` typed without repeating the generic:
+ *
+ *     export const { defineTool } = toolkit<Context>();
+ */
+export declare function toolkit<Ctx>(): {
+    defineTool: <I extends Schema = Schema<Record<string, never>>, O extends Schema | undefined = undefined>(definition: ToolDefinition<Ctx, I, O>) => Tool<Ctx>;
+};
+export declare function isTool(value: unknown): value is Tool;
+/**
+ * One line saying what a call is about to do, for refusals, approval forms and
+ * the audit log. The tool's own `summary`, or its title as a phrase: "delete a
+ * note". A summary that throws falls back too, because it runs before the
+ * arguments have been anywhere near the handler.
+ */
+export declare function summarize(tool: Pick<Tool, "summary" | "title">, args: Record<string, unknown>): string;
+export {};