@better-fs-tools/shell 0.1.0 → 0.3.0

package/README.md

@@ -23,12 +23,12 @@ The package has no peers and imports no `node:` module. It starts no process by
 ## Quick start
 
 ```ts
-import { createNodeBashTool } from "@better-fs-tools/node";
-import { textOf } from "@better-fs-tools/shell";
+import { nodeCommandRunner } from "@better-fs-tools/node";
+import { createBashTool, shellEnv, 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 bash = createBashTool({ runner: nodeCommandRunner(), env: shellEnv(() => process.env) });
 
 const listed = await bash({ command: "ls package.json" });
 console.log(textOf(listed));
@@ -52,12 +52,16 @@ Each call starts a new shell. A `cd` or an `export` does not carry to the next c
 
 ## 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                       |
+Every integration takes the options of `createBashTool()`, with `runner` and `env` required, plus `signature`.
+
+| Host or runner     | Package                       | Factories                                                                                   |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------- |
+| Node or Bun        | `@better-fs-tools/node`       | `nodeCommandRunner()`, a runner for `createBashTool()` or a bundle                          |
+| AI SDK 7           | `@better-fs-tools/ai-sdk`     | `createAiSdkBashTool({ runner, env })`                                                      |
+| Pi coding agent    | `@better-fs-tools/pi`         | `createPiBashTool({ runner, env })`. `piCwdCommandRunner()` from `./node` runs in `ctx.cwd` |
+| Pi agent core      | `@better-fs-tools/pi`         | `createAgentCoreBashTool({ runner, env })` from `./agent-core`                              |
+| Pi durable harness | `@better-fs-tools/pi-durable` | the `bash` option of `createDurableFsTools()`, with `durableEnvRunner()`                    |
+| just-bash          | `@better-fs-tools/just-bash`  | `justBashCommandRunner(bash)`, an emulated shell with no process                            |
 
 ## Results
 
@@ -73,9 +77,10 @@ The error codes are `INVALID_INPUT`, `CWD_NOT_FOUND`, `CWD_NOT_A_DIRECTORY`, `DE
 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";
+import { nodeCommandRunner } from "@better-fs-tools/node";
+import { createBashTool, shellEnv } from "@better-fs-tools/shell";
 
-const bash = createNodeBashTool();
+const bash = createBashTool({ runner: nodeCommandRunner(), env: shellEnv(() => process.env) });
 const result = await bash({ command: "ls" });
 
 if (result.status === "error") {
@@ -85,7 +90,7 @@ if (result.status === "error") {
 }
 ```
 
-[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`, `spill-failed`, `unconfirmed-stop`, `extension-failed`, and the error note of an error result, whose code is the error code in kebab case (`denied`, `aborted`, `output-cap`, and so on).
+[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:
 
@@ -117,13 +122,13 @@ A `defaultTimeoutMs` that you set above `maxTimeoutMs`, or a `headPercent` over
 
 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.
+`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`. Every integration and bundle requires it, like the core.
 
 ## Hooks
 
-`runner` and `env` are required. `limits` and `messages` merge key by key. Every other dependency replaces its default.
+`runner` and `env` are required. `limits` and `messages` merge key by key. Every other option replaces its default.
 
-| Dependency  | Default                   | What a host builds on it                                                                                                                                                    |
+| Option      | 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.                                                                                                                            |
@@ -135,7 +140,7 @@ stdout and stderr are merged in arrival order. The core decodes UTF-8 with repla
 | `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.                                                                                              |
+| `digest`    | `sha256Digest()`          | 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.
@@ -143,9 +148,9 @@ The stages run in this order: input, cwd, `beforeRun`, `authorize`, `env`, the r
 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 { nodeCommandRunner } from "@better-fs-tools/node";
 import type { AfterRunHook, BeforeRunHook, ShellAuthorizer } from "@better-fs-tools/shell";
-import { defaultShellEnv } from "@better-fs-tools/shell";
+import { createBashTool, defaultShellEnv } from "@better-fs-tools/shell";
 
 // Host policy: allow a short list of command prefixes.
 const allowPrefixes: ShellAuthorizer = {
@@ -184,7 +189,8 @@ const maskTokens: AfterRunHook = {
   }),
 };
 
-export const bash = createNodeBashTool({
+export const bash = createBashTool({
+  runner: nodeCommandRunner(),
   authorize: allowPrefixes,
   beforeRun: [noInteractive],
   afterRun: [maskTokens],
@@ -204,7 +210,8 @@ import { open } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createNodeBashTool } from "@better-fs-tools/node";
+import { nodeCommandRunner } from "@better-fs-tools/node";
+import { createBashTool, shellEnv } from "@better-fs-tools/shell";
 import type { SpillSink } from "@better-fs-tools/shell";
 
 // Save every byte to a file. The truncation line names it, so the model can
@@ -226,13 +233,17 @@ const fileSpill: SpillSink = {
   },
 };
 
-export const bash = createNodeBashTool({ spill: fileSpill });
+export const bash = createBashTool({
+  runner: nodeCommandRunner(),
+  env: shellEnv(() => process.env),
+  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 adds an `extension-failed` warning and formats with `defaultShellFormatter()`, as the read and write tools do. The format context has `digest`, `limits`, `messages`, `mode`, and `call`.
+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
 
@@ -247,7 +258,7 @@ The runner's `id` goes into the tool description, so the model can see, for exam
 
 ## 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.
+`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 signature's own names as keys, as in the read and write signatures. `bashToolDefinition()` from the same subpath binds the bash tool to a signature for a framework of your own. `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
 
@@ -265,5 +276,5 @@ Every tool has one parse helper with the same pattern: `parseReadInput`, `parseE
 ## 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
+- [docs/result-schema.md](docs/result-schema.md): every field of the result, every error code with its phase, and every note. The [bash reference](https://better-fs-tools.gandrew.com/reference/bash) on the docs site has the same facts
+- [Choose an integration](https://better-fs-tools.gandrew.com/integrations) on the docs site, or `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/deps.d.ts

@@ -26,16 +26,16 @@ export interface ShellDependencies<THost = undefined> {
     readonly spill: SpillSink<THost> | null;
     readonly afterRun: readonly AfterRunHook<THost>[];
     readonly formatter: ShellFormatter<THost>;
-    /** Given to host functions as ctx.digest. Default null. */
+    /** Given to host functions as ctx.digest. Default sha256Digest(). */
     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.
+ * Every other option replaces its default.
  */
-export type ShellToolDeps<THost = undefined> = {
+export type BashToolOptions<THost = undefined> = {
     readonly runner: ShellDependencies<THost>["runner"];
     readonly env: ShellDependencies<THost>["env"];
     readonly limits?: Partial<ShellLimits>;

package/dist/contract/format.d.ts

@@ -3,7 +3,7 @@ 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. */
+    /** The tool's digest option. */
     readonly digest: Digest | null;
     readonly limits: Readonly<ShellLimits>;
     readonly messages: Readonly<ShellMessageCatalog>;
@@ -14,9 +14,9 @@ export interface ShellFormatContext<THost = undefined> {
 export interface ShellFormatter<THost = undefined> {
     readonly id: string;
     /**
-     * Sync and pure. A string becomes one text part. A throw, or a return that
-     * is neither a string nor an array, adds an extension-failed warning, and the
-     * default formatter formats the report. The status stays.
+     * 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/messages.d.ts

@@ -50,9 +50,6 @@ export interface ShellMessageCatalog extends ToolMessages {
     }): string;
     unconfirmedStop(): string;
     abortedBeforeStart(): string;
-    spillFailed(c: {
-        sink: string;
-    }): string;
     /**
      * The output stream failed (`detail`), gave chunks that were not output
      * (`skippedChunks`), or had not ended `drainMs` after the exit.

package/dist/core/create-bash-tool.d.ts

@@ -1,8 +1,8 @@
 import type { BashTool } from "../contract/context.ts";
-import type { ShellToolDeps } from "../contract/deps.ts";
+import type { BashToolOptions } from "../contract/deps.ts";
 /**
  * Creates the bash tool. Throws TypeError on an unknown key, a missing runner
- * or env, or a malformed dependency. `limits` and `messages` merge key by key.
- * Every other dependency replaces its default.
+ * or env, or a malformed option. `limits` and `messages` merge key by key.
+ * Every other option replaces its default.
  */
-export declare function createBashTool<THost = undefined>(deps: ShellToolDeps<THost>): BashTool<THost>;
+export declare function createBashTool<THost = undefined>(options: BashToolOptions<THost>): BashTool<THost>;

package/dist/core/create-bash-tool.js

@@ -3,11 +3,11 @@ import { isRecord } from "./input.js";
 import { runBash } from "./pipeline.js";
 /**
  * Creates the bash tool. Throws TypeError on an unknown key, a missing runner
- * or env, or a malformed dependency. `limits` and `messages` merge key by key.
- * Every other dependency replaces its default.
+ * or env, or a malformed option. `limits` and `messages` merge key by key.
+ * Every other option replaces its default.
  */
-export function createBashTool(deps) {
-    const resolved = resolveShellDependencies(deps);
+export function createBashTool(options) {
+    const resolved = resolveShellDependencies(options);
     const bash = async (input, ctx) => {
         if (ctx !== undefined && !isRecord(ctx))
             throw new TypeError("bash context must be an object");

package/dist/core/deps.d.ts

@@ -1,5 +1,5 @@
-import type { ShellDependencies, ShellToolDeps } from "../contract/deps.ts";
+import type { ShellDependencies, BashToolOptions } from "../contract/deps.ts";
 import type { CommandRunner } from "../contract/runner.ts";
-export declare function resolveShellDependencies<THost>(deps: ShellToolDeps<THost>): ShellDependencies<THost>;
+export declare function resolveShellDependencies<THost>(deps: BashToolOptions<THost>): ShellDependencies<THost>;
 export declare function isRunner(value: unknown): value is CommandRunner;
 export declare function isAbsolute(value: unknown): value is string;

package/dist/core/deps.js

@@ -1,3 +1,4 @@
+import { sha256Digest } from "@better-fs-tools/read";
 import { defaultShellFormatter } from "../formatters/default.js";
 import { isRecord } from "./input.js";
 import { resolveShellLimits } from "./limits.js";
@@ -19,10 +20,10 @@ const KNOWN = new Set([
 ]);
 export function resolveShellDependencies(deps) {
     if (!isRecord(deps))
-        throw new TypeError("bash tool dependencies must be an object");
+        throw new TypeError("bash tool options must be an object");
     for (const key of Object.keys(deps)) {
         if (!KNOWN.has(key))
-            throw new TypeError(`Unknown bash tool dependency: ${key}`);
+            throw new TypeError(`Unknown bash tool option: ${key}`);
     }
     const { runner } = deps;
     if (typeof runner !== "function" && !isRunner(runner)) {
@@ -62,7 +63,7 @@ export function resolveShellDependencies(deps) {
     if (!isRecord(formatter) || typeof formatter.format !== "function") {
         throw new TypeError("formatter must have a format function");
     }
-    const digest = deps.digest ?? null;
+    const digest = deps.digest === undefined ? sha256Digest() : deps.digest;
     if (digest !== null &&
         (!isRecord(digest) || typeof digest.create !== "function" || typeof digest.hash !== "function")) {
         throw new TypeError("digest must be a digest with create and hash, or null");

package/dist/core/env.d.ts

@@ -5,7 +5,7 @@ type EnvRecord = Readonly<Record<string, string | undefined>>;
  */
 export declare const defaultShellEnv: Readonly<Record<string, string>>;
 /**
- * An env dependency for any host: `base` with defaultShellEnv over it.
+ * An env option for any host: `base` with defaultShellEnv over it.
  * Entries whose value is undefined are left out. A function base is read
  * again on each call, so `shellEnv(() => process.env)` follows changes to
  * process.env.

package/dist/core/env.js

@@ -10,7 +10,7 @@ export const defaultShellEnv = Object.freeze({
     TERM: "dumb",
 });
 /**
- * An env dependency for any host: `base` with defaultShellEnv over it.
+ * An env option for any host: `base` with defaultShellEnv over it.
  * Entries whose value is undefined are left out. A function base is read
  * again on each call, so `shellEnv(() => process.env)` follows changes to
  * process.env.

package/dist/core/execute.js

@@ -6,8 +6,7 @@ import { StageStop, errorNote, messageOf, warning } from "./stop.js";
 const DRAIN_AFTER_EXIT_MS = 1_000;
 const EXIT_WAIT_AFTER_KILL_GRACE_MS = 1_000;
 export async function execute(scope, runner, planned, env) {
-    const { deps } = scope;
-    const { limits, messages } = deps;
+    const { limits, messages } = scope.deps;
     const spill = await openSpill(scope, planned);
     const controller = new AbortController();
     let stoppedBy = null;
@@ -96,9 +95,6 @@ export async function execute(scope, runner, planned, env) {
         throw startError(scope, exit.error.reason, exit.error.detail ?? null, planned.cwd);
     }
     const spillRef = await (spill?.close() ?? Promise.resolve(null));
-    if (spill?.failed === true) {
-        scope.notes.push(warning("spill-failed", messages.spillFailed({ sink: deps.spill?.id ?? "unknown" })));
-    }
     const reason = stoppedBy;
     if (exit === null)
         scope.notes.push(warning("unconfirmed-stop", messages.unconfirmedStop()));
@@ -235,9 +231,6 @@ async function openSpill(scope, planned) {
     let chain = Promise.resolve();
     let failed = false;
     return {
-        get failed() {
-            return failed;
-        },
         write(bytes) {
             if (failed)
                 return;

package/dist/core/messages.js

@@ -45,7 +45,6 @@ function catalogFor(param, duration) {
         outputCap: ({ limit }) => `The command wrote more than ${formatBytes(limit)} of output, so it was stopped. Send less output, for example with a filter, a count, or a redirect to a file.`,
         unconfirmedStop: () => "The runner did not confirm that the process tree stopped. Processes may still be running.",
         abortedBeforeStart: () => "The call was aborted before the command started.",
-        spillFailed: ({ sink }) => `The ${sink} spill sink failed, so the full output was not saved. The command was not affected.`,
         outputIncomplete: ({ detail, skippedChunks, drainMs }) => {
             const causes = [
                 ...(detail === null ? [] : [`the output stream failed (${detail})`]),

package/dist/core/pipeline.js

@@ -3,7 +3,7 @@ import { AbortStop } from "./abort.js";
 import { execute } from "./execute.js";
 import { clampedTimeout, isRecord, parseBashInput } from "./input.js";
 import { authorize, baseCwd, beforeRun, environment, extensionFailure, resolveCwd, runnerFor, } from "./stages.js";
-import { StageStop, errorNote, extensionId, info, isNoteList, messageOf, warning } from "./stop.js";
+import { StageStop, errorNote, info, isNoteList, messageOf } from "./stop.js";
 export async function runBash(deps, input, call) {
     const notes = [];
     const { messages, limits } = deps;
@@ -165,15 +165,9 @@ function finish(deps, call, done) {
     catch { }
     if (content !== null)
         return Object.freeze({ ...done, content });
-    const id = extensionId(deps.formatter);
-    const note = warning("extension-failed", deps.messages.extensionFailed({ extension: id, phase: "format" }), { extension: "formatter", id });
-    const kept = Object.freeze({
-        ...done,
-        notes: Object.freeze([...done.notes, note]),
-    });
     return Object.freeze({
-        ...kept,
-        content: toContent(defaultShellFormatter().format(kept, context)) ?? [],
+        ...done,
+        content: toContent(defaultShellFormatter().format(done, context)) ?? [],
     });
 }
 function toContent(value) {

package/dist/formatters/default.d.ts

@@ -1,13 +1,16 @@
 import type { Note } from "@better-fs-tools/read";
 import type { ShellFormatter } from "../contract/format.ts";
 export interface ShellFormatterOptions {
+    /** Filter or rewrite a note for the model text. null hides it. Default: show every note. */
+    readonly notes?: (note: Note) => Note | null;
     /** Default: `[bash:${note.code}] ${note.message}`. */
     readonly noteLine?: (note: Note) => string;
 }
 /**
  * The status line, then the output view, then a blank line and the note
  * lines. A call that did not run prints the note lines only. "view" mode
- * leaves out the notes.
+ * leaves out the notes. The `notes` option hides or rewrites a note, as the
+ * read tool's formatters do.
  *
  * ```text
  * Exit code 1 · 0.4 s

package/dist/formatters/default.js

@@ -1,7 +1,8 @@
 /**
  * The status line, then the output view, then a blank line and the note
  * lines. A call that did not run prints the note lines only. "view" mode
- * leaves out the notes.
+ * leaves out the notes. The `notes` option hides or rewrites a note, as the
+ * read tool's formatters do.
  *
  * ```text
  * Exit code 1 · 0.4 s
@@ -12,7 +13,9 @@ export function defaultShellFormatter(options = {}) {
     if (options === null || typeof options !== "object" || Array.isArray(options)) {
         throw new TypeError("defaultShellFormatter options must be an object");
     }
-    const { noteLine = defaultNoteLine } = options;
+    const { notes: filter = showNote, noteLine = defaultNoteLine } = options;
+    if (typeof filter !== "function")
+        throw new TypeError("notes must be a function");
     if (typeof noteLine !== "function")
         throw new TypeError("noteLine must be a function");
     return Object.freeze({
@@ -21,7 +24,7 @@ export function defaultShellFormatter(options = {}) {
             const main = body(report, ctx.messages);
             if (ctx.mode === "view")
                 return main.join("\n");
-            const notes = report.notes.map(noteLine);
+            const notes = noteLines(report.notes, filter, noteLine);
             if (notes.length === 0)
                 return main.join("\n");
             if (main.length === 0)
@@ -30,6 +33,18 @@ export function defaultShellFormatter(options = {}) {
         },
     });
 }
+function noteLines(notes, filter, line) {
+    const lines = [];
+    for (const note of notes) {
+        const shown = filter(note);
+        if (shown !== null)
+            lines.push(line(shown));
+    }
+    return lines;
+}
+function showNote(note) {
+    return note;
+}
 function defaultNoteLine(note) {
     return `[bash:${note.code}] ${note.message}`;
 }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export type { BashInput, BashRequest } from "./contract/input.ts";
 export type { BashTool } from "./contract/context.ts";
 export type { CommandRunner, OutputChunk, RunExit, RunHandle, RunRequest, RunStartError, } from "./contract/runner.ts";
 export type { ShellError, ShellErrorCode, ShellFailure, ShellOutput, ShellPhase, ShellReport, ShellResult, ShellRun, ShellRunReport, ShellStatus, } from "./contract/result.ts";
-export type { ShellDependencies, ShellToolDeps } from "./contract/deps.ts";
+export type { BashToolOptions } from "./contract/deps.ts";
 export type { AfterRunHook, AfterRunUpdate, BeforeRunDecision, BeforeRunHook, PlannedRun, RunOutcome, ShellAuthorizer, ShellAuthorizeTarget, ShellEnv, ShellHookContext, SpillSink, SpillWriter, } from "./contract/extensions.ts";
 export type { ShellFormatContext, ShellFormatter } from "./contract/format.ts";
 export type { ShellLimits } from "./contract/limits.ts";

package/dist/signature/definition.d.ts

@@ -0,0 +1,24 @@
+import type { ToolDefinition } from "@better-fs-tools/read";
+import type { BashToolOptions } from "../contract/deps.ts";
+import type { BashInput } from "../contract/input.ts";
+import type { ShellCanonicalParam } from "../contract/messages.ts";
+import type { ShellResult } from "../contract/result.ts";
+import type { BashSignature } from "./bash.ts";
+/** The bash tool bound to its signature. */
+export interface BashToolDefinition<THost = undefined> extends ToolDefinition<BashInput, ShellResult, THost, ShellCanonicalParam> {
+    readonly signature: BashSignature;
+}
+/** The bash tool's options, plus the signature the model sees. */
+export type BashToolDefinitionOptions<THost = undefined> = BashToolOptions<THost> & {
+    /**
+     * Default defaultBashSignature() with the runner's id, when the runner is
+     * not a factory, and the tool's limits, so the description names them.
+     */
+    readonly signature?: BashSignature;
+};
+/**
+ * Creates the bash tool and binds it to a signature. The signature's `param`
+ * and `duration` messages go under `options.messages`, so a host message
+ * still wins. Throws TypeError where createBashTool() does.
+ */
+export declare function bashToolDefinition<THost = undefined>(options: BashToolDefinitionOptions<THost>): BashToolDefinition<THost>;

package/dist/signature/definition.js

@@ -0,0 +1,39 @@
+import { createBashTool } from "../core/create-bash-tool.js";
+import { parseBashInput } from "../core/input.js";
+import { resolveShellLimits } from "../core/limits.js";
+import { bashSignatureMessages, defaultBashSignature } from "./bash.js";
+/**
+ * Creates the bash tool and binds it to a signature. The signature's `param`
+ * and `duration` messages go under `options.messages`, so a host message
+ * still wins. Throws TypeError where createBashTool() does.
+ */
+export function bashToolDefinition(options) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("bashToolDefinition options must be an object");
+    }
+    const { signature: given, ...rest } = options;
+    const runnerId = typeof rest.runner === "function" ? undefined : rest.runner?.id;
+    const signature = given ??
+        defaultBashSignature({
+            ...(runnerId === undefined ? {} : { runner: runnerId }),
+            ...(rest.limits === undefined ? {} : { limits: rest.limits }),
+        });
+    const bash = createBashTool({
+        ...rest,
+        messages: { ...bashSignatureMessages(signature), ...rest.messages },
+    });
+    const limits = resolveShellLimits(rest.limits);
+    return Object.freeze({
+        name: signature.name,
+        description: signature.description,
+        inputSchema: signature.schema,
+        ...(signature.grammar === undefined ? {} : { grammar: signature.grammar }),
+        signature,
+        validate(modelInput) {
+            const input = signature.toInput(modelInput);
+            parseBashInput(input, limits);
+            return input;
+        },
+        execute: async (modelInput, ctx) => bash(signature.toInput(modelInput), ctx),
+    });
+}

package/dist/signature/index.d.ts

@@ -1,3 +1,5 @@
 /** The `./signature` subpath: the model-facing name, schema, and description of the bash tool. */
 export { bashSignatureMessages, defaultBashSignature } from "./bash.ts";
 export type { BashParam, BashSignature, BashSignatureOptions } from "./bash.ts";
+export { bashToolDefinition } from "./definition.ts";
+export type { BashToolDefinition, BashToolDefinitionOptions } from "./definition.ts";

package/dist/signature/index.js

@@ -1,2 +1,3 @@
 /** The `./signature` subpath: the model-facing name, schema, and description of the bash tool. */
 export { bashSignatureMessages, defaultBashSignature } from "./bash.js";
+export { bashToolDefinition } from "./definition.js";

package/docs/architecture.md

@@ -23,7 +23,7 @@ formatter.format(report, { mode: "model", call, ... }) ─▶ content
 ShellResult
 ```
 
-| Stage     | Dependency              | What happens                                                                                                                    |
+| Stage     | Option                  | What happens                                                                                                                    |
 | --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | Input     | `limits`                | `parseBashInput` accepts only `command`, `timeoutMs`, and `cwd`. A timeout over `maxTimeoutMs` is clamped with a `clamped` note |
 | Runner    | `runner`, `cwd`         | A `CommandRunner`, or a factory of the call context. The default cwd is `cwd`, or the runner's `cwd`                            |
@@ -63,9 +63,9 @@ A failing output stream, chunks that are not output, or a stream that has not en
 
 ## Host code
 
-A throw or a malformed return from host code gives `EXTENSION_FAILED` with the phase of the stage. An `afterRun` failure keeps the run and the output. A formatter failure is the exception: the status stays, the core adds an `extension-failed` warning, and `defaultShellFormatter()` makes the content, as in the read and write tools.
+A throw or a malformed return from host code gives `EXTENSION_FAILED` with the phase of the stage. An `afterRun` failure keeps the run and the output. A formatter failure is the exception: the status stays, the core adds no note, and `defaultShellFormatter()` makes the content, as in the read and write tools.
 
-Every host function gets `ctx`: the tool name, the request, the limits, the messages, `digest`, `clock`, and the call context. The bash tool hashes nothing itself. `digest` and `clock` come from the dependencies, so a bundle can give bash the same digest and clock as its file tools.
+Every host function gets `ctx`: the tool name, the request, the limits, the messages, `digest`, `clock`, and the call context. The bash tool hashes nothing itself. `digest` and `clock` come from the options, so a bundle can give bash the same digest and clock as its file tools.
 
 ## Runners
 

package/docs/result-schema.md

@@ -91,7 +91,7 @@ The validated canonical input. `timeoutMs` is concrete: the input value clamped
   omittedLines: number;
   stdoutBytes: number;
   stderrBytes: number;
-  spill: string | null; // the spill sink's reference, or null without a sink
+  spill: string | null; // the spill sink's reference, or null without a sink or when the sink failed
 }
 ```
 
@@ -111,7 +111,7 @@ stdout and stderr are merged in arrival order. The view is `head`, a gap line, t
 | `OUTPUT_CAP`          | `run`                                                                  | The command wrote more than `maxCaptureBytes`, so the core stopped it                                                                     | set                                                       |
 | `EXTENSION_FAILED`    | `resolve`, `beforeRun`, `authorize`, `env`, `spill`, `run`, `afterRun` | Host code threw or returned a malformed value. `run` is a runner factory, `resolve` a cwd factory or resolver                             | set for `afterRun`                                        |
 
-`ShellPhase` also has `format`. A formatter failure is not an error: it gives an `extension-failed` warning, and the status stays.
+`ShellPhase` also has `format`. A formatter failure is not an error: the default formatter runs, no note is added, and the status stays.
 
 An `afterRun` hook that fails turns the result into `EXTENSION_FAILED`, and keeps `run`, `output`, and the notes so far. An abort during the run, and `OUTPUT_CAP`, keep them too. The formatter then shows the exit as the status line, and the reason in the error note.
 
@@ -131,14 +131,12 @@ Notes from the core:
 | ----------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
 | `clamped`                                                                                                                                 | info     | The input timeout was over `maxTimeoutMs`                                                                                                                                                         | `{ param: "timeoutMs", requested, max }` |
 | `output-incomplete`                                                                                                                       | warning  | The output stream failed, the runner gave chunks that were not output, or the stream had not ended `drainMs` after the exit. Not added after a stop the tool started (timeout, abort, output cap) | `{ skippedChunks, detail?, drainMs? }`   |
-| `spill-failed`                                                                                                                            | warning  | The spill sink failed. The command was not affected                                                                                                                                               | none                                     |
 | `unconfirmed-stop`                                                                                                                        | warning  | The runner did not settle its exit in the grace time after a stop                                                                                                                                 | none                                     |
-| `extension-failed`                                                                                                                        | warning  | The formatter failed, and the default formatter ran. The status stays                                                                                                                             | `{ extension: "formatter", id }`         |
 | `invalid-input`, `cwd-not-found`, `cwd-not-a-directory`, `refused`, `denied`, `aborted`, `spawn-failed`, `output-cap`, `extension-failed` | warning  | The error note of each error code                                                                                                                                                                 | none                                     |
 
 A resolver can add its own note, for example `path-repaired` from `unicodeRepair()`. An allow decision from the authorizer and a `beforeRun` hook can add notes. They keep their codes.
 
-Order: the error note comes first, then `clamped`, then the resolver note, then the `beforeRun` and authorizer notes, then the run notes (`spill-failed`, `unconfirmed-stop`, `output-incomplete`). An `afterRun` hook can replace the notes. A formatter failure adds its `extension-failed` note at the very end.
+Order: the error note comes first, then `clamped`, then the resolver note, then the `beforeRun` and authorizer notes, then the run notes (`unconfirmed-stop`, `output-incomplete`). An `afterRun` hook can replace the notes.
 
 ## Content
 
@@ -149,3 +147,5 @@ The formatter makes `content` once, with `mode: "model"`. A formatter that retur
 3. A blank line, then the note lines.
 
 A call that never started prints the note lines only. In `mode: "view"` the notes are left out.
+
+`defaultShellFormatter({ notes })` takes a function that rewrites a note, or returns `null` to hide it from the model text. `noteLine(note)` changes the text of one note line. The read and write formatters take the same `notes` option. The report keeps every note.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-fs-tools/shell",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A bash tool for TypeScript agents: a small run core with hooks and defaults.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@better-fs-tools/fs": "^0.1.0",
-    "@better-fs-tools/read": "^0.1.0"
+    "@better-fs-tools/fs": "^0.3.0",
+    "@better-fs-tools/read": "^0.3.0"
   }
 }