@smthrs/std 1.0.0-rc.5 → 1.0.0-rc.7

package/docs/reference/flows.md

@@ -241,9 +241,9 @@ envelope `bash` declares for every call.
 | Output                                     | Type                           | Meaning                                                                            |
 | ------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------- |
 | `exitCode`                                 | number                         | The command's exit code, including non-zero.                                       |
-| `stdout`, `stderr`                         | string                         | Captured streams, tail kept when truncated.                                        |
+| `stdout`, `stderr`                         | string                         | Captured streams; start and end kept when truncated.                               |
 | `stdoutTruncated`, `stderrTruncated`       | boolean                        | Whether that stream is a fragment.                                                 |
-| `stdoutDroppedBytes`, `stderrDroppedBytes` | number                         | Bytes omitted from the start.                                                      |
+| `stdoutDroppedBytes`, `stderrDroppedBytes` | number                         | Bytes omitted from the middle.                                                     |
 | `invalidProbe`                             | `Probe.InvalidProbe`, optional | Reserved for independently confirmed launch failures; not inferred from exit code. |
 
 `Bash.Input` and `Bash.Output` are also exported as TypeScript types alongside

package/docs/troubleshooting.md

@@ -260,11 +260,11 @@ runs. The server would have run workspace-written code on the host.
 absolute path, not a launcher. For typescript-language-server, also pin
 `initializationOptions: { tsserver: { path } }` to a host copy.
 
-## A write of captured output replaced a file with a log tail
+## A write of captured output replaced a file with a fragment
 
 **What happened.** A truncated `stdout`, `stderr`, or `tail` was written to a
