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

package/dist/cjs/ShellCommand.js

@@ -0,0 +1,102 @@
+"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 ShellCommand_exports = {};
+__export(ShellCommand_exports, {
+  DEFAULT_MAX_OUTPUT_TOKENS: () => DEFAULT_MAX_OUTPUT_TOKENS,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  Input: () => Input,
+  MAX_CAPTURE_BYTES: () => MAX_CAPTURE_BYTES,
+  Output: () => Output,
+  TIMEOUT_EXIT_CODE: () => TIMEOUT_EXIT_CODE,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  run: () => run
+});
+module.exports = __toCommonJS(ShellCommand_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_CodexText = require("./internal/CodexText.js");
+var import_Declaration = require("./internal/Declaration.js");
+var Exec = __toESM(require("./internal/Exec.js"), 1);
+const name = "shell_command";
+const description = "Runs a shell command and returns its output.\n- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary.";
+const DEFAULT_TIMEOUT_MS = 1e4;
+const MAX_CAPTURE_BYTES = 8e6;
+const DEFAULT_MAX_OUTPUT_TOKENS = 1e4;
+const TIMEOUT_EXIT_CODE = 124;
+const Input = Schema.Struct({
+  command: Schema.String.annotate({ description: "Shell script to run in the user's default shell." }),
+  workdir: Schema.optional(
+    Schema.String.annotate({ description: "Working directory for the command. Defaults to the turn cwd." })
+  ),
+  timeout_ms: Schema.optional(
+    Schema.Number.annotate({ description: "Maximum command runtime. Defaults to 10000 ms." })
+  )
+});
+const Output = Schema.Struct({
+  output: Schema.String.annotate({
+    description: "Codex-formatted result: exit code, wall time, and possibly middle-truncated output"
+  }),
+  exitCode: Schema.Number.annotate({ description: "Command exit code; 124 when the command timed out" })
+});
+const effects = (0, import_Declaration.envelope)({ tier: "irreversible", mode: "expected", reads: [], writes: [] });
+const effectsFor = (_input) => effects;
+const capabilities = [(0, import_Declaration.capability)("proc:spawn", "*")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const run = Effect.fn("ShellCommand.run")(function* (input) {
+  const timeoutMs = input.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+  const startedAt = Date.now();
+  const result = yield* Exec.exec(input.command, {
+    ...input.workdir === void 0 ? {} : { cwd: input.workdir },
+    timeoutMs,
+    maxCaptureBytes: MAX_CAPTURE_BYTES
+  }).pipe(
+    Effect.map((value) => ({ timedOut: false, value })),
+    Effect.catch(
+      (error) => error.code === "timeout" ? Effect.succeed({ timedOut: true, value: { exitCode: TIMEOUT_EXIT_CODE, stderr: "", stdout: "" } }) : Effect.fail(Exec.toStdError(input.command, error))
+    )
+  );
+  const durationSeconds = (Date.now() - startedAt) / 1e3;
+  const aggregated = result.value.stderr === "" ? result.value.stdout : result.value.stdout === "" ? result.value.stderr : `${result.value.stdout}${result.value.stderr}`;
+  return {
+    exitCode: result.value.exitCode,
+    output: (0, import_CodexText.formatExecOutputForModel)({
+      durationSeconds,
+      exitCode: result.value.exitCode,
+      maxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+      output: aggregated,
+      ...result.timedOut ? { timedOutAfterMs: timeoutMs } : {}
+    })
+  };
+});
+//# sourceMappingURL=ShellCommand.js.map

package/dist/cjs/ShellCommand.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ShellCommand.ts"],
+  "sourcesContent": ["/**\n * shell_command flow declaration and portable handler.\n *\n * A Codex CLI clone of the `shell_command` tool: string command, `workdir`,\n * `timeout_ms`, and the Codex output format (`Exit code:` / `Wall time:` /\n * `Output:` with middle token-budget truncation).\n *\n * Codex's `sandbox_permissions` / `justification` / `prefix_rule` approval\n * parameters are deliberately absent: the permission kernel owns\n * sandboxing and escalation in this harness.\n *\n * @since 1.0.0\n */\n\nimport type * as ChildProcessSpawner from \"@smthrs/kernel/ChildProcessSpawner\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport { formatExecOutputForModel } from \"./internal/CodexText.ts\"\nimport { capability, envelope } from \"./internal/Declaration.ts\"\nimport * as Exec from \"./internal/Exec.ts\"\nimport type * as StdError from \"./StdError.ts\"\n\n/**\n * Registry name for the shell_command flow. Matches the Codex CLI tool name.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"shell_command\"\n\n/**\n * Model-facing description of the shell_command flow. Matches the Codex CLI\n * (non-Windows) description.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description = \"Runs a shell command and returns its output.\\n\" +\n  \"- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary.\"\n\n/**\n * Default command timeout in milliseconds, matching Codex.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const DEFAULT_TIMEOUT_MS = 10_000\n\n/**\n * Maximum bytes retained from each stream while a shell command executes.\n *\n * This is far above the 10,000-token model budget because\n * `formatExecOutputForModel` keeps the head and tail while the capture bound\n * keeps only the tail. Commands below this bound therefore render byte for\n * byte as before, while larger output costs the bound instead of its full size.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_CAPTURE_BYTES = 8_000_000\n\n/**\n * Default output token budget, matching Codex.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const DEFAULT_MAX_OUTPUT_TOKENS = 10_000\n\n/**\n * Timeout exit code reported to the model, matching Codex exec.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const TIMEOUT_EXIT_CODE = 124\n\n/**\n * Input schema for the shell_command flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  command: Schema.String.annotate({ description: \"Shell script to run in the user's default shell.\" }),\n  workdir: Schema.optional(\n    Schema.String.annotate({ description: \"Working directory for the command. Defaults to the turn cwd.\" })\n  ),\n  timeout_ms: Schema.optional(\n    Schema.Number.annotate({ description: \"Maximum command runtime. Defaults to 10000 ms.\" })\n  )\n})\n\n/**\n * Decoded input accepted by the `shell_command` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * Output schema for the shell_command flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  output: Schema.String.annotate({\n    description: \"Codex-formatted result: exit code, wall time, and possibly middle-truncated output\"\n  }),\n  exitCode: Schema.Number.annotate({ description: \"Command exit code; 124 when the command timed out\" })\n})\n\n/**\n * Decoded output returned by the `shell_command` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * Static conservative effect envelope for the shell_command flow.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({ tier: \"irreversible\", mode: \"expected\", reads: [], writes: [] })\n\n/**\n * Narrows the effect envelope for a decoded invocation.\n *\n * A command line carries no declared envelope, so an invocation says nothing\n * the registry-time worst case does not already say.\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 shell_command flow.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"proc:spawn\", \"*\")]\n\n/**\n * Declaration-only shell_command 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 * Executes a shell command through the permission-aware kernel service and\n * renders the Codex model-facing output format.\n *\n * Non-zero exit codes and timeouts remain successful values, exactly as in\n * Codex; only host and permission failures use the typed error channel.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"ShellCommand.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError, ChildProcessSpawner.ChildProcessSpawner> {\n  const timeoutMs = input.timeout_ms ?? DEFAULT_TIMEOUT_MS\n  const startedAt = Date.now()\n  const result = yield* Exec.exec(input.command, {\n    ...(input.workdir === undefined ? {} : { cwd: input.workdir }),\n    timeoutMs,\n    maxCaptureBytes: MAX_CAPTURE_BYTES\n  }).pipe(\n    Effect.map((value) => ({ timedOut: false, value })),\n    Effect.catch((error) =>\n      error.code === \"timeout\"\n        ? Effect.succeed({ timedOut: true, value: { exitCode: TIMEOUT_EXIT_CODE, stderr: \"\", stdout: \"\" } })\n        : Effect.fail(Exec.toStdError(input.command, error))\n    )\n  )\n  const durationSeconds = (Date.now() - startedAt) / 1_000\n  const aggregated = result.value.stderr === \"\"\n    ? result.value.stdout\n    : result.value.stdout === \"\"\n    ? result.value.stderr\n    : `${result.value.stdout}${result.value.stderr}`\n  return {\n    exitCode: result.value.exitCode,\n    output: formatExecOutputForModel({\n      durationSeconds,\n      exitCode: result.value.exitCode,\n      maxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,\n      output: aggregated,\n      ...(result.timedOut ? { timedOutAfterMs: timeoutMs } : {})\n    })\n  }\n})\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,aAAwB;AACxB,aAAwB;AACxB,uBAAyC;AACzC,yBAAqC;AACrC,WAAsB;AASf,MAAM,OAAO;AASb,MAAM,cAAc;AASpB,MAAM,qBAAqB;AAa3B,MAAM,oBAAoB;AAQ1B,MAAM,4BAA4B;AAQlC,MAAM,oBAAoB;AAQ1B,MAAM,QAAQ,OAAO,OAAO;AAAA,EACjC,SAAS,OAAO,OAAO,SAAS,EAAE,aAAa,mDAAmD,CAAC;AAAA,EACnG,SAAS,OAAO;AAAA,IACd,OAAO,OAAO,SAAS,EAAE,aAAa,+DAA+D,CAAC;AAAA,EACxG;AAAA,EACA,YAAY,OAAO;AAAA,IACjB,OAAO,OAAO,SAAS,EAAE,aAAa,iDAAiD,CAAC;AAAA,EAC1F;AACF,CAAC;AAgBM,MAAM,SAAS,OAAO,OAAO;AAAA,EAClC,QAAQ,OAAO,OAAO,SAAS;AAAA,IAC7B,aAAa;AAAA,EACf,CAAC;AAAA,EACD,UAAU,OAAO,OAAO,SAAS,EAAE,aAAa,oDAAoD,CAAC;AACvG,CAAC;AAgBM,MAAM,cAAU,6BAAS,EAAE,MAAM,gBAAgB,MAAM,YAAY,OAAO,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC;AAW1F,MAAM,aAAa,CAAC,WAA8B;AAQlD,MAAM,eAAe,KAAC,+BAAW,cAAc,GAAG,CAAC;AAQnD,MAAM,OAAO,EAAE,MAAM,aAAa,OAAO,OAAO,QAAQ,QAAQ,cAAc,QAAQ;AAYtF,MAAM,MAAM,OAAO,GAAG,kBAAkB,EAAE,WAC/C,OACkG;AAClG,QAAM,YAAY,MAAM,cAAc;AACtC,QAAM,YAAY,KAAK,IAAI;AAC3B,QAAM,SAAS,OAAO,KAAK,KAAK,MAAM,SAAS;AAAA,IAC7C,GAAI,MAAM,YAAY,SAAY,CAAC,IAAI,EAAE,KAAK,MAAM,QAAQ;AAAA,IAC5D;AAAA,IACA,iBAAiB;AAAA,EACnB,CAAC,EAAE;AAAA,IACD,OAAO,IAAI,CAAC,WAAW,EAAE,UAAU,OAAO,MAAM,EAAE;AAAA,IAClD,OAAO;AAAA,MAAM,CAAC,UACZ,MAAM,SAAS,YACX,OAAO,QAAQ,EAAE,UAAU,MAAM,OAAO,EAAE,UAAU,mBAAmB,QAAQ,IAAI,QAAQ,GAAG,EAAE,CAAC,IACjG,OAAO,KAAK,KAAK,WAAW,MAAM,SAAS,KAAK,CAAC;AAAA,IACvD;AAAA,EACF;AACA,QAAM,mBAAmB,KAAK,IAAI,IAAI,aAAa;AACnD,QAAM,aAAa,OAAO,MAAM,WAAW,KACvC,OAAO,MAAM,SACb,OAAO,MAAM,WAAW,KACxB,OAAO,MAAM,SACb,GAAG,OAAO,MAAM,MAAM,GAAG,OAAO,MAAM,MAAM;AAChD,SAAO;AAAA,IACL,UAAU,OAAO,MAAM;AAAA,IACvB,YAAQ,2CAAyB;AAAA,MAC/B;AAAA,MACA,UAAU,OAAO,MAAM;AAAA,MACvB,iBAAiB;AAAA,MACjB,QAAQ;AAAA,MACR,GAAI,OAAO,WAAW,EAAE,iBAAiB,UAAU,IAAI,CAAC;AAAA,IAC1D,CAAC;AAAA,EACH;AACF,CAAC;",
+  "names": []
+}

package/dist/cjs/StdError.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The single typed error returned by every standard flow handler.
+ *
+ * @since 1.0.0
+ */
+import { Schema } from "effect";
+/**
+ * Stable, model-facing failure codes shared by the standard flows.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Code: Schema.Literals<readonly ["stale_read", "not_found", "not_a_directory", "not_a_file", "is_directory", "binary_file", "offset_out_of_range", "invalid_pattern", "invalid_input", "no_match", "not_modified", "permission_denied", "outside_declared_reads", "outside_declared_writes", "command_failed", "request_failed", "timeout", "rate_limited", "provider_unavailable", "moved_off", "unsupported", "unsupported_content_type", "response_too_large", "outside_container"]>;
+/**
+ * Stable, model-facing failure codes shared by the standard flows.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Code = typeof Code.Type;
+declare const StdError_base: Schema.Class<StdError, Schema.TaggedStruct<"@smthrs/std/StdError", {
+    readonly code: Schema.Literals<readonly ["stale_read", "not_found", "not_a_directory", "not_a_file", "is_directory", "binary_file", "offset_out_of_range", "invalid_pattern", "invalid_input", "no_match", "not_modified", "permission_denied", "outside_declared_reads", "outside_declared_writes", "command_failed", "request_failed", "timeout", "rate_limited", "provider_unavailable", "moved_off", "unsupported", "unsupported_content_type", "response_too_large", "outside_container"]>;
+    readonly message: Schema.String;
+    readonly path: Schema.optional<Schema.String>;
+    /** Full-file base, or unread when this run has not read the existing file. */
+    readonly base_digest: Schema.optional<Schema.String>;
+    /** Full-file current SHA-256, or absent. */
+    readonly current_digest: Schema.optional<Schema.String>;
+    /** Language-server request that failed. */
+    readonly method: Schema.optional<Schema.String>;
+    /** JSON-RPC diagnostics, bounded by the transport's maximum frame size. */
+    readonly rpcError: Schema.optional<Schema.Struct<{
+        readonly code: Schema.Number;
+        readonly message: Schema.String;
+        readonly data: Schema.optional<Schema.Unknown>;
+    }>>;
+    /** At most 64 KiB of the language server's most recent stderr. */
+    readonly stderr: Schema.optional<Schema.String>;
+    /** The limit a `timeout` ran past, in milliseconds, when the flow knows it. */
+    readonly limitMillis: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A recoverable standard-flow failure.
+ *
+ * Handlers keep ordinary outcomes (a non-zero exit code, an empty match set)
+ * in the success channel; this error is reserved for failures the model must
+ * see as failures.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class StdError extends StdError_base {
+}
+export {};
+//# sourceMappingURL=StdError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StdError.d.ts","sourceRoot":"","sources":["../../src/StdError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,IAAI,kdAyBf,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;;;;;IAgBjC,8EAA8E;;IAE9E,4CAA4C;;IAE5C,2CAA2C;;IAE3C,2EAA2E;;;;;;IAM3E,kEAAkE;;IAElE,+EAA+E;;;AA5BjF;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,aAoB5B;CAAG"}

package/dist/cjs/StdError.js

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var StdError_exports = {};
+__export(StdError_exports, {
+  Code: () => Code,
+  StdError: () => StdError
+});
+module.exports = __toCommonJS(StdError_exports);
+var import_effect = require("effect");
+const Code = import_effect.Schema.Literals([
+  "stale_read",
+  "not_found",
+  "not_a_directory",
+  "not_a_file",
+  "is_directory",
+  "binary_file",
+  "offset_out_of_range",
+  "invalid_pattern",
+  "invalid_input",
+  "no_match",
+  "not_modified",
+  "permission_denied",
+  "outside_declared_reads",
+  "outside_declared_writes",
+  "command_failed",
+  "request_failed",
+  "timeout",
+  "rate_limited",
+  "provider_unavailable",
+  "moved_off",
+  "unsupported",
+  "unsupported_content_type",
+  "response_too_large",
+  "outside_container"
+]);
+class StdError extends import_effect.Schema.TaggedError()("@smthrs/std/StdError", {
+  code: Code,
+  message: import_effect.Schema.String,
+  path: import_effect.Schema.optional(import_effect.Schema.String),
+  /** Full-file base, or unread when this run has not read the existing file. */
+  base_digest: import_effect.Schema.optional(import_effect.Schema.String),
+  /** Full-file current SHA-256, or absent. */
+  current_digest: import_effect.Schema.optional(import_effect.Schema.String),
+  /** Language-server request that failed. */
+  method: import_effect.Schema.optional(import_effect.Schema.String),
+  /** JSON-RPC diagnostics, bounded by the transport's maximum frame size. */
+  rpcError: import_effect.Schema.optional(import_effect.Schema.Struct({
+    code: import_effect.Schema.Number,
+    message: import_effect.Schema.String,
+    data: import_effect.Schema.optional(import_effect.Schema.Unknown)
+  })),
+  /** At most 64 KiB of the language server's most recent stderr. */
+  stderr: import_effect.Schema.optional(import_effect.Schema.String),
+  /** The limit a `timeout` ran past, in milliseconds, when the flow knows it. */
+  limitMillis: import_effect.Schema.optional(import_effect.Schema.Number)
+}) {
+}
+//# sourceMappingURL=StdError.js.map

package/dist/cjs/StdError.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/StdError.ts"],
+  "sourcesContent": ["/**\n * The single typed error returned by every standard flow handler.\n *\n * @since 1.0.0\n */\n\nimport { Schema } from \"effect\"\n\n/**\n * Stable, model-facing failure codes shared by the standard flows.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Code = Schema.Literals([\n  \"stale_read\",\n  \"not_found\",\n  \"not_a_directory\",\n  \"not_a_file\",\n  \"is_directory\",\n  \"binary_file\",\n  \"offset_out_of_range\",\n  \"invalid_pattern\",\n  \"invalid_input\",\n  \"no_match\",\n  \"not_modified\",\n  \"permission_denied\",\n  \"outside_declared_reads\",\n  \"outside_declared_writes\",\n  \"command_failed\",\n  \"request_failed\",\n  \"timeout\",\n  \"rate_limited\",\n  \"provider_unavailable\",\n  \"moved_off\",\n  \"unsupported\",\n  \"unsupported_content_type\",\n  \"response_too_large\",\n  \"outside_container\"\n])\n\n/**\n * Stable, model-facing failure codes shared by the standard flows.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Code = typeof Code.Type\n\n/**\n * A recoverable standard-flow failure.\n *\n * Handlers keep ordinary outcomes (a non-zero exit code, an empty match set)\n * in the success channel; this error is reserved for failures the model must\n * see as failures.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class StdError extends Schema.TaggedError<StdError>()(\"@smthrs/std/StdError\", {\n  code: Code,\n  message: Schema.String,\n  path: Schema.optional(Schema.String),\n  /** Full-file base, or unread when this run has not read the existing file. */\n  base_digest: Schema.optional(Schema.String),\n  /** Full-file current SHA-256, or absent. */\n  current_digest: Schema.optional(Schema.String),\n  /** Language-server request that failed. */\n  method: Schema.optional(Schema.String),\n  /** JSON-RPC diagnostics, bounded by the transport's maximum frame size. */\n  rpcError: Schema.optional(Schema.Struct({\n    code: Schema.Number,\n    message: Schema.String,\n    data: Schema.optional(Schema.Unknown)\n  })),\n  /** At most 64 KiB of the language server's most recent stderr. */\n  stderr: Schema.optional(Schema.String),\n  /** The limit a `timeout` ran past, in milliseconds, when the flow knows it. */\n  limitMillis: Schema.optional(Schema.Number)\n}) {}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAAuB;AAQhB,MAAM,OAAO,qBAAO,SAAS;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAoBM,MAAM,iBAAiB,qBAAO,YAAsB,EAAE,wBAAwB;AAAA,EACnF,MAAM;AAAA,EACN,SAAS,qBAAO;AAAA,EAChB,MAAM,qBAAO,SAAS,qBAAO,MAAM;AAAA;AAAA,EAEnC,aAAa,qBAAO,SAAS,qBAAO,MAAM;AAAA;AAAA,EAE1C,gBAAgB,qBAAO,SAAS,qBAAO,MAAM;AAAA;AAAA,EAE7C,QAAQ,qBAAO,SAAS,qBAAO,MAAM;AAAA;AAAA,EAErC,UAAU,qBAAO,SAAS,qBAAO,OAAO;AAAA,IACtC,MAAM,qBAAO;AAAA,IACb,SAAS,qBAAO;AAAA,IAChB,MAAM,qBAAO,SAAS,qBAAO,OAAO;AAAA,EACtC,CAAC,CAAC;AAAA;AAAA,EAEF,QAAQ,qBAAO,SAAS,qBAAO,MAAM;AAAA;AAAA,EAErC,aAAa,qBAAO,SAAS,qBAAO,MAAM;AAC5C,CAAC,EAAE;AAAC;",
+  "names": []
+}

package/dist/cjs/TestRun.d.ts

@@ -0,0 +1,311 @@
+/**
+ * The `test` flow: run the declared suite, and answer with the two facts.
+ *
+ * Two things this returns that a shell command cannot. First, a *reading*:
+ * `{passed, failed}` parsed from the runner's own report, with the raw tail
+ * kept for whatever the parse could not carry — a suite's answer is a number
+ * and a list of names, not twenty kilobytes of stdout for a model to re-read.
+ *
+ * Second, `against: "base"`: the same selection also runs against the pristine
+ * base commit in a scratch checkout, and the two failure sets are differenced
+ * here. That is the whole of attribution, in one call. Without it, agents pay
+ * for it in frames — sphinx-8721 spent fourteen frames because a pre-existing
+ * failure was never baselined, sympy-13878 spent $0.90 on the same mistake, and
+ * django-24970 spent three frames. The rule the harness teaches ("before
+ * blaming your own edit, run the same command on the unmodified tree") is only
+ * cheap when the tool can do it.
+ *
+ * A third thing is answered on the way out: whether a non-zero exit is the
+ * tree's failure at all, or the command failing to resolve a name. Jev decides
+ * it through `Probe.classify`, so the flow needs an `Evaluator` and a host
+ * uses its configured subscription seat. A judge that does not answer fails the call with
+ * the code `Probe.unjudged` names, because a run nobody judged is not a run
+ * this flow can report on.
+ *
+ * @since 1.0.0
+ */
+import type * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import type * as Evaluator from "@smthrs/model/Evaluator";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+import * as TestRunner from "./TestRunner.ts";
+/**
+ * Registry name for the test flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "test";
+/**
+ * Model-facing description of the test flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Run this repository's declared test runner and get {passed, failed[ids]}, not raw output. against:'base' also runs it on the pristine base commit, so a pre-existing failure is named, not investigated.";
+/**
+ * The parent directory baseline checkouts are written into, relative to the
+ * repository root, and therefore also relative to the runner's own directory.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const scratchDirectory = ".flows-test-base";
+/**
+ * Default wall-clock budget for one test run.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+/**
+ * Maximum bytes retained from each stream while a test run executes.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const MAX_CAPTURE_BYTES = 8000000;
+/**
+ * Input schema for the test flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly selection: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly against: Schema.optional<Schema.Literals<readonly ["workspace", "base"]>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>;
+/**
+ * Decoded input accepted by the `test` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * One run's outcome.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Outcome: Schema.Struct<{
+    readonly command: Schema.String;
+    readonly exitCode: Schema.Number;
+    readonly passed: Schema.Number;
+    readonly failed: Schema.$Array<Schema.String>;
+    readonly parsed: Schema.Boolean;
+    readonly tail: Schema.String;
+    readonly tailTruncated: Schema.Boolean;
+    readonly tailDroppedBytes: Schema.Number;
+    readonly invalidProbe: Schema.optional<Schema.Struct<{
+        readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+        readonly evidence: Schema.String;
+        readonly message: Schema.String;
+    }>>;
+}>;
+/**
+ * Output schema for the test flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly base: Schema.optional<Schema.Struct<{
+        readonly ref: Schema.String;
+        readonly commit: Schema.String;
+        readonly command: Schema.String;
+        readonly exitCode: Schema.Number;
+        readonly passed: Schema.Number;
+        readonly failed: Schema.$Array<Schema.String>;
+        readonly parsed: Schema.Boolean;
+        readonly tail: Schema.String;
+        readonly tailTruncated: Schema.Boolean;
+        readonly tailDroppedBytes: Schema.Number;
+        readonly invalidProbe: Schema.optional<Schema.Struct<{
+            readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+            readonly evidence: Schema.String;
+            readonly message: Schema.String;
+        }>>;
+    }>>;
+    readonly introduced: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly preexisting: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly fixed: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly command: Schema.String;
+    readonly exitCode: Schema.Number;
+    readonly passed: Schema.Number;
+    readonly failed: Schema.$Array<Schema.String>;
+    readonly parsed: Schema.Boolean;
+    readonly tail: Schema.String;
+    readonly tailTruncated: Schema.Boolean;
+    readonly tailDroppedBytes: Schema.Number;
+    readonly invalidProbe: Schema.optional<Schema.Struct<{
+        readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+        readonly evidence: Schema.String;
+        readonly message: Schema.String;
+    }>>;
+}>;
+/**
+ * Decoded output returned by the `test` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static conservative effect envelope for the test flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the test flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only test flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "test";
+    readonly description: "Run this repository's declared test runner and get {passed, failed[ids]}, not raw output. against:'base' also runs it on the pristine base commit, so a pre-existing failure is named, not investigated.";
+    readonly input: Schema.Struct<{
+        readonly selection: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly against: Schema.optional<Schema.Literals<readonly ["workspace", "base"]>>;
+        readonly timeoutMs: Schema.optional<Schema.Number>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly base: Schema.optional<Schema.Struct<{
+            readonly ref: Schema.String;
+            readonly commit: Schema.String;
+            readonly command: Schema.String;
+            readonly exitCode: Schema.Number;
+            readonly passed: Schema.Number;
+            readonly failed: Schema.$Array<Schema.String>;
+            readonly parsed: Schema.Boolean;
+            readonly tail: Schema.String;
+            readonly tailTruncated: Schema.Boolean;
+            readonly tailDroppedBytes: Schema.Number;
+            readonly invalidProbe: Schema.optional<Schema.Struct<{
+                readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+                readonly evidence: Schema.String;
+                readonly message: Schema.String;
+            }>>;
+        }>>;
+        readonly introduced: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly preexisting: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly fixed: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly command: Schema.String;
+        readonly exitCode: Schema.Number;
+        readonly passed: Schema.Number;
+        readonly failed: Schema.$Array<Schema.String>;
+        readonly parsed: Schema.Boolean;
+        readonly tail: Schema.String;
+        readonly tailTruncated: Schema.Boolean;
+        readonly tailDroppedBytes: Schema.Number;
+        readonly invalidProbe: Schema.optional<Schema.Struct<{
+            readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+            readonly evidence: Schema.String;
+            readonly message: Schema.String;
+        }>>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const activity: "tests";
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const presentation: {
+    readonly verb: {
+        readonly pending: "running";
+        readonly success: "ran";
+        readonly failure: "failed to run";
+    };
+    readonly subject: "selection";
+    readonly result: "tests";
+};
+/**
+ * Runs the declared suite, and on request the same suite on the pristine base.
+ *
+ * Baseline Git and both runners use the caller-provided process service.
+ * A host that cannot safely stage the base declares `baseline: false`, which
+ * refuses the request before running either suite or Git. Library hosts that
+ * support staging remove the detached checkout when the call ends.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly timeoutMs?: number | undefined;
+    readonly selection?: readonly string[] | undefined;
+    readonly against?: "base" | "workspace" | undefined;
+}) => Effect.Effect<{
+    readonly tail: string;
+    readonly exitCode: number;
+    readonly command: string;
+    readonly failed: readonly string[];
+    readonly passed: number;
+    readonly parsed: boolean;
+    readonly tailTruncated: boolean;
+    readonly tailDroppedBytes: number;
+    readonly fixed?: readonly string[] | undefined;
+    readonly invalidProbe?: {
+        readonly reason: "unknown-command" | "unknown-test" | "unknown-path" | "unknown-module" | "unknown-environment";
+        readonly evidence: string;
+        readonly message: string;
+    } | undefined;
+    readonly base?: {
+        readonly tail: string;
+        readonly exitCode: number;
+        readonly command: string;
+        readonly failed: readonly string[];
+        readonly ref: string;
+        readonly commit: string;
+        readonly passed: number;
+        readonly parsed: boolean;
+        readonly tailTruncated: boolean;
+        readonly tailDroppedBytes: number;
+        readonly invalidProbe?: {
+            readonly reason: "unknown-command" | "unknown-test" | "unknown-path" | "unknown-module" | "unknown-environment";
+            readonly evidence: string;
+            readonly message: string;
+        } | undefined;
+    } | undefined;
+    readonly introduced?: readonly string[] | undefined;
+    readonly preexisting?: readonly string[] | undefined;
+}, StdError.StdError, ChildProcessSpawner.ChildProcessSpawner | Evaluator.Evaluator | TestRunner.TestRunner>;
+//# sourceMappingURL=TestRun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TestRun.d.ts","sourceRoot":"","sources":["../../src/TestRun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,KAAK,mBAAmB,MAAM,oCAAoC,CAAA;AAC9E,OAAO,KAAK,KAAK,SAAS,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AASvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,IAAI,SAAS,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,6MACoL,CAAA;AAE5M;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,qBAAwB,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAY,CAAA;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;EAShB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;EAoBlB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAA8E,CAAA;AAElG;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAAkC,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAG,OAAgB,CAAA;AAExC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAIf,CAAA;AAkGV;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4GA6Dd,CAAA"}