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

package/dist/cjs/TreeFingerprint.js

@@ -0,0 +1,87 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key2 of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key2) && key2 !== except)
+        __defProp(to, key2, { get: () => from[key2], enumerable: !(desc = __getOwnPropDesc(from, key2)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TreeFingerprint_exports = {};
+__export(TreeFingerprint_exports, {
+  defaultIgnoreSuffixes: () => defaultIgnoreSuffixes,
+  defaultPrune: () => defaultPrune,
+  key: () => key,
+  maxPaths: () => maxPaths,
+  moved: () => moved,
+  parse: () => parse,
+  script: () => script
+});
+module.exports = __toCommonJS(TreeFingerprint_exports);
+var Prune = __toESM(require("./internal/Prune.js"), 1);
+const key = "mutated";
+const defaultPrune = [
+  ...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"
+];
+const defaultIgnoreSuffixes = [
+  ".pyc",
+  ".pyo",
+  ".pyd",
+  ".so",
+  ".o",
+  ".a",
+  ".dylib",
+  ".class",
+  ".egg-info"
+];
+const maxPaths = 5e4;
+const quoted = (name) => `'${name.replaceAll("'", `'\\''`)}'`;
+const script = (options = {}) => {
+  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");
+};
+const parse = (stdout) => {
+  const lines = stdout.trim().split("\n").map((line) => line.trim());
+  if (lines.length !== 2) return void 0;
+  const checksum = /^(\d+) (\d+)$/.exec(lines[0]);
+  const count = /^(\d+)$/.exec(lines[1]);
+  if (checksum === null || count === null) return void 0;
+  const paths = Number(count[1]);
+  const bounded = paths > maxPaths;
+  return {
+    digest: `${checksum[1]}:${checksum[2]}`,
+    paths: bounded ? maxPaths : paths,
+    complete: !bounded
+  };
+};
+const moved = (before, after) => before === void 0 || after === void 0 || !before.complete || !after.complete ? void 0 : before.digest !== after.digest;
+//# sourceMappingURL=TreeFingerprint.js.map

package/dist/cjs/TreeFingerprint.js.map

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

package/dist/cjs/UpdatePlan.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 * 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 declare const name = "update_plan";
+/**
+ * Model-facing description of the update_plan flow. Matches the Codex CLI
+ * description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description: string;
+/**
+ * Status of one plan step, matching Codex.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const StepStatus: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+/**
+ * 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 declare const Plan: Schema.$Array<Schema.Struct<{
+    readonly step: Schema.String;
+    readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+}>>;
+/**
+ * Input schema for the update_plan flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly explanation: Schema.optional<Schema.String>;
+    readonly plan: Schema.$Array<Schema.Struct<{
+        readonly step: Schema.String;
+        readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+    }>>;
+}>;
+/**
+ * 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 declare const Output: Schema.Struct<{
+    readonly output: Schema.String;
+}>;
+/**
+ * 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 declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * 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 declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the update_plan flow: none.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: ReadonlyArray<string>;
+/**
+ * Declaration-only update_plan flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "update_plan";
+    readonly description: string;
+    readonly input: Schema.Struct<{
+        readonly explanation: Schema.optional<Schema.String>;
+        readonly plan: Schema.$Array<Schema.Struct<{
+            readonly step: Schema.String;
+            readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+        }>>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly output: Schema.String;
+    }>;
+    readonly capabilities: readonly string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * 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 declare const run: (input: {
+    readonly plan: readonly {
+        readonly step: string;
+        readonly status: "pending" | "completed" | "in_progress";
+    }[];
+    readonly explanation?: string | undefined;
+}) => Effect.Effect<{
+    readonly output: string;
+}, StdError.StdError, never>;
+//# sourceMappingURL=UpdatePlan.d.ts.map

package/dist/cjs/UpdatePlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UpdatePlan.d.ts","sourceRoot":"","sources":["../../src/UpdatePlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,gBAAgB,CAAA;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,QAE4B,CAAA;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,mEAA2D,CAAA;AAWlF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI;;;GAU+B,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;EAGhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;EAEjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAwE,CAAA;AAE5F;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAAM,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG;;;;;;;;4BAad,CAAA"}

package/dist/cjs/UpdatePlan.js

@@ -0,0 +1,87 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var UpdatePlan_exports = {};
+__export(UpdatePlan_exports, {
+  Input: () => Input,
+  Output: () => Output,
+  Plan: () => Plan,
+  StepStatus: () => StepStatus,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  run: () => run
+});
+module.exports = __toCommonJS(UpdatePlan_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_Declaration = require("./internal/Declaration.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+const name = "update_plan";
+const description = "Updates the task plan.\nProvide an optional explanation and a list of plan items, each with a step and status.\nAt most one step can be in_progress at a time.\n";
+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." })
+});
+const inProgressCount = (plan) => plan.reduce((total, item) => item.status === "in_progress" ? total + 1 : total, 0);
+const Plan = Schema.Array(Step).pipe(
+  Schema.check(
+    Schema.makeFilter(
+      (plan) => inProgressCount(plan) <= 1 ? void 0 : "invalid_input: at most one plan step can be in_progress at a time",
+      { identifier: "invalid_input" }
+    )
+  )
+).annotate({ description: "The list of steps" });
+const Input = Schema.Struct({
+  explanation: Schema.optional(Schema.String.annotate({ description: "Optional explanation for this plan update." })),
+  plan: Plan
+});
+const Output = Schema.Struct({
+  output: Schema.String.annotate({ description: "Acknowledgement text, always 'Plan updated'" })
+});
+const effects = (0, import_Declaration.envelope)({ tier: "sealed", mode: "hermetic", reads: [], writes: [] });
+const effectsFor = (_input) => effects;
+const capabilities = [];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const run = Effect.fn("UpdatePlan.run")(function* (input) {
+  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" };
+});
+//# sourceMappingURL=UpdatePlan.js.map

package/dist/cjs/UpdatePlan.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/UpdatePlan.ts"],
+  "sourcesContent": ["/**\n * update_plan flow declaration and portable handler.\n *\n * A Codex CLI clone of the `update_plan` tool: an optional explanation and a\n * list of plan items, acknowledged with \"Plan updated\". Pure \u2014 no host\n * access; the harness observes plan updates through the journal.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport { envelope } from \"./internal/Declaration.ts\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * Registry name for the update_plan flow. Matches the Codex CLI tool name.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"update_plan\"\n\n/**\n * Model-facing description of the update_plan flow. Matches the Codex CLI\n * description.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description = \"Updates the task plan.\\n\" +\n  \"Provide an optional explanation and a list of plan items, each with a step and status.\\n\" +\n  \"At most one step can be in_progress at a time.\\n\"\n\n/**\n * Status of one plan step, matching Codex.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const StepStatus = Schema.Literals([\"pending\", \"in_progress\", \"completed\"])\n\nconst Step = Schema.Struct({\n  step: Schema.String.annotate({ description: \"Task step text.\" }),\n  status: StepStatus.annotate({ description: \"Step status.\" })\n})\n\n/** How many steps of a plan claim to be running right now. */\nconst inProgressCount = (plan: ReadonlyArray<typeof Step.Type>): number =>\n  plan.reduce((total, item) => item.status === \"in_progress\" ? total + 1 : total, 0)\n\n/**\n * The plan itself: steps, at most one of them `in_progress`.\n *\n * The single-in-progress rule is the last line of the Codex description a\n * model reads every frame, so it is enforced here rather than left as prose a\n * decode ignores. A plan naming two running steps is a decode failure at the\n * `plan` path, not a silent acknowledgement.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Plan = Schema.Array(Step).pipe(\n  Schema.check(\n    Schema.makeFilter(\n      (plan) =>\n        inProgressCount(plan) <= 1\n          ? undefined\n          : \"invalid_input: at most one plan step can be in_progress at a time\",\n      { identifier: \"invalid_input\" }\n    )\n  )\n).annotate({ description: \"The list of steps\" })\n\n/**\n * Input schema for the update_plan flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  explanation: Schema.optional(Schema.String.annotate({ description: \"Optional explanation for this plan update.\" })),\n  plan: Plan\n})\n\n/**\n * Decoded input accepted by the `update_plan` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * Output schema for the update_plan flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  output: Schema.String.annotate({ description: \"Acknowledgement text, always 'Plan updated'\" })\n})\n\n/**\n * Decoded output returned by the `update_plan` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * Static effect envelope for the update_plan flow: no reads, no writes.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"sealed\", mode: \"hermetic\", reads: [], writes: [] })\n\n/**\n * Narrows the effect envelope for a decoded invocation.\n *\n * The flow touches nothing, so every invocation declares what the static\n * envelope declares.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (_input: typeof Input.Type) => effects\n\n/**\n * Capabilities required by the update_plan flow: none.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities: ReadonlyArray<string> = []\n\n/**\n * Declaration-only update_plan flow.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = { name, description, input: Input, output: Output, capabilities, effects } as const\n\n/**\n * Acknowledges a plan update with Codex's exact response text.\n *\n * The single-in-progress rule is checked again here. `Plan` refuses it at\n * decode time, but a host that calls this handler directly never decodes, and\n * an invariant enforced in only one of the two entrances is enforced in\n * neither.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"UpdatePlan.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError> {\n  const running = inProgressCount(input.plan)\n  if (running > 1) {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"invalid_input\",\n        message: `At most one step can be in_progress at a time; the plan named ${running}`\n      })\n    )\n  }\n  return { output: \"Plan updated\" }\n})\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,aAAwB;AACxB,aAAwB;AACxB,yBAAyB;AACzB,eAA0B;AAQnB,MAAM,OAAO;AASb,MAAM,cAAc;AAUpB,MAAM,aAAa,OAAO,SAAS,CAAC,WAAW,eAAe,WAAW,CAAC;AAEjF,MAAM,OAAO,OAAO,OAAO;AAAA,EACzB,MAAM,OAAO,OAAO,SAAS,EAAE,aAAa,kBAAkB,CAAC;AAAA,EAC/D,QAAQ,WAAW,SAAS,EAAE,aAAa,eAAe,CAAC;AAC7D,CAAC;AAGD,MAAM,kBAAkB,CAAC,SACvB,KAAK,OAAO,CAAC,OAAO,SAAS,KAAK,WAAW,gBAAgB,QAAQ,IAAI,OAAO,CAAC;AAa5E,MAAM,OAAO,OAAO,MAAM,IAAI,EAAE;AAAA,EACrC,OAAO;AAAA,IACL,OAAO;AAAA,MACL,CAAC,SACC,gBAAgB,IAAI,KAAK,IACrB,SACA;AAAA,MACN,EAAE,YAAY,gBAAgB;AAAA,IAChC;AAAA,EACF;AACF,EAAE,SAAS,EAAE,aAAa,oBAAoB,CAAC;AAQxC,MAAM,QAAQ,OAAO,OAAO;AAAA,EACjC,aAAa,OAAO,SAAS,OAAO,OAAO,SAAS,EAAE,aAAa,6CAA6C,CAAC,CAAC;AAAA,EAClH,MAAM;AACR,CAAC;AAgBM,MAAM,SAAS,OAAO,OAAO;AAAA,EAClC,QAAQ,OAAO,OAAO,SAAS,EAAE,aAAa,8CAA8C,CAAC;AAC/F,CAAC;AAgBM,MAAM,cAAU,6BAAS,EAAE,MAAM,UAAU,MAAM,YAAY,OAAO,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC;AAWpF,MAAM,aAAa,CAAC,WAA8B;AAQlD,MAAM,eAAsC,CAAC;AAQ7C,MAAM,OAAO,EAAE,MAAM,aAAa,OAAO,OAAO,QAAQ,QAAQ,cAAc,QAAQ;AAatF,MAAM,MAAM,OAAO,GAAG,gBAAgB,EAAE,WAC7C,OACyD;AACzD,QAAM,UAAU,gBAAgB,MAAM,IAAI;AAC1C,MAAI,UAAU,GAAG;AACf,WAAO,OAAO,OAAO;AAAA,MACnB,IAAI,SAAS,SAAS;AAAA,QACpB,MAAM;AAAA,QACN,SAAS,iEAAiE,OAAO;AAAA,MACnF,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO,EAAE,QAAQ,eAAe;AAClC,CAAC;",
+  "names": []
+}

package/dist/cjs/WebFetch.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 StdError from "./StdError.ts";
+/**
+ * The registry name of the `webfetch` flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "webfetch";
+/**
+ * The one-line description the model sees for the `webfetch` flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare 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 declare const Input: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly format: Schema.optional<Schema.Literals<readonly ["text", "markdown", "html"]>>;
+    readonly timeout: Schema.optional<Schema.Number>;
+}>;
+/**
+ * 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 declare const Output: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly status: Schema.Int;
+    readonly contentType: Schema.String;
+    readonly content: Schema.String;
+    readonly truncated: Schema.Boolean;
+    readonly notice: Schema.optional<Schema.String>;
+}>;
+/**
+ * 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 declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows {@link effects} to what this particular input actually touches.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * The authority the `webfetch` flow requires.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * The `webfetch` flow declaration: schemas, capabilities, and effects, with the
+ * implementation attached separately.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "webfetch";
+    readonly description: "Fetch an HTTP URL and render its content as text, Markdown, or HTML.";
+    readonly input: Schema.Struct<{
+        readonly url: Schema.String;
+        readonly format: Schema.optional<Schema.Literals<readonly ["text", "markdown", "html"]>>;
+        readonly timeout: Schema.optional<Schema.Number>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly url: Schema.String;
+        readonly status: Schema.Int;
+        readonly contentType: Schema.String;
+        readonly content: Schema.String;
+        readonly truncated: Schema.Boolean;
+        readonly notice: Schema.optional<Schema.String>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * Runs the `webfetch` flow: fetches one HTTP URL and renders it as text.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly url: string;
+    readonly timeout?: number | undefined;
+    readonly format?: "text" | "markdown" | "html" | undefined;
+}) => Effect.Effect<{
+    readonly status: number;
+    readonly content: string;
+    readonly contentType: string;
+    readonly url: string;
+    readonly truncated: boolean;
+    readonly notice?: string | undefined;
+}, StdError.StdError, GrantStore | HttpClient.HttpClient>;
+//# sourceMappingURL=WebFetch.d.ts.map

package/dist/cjs/WebFetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebFetch.d.ts","sourceRoot":"","sources":["../../src/WebFetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,KAAK,UAAU,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAOvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAGzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,aAAa,CAAA;AAC9B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,yEAAyE,CAAA;AACjG;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;EAQhB,CAAA;AACF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AACrC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;;;EAOjB,CAAA;AACF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AACvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAwE,CAAA;AAC5F;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAChE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAA+B,CAAA;AACxD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;CAAsF,CAAA;AAIvG;;;;;GAKG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;yDA0EsD,CAAA"}

package/dist/cjs/WebFetch.js

@@ -0,0 +1,140 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var WebFetch_exports = {};
+__export(WebFetch_exports, {
+  Input: () => Input,
+  Output: () => Output,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  run: () => run
+});
+module.exports = __toCommonJS(WebFetch_exports);
+var HttpClient = __toESM(require("@smthrs/kernel/HttpClient"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var HttpClientRequest = __toESM(require("effect/unstable/http/HttpClientRequest"), 1);
+var import_Declaration = require("./internal/Declaration.js");
+var import_Html = require("./internal/Html.js");
+var import_Http = require("./internal/Http.js");
+var import_HttpNetwork = require("./internal/HttpNetwork.js");
+var import_Url = require("./internal/Url.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+const maxRedirects = 10;
+const name = "webfetch";
+const description = "Fetch an HTTP URL and render its content as text, Markdown, or HTML.";
+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(import_Http.Timeout).annotate({
+    description: "Total timeout across requests, redirects, and response body in seconds, capped at 120"
+  })
+});
+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" }))
+});
+const effects = (0, import_Declaration.envelope)({ tier: "sealed", mode: "expected", reads: [], writes: [] });
+const effectsFor = (_input) => effects;
+const capabilities = [(0, import_Declaration.capability)("net:get", "*")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const error = (code, message, path) => new StdError.StdError({ code, message, ...path === void 0 ? {} : { path } });
+const run = Effect.fn("WebFetch.run")(function* (input) {
+  let url = (0, import_Url.parseHttpUrl)(input.url);
+  if (url === void 0) {
+    return yield* Effect.fail(
+      error("invalid_input", "URL must use http or https without user information", input.url)
+    );
+  }
+  const client = (0, import_HttpNetwork.guarded)(yield* HttpClient.HttpClient, false);
+  let headers = {
+    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) => (0, import_HttpNetwork.refusal)(cause) ?? error("request_failed", `Web fetch request failed: ${url}`))
+    );
+    const location = (0, import_Http.header)(response.headers, "location");
+    if (response.status >= 300 && response.status < 400 && location !== void 0) {
+      const next = (0, import_Url.parseHttpUrl)(location, url);
+      if (next === void 0) {
+        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 = (0, import_Http.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((0, import_Http.header)(response.headers, "content-length"));
+    if (Number.isFinite(length) && length > import_Http.MAX_RESPONSE_BYTES) {
+      return yield* Effect.fail(error("response_too_large", "Response exceeds the 5 MiB limit"));
+    }
+    const body = yield* (0, import_Http.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 } = (0, import_Http.capOutput)(
+      format === "html" || !normalizedContentType.includes("html") ? raw : format === "text" ? (0, import_Html.toText)(raw) : (0, import_Html.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.
+  (0, import_Http.withDeadline)(effect, input.url, input.timeout, (seconds) => error("timeout", `Web fetch timed out after ${seconds} seconds`))
+));
+//# sourceMappingURL=WebFetch.js.map