@better-fs-tools/shell 0.0.0-tegami-trusted-publish-setup → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Andrew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,269 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# @better-fs-tools/shell
+
+A `bash` tool for TypeScript agents. It runs one command for each call and returns the exit code and a bounded view of the output.
+
+The package has a small run core, hooks, and defaults. It ships no policy: no authorizers, no command parser, and no guards. A host adds those through the hooks.
+
+The core always does these things:
+
+- It runs one command for each call, with stdin closed.
+- It stops the whole process tree on a timeout and on an abort.
+- It uses one timeout unit, milliseconds, in the code.
+- It keeps the output bounded in memory, and cuts the model view to a head and a tail with one line between them.
+- It puts the exit code first in the model text.
+
+## Install
+
+```sh
+npm install @better-fs-tools/shell @better-fs-tools/read @better-fs-tools/fs
+```
+
+The package has no peers and imports no `node:` module. It starts no process by itself. A runner does that: `nodeCommandRunner()` from [`@better-fs-tools/node`](https://www.npmjs.com/package/@better-fs-tools/node), `justBashCommandRunner()` from [`@better-fs-tools/just-bash`](https://www.npmjs.com/package/@better-fs-tools/just-bash), or your own.
+
+## Quick start
+
+```ts
+import { createNodeBashTool } from "@better-fs-tools/node";
+import { textOf } from "@better-fs-tools/shell";
+
+// bash -c in process.cwd(), with process.env, a 2 minute timeout, and a
+// 30 000 byte view of the output.
+const bash = createNodeBashTool();
+
+const listed = await bash({ command: "ls package.json" });
+console.log(textOf(listed));
+// Exit code 0 · 0 s
+// package.json
+
+const failed = await bash({ command: "grep -q nothing-here package.json" });
+if (failed.status === "failed") console.log(failed.run.exitCode); // 1
+
+const slow = await bash({ command: "sleep 5", timeoutMs: 100 });
+console.log(textOf(slow));
+// Timed out after 0.1 s. The process tree was stopped.
+// (no output)
+```
+
+`textOf` from `@better-fs-tools/shell` is the same function as `textOf` from `@better-fs-tools/read` and `@better-fs-tools/write`. It is re-exported so a bash-only host needs one import.
+
+A tool call is `bash(input, ctx?)`. The input is `{ command, timeoutMs?, cwd? }`. `ctx` is the call context that the other tools use: `{ signal?, callId?, host }`.
+
+Each call starts a new shell. A `cd` or an `export` does not carry to the next call. Use the `cwd` input instead.
+
+## Hosts
+
+| Host            | Package                      | Factories                                                                              |
+| --------------- | ---------------------------- | -------------------------------------------------------------------------------------- |
+| Node or Bun     | `@better-fs-tools/node`      | `createNodeBashTool()`, `nodeCommandRunner()`, and `createNodeFsTools({ bash: true })` |
+| AI SDK 7        | `@better-fs-tools/ai-sdk`    | `createAiSdkBashTool({ runner, env })`                                                 |
+| Pi coding agent | `@better-fs-tools/pi`        | `createPiBashTool()`, with Pi's own shape: `{ command, timeout }` in seconds           |
+| just-bash       | `@better-fs-tools/just-bash` | `justBashCommandRunner(bash)`, an emulated shell with no process                       |
+
+## Results
+
+| Status    | When                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------ |
+| `ok`      | The command exited with code 0.                                                                        |
+| `failed`  | The command exited with another code, or a signal ended it. This is a normal result, not a tool error. |
+| `timeout` | The timeout stopped the command. The output so far is kept.                                            |
+| `error`   | The call stopped, or the core stopped the command. `error.code` says why.                              |
+
+The error codes are `INVALID_INPUT`, `CWD_NOT_FOUND`, `CWD_NOT_A_DIRECTORY`, `DENIED` (the authorizer refused), `REFUSED` (a `beforeRun` hook refused), `ABORTED` (the caller's signal fired, before or during the run), `SPAWN_FAILED`, `OUTPUT_CAP`, and `EXTENSION_FAILED`. Read and write use the same codes for a denial and an abort.
+
+The result is a union on `status`. Every result has `tool: "bash"`, `status`, `request`, `run` (command as run, cwd, exit code, signal, duration, and what stopped it), `output` (the view, byte and line counts, and the spill reference), `notes`, and `content` for the model. Only the `error` variant has `error: { code, phase, message, data? }`, the same shape as the read and write errors. For `ok`, `failed`, and `timeout`, `run` and `output` are never null. For `error` they are set only when the command started: an abort during the run, `OUTPUT_CAP`, or a failed `afterRun` hook.
+
+```ts
+import { createNodeBashTool } from "@better-fs-tools/node";
+
+const bash = createNodeBashTool();
+const result = await bash({ command: "ls" });
+
+if (result.status === "error") {
+  console.log(result.error.code, result.error.phase); // only the error variant has `error`
+} else {
+  console.log(result.run.exitCode, result.output.totalBytes); // never null here
+}
+```
+
+[docs/result-schema.md](docs/result-schema.md) lists every field, every error code with its phase, and every note. Note codes are kebab case, as in read and write: `clamped`, `output-incomplete`, `unconfirmed-stop`, and the error note of an error result, whose code is the error code in kebab case (`denied`, `aborted`, `output-cap`, and so on).
+
+The model text starts with the status line:
+
+```text
+Exit code 1 · 0.4 s
+<output>
+```
+
+```text
+Timed out after 2 min. The process tree was stopped.
+<first lines>
+[… 11945 lines (1.8 MB) not shown] Full output: /tmp/bash-1.log
+<last lines>
+```
+
+## Defaults
+
+| Limit              | Default    | Meaning                                                                                          |
+| ------------------ | ---------- | ------------------------------------------------------------------------------------------------ |
+| `defaultTimeoutMs` | 120 000    | Used when the input has no timeout.                                                              |
+| `maxTimeoutMs`     | 600 000    | A larger input timeout is cut to this, with a `clamped` info note.                               |
+| `killGraceMs`      | 2 000      | Time between SIGTERM and SIGKILL. The core waits this long plus one second for the exit.         |
+| `maxOutputBytes`   | 30 000     | Bytes in the model view.                                                                         |
+| `maxOutputLines`   | 2 000      | Lines in the model view.                                                                         |
+| `headPercent`      | 20         | Percent of the view for the head. The tail gets the rest, because errors are usually at the end. |
+| `maxCaptureBytes`  | 10 485 760 | Past this, the core stops the command with `OUTPUT_CAP`.                                         |
+
+A `defaultTimeoutMs` that you set above `maxTimeoutMs`, or a `headPercent` over 100, throws `TypeError`. When you set only `maxTimeoutMs` below 120 000, the default timeout is lowered to it. The same limits rule holds in read, write, and bash. A per-call value over its ceiling is clamped, with a `clamped` info note. Two limits that you set and that conflict throw `TypeError` when the tool is built. A default that is over a ceiling you set is lowered to that ceiling.
+
+stdout and stderr are merged in arrival order. The core decodes UTF-8 with replacement characters and removes ANSI escape codes. It changes nothing else.
+
+`createBashTool` has no default environment: `env` is required, so the host chooses once what a command sees. `shellEnv(() => process.env)` passes the host environment, `shellEnv({ PATH, HOME })` passes an allow list, and `shellEnv()` passes `defaultShellEnv` alone. Every `shellEnv()` puts `defaultShellEnv` over its base: `PAGER=cat`, `GIT_PAGER=cat`, `GIT_TERMINAL_PROMPT=0`, `NO_COLOR=1`, and `TERM=dumb`. `createNodeBashTool()`, `createPiBashTool()`, and `createNodeFsTools({ bash: true })` default `env` to `shellEnv(() => process.env)`. `createAiSdkBashTool()` and `createFsTools()` require it, like the core.
+
+## Hooks
+
+`runner` and `env` are required. `limits` and `messages` merge key by key. Every other dependency replaces its default.
+
+| Dependency  | Default                   | What a host builds on it                                                                                                                                                    |
+| ----------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runner`    | required                  | Node, just-bash, a sandbox wrapper, a remote runner. A factory gets the call.                                                                                               |
+| `cwd`       | the runner's `cwd`        | Another default directory, or one for each call.                                                                                                                            |
+| `resolve`   | none                      | A read tool resolver changes the requested cwd string.                                                                                                                      |
+| `beforeRun` | `[]`                      | Guards and command rewrites. A rewrite feeds the next hook.                                                                                                                 |
+| `authorize` | none (allow)              | Approval prompts, prefix rules, deny lists, plan mode. A read `ToolAuthorizer` works on the cwd: `denyPaths()` sees the working directory, not the files a command touches. |
+| `env`       | required                  | The host environment, allow lists, and secret scrubbing.                                                                                                                    |
+| `spill`     | none                      | Every output byte saved to a file or a store.                                                                                                                               |
+| `afterRun`  | `[]`                      | Secret masking, output filters, exit-code meanings, read-record invalidation.                                                                                               |
+| `formatter` | `defaultShellFormatter()` | Another layout of the model text.                                                                                                                                           |
+| `messages`  | `defaultShellMessages`    | Wording. A signature sets the parameter names and the timeout unit.                                                                                                         |
+| `digest`    | null                      | Passed to host functions as `ctx.digest`. The bash tool hashes nothing itself.                                                                                              |
+| `clock`     | `() => new Date()`        | Passed to host functions as `ctx.clock`.                                                                                                                                    |
+
+The stages run in this order: input, cwd, `beforeRun`, `authorize`, `env`, the run, `afterRun`, and the formatter. `authorize` sees the command after every `beforeRun` rewrite, so an approval prompt shows the command that runs. Its target has the cwd as `resolvedPath`, and a `displayPath` relative to the default cwd (`.` for the default cwd itself), as the file tools show paths.
+
+A `beforeRun` hook returns `{ allow: true, command?, notes? }` or `{ allow: false, note? }`, the same `{ allow }` shape as an authorize decision. A refusal without a note gets a default `refused` note. A refusal note becomes the `refused` error note with the hook's own code in `data.source`, as for an authorizer note. An `afterRun` hook returns `{ output?, notes? }`: only the parts the core keeps. A field left out keeps its value.
+
+```ts
+import { createNodeBashTool } from "@better-fs-tools/node";
+import type { AfterRunHook, BeforeRunHook, ShellAuthorizer } from "@better-fs-tools/shell";
+import { defaultShellEnv } from "@better-fs-tools/shell";
+
+// Host policy: allow a short list of command prefixes.
+const allowPrefixes: ShellAuthorizer = {
+  id: "allow-prefixes",
+  authorize: (target) =>
+    ["git status", "ls", "bun test"].some((prefix) => target.command.startsWith(prefix))
+      ? { allow: true }
+      : {
+          allow: false,
+          note: { code: "not-allowed", severity: "warning", message: "Ask the user first." },
+        },
+};
+
+// A reusable guard: refuse programs that need a terminal. It runs before
+// authorize, so allowPrefixes sees any rewritten command.
+const noInteractive: BeforeRunHook = {
+  id: "no-interactive",
+  beforeRun: (run) =>
+    /^(vim|less|top)\b/u.test(run.command)
+      ? {
+          allow: false,
+          note: { code: "interactive", severity: "warning", message: "stdin is closed." },
+        }
+      : { allow: true },
+};
+
+// Mask a secret in the model view. The hook returns only what it changes.
+const maskTokens: AfterRunHook = {
+  id: "mask-tokens",
+  afterRun: (outcome) => ({
+    output: {
+      ...outcome.output,
+      head: outcome.output.head.replaceAll(/ghp_\w+/gu, "ghp_***"),
+      tail: outcome.output.tail?.replaceAll(/ghp_\w+/gu, "ghp_***") ?? null,
+    },
+  }),
+};
+
+export const bash = createNodeBashTool({
+  authorize: allowPrefixes,
+  beforeRun: [noInteractive],
+  afterRun: [maskTokens],
+  // Only PATH and HOME from the host, plus the pager and colour defaults.
+  env: () => ({
+    PATH: process.env.PATH ?? "/usr/bin:/bin",
+    HOME: process.env.HOME ?? "/",
+    ...defaultShellEnv,
+  }),
+});
+```
+
+A spill sink gets every byte in arrival order. Its reference goes into the truncation line:
+
+```ts
+import { open } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createNodeBashTool } from "@better-fs-tools/node";
+import type { SpillSink } from "@better-fs-tools/shell";
+
+// Save every byte to a file. The truncation line names it, so the model can
+// read the part the view left out with the read tool.
+const fileSpill: SpillSink = {
+  id: "file",
+  async open() {
+    const path = join(tmpdir(), `bash-${crypto.randomUUID()}.log`);
+    const file = await open(path, "w");
+    return {
+      write: async (bytes) => {
+        await file.write(bytes);
+      },
+      close: async () => {
+        await file.close();
+        return path;
+      },
+    };
+  },
+};
+
+export const bash = createNodeBashTool({ spill: fileSpill });
+// [… 196 000 lines (1.2 MB) not shown] Full output: /tmp/bash-….log
+```
+
+A hook that throws, or returns a malformed value, gives `EXTENSION_FAILED` with its phase. After the run, the result keeps the run and the output.
+
+A formatter that throws, or returns neither a string nor an array, does not change the status. The core formats with `defaultShellFormatter()` and adds no note, as the read and write tools do. The format context has `digest`, `limits`, `messages`, `mode`, and `call`.
+
+## Runners
+
+A runner starts one command and never throws for a failed command:
+
+- `run(request)` gets the command, an absolute cwd, the whole environment, an abort signal, and `killGraceMs`.
+- It returns `output`, an async iterable of `{ stream, bytes }` chunks in arrival order, and `exit`, a promise of `{ code, signal, error? }`.
+- When the signal aborts, the runner stops the whole process tree.
+- A start that fails is an exit with `code: null` and an `error` reason: `cwd-not-found`, `cwd-not-a-directory`, or `spawn-failed`.
+
+The runner's `id` goes into the tool description, so the model can see, for example, that commands run in an emulated shell.
+
+## Signatures
+
+`defaultBashSignature()` from `@better-fs-tools/shell/signature` gives the model `bash({ command, timeout?, cwd? })` with the timeout in milliseconds. `timeoutUnit: "s"` takes seconds, and `cwd: false` leaves out the cwd parameter; `names.cwd` and `describe.cwd` are then ignored. `names` renames a parameter, for example `names: { timeout: "timeout_seconds" }`, and `describe` replaces a parameter's description. Both take the preset's own names as keys, as in the read and write presets. `BashSignature` extends the `ToolSignature` base from `@better-fs-tools/read` with `duration(ms)`, the timeout in the signature's unit. `bashSignatureMessages(signature)` gives the messages the same parameter names and unit.
+
+## Parse helper
+
+Every tool has one parse helper with the same pattern: `parseReadInput`, `parseEditInput`, `parseWriteInput`, `parseApplyPatchInput`, and `parseBashInput`. Each takes the canonical input and the resolved limits, returns the request, and throws `TypeError` for input it refuses. The tool turns that throw into `INVALID_INPUT`. A clamp is not an error: the helper returns the clamped value, and the tool adds the `clamped` note.
+
+## Known limits
+
+- POSIX only. The Node runner runs `bash -c` in its own process group.
+- A background child that outlives a normal exit keeps running. The core stops reading its output shortly after the shell exits.
+- The allowed roots of the file tools do not limit what a command touches. Add an OS sandbox through a wrapper runner.
+- The bash tool does not update the read records of the file tools. The write core still catches most changes, because it compares the version or the content hash at commit. On a backend with weak versions, a change in the same second can go unseen. An `afterRun` hook that calls `invalidate(path)` closes that gap.
+- The just-bash runner buffers output until the command ends. A busy loop does not yield to the event loop, so the timeout cannot fire during it. Set just-bash's `executionLimits`.
+- There are no background runs, no persistent session, no PTY, and no input to a running process.
+
+## More
+
+- [docs/architecture.md](docs/architecture.md): the stages, their order, and why
+- [docs/result-schema.md](docs/result-schema.md): every field of the result, every error code with its phase, and every note
+- `docs/hosts.md` in [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write): the bash defaults of every host, next to the file tools

package/dist/contract/context.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCallContext } from "@better-fs-tools/read";
+import type { BashInput } from "./input.ts";
+import type { ShellResult } from "./result.ts";
+/**
+ * The bash tool function. The context argument is optional, and `host` may be
+ * left out, when THost includes undefined.
+ */
+export type BashTool<THost = undefined> = undefined extends THost ? (input: BashInput, ctx?: Omit<ToolCallContext<THost>, "host"> & {
+    readonly host?: THost;
+}) => Promise<ShellResult> : (input: BashInput, ctx: ToolCallContext<THost>) => Promise<ShellResult>;

package/dist/contract/deps.d.ts

@@ -0,0 +1,43 @@
+import type { Clock, Digest, PathResolver, ToolCallContext } from "@better-fs-tools/read";
+import type { AfterRunHook, BeforeRunHook, ShellAuthorizer, ShellEnv, SpillSink } from "./extensions.ts";
+import type { ShellFormatter } from "./format.ts";
+import type { ShellLimits } from "./limits.ts";
+import type { ShellMessageCatalog } from "./messages.ts";
+import type { CommandRunner } from "./runner.ts";
+export interface ShellDependencies<THost = undefined> {
+    /** A runner, or a factory called once for each call. */
+    readonly runner: CommandRunner | ((call: ToolCallContext<THost>) => CommandRunner);
+    /** The default cwd, or a factory. Default the runner's cwd. */
+    readonly cwd: string | ((call: ToolCallContext<THost>) => string) | null;
+    readonly limits: Readonly<ShellLimits>;
+    readonly messages: Readonly<ShellMessageCatalog>;
+    /** Changes the requested cwd string, as for the read tool. null is identity. */
+    readonly resolve: PathResolver<THost> | null;
+    /** Checks and rewrites, in order, before authorize. */
+    readonly beforeRun: readonly BeforeRunHook<THost>[];
+    /** Host policy on the final command. null allows. */
+    readonly authorize: ShellAuthorizer<THost> | null;
+    /**
+     * The whole environment of each command. Pass shellEnv(() => process.env),
+     * an allow list such as shellEnv({ PATH }), or shellEnv() for defaultShellEnv alone.
+     */
+    readonly env: ShellEnv<THost>;
+    /** null turns spill off. */
+    readonly spill: SpillSink<THost> | null;
+    readonly afterRun: readonly AfterRunHook<THost>[];
+    readonly formatter: ShellFormatter<THost>;
+    /** Given to host functions as ctx.digest. Default null. */
+    readonly digest: Digest | null;
+    /** Given to host functions as ctx.clock. Default () => new Date(). */
+    readonly clock: Clock;
+}
+/**
+ * `runner` and `env` are required. `limits` and `messages` merge key by key.
+ * Every other dependency replaces its default.
+ */
+export type ShellToolDeps<THost = undefined> = {
+    readonly runner: ShellDependencies<THost>["runner"];
+    readonly env: ShellDependencies<THost>["env"];
+    readonly limits?: Partial<ShellLimits>;
+    readonly messages?: Partial<ShellMessageCatalog>;
+} & Partial<Omit<ShellDependencies<THost>, "runner" | "env" | "limits" | "messages">>;

package/dist/contract/extensions.d.ts

@@ -0,0 +1,94 @@
+import type { AccessDecision, AccessTarget, Note, ToolCallContext, ToolHookContext } from "@better-fs-tools/read";
+import type { BashRequest } from "./input.ts";
+import type { ShellLimits } from "./limits.ts";
+import type { ShellMessageCatalog } from "./messages.ts";
+import type { ShellError, ShellOutput, ShellRun } from "./result.ts";
+/** Given to every shell host function. One object for each call. */
+export interface ShellHookContext<THost = undefined> extends ToolHookContext<THost> {
+    readonly tool: "bash";
+    readonly request: BashRequest;
+    readonly limits: Readonly<ShellLimits>;
+    readonly messages: Readonly<ShellMessageCatalog>;
+    readonly call: ToolCallContext<THost>;
+}
+/**
+ * The path fields name the working directory, so a read tool authorizer
+ * (a ToolAuthorizer) that checks paths also works on the cwd.
+ */
+export interface ShellAuthorizeTarget extends AccessTarget {
+    readonly action: "run";
+    readonly command: string;
+    readonly cwd: string;
+    readonly timeoutMs: number;
+}
+/**
+ * Host policy. Runs after the beforeRun hooks, so it sees the command that
+ * will run. A ToolAuthorizer from read fits here.
+ */
+export interface ShellAuthorizer<THost = undefined> {
+    readonly id: string;
+    readonly authorize: (target: ShellAuthorizeTarget, ctx: ShellHookContext<THost>) => AccessDecision | Promise<AccessDecision>;
+}
+export interface PlannedRun {
+    readonly command: string;
+    readonly cwd: string;
+    readonly timeoutMs: number;
+}
+/**
+ * The same `{ allow }` shape as an authorize decision. `command` rewrites the
+ * command. A refusal gives REFUSED, with `note` or a default refused note.
+ */
+export type BeforeRunDecision = {
+    readonly allow: true;
+    readonly command?: string;
+    readonly notes?: readonly Note[];
+} | {
+    readonly allow: false;
+    readonly note?: Note;
+};
+/**
+ * A reusable check or rewrite. Runs in order before authorize, so the
+ * authorizer sees the final command. A rewrite feeds the next hook.
+ */
+export interface BeforeRunHook<THost = undefined> {
+    readonly id: string;
+    beforeRun(run: PlannedRun, ctx: ShellHookContext<THost>): BeforeRunDecision | Promise<BeforeRunDecision>;
+}
+/** Returns the whole environment of the command. */
+export type ShellEnv<THost = undefined> = (run: PlannedRun, ctx: ShellHookContext<THost>) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+export interface SpillWriter {
+    write(bytes: Uint8Array): Promise<void>;
+    /** Returns a reference the truncation note shows, for example a path. */
+    close(): Promise<string>;
+}
+/** Receives every output byte, in arrival order. */
+export interface SpillSink<THost = undefined> {
+    readonly id: string;
+    open(run: PlannedRun, ctx: ShellHookContext<THost>): Promise<SpillWriter>;
+}
+/** What afterRun hooks see: a run that started, with its status. */
+export type RunOutcome = {
+    readonly status: "ok" | "failed" | "timeout";
+    readonly run: ShellRun;
+    readonly output: ShellOutput;
+    readonly notes: readonly Note[];
+} | {
+    readonly status: "error";
+    readonly error: ShellError;
+    readonly run: ShellRun;
+    readonly output: ShellOutput;
+    readonly notes: readonly Note[];
+};
+/**
+ * What an afterRun hook may change. A field left out keeps its value. `notes`
+ * replaces the whole list, so keep the notes you were given.
+ */
+export interface AfterRunUpdate {
+    readonly output?: ShellOutput;
+    readonly notes?: readonly Note[];
+}
+export interface AfterRunHook<THost = undefined> {
+    readonly id: string;
+    /** Runs in order on every run that started. Returns the output view and the notes to keep. */
+    afterRun(outcome: RunOutcome, ctx: ShellHookContext<THost>): AfterRunUpdate | Promise<AfterRunUpdate>;
+}

package/dist/contract/format.d.ts

@@ -0,0 +1,22 @@
+import type { ContentPart, Digest, ToolCallContext } from "@better-fs-tools/read";
+import type { ShellLimits } from "./limits.ts";
+import type { ShellMessageCatalog } from "./messages.ts";
+import type { ShellReport } from "./result.ts";
+export interface ShellFormatContext<THost = undefined> {
+    /** The tool's digest dependency. */
+    readonly digest: Digest | null;
+    readonly limits: Readonly<ShellLimits>;
+    readonly messages: Readonly<ShellMessageCatalog>;
+    /** "view": status line and output only, no notes. */
+    readonly mode: "model" | "view";
+    readonly call: ToolCallContext<THost>;
+}
+export interface ShellFormatter<THost = undefined> {
+    readonly id: string;
+    /**
+     * Sync and pure. A string becomes one text part. After a throw, or a return
+     * that is neither a string nor an array, the default formatter formats the
+     * report with no added note. The status stays.
+     */
+    format(report: ShellReport, ctx: ShellFormatContext<THost>): string | readonly ContentPart[];
+}

package/dist/contract/input.d.ts

@@ -0,0 +1,15 @@
+/** The canonical input. A signature maps the model's input to it. */
+export interface BashInput {
+    readonly command: string;
+    /** Milliseconds. Clamped to limits.maxTimeoutMs with a clamped note. Default limits.defaultTimeoutMs. */
+    readonly timeoutMs?: number;
+    /** Relative to the default cwd, or absolute. Default the default cwd. */
+    readonly cwd?: string;
+}
+/** The input after parse: every field set. */
+export interface BashRequest {
+    readonly command: string;
+    readonly timeoutMs: number;
+    /** The requested cwd, as the model sent it. null when left out. */
+    readonly cwd: string | null;
+}

package/dist/contract/limits.d.ts

@@ -0,0 +1,16 @@
+export interface ShellLimits {
+    /** Used when the input has no timeout. Default 120_000. */
+    readonly defaultTimeoutMs: number;
+    /** A larger input timeout is cut to this, with a note. Default 600_000. */
+    readonly maxTimeoutMs: number;
+    /** Time between SIGTERM and SIGKILL. The tool waits this long plus one second for the exit. Default 2_000. */
+    readonly killGraceMs: number;
+    /** Bytes of output in the model view. Default 30_000. */
+    readonly maxOutputBytes: number;
+    /** Lines of output in the model view. Default 2_000. */
+    readonly maxOutputLines: number;
+    /** Percent of the view budget given to the head. The tail gets the rest. Default 20. */
+    readonly headPercent: number;
+    /** Past this many output bytes the tool stops the command. Default 10_485_760 (10 MiB). */
+    readonly maxCaptureBytes: number;
+}

package/dist/contract/messages.d.ts

@@ -0,0 +1,69 @@
+import type { ToolMessages } from "@better-fs-tools/read";
+import type { ShellPhase } from "./result.ts";
+export type ShellCanonicalParam = "command" | "timeoutMs" | "cwd";
+/**
+ * Wording for every note and status line of the tool. Text that names a
+ * model parameter calls `param(name)`, which a signature overrides.
+ */
+export interface ShellMessageCatalog extends ToolMessages {
+    /** Host name for a canonical parameter. An empty string means the host has no such parameter. */
+    param(name: ShellCanonicalParam): string;
+    /** How a timeout value reads in the host's unit, for example "120 s". */
+    duration(ms: number): string;
+    invalidInput(c: {
+        detail: string;
+    }): string;
+    cwdNotFound(c: {
+        cwd: string;
+    }): string;
+    cwdNotADirectory(c: {
+        cwd: string;
+    }): string;
+    refused(c: {
+        hook: string;
+    }): string;
+    spawnFailed(c: {
+        detail: string | null;
+    }): string;
+    extensionFailed(c: {
+        extension: string;
+        phase: ShellPhase;
+    }): string;
+    timeoutClamped(c: {
+        requestedMs: number;
+        maxMs: number;
+    }): string;
+    /** The first line of an ended run. */
+    exited(c: {
+        code: number | null;
+        signal: string | null;
+        durationMs: number;
+    }): string;
+    timedOut(c: {
+        timeoutMs: number;
+    }): string;
+    aborted(c: {
+        durationMs: number;
+    }): string;
+    outputCap(c: {
+        limit: number;
+    }): string;
+    unconfirmedStop(): string;
+    abortedBeforeStart(): string;
+    /**
+     * The output stream failed (`detail`), gave chunks that were not output
+     * (`skippedChunks`), or had not ended `drainMs` after the exit.
+     */
+    outputIncomplete(c: {
+        detail: string | null;
+        skippedChunks: number;
+        drainMs: number | null;
+    }): string;
+    noOutput(): string;
+    /** The line between the head and the tail. */
+    omitted(c: {
+        lines: number;
+        bytes: number;
+        spill: string | null;
+    }): string;
+}