@thenavidm/slipway 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.8, 2026-10-05: what Midjourney and Substack needed
+
+- **HTTP checks Origin.** A request whose `Origin` is another site is refused unless `<PREFIX>_HTTP_ALLOWED_ORIGINS` lists it, as the MCP transport spec asks: a page in a browser can send a request to a localhost server, and only that header says where it came from. Clients that are not browsers send none and are unaffected. Substack's own server did this before it moved.
+- **`spends`: a call that costs money.** A paid generation needs confirming, `<PREFIX>_ALLOW_DESTRUCTIVE=0` refuses it, the CLI marks it `$`, and its refusal says it spends money that cannot be refunded, while clients still see a plain write, because making an image destroys nothing. Midjourney's ten generating tools are this.
+- **`flagAliases`: the spellings people already use.** `{ ar: "aspect" }` lets `--ar 16:9` set `aspect` on every command that has it, and help shows the alias beside the flag. `slipway check` fails an alias no input takes.
+- **`synonyms`, stopwords and exact names in search.** An app can map the words its users type onto the words its tools use, for `which` and the search surface; a query of filler words finds nothing instead of everything; and a term that is a tool's name, or a synonym pointing at it, wins outright. Midjourney's "make a picture" finds `imagine`, not `vary_image`.
+- **`--select` reaches into a result list.** When no path starts at the top and a result holds one list of records, the fields are selected inside it and the rest is kept: `--select id` on `{ count, jobs: [...] }` keeps the count and each job's id.
+- **An app command can own a flag Slipway also has.** `flags: ["--out"]` hands `--out` to the command instead of taking it as the global output flag. Midjourney's `capture --out` needs it.
+- **`login --help` prints the steps** for an app whose login is printed steps, not the general help.
+- **A command's own `--help` page reads as a sentence.** The line written for the command table, such as "capture a session for your publication once", starts with a capital and ends with a period on `login --help` and an app command's `--help`.
+- **Every command's `--help` is 10 tokens shorter.** `--select` and `--agent` say what they do in fewer words, and a read says `Risk: read`. Midjourney's `list-jobs --help` had grown 10 tokens on the move and is now the size 1.3.1's was.
+- **The unknown-command hint names one binary.** Typed at the MCP binary it said to list commands with `substack-cli` and find one with `substack-mcp which`; both now name the CLI binary.
+- **`install` says where settings go, not that they must be set.** Most settings are optional, and the notes no longer read as an order to set every one.
+
+## 0.1.7, 2026-10-05: what Threads and ThriveCart needed, and what Substack and WordPress will
+
+- **`riskFor`: a write whose arguments decide its risk.** Publishing is destructive and saving a draft is a write, from the same tool. `risk` stays the highest a call can be, which is what clients see in annotations and listings; the guard, the approval and the audit log go by the call, and only a destructive call needs confirming. WordPress's post tools need it: 1.1 confirmed publishing and not drafting.
+- **`onServe`: work that belongs to a running server.** It runs once the server is answering, over stdio or HTTP, and never for a CLI command, with the context and the server's logger; a throw is logged and the server keeps serving. Threads uses it to warn that a token expires this week, and Substack's queue of scheduled Notes needs it.
+- **A tool's own consequence.** `consequence` replaces "is public or cannot be undone" in the refusal and the approval form. ThriveCart's refund said it "is public" on Slipway and now says it "moves money or ends a customer's access and cannot be undone", as its own release did.
+- **`which` lists only the close matches.** Results scoring at least half of the best one, and always the top three. On Threads, "publish a post staged earlier" printed ten lines, 1,077 characters, where three carried the answer.
+- **`<PREFIX>_TOOLSETS` is listed only when some tool has a toolset.** With none, every tool is always on and the switch does nothing, so help and `agent-context` stop offering it.
+- **Tests from the servers that moved.** ThriveCart's cases for `--select` paths that share a head and for a list of choices typed as repeated words now run here, where that code lives.
+
 ## 0.1.6, 2026-10-05: what Mastodon's move needed
 
 - **`login` runs the app's own sign-in, with the words after it.** `mastodon-cli login mastodon.social --oob` hands `mastodon.social --oob` to Mastodon's flow, which registers an app on that instance and signs in. A flow given with `usage` and `help` shows them in help, `login --help` and `agent-context`, so nobody has to guess that it takes an instance.

package/README.md

@@ -213,6 +213,9 @@ The context is built on the first call that needs it, never at startup, and so i
 | `output` | Optional. Results are validated against it and sent as `structuredContent` |
 | `risk` | `read`, `write` (easy to undo) or `destructive` (public, irreversible, or both) |
 | `requireConfirm` | Defaults to true for destructive tools. Set it on a write that spends money |
+| `riskFor` | `(args) => risk`, when the arguments decide it: publishing is destructive, saving a draft is a write. `risk` stays the highest, which clients see; the guard, confirmation and audit log go by the call |
+| `spends` | The call spends money or credits, a paid generation: it needs confirming, `<PREFIX>_ALLOW_DESTRUCTIVE=0` refuses it, and the CLI marks it `$`, while clients still see a write |
+| `consequence` | What a confirmed call does, in the tool's own words for the refusal and the approval form: "moves money and cannot be undone". Defaults to "is public or cannot be undone" |
 | `idempotent`, `openWorld` | Annotation hints. Reads are idempotent by default; every tool is open world unless it never leaves the machine |
 | `tags` | Toolsets this tool belongs to. A tool with no tags is always on |
 | `summary` | One line for the refusal message and the audit log: "delete note 7" |
@@ -385,7 +388,7 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli>` | Every command, grouped by toolset, writes marked |
 | `<cli> <command> [flags]` | Run one tool |
 | `<cli> <command> --help` | Its flags, choices, defaults, examples and risk |
-| `<cli> which <words>` | Find the command for a task, by what it does |
+| `<cli> which <words>` | Find the command for a task, by what it does. An app's `synonyms` add the words its users type: `{ picture: ["image"] }` |
 | `<cli> schema <command>` | The JSON Schema an MCP client receives. `--output` for the result's |
 | `<cli> agent-context` | Commands, flags, risk, examples, exit codes and settings as JSON. `--brief` for just the commands, which ones write or need `--confirm`, and the exit codes |
 | `<cli> doctor` | Check the setup. `--network` also calls the service, which an app with `doctorNetwork` does every time |
@@ -395,7 +398,7 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli> <command>` from `commands` | A terminal command the app adds, such as `logout`. Listed in help and `agent-context`, never sent to an MCP client |
 | `<cli> completion bash` | Tab completion for bash, zsh or fish |
 
-Flags come from the schema: `--flag value`, `--flag=value`, the underscore spelling, `--no-flag` for a boolean, repeated or comma-separated lists of numbers and choices, and JSON or `@file.json` for an object. `--input` takes every argument as one JSON object, from the flag, a file or stdin, and flags on the same line override it.
+Flags come from the schema: `--flag value`, `--flag=value`, the underscore spelling, any name an app's `flagAliases` gives (`{ ar: "aspect" }` for `--ar 16:9`), `--no-flag` for a boolean, repeated or comma-separated lists of numbers and choices, and JSON or `@file.json` for an object. `--input` takes every argument as one JSON object, from the flag, a file or stdin, and flags on the same line override it.
 
 | Output flag | Shape |
 |---|---|
@@ -404,7 +407,7 @@ Flags come from the schema: `--flag value`, `--flag=value`, the underscore spell
 | `--jsonl` | One JSON value per line, for lists |
 | `--csv`, `--tsv` | A table, for lists of records |
 | `--quiet` | One value per line: ids, or the one `--select` field |
