@smthrs/std 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/esm/internal/Exec.js

@@ -20,6 +20,7 @@ import * as ChildProcess from "effect/process/ChildProcess";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import * as StdError from "../StdError.js";
+import { elideMiddle } from "./Text.js";
 /**
  * Failure codes a buffered execution can report, matching the codes the
  * removed kernel `Shell` used so handler-level mapping is unchanged.
@@ -27,13 +28,15 @@ import * as StdError from "../StdError.js";
  * @category models
  * @since 1.0.0
  */
-export const ExecErrorCode = Schema.Literals(["timeout", "spawn_error", "capture_overflow"]);
+export const ExecErrorCode = Schema.Literals(["timeout", "spawn_error", "arguments_too_long", "capture_overflow"]);
 /**
  * A command that never produced an exit code.
  *
  * A non-zero exit is a successful {@link ExecResult}, not a failure; this
- * error is reserved for a command that could not start or was cut off by its
- * timeout, or whose captured output exceeded a refusing capture bound.
+ * error is reserved for a command that could not start (`arguments_too_long`
+ * when the operating system refused it for the size of its arguments) or was
+ * cut off by its timeout, or whose captured output exceeded a refusing capture
+ * bound.
  *
  * @category errors
  * @since 1.0.0
@@ -46,32 +49,22 @@ export class ExecError extends Schema.TaggedError()("@smthrs/std/ExecError", {
 }) {
 }
 const decoder = new TextDecoder("utf-8");
-/**
- * Joins the retained chunks and decodes them, skipping the partial code point a
- * dropped head can leave behind.
- *
- * A UTF-8 continuation byte is `10xxxxxx`, and a code point is at most four
- * bytes, so at most three leading continuation bytes can precede the first
- * whole character. Skipping them is counted as dropped rather than decoded to a
- * replacement character the process never printed.
- */
-const decodeTail = (state) => {
-    const bytes = new Uint8Array(state.bytes);
+const emptyTail = () => ({ chunks: [], bytes: 0, dropped: 0 });
+/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */
+const isContinuation = (byte) => (byte & 0b1100_0000) === 0b1000_0000;
+const join = (chunks, size) => {
+    const bytes = new Uint8Array(size);
     let offset = 0;
-    for (const chunk of state.chunks) {
+    for (const chunk of chunks) {
         bytes.set(chunk, offset);
         offset += chunk.byteLength;
     }
-    if (state.dropped === 0)
-        return { text: decoder.decode(bytes), droppedBytes: 0 };
-    let start = 0;
-    while (start < bytes.byteLength && start < 3 && (bytes[start] & 0b1100_0000) === 0b1000_0000)
-        start++;
-    return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start };
+    return bytes;
 };
-const boundedTail = (stream, maxBytes, overflow) => Stream.runFold(stream, () => ({ chunks: [], bytes: 0, dropped: 0 }), (state, chunk) => {
+/** Appends one chunk and drops from the front whatever no longer fits. */
+const keepTail = (state, chunk, maxBytes) => {
     if (chunk.byteLength === 0)
-        return state;
+        return;
     state.chunks.push(chunk);
     state.bytes += chunk.byteLength;
     while (state.bytes > maxBytes && state.chunks.length > 0) {
@@ -88,13 +81,101 @@ const boundedTail = (stream, maxBytes, overflow) => Stream.runFold(stream, () =>
             state.dropped += excess;
         }
     }
+};
+/**
+ * Joins the retained chunks and decodes them, skipping the partial code point a
+ * dropped head can leave behind.
+ *
+ * A code point is at most four bytes, so at most three leading continuation
+ * bytes can precede the first whole character. Skipping them is counted as
+ * dropped rather than decoded to a replacement character the process never
+ * printed.
+ */
+const decodeTail = (state) => {
+    const bytes = join(state.chunks, state.bytes);
+    if (state.dropped === 0)
+        return { text: decoder.decode(bytes), droppedBytes: 0 };
+    let start = 0;
+    while (start < bytes.byteLength && start < 3 && isContinuation(bytes[start]))
+        start++;
+    return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start };
+};
+/**
+ * The length of a cut head without the character the cut left unfinished.
+ *
+ * Its last character starts at the last byte that is not a continuation byte,
+ * and that byte says how many bytes the character needs. One that needs more
+ * than the head holds is dropped, for the same reason {@link decodeTail} skips
+ * a partial code point.
+ */
+const wholeLength = (bytes) => {
+    for (let back = 1; back <= Math.min(3, bytes.byteLength); back++) {
+        const byte = bytes[bytes.byteLength - back];
+        if (isContinuation(byte))
+            continue;
+        const width = byte >= 0b1111_0000 ? 4 : byte >= 0b1110_0000 ? 3 : byte >= 0b1100_0000 ? 2 : 1;
+        return width > back ? bytes.byteLength - back : bytes.byteLength;
+    }
+    return bytes.byteLength;
+};
+/**
+ * Decodes a stream kept by its ends. A stream that fit is decoded whole;
+ * otherwise each end is cut on a character boundary and one line naming every
+ * byte between them stands where the middle was.
+ */
+const decodeEnds = (state) => {
+    if (state.tail.dropped === 0) {
+        const whole = join([...state.head, ...state.tail.chunks], state.headBytes + state.tail.bytes);
+        return { text: decoder.decode(whole), droppedBytes: 0 };
+    }
+    const head = join(state.head, state.headBytes);
+    const kept = wholeLength(head);
+    const tail = decodeTail(state.tail);
+    const droppedBytes = head.byteLength - kept + tail.droppedBytes;
+    return { text: elideMiddle(decoder.decode(head.subarray(0, kept)), droppedBytes, tail.text), droppedBytes };
+};
+const boundedTail = (stream, maxBytes, overflow) => Stream.runFold(stream, emptyTail, (state, chunk) => {
+    keepTail(state, chunk, maxBytes);
     return state;
 }).pipe(Effect.map((state) => overflow === "refuse" && state.dropped > 0
     ? { text: "", droppedBytes: state.dropped }
     : decodeTail(state)));
+/**
+ * Keeps the first half of the bound and the last half. The head fills first,
+ * and every byte after it passes through the tail, which drops from its front:
+ * what falls out of the tail is the middle.
+ */
+const boundedEnds = (stream, maxBytes) => {
+    const headBytes = Math.floor(maxBytes / 2);
+    return Stream.runFold(stream, () => ({ head: [], headBytes: 0, tail: emptyTail() }), (state, chunk) => {
+        const taken = Math.min(headBytes - state.headBytes, chunk.byteLength);
+        if (taken > 0) {
+            state.head.push(chunk.subarray(0, taken));
+            state.headBytes += taken;
+        }
+        keepTail(state.tail, chunk.subarray(taken), maxBytes - headBytes);
+        return state;
+    }).pipe(Effect.map(decodeEnds));
+};
 const capture = (stream, maxBytes, overflow) => maxBytes === undefined
     ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))
-    : boundedTail(stream, maxBytes, overflow);
+    : overflow === "ends"
+        ? boundedEnds(stream, maxBytes)
+        : boundedTail(stream, maxBytes, overflow);
+/**
+ * A command whose arguments exceed the operating system's limit fails `execve`
+ * with `E2BIG` before it starts: one argument over 128 KiB on Linux, all of
+ * them over 1 MiB on macOS. A heredoc in a command line, or a file's text
+ * passed as an argument, is one such argument. The platform error's own text
+ * repeats the whole command line, so this text is written here instead, and a
+ * caller may show it as it stands.
+ */
+const argumentsTooLong = (error) => error.cause?.code === "E2BIG"
+    ? new ExecError({
+        code: "arguments_too_long",
+        message: "Command not started: its arguments exceed the operating system's size limit (E2BIG). Send long text on standard input or in a file, not in the command line or its arguments."
+    })
+    : undefined;
 const unbounded = (command, options) => Effect.gen(function* () {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const settings = {
@@ -137,7 +218,7 @@ const unbounded = (command, options) => Effect.gen(function* () {
         stdoutDroppedBytes: stdout.droppedBytes,
         stderrDroppedBytes: stderr.droppedBytes
     };
-}).pipe(Effect.scoped, Effect.mapError((error) => error instanceof ExecError ? error : new ExecError({
+}).pipe(Effect.scoped, Effect.mapError((error) => error instanceof ExecError ? error : argumentsTooLong(error) ?? new ExecError({
     code: "spawn_error",
     message: `exec: ${command}: ${error.message}`
 })));
@@ -167,18 +248,21 @@ export const exec = (command, options = {}) => options.timeoutMs === undefined
  *
  * A timeout keeps its own code, because "the command never finished" and "the
  * command never started" are different things to a caller deciding whether to
- * retry. Every other way of producing no exit code is a host failure.
+ * retry. Arguments the operating system refused for their size are the
+ * caller's own input, which a shell flow publishes, so they read as
+ * `invalid_input`. Every other way of producing no exit code is a host failure.
  *
  * @category errors
  * @since 1.0.0
  */
-export const toStdErrorCode = (error) => error.code === "timeout" ? "timeout" : "command_failed";
+export const toStdErrorCode = (error) => error.code === "timeout" ? "timeout" : error.code === "arguments_too_long" ? "invalid_input" : "command_failed";
 /**
  * The model-facing failure one execution error becomes.
  *
  * A timeout names the command, which is what the caller asked for and all a
- * timeout has to say. Any other failure carries the message the execution
- * produced, which already names the command.
+ * timeout has to say. Arguments too long to start carry the reason and the
+ * fix, and nothing of the command. Any other failure carries the message the
+ * execution produced, which already names the command.
  *
  * @category errors
  * @since 1.0.0
@@ -187,7 +271,9 @@ export const toStdError = (command, error) => new StdError.StdError({
     code: toStdErrorCode(error),
     message: error.code === "timeout"
         ? `Command timed out: ${command}`
-        : `Command failed to start: ${error.message}`,
+        : error.code === "arguments_too_long"
+            ? error.message
+            : `Command failed to start: ${error.message}`,
     ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })
 });
 //# sourceMappingURL=Exec.js.map

package/dist/esm/internal/Exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"Exec.js","sourceRoot":"","sources":["../../../src/internal/Exec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Buffered shell execution over the permission-aware process spawner.\n *\n * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a\n * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with\n * `ChildProcessSpawner`, Effect's own process boundary, which streams and has\n * no buffered form. This module is the buffered form the shell flows still\n * want, expressed in terms of the spawner so the `proc:spawn` capability check\n * and the command-line resource stay exactly where the kernel put them.\n *\n * Commands run through the platform shell (`shell: true`), matching the old\n * service: the flows take a command *line*, not an argv.\n *\n * @since 1.0.0\n */\n\nimport * as ChildProcessEnvironment from \"@smthrs/kernel/ChildProcessEnvironment\"\nimport * as ChildProcessSpawner from \"@smthrs/kernel/ChildProcessSpawner\"\nimport * as Effect from \"effect/Effect\"\nimport * as ChildProcess from \"effect/process/ChildProcess\"\nimport * as Schema from \"effect/Schema\"\nimport * as Stream from \"effect/Stream\"\nimport * as StdError from \"../StdError.ts\"\n\n/**\n * Failure codes a buffered execution can report, matching the codes the\n * removed kernel `Shell` used so handler-level mapping is unchanged.\n *\n * @category models\n * @since 1.0.0\n */\nexport const ExecErrorCode = Schema.Literals([\"timeout\", \"spawn_error\", \"capture_overflow\"])\n\n/**\n * Failure codes a buffered execution can report.\n *\n * @category models\n * @since 1.0.0\n */\nexport type ExecErrorCode = typeof ExecErrorCode.Type\n\n/**\n * A command that never produced an exit code.\n *\n * A non-zero exit is a successful {@link ExecResult}, not a failure; this\n * error is reserved for a command that could not start or was cut off by its\n * timeout, or whose captured output exceeded a refusing capture bound.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class ExecError extends Schema.TaggedError<ExecError>()(\"@smthrs/std/ExecError\", {\n  code: ExecErrorCode,\n  message: Schema.String,\n  /** The limit a `timeout` ran past, in milliseconds. */\n  limitMillis: Schema.optional(Schema.Number)\n}) {}\n\n/**\n * The buffered result of one command.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecResult {\n  readonly stdout: string\n  readonly stderr: string\n  readonly exitCode: number\n  /** UTF-8 bytes dropped from the head of stdout to stay inside the capture bound. */\n  readonly stdoutDroppedBytes: number\n  /** UTF-8 bytes dropped from the head of stderr to stay inside the capture bound. */\n  readonly stderrDroppedBytes: number\n}\n\n/**\n * Options accepted by {@link exec}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecOptions {\n  readonly cwd?: string | undefined\n  readonly env?: Readonly<Record<string, string>> | undefined\n  readonly timeoutMs?: number | undefined\n  /**\n   * The program's arguments. Present means an argv, absent means a command\n   * line for the platform shell. An argv is how a payload reaches a program\n   * without being quoted into a string: nothing between here and `execve`\n   * re-parses it.\n   */\n  readonly args?: ReadonlyArray<string> | undefined\n  /**\n   * Text written to the program's standard input, as data. A script delivered\n   * this way is never quoted, escaped, or heredoc-terminated, which is the\n   * whole point: quoting corruption cost the measured SWE-bench program twelve\n   * probe failures and one instance's most expensive frame.\n   */\n  readonly stdin?: string | undefined\n  /**\n   * Bytes retained per captured stream. A stream that prints more keeps its\n   * tail and reports what it dropped, so a command printing gigabytes costs a\n   * bounded amount of memory rather than the whole of what it printed.\n   *\n   * Absent means unbounded, which is what a caller wants when it needs every\n   * byte a tool produced (`rg --files`, `git worktree list`).\n   */\n  readonly maxCaptureBytes?: number | undefined\n  /** Defaults to `tail`; `refuse` fails if either stream exceeds the bound. */\n  readonly overflow?: \"tail\" | \"refuse\" | undefined\n}\n\n/** One captured stream: the text kept, and the bytes dropped to keep it bounded. */\ninterface Capture {\n  readonly text: string\n  readonly droppedBytes: number\n}\n\ninterface Tail {\n  chunks: Array<Uint8Array>\n  bytes: number\n  dropped: number\n}\n\nconst decoder = new TextDecoder(\"utf-8\")\n\n/**\n * Joins the retained chunks and decodes them, skipping the partial code point a\n * dropped head can leave behind.\n *\n * A UTF-8 continuation byte is `10xxxxxx`, and a code point is at most four\n * bytes, so at most three leading continuation bytes can precede the first\n * whole character. Skipping them is counted as dropped rather than decoded to a\n * replacement character the process never printed.\n */\nconst decodeTail = (state: Tail): Capture => {\n  const bytes = new Uint8Array(state.bytes)\n  let offset = 0\n  for (const chunk of state.chunks) {\n    bytes.set(chunk, offset)\n    offset += chunk.byteLength\n  }\n  if (state.dropped === 0) return { text: decoder.decode(bytes), droppedBytes: 0 }\n  let start = 0\n  while (start < bytes.byteLength && start < 3 && (bytes[start]! & 0b1100_0000) === 0b1000_0000) start++\n  return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start }\n}\n\nconst boundedTail = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number,\n  overflow: \"tail\" | \"refuse\" | undefined\n): Effect.Effect<Capture, E> =>\n  Stream.runFold(\n    stream,\n    (): Tail => ({ chunks: [], bytes: 0, dropped: 0 }),\n    (state, chunk) => {\n      if (chunk.byteLength === 0) return state\n      state.chunks.push(chunk)\n      state.bytes += chunk.byteLength\n      while (state.bytes > maxBytes && state.chunks.length > 0) {\n        const excess = state.bytes - maxBytes\n        const first = state.chunks[0]!\n        if (first.byteLength <= excess) {\n          state.chunks.shift()\n          state.bytes -= first.byteLength\n          state.dropped += first.byteLength\n        } else {\n          state.chunks[0] = first.subarray(excess)\n          state.bytes -= excess\n          state.dropped += excess\n        }\n      }\n      return state\n    }\n  ).pipe(Effect.map((state) =>\n    overflow === \"refuse\" && state.dropped > 0\n      ? { text: \"\", droppedBytes: state.dropped }\n      : decodeTail(state)\n  ))\n\nconst capture = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number | undefined,\n  overflow: \"tail\" | \"refuse\" | undefined\n): Effect.Effect<Capture, E> =>\n  maxBytes === undefined\n    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))\n    : boundedTail(stream, maxBytes, overflow)\n\nconst unbounded = (\n  command: string,\n  options: ExecOptions\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n    const settings: ChildProcess.CommandOptions = {\n      ...(options.args === undefined ? { shell: true } : {}),\n      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),\n      env: ChildProcessEnvironment.make(process.env, options.env),\n      extendEnv: false,\n      ...(options.stdin === undefined\n        ? {}\n        : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) })\n    }\n    const handle = yield* spawner.spawn(\n      options.args === undefined\n        ? ChildProcess.make(command, settings)\n        : ChildProcess.make(command, [...options.args], settings)\n    )\n    // stdout, stderr, and the exit code have to be consumed concurrently: a\n    // command that fills a pipe blocks until the pipe is drained, so waiting\n    // for exit first would deadlock on any output larger than the buffer.\n    const [stdout, stderr, exitCode] = yield* Effect.all(\n      [\n        capture(handle.stdout, options.maxCaptureBytes, options.overflow),\n        capture(handle.stderr, options.maxCaptureBytes, options.overflow),\n        handle.exitCode\n      ],\n      { concurrency: \"unbounded\" }\n    )\n    if (options.overflow === \"refuse\") {\n      const overflowed = [\n        stdout.droppedBytes > 0 ? \"stdout\" : undefined,\n        stderr.droppedBytes > 0 ? \"stderr\" : undefined\n      ]\n        .filter((stream): stream is string => stream !== undefined)\n      if (overflowed.length > 0) {\n        return yield* Effect.fail(\n          new ExecError({\n            code: \"capture_overflow\",\n            message: `${command} ${\n              overflowed.join(\" and \")\n            } exceeded the ${options.maxCaptureBytes}-byte capture cap; refusing partial output`\n          })\n        )\n      }\n    }\n    return {\n      stdout: stdout.text,\n      stderr: stderr.text,\n      exitCode,\n      stdoutDroppedBytes: stdout.droppedBytes,\n      stderrDroppedBytes: stderr.droppedBytes\n    }\n  }).pipe(\n    Effect.scoped,\n    Effect.mapError((error) =>\n      error instanceof ExecError ? error : new ExecError({\n        code: \"spawn_error\",\n        message: `exec: ${command}: ${error.message}`\n      })\n    )\n  )\n\n/**\n * Runs a command line through the platform shell and buffers its output.\n *\n * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber\n * — including the one a `timeoutMs` interrupts — terminates the process rather\n * than leaking it.\n *\n * @category execution\n * @since 1.0.0\n */\nexport const exec = (\n  command: string,\n  options: ExecOptions = {}\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  options.timeoutMs === undefined\n    ? unbounded(command, options)\n    : Effect.timeoutOrElse(unbounded(command, options), {\n      duration: options.timeoutMs,\n      orElse: () =>\n        Effect.fail(\n          new ExecError({\n            code: \"timeout\",\n            message: `exec: \\`${command}\\` exceeded ${options.timeoutMs}ms`,\n            limitMillis: options.timeoutMs\n          })\n        )\n    })\n\n/**\n * The model-facing failure code a command that never produced an exit code\n * carries.\n *\n * A timeout keeps its own code, because \"the command never finished\" and \"the\n * command never started\" are different things to a caller deciding whether to\n * retry. Every other way of producing no exit code is a host failure.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdErrorCode = (error: ExecError): StdError.Code =>\n  error.code === \"timeout\" ? \"timeout\" : \"command_failed\"\n\n/**\n * The model-facing failure one execution error becomes.\n *\n * A timeout names the command, which is what the caller asked for and all a\n * timeout has to say. Any other failure carries the message the execution\n * produced, which already names the command.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdError = (command: string, error: ExecError): StdError.StdError =>\n  new StdError.StdError({\n    code: toStdErrorCode(error),\n    message: error.code === \"timeout\"\n      ? `Command timed out: ${command}`\n      : `Command failed to start: ${error.message}`,\n    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })\n  })\n"]}
+{"version":3,"file":"Exec.js","sourceRoot":"","sources":["../../../src/internal/Exec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Buffered shell execution over the permission-aware process spawner.\n *\n * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a\n * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with\n * `ChildProcessSpawner`, Effect's own process boundary, which streams and has\n * no buffered form. This module is the buffered form the shell flows still\n * want, expressed in terms of the spawner so the `proc:spawn` capability check\n * and the command-line resource stay exactly where the kernel put them.\n *\n * Commands run through the platform shell (`shell: true`), matching the old\n * service: the flows take a command *line*, not an argv.\n *\n * @since 1.0.0\n */\n\nimport * as ChildProcessEnvironment from \"@smthrs/kernel/ChildProcessEnvironment\"\nimport * as ChildProcessSpawner from \"@smthrs/kernel/ChildProcessSpawner\"\nimport * as Effect from \"effect/Effect\"\nimport * as ChildProcess from \"effect/process/ChildProcess\"\nimport * as Schema from \"effect/Schema\"\nimport * as Stream from \"effect/Stream\"\nimport * as StdError from \"../StdError.ts\"\nimport { elideMiddle } from \"./Text.ts\"\n\n/**\n * Failure codes a buffered execution can report, matching the codes the\n * removed kernel `Shell` used so handler-level mapping is unchanged.\n *\n * @category models\n * @since 1.0.0\n */\nexport const ExecErrorCode = Schema.Literals([\"timeout\", \"spawn_error\", \"arguments_too_long\", \"capture_overflow\"])\n\n/**\n * Failure codes a buffered execution can report.\n *\n * @category models\n * @since 1.0.0\n */\nexport type ExecErrorCode = typeof ExecErrorCode.Type\n\n/**\n * A command that never produced an exit code.\n *\n * A non-zero exit is a successful {@link ExecResult}, not a failure; this\n * error is reserved for a command that could not start (`arguments_too_long`\n * when the operating system refused it for the size of its arguments) or was\n * cut off by its timeout, or whose captured output exceeded a refusing capture\n * bound.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class ExecError extends Schema.TaggedError<ExecError>()(\"@smthrs/std/ExecError\", {\n  code: ExecErrorCode,\n  message: Schema.String,\n  /** The limit a `timeout` ran past, in milliseconds. */\n  limitMillis: Schema.optional(Schema.Number)\n}) {}\n\n/**\n * The buffered result of one command.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecResult {\n  readonly stdout: string\n  readonly stderr: string\n  readonly exitCode: number\n  /** UTF-8 bytes of stdout dropped to stay inside the capture bound; see `overflow`. */\n  readonly stdoutDroppedBytes: number\n  /** UTF-8 bytes of stderr dropped to stay inside the capture bound; see `overflow`. */\n  readonly stderrDroppedBytes: number\n}\n\n/**\n * Options accepted by {@link exec}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecOptions {\n  readonly cwd?: string | undefined\n  readonly env?: Readonly<Record<string, string>> | undefined\n  readonly timeoutMs?: number | undefined\n  /**\n   * The program's arguments. Present means an argv, absent means a command\n   * line for the platform shell. An argv is how a payload reaches a program\n   * without being quoted into a string: nothing between here and `execve`\n   * re-parses it.\n   */\n  readonly args?: ReadonlyArray<string> | undefined\n  /**\n   * Text written to the program's standard input, as data. A script delivered\n   * this way is never quoted, escaped, or heredoc-terminated, which is the\n   * whole point: quoting corruption cost the measured SWE-bench program twelve\n   * probe failures and one instance's most expensive frame.\n   */\n  readonly stdin?: string | undefined\n  /**\n   * Bytes retained per captured stream. A stream that prints more keeps what\n   * `overflow` names and reports what it dropped, so a command printing\n   * gigabytes costs a bounded amount of memory rather than the whole of what it\n   * printed.\n   *\n   * Absent means unbounded, which is what a caller wants when it needs every\n   * byte a tool produced (`rg --files`, `git worktree list`).\n   */\n  readonly maxCaptureBytes?: number | undefined\n  /**\n   * What a stream past the bound keeps. `tail`, the default, keeps its last\n   * bytes. `ends` keeps its first and last halves and puts one line naming the\n   * dropped bytes where the middle was. `refuse` fails if either stream exceeds\n   * the bound.\n   */\n  readonly overflow?: Overflow | undefined\n}\n\ntype Overflow = \"tail\" | \"ends\" | \"refuse\"\n\n/** One captured stream: the text kept, and the bytes dropped to keep it bounded. */\ninterface Capture {\n  readonly text: string\n  readonly droppedBytes: number\n}\n\ninterface Tail {\n  chunks: Array<Uint8Array>\n  bytes: number\n  dropped: number\n}\n\n/** A stream's first bytes and its last ones: what `overflow: \"ends\"` keeps. */\ninterface Ends {\n  readonly head: Array<Uint8Array>\n  headBytes: number\n  readonly tail: Tail\n}\n\nconst decoder = new TextDecoder(\"utf-8\")\n\nconst emptyTail = (): Tail => ({ chunks: [], bytes: 0, dropped: 0 })\n\n/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */\nconst isContinuation = (byte: number): boolean => (byte & 0b1100_0000) === 0b1000_0000\n\nconst join = (chunks: ReadonlyArray<Uint8Array>, size: number): Uint8Array => {\n  const bytes = new Uint8Array(size)\n  let offset = 0\n  for (const chunk of chunks) {\n    bytes.set(chunk, offset)\n    offset += chunk.byteLength\n  }\n  return bytes\n}\n\n/** Appends one chunk and drops from the front whatever no longer fits. */\nconst keepTail = (state: Tail, chunk: Uint8Array, maxBytes: number): void => {\n  if (chunk.byteLength === 0) return\n  state.chunks.push(chunk)\n  state.bytes += chunk.byteLength\n  while (state.bytes > maxBytes && state.chunks.length > 0) {\n    const excess = state.bytes - maxBytes\n    const first = state.chunks[0]!\n    if (first.byteLength <= excess) {\n      state.chunks.shift()\n      state.bytes -= first.byteLength\n      state.dropped += first.byteLength\n    } else {\n      state.chunks[0] = first.subarray(excess)\n      state.bytes -= excess\n      state.dropped += excess\n    }\n  }\n}\n\n/**\n * Joins the retained chunks and decodes them, skipping the partial code point a\n * dropped head can leave behind.\n *\n * A code point is at most four bytes, so at most three leading continuation\n * bytes can precede the first whole character. Skipping them is counted as\n * dropped rather than decoded to a replacement character the process never\n * printed.\n */\nconst decodeTail = (state: Tail): Capture => {\n  const bytes = join(state.chunks, state.bytes)\n  if (state.dropped === 0) return { text: decoder.decode(bytes), droppedBytes: 0 }\n  let start = 0\n  while (start < bytes.byteLength && start < 3 && isContinuation(bytes[start]!)) start++\n  return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start }\n}\n\n/**\n * The length of a cut head without the character the cut left unfinished.\n *\n * Its last character starts at the last byte that is not a continuation byte,\n * and that byte says how many bytes the character needs. One that needs more\n * than the head holds is dropped, for the same reason {@link decodeTail} skips\n * a partial code point.\n */\nconst wholeLength = (bytes: Uint8Array): number => {\n  for (let back = 1; back <= Math.min(3, bytes.byteLength); back++) {\n    const byte = bytes[bytes.byteLength - back]!\n    if (isContinuation(byte)) continue\n    const width = byte >= 0b1111_0000 ? 4 : byte >= 0b1110_0000 ? 3 : byte >= 0b1100_0000 ? 2 : 1\n    return width > back ? bytes.byteLength - back : bytes.byteLength\n  }\n  return bytes.byteLength\n}\n\n/**\n * Decodes a stream kept by its ends. A stream that fit is decoded whole;\n * otherwise each end is cut on a character boundary and one line naming every\n * byte between them stands where the middle was.\n */\nconst decodeEnds = (state: Ends): Capture => {\n  if (state.tail.dropped === 0) {\n    const whole = join([...state.head, ...state.tail.chunks], state.headBytes + state.tail.bytes)\n    return { text: decoder.decode(whole), droppedBytes: 0 }\n  }\n  const head = join(state.head, state.headBytes)\n  const kept = wholeLength(head)\n  const tail = decodeTail(state.tail)\n  const droppedBytes = head.byteLength - kept + tail.droppedBytes\n  return { text: elideMiddle(decoder.decode(head.subarray(0, kept)), droppedBytes, tail.text), droppedBytes }\n}\n\nconst boundedTail = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number,\n  overflow: Overflow | undefined\n): Effect.Effect<Capture, E> =>\n  Stream.runFold(stream, emptyTail, (state, chunk) => {\n    keepTail(state, chunk, maxBytes)\n    return state\n  }).pipe(Effect.map((state) =>\n    overflow === \"refuse\" && state.dropped > 0\n      ? { text: \"\", droppedBytes: state.dropped }\n      : decodeTail(state)\n  ))\n\n/**\n * Keeps the first half of the bound and the last half. The head fills first,\n * and every byte after it passes through the tail, which drops from its front:\n * what falls out of the tail is the middle.\n */\nconst boundedEnds = <E>(stream: Stream.Stream<Uint8Array, E>, maxBytes: number): Effect.Effect<Capture, E> => {\n  const headBytes = Math.floor(maxBytes / 2)\n  return Stream.runFold(stream, (): Ends => ({ head: [], headBytes: 0, tail: emptyTail() }), (state, chunk) => {\n    const taken = Math.min(headBytes - state.headBytes, chunk.byteLength)\n    if (taken > 0) {\n      state.head.push(chunk.subarray(0, taken))\n      state.headBytes += taken\n    }\n    keepTail(state.tail, chunk.subarray(taken), maxBytes - headBytes)\n    return state\n  }).pipe(Effect.map(decodeEnds))\n}\n\nconst capture = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number | undefined,\n  overflow: Overflow | undefined\n): Effect.Effect<Capture, E> =>\n  maxBytes === undefined\n    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))\n    : overflow === \"ends\"\n    ? boundedEnds(stream, maxBytes)\n    : boundedTail(stream, maxBytes, overflow)\n\n/**\n * A command whose arguments exceed the operating system's limit fails `execve`\n * with `E2BIG` before it starts: one argument over 128 KiB on Linux, all of\n * them over 1 MiB on macOS. A heredoc in a command line, or a file's text\n * passed as an argument, is one such argument. The platform error's own text\n * repeats the whole command line, so this text is written here instead, and a\n * caller may show it as it stands.\n */\nconst argumentsTooLong = (error: { readonly cause?: unknown }): ExecError | undefined =>\n  (error.cause as { readonly code?: unknown } | undefined)?.code === \"E2BIG\"\n    ? new ExecError({\n      code: \"arguments_too_long\",\n      message:\n        \"Command not started: its arguments exceed the operating system's size limit (E2BIG). Send long text on standard input or in a file, not in the command line or its arguments.\"\n    })\n    : undefined\n\nconst unbounded = (\n  command: string,\n  options: ExecOptions\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n    const settings: ChildProcess.CommandOptions = {\n      ...(options.args === undefined ? { shell: true } : {}),\n      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),\n      env: ChildProcessEnvironment.make(process.env, options.env),\n      extendEnv: false,\n      ...(options.stdin === undefined\n        ? {}\n        : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) })\n    }\n    const handle = yield* spawner.spawn(\n      options.args === undefined\n        ? ChildProcess.make(command, settings)\n        : ChildProcess.make(command, [...options.args], settings)\n    )\n    // stdout, stderr, and the exit code have to be consumed concurrently: a\n    // command that fills a pipe blocks until the pipe is drained, so waiting\n    // for exit first would deadlock on any output larger than the buffer.\n    const [stdout, stderr, exitCode] = yield* Effect.all(\n      [\n        capture(handle.stdout, options.maxCaptureBytes, options.overflow),\n        capture(handle.stderr, options.maxCaptureBytes, options.overflow),\n        handle.exitCode\n      ],\n      { concurrency: \"unbounded\" }\n    )\n    if (options.overflow === \"refuse\") {\n      const overflowed = [\n        stdout.droppedBytes > 0 ? \"stdout\" : undefined,\n        stderr.droppedBytes > 0 ? \"stderr\" : undefined\n      ]\n        .filter((stream): stream is string => stream !== undefined)\n      if (overflowed.length > 0) {\n        return yield* Effect.fail(\n          new ExecError({\n            code: \"capture_overflow\",\n            message: `${command} ${\n              overflowed.join(\" and \")\n            } exceeded the ${options.maxCaptureBytes}-byte capture cap; refusing partial output`\n          })\n        )\n      }\n    }\n    return {\n      stdout: stdout.text,\n      stderr: stderr.text,\n      exitCode,\n      stdoutDroppedBytes: stdout.droppedBytes,\n      stderrDroppedBytes: stderr.droppedBytes\n    }\n  }).pipe(\n    Effect.scoped,\n    Effect.mapError((error) =>\n      error instanceof ExecError ? error : argumentsTooLong(error) ?? new ExecError({\n        code: \"spawn_error\",\n        message: `exec: ${command}: ${error.message}`\n      })\n    )\n  )\n\n/**\n * Runs a command line through the platform shell and buffers its output.\n *\n * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber\n * — including the one a `timeoutMs` interrupts — terminates the process rather\n * than leaking it.\n *\n * @category execution\n * @since 1.0.0\n */\nexport const exec = (\n  command: string,\n  options: ExecOptions = {}\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  options.timeoutMs === undefined\n    ? unbounded(command, options)\n    : Effect.timeoutOrElse(unbounded(command, options), {\n      duration: options.timeoutMs,\n      orElse: () =>\n        Effect.fail(\n          new ExecError({\n            code: \"timeout\",\n            message: `exec: \\`${command}\\` exceeded ${options.timeoutMs}ms`,\n            limitMillis: options.timeoutMs\n          })\n        )\n    })\n\n/**\n * The model-facing failure code a command that never produced an exit code\n * carries.\n *\n * A timeout keeps its own code, because \"the command never finished\" and \"the\n * command never started\" are different things to a caller deciding whether to\n * retry. Arguments the operating system refused for their size are the\n * caller's own input, which a shell flow publishes, so they read as\n * `invalid_input`. Every other way of producing no exit code is a host failure.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdErrorCode = (error: ExecError): StdError.Code =>\n  error.code === \"timeout\" ? \"timeout\" : error.code === \"arguments_too_long\" ? \"invalid_input\" : \"command_failed\"\n\n/**\n * The model-facing failure one execution error becomes.\n *\n * A timeout names the command, which is what the caller asked for and all a\n * timeout has to say. Arguments too long to start carry the reason and the\n * fix, and nothing of the command. Any other failure carries the message the\n * execution produced, which already names the command.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdError = (command: string, error: ExecError): StdError.StdError =>\n  new StdError.StdError({\n    code: toStdErrorCode(error),\n    message: error.code === \"timeout\"\n      ? `Command timed out: ${command}`\n      : error.code === \"arguments_too_long\"\n      ? error.message\n      : `Command failed to start: ${error.message}`,\n    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })\n  })\n"]}

package/dist/esm/internal/Text.d.ts

@@ -85,6 +85,17 @@ export interface Page {
 export declare const truncateBytes: (text: string, maxBytes: number, options: {
     readonly keep: "head" | "tail";
 }) => Truncation;
+/**
+ * Joins the start and the end of a stream cut in the middle around one line
+ * naming the bytes cut between them.
+ *
+ * The line stands alone, so a start that stops mid-line is ended before it.
+ * Only the line's own newlines are added; `droppedBytes` counts printed bytes.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.5
+ */
+export declare const elideMiddle: (start: string, droppedBytes: number, end: string) => string;
 /**
  * Splits on LF without counting a terminal LF as a line.
  * Carriage returns remain part of each line, including the CR in CRLF, so

package/dist/esm/internal/Text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Text.d.ts","sourceRoot":"","sources":["../../../src/internal/Text.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,OAAQ,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,OAAQ,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,OAAQ,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,KAC1C,UAwBF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,aAAa,CAAC,MAAM,CAI9D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,MAAM,EACZ,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAC3D,IAWF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MACL,CAAA"}
+{"version":3,"file":"Text.d.ts","sourceRoot":"","sources":["../../../src/internal/Text.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,OAAQ,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,OAAQ,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,OAAQ,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,KAC1C,UAwBF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,EAAE,cAAc,MAAM,EAAE,KAAK,MAAM,KAAG,MAG1D,CAAA;AAErB;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,aAAa,CAAC,MAAM,CAI9D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,MAAM,EACZ,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAC3D,IAWF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MACL,CAAA"}

package/dist/esm/internal/Text.js

@@ -88,6 +88,17 @@ export const truncateBytes = (text, maxBytes, options) => {
         }
     }
 };
+/**
+ * Joins the start and the end of a stream cut in the middle around one line
+ * naming the bytes cut between them.
+ *
+ * The line stands alone, so a start that stops mid-line is ended before it.
+ * Only the line's own newlines are added; `droppedBytes` counts printed bytes.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.5
+ */
+export const elideMiddle = (start, droppedBytes, end) => `${start}${start === "" || start.endsWith("\n") ? "" : "\n"}[${droppedBytes} ${droppedBytes === 1 ? "byte" : "bytes"} omitted]\n${end}`;
 /**
  * Splits on LF without counting a terminal LF as a line.
  * Carriage returns remain part of each line, including the CR in CRLF, so

package/dist/esm/internal/Text.js.map

@@ -1 +1 @@
-{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/internal/Text.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared text paging, numbering, and byte-budget helpers.\n *\n * Every limit here is a display budget, not a policy limit: exceeding one is\n * always disclosed to the model rather than silently applied.\n *\n * @since 1.0.0\n */\n\n/**\n * Default number of lines or entries returned by a paged flow.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const DEFAULT_READ_LIMIT = 2_000\n\n/**\n * Maximum number of directory entries or glob paths returned in one call.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_ENTRIES = 1_000\n\n/**\n * Maximum number of grep matches returned in one call.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_GREP_MATCHES = 200\n\n/**\n * Maximum number of Unicode scalar values displayed for a single line.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_LINE_CHARS = 2_000\n\n/**\n * Maximum UTF-8 byte budget for one rendered text payload.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_OUTPUT_BYTES = 60_000\n\n/**\n * Maximum UTF-8 byte budget captured per shell output stream.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_SHELL_OUTPUT_BYTES = 30_000\n\n/**\n * A byte-budgeted rendering of a text value.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Truncation {\n  readonly text: string\n  readonly truncated: boolean\n  readonly keptBytes: number\n  readonly droppedBytes: number\n}\n\n/**\n * One page of source lines.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Page {\n  readonly lines: ReadonlyArray<string>\n  readonly startLine: number\n  readonly endLine: number\n  readonly totalLines: number\n}\n\nconst encoder = new TextEncoder()\nconst fatalDecoder = new TextDecoder(\"utf-8\", { fatal: true })\n\n/**\n * Trims a string to a UTF-8 byte budget without splitting a code point.\n *\n * `keep: \"head\"` retains the beginning of the value; `keep: \"tail\"` retains\n * the end, which is what shell output needs because the interesting part of an\n * overflowing stream is almost always its last lines.\n *\n * @category rendering\n * @since 1.0.0\n */\nexport const truncateBytes = (\n  text: string,\n  maxBytes: number,\n  options: { readonly keep: \"head\" | \"tail\" }\n): Truncation => {\n  const bytes = encoder.encode(text)\n  if (bytes.byteLength <= maxBytes) {\n    return { text, truncated: false, keptBytes: bytes.byteLength, droppedBytes: 0 }\n  }\n  let start = options.keep === \"head\" ? 0 : bytes.byteLength - maxBytes\n  let end = options.keep === \"head\" ? maxBytes : bytes.byteLength\n  // TextEncoder produces valid UTF-8. Moving a cut inward reaches a scalar\n  // boundary after at most three continuation bytes, so decoding must succeed.\n  while (true) {\n    try {\n      const decoded = fatalDecoder.decode(bytes.subarray(start, end))\n      const keptBytes = end - start\n      return {\n        text: decoded,\n        truncated: true,\n        keptBytes,\n        droppedBytes: bytes.byteLength - keptBytes\n      }\n    } catch {\n      if (options.keep === \"head\") end--\n      else start++\n    }\n  }\n}\n\n/**\n * Splits on LF without counting a terminal LF as a line.\n * Carriage returns remain part of each line, including the CR in CRLF, so\n * joining a page with LF preserves its bytes except for the final LF.\n *\n * @category parsing\n * @since 1.0.0\n */\nexport const sourceLines = (text: string): ReadonlyArray<string> => {\n  const lines = text.length === 0 ? [] : text.split(\"\\n\")\n  if (text.endsWith(\"\\n\")) lines.pop()\n  return lines\n}\n\n/**\n * Selects a 1-based page of lines from a text value.\n *\n * @category paging\n * @since 1.0.0\n */\nexport const slice = (\n  text: string,\n  options: { readonly offset: number; readonly limit: number }\n): Page => {\n  const lines = sourceLines(text)\n  const totalLines = lines.length\n  const startLine = Math.max(1, options.offset)\n  const endLine = Math.min(totalLines, startLine + Math.max(0, options.limit) - 1)\n  return {\n    lines: lines.slice(startLine - 1, endLine),\n    startLine,\n    endLine,\n    totalLines\n  }\n}\n\n/**\n * Renders the disclosure appended whenever output was capped.\n *\n * @category rendering\n * @since 1.0.0\n */\nexport const notice = (unit: string, shown: number, total: number): string =>\n  `Showing ${shown} of ${total} ${unit}; output was truncated.`\n"]}
+{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/internal/Text.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared text paging, numbering, and byte-budget helpers.\n *\n * Every limit here is a display budget, not a policy limit: exceeding one is\n * always disclosed to the model rather than silently applied.\n *\n * @since 1.0.0\n */\n\n/**\n * Default number of lines or entries returned by a paged flow.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const DEFAULT_READ_LIMIT = 2_000\n\n/**\n * Maximum number of directory entries or glob paths returned in one call.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_ENTRIES = 1_000\n\n/**\n * Maximum number of grep matches returned in one call.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_GREP_MATCHES = 200\n\n/**\n * Maximum number of Unicode scalar values displayed for a single line.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_LINE_CHARS = 2_000\n\n/**\n * Maximum UTF-8 byte budget for one rendered text payload.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_OUTPUT_BYTES = 60_000\n\n/**\n * Maximum UTF-8 byte budget captured per shell output stream.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_SHELL_OUTPUT_BYTES = 30_000\n\n/**\n * A byte-budgeted rendering of a text value.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Truncation {\n  readonly text: string\n  readonly truncated: boolean\n  readonly keptBytes: number\n  readonly droppedBytes: number\n}\n\n/**\n * One page of source lines.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Page {\n  readonly lines: ReadonlyArray<string>\n  readonly startLine: number\n  readonly endLine: number\n  readonly totalLines: number\n}\n\nconst encoder = new TextEncoder()\nconst fatalDecoder = new TextDecoder(\"utf-8\", { fatal: true })\n\n/**\n * Trims a string to a UTF-8 byte budget without splitting a code point.\n *\n * `keep: \"head\"` retains the beginning of the value; `keep: \"tail\"` retains\n * the end, which is what shell output needs because the interesting part of an\n * overflowing stream is almost always its last lines.\n *\n * @category rendering\n * @since 1.0.0\n */\nexport const truncateBytes = (\n  text: string,\n  maxBytes: number,\n  options: { readonly keep: \"head\" | \"tail\" }\n): Truncation => {\n  const bytes = encoder.encode(text)\n  if (bytes.byteLength <= maxBytes) {\n    return { text, truncated: false, keptBytes: bytes.byteLength, droppedBytes: 0 }\n  }\n  let start = options.keep === \"head\" ? 0 : bytes.byteLength - maxBytes\n  let end = options.keep === \"head\" ? maxBytes : bytes.byteLength\n  // TextEncoder produces valid UTF-8. Moving a cut inward reaches a scalar\n  // boundary after at most three continuation bytes, so decoding must succeed.\n  while (true) {\n    try {\n      const decoded = fatalDecoder.decode(bytes.subarray(start, end))\n      const keptBytes = end - start\n      return {\n        text: decoded,\n        truncated: true,\n        keptBytes,\n        droppedBytes: bytes.byteLength - keptBytes\n      }\n    } catch {\n      if (options.keep === \"head\") end--\n      else start++\n    }\n  }\n}\n\n/**\n * Joins the start and the end of a stream cut in the middle around one line\n * naming the bytes cut between them.\n *\n * The line stands alone, so a start that stops mid-line is ended before it.\n * Only the line's own newlines are added; `droppedBytes` counts printed bytes.\n *\n * @category rendering\n * @since 1.0.0-rc.5\n */\nexport const elideMiddle = (start: string, droppedBytes: number, end: string): string =>\n  `${start}${start === \"\" || start.endsWith(\"\\n\") ? \"\" : \"\\n\"}[${droppedBytes} ${\n    droppedBytes === 1 ? \"byte\" : \"bytes\"\n  } omitted]\\n${end}`\n\n/**\n * Splits on LF without counting a terminal LF as a line.\n * Carriage returns remain part of each line, including the CR in CRLF, so\n * joining a page with LF preserves its bytes except for the final LF.\n *\n * @category parsing\n * @since 1.0.0\n */\nexport const sourceLines = (text: string): ReadonlyArray<string> => {\n  const lines = text.length === 0 ? [] : text.split(\"\\n\")\n  if (text.endsWith(\"\\n\")) lines.pop()\n  return lines\n}\n\n/**\n * Selects a 1-based page of lines from a text value.\n *\n * @category paging\n * @since 1.0.0\n */\nexport const slice = (\n  text: string,\n  options: { readonly offset: number; readonly limit: number }\n): Page => {\n  const lines = sourceLines(text)\n  const totalLines = lines.length\n  const startLine = Math.max(1, options.offset)\n  const endLine = Math.min(totalLines, startLine + Math.max(0, options.limit) - 1)\n  return {\n    lines: lines.slice(startLine - 1, endLine),\n    startLine,\n    endLine,\n    totalLines\n  }\n}\n\n/**\n * Renders the disclosure appended whenever output was capped.\n *\n * @category rendering\n * @since 1.0.0\n */\nexport const notice = (unit: string, shown: number, total: number): string =>\n  `Showing ${shown} of ${total} ${unit}; output was truncated.`\n"]}

package/docs/README.md

@@ -42,7 +42,9 @@ the details that decide whether a model gets its next step right:
 
 ## Install
 
-Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+```bash
+npm install @smthrs/std@next effect
+```
 
 The handlers
 ask the host for services such as `FileSystem`, `Path`, and

package/docs/api.md

@@ -60,7 +60,7 @@ Some of them export more than the common nine:
 
 | Module         | Additional exports                                                                          |
 | -------------- | ------------------------------------------------------------------------------------------- |
-| `Bash`         | `DEFAULT_TIMEOUT_MS`                                                                        |
+| `Bash`         | `DEFAULT_TIMEOUT_MS`, `elideMiddle(start, droppedBytes, end)`                               |
 | `Explore`      | `make(options: { model?: string })`, and no `run`                                           |
 | `Grep`         | `ContextLine`, `Symbol`, `Match` schemas                                                    |
 | `Read`         | `MAX_READ_FILE_BYTES`, the 64 MiB bound past which `read` refuses a file                    |
@@ -307,23 +307,26 @@ How the project under test runs its suite, declared once by the host.
 
 Pinned trees, and the scratch checkouts a call runs against.
 
-| Export             | Type                                                                       | Meaning                                                          |
-| ------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `Checkpoints`      | interface and `Context.Service` tag                                        | `{ capture, materialize }`.                                      |
-| `Snapshot`         | `Schema.Class`                                                             | `{ id, ref }`, identified as `@smthrs/std/Checkpoints/Snapshot`. |
-| `Materialized`     | interface                                                                  | `id`, `host`, `guest`, `root`, `guestRoot`.                      |
-| `baseId`           | `"base"`                                                                   | The id naming the tree the run opened on.                        |
-| `scratchDirectory` | `".flows-checkpoints"`                                                     | Where a checkpoint is materialized, relative to the root.        |
-| `configSection`    | `"flows-checkpoint"`                                                       | The git-config section minted checkpoints are recorded under.    |
-| `make`             | `(service: Checkpoints) => Checkpoints`                                    |                                                                  |
-| `unavailable`      | `(id: string) => StdError`                                                 | The refusal a host that pins nothing answers with.               |
-| `makeNoop`         | `() => Checkpoints`                                                        | Fails both calls with `unavailable`.                             |
-| `layerNoop`        | `Layer<Checkpoints>`                                                       |                                                                  |
-| `GitOptions`       | interface                                                                  | `root`, `cwd?`, `baseRef?`.                                      |
-| `makeGit`          | `(options: GitOptions) => Effect<Checkpoints, never, ChildProcessSpawner>` |                                                                  |
-| `layerGit`         | `(options: GitOptions) => Layer<Checkpoints, never, ChildProcessSpawner>`  |                                                                  |
-| `Relocation`       | tagged union                                                               | `Relocated`, `UnsupportedFlow`, `AbsolutePath`, `OutsideTree`.   |
-| `relocate`         | `(flow: string, input: Json, materialized: Materialized) => Relocation`    | Rewrites one call's input onto a checkpoint.                     |
+| Export             | Type                                                                                          | Meaning                                                          |
+| ------------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `Checkpoints`      | interface and `Context.Service` tag                                                           | `{ capture, materialize }`.                                      |
+| `Snapshot`         | `Schema.Class`                                                                                | `{ id, ref }`, identified as `@smthrs/std/Checkpoints/Snapshot`. |
+| `Materialized`     | interface                                                                                     | `id`, `host`, `guest`, `root`, `guestRoot`.                      |
+| `baseId`           | `"base"`                                                                                      | The id naming the tree the run opened on.                        |
+| `scratchDirectory` | `".flows-checkpoints"`                                                                        | Where a checkpoint is materialized, relative to the root.        |
+| `configSection`    | `"flows-checkpoint"`                                                                          | The git-config section minted checkpoints are recorded under.    |
+| `make`             | `(service: Checkpoints) => Checkpoints`                                                       |                                                                  |
+| `unavailable`      | `(id: string) => StdError`                                                                    | The refusal a host that pins nothing answers with.               |
+| `makeNoop`         | `() => Checkpoints`                                                                           | Fails both calls with `unavailable`.                             |
+| `layerNoop`        | `Layer<Checkpoints>`                                                                          |                                                                  |
+| `GitOptions`       | interface                                                                                     | `root`, `cwd?`, `baseRef?`.                                      |
+| `makeGit`          | `(options: GitOptions) => Effect<Checkpoints, never, ChildProcessSpawner>`                    |                                                                  |
+| `layerGit`         | `(options: GitOptions) => Layer<Checkpoints, never, ChildProcessSpawner>`                     |                                                                  |
+| `ContainerOptions` | interface                                                                                     | `container`, `cwd?`.                                             |
+| `makeContainer`    | `(options: ContainerOptions) => Effect<Checkpoints, never, ChildProcessSpawner \| Container>` | Runs git inside the container `bash` runs in.                    |
+| `layerContainer`   | `(options: ContainerOptions) => Layer<Checkpoints, never, ChildProcessSpawner \| Container>`  |                                                                  |
+| `Relocation`       | tagged union                                                                                  | `Relocated`, `UnsupportedFlow`, `AbsolutePath`, `OutsideTree`.   |
+| `relocate`         | `(flow: string, input: Json, materialized: Materialized) => Relocation`                       | Rewrites one call's input onto a checkpoint.                     |
 
 `capture(id)` returns a `Snapshot`. `materialize(id, use)` is scoped: it hands
 the tree to `use` and removes the checkout however that effect ends. Host git

package/docs/concepts/limits-and-disclosure.md

@@ -84,17 +84,20 @@ caller paging a large directory could see one entry twice and another never.
 `stdoutTruncated`, `stderrTruncated`, and `tailTruncated` are not display
 details. A truncated capture is a fragment of what the process printed, and
 [`@smthrs/harness`](/api/harness) reads these flags to refuse a later write of
-those exact bytes: writing a captured tail over a file replaces the file with
-the end of a log. Read the flag before writing captured output anywhere, and set
+those exact bytes: writing a captured fragment over a file replaces the file
+with a piece of a log. Read the flag before writing captured output anywhere, and set
 it in your own handler whenever you cut a capture: a consumer that cannot tell a
 fragment from the whole writes the fragment.
 
 `stdoutDroppedBytes`, `stderrDroppedBytes`, and `tailDroppedBytes` count what
 the process actually produced beyond the capture. Capture is bounded where the
 stream is read rather than after it is read, so a command that prints gigabytes
-costs the bound instead of the whole of what it printed. `bash` keeps the tail
-of each stream, because a failing command prints its verdict last; `read`,
-`fetch`, and `http-post` keep the head.
+costs the bound instead of the whole of what it printed. `bash` keeps the
+first and last 15,000 bytes of each stream and puts one line such as
+`[10025 bytes omitted]` where the middle was, because a search prints its
+matches first and a failing command prints its verdict last. Its dropped-bytes
+count is the size of that middle. `test` keeps the tail; `read`, `fetch`, and
+`http-post` keep the head.
 
 Every caller-supplied command (`bash`, `test`, `shell_command`) passes a capture
 bound. The internal `git` plumbing behind `Checkpoints` and `TestRun`'s baseline

package/docs/guides/pin-a-checkpoint.md

@@ -32,6 +32,26 @@ const store = Checkpoints.layerGit({
 `Checkpoints.layerNoop`, whose refusal says to take the reading on the live tree
 instead.
 
+## Bind the container store
+
+When the repository lives only in a container and `bash` runs there, bind
+`layerContainer` instead. It runs git inside that container through the
+`Container` transport `bash` uses, so `ctx.base` and `ctx.checkpoint()` read the
+container's tree. A git store would look for the repository on the host and
+refuse every call that names a checkpoint.
+
+```ts
+const store = Checkpoints.layerContainer({
+  container: "task", // the container `bash` runs in
+  cwd: "/app" // optional; absent is the container's working directory
+})
+```
+
+`layerContainer` requires a `ChildProcessSpawner` and a `Container`. It records
+and names a checkpoint as the git store does, and checks a tree out at the same
+`<top>/.flows-checkpoints/<id>-<lease>` path inside the container, so a
+relocated `bash` call keeps its subdirectory.
+
 ## Capture and materialize
 
 ```ts

package/docs/guides/run-a-shell-command.md

@@ -159,15 +159,25 @@ channel.
 | Field                                      | Meaning                                                     |
 | ------------------------------------------ | ----------------------------------------------------------- |
 | `exitCode`                                 | The command's exit code.                                    |
-| `stdout`, `stderr`                         | The captured streams, tail-first when truncated.            |
+| `stdout`, `stderr`                         | The captured streams; start and end when truncated.         |
 | `stdoutTruncated`, `stderrTruncated`       | Whether that stream is a fragment.                          |
-| `stdoutDroppedBytes`, `stderrDroppedBytes` | Bytes omitted from the start.                               |
+| `stdoutDroppedBytes`, `stderrDroppedBytes` | Bytes omitted from the middle.                              |
 | `invalidProbe`                             | Present when the shell refused to start the command at all. |
 
-Each stream is bounded at 30,000 bytes and the tail is kept, because a failing
-command prints its verdict last. Never write a truncated stream to a file: it is
-the end of a log, not the content it came from. `@smthrs/harness` reads the
-`Truncated` flags to refuse exactly that.
+Each stream is bounded at 30,000 bytes: its first 15,000 and its last 15,000.
+A search prints its matches first and a failing command prints its verdict
+last, so both survive. One line stands where the middle was:
+
+```text
+MARKER-HEAD
+xxxxxxxxxxxx
+[10025 bytes omitted]
+xxxxxxxxxxxx
+MARKER-TAIL
+```
+
+Never write a truncated stream to a file: it is a fragment, not the content it
+came from. `@smthrs/harness` reads the `Truncated` flags to refuse exactly that.
 
 `timeoutMs` defaults to `Bash.DEFAULT_TIMEOUT_MS`, ten minutes.
 

package/docs/installation.md

@@ -7,7 +7,11 @@ sidebar:
 
 ## Install the package
 
-Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+```bash
+npm install @smthrs/std@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
 
 It requires
 Node.js 26.4.0 or later and ships as both ESM and CommonJS with TypeScript
@@ -92,14 +96,14 @@ Six flows reach the host through a service rather than through a platform layer.
 Each one has a refusal layer for a host that cannot serve it, so a flow whose
 service is missing says so instead of succeeding quietly.
 
-| Service          | Refusal layer              | Working layer                                   |
-| ---------------- | -------------------------- | ----------------------------------------------- |
-| `Search`         | `Search.layerNoop`         | `PortableSearch.layer` or `NativeSearch.layer`  |
-| `Container`      | `Container.layerNoop`      | `Container.layerCommand({ program: "docker" })` |
-| `TestRunner`     | `TestRunner.layerNoop`     | `TestRunner.layer(runner)`                      |
-| `Checkpoints`    | `Checkpoints.layerNoop`    | `Checkpoints.layerGit({ root })`                |
-| `WebSearch`      | `WebSearch.layerNoop`      | `ExaWebSearch.layer(credentialId)`              |
-| `LanguageServer` | `LanguageServer.layerNoop` | `NodeLanguageServer.layer(config)`              |
+| Service          | Refusal layer              | Working layer                                                                   |
+| ---------------- | -------------------------- | ------------------------------------------------------------------------------- |
+| `Search`         | `Search.layerNoop`         | `PortableSearch.layer` or `NativeSearch.layer`                                  |
+| `Container`      | `Container.layerNoop`      | `Container.layerCommand({ program: "docker" })`                                 |
+| `TestRunner`     | `TestRunner.layerNoop`     | `TestRunner.layer(runner)`                                                      |
+| `Checkpoints`    | `Checkpoints.layerNoop`    | `Checkpoints.layerGit({ root })` or `Checkpoints.layerContainer({ container })` |
+| `WebSearch`      | `WebSearch.layerNoop`      | `ExaWebSearch.layer(credentialId)`                                              |
+| `LanguageServer` | `LanguageServer.layerNoop` | `NodeLanguageServer.layer(config)`                                              |
 
 `NativeSearch.layer` drives the `rg` executable, so a host that binds it needs
 ripgrep on the path. `PortableSearch.layer` needs nothing beyond `FileSystem`

package/docs/quickstart.md

@@ -14,7 +14,7 @@ without an external binary and without an API key.
 ## Prerequisites
 
 - Node.js 26.4.0 or later.
-- A package with the dependencies installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+- A project with the packages installed: `npm install @smthrs/std@next @effect/platform-node effect`.
 
 ## Make a tree to search