@smthrs/std 0.0.0-stage → 1.0.0-rc.3

package/src/TreeFingerprint.ts

@@ -0,0 +1,200 @@
+/**
+ * The identity of one directory tree, measured where the tree is.
+ *
+ * `@smthrs/agent/WorkspaceObservation` measures the host workspace around
+ * every frame so the loop's mutation accounting is a fact rather than a
+ * claim. A command routed into a container writes to a filesystem that walk
+ * never sees: the SWE-bench rig bind-mounts the checkout into its container,
+ * so a container edit lands on the host too, but a container Harbor or Pier
+ * starts has no such mount, and every edit an agent made there read as an
+ * idle frame. Measured 2026-09-22 on Terminal-Bench 4.0: `read_only_cap`
+ * ended one run after twenty-four frames of container writes, and the claim
+ * judge refused another's completion as "work this run never recorded".
+ *
+ * This module is the same measurement taken inside the container: one POSIX
+ * shell script that lists every kept file under a directory with its size and
+ * modification time, in sorted order, and prints one checksum of the listing.
+ * `bash` runs it through the container transport before and after a
+ * containerised command and reports whether the two answers differ under the
+ * reserved {@link key}. The harness reads that key as a measured write, the
+ * way it reads `invalidProbe` as a measured refusal.
+ *
+ * The same properties as the host walk, and the same stated limits:
+ *
+ * - **Identity, not content.** Size and mtime per file; a rewrite that
+ *   restores both is invisible.
+ * - **Pruning is the signal.** {@link defaultPrune} and
+ *   {@link defaultIgnoreSuffixes} are the one list both measurements use, so
+ *   a derived artifact the host walk skips is skipped here too.
+ * - **A partial listing says so.** The listing stops at {@link maxPaths}, and
+ *   a measurement that stopped there reports `complete: false`; `bash` then
+ *   reports nothing rather than a guess.
+ * - **Every tool it needs is POSIX or busybox.** `find -prune`, `stat -c`,
+ *   `sort`, `head`, `cksum` and `grep -c` are in every Linux base image this
+ *   has been run against, GNU and busybox alike. A container that lacks one
+ *   answers with a non-zero exit, which is read as "unmeasured".
+ *
+ * @since 1.0.0
+ */
+
+import * as Prune from "./internal/Prune.ts"
+
+/**
+ * The reserved output key a flow reports a measured write under.
+ *
+ * A wire contract with the harness rather than a shared type, exactly as
+ * `Probe.key` is: `@smthrs/harness` reads this key off a `Schema.Json` result
+ * and must not depend on the tool library to do it. `true` means the tree the
+ * call targeted differed after the call from before it; `false` means it was
+ * measured and held still; absent means it was not measured.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const key = "mutated"
+
+/**
+ * Directory names never descended into.
+ *
+ * Every entry is a place a tool writes derived state while the run is working:
+ * version-control internals, dependency trees, and the caches Python, Node,
+ * Rust and their test runners keep beside the sources. A run that changes only
+ * these has changed nothing it will be judged on.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const defaultPrune: ReadonlyArray<string> = [
+  ...Prune.repositoryDirectories,
+  // Build and environment directories a search still reads, since a project
+  // may keep sources under these names, but a measurement leaves out.
+  "venv",
+  "target"
+]
+
+/**
+ * File and directory name suffixes left out of a measurement.
+ *
+ * Compiled output is the case that matters: several SWE-bench projects build
+ * extensions in place, which drops `.so` files next to the `.py` files they
+ * came from. Those move whenever the run executes its test suite, and
+ * counting them would report every probe as an edit.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const defaultIgnoreSuffixes: ReadonlyArray<string> = [
+  ".pyc",
+  ".pyo",
+  ".pyd",
+  ".so",
+  ".o",
+  ".a",
+  ".dylib",
+  ".class",
+  ".egg-info"
+]
+
+/**
+ * The largest number of files one measurement covers.
+ *
+ * The same bound the host walk uses, for the same reason: a listing that
+ * stopped here covers a prefix chosen by sort order, and a prefix holding
+ * still says nothing about the files being edited outside it.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const maxPaths = 50_000
+
+/**
+ * One measurement, as {@link parse} reads it off the script's output.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Measurement {
+  /** The checksum of the whole listing; equal for two measurements of an unchanged tree. */
+  readonly digest: string
+  /** How many files the listing covered. */
+  readonly paths: number
+  /** Whether the listing covered the whole tree rather than a bounded prefix. */
+  readonly complete: boolean
+}
+
+/** One name, single-quoted for a POSIX shell. Every name here is a constant without quotes in it. */
+const quoted = (name: string): string => `'${name.replaceAll("'", `'\\''`)}'`
+
+/**
+ * The POSIX shell script that measures the current directory.
+ *
+ * Prints two lines: `cksum`'s `<crc> <bytes>` over the sorted listing, then
+ * the number of listing lines. The listing is capped one past
+ * {@link maxPaths} so the count alone says whether the bound was reached.
+ * Errors from `find` and `stat` are discarded: a path that vanished mid-walk
+ * is movement the next measurement reports, and a file the shell may not
+ * stat is one it could not have measured either way.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const script = (options: {
+  readonly prune?: ReadonlyArray<string> | undefined
+  readonly ignoreSuffixes?: ReadonlyArray<string> | undefined
+} = {}): string => {
+  const prune = (options.prune ?? defaultPrune).map((name) => `-name ${quoted(name)}`).join(" -o ")
+  const skipped = (options.ignoreSuffixes ?? defaultIgnoreSuffixes)
+    .map((suffix) => `! -name ${quoted(`*${suffix}`)}`)
+    .join(" ")
+  return [
+    "set -f",
+    `L=$(find . -xdev \\( ${prune} \\) -prune -o -type f ${skipped} -exec stat -c '%s %Y %n' {} + 2>/dev/null | LC_ALL=C sort | head -n ${
+      maxPaths + 1
+    })`,
+    `printf '%s' "$L" | cksum`,
+    `printf '%s' "$L" | grep -c ''`
+  ].join("\n")
+}
+
+/**
+ * Reads one measurement off the script's standard output.
+ *
+ * `undefined` for anything that is not two well-formed lines: the script did
+ * not run, a tool it needs is missing, or the output was cut. An unmeasured
+ * tree is reported as unmeasured, never as unchanged.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export const parse = (stdout: string): Measurement | undefined => {
+  const lines = stdout.trim().split("\n").map((line) => line.trim())
+  if (lines.length !== 2) return undefined
+  const checksum = /^(\d+) (\d+)$/.exec(lines[0]!)
+  const count = /^(\d+)$/.exec(lines[1]!)
+  if (checksum === null || count === null) return undefined
+  const paths = Number(count[1])
+  const bounded = paths > maxPaths
+  return {
+    digest: `${checksum[1]}:${checksum[2]}`,
+    paths: bounded ? maxPaths : paths,
+    complete: !bounded
+  }
+}
+
+/**
+ * Whether two measurements say the tree moved, or nothing at all.
+ *
+ * `true` and `false` are answers; `undefined` is the honest reading whenever
+ * either measurement is absent or bounded, because a prefix that held still
+ * is not a tree that held still.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export const moved = (
+  before: Measurement | undefined,
+  after: Measurement | undefined
+): boolean | undefined =>
+  before === undefined || after === undefined || !before.complete || !after.complete
+    ? undefined
+    : before.digest !== after.digest

package/src/UpdatePlan.ts

@@ -0,0 +1,171 @@
+/**
+ * update_plan flow declaration and portable handler.
+ *
+ * A Codex CLI clone of the `update_plan` tool: an optional explanation and a
+ * list of plan items, acknowledged with "Plan updated". Pure — no host
+ * access; the harness observes plan updates through the journal.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { envelope } from "./internal/Declaration.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * Registry name for the update_plan flow. Matches the Codex CLI tool name.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "update_plan"
+
+/**
+ * Model-facing description of the update_plan flow. Matches the Codex CLI
+ * description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description = "Updates the task plan.\n" +
+  "Provide an optional explanation and a list of plan items, each with a step and status.\n" +
+  "At most one step can be in_progress at a time.\n"
+
+/**
+ * Status of one plan step, matching Codex.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const StepStatus = Schema.Literals(["pending", "in_progress", "completed"])
+
+const Step = Schema.Struct({
+  step: Schema.String.annotate({ description: "Task step text." }),
+  status: StepStatus.annotate({ description: "Step status." })
+})
+
+/** How many steps of a plan claim to be running right now. */
+const inProgressCount = (plan: ReadonlyArray<typeof Step.Type>): number =>
+  plan.reduce((total, item) => item.status === "in_progress" ? total + 1 : total, 0)
+
+/**
+ * The plan itself: steps, at most one of them `in_progress`.
+ *
+ * The single-in-progress rule is the last line of the Codex description a
+ * model reads every frame, so it is enforced here rather than left as prose a
+ * decode ignores. A plan naming two running steps is a decode failure at the
+ * `plan` path, not a silent acknowledgement.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Plan = Schema.Array(Step).pipe(
+  Schema.check(
+    Schema.makeFilter(
+      (plan) =>
+        inProgressCount(plan) <= 1
+          ? undefined
+          : "invalid_input: at most one plan step can be in_progress at a time",
+      { identifier: "invalid_input" }
+    )
+  )
+).annotate({ description: "The list of steps" })
+
+/**
+ * Input schema for the update_plan flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  explanation: Schema.optional(Schema.String.annotate({ description: "Optional explanation for this plan update." })),
+  plan: Plan
+})
+
+/**
+ * Decoded input accepted by the `update_plan` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+
+/**
+ * Output schema for the update_plan flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({
+  output: Schema.String.annotate({ description: "Acknowledgement text, always 'Plan updated'" })
+})
+
+/**
+ * Decoded output returned by the `update_plan` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+
+/**
+ * Static effect envelope for the update_plan flow: no reads, no writes.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "hermetic", reads: [], writes: [] })
+
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * The flow touches nothing, so every invocation declares what the static
+ * envelope declares.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+
+/**
+ * Capabilities required by the update_plan flow: none.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities: ReadonlyArray<string> = []
+
+/**
+ * Declaration-only update_plan flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * Acknowledges a plan update with Codex's exact response text.
+ *
+ * The single-in-progress rule is checked again here. `Plan` refuses it at
+ * decode time, but a host that calls this handler directly never decodes, and
+ * an invariant enforced in only one of the two entrances is enforced in
+ * neither.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("UpdatePlan.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError> {
+  const running = inProgressCount(input.plan)
+  if (running > 1) {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "invalid_input",
+        message: `At most one step can be in_progress at a time; the plan named ${running}`
+      })
+    )
+  }
+  return { output: "Plan updated" }
+})

package/src/WebFetch.ts

@@ -0,0 +1,194 @@
+/**
+ * The `webfetch` flow: an HTTP GET rendered as text, Markdown, or HTML.
+ *
+ * The handler fetches through the permission-checked `HttpClient`, follows at
+ * most ten redirects, refuses a body over 5 MiB, and returns the final URL,
+ * status, and content type beside the rendered body. The rendered body keeps
+ * its first 60,000 bytes and reports any cut with `truncated` and `notice`.
+ *
+ * @since 1.0.0
+ */
+
+import type { GrantStore } from "@smthrs/kernel/GrantStore"
+import * as HttpClient from "@smthrs/kernel/HttpClient"
+import * as Effect from "effect/Effect"
+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"
+import { guarded, refusal } from "./internal/HttpNetwork.ts"
+import { parseHttpUrl } from "./internal/Url.ts"
+import * as StdError from "./StdError.ts"
+
+const maxRedirects = 10
+/**
+ * The registry name of the `webfetch` flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "webfetch"
+/**
+ * The one-line description the model sees for the `webfetch` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description = "Fetch an HTTP URL and render its content as text, Markdown, or HTML."
+/**
+ * What the `webfetch` flow accepts.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  url: Schema.String.annotate({ description: "Absolute http or https URL to retrieve without user information" }),
+  format: Schema.optional(Schema.Literals(["text", "markdown", "html"])).annotate({
+    description: "Response rendering format; defaults to markdown"
+  }),
+  timeout: Schema.optional(Timeout).annotate({
+    description: "Total timeout across requests, redirects, and response body in seconds, capped at 120"
+  })
+})
+/**
+ * Decoded input accepted by the `webfetch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+/**
+ * What the `webfetch` flow returns.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({
+  url: Schema.String.annotate({ description: "Final URL after redirects" }),
+  status: Schema.Int.annotate({ description: "HTTP status code, including error statuses" }),
+  contentType: Schema.String.annotate({ description: "Response Content-Type header, or an empty string when absent" }),
+  content: Schema.String.annotate({ description: "Response body rendered in the requested format" }),
+  truncated: Schema.Boolean.annotate({ description: "Whether the rendered body exceeded the display budget" }),
+  notice: Schema.optional(Schema.String.annotate({ description: "Truncation disclosure" }))
+})
+/**
+ * Decoded output returned by the `webfetch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+/**
+ * The declared effect envelope of the `webfetch` flow, before any input is known.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "expected", reads: [], writes: [] })
+/**
+ * Narrows {@link effects} to what this particular input actually touches.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+/**
+ * The authority the `webfetch` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("net:get", "*")]
+/**
+ * The `webfetch` flow declaration: schemas, capabilities, and effects, with the
+ * implementation attached separately.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+const error = (code: StdError.Code, message: string, path?: string): StdError.StdError =>
+  new StdError.StdError({ code, message, ...(path === undefined ? {} : { path }) })
+/**
+ * Runs the `webfetch` flow: fetches one HTTP URL and renders it as text.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("WebFetch.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, HttpClient.HttpClient | GrantStore> {
+  let url = parseHttpUrl(input.url)
+  if (url === undefined) {
+    return yield* Effect.fail(
+      error("invalid_input", "URL must use http or https without user information", input.url)
+    )
+  }
+  const client = guarded(yield* HttpClient.HttpClient, false)
+  let headers: Readonly<Record<string, string>> = {
+    accept: input.format === "html" ? "text/html, text/plain;q=0.8" : "text/markdown, text/plain, text/html;q=0.8"
+  }
+  for (let redirect = 0; redirect <= maxRedirects; redirect++) {
+    const response = yield* client.execute(
+      HttpClientRequest.setHeaders(HttpClientRequest.get(url.toString()), headers)
+    ).pipe(
+      Effect.mapError((cause) => refusal(cause) ?? error("request_failed", `Web fetch request failed: ${url}`))
+    )
+    const location = header(response.headers, "location")
+    if (response.status >= 300 && response.status < 400 && location !== undefined) {
+      const next = parseHttpUrl(location, url)
+      if (next === undefined) {
+        return yield* Effect.fail(
+          error("invalid_input", "Redirect target must use http or https without user information", location)
+        )
+      }
+      if (next.origin !== url.origin) {
+        headers = Object.fromEntries(
+          Object.entries(headers).filter(([key]) =>
+            key.toLowerCase() !== "authorization" && key.toLowerCase() !== "cookie"
+          )
+        )
+      }
+      url = next
+      continue
+    }
+    const contentType = header(response.headers, "content-type") ?? ""
+    const normalizedContentType = contentType.toLowerCase()
+    if (
+      !normalizedContentType.startsWith("text/")
+      && !normalizedContentType.includes("json")
+      && !normalizedContentType.includes("xml")
+    ) {
+      return yield* Effect.fail(
+        error("unsupported_content_type", `Unsupported content type: ${contentType || "unknown"}`)
+      )
+    }
+    const length = Number(header(response.headers, "content-length"))
+    if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
+      return yield* Effect.fail(error("response_too_large", "Response exceeds the 5 MiB limit"))
+    }
+    const body = yield* readBounded(response.stream, url.toString()).pipe(
+      Effect.mapError((cause) =>
+        cause instanceof StdError.StdError
+          ? cause
+          : error("request_failed", "Web fetch response could not be read")
+      )
+    )
+    const raw = new TextDecoder().decode(body)
+    const format = input.format ?? "markdown"
+    const { text: content, ...disclosure } = capOutput(
+      format === "html" || !normalizedContentType.includes("html")
+        ? raw
+        : format === "text"
+        ? toText(raw)
+        : toMarkdown(raw)
+    )
+    return { url: url.toString(), status: response.status, contentType, content, ...disclosure }
+  }
+  return yield* Effect.fail(error("request_failed", "Web fetch exceeded the redirect limit"))
+}, (effect, input) =>
+  // Keep the shared deadline outside the redirect loop and error mapping.
+  withDeadline(effect, input.url, input.timeout, (seconds) =>
+    error("timeout", `Web fetch timed out after ${seconds} seconds`)))