-| `--select a,b.c` | Keep only these fields. Dotted paths descend into arrays |
+| `--select a,b.c` | Keep only these fields. Dotted paths descend into arrays, and a field not at the top selects inside the one list a result holds, keeping the rest |
 | `--out <file>` | Write to a new file, readable only by you, never over an existing one |
 | `--wait` | For a job: wait until it finishes |
 | `--refresh` | Skip the local cache and fetch again |
@@ -429,7 +432,9 @@ Errors are JSON on stderr, always, with `error`, `code` and a `hint` that names
 | `<mcp>` | MCP over stdio, what a client launches |
 | `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health`. The app's `httpPort` replaces 8787, for a server that shipped another default |
 
-HTTP binds `127.0.0.1` and checks the Host header, so a web page cannot reach it through a name that resolves to localhost. It refuses to listen on any other address without `<PREFIX>_HTTP_TOKEN`, because anyone who reached the port would act as your account.
+HTTP binds `127.0.0.1` and checks the Host header, so a web page cannot reach it through a name that resolves to localhost, and it refuses a request whose Origin is another site unless `<PREFIX>_HTTP_ALLOWED_ORIGINS` lists it, as the MCP transport spec asks. It refuses to listen on any other address without `<PREFIX>_HTTP_TOKEN`, because anyone who reached the port would act as your account.
+
+Work that belongs to a running server goes in `onServe(ctx, log)`, which runs once the server is answering over either transport and never for a CLI command: a queue that publishes on time, or a warning that a token expires this week. A throw there is logged and the server keeps serving.
 
 Resources and prompts are optional and take a few lines each:
 
@@ -550,12 +555,13 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 | `<PREFIX>_CONFIRM` | `human` | `model` lets `confirm: true` alone confirm, for an agent with no person to ask |
 | `<PREFIX>_CACHE` | `1` | `0` never answers from the local cache |
 | `<PREFIX>_DATA_DIR` | the system's data folder | Where the local data file lives |
-| `<PREFIX>_TOOLSETS` | `all` | Comma-separated toolsets to turn on |
+| `<PREFIX>_TOOLSETS` | `all` | Comma-separated toolsets to turn on. Listed only when some tool has a toolset |
 | `<PREFIX>_SURFACE` | `full` | `search` lists three tools that find, describe and run the rest |
 | `<PREFIX>_TOOL_TIMEOUT_MS` | none | Give up on any tool after this long |
 | `<PREFIX>_HTTP_PORT` | `8787`, or the app's `httpPort` | For `--http` |
 | `<PREFIX>_HTTP_HOST` | `127.0.0.1` | For `--http`. Any other address needs a token |
 | `<PREFIX>_HTTP_TOKEN` | none | Bearer token required by `--http` |
+| `<PREFIX>_HTTP_ALLOWED_ORIGINS` | none | Browser origins beyond localhost that may call `--http`, comma-separated |
 | `<PREFIX>_DEBUG` | `0` | `1` prints debug lines on stderr |
 
 ## Versions