-file. Those fields are fragments: the capture keeps the tail of what the process
-printed, not the whole of it.
+file. Those fields are fragments: `bash` keeps the start and the end of what the
+process printed and `test` keeps the tail, never the whole of it.
 
 **What to change.** Check `stdoutTruncated`, `stderrTruncated`, or
 `tailTruncated` before writing captured output anywhere.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/std",
   "type": "module",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "license": "MIT",
   "smthrs": {
     "group": "agent"
@@ -401,21 +401,21 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/capability": "1.0.0-rc.5",
-    "@smthrs/control": "1.0.0-rc.5",
-    "@smthrs/core": "1.0.0-rc.5",
-    "@smthrs/kernel": "1.0.0-rc.5",
-    "@smthrs/model": "1.0.0-rc.5"
+    "@smthrs/capability": "1.0.0-rc.7",
+    "@smthrs/control": "1.0.0-rc.7",
+    "@smthrs/core": "1.0.0-rc.7",
+    "@smthrs/kernel": "1.0.0-rc.7",
+    "@smthrs/model": "1.0.0-rc.7"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",
-    "@effect/platform-node": "4.0.0-rc.115",
-    "@effect/vitest": "4.0.0-rc.115",
+    "@effect/platform-node": "4.0.4",
+    "@effect/vitest": "4.0.4",
     "@eslint/js": "9.39.5",
     "@types/node": "26.4.1",
     "@vitest/coverage-v8": "5.0.0",
     "dprint": "0.57.1",
-    "effect": "4.0.0-rc.115",
+    "effect": "4.0.4",
     "esbuild": "0.28.2",
     "eslint": "9.39.5",
     "eslint-import-resolver-typescript": "4.4.5",
@@ -428,7 +428,7 @@
     "vitest": "5.0.0"
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.115"
+    "effect": "^4.0.4"
   },
   "scripts": {
     "lint": "eslint src --max-warnings=0 && dprint check",

package/src/Bash.ts

@@ -27,7 +27,7 @@ import { capability, envelope } from "./internal/Declaration.ts"
 import * as Diagnostics from "./internal/Diagnostics.ts"
 import { outsideEnvelope } from "./internal/EnvelopePrecheck.ts"
 import * as Exec from "./internal/Exec.ts"
-import { MAX_SHELL_OUTPUT_BYTES, truncateBytes } from "./internal/Text.ts"
+import { elideMiddle as elide, MAX_SHELL_OUTPUT_BYTES } from "./internal/Text.ts"
 import * as Probe from "./Probe.ts"
 import * as StdError from "./StdError.ts"
 import * as TreeFingerprint from "./TreeFingerprint.ts"
@@ -173,10 +173,12 @@ export type Input = typeof Input.Type
 export const Output = Schema.Struct({
   exitCode: Schema.Number.annotate({ description: "Command exit code, including non-zero codes" }),
   stdout: Schema.String.annotate({
-    description: "Captured stdout; only the tail, and not the whole output, when stdoutTruncated is true"
+    description:
+      "Captured stdout; when stdoutTruncated is true, only its start and end, with one line naming the bytes omitted between them"
   }),
   stderr: Schema.String.annotate({
-    description: "Captured stderr; only the tail, and not the whole output, when stderrTruncated is true"
+    description:
+      "Captured stderr; when stderrTruncated is true, only its start and end, with one line naming the bytes omitted between them"
   }),
   stdoutTruncated: Schema.Boolean.annotate({
     description:
@@ -186,8 +188,8 @@ export const Output = Schema.Struct({
     description:
       "Whether stderr exceeded the capture limit, leaving stderr a fragment that must not be written to a file"
   }),
-  stdoutDroppedBytes: Schema.Number.annotate({ description: "UTF-8 bytes omitted from the start of stdout" }),
-  stderrDroppedBytes: Schema.Number.annotate({ description: "UTF-8 bytes omitted from the start of stderr" }),
+  stdoutDroppedBytes: Schema.Number.annotate({ description: "UTF-8 bytes omitted from the middle of stdout" }),
+  stderrDroppedBytes: Schema.Number.annotate({ description: "UTF-8 bytes omitted from the middle of stderr" }),
   invalidProbe: Schema.optional(
     Probe.InvalidProbe.annotate({
       description: "Reserved for a confirmed launch failure; an exit code alone does not establish one"
@@ -209,6 +211,17 @@ export const Output = Schema.Struct({
  */
 export type Output = typeof Output.Type
 
+/**
+ * The text of a stream cut to its start and end: the start, one line naming
+ * the bytes omitted between them, and the end. A host that captures output
+ * itself, such as a terminal behind {@link inTerminal}, cuts with this so every
+ * {@link Output} reads the same.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.5
+ */
+export const elideMiddle: (start: string, droppedBytes: number, end: string) => string = elide
+
 /**
  * Static conservative effect envelope for the bash flow.
  *
@@ -500,6 +513,7 @@ export const run = Effect.fn("Bash.run")(function*(
     ...(spawned.env === undefined ? {} : { env: spawned.env }),
     timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     maxCaptureBytes: MAX_SHELL_OUTPUT_BYTES,
+    overflow: "ends",
     ...(spawned.args === undefined ? {} : { args: spawned.args }),
     ...(spawned.stdin === undefined ? {} : { stdin: spawned.stdin })
   }).pipe(Effect.mapError((error) => Exec.toStdError(spawned.quoted, error)))
@@ -507,18 +521,16 @@ export const run = Effect.fn("Bash.run")(function*(
   // A command on this host may have changed files a language server holds
   // open; a container's files are not the ones it was sent.
   if (!contained) yield* Diagnostics.refresh
-  const stdout = truncateBytes(result.stdout, MAX_SHELL_OUTPUT_BYTES, { keep: "tail" })
-  const stderr = truncateBytes(result.stderr, MAX_SHELL_OUTPUT_BYTES, { keep: "tail" })
   // Exit codes alone cannot establish whether the shell refused to launch a
   // command or a launched runner chose that status after executing tests.
   return {
     exitCode: result.exitCode,
-    stdout: stdout.text,
-    stderr: stderr.text,
-    stdoutTruncated: result.stdoutDroppedBytes > 0 || stdout.truncated,
-    stderrTruncated: result.stderrDroppedBytes > 0 || stderr.truncated,
-    stdoutDroppedBytes: result.stdoutDroppedBytes + stdout.droppedBytes,
-    stderrDroppedBytes: result.stderrDroppedBytes + stderr.droppedBytes,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    stdoutTruncated: result.stdoutDroppedBytes > 0,
+    stderrTruncated: result.stderrDroppedBytes > 0,
+    stdoutDroppedBytes: result.stdoutDroppedBytes,
+    stderrDroppedBytes: result.stderrDroppedBytes,
     ...(mutated === undefined ? {} : { mutated })
   }
 })

package/src/ExaWebSearch.ts

@@ -11,7 +11,7 @@
 import * as Credential from "@smthrs/control/Credential"
 import * as HttpClient from "@smthrs/kernel/HttpClient"
 import { Clock, Effect, Layer, Redacted, Schema } from "effect"
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
 import { header, readBounded } from "./internal/Http.ts"
 import * as StdError from "./StdError.ts"
 import * as WebSearch from "./WebSearch.ts"

package/src/Fetch.ts

@@ -5,8 +5,8 @@
  */
 
 import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
 import * as Schema from "effect/Schema"
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
 import { capability, envelope } from "./internal/Declaration.ts"
 import { execute, Response, Timeout } from "./internal/Http.ts"
 

package/src/HttpPost.ts

@@ -5,8 +5,8 @@
  */
 
 import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
 import * as Schema from "effect/Schema"
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
 import { capability, envelope } from "./internal/Declaration.ts"
 import { execute, Response, Timeout } from "./internal/Http.ts"
 

package/src/NodeLanguageServer.ts

@@ -12,7 +12,7 @@
 import * as ChildProcessEnvironment from "@smthrs/kernel/ChildProcessEnvironment"
 import * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner"
 import { Clock, Deferred, Effect, Fiber, Layer, Option, Queue, type Scope, Semaphore, Stream } from "effect"
-import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import * as ChildProcess from "effect/process/ChildProcess"
 import { createHash } from "node:crypto"
 import * as NodeFs from "node:fs"
 import * as NodePath from "node:path"

package/src/WebFetch.ts

@@ -12,8 +12,8 @@
 import type { GrantStore } from "@smthrs/kernel/GrantStore"
 import * as HttpClient from "@smthrs/kernel/HttpClient"
 import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
 import * as Schema from "effect/Schema"
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
 import { capability, envelope } from "./internal/Declaration.ts"
 import { toMarkdown, toText } from "./internal/Html.ts"
 import { capOutput, header, MAX_RESPONSE_BYTES, readBounded, Timeout, withDeadline } from "./internal/Http.ts"

package/src/internal/Exec.ts

@@ -17,10 +17,11 @@
 import * as ChildProcessEnvironment from "@smthrs/kernel/ChildProcessEnvironment"
 import * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner"
 import * as Effect from "effect/Effect"
+import * as ChildProcess from "effect/process/ChildProcess"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
-import * as ChildProcess from "effect/unstable/process/ChildProcess"
 import * as StdError from "../StdError.ts"
+import { elideMiddle } from "./Text.ts"
 
 /**
  * Failure codes a buffered execution can report, matching the codes the
@@ -66,9 +67,9 @@ export interface ExecResult {
   readonly stdout: string
   readonly stderr: string
   readonly exitCode: number
-  /** UTF-8 bytes dropped from the head of stdout to stay inside the capture bound. */
+  /** UTF-8 bytes of stdout dropped to stay inside the capture bound; see `overflow`. */
   readonly stdoutDroppedBytes: number
-  /** UTF-8 bytes dropped from the head of stderr to stay inside the capture bound. */
+  /** UTF-8 bytes of stderr dropped to stay inside the capture bound; see `overflow`. */
   readonly stderrDroppedBytes: number
 }
 
@@ -97,18 +98,26 @@ export interface ExecOptions {
    */
   readonly stdin?: string | undefined
   /**
-   * Bytes retained per captured stream. A stream that prints more keeps its
-   * tail and reports what it dropped, so a command printing gigabytes costs a
-   * bounded amount of memory rather than the whole of what it printed.
+   * Bytes retained per captured stream. A stream that prints more keeps what
+   * `overflow` names and reports what it dropped, so a command printing
+   * gigabytes costs a bounded amount of memory rather than the whole of what it
+   * printed.
    *
    * Absent means unbounded, which is what a caller wants when it needs every
    * byte a tool produced (`rg --files`, `git worktree list`).
    */
   readonly maxCaptureBytes?: number | undefined
-  /** Defaults to `tail`; `refuse` fails if either stream exceeds the bound. */
-  readonly overflow?: "tail" | "refuse" | undefined
+  /**
+   * What a stream past the bound keeps. `tail`, the default, keeps its last
+   * bytes. `ends` keeps its first and last halves and puts one line naming the
+   * dropped bytes where the middle was. `refuse` fails if either stream exceeds
+   * the bound.
+   */
+  readonly overflow?: Overflow | undefined
 }
 
+type Overflow = "tail" | "ends" | "refuse"
+
 /** One captured stream: the text kept, and the bytes dropped to keep it bounded. */
 interface Capture {
   readonly text: string
@@ -121,70 +130,143 @@ interface Tail {
   dropped: number
 }
 
+/** A stream's first bytes and its last ones: what `overflow: "ends"` keeps. */
+interface Ends {
+  readonly head: Array<Uint8Array>
+  headBytes: number
+  readonly tail: Tail
+}
+
 const decoder = new TextDecoder("utf-8")
 
+const emptyTail = (): Tail => ({ chunks: [], bytes: 0, dropped: 0 })
+
+/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */
+const isContinuation = (byte: number): boolean => (byte & 0b1100_0000) === 0b1000_0000
+
+const join = (chunks: ReadonlyArray<Uint8Array>, size: number): Uint8Array => {
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+/** Appends one chunk and drops from the front whatever no longer fits. */
+const keepTail = (state: Tail, chunk: Uint8Array, maxBytes: number): void => {
+  if (chunk.byteLength === 0) return
+  state.chunks.push(chunk)
+  state.bytes += chunk.byteLength
+  while (state.bytes > maxBytes && state.chunks.length > 0) {
+    const excess = state.bytes - maxBytes
+    const first = state.chunks[0]!
+    if (first.byteLength <= excess) {
+      state.chunks.shift()
+      state.bytes -= first.byteLength
+      state.dropped += first.byteLength
+    } else {
+      state.chunks[0] = first.subarray(excess)
+      state.bytes -= excess
+      state.dropped += excess
+    }
+  }
+}
+
 /**
  * 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.
+ * 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: Tail): Capture => {
-  const bytes = new Uint8Array(state.bytes)
-  let offset = 0
-  for (const chunk of state.chunks) {
-    bytes.set(chunk, offset)
-    offset += chunk.byteLength
-  }
+  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 && (bytes[start]! & 0b1100_0000) === 0b1000_0000) start++
+  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: Uint8Array): number => {
+  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: Ends): Capture => {
+  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 = <E>(
   stream: Stream.Stream<Uint8Array, E>,
   maxBytes: number,
-  overflow: "tail" | "refuse" | undefined
+  overflow: Overflow | undefined
 ): Effect.Effect<Capture, E> =>
-  Stream.runFold(
-    stream,
-    (): Tail => ({ chunks: [], bytes: 0, dropped: 0 }),
-    (state, chunk) => {
-      if (chunk.byteLength === 0) return state
-      state.chunks.push(chunk)
-      state.bytes += chunk.byteLength
-      while (state.bytes > maxBytes && state.chunks.length > 0) {
-        const excess = state.bytes - maxBytes
-        const first = state.chunks[0]!
-        if (first.byteLength <= excess) {
-          state.chunks.shift()
-          state.bytes -= first.byteLength
-          state.dropped += first.byteLength
-        } else {
-          state.chunks[0] = first.subarray(excess)
-          state.bytes -= excess
-          state.dropped += excess
-        }
-      }
-      return state
-    }
-  ).pipe(Effect.map((state) =>
+  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 = <E>(stream: Stream.Stream<Uint8Array, E>, maxBytes: number): Effect.Effect<Capture, E> => {
+  const headBytes = Math.floor(maxBytes / 2)
+  return Stream.runFold(stream, (): Ends => ({ 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 = <E>(
   stream: Stream.Stream<Uint8Array, E>,
   maxBytes: number | undefined,
-  overflow: "tail" | "refuse" | undefined
+  overflow: Overflow | undefined
 ): Effect.Effect<Capture, E> =>
   maxBytes === undefined
     ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))
+    : overflow === "ends"
+    ? boundedEnds(stream, maxBytes)
     : boundedTail(stream, maxBytes, overflow)
 
 const unbounded = (

package/src/internal/Http.ts

@@ -7,9 +7,9 @@
 import type { GrantStore } from "@smthrs/kernel/GrantStore"
 import * as HttpClient from "@smthrs/kernel/HttpClient"
 import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
 import * as StdError from "../StdError.ts"
 import { guarded, refusal } from "./HttpNetwork.ts"
 import { MAX_OUTPUT_BYTES, notice, truncateBytes } from "./Text.ts"

package/src/internal/HttpNetwork.ts

@@ -13,9 +13,9 @@ import {
   supportsDestinationPinning
 } from "@smthrs/kernel/HttpClient"
 import { Context, Effect, Option } from "effect"
-import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient"
-import * as HttpClient from "effect/unstable/http/HttpClient"
-import * as HttpClientError from "effect/unstable/http/HttpClientError"
+import * as FetchHttpClient from "effect/http/FetchHttpClient"
+import * as HttpClient from "effect/http/HttpClient"
+import * as HttpClientError from "effect/http/HttpClientError"
 import { lookup } from "node:dns/promises"
 import { BlockList, isIP } from "node:net"
 import * as StdError from "../StdError.ts"

package/src/internal/Text.ts

@@ -124,6 +124,21 @@ export const truncateBytes = (
   }
 }
 
+/**
+ * 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: string, droppedBytes: number, end: string): string =>
+  `${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