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

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

@@ -160,6 +160,18 @@ The same rule refuses a hermetic `script` whose `interpreter` is not a shell:
 the pre-check reads shell text, and Python is not shell text. Run it
 unhermetically, or express it as shell.
 
+## invalid_input: Command not started: its arguments exceed the operating system's size limit (E2BIG)
+
+**What happened.** The operating system refused to start the command because
+its arguments are too large: one argument over 128 KiB on Linux, or all of them
+over 1 MiB on macOS. A long heredoc in `command`, or a file's text passed in
+`args`, is one such argument. For a `container` call the host's `docker exec`
+carries the same arguments, so the same limit applies.
+
+**What to change.** Send the text on standard input, which has no size limit.
+Put a program and its data in `script`, or keep `command` short and pass the
+data in `stdin`. Never put long text in `command` or `args`.
+
 ## provider_unavailable: this host has no container transport
 
 **What happened.** A call named a `container` and no `Container` service was
@@ -260,11 +272,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.6",
+  "version": "1.0.0-rc.8",
   "license": "MIT",
   "smthrs": {
     "group": "agent"
@@ -401,11 +401,11 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/capability": "1.0.0-rc.6",
-    "@smthrs/control": "1.0.0-rc.6",
-    "@smthrs/core": "1.0.0-rc.6",
-    "@smthrs/kernel": "1.0.0-rc.6",
-    "@smthrs/model": "1.0.0-rc.6"
+    "@smthrs/capability": "1.0.0-rc.8",
+    "@smthrs/control": "1.0.0-rc.8",
+    "@smthrs/core": "1.0.0-rc.8",
+    "@smthrs/kernel": "1.0.0-rc.8",
+    "@smthrs/model": "1.0.0-rc.8"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",

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/Checkpoints.ts

@@ -72,6 +72,8 @@
 
 import { ChildProcessSpawner } from "@smthrs/kernel/ChildProcessSpawner"
 import { Context, Effect, Layer, Schema } from "effect"
+import * as Container from "./Container.ts"
+import * as Exec from "./internal/Exec.ts"
 import { GitWorktree } from "./internal/GitWorktree.ts"
 import { withoutTrailingSlash } from "./internal/Paths.ts"
 import * as Prune from "./internal/Prune.ts"
@@ -409,6 +411,141 @@ const gitStore = (options: GitOptions, spawner: ChildProcessSpawner["Service"]):
  */
 export const layerGit = (options: GitOptions): Layer.Layer<Checkpoints, never, ChildProcessSpawner> =>
   Layer.effect(Checkpoints)(makeGit(options))
+
+/**
+ * What {@link makeContainer} needs to know about the container it pins in.
+ *
+ * @category models
+ * @since 1.0.0-rc.8
+ */
+export interface ContainerOptions {
+  /** The container `bash` runs in. */
+  readonly container: string
+  /** A directory of the repository inside it; absent is the container's own working directory. */
+  readonly cwd?: string | undefined
+}
+
+/**
+ * `$1` is the id. Records the working tree with `stash create` over a copy of
+ * the index, names the commit in config as {@link makeGit} does, and prints it.
+ */
+const pinScript = [
+  "set -e",
+  "cd \"$(git rev-parse --show-toplevel)\"",
+  "copy=$(mktemp -d)",
+  "trap 'rm -rf -- \"$copy\"' EXIT",
+  "index=$(git rev-parse --git-path index)",
+  "if [ -e \"$index\" ]; then cp -p -- \"$index\" \"$copy/index\"; fi",
+  "commit=$(GIT_INDEX_FILE=\"$copy/index\" git -c user.name=flows -c user.email=flows@localhost stash create \"flows checkpoint $1\")",
+  "[ -n \"$commit\" ] || commit=$(git rev-parse --verify 'HEAD^{commit}')",
+  `git config "${configSection}.$1" "$commit"`,
+  "printf '%s\\n' \"$commit\""
+].join("\n")
+
+/**
+ * `$1` is the id, `$2` the lease. Checks the tree out at
+ * `<top>/.flows-checkpoints/<id>-<lease>` in a repository of its own whose
+ * objects are the workspace's, and prints the top and the checkout.
+ */
+const checkoutScript = [
+  "set -e",
+  "top=$(git rev-parse --show-toplevel)",
+  "cd \"$top\"",
+  "common=$(cd \"$(git rev-parse --git-common-dir)\" && pwd -P)",
+  `if [ "$1" = ${baseId} ]; then`,
+  `  commit=$(git rev-parse --verify --quiet '${TestRunner.captureBase}^{commit}' || git rev-parse --verify --quiet 'HEAD^{commit}') || { echo "No commit resolves from ${TestRunner.captureBase} or HEAD in $top." >&2; exit 1; }`,
+  "else",
+  `  commit=$(git config --get "${configSection}.$1") || { echo "No checkpoint is stored under $1 in $top. Take the reading on the live tree instead." >&2; exit 1; }`,
+  "fi",
+  `dir="$top/${scratchDirectory}/$1-$2"`,
+  "trap 'rm -rf -- \"$dir\"' EXIT",
+  `mkdir -p -- "$top/${scratchDirectory}"`,
+  "git init --quiet \"$dir\"",
+  "printf '%s/objects\\n' \"$common\" > \"$dir/.git/objects/info/alternates\"",
+  "git -C \"$dir\" checkout --quiet --detach \"$commit\"",
+  "trap - EXIT",
+  "printf '%s\\n%s\\n' \"$top\" \"$dir\""
+].join("\n")
+
+/**
+ * Builds the store for a host whose `bash` runs in one container.
+ *
+ * The repository is the container's, so every git command runs there, through
+ * the same {@link Container.Container} transport `bash` takes. The host store
+ * looked in the CLI's own directory instead and refused every `at` in 112 of
+ * 123 trials of the 2026-10-14 SWE-bench Pro run. This keeps that store's
+ * shape: a checkpoint is a `stash create` commit named in config, and a tree
+ * is checked out under the repository for one call, so a relocated `bash`
+ * call keeps its subdirectory and still finds what the workspace installs
+ * beside it. That git may run what the repository configures, but only inside
+ * the container the agent already commands.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.8
+ */
+export const makeContainer = (
+  options: ContainerOptions
+): Effect.Effect<Checkpoints, never, ChildProcessSpawner | Container.Container> =>
+  Effect.gen(function*() {
+    const spawner = yield* ChildProcessSpawner
+    const transport = yield* Container.Container
+    const sh = (script: string, args: ReadonlyArray<string>) =>
+      transport.exec({
+        container: options.container,
+        file: "sh",
+        args: ["-c", script, "sh", ...args],
+        cwd: options.cwd,
+        stdin: false
+      }).pipe(
+        Effect.flatMap((plan) =>
+          Exec.exec(plan.file, { args: plan.args, env: plan.env }).pipe(
+            Effect.mapError((error) => Exec.toStdError(plan.file, error))
+          )
+        ),
+        Effect.flatMap((result) =>
+          result.exitCode === 0
+            ? Effect.succeed(result.stdout.trim().split("\n"))
+            : Effect.fail(failed(`git in container ${options.container} failed: ${result.stderr.trim()}`))
+        ),
+        Effect.provideService(ChildProcessSpawner, spawner)
+      )
+    const named = (id: string) =>
+      namable.test(id)
+        ? Effect.void
+        : Effect.fail(failed(`A checkpoint id must match ${namable.source}; ${id} does not.`, "invalid_input"))
+    return make({
+      capture: (id) =>
+        named(id).pipe(
+          Effect.andThen(sh(pinScript, [id])),
+          Effect.map(([commit]) => new Snapshot({ id, ref: commit! }))
+        ),
+      materialize: (id, use) =>
+        named(id).pipe(Effect.andThen(Effect.acquireUseRelease(
+          sh(checkoutScript, [id, globalThis.crypto.randomUUID()]),
+          ([root, checkout]) => use({ id, host: checkout!, guest: checkout!, root: root!, guestRoot: root! }),
+          ([, checkout]) =>
+            sh("rm -rf -- \"$1\"", [checkout!]).pipe(
+              Effect.catch((error) =>
+                Effect.logWarning("could not remove a scratch checkout").pipe(
+                  Effect.annotateLogs({ path: checkout, reason: error.message })
+                )
+              )
+            )
+        )))
+    })
+  })
+
+/**
+ * Provides {@link makeContainer}.
+ *
+ * @category layers
+ * @since 1.0.0-rc.8
+ */
+export const layerContainer = (
+  options: ContainerOptions
+): Layer.Layer<Checkpoints, never, ChildProcessSpawner | Container.Container> =>
+  Layer.effect(Checkpoints)(makeContainer(options))
+
 /**
  * Rewrites one call's input so the call runs against a materialized checkpoint.
  *