@thenavidm/slipway 0.1.0

package/dist/cli/output.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How a result is printed.
+ *
+ * A person reads text, a script reads JSON, a spreadsheet reads CSV, and a
+ * model reads whatever costs it least. One result, several shapes, chosen by a
+ * flag, never by guessing at what the reader is.
+ */
+import type { Tool } from "../tool.js";
+export type Format = "auto" | "json" | "compact" | "jsonl" | "csv" | "tsv" | "quiet";
+export type OutputOptions = {
+    format: Format;
+    select?: string[];
+};
+/**
+ * `--select a,b.c` keeps only those fields. Dotted paths descend, arrays are
+ * walked element by element, which is what makes a long listing affordable.
+ */
+export declare function selectFields(data: unknown, paths: readonly string[]): unknown;
+/** What a result is as data: a content result's data, or its parts described in words. */
+export declare function terminalData(value: unknown): unknown;
+/** Render a result for stdout. Always ends with a newline. */
+export declare function formatOutput(value: unknown, tool: Tool | undefined, options: OutputOptions): string;

package/dist/cli/output.js

@@ -0,0 +1,159 @@
+/**
+ * How a result is printed.
+ *
+ * A person reads text, a script reads JSON, a spreadsheet reads CSV, and a
+ * model reads whatever costs it least. One result, several shapes, chosen by a
+ * flag, never by guessing at what the reader is.
+ */
+import { getPath } from "../pages.js";
+import { isContentResult } from "../result.js";
+/**
+ * `--select a,b.c` keeps only those fields. Dotted paths descend, arrays are
+ * walked element by element, which is what makes a long listing affordable.
+ */
+export function selectFields(data, paths) {
+    if (Array.isArray(data))
+        return data.map((item) => selectFields(item, paths));
+    if (data === null || typeof data !== "object")
+        return data;
+    // Grouped by first segment: assigning one path at a time let the last path win,
+    // so `--select posts.uri,posts.text` returned only the text.
+    const byHead = new Map();
+    for (const path of paths) {
+        const [head, ...rest] = path.split(".");
+        if (!head)
+            continue;
+        const group = byHead.get(head) ?? [];
+        if (rest.length)
+            group.push(rest.join("."));
+        byHead.set(head, group);
+    }
+    const out = {};
+    for (const [head, rest] of byHead) {
+        const value = data[head];
+        if (value === undefined)
+            continue;
+        out[head] = rest.length ? selectFields(value, rest) : value;
+    }
+    return out;
+}
+function describePart(part) {
+    if (part.type === "text")
+        return part.text;
+    const p = part;
+    const size = p.data ?? p.resource?.blob;
+    const kb = size ? `, ${Math.max(1, Math.round((size.length * 3) / 4 / 1024))} KB` : "";
+    const where = p.uri ?? p.resource?.uri;
+    return `[${p.type}${p.mimeType ?? p.resource?.mimeType ? ` ${p.mimeType ?? p.resource?.mimeType}` : ""}${kb}${where ? ` ${where}` : ""}]`;
+}
+/** What a result is as data: a content result's data, or its parts described in words. */
+export function terminalData(value) {
+    if (!isContentResult(value))
+        return value;
+    if (value.data !== undefined)
+        return value.data;
+    return value.parts.map(describePart).join("\n");
+}
+function cell(value, separator) {
+    if (value === null || value === undefined)
+        return "";
+    const text = typeof value === "object" ? JSON.stringify(value) : String(value);
+    if (separator === "\t")
+        return text.replace(/[\t\n\r]+/g, " ");
+    return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+function table(data, separator) {
+    if (Array.isArray(data)) {
+        if (data.every((row) => row === null || typeof row !== "object" || Array.isArray(row))) {
+            return data.map((row) => cell(row, separator)).join("\n");
+        }
+        const columns = [];
+        for (const row of data) {
+            if (row && typeof row === "object")
+                for (const key of Object.keys(row))
+                    if (!columns.includes(key))
+                        columns.push(key);
+        }
+        const lines = [columns.map((column) => cell(column, separator)).join(separator)];
+        for (const row of data) {
+            lines.push(columns.map((column) => cell(row?.[column], separator)).join(separator));
+        }
+        return lines.join("\n");
+    }
+    if (data !== null && typeof data === "object") {
+        // A single array field is the listing a person meant to tabulate.
+        const arrays = Object.entries(data).filter(([, value]) => Array.isArray(value));
+        if (arrays.length === 1)
+            return table(arrays[0][1], separator);
+        return Object.entries(data)
+            .map(([key, value]) => `${cell(key, separator)}${separator}${cell(value, separator)}`)
+            .join("\n");
+    }
+    return cell(data, separator);
+}
+/**
+ * The one list inside a wrapper like `{ items, cursor }`, which is what a person
+ * means when they ask for lines or rows of a result that is not itself a list.
+ */
+function singleList(data) {
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return undefined;
+    const arrays = Object.values(data).filter(Array.isArray);
+    return arrays.length === 1 ? arrays[0] : undefined;
+}
+const IDENTIFIERS = ["id", "uri", "url", "name", "handle", "slug", "key"];
+function quiet(data, select) {
+    const pick = (item) => {
+        if (item === null || typeof item !== "object")
+            return String(item ?? "");
+        if (select?.length === 1)
+            return String(getPath(item, select[0]) ?? "");
+        const key = IDENTIFIERS.find((candidate) => item[candidate] !== undefined);
+        return key ? String(item[key]) : JSON.stringify(item);
+    };
+    if (Array.isArray(data))
+        return data.map(pick).join("\n");
+    if (data !== null && typeof data === "object") {
+        const arrays = Object.values(data).filter(Array.isArray);
+        if (arrays.length === 1)
+            return arrays[0].map(pick).join("\n");
+    }
+    return pick(data);
+}
+/** Render a result for stdout. Always ends with a newline. */
+export function formatOutput(value, tool, options) {
+    let data = terminalData(value);
+    if (options.select?.length && data !== null && typeof data === "object")
+        data = selectFields(data, options.select);
+    let text;
+    switch (options.format) {
+        case "json":
+            text = JSON.stringify(data, null, 2) ?? "null";
+            break;
+        case "compact":
+            text = JSON.stringify(data) ?? "null";
+            break;
+        case "jsonl": {
+            const list = Array.isArray(data) ? data : singleList(data);
+            text = list ? list.map((item) => JSON.stringify(item)).join("\n") : (JSON.stringify(data) ?? "null");
+            break;
+        }
+        case "csv":
+            text = table(data, ",");
+            break;
+        case "tsv":
+            text = table(data, "\t");
+            break;
+        case "quiet":
+            text = quiet(data, options.select);
+            break;
+        default:
+            if (typeof data === "string")
+                text = data;
+            else if (tool?.render && !options.select?.length && data !== undefined)
+                text = tool.render(data);
+            else
+                text = JSON.stringify(data, null, 2) ?? "null";
+    }
+    return text.endsWith("\n") ? text : `${text}\n`;
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The CLI surface.
+ *
+ * Every tool is a command with the same name, the same arguments and the same
+ * guard as over MCP, because both run through `app.invoke`. What this module
+ * adds is what a terminal needs and a protocol does not: flags, help, output
+ * shapes, exit codes, pagination and files.
+ */
+import type { App, CliIO } from "../app.js";
+export declare function runCli(app: App, argv: readonly string[], partial?: Partial<CliIO>): Promise<number>;

package/dist/cli/run.js

@@ -0,0 +1,343 @@
+/**
+ * The CLI surface.
+ *
+ * Every tool is a command with the same name, the same arguments and the same
+ * guard as over MCP, because both run through `app.invoke`. What this module
+ * adds is what a terminal needs and a protocol does not: flags, help, output
+ * shapes, exit codes, pagination and files.
+ */
+import { writeFileSync } from "node:fs";
+import { runDoctor } from "../doctor.js";
+import { EXIT, UsageError, toSlipwayError } from "../errors.js";
+import { eachPage } from "../pages.js";
+import { visibility, policyEnvNames } from "../policy.js";
+import { outputJsonSchema } from "../schema.js";
+import { didYouMean, searchTools } from "../search.js";
+import { completionScript } from "./completion.js";
+import { agentContext, SLIPWAY_VERSION } from "./context.js";
+import { flagsFor, missingRequired, parseJsonValue, parseToolArgs } from "./flags.js";
+import { BUILTINS, renderGeneralHelp, renderList, renderToolHelp, toolLine } from "./help.js";
+import { formatOutput } from "./output.js";
+const VALUE_FLAGS = new Set(["--select", "--out", "--input", "--max-items", "--timeout"]);
+const FORMATS = {
+    "--json": "json",
+    "--compact": "compact",
+    "--jsonl": "jsonl",
+    "--csv": "csv",
+    "--tsv": "tsv",
+    "--plain": "tsv",
+    "--quiet": "quiet",
+};
+/** Accepted so scripts written for other CLIs do not break. `--yes` is accepted and never confirms anything. */
+const IGNORED = new Set(["--no-color", "--no-input", "--yes"]);
+const SWITCHES = new Set([...Object.keys(FORMATS), ...IGNORED, "--agent", "--dry-run", "--confirm", "--wait", "--refresh", "--all", "--help", "-h", "--version", "-v"]);
+function flagOf(token) {
+    const eq = token.indexOf("=");
+    return eq === -1 ? token : token.slice(0, eq);
+}
+/** The index of the command word: the first bare word that is not the value of a global flag. */
+function findCommand(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--")
+            return -1;
+        if (token.startsWith("-")) {
+            if (VALUE_FLAGS.has(token))
+                i++;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+/**
+ * Pull the CLI's own flags out of argv. A flag the tool itself defines wins, so
+ * a tool with an `input` or `select` argument keeps it.
+ */
+function extractGlobals(argv, reserved) {
+    const globals = { format: "auto", explicitFormat: false, agent: false, dryRun: false, confirm: false, wait: false, refresh: false, all: false, help: false, version: false };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        const name = flagOf(token);
+        if (reserved.has(name) || (!SWITCHES.has(name) && !VALUE_FLAGS.has(name))) {
+            rest.push(token);
+            continue;
+        }
+        if (VALUE_FLAGS.has(name)) {
+            const value = token.includes("=") ? token.slice(token.indexOf("=") + 1) : argv[++i];
+            if (value === undefined)
+                throw new UsageError(`${name} expects a value.`);
+            if (name === "--select")
+                globals.select = value.split(",").map((part) => part.trim()).filter(Boolean);
+            else if (name === "--out")
+                globals.out = value;
+            else if (name === "--input")
+                globals.input = value;
+            else {
+                const number = Number(value);
+                if (!Number.isInteger(number) || number < 1)
+                    throw new UsageError(`${name} expects a positive whole number, got '${value}'.`);
+                if (name === "--max-items")
+                    globals.maxItems = number;
+                else
+                    globals.timeoutMs = number;
+            }
+            continue;
+        }
+        if (FORMATS[name]) {
+            globals.format = FORMATS[name];
+            globals.explicitFormat = true;
+        }
+        else if (name === "--agent")
+            globals.agent = true;
+        else if (name === "--dry-run")
+            globals.dryRun = true;
+        else if (name === "--confirm")
+            globals.confirm = true;
+        else if (name === "--wait")
+            globals.wait = true;
+        else if (name === "--refresh")
+            globals.refresh = true;
+        else if (name === "--all")
+            globals.all = true;
+        else if (name === "--help" || name === "-h")
+            globals.help = true;
+        else if (name === "--version" || name === "-v")
+            globals.version = true;
+    }
+    // Agent mode means one line of JSON, unless a format was asked for by name.
+    if (globals.agent && !globals.explicitFormat)
+        globals.format = "compact";
+    return { globals, rest };
+}
+function defaultIO(app, partial) {
+    return {
+        stdout: (text) => void process.stdout.write(text),
+        stderr: (text) => void process.stderr.write(text),
+        stdin: async () => {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+            return Buffer.concat(chunks).toString("utf8");
+        },
+        env: process.env,
+        isTTY: Boolean(process.stdout.isTTY),
+        bin: app.bins.cli,
+        ...partial,
+    };
+}
+function emitError(io, app, error, agent) {
+    const payload = app.secrets.redactDeep(error.toJSON());
+    io.stderr(`${agent ? JSON.stringify(payload) : JSON.stringify(payload, null, 2)}\n`);
+}
+export async function runCli(app, argv, partial = {}) {
+    const io = defaultIO(app, partial);
+    const at = findCommand(argv);
+    const command = at === -1 ? undefined : argv[at];
+    const builtin = command !== undefined && BUILTINS.includes(command);
+    const tool = command !== undefined && !builtin ? app.find(command) : undefined;
+    const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : []);
+    let agent = argv.includes("--agent");
+    try {
+        const { globals, rest } = extractGlobals(at === -1 ? argv : [...argv.slice(0, at), ...argv.slice(at + 1)], reserved);
+        agent = globals.agent;
+        if (command === undefined) {
+            if (globals.version)
+                return printVersion(app, io);
+            if (globals.help)
+                return print(io, renderGeneralHelp(app, io.bin));
+            return print(io, renderList(app, app.tools(io.env), io.bin));
+        }
+        if (builtin)
+            return await runBuiltin(app, io, command, rest, globals);
+        if (!tool) {
+            const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS];
+            const guess = didYouMean(command, candidates);
+            throw new UsageError(`Unknown command '${command}'.${guess ? ` Did you mean '${guess}'?` : ""}`, {
+                hint: `Run \`${io.bin}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
+            });
+        }
+        const seen = visibility(tool, app.policy(io.env));
+        if (!seen.visible) {
+            const names = policyEnvNames(app.envPrefix);
+            throw new UsageError(seen.reason === "read-only"
+                ? `${tool.command} is unavailable: ${names.readOnly}=1 hides every write.`
+                : `${tool.command} is in a toolset that is off: ${tool.tags.join(", ")}.`, { hint: seen.reason === "read-only" ? `Unset ${names.readOnly} to allow writes.` : `Add one of them to ${names.toolsets}, or set ${names.toolsets}=all.` });
+        }
+        if (globals.help)
+            return print(io, renderToolHelp(tool, io.bin));
+        return await runTool(app, io, tool, rest, globals);
+    }
+    catch (error) {
+        const failure = toSlipwayError(error);
+        emitError(io, app, failure, agent);
+        if (failure.code === "usage" && tool && !agent && io.isTTY)
+            io.stderr(renderToolHelp(tool, io.bin));
+        return failure.exitCode;
+    }
+}
+function print(io, text) {
+    io.stdout(text.endsWith("\n") ? text : `${text}\n`);
+    return EXIT.ok;
+}
+function printVersion(app, io) {
+    return print(io, `${app.name} ${app.version} (slipway ${SLIPWAY_VERSION})`);
+}
+function json(globals, value) {
+    return globals.format === "compact" ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+}
+async function runBuiltin(app, io, command, rest, globals) {
+    const target = rest.find((token) => !token.startsWith("-"));
+    switch (command) {
+        case "tools":
+            return print(io, renderList(app, app.tools(io.env), io.bin));
+        case "version":
+            return printVersion(app, io);
+        case "help": {
+            if (!target)
+                return print(io, renderGeneralHelp(app, io.bin));
+            const tool = app.find(target);
+            if (!tool)
+                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+            return print(io, renderToolHelp(tool, io.bin));
+        }
+        case "schema": {
+            const tool = target ? app.find(target) : undefined;
+            if (!tool)
+                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${io.bin}\` to list commands.` });
+            if (rest.includes("--output")) {
+                if (!tool.output)
+                    throw new UsageError(`${tool.command} declares no output schema.`);
+                return print(io, json(globals, outputJsonSchema(tool.output)));
+            }
+            return print(io, json(globals, tool.jsonSchema));
+        }
+        case "agent-context":
+            return print(io, json(globals, agentContext(app, io.env, io.bin, { brief: rest.includes("--brief") })));
+        case "which": {
+            const query = rest.filter((token) => !token.startsWith("-")).join(" ");
+            if (!query)
+                throw new UsageError("which expects the words for what you want to do: which schedule a post");
+            const matches = searchTools(app.tools(io.env), query, 10);
+            if (globals.format !== "auto") {
+                return print(io, json(globals, matches.map(({ tool, score }) => ({ command: tool.command, title: tool.title, risk: tool.risk, score: Number(score.toFixed(2)) }))));
+            }
+            if (!matches.length)
+                return print(io, `No command matches '${query}'. Run \`${io.bin}\` to see them all.`);
+            return print(io, matches.map(({ tool }) => toolLine(tool)).join("\n"));
+        }
+        case "doctor":
+            return runDoctor(app, io, { network: rest.includes("--network"), json: globals.format !== "auto" });
+        case "login": {
+            const login = app.definition.login;
+            if (typeof login === "function")
+                return await login(io);
+            if (typeof login === "string")
+                return print(io, login);
+            return print(io, `${app.title} reads its credentials from the environment. Run \`${io.bin} doctor\` to see what is missing.`);
+        }
+        case "completion":
+            return print(io, completionScript(app, target, io.bin, io.env));
+        case "install": {
+            const { runInstall } = await import("./install.js");
+            return runInstall(app, io, rest, { agent: globals.agent, dryRun: globals.dryRun, format: globals.format });
+        }
+        case "data": {
+            const { runData } = await import("./data.js");
+            return runData(app, io, rest, { format: globals.format, ...(globals.select ? { select: globals.select } : {}), agent: globals.agent });
+        }
+        default:
+            throw new UsageError(`Unknown command '${command}'.`);
+    }
+}
+async function readInput(io, raw) {
+    const value = raw === "-" ? parseJsonValue(await io.stdin(), "--input") : parseJsonValue(raw, "--input");
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new UsageError("--input expects a JSON object of arguments.");
+    }
+    return value;
+}
+async function runTool(app, io, tool, rest, globals) {
+    const flags = flagsFor(tool.jsonSchema);
+    const base = globals.input ? await readInput(io, globals.input) : {};
+    const args = { ...base, ...parseToolArgs(rest, flags, tool.positional) };
+    if (globals.confirm && tool.requireConfirm)
+        args.confirm = true;
+    const missing = missingRequired(flags, args).filter((flag) => !(globals.all && tool.paginate && flag.key === tool.paginate.cursorArg));
+    if (missing.length && !globals.dryRun) {
+        throw new UsageError(`Missing ${missing.map((flag) => flag.flag).join(", ")}.`, { hint: `Run \`${io.bin} ${tool.command} --help\`.` });
+    }
+    if ((globals.all || globals.maxItems) && !tool.paginate) {
+        throw new UsageError(`${tool.command} does not page, so --all and --max-items do not apply.`);
+    }
+    if (globals.wait && !tool.job) {
+        throw new UsageError(`${tool.command} does not start a job, so --wait does not apply.`);
+    }
+    const controller = new AbortController();
+    const onInterrupt = () => controller.abort(new DOMException("Interrupted", "AbortError"));
+    const listens = partialIsProcess(io);
+    if (listens)
+        process.once("SIGINT", onInterrupt);
+    const signal = globals.timeoutMs ? AbortSignal.any([controller.signal, AbortSignal.timeout(globals.timeoutMs)]) : controller.signal;
+    const options = {
+        surface: "cli",
+        confirmed: globals.confirm,
+        dryRun: globals.dryRun,
+        ...(globals.wait ? { waitMs: Number.POSITIVE_INFINITY } : {}),
+        ...(globals.refresh ? { refresh: true } : {}),
+        ...(io.isTTY && !globals.agent && tool.cache
+            ? { onCache: ({ ageSeconds }) => io.stderr(`(from the local cache, ${ageSeconds} s old; --refresh fetches it again)\n`) }
+            : {}),
+        signal,
+        env: io.env,
+        onProgress: io.isTTY && !globals.agent
+            ? ({ progress, total, message }) => io.stderr(`… ${total ? `${progress}/${total}` : progress}${message ? ` ${message}` : ""}\n`)
+            : undefined,
+    };
+    try {
+        let result;
+        if (tool.paginate && (globals.all || globals.maxItems) && !globals.dryRun) {
+            result = await allPages(app, tool, args, options, globals.maxItems ?? Number.POSITIVE_INFINITY);
+        }
+        else {
+            result = await app.invoke(tool.name, args, options);
+        }
+        if (globals.out)
+            return writeOut(io, globals, tool, result);
+        io.stdout(formatOutput(result, tool, { format: globals.format, select: globals.select }));
+        return EXIT.ok;
+    }
+    finally {
+        if (listens)
+            process.removeListener("SIGINT", onInterrupt);
+    }
+}
+/** Only the real process gets a Ctrl-C handler; a test harness passing its own stdout does not. */
+function partialIsProcess(io) {
+    return io.env === process.env;
+}
+/** Follow a cursor until the pages run out or enough items arrived, and return them as one list. */
+async function allPages(app, tool, args, options, max) {
+    const items = [];
+    const run = await eachPage(app, tool, args, options, tool.paginate.items, max, (page) => void items.push(...page));
+    return { items, count: run.count, pages: run.pages, next_cursor: run.next_cursor };
+}
+/** Write to a new file only, readable by its owner, so an export never replaces something or leaks to other users. */
+function writeOut(io, globals, tool, result) {
+    const format = globals.format === "auto" ? "json" : globals.format;
+    const text = formatOutput(result, tool, { format, select: globals.select });
+    try {
+        writeFileSync(globals.out, text, { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        const code = error.code;
+        throw new UsageError(code === "EEXIST" ? `${globals.out} already exists. Choose a new file name.` : `Could not write ${globals.out}: ${error.message}`);
+    }
+    io.stdout(`${JSON.stringify({ saved: globals.out, bytes: Buffer.byteLength(text) })}\n`);
+    return EXIT.ok;
+}

package/dist/confirm.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Confirmation a model cannot fake.
+ *
+ * `confirm: true` is something the model types, so on its own it proves only
+ * that the model meant it. Where the client can put a person in front of the
+ * call, Slipway asks the person instead, and the model's flag stops counting:
+ *
+ * - Claude Code shows its own approval prompt for a tool marked as needing a
+ *   person, on every call and in every permission mode. A call that arrives
+ *   from it has already been approved, so nothing else is asked.
+ * - Any other client that supports elicitation is sent an approval form. The
+ *   tool runs only on an explicit yes.
+ * - A client that can do neither falls back to `confirm: true`.
+ *
+ * An approval form's answer comes back from the client as data, and a client
+ * could attach an answer to a call nobody was asked about. So an answer only
+ * counts next to the signed state Slipway minted when it asked, which names
+ * the exact tool and arguments and can be used once.
+ */
+import { inputRequired, type McpServer, type ServerContext } from "@modelcontextprotocol/server";
+import type { App } from "./app.js";
+import type { ConfirmMode } from "./policy.js";
+import type { Tool } from "./tool.js";
+/** The key of Slipway's approval form among a call's input requests. */
+export declare const APPROVAL_KEY = "slipway_approval";
+export type ClientView = {
+    name?: string;
+    version?: string;
+    capabilities?: Record<string, unknown>;
+};
+/**
+ * Who is calling and what it can do. On the 2026-07-28 revision every request
+ * carries this itself; on earlier revisions it was said once, at initialize.
+ */
+export declare function clientView(server: McpServer, ctx: ServerContext): ClientView;
+/**
+ * Whether the client can show a person a form. A bare `elicitation: {}` is the
+ * 2025 way of saying so; naming only `url` mode is not.
+ */
+export declare function canAskPerson(client: ClientView): boolean;
+/** Whether the client shows its own approval prompt for a tool that asks for a person. */
+export declare function promptsItself(client: ClientView): boolean;
+/**
+ * How this call gets confirmed.
+ *
+ * - `client`: the client already asked a person, so the call runs.
+ * - `person`: Slipway asks the person with an approval form.
+ * - `flag`: the call runs only with `confirm: true`.
+ */
+export type ConfirmRoute = "client" | "person" | "flag";
+export declare function confirmRoute(mode: ConfirmMode, client: ClientView, listedForPerson: boolean): ConfirmRoute;
+type Pending = {
+    t: string;
+    h: string;
+    n: string;
+};
+/** For `ServerOptions.requestState.verify`: rejects state Slipway did not sign, or signed more than ten minutes ago. */
+export declare const verifyApprovalState: (state: string, ctx: ServerContext) => Promise<Pending>;
+/**
+ * The words and the one field an approval form shows.
+ *
+ * The field is required, starts unticked, and only an explicit true counts.
+ * Accepting is not enough on its own: a client with nobody to ask may accept a
+ * form by itself (Codex accepts a form that has no fields), and one that fills
+ * in defaults would otherwise approve with them.
+ */
+export declare function approvalForm(appTitle: string, tool: Pick<Tool, "risk">, summary: string): {
+    message: string;
+    requestedSchema: {
+        type: "object";
+        properties: {
+            approve: {
+                type: "boolean";
+                title: string;
+                description: string;
+                default: boolean;
+            };
+        };
+        required: string[];
+    };
+};
+/**
+ * Ask a person to approve the call, or read their answer.
+ *
+ * Returns the input-required result to send while the person has not answered
+ * yet, and nothing once they approved. Throws a refusal for a no, a closed
+ * form, or an answer that does not belong to this exact call.
+ */
+export declare function personApproval<Ctx>(app: App<Ctx>, tool: Tool<Ctx>, rawArgs: Record<string, unknown>, ctx: ServerContext, env: NodeJS.ProcessEnv): Promise<ReturnType<typeof inputRequired> | undefined>;
+export {};