@better-fs-tools/shell 0.1.0 → 0.2.0

package/README.md

@@ -85,7 +85,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:
 
@@ -232,7 +232,7 @@ export const bash = createNodeBashTool({ spill: fileSpill });
 
 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
 

package/dist/contract/format.d.ts

@@ -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/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/docs/architecture.md

@@ -63,7 +63,7 @@ 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.
 

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.2.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.2.0",
+    "@better-fs-tools/read": "^0.2.0"
   }
 }