@@ -567,7 +573,10 @@ See [CHANGELOG.md](CHANGELOG.md).
 | Server | Package | Covers |
 | --- | --- | --- |
 | [Bluesky](https://github.com/thenavidm/bluesky-mcp-cli) | [`@thenavidm/bluesky-mcp-cli`](https://www.npmjs.com/package/@thenavidm/bluesky-mcp-cli) 2.0.0 | Posting, threads, replies, the timeline, search, feeds, lists, notifications and the social graph |
+| [Mastodon](https://github.com/thenavidm/mastodon-mcp-cli) | [`@thenavidm/mastodon-mcp-cli`](https://www.npmjs.com/package/@thenavidm/mastodon-mcp-cli) 2.0.0 | Posting, editing, threads, timelines, search, lists, notifications and following, on any instance |
 | [Teachable](https://github.com/thenavidm/teachable-mcp-cli) | [`@thenavidm/teachable-mcp-cli`](https://www.npmjs.com/package/@thenavidm/teachable-mcp-cli) 3.0.0 | Courses, users, enrollments, pricing, coupons and transactions |
+| [Threads](https://github.com/thenavidm/threads-mcp-cli) | [`@thenavidm/threads-mcp-cli`](https://www.npmjs.com/package/@thenavidm/threads-mcp-cli) 2.0.0 | Posting, threads, carousels, replies and reply approvals, insights and keyword search |
+| [ThriveCart](https://github.com/thenavidm/thrivecart-mcp-cli) | [`@thenavidm/thrivecart-mcp-cli`](https://www.npmjs.com/package/@thenavidm/thrivecart-mcp-cli) 3.0.0 | Products and pricing, transactions and revenue, customers, subscriptions and affiliates, across several carts |
 
 Each server was measured against its previous release before it moved: startup, what a client receives, CLI exit codes, and tokens in Claude Code and Codex. Its README has the numbers.
 

package/dist/app.d.ts

@@ -79,6 +79,11 @@ export type CliCommand = {
     usage?: string;
     /** One line: what it does. */
     help: string;
+    /**
+     * Flags the command reads itself, such as `--out`, which would otherwise be
+     * taken as Slipway's global flag of the same name before the command sees it.
+     */
+    flags?: readonly string[];
     run: (io: CliIO, args: string[]) => number | Promise<number>;
 };
 export type AppDefinition<Ctx> = {
@@ -129,6 +134,13 @@ export type AppDefinition<Ctx> = {
      * a scope.
      */
     doctorNetwork?: boolean;
+    /**
+     * Runs once the server is answering, over stdio or HTTP, and never for a CLI
+     * command. For work that belongs to a running server, such as a queue that
+     * publishes on time, or a warning such as a token about to expire. It gets
+     * the context and the server's stderr logger; a throw is logged, never fatal.
+     */
+    onServe?: (ctx: Ctx, log: Logger) => void | Promise<void>;
     /**
      * How to sign in: printed instructions, or an interactive flow that returns an
      * exit code. A flow gets the words after `login`: `mastodon-cli login mastodon.social`.
@@ -140,6 +152,19 @@ export type AppDefinition<Ctx> = {
         help: string;
         run: LoginFlow;
     };
+    /**
+     * Other names a flag answers to, on every command that has the input:
+     * `{ ar: "aspect" }` lets `--ar 16:9` set `aspect`, as Midjourney's own
+     * syntax spells it. Help shows each beside its flag, and `slipway check`
+     * fails one that no tool's input can take.
+     */
+    flagAliases?: Readonly<Record<string, string>>;
+    /**
+     * Words people type, mapped onto words the tools use, for `which` and the
+     * search surface: `{ picture: ["image"] }`. Without them a lookup works only
+     * for someone who already knows the vocabulary.
+     */
+    synonyms?: Readonly<Record<string, readonly string[]>>;
     /**
      * Terminal commands beyond the tools, such as `logout`, `auth` or `refresh`.
      * An MCP client never sees them. Each is listed in help and `agent-context`,

package/dist/app.js

@@ -18,7 +18,7 @@ import { isContentResult } from "./result.js";
 import { formatIssues, validate } from "./schema.js";
 import { buildServer } from "./server.js";
 import { localDataTools } from "./sync.js";
-import { defineTool, isTool, summarize } from "./tool.js";
+import { defineTool, forCall, isTool, summarize } from "./tool.js";
 const SLUG = /^[a-z][a-z0-9-]{0,40}$/;
 export function stderrLogger(prefix, env) {
     const debug = /^(1|true|yes)$/i.test(env[`${prefix}_DEBUG`] ?? "");
@@ -140,7 +140,7 @@ export function slipway(definition) {
             assertVisible(tool, policy, envPrefix);
             const { confirm: _confirm, ...args } = rawArgs;
             const summary = summarize(tool, args);
-            new Guard(policy, options.surface, envPrefix).preflight(tool, summary);
+            new Guard(policy, options.surface, envPrefix).preflight(forCall(tool, args), summary);
             return summary;
         },
         async run(tool, rawArgs, options) {
@@ -152,8 +152,10 @@ export function slipway(definition) {
             const confirmedBy = options.approvedBy ?? (options.confirmed === true || confirm === true ? "flag" : undefined);
             const dryRun = options.dryRun === true;
             const summary = summarize(tool, args);
+            // What this call risks, which `riskFor` may put below the tool's declared risk.
+            const call = forCall(tool, args);
             const guard = new Guard(policy, options.surface, envPrefix);
-            guard.check(tool, { confirmedBy, dryRun, summary });
+            guard.check(call, { confirmedBy, dryRun, summary });
             const ctx = await app.context(env);
             const timeoutMs = tool.timeoutMs ?? policy.toolTimeoutMs;
             const withDeadline = () => deadlineSignal(options.signal, timeoutMs);
@@ -168,7 +170,7 @@ export function slipway(definition) {
                     surface: options.surface,
                     env,
                     dryRun,
-                    tool: { name: tool.name, risk: tool.risk },
+                    tool: { name: tool.name, risk: call.risk },
                     secrets,
                     log,
                     async progress(progress, total, message) {
@@ -182,7 +184,7 @@ export function slipway(definition) {
                 const wouldRun = tool.preview ? await tool.preview(args, toolContext) : args;
                 return { dry_run: true, tool: tool.name, summary, would_run: secrets.redactDeep(wouldRun) };
             }
-            const writes = tool.risk !== "read" || tool.requireConfirm;
+            const writes = call.risk !== "read" || call.requireConfirm;
             const cache = tool.cache && policy.cache ? { scope: app.dataScope(ctx), key: cacheKey(args), ttlSeconds: tool.cache.ttlSeconds } : undefined;
             if (cache && !options.refresh) {
                 const hit = await quietly(log, async () => (await app.localData(env)).cacheGet(cache.scope, tool.name, cache.key));
@@ -227,7 +229,7 @@ export function slipway(definition) {
                     result = await untilAborted(Promise.resolve(tool.handler(args, toolContext)), signal, timeoutMs, tool.name);
                 }
                 if (writes)
-                    guard.record(tool, summary, result?.done === false ? "started" : "done");
+                    guard.record(call, summary, result?.done === false ? "started" : "done");
                 await forget();
                 // Only data is cached. Images and files are fetched again.
                 if (cache && !isContentResult(result)) {
@@ -238,7 +240,7 @@ export function slipway(definition) {
             }
             catch (error) {
                 if (writes)
-                    guard.record(tool, summary, "failed");
+                    guard.record(call, summary, "failed");
                 await forget();
                 throw toSlipwayError(error);
             }

package/dist/check.js

@@ -55,6 +55,20 @@ export async function checkApp(app, options = {}) {
             add("error", "names", `The terminal command '${command.name}' has the name of a built-in or a tool. Rename it.`);
         }
     }
+    for (const [alias, key] of Object.entries(app.definition.flagAliases ?? {})) {
+        const takes = app.allTools.some((tool) => Object.keys(tool.jsonSchema.properties ?? {}).includes(key));
+        if (!takes)
+            add("error", "names", `--${alias} points at '${key}', which no tool's input has.`);
+    }
+    // A synonym pointing at a word no tool uses is a redirect to nowhere that quietly stops matching.
+    const vocabulary = new Set(app.allTools.flatMap((tool) => `${tool.name} ${tool.title} ${tool.description}`.toLowerCase().split(/[^a-z0-9]+/)));
+    for (const [word, targets] of Object.entries(app.definition.synonyms ?? {})) {
+        for (const target of targets) {
+            if (!vocabulary.has(target.toLowerCase()) && !app.allTools.some((tool) => tool.name === target)) {
+                add("warn", "synonyms", `'${word}' points at '${target}', which no tool's name, title or description uses.`);
+            }
+        }
+    }
     const httpPort = app.definition.httpPort;
     if (httpPort !== undefined && (!Number.isInteger(httpPort) || httpPort < 1 || httpPort > 65535)) {
         add("error", "http", `httpPort is ${httpPort}, which is not a port number from 1 to 65535.`);

package/dist/cli/context.d.ts

@@ -34,6 +34,7 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
         title: string;
         risk?: "destructive" | "write" | undefined;
         requires_confirm?: boolean | undefined;
+        spends?: boolean | undefined;
     }[];
 } | {
     name: string;
@@ -96,6 +97,7 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
         description: string;
         risk: import("../tool.js").Risk;
         requires_confirm: boolean;
+        spends?: boolean | undefined;
         toolsets?: readonly string[] | undefined;
         positional?: readonly string[] | undefined;
         flags: {

package/dist/cli/context.js

@@ -51,6 +51,7 @@ export function agentContext(app, env, bin, options = {}) {
                 title: tool.title,
                 ...(tool.risk !== "read" ? { risk: tool.risk } : {}),
                 ...(tool.requireConfirm ? { requires_confirm: true } : {}),
+                ...(tool.spends ? { spends: true } : {}),
             })),
         };
     }
@@ -78,8 +79,10 @@ export function agentContext(app, env, bin, options = {}) {
                 description: setting.description,
             })),
             { env: names.readOnly, value: policy.readOnly, description: "hide and refuse every write" },
-            { env: names.allowDestructive, value: policy.allowDestructive, description: "allow public or irreversible writes" },
-            { env: names.toolsets, value: policy.toolsets === "all" ? "all" : [...policy.toolsets], description: "toolsets that are on" },
+            { env: names.allowDestructive, value: policy.allowDestructive, description: app.allTools.some((tool) => tool.spends) ? "allow public or irreversible writes and paid calls" : "allow public or irreversible writes" },
+            ...(app.allTools.some((tool) => tool.tags.length > 0)
+                ? [{ env: names.toolsets, value: policy.toolsets === "all" ? "all" : [...policy.toolsets], description: "toolsets that are on" }]
+                : []),
             { env: names.surface, value: policy.surface, description: "full tool list, or search for very large catalogs" },
             { env: names.auditLog, value: policy.auditLog ?? null, description: "file that records every attempted write" },
             { env: names.toolTimeoutMs, value: policy.toolTimeoutMs ?? null, description: "deadline for any tool" },
@@ -87,6 +90,7 @@ export function agentContext(app, env, bin, options = {}) {
             { env: `${app.envPrefix}_HTTP_PORT`, value: env[`${app.envPrefix}_HTTP_PORT`] ?? null, description: `port for --http, ${app.definition.httpPort ?? 8787} when unset` },
             { env: `${app.envPrefix}_HTTP_HOST`, value: env[`${app.envPrefix}_HTTP_HOST`] ?? null, description: "address for --http, 127.0.0.1 when unset; any other needs a token" },
             { env: `${app.envPrefix}_HTTP_TOKEN`, set: Boolean(env[`${app.envPrefix}_HTTP_TOKEN`]), secret: true, description: "bearer token --http requires" },
+            { env: `${app.envPrefix}_HTTP_ALLOWED_ORIGINS`, value: env[`${app.envPrefix}_HTTP_ALLOWED_ORIGINS`] ?? null, description: "browser origins beyond localhost that may call --http, comma-separated" },
             { env: `${app.envPrefix}_DEBUG`, value: /^(1|true|yes)$/i.test(env[`${app.envPrefix}_DEBUG`] ?? ""), description: "print debug lines on stderr" },
         ],
         ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
@@ -99,6 +103,7 @@ export function agentContext(app, env, bin, options = {}) {
             description: tool.description,
             risk: tool.risk,
             requires_confirm: tool.requireConfirm,
+            ...(tool.spends ? { spends: true } : {}),
             ...(tool.tags.length ? { toolsets: tool.tags } : {}),
             ...(tool.positional.length ? { positional: tool.positional } : {}),
             flags: flagsFor(tool.jsonSchema)

package/dist/cli/data.js

@@ -64,7 +64,7 @@ export async function runData(app, io, tokens, options) {
                 const lists = app.allTools.filter((candidate) => candidate.sync).map((candidate) => candidate.command);
                 throw new UsageError(`${tool.command} is not a list that can be synced.`, { hint: `Lists that can: ${lists.join(", ") || "none"}.` });
             }
-            const args = await app.parse(tool, parseToolArgs(flags, flagsFor(tool.jsonSchema), tool.positional));
+            const args = await app.parse(tool, parseToolArgs(flags, flagsFor(tool.jsonSchema), tool.positional, app.definition.flagAliases));
             const report = await syncTool(app, tool, args, {
                 surface: "cli",
                 env: io.env,

package/dist/cli/flags.d.ts

@@ -31,5 +31,5 @@ export declare function parseJsonValue(raw: string, label: string): unknown;
  * positional arguments. The schema validates the result afterwards; this only
  * gets values into the right types and reports mistakes in terms of flags.
  */
-export declare function parseToolArgs(argv: readonly string[], flags: readonly Flag[], positional: readonly string[]): Record<string, unknown>;
+export declare function parseToolArgs(argv: readonly string[], flags: readonly Flag[], positional: readonly string[], aliases?: Readonly<Record<string, string>>): Record<string, unknown>;
 export declare function missingRequired(flags: readonly Flag[], args: Record<string, unknown>): Flag[];

package/dist/cli/flags.js

@@ -118,7 +118,7 @@ function splits(flag) {
  * positional arguments. The schema validates the result afterwards; this only
  * gets values into the right types and reports mistakes in terms of flags.
  */
-export function parseToolArgs(argv, flags, positional) {
+export function parseToolArgs(argv, flags, positional, aliases = {}) {
     const out = {};
     const bare = [];
     const byName = new Map();
@@ -126,6 +126,12 @@ export function parseToolArgs(argv, flags, positional) {
         byName.set(flag.flag, flag);
         byName.set(`--${flag.key}`, flag);
     }
+    // An alias never shadows a real flag of the same name.
+    for (const [alias, key] of Object.entries(aliases)) {
+        const flag = flags.find((candidate) => candidate.key === key);
+        if (flag && !byName.has(`--${alias}`))
+            byName.set(`--${alias}`, flag);
+    }
     const assign = (flag, value) => {
         if (flag.repeatable) {
             const values = Array.isArray(value) ? value : [value];

package/dist/cli/help.d.ts

@@ -12,7 +12,7 @@ export declare const GLOBAL_FLAGS: Array<[string, string]>;
 export declare function renderList(app: App, tools: readonly Tool[], bin: string, env?: NodeJS.ProcessEnv): string;
 /** An example's arguments as the command someone would type. */
 export declare function exampleCommand(bin: string, tool: Tool, args: Record<string, unknown>): string;
-export declare function renderToolHelp(tool: Tool, bin: string): string;
+export declare function renderToolHelp(tool: Tool, bin: string, aliases?: Readonly<Record<string, string>>): string;
 export declare function renderGeneralHelp(app: App, bin: string): string;
 /** One line per tool, for search results and listings. */
 export declare function toolLine(tool: Tool): string;

package/dist/cli/help.js

@@ -17,8 +17,8 @@ export const GLOBAL_FLAGS = [
     ["--jsonl", "one JSON value per line, for lists"],
     ["--csv / --tsv", "a table, for lists of records"],
     ["--quiet", "one value per line: ids, or the one --select field"],
-    ["--select <a,b.c>", "keep only these fields; dotted paths descend"],
-    ["--agent", "JSON, compact, no prompts, no color. Never confirms anything"],
+    ["--select <a,b.c>", "keep only these fields"],
+    ["--agent", "compact JSON, no prompts, never confirms"],
     ["--out <file>", "write the output to a new file instead of stdout"],
     ["--input <json|@file|->", "all arguments as one JSON object; flags override it"],
     ["--dry-run", "check everything and print what would run, without running it"],
@@ -32,7 +32,9 @@ function line(left, help) {
     return left.length < COLUMN ? [`${left.padEnd(COLUMN)}${help}`] : [left, `${" ".repeat(COLUMN)}${help}`];
 }
 function riskWords(tool) {
-    return tool.risk === "read" ? "read only" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
+    if (tool.spends)
+        return "spends money, needs --confirm";
+    return tool.risk === "read" ? "read" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
 }
 /** The output flags a command can use: the four every command takes, and those its kind adds. */
 function outputFlagsFor(tool) {
@@ -92,11 +94,12 @@ export function renderList(app, tools, bin, env = process.env) {
         if (grouped)
             lines.push(``, `  ${group || "general"}${group && toolsets[group] ? `: ${toolsets[group]}` : ""}`);
         for (const tool of members)
-            lines.push(`  ${riskMark(tool.risk)} ${tool.command.padEnd(width)}${tool.title}`);
+            lines.push(`  ${riskMark(tool)} ${tool.command.padEnd(width)}${tool.title}`);
     }
     // The legend says `!` needs --confirm only when that holds for every listed command.
-    const confirmByRisk = tools.every((tool) => tool.requireConfirm === (tool.risk === "destructive"));
-    lines.push(``, `  * writes    ! public or irreversible${confirmByRisk ? ", needs --confirm" : ""}`, ``, `  ${bin} <command> --help    what one takes, with examples`, `  ${bin} which <words>       find the command for a task`, `  ${bin} --help              flags, settings and setup`, ``, ...hiddenNote(app, env));
+    const confirmByRisk = tools.every((tool) => tool.requireConfirm === (tool.risk === "destructive" || tool.spends));
+    const paid = tools.some((tool) => tool.spends) ? "    $ spends money, needs --confirm" : "";
+    lines.push(``, `  * writes    ! public or irreversible${confirmByRisk ? ", needs --confirm" : ""}${paid}`, ``, `  ${bin} <command> --help    what one takes, with examples`, `  ${bin} which <words>       find the command for a task`, `  ${bin} --help              flags, settings and setup`, ``, ...hiddenNote(app, env));
     return lines.join("\n");
 }
 function shellQuote(value) {
@@ -136,7 +139,8 @@ function placeholder(flag) {
         return flag.choices.length <= 6 ? ` <${flag.choices.join("|")}>` : " <choice>";
     return ` <${flag.kind === "json" ? "json|@file" : flag.kind}>`;
 }
-export function renderToolHelp(tool, bin) {
+export function renderToolHelp(tool, bin, aliases = {}) {
+    const aliasOf = (key) => Object.entries(aliases).filter(([, target]) => target === key).map(([alias]) => `, --${alias}`).join("");
     const flags = flagsFor(tool.jsonSchema).filter((flag) => flag.key !== "confirm");
     const required = flags.filter((flag) => flag.required);
     const optional = flags.filter((flag) => !flag.required);
@@ -159,7 +163,7 @@ export function renderToolHelp(tool, bin) {
             const extra = [flag.repeatable ? "Repeatable." : "", flag.default !== undefined ? `Default ${JSON.stringify(flag.default)}.` : ""]
                 .filter(Boolean)
                 .join(" ");
-            lines.push(...line(`  ${flag.flag}${placeholder(flag)}`, [flag.help, extra].filter(Boolean).join(" ")));
+            lines.push(...line(`  ${flag.flag}${aliasOf(flag.key)}${placeholder(flag)}`, [flag.help, extra].filter(Boolean).join(" ")));
         }
         lines.push(...after, ``);
     };
@@ -215,15 +219,16 @@ export function renderGeneralHelp(app, bin) {
     const settings = [
         ...(app.definition.settings ?? []).filter((setting) => !setting.tuning).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
-        [`${names.allowDestructive}=0`, "refuse the irreversible writes"],
-        [`${names.toolsets}=a,b`, "only these toolsets, or all"],
+        [`${names.allowDestructive}=0`, app.allTools.some((tool) => tool.spends) ? "refuse the irreversible writes and paid calls" : "refuse the irreversible writes"],
+        // With no tagged tool every tool is always on, so the switch would do nothing.
+        ...(app.allTools.some((tool) => tool.tags.length > 0) ? [[`${names.toolsets}=a,b`, "only these toolsets, or all"]] : []),
         [`${names.surface}=search`, "MCP lists three finder tools instead"],
         [`${names.auditLog}=<file>`, "log every attempted write"],
         [`${names.toolTimeoutMs}=<ms>`, "deadline for any tool"],
         [`${names.confirm}=model`, "confirm: true alone confirms over MCP"],
         ...(cache ? [[`${names.cache}=0`, "never answer from the local cache"]] : []),
         ...(cache || sync ? [[`${names.dataDir}=<dir>`, "keep local data in this folder"]] : []),
-        [`${app.envPrefix}_HTTP_PORT / _HOST / _TOKEN`, "for --http"],
+        [`${app.envPrefix}_HTTP_PORT / _HOST / _TOKEN / _ALLOWED_ORIGINS`, "for --http"],
         [`${app.envPrefix}_DEBUG=1`, "debug lines on stderr"],
     ];
     // Flags that cannot apply here (jobs, the cache) are left out; agent-context lists every one.
@@ -252,5 +257,5 @@ export function renderGeneralHelp(app, bin) {
 }
 /** One line per tool, for search results and listings. */
 export function toolLine(tool) {
-    return `${riskMark(tool.risk)} ${tool.command}  ${tool.title}: ${firstSentence(tool.description, 80)}`;
+    return `${riskMark(tool)} ${tool.command}  ${tool.title}: ${firstSentence(tool.description, 80)}`;
 }

package/dist/cli/output.js

@@ -16,6 +16,19 @@ export function selectFields(data, paths) {
         return data.map((item) => selectFields(item, paths));
     if (data === null || typeof data !== "object")
         return data;
+    const record = data;
+    // `--select id,status` on `{ count, jobs: [...] }` means the jobs' fields. When no path
+    // starts at the top and the result holds one list of records, select inside it and keep
+    // the rest as it is. A list of plain values, such as image URLs, is not a result set.
+    const heads = paths.map((path) => path.split(".")[0]).filter((head) => Boolean(head));
+    if (heads.length && heads.every((head) => !(head in record))) {
+        const isRecord = (item) => item !== null && typeof item === "object" && !Array.isArray(item);
+        const arrays = Object.entries(record).filter(([, value]) => Array.isArray(value));
+        const lists = arrays.filter(([, value]) => value.length > 0 && value.every(isRecord));
+        const only = lists.length === 1 ? lists[0] : lists.length === 0 && arrays.length === 1 && arrays[0][1].length === 0 ? arrays[0] : undefined;
+        if (only)
+            return { ...record, [only[0]]: only[1].map((item) => selectFields(item, paths)) };
+    }
     // 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();

package/dist/cli/run.js

@@ -142,7 +142,7 @@ export async function runCli(app, argv, partial = {}) {
     const builtin = command !== undefined && BUILTINS.includes(command);
     const custom = command !== undefined && !builtin ? app.definition.commands?.find((candidate) => candidate.name === command) : undefined;
     const tool = command !== undefined && !builtin && !custom ? app.find(command) : undefined;
-    const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : []);
+    const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : (custom?.flags ?? []));
     let agent = argv.includes("--agent");
     try {
         const { globals, rest } = extractGlobals(at === -1 ? argv : [...argv.slice(0, at), ...argv.slice(at + 1)], reserved);
@@ -158,14 +158,14 @@ export async function runCli(app, argv, partial = {}) {
             return await runBuiltin(app, io, command, rest, globals);
         if (custom) {
             if (globals.help)
-                return print(io, `\nUsage: ${io.bin} ${custom.usage ?? custom.name}\n\n${custom.help}\n`);
+                return print(io, `\nUsage: ${io.bin} ${custom.usage ?? custom.name}\n\n${sentence(custom.help)}\n`);
             return await custom.run(io, rest);
         }
         if (!tool) {
             const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS, ...(app.definition.commands ?? []).map((c) => c.name)];
             const guess = didYouMean(command, candidates);
             throw new UsageError(`Unknown command '${command}'.${guess ? ` Did you mean '${guess}'?` : ""}`, {
-                hint: `Run \`${app.bins.cli}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
+                hint: `Run \`${app.bins.cli}\` to list commands, or \`${app.bins.cli} which <words>\` to find one.`,
             });
         }
         const seen = visibility(tool, app.policy(io.env));
@@ -176,14 +176,14 @@ export async function runCli(app, argv, partial = {}) {
                 : `${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 print(io, renderToolHelp(tool, io.bin, app.definition.flagAliases));
         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));
+            io.stderr(renderToolHelp(tool, io.bin, app.definition.flagAliases));
         return failure.exitCode;
     }
 }
@@ -204,7 +204,10 @@ async function runBuiltin(app, io, command, rest, globals) {
         return print(io, (await import("./install.js")).installHelp(app, io.bin));
     const login = app.definition.login;
     if (globals.help && command === "login" && typeof login === "object")
-        return print(io, `\nUsage: ${io.bin} ${login.usage ?? "login"}\n\n${login.help}\n`);
+        return print(io, `\nUsage: ${io.bin} ${login.usage ?? "login"}\n\n${sentence(login.help)}\n`);
+    // Printed steps are their own help.
+    if (globals.help && command === "login" && typeof login === "string")
+        return print(io, login);
     if (globals.help && command !== "help")
         return print(io, renderGeneralHelp(app, io.bin));
     const target = rest.find((token) => !token.startsWith("-"));
@@ -219,7 +222,7 @@ async function runBuiltin(app, io, command, rest, globals) {
             const tool = app.find(target);
             if (!tool)
                 throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
-            return print(io, renderToolHelp(tool, io.bin));
+            return print(io, renderToolHelp(tool, io.bin, app.definition.flagAliases));
         }
         case "schema": {
             const tool = target ? app.find(target) : undefined;
@@ -238,7 +241,11 @@ async function runBuiltin(app, io, command, rest, globals) {
             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);
+            // Only the close matches: on Threads the right command scored 20 and the eighth 9, and the
+            // ten-line list cost an agent more to read than the answer was worth.
+            const found = searchTools(app.tools(io.env), query, 10, app.definition.synonyms);
+            const best = found[0]?.score ?? 0;
+            const matches = found.filter(({ score }, index) => index < 3 || score >= best / 2);
             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)) }))));
             }
@@ -281,7 +288,7 @@ async function readInput(io, raw) {
 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) };
+    const args = { ...base, ...parseToolArgs(rest, flags, tool.positional, app.definition.flagAliases) };
     if (globals.confirm && tool.requireConfirm)
         args.confirm = true;
     const missing = missingRequired(flags, args).filter((flag) => !(globals.all && tool.paginate && flag.key === tool.paginate.cursorArg));
@@ -357,3 +364,10 @@ function writeOut(io, globals, tool, result) {
     io.stdout(`${JSON.stringify({ saved: globals.out, bytes: Buffer.byteLength(text) })}\n`);
     return EXIT.ok;
 }
+/** A help line written for the command table reads as a sentence on its own `--help` page. */
+function sentence(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return trimmed;
+    return `${trimmed[0].toUpperCase()}${trimmed.slice(1)}${/[.!?:]$/.test(trimmed) ? "" : "."}`;
+}

package/dist/confirm.d.ts

@@ -64,7 +64,7 @@ export declare const verifyApprovalState: (state: string, ctx: ServerContext) =>
  * 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): {
+export declare function approvalForm(appTitle: string, tool: Pick<Tool, "risk" | "consequence" | "spends">, summary: string): {
     message: string;
     requestedSchema: {
         type: "object";

package/dist/docs.js

@@ -52,7 +52,7 @@ export function settingsTable(app) {
         "|---|---|",
         ...(app.definition.settings ?? []).map((setting) => `| \`${setting.env}\` | ${cell(setting.description)}${setting.secret ? " Keep it private." : ""} |`),
         `| \`${names.readOnly}=1\` | Hide and refuse every write |`,
-        `| \`${names.allowDestructive}=0\` | Keep writes, refuse the public or irreversible ones |`,
+        `| \`${names.allowDestructive}=0\` | Keep writes, refuse the public or irreversible ones${app.allTools.some((tool) => tool.spends) ? " and paid calls" : ""} |`,
         `| \`${names.toolsets}\` | Comma-separated toolsets to turn on, or \`all\` |`,
         `| \`${names.surface}=search\` | List three tools that find, describe and run the rest |`,
         `| \`${names.auditLog}\` | File that records every attempted write |`,

package/dist/doctor.js

@@ -16,7 +16,8 @@ export async function runDoctor(app, io, options) {
     const major = Number(process.versions.node.split(".")[0]);
     checks.push({ name: "Node.js", ok: major >= 22, detail: `v${process.versions.node}`, ...(major >= 22 ? {} : { fix: "Install Node.js 22 or later." }) });
     checks.push({ name: "Version", ok: true, detail: `${app.name} ${app.version}` });
-    const writes = policy.readOnly ? "off (read-only)" : policy.allowDestructive ? "on" : "on, irreversible ones refused";
+    const paid = app.allTools.some((tool) => tool.spends) ? " and paid" : "";
+    const writes = policy.readOnly ? "off (read-only)" : policy.allowDestructive ? "on" : `on, irreversible${paid} ones refused`;
     checks.push({ name: "Writes", ok: true, detail: writes });
     checks.push({
         name: "Tools",

package/dist/guard.d.ts

@@ -43,4 +43,4 @@ export declare class Guard {
     record(tool: Tool, summary: string, outcome: GuardOutcome | "failed" | "done" | "started", confirmedBy?: ConfirmedBy): void;
 }
 /** Why a tool needs confirming, in the words a refusal and an approval form both use. */
-export declare function consequence(tool: Pick<Tool, "risk">): string;
+export declare function consequence(tool: Pick<Tool, "risk" | "consequence" | "spends">): string;

package/dist/guard.js

@@ -41,10 +41,10 @@ export class Guard {
                 hint: `Unset ${names.readOnly} to allow writes.`,
             });
         }
-        if (tool.risk === "destructive" && !this.policy.allowDestructive) {
+        if ((tool.risk === "destructive" || tool.spends) && !this.policy.allowDestructive) {
             this.record(tool, summary, "blocked: destructive disabled");
             throw new RefusedError(`${tool.name} is unavailable: this server is running with ${names.allowDestructive}=0.`, {
-                hint: `Unset ${names.allowDestructive} to allow irreversible writes.`,
+                hint: `Unset ${names.allowDestructive} to allow irreversible writes${tool.spends ? " and paid calls" : ""}.`,
             });
         }
     }
@@ -85,5 +85,9 @@ export class Guard {
 }
 /** Why a tool needs confirming, in the words a refusal and an approval form both use. */
 export function consequence(tool) {
+    if (tool.consequence)
+        return tool.consequence;
+    if (tool.spends)
+        return "spends money and cannot be refunded";
     return tool.risk === "destructive" ? "is public or cannot be undone" : "has an effect that cannot be taken back";
 }

package/dist/install.js

@@ -215,7 +215,7 @@ export function planInstall(app, options, context) {
     if (client === "claude-code") {
         const entry = { type: "stdio", command: launch.command, args: launch.args };
         if (variables.length)
-            notes.push(`Claude Code passes its own environment to the server: set ${list(variables)} in the shell you start Claude Code from.`);
+            notes.push(`Claude Code passes its own environment to the server, so whichever of ${list(variables)} you use go in the shell you start Claude Code from.`);
         return { client, scope, name, entry, env, notes, run: { command: "claude", args: ["mcp", "add-json", name, JSON.stringify(entry), "--scope", scope] } };
     }
     if (client === "codex") {
@@ -223,7 +223,7 @@ export function planInstall(app, options, context) {
         const before = existsSync(file) ? readFileSync(file, "utf8") : "";
         const text = upsertCodexServer(before, name, launch, variables, usesNpx);
         if (variables.length)
-            notes.push(`Codex passes ${list(variables)} on from its own environment: set ${them(variables)} where you start Codex.`);
+            notes.push(`Codex passes ${list(variables)} on from its own environment, so whichever you use go where you start Codex.`);
         if (scope === "project")
             notes.push("Codex reads a project's .codex/config.toml only once the project is trusted.");
         const entry = upsertCodexServer("", name, launch, variables, usesNpx).trim();
@@ -290,7 +290,7 @@ export function planInstall(app, options, context) {
         if (env.copied.length)
             notes.push(`Copied ${list(env.copied)} from this shell into ${file}, which is now readable by you only.`);
         if (env.toAdd.length) {
-            notes.push(`Claude Desktop does not read a shell's environment. Add ${list(env.toAdd)} to the env of "${name}" in ${file}, or run install again with --copy-env to copy ${them(env.toAdd)} from this shell.`);
+            notes.push(`Claude Desktop does not read a shell's environment, so whichever of ${list(env.toAdd)} you use go in the env of "${name}" in ${file}, or run install again with --copy-env to copy them from this shell.`);
         }
     }
     return { client, scope, name, file, entry: server, text: `${JSON.stringify(next, null, 2)}\n`, env, notes };

package/dist/policy.d.ts

@@ -63,4 +63,7 @@ export type Visibility = {
 };
 /** Whether a tool is on under this policy, and if not, why, so a refusal can say how to turn it on. */
 export declare function visibility(tool: Pick<Tool, "risk" | "tags">, policy: Policy): Visibility;
-export declare function riskMark(risk: Risk): string;
+export declare function riskMark(tool: {
+    risk: Risk;
+    spends?: boolean;
+}): string;

package/dist/policy.js

@@ -69,6 +69,6 @@ export function visibility(tool, policy) {
     }
     return { visible: true };
 }
-export function riskMark(risk) {
-    return risk === "read" ? " " : risk === "destructive" ? "!" : "*";
+export function riskMark(tool) {
+    return tool.spends ? "$" : tool.risk === "read" ? " " : tool.risk === "destructive" ? "!" : "*";
 }

package/dist/search.d.ts

@@ -10,7 +10,7 @@ export type Match = {
     tool: Tool;
     score: number;
 };
-export declare function searchTools(tools: readonly Tool[], query: string, limit?: number): Match[];
+export declare function searchTools(tools: readonly Tool[], query: string, limit?: number, synonyms?: Readonly<Record<string, readonly string[]>>): Match[];
 /** Edit distance, for "did you mean" on a mistyped command. */
 export declare function distance(a: string, b: string): number;
 export declare function didYouMean(input: string, candidates: readonly string[]): string | undefined;

package/dist/search.js

@@ -5,6 +5,11 @@
  * from the words someone would use to ask for it. The same ranking answers
  * `which` in a terminal and `search_tools` for a model.
  */
+/** Words a query carries that say nothing about which tool: "how do I get my images". */
+const STOP_WORDS = new Set([
+    "the", "my", "me", "to", "of", "for", "in", "on", "and", "or", "how", "do", "does", "can", "want",
+    "with", "from", "is", "are", "it", "that", "this", "what", "which", "any", "some", "please", "an",
+]);
 function words(text) {
     return text
         .toLowerCase()
@@ -12,6 +17,13 @@ function words(text) {
         .filter((word) => word.length > 1)
         .map(stem);
 }
+function queryWords(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 1 && !STOP_WORDS.has(word))
+        .map(stem);
+}
 /** Close enough for matching "posts" to "post" and "scheduling" to "schedul". */
 function stem(word) {
     if (word.length > 4 && word.endsWith("ies"))
@@ -48,23 +60,32 @@ const RELATED = new Map();
 for (const group of SYNONYMS)
     for (const word of group)
         RELATED.set(word, [...new Set([...(RELATED.get(word) ?? []), ...group])]);
-function hits(query, haystack) {
+function hits(query, haystack, extra) {
     const direct = exact(query, haystack);
     if (direct > 0)
         return direct;
     // A synonym counts for a little less than the word itself, so an exact match still wins.
-    return (RELATED.get(query) ?? []).some((word) => word !== query && exact(word, haystack) === 1) ? 0.75 : 0;
+    const related = [...(RELATED.get(query) ?? []), ...(extra?.get(query) ?? [])];
+    return related.some((word) => word !== query && exact(word, haystack) === 1) ? 0.75 : 0;
 }
 function exact(query, haystack) {
     if (haystack.includes(query))
         return 1;
     return haystack.some((word) => word.startsWith(query) || query.startsWith(word)) ? 0.5 : 0;
 }
-export function searchTools(tools, query, limit = 10) {
-    const terms = [...new Set(words(query))];
+export function searchTools(tools, query, limit = 10, synonyms = {}) {
+    const terms = [...new Set(queryWords(query))];
     if (terms.length === 0)
         return [];
     const phrase = query.trim().toLowerCase();
+    const extra = new Map();
+    const pointsAt = new Map();
+    for (const [word, targets] of Object.entries(synonyms)) {
+        extra.set(stem(word.toLowerCase()), targets.flatMap(words));
+        pointsAt.set(stem(word.toLowerCase()), targets.map((target) => target.toLowerCase()));
+    }
+    // A synonym can point straight at a tool's name, "redo" at `rerun_job`.
+    const named = (tool, term) => [term, ...(pointsAt.get(term) ?? [])].some((word) => word === tool.name || word === tool.name.replace(/_/g, ""));
     const scored = tools.map((tool) => {
         const name = words(tool.name);
         const title = words(tool.title);
@@ -73,7 +94,8 @@ export function searchTools(tools, query, limit = 10) {
         let score = 0;
         let matched = 0;
         for (const term of terms) {
-            const got = hits(term, name) * 5 + hits(term, title) * 4 + hits(term, tags) * 3 + hits(term, description);
+            // A term that is the tool's name is not a hint, it is the answer.
+            const got = (named(tool, term) ? 20 : 0) + hits(term, name, extra) * 5 + hits(term, title, extra) * 4 + hits(term, tags, extra) * 3 + hits(term, description, extra);
             if (got > 0)
                 matched++;
             score += got;

package/dist/serve.d.ts

@@ -2,6 +2,7 @@
  * Serving an app over stdio, which every local client launches, or HTTP.
  */
 import { type App } from "./app.js";
+import type { Logger } from "./tool.js";
 /**
  * Serve over stdio.
  *
@@ -11,10 +12,17 @@ import { type App } from "./app.js";
  * set of tools that explain what to configure.
  */
 export declare function serveStdioApp(app: App, env: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Once the server is answering: say if nothing is configured, then run the
+ * app's `onServe`. Nothing here can hold up the handshake or stop the server.
+ */
+export declare function afterStart(app: App, env: NodeJS.ProcessEnv, log: Logger): Promise<void>;
 export type HttpOptions = {
     host: string;
     port: number;
     token?: string;
+    /** Browser origins beyond localhost that may call the server, from `<PREFIX>_HTTP_ALLOWED_ORIGINS`. */
+    allowedOrigins?: readonly string[];
 };
 export declare function httpOptions(app: App, env: NodeJS.ProcessEnv, argv: string[]): HttpOptions;
 /**

package/dist/serve.js

@@ -27,17 +27,29 @@ export async function serveStdioApp(app, env) {
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
-    void warnIfUnconfigured(app, env, log.warn);
+    void afterStart(app, env, log);
 }
-async function warnIfUnconfigured(app, env, warn) {
+/**
+ * Once the server is answering: say if nothing is configured, then run the
+ * app's `onServe`. Nothing here can hold up the handshake or stop the server.
+ */
+export async function afterStart(app, env, log) {
+    let ctx;
     try {
-        const ctx = await app.context(env);
+        ctx = await app.context(env);
         if (app.definition.configured && !(await app.definition.configured(ctx))) {
-            warn(`Nothing is configured yet. Tools that need an account will say what is missing. Run \`${app.bins.cli} doctor\`.`);
+            log.warn(`Nothing is configured yet. Tools that need an account will say what is missing. Run \`${app.bins.cli} doctor\`.`);
         }
     }
     catch (error) {
-        warn(`Setup is incomplete: ${error.message} Run \`${app.bins.cli} doctor\`.`);
+        log.warn(`Setup is incomplete: ${error.message} Run \`${app.bins.cli} doctor\`.`);
+        return;
+    }
+    try {
+        await app.definition.onServe?.(ctx, log);
+    }
+    catch (error) {
+        log.warn(app.secrets.redact(error?.message ?? String(error)));
     }
 }
 export function httpOptions(app, env, argv) {
@@ -50,9 +62,21 @@ export function httpOptions(app, env, argv) {
         host: env[`${app.envPrefix}_HTTP_HOST`]?.trim() || "127.0.0.1",
         port,
         token: env[`${app.envPrefix}_HTTP_TOKEN`]?.trim() || undefined,
+        allowedOrigins: (env[`${app.envPrefix}_HTTP_ALLOWED_ORIGINS`] ?? "")
+            .split(",")
+            .map((origin) => origin.trim().replace(/\/$/, ""))
+            .filter(Boolean),
     };
 }
 const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+function localOrigin(origin) {
+    try {
+        return LOOPBACK.has(new URL(origin).hostname);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Serve over Streamable HTTP, for a machine that is always on.
  *
@@ -83,6 +107,7 @@ export async function serveHttpApp(app, env, options) {
     const port = address && typeof address === "object" ? address.port : options.port;
     const url = `http://${options.host.includes(":") && !options.host.startsWith("[") ? `[${options.host}]` : options.host}:${port}/mcp`;
     log.info(`listening on ${url}${options.token ? " (bearer token required)" : ""}`);
+    void afterStart(app, env, log);
     return {
         url,
         close: async () => {
@@ -99,6 +124,14 @@ async function handle(app, fetchMcp, options, loopback, req, res) {
         res.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: "forbidden host" }));
         return;
     }
+    // The MCP transport spec asks every server to check Origin: a page on another
+    // site can send a request here that a browser lets through, and only the
+    // Origin header says where it came from. Clients that are not browsers send none.
+    const origin = req.headers.origin;
+    if (origin && !localOrigin(origin) && !(options.allowedOrigins ?? []).includes(origin.replace(/\/$/, ""))) {
+        res.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: `Origin ${origin} is not allowed. Add it to ${app.envPrefix}_HTTP_ALLOWED_ORIGINS if this is deliberate.` }));
+        return;
+    }
     if (url.pathname === "/health") {
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({ ok: true, name: app.name, version: app.version, tools: app.tools().length }));

package/dist/server.d.ts

@@ -8,7 +8,7 @@
 import { McpServer, type ToolAnnotations } from "@modelcontextprotocol/server";
 import type { App } from "./app.js";
 import type { Policy } from "./policy.js";
-import type { Tool } from "./tool.js";
+import { type Tool } from "./tool.js";
 /** Claude Code shows a person a permission prompt on every call to a tool carrying this, in any mode. */
 export declare const REQUIRES_USER_INTERACTION = "anthropic/requiresUserInteraction";
 /** Claude Code raises its result-size limit for a tool carrying this. */

package/dist/server.js

@@ -12,6 +12,7 @@ import { toSlipwayError, UsageError } from "./errors.js";
 import { errorResult, isPlainObject, toCallToolResult } from "./result.js";
 import { outputJsonSchema } from "./schema.js";
 import { firstSentence, searchTools } from "./search.js";
+import { forCall } from "./tool.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. */
@@ -82,14 +83,16 @@ export function buildServer(app, env) {
  * is what makes Claude Code prompt for it.
  */
 async function confirmFirst(server, app, tool, args, ctx, env, policy, listedForPerson) {
-    if (!tool.requireConfirm)
+    // A call whose arguments make it a plain write needs nobody's approval, even on a tool that can publish.
+    const call = forCall(tool, args);
+    if (!call.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);
+    const ask = await personApproval(app, call, args, ctx, env);
     return ask ? { ask } : { approvedBy: "person" };
 }
 function registerTool(server, app, tool, env, policy) {
@@ -143,7 +146,7 @@ function registerSearchSurface(server, app, env, policy) {
         }),
         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 }) => ({
+        const matches = searchTools(visible(), query, limit ?? 10, app.definition.synonyms).map(({ tool }) => ({
             name: tool.name,
             title: tool.title,
             risk: tool.risk,

package/dist/tool.d.ts

@@ -103,6 +103,27 @@ export type ToolDefinition<Ctx, I extends Schema, O extends Schema | undefined>
      * generation.
      */
     requireConfirm?: boolean;
+    /**
+     * The risk of one call, when its arguments decide it: publishing is
+     * destructive, saving a draft is a write. `risk` stays the highest a call can
+     * be, which is what clients see in annotations and listings. The guard, the
+     * confirmation and the audit log go by this, and with it only a destructive
+     * call needs confirming.
+     */
+    riskFor?: (args: InferOutput<I>) => Risk;
+    /**
+     * The call spends money or credits: a paid generation, a billed send. It
+     * needs confirming, `<PREFIX>_ALLOW_DESTRUCTIVE=0` refuses it, and the CLI
+     * marks it `$`, while clients still see a plain write, because making an
+     * image destroys nothing.
+     */
+    spends?: boolean;
+    /**
+     * What a confirmed call does that cannot be taken back, as the refusal and
+     * the approval form put it: "moves money and cannot be undone". Defaults to
+     * "is public or cannot be undone" for a destructive tool.
+     */
+    consequence?: string;
     /** 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". */
@@ -146,6 +167,12 @@ export type Tool<Ctx = any> = {
     readonly idempotent: boolean;
     readonly openWorld: boolean;
     readonly requireConfirm: boolean;
+    /** The call spends money or credits. */
+    readonly spends: boolean;
+    /** The risk of one call, from its arguments. `forCall` applies it. */
+    readonly riskFor?: (args: any) => Risk;
+    /** What a confirmed call does that cannot be taken back, in the tool's own words. */
+    readonly consequence?: string;
     readonly tags: readonly string[];
     readonly examples: readonly ToolExample[];
     readonly positional: readonly string[];
@@ -191,4 +218,11 @@ export declare function isTool(value: unknown): value is Tool;
  * arguments have been anywhere near the handler.
  */
 export declare function summarize(tool: Pick<Tool, "summary" | "title">, args: Record<string, unknown>): string;
+/**
+ * The tool as one call sees it. With `riskFor`, the call's risk comes from its
+ * arguments, never above the declared one, and only a destructive call needs
+ * confirming. Like `summarize`, it runs before validation, so a `riskFor` that
+ * throws on odd arguments counts as the declared risk.
+ */
+export declare function forCall<Ctx>(tool: Tool<Ctx>, args: Record<string, unknown>): Tool<Ctx>;
 export {};

package/dist/tool.js

@@ -36,6 +36,14 @@ export function defineTool(definition) {
     }
     if (typeof definition.handler !== "function")
         throw new Error(`${where}: handler is required.`);
+    if (definition.spends && definition.risk === "read")
+        throw new Error(`${where}: a read cannot spend; make it a write.`);
+    if (definition.riskFor !== undefined) {
+        if (typeof definition.riskFor !== "function")
+            throw new Error(`${where}: riskFor must be a function of the arguments.`);
+        if (definition.risk === "read")
+            throw new Error(`${where}: riskFor is for a write whose arguments decide how far it reaches; a read has nothing to decide.`);
+    }
     const job = definition.job;
     if (job) {
         if (definition.name.length > 57)
@@ -75,7 +83,7 @@ export function defineTool(definition) {
         if (own.includes(name))
             throw new Error(`${where}: '${name}' is Slipway's own argument. Rename the input property.`);
     }
-    const requireConfirm = definition.requireConfirm ?? definition.risk === "destructive";
+    const requireConfirm = definition.requireConfirm ?? (definition.risk === "destructive" || definition.spends === true);
     const schema = withControls(input, {
         confirm: requireConfirm,
         ...(job ? { wait: { defaultSeconds: waitSecondsFor(job), maxSeconds: MAX_WAIT_SECONDS } } : {}),
@@ -99,6 +107,9 @@ export function defineTool(definition) {
         idempotent: definition.idempotent ?? definition.risk === "read",
         openWorld: definition.openWorld ?? true,
         requireConfirm,
+        spends: definition.spends === true,
+        ...(definition.riskFor ? { riskFor: definition.riskFor } : {}),
+        ...(definition.consequence?.trim() ? { consequence: definition.consequence.trim().replace(/\.$/, "") } : {}),
         tags: Object.freeze([...(definition.tags ?? [])]),
         examples: Object.freeze([...(definition.examples ?? [])]),
         positional: Object.freeze([...(definition.positional ?? [])]),
@@ -149,3 +160,26 @@ export function summarize(tool, args) {
         return fallback;
     }
 }
+const REACH = { read: 0, write: 1, destructive: 2 };
+/**
+ * The tool as one call sees it. With `riskFor`, the call's risk comes from its
+ * arguments, never above the declared one, and only a destructive call needs
+ * confirming. Like `summarize`, it runs before validation, so a `riskFor` that
+ * throws on odd arguments counts as the declared risk.
+ */
+export function forCall(tool, args) {
+    if (!tool.riskFor)
+        return tool;
+    let risk = tool.risk;
+    try {
+        const asked = tool.riskFor(args);
+        if (asked in REACH && REACH[asked] < REACH[tool.risk])
+            risk = asked;
+    }
+    catch {
+        // The declared risk is the safe answer.
+    }
+    if (risk === tool.risk)
+        return tool;
+    return { ...tool, risk, requireConfirm: tool.requireConfirm && (risk === "destructive" || tool.spends) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Slipway, the TypeScript framework for MCP servers and agent-native CLIs. One tool definition ships an MCP server and a CLI, with write safety, typed results and release checks built in.",
   "type": "module",
   "license": "Apache-2.0",