@thenavidm/slipway 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed in Slipway, newest first.
 
+## 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,8 @@ 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 |
+| `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" |
@@ -431,6 +433,8 @@ Errors are JSON on stderr, always, with `error`, `code` and a `hint` that names
 
 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.
 
+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:
 
 ```ts
@@ -550,7 +554,7 @@ 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` |
@@ -567,6 +571,7 @@ 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 |
 
 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

@@ -129,6 +129,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`.

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/cli/context.js

@@ -79,7 +79,9 @@ export function agentContext(app, env, bin, options = {}) {
             })),
             { 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" },
+            ...(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" },

package/dist/cli/help.js

@@ -216,7 +216,8 @@ export function renderGeneralHelp(app, bin) {
         ...(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"],
+        // 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"],

package/dist/cli/run.js

@@ -238,7 +238,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);
+            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)) }))));
             }

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">): string;

package/dist/guard.js

@@ -85,5 +85,7 @@ 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;
     return tool.risk === "destructive" ? "is public or cannot be undone" : "has an effect that cannot be taken back";
 }

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,6 +12,11 @@ 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;

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) {
@@ -83,6 +95,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 () => {

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) {

package/dist/tool.d.ts

@@ -103,6 +103,20 @@ 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;
+    /**
+     * 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 +160,10 @@ export type Tool<Ctx = any> = {
     readonly idempotent: boolean;
     readonly openWorld: boolean;
     readonly requireConfirm: 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 +209,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,12 @@ export function defineTool(definition) {
     }
     if (typeof definition.handler !== "function")
         throw new Error(`${where}: handler is required.`);
+    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)
@@ -99,6 +105,8 @@ export function defineTool(definition) {
         idempotent: definition.idempotent ?? definition.risk === "read",
         openWorld: definition.openWorld ?? true,
         requireConfirm,
+        ...(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 +157,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" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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",