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

package/dist/esm/internal/EnvelopePrecheck.js

@@ -0,0 +1,167 @@
+/**
+ * The hermetic pre-check: a lexical scan of shell text for the paths it names,
+ * and the refusal when one of them falls outside the declared envelope.
+ *
+ * The scan is fail-closed over explicit path tokens and nothing more. It
+ * cannot prove confinement — a shell can name a path no lexer sees, through a
+ * variable, a substitution, or a program that opens a file of its own — so a
+ * kernel or host sandbox must eventually enforce and report the complete read
+ * and write sets.
+ *
+ * It lives beside the flow rather than inside it because it is its own
+ * concept, with its own vocabulary (Access, PathReference) and its own
+ * security history: three independent bypasses, each sufficient on its own to
+ * defeat it, are closed here.
+ *
+ * @since 1.0.0
+ */
+import * as StdError from "../StdError.js";
+import { withinEnvelope } from "./Paths.js";
+const commandSeparators = new Set(["&&", "||", ";", "|", "&", "\n"]);
+const redirections = new Set([">", ">>", "<", "<<"]);
+const writeCommands = new Set(["chmod", "chown", "mkdir", "rm", "rmdir", "tee", "touch", "truncate", "unlink"]);
+const destinationCommands = new Set(["cp", "install", "mv"]);
+const prefixWrappers = new Set(["env", "nice", "time", "sudo", "nohup", "xargs", "command", "exec"]);
+// Shell spaces may disappear, but a physical line ends one command. Retaining
+// LF prevents a command on line one from classifying every later line's paths.
+//
+// A word is one or more runs of bare characters and quoted sections, not a
+// bare run alone: `FOO="a b" rm /work/target` used to tokenize as `FOO="a`,
+// `b"`, `rm`, `/work/target`, and since only the first token carried an `=`
+// the command was read as `b"` rather than `rm` — so the delete was
+// classified as a read and a hermetic call with `writes: []` spawned. The
+// quoted alternatives come first inside the group so a quoted span is taken
+// whole; the bare class excludes quotes so the branches cannot overlap.
+const tokenize = (command) => command.match(/\n|>>|<<|&&|\|\||[<>;|&]|(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s<>;|&"']+)+/g) ?? [];
+const unquote = (token) => {
+    const first = token[0];
+    const last = token[token.length - 1];
+    return token.length >= 2 && (first === "'" || first === "\"") && last === first
+        ? token.slice(1, -1)
+        : token;
+};
+const pathValue = (token) => unquote(token)
+    .replace(/^\$\(+/, "")
+    .replace(/[),]+$/, "");
+const isPathToken = (path, token) => token === "." ||
+    token === ".." ||
+    token.startsWith("./") ||
+    token.startsWith("../") ||
+    path.isAbsolute(token) ||
+    /^[A-Za-z]:[\\/]/.test(token) ||
+    token.includes("/");
+const segmentReferences = (path, tokens) => {
+    const commentIndex = tokens.findIndex((token) => token.startsWith("#"));
+    const active = commentIndex === -1 ? tokens : tokens.slice(0, commentIndex);
+    const hasWrapper = active.some((token) => prefixWrappers.has(path.basename(pathValue(token))));
+    let commandIndex = active.findIndex((token) => !redirections.has(token) &&
+        !token.includes("=") &&
+        !prefixWrappers.has(path.basename(pathValue(token))) &&
+        !token.startsWith("-") &&
+        token !== "");
+    if (hasWrapper) {
+        // Wrapper options can carry their own values. Prefer a later known
+        // mutating command so an option value cannot lend it a read classification.
+        const mutatingIndex = active.findIndex((token) => {
+            const command = path.basename(pathValue(token));
+            return writeCommands.has(command) || destinationCommands.has(command);
+        });
+        if (mutatingIndex !== -1)
+            commandIndex = mutatingIndex;
+    }
+    if (commandIndex === -1)
+        return [];
+    const command = path.basename(pathValue(active[commandIndex]));
+    const candidates = [];
+    for (let index = 0; index < active.length; index++) {
+        const token = active[index];
+        if (index === commandIndex || redirections.has(token) || token.startsWith("-"))
+            continue;
+        const value = pathValue(token);
+        if (value !== "" && isPathToken(path, value))
+            candidates.push({ index, value });
+    }
+    const destinationIndex = destinationCommands.has(command)
+        ? candidates[candidates.length - 1]?.index
+        : undefined;
+    return candidates.map(({ index, value }) => {
+        const previous = active[index - 1];
+        const access = previous === ">" || previous === ">>" ||
+            writeCommands.has(command) || destinationIndex === index
+            ? "write"
+            : "read";
+        return { access, value };
+    });
+};
+/**
+ * Every path token the shell text names, one segment at a time.
+ *
+ * @category pre-check
+ * @since 1.0.0
+ */
+export const commandReferences = (path, command) => {
+    const references = [];
+    let segment = [];
+    for (const token of tokenize(command)) {
+        if (commandSeparators.has(token)) {
+            references.push(...segmentReferences(path, segment));
+            segment = [];
+        }
+        else {
+            segment.push(token);
+        }
+    }
+    references.push(...segmentReferences(path, segment));
+    return references;
+};
+const resolvePath = (path, cwd, value) => path.isAbsolute(value) ? path.normalize(value) : path.resolve(cwd, value);
+const isDeclared = (path, cwd, declared, source) => withinEnvelope(declared.map((entry) => resolvePath(path, cwd, entry)), resolvePath(path, cwd, source));
+/**
+ * The refusal shell text earns by naming a path outside its declared
+ * envelope, or `undefined` when every path it names is declared.
+ *
+ * @category pre-check
+ * @since 1.0.0
+ */
+export const outsideEnvelope = (input, text, path) => {
+    const base = path.resolve(".");
+    const cwd = path.resolve(input.cwd ?? ".");
+    // Passing the default explicitly is not a declaration the caller owes. A
+    // working directory is where the command runs, not a file it reads, and
+    // `cwd: "."` names exactly what omitting `cwd` names — so refusing it asked
+    // the caller to list the workspace root among its reads to say nothing at
+    // all. Agents hit this constantly: one SWE-bench run spent ten of its
+    // forty-eight tool calls re-issuing the same command after
+    // "Working directory is outside declared reads: <the workspace root>". A
+    // cwd that points somewhere else is still declared or refused.
+    if (input.cwd !== undefined && cwd !== base && !isDeclared(path, cwd, input.reads, cwd)) {
+        return new StdError.StdError({
+            code: "outside_declared_reads",
+            message: `Working directory is outside declared reads: ${cwd}`,
+            path: cwd
+        });
+    }
+    // The Shell contract currently has no sandbox or access-reporting surface.
+    // This lexical scan is intentionally only a fail-closed pre-check for
+    // explicit path tokens. It cannot prove confinement; a kernel/host sandbox
+    // must eventually enforce and report the complete read and write sets.
+    for (const reference of commandReferences(path, text)) {
+        const resolved = resolvePath(path, cwd, reference.value);
+        // /dev/* is the process plumbing every shell one-liner leans on:
+        // `2>/dev/null`, `cat /dev/stdin`. Normalize first so a dot-dot segment
+        // cannot disguise an ordinary filesystem path as process plumbing.
+        if (resolved.startsWith("/dev/"))
+            continue;
+        const declared = reference.access === "write" ? input.writes : input.reads;
+        if (!isDeclared(path, cwd, declared, resolved)) {
+            const code = reference.access === "write" ? "outside_declared_writes" : "outside_declared_reads";
+            return new StdError.StdError({
+                code,
+                message: `Command path is outside declared ${reference.access}s: ${resolved}`,
+                path: resolved
+            });
+        }
+    }
+    return undefined;
+};
+//# sourceMappingURL=EnvelopePrecheck.js.map

package/dist/esm/internal/EnvelopePrecheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvelopePrecheck.js","sourceRoot":"","sources":["../../../src/internal/EnvelopePrecheck.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The hermetic pre-check: a lexical scan of shell text for the paths it names,\n * and the refusal when one of them falls outside the declared envelope.\n *\n * The scan is fail-closed over explicit path tokens and nothing more. It\n * cannot prove confinement — a shell can name a path no lexer sees, through a\n * variable, a substitution, or a program that opens a file of its own — so a\n * kernel or host sandbox must eventually enforce and report the complete read\n * and write sets.\n *\n * It lives beside the flow rather than inside it because it is its own\n * concept, with its own vocabulary (Access, PathReference) and its own\n * security history: three independent bypasses, each sufficient on its own to\n * defeat it, are closed here.\n *\n * @since 1.0.0\n */\n\nimport type * as Path from \"@smthrs/kernel/Path\"\nimport * as StdError from \"../StdError.ts\"\nimport { withinEnvelope } from \"./Paths.ts\"\n\n/**\n * The filesystem envelope one invocation declared.\n *\n * Structural rather than the hermetic `Bash.Input` itself: the scan needs the\n * three fields and none of the rest, and depending on the flow module would\n * make the flow and its pre-check import each other.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Envelope {\n  readonly cwd?: string | undefined\n  readonly reads: ReadonlyArray<string>\n  readonly writes: ReadonlyArray<string>\n}\n\n/**\n * How a command touches a path it names.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Access = \"read\" | \"write\"\n\n/**\n * One path a command names, and how it touches it.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface PathReference {\n  readonly access: Access\n  readonly value: string\n}\n\nconst commandSeparators = new Set([\"&&\", \"||\", \";\", \"|\", \"&\", \"\\n\"])\nconst redirections = new Set([\">\", \">>\", \"<\", \"<<\"])\nconst writeCommands = new Set([\"chmod\", \"chown\", \"mkdir\", \"rm\", \"rmdir\", \"tee\", \"touch\", \"truncate\", \"unlink\"])\nconst destinationCommands = new Set([\"cp\", \"install\", \"mv\"])\nconst prefixWrappers = new Set([\"env\", \"nice\", \"time\", \"sudo\", \"nohup\", \"xargs\", \"command\", \"exec\"])\n\n// Shell spaces may disappear, but a physical line ends one command. Retaining\n// LF prevents a command on line one from classifying every later line's paths.\n//\n// A word is one or more runs of bare characters and quoted sections, not a\n// bare run alone: `FOO=\"a b\" rm /work/target` used to tokenize as `FOO=\"a`,\n// `b\"`, `rm`, `/work/target`, and since only the first token carried an `=`\n// the command was read as `b\"` rather than `rm` — so the delete was\n// classified as a read and a hermetic call with `writes: []` spawned. The\n// quoted alternatives come first inside the group so a quoted span is taken\n// whole; the bare class excludes quotes so the branches cannot overlap.\nconst tokenize = (command: string): ReadonlyArray<string> =>\n  command.match(/\\n|>>|<<|&&|\\|\\||[<>;|&]|(?:\"(?:\\\\.|[^\"\\\\])*\"|'[^']*'|[^\\s<>;|&\"']+)+/g) ?? []\n\nconst unquote = (token: string): string => {\n  const first = token[0]\n  const last = token[token.length - 1]\n  return token.length >= 2 && (first === \"'\" || first === \"\\\"\") && last === first\n    ? token.slice(1, -1)\n    : token\n}\n\nconst pathValue = (token: string): string =>\n  unquote(token)\n    .replace(/^\\$\\(+/, \"\")\n    .replace(/[),]+$/, \"\")\n\nconst isPathToken = (path: Path.Path, token: string): boolean =>\n  token === \".\" ||\n  token === \"..\" ||\n  token.startsWith(\"./\") ||\n  token.startsWith(\"../\") ||\n  path.isAbsolute(token) ||\n  /^[A-Za-z]:[\\\\/]/.test(token) ||\n  token.includes(\"/\")\n\nconst segmentReferences = (path: Path.Path, tokens: ReadonlyArray<string>): ReadonlyArray<PathReference> => {\n  const commentIndex = tokens.findIndex((token) => token.startsWith(\"#\"))\n  const active = commentIndex === -1 ? tokens : tokens.slice(0, commentIndex)\n  const hasWrapper = active.some((token) => prefixWrappers.has(path.basename(pathValue(token))))\n  let commandIndex = active.findIndex((token) =>\n    !redirections.has(token) &&\n    !token.includes(\"=\") &&\n    !prefixWrappers.has(path.basename(pathValue(token))) &&\n    !token.startsWith(\"-\") &&\n    token !== \"\"\n  )\n  if (hasWrapper) {\n    // Wrapper options can carry their own values. Prefer a later known\n    // mutating command so an option value cannot lend it a read classification.\n    const mutatingIndex = active.findIndex((token) => {\n      const command = path.basename(pathValue(token))\n      return writeCommands.has(command) || destinationCommands.has(command)\n    })\n    if (mutatingIndex !== -1) commandIndex = mutatingIndex\n  }\n  if (commandIndex === -1) return []\n\n  const command = path.basename(pathValue(active[commandIndex]!))\n  const candidates: Array<{ readonly index: number; readonly value: string }> = []\n  for (let index = 0; index < active.length; index++) {\n    const token = active[index]!\n    if (index === commandIndex || redirections.has(token) || token.startsWith(\"-\")) continue\n    const value = pathValue(token)\n    if (value !== \"\" && isPathToken(path, value)) candidates.push({ index, value })\n  }\n\n  const destinationIndex = destinationCommands.has(command)\n    ? candidates[candidates.length - 1]?.index\n    : undefined\n\n  return candidates.map(({ index, value }) => {\n    const previous = active[index - 1]\n    const access: Access = previous === \">\" || previous === \">>\" ||\n        writeCommands.has(command) || destinationIndex === index\n      ? \"write\"\n      : \"read\"\n    return { access, value }\n  })\n}\n\n/**\n * Every path token the shell text names, one segment at a time.\n *\n * @category pre-check\n * @since 1.0.0\n */\nexport const commandReferences = (path: Path.Path, command: string): ReadonlyArray<PathReference> => {\n  const references: Array<PathReference> = []\n  let segment: Array<string> = []\n  for (const token of tokenize(command)) {\n    if (commandSeparators.has(token)) {\n      references.push(...segmentReferences(path, segment))\n      segment = []\n    } else {\n      segment.push(token)\n    }\n  }\n  references.push(...segmentReferences(path, segment))\n  return references\n}\n\nconst resolvePath = (\n  path: Path.Path,\n  cwd: string,\n  value: string\n): string => path.isAbsolute(value) ? path.normalize(value) : path.resolve(cwd, value)\n\nconst isDeclared = (\n  path: Path.Path,\n  cwd: string,\n  declared: ReadonlyArray<string>,\n  source: string\n): boolean =>\n  withinEnvelope(\n    declared.map((entry) => resolvePath(path, cwd, entry)),\n    resolvePath(path, cwd, source)\n  )\n\n/**\n * The refusal shell text earns by naming a path outside its declared\n * envelope, or `undefined` when every path it names is declared.\n *\n * @category pre-check\n * @since 1.0.0\n */\nexport const outsideEnvelope = (\n  input: Envelope,\n  text: string,\n  path: Path.Path\n): StdError.StdError | undefined => {\n  const base = path.resolve(\".\")\n  const cwd = path.resolve(input.cwd ?? \".\")\n  // Passing the default explicitly is not a declaration the caller owes. A\n  // working directory is where the command runs, not a file it reads, and\n  // `cwd: \".\"` names exactly what omitting `cwd` names — so refusing it asked\n  // the caller to list the workspace root among its reads to say nothing at\n  // all. Agents hit this constantly: one SWE-bench run spent ten of its\n  // forty-eight tool calls re-issuing the same command after\n  // \"Working directory is outside declared reads: <the workspace root>\". A\n  // cwd that points somewhere else is still declared or refused.\n  if (input.cwd !== undefined && cwd !== base && !isDeclared(path, cwd, input.reads, cwd)) {\n    return new StdError.StdError({\n      code: \"outside_declared_reads\",\n      message: `Working directory is outside declared reads: ${cwd}`,\n      path: cwd\n    })\n  }\n\n  // The Shell contract currently has no sandbox or access-reporting surface.\n  // This lexical scan is intentionally only a fail-closed pre-check for\n  // explicit path tokens. It cannot prove confinement; a kernel/host sandbox\n  // must eventually enforce and report the complete read and write sets.\n  for (const reference of commandReferences(path, text)) {\n    const resolved = resolvePath(path, cwd, reference.value)\n    // /dev/* is the process plumbing every shell one-liner leans on:\n    // `2>/dev/null`, `cat /dev/stdin`. Normalize first so a dot-dot segment\n    // cannot disguise an ordinary filesystem path as process plumbing.\n    if (resolved.startsWith(\"/dev/\")) continue\n    const declared = reference.access === \"write\" ? input.writes : input.reads\n    if (!isDeclared(path, cwd, declared, resolved)) {\n      const code = reference.access === \"write\" ? \"outside_declared_writes\" : \"outside_declared_reads\"\n      return new StdError.StdError({\n        code,\n        message: `Command path is outside declared ${reference.access}s: ${resolved}`,\n        path: resolved\n      })\n    }\n  }\n  return undefined\n}\n"]}

package/dist/esm/internal/Exec.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Buffered shell execution over the permission-aware process spawner.
+ *
+ * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a
+ * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with
+ * `ChildProcessSpawner`, Effect's own process boundary, which streams and has
+ * no buffered form. This module is the buffered form the shell flows still
+ * want, expressed in terms of the spawner so the `proc:spawn` capability check
+ * and the command-line resource stay exactly where the kernel put them.
+ *
+ * Commands run through the platform shell (`shell: true`), matching the old
+ * service: the flows take a command *line*, not an argv.
+ *
+ * @since 1.0.0
+ */
+import * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as StdError from "../StdError.ts";
+/**
+ * Failure codes a buffered execution can report, matching the codes the
+ * removed kernel `Shell` used so handler-level mapping is unchanged.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const ExecErrorCode: Schema.Literals<readonly ["timeout", "spawn_error", "capture_overflow"]>;
+/**
+ * Failure codes a buffered execution can report.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type ExecErrorCode = typeof ExecErrorCode.Type;
+declare const ExecError_base: Schema.Class<ExecError, Schema.TaggedStruct<"@smthrs/std/ExecError", {
+    readonly code: Schema.Literals<readonly ["timeout", "spawn_error", "capture_overflow"]>;
+    readonly message: Schema.String;
+    /** The limit a `timeout` ran past, in milliseconds. */
+    readonly limitMillis: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A command that never produced an exit code.
+ *
+ * A non-zero exit is a successful {@link ExecResult}, not a failure; this
+ * error is reserved for a command that could not start or was cut off by its
+ * timeout, or whose captured output exceeded a refusing capture bound.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ExecError extends ExecError_base {
+}
+/**
+ * The buffered result of one command.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    /** UTF-8 bytes dropped from the head of stdout to stay inside the capture bound. */
+    readonly stdoutDroppedBytes: number;
+    /** UTF-8 bytes dropped from the head of stderr to stay inside the capture bound. */
+    readonly stderrDroppedBytes: number;
+}
+/**
+ * Options accepted by {@link exec}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface ExecOptions {
+    readonly cwd?: string | undefined;
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    readonly timeoutMs?: number | undefined;
+    /**
+     * The program's arguments. Present means an argv, absent means a command
+     * line for the platform shell. An argv is how a payload reaches a program
+     * without being quoted into a string: nothing between here and `execve`
+     * re-parses it.
+     */
+    readonly args?: ReadonlyArray<string> | undefined;
+    /**
+     * Text written to the program's standard input, as data. A script delivered
+     * this way is never quoted, escaped, or heredoc-terminated, which is the
+     * whole point: quoting corruption cost the measured SWE-bench program twelve
+     * probe failures and one instance's most expensive frame.
+     */
+    readonly stdin?: string | undefined;
+    /**
+     * Bytes retained per captured stream. A stream that prints more keeps its
+     * tail and reports what it dropped, so a command printing gigabytes costs a
+     * bounded amount of memory rather than the whole of what it printed.
+     *
+     * Absent means unbounded, which is what a caller wants when it needs every
+     * byte a tool produced (`rg --files`, `git worktree list`).
+     */
+    readonly maxCaptureBytes?: number | undefined;
+    /** Defaults to `tail`; `refuse` fails if either stream exceeds the bound. */
+    readonly overflow?: "tail" | "refuse" | undefined;
+}
+/**
+ * Runs a command line through the platform shell and buffers its output.
+ *
+ * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber
+ * — including the one a `timeoutMs` interrupts — terminates the process rather
+ * than leaking it.
+ *
+ * @category execution
+ * @since 1.0.0
+ */
+export declare const exec: (command: string, options?: ExecOptions) => Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner>;
+/**
+ * The model-facing failure code a command that never produced an exit code
+ * carries.
+ *
+ * A timeout keeps its own code, because "the command never finished" and "the
+ * command never started" are different things to a caller deciding whether to
+ * retry. Every other way of producing no exit code is a host failure.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const toStdErrorCode: (error: ExecError) => StdError.Code;
+/**
+ * The model-facing failure one execution error becomes.
+ *
+ * A timeout names the command, which is what the caller asked for and all a
+ * timeout has to say. Any other failure carries the message the execution
+ * produced, which already names the command.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const toStdError: (command: string, error: ExecError) => StdError.StdError;
+export {};
+//# sourceMappingURL=Exec.d.ts.map

package/dist/esm/internal/Exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exec.d.ts","sourceRoot":"","sources":["../../../src/internal/Exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,mBAAmB,MAAM,oCAAoC,CAAA;AACzE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,0EAAkE,CAAA;AAE5F;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;;;;IAenD,uDAAuD;;;AAbzD;;;;;;;;;GASG;AACH,qBAAa,SAAU,SAAQ,cAK7B;CAAG;AAEL;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;CAClD;AAiJD;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,GACf,SAAS,MAAM,EACf,UAAS,WAAgB,KACxB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,mBAAmB,CAAC,mBAAmB,CAazE,CAAA;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,KAAG,QAAQ,CAAC,IACF,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,OAAO,SAAS,KAAG,QAAQ,CAAC,QAOpE,CAAA"}

package/dist/esm/internal/Exec.js

@@ -0,0 +1,193 @@
+/**
+ * Buffered shell execution over the permission-aware process spawner.
+ *
+ * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a
+ * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with
+ * `ChildProcessSpawner`, Effect's own process boundary, which streams and has
+ * no buffered form. This module is the buffered form the shell flows still
+ * want, expressed in terms of the spawner so the `proc:spawn` capability check
+ * and the command-line resource stay exactly where the kernel put them.
+ *
+ * Commands run through the platform shell (`shell: true`), matching the old
+ * service: the flows take a command *line*, not an argv.
+ *
+ * @since 1.0.0
+ */
+import * as ChildProcessEnvironment from "@smthrs/kernel/ChildProcessEnvironment";
+import * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import * as StdError from "../StdError.js";
+/**
+ * Failure codes a buffered execution can report, matching the codes the
+ * removed kernel `Shell` used so handler-level mapping is unchanged.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const ExecErrorCode = Schema.Literals(["timeout", "spawn_error", "capture_overflow"]);
+/**
+ * A command that never produced an exit code.
+ *
+ * A non-zero exit is a successful {@link ExecResult}, not a failure; this
+ * error is reserved for a command that could not start or was cut off by its
+ * timeout, or whose captured output exceeded a refusing capture bound.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class ExecError extends Schema.TaggedError()("@smthrs/std/ExecError", {
+    code: ExecErrorCode,
+    message: Schema.String,
+    /** The limit a `timeout` ran past, in milliseconds. */
+    limitMillis: Schema.optional(Schema.Number)
+}) {
+}
+const decoder = new TextDecoder("utf-8");
+/**
+ * Joins the retained chunks and decodes them, skipping the partial code point a
+ * dropped head can leave behind.
+ *
+ * A UTF-8 continuation byte is `10xxxxxx`, and a code point is at most four
+ * bytes, so at most three leading continuation bytes can precede the first
+ * whole character. Skipping them is counted as dropped rather than decoded to a
+ * replacement character the process never printed.
+ */
+const decodeTail = (state) => {
+    const bytes = new Uint8Array(state.bytes);
+    let offset = 0;
+    for (const chunk of state.chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    if (state.dropped === 0)
+        return { text: decoder.decode(bytes), droppedBytes: 0 };
+    let start = 0;
+    while (start < bytes.byteLength && start < 3 && (bytes[start] & 0b1100_0000) === 0b1000_0000)
+        start++;
+    return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start };
+};
+const boundedTail = (stream, maxBytes, overflow) => Stream.runFold(stream, () => ({ chunks: [], bytes: 0, dropped: 0 }), (state, chunk) => {
+    if (chunk.byteLength === 0)
+        return state;
+    state.chunks.push(chunk);
+    state.bytes += chunk.byteLength;
+    while (state.bytes > maxBytes && state.chunks.length > 0) {
+        const excess = state.bytes - maxBytes;
+        const first = state.chunks[0];
+        if (first.byteLength <= excess) {
+            state.chunks.shift();
+            state.bytes -= first.byteLength;
+            state.dropped += first.byteLength;
+        }
+        else {
+            state.chunks[0] = first.subarray(excess);
+            state.bytes -= excess;
+            state.dropped += excess;
+        }
+    }
+    return state;
+}).pipe(Effect.map((state) => overflow === "refuse" && state.dropped > 0
+    ? { text: "", droppedBytes: state.dropped }
+    : decodeTail(state)));
+const capture = (stream, maxBytes, overflow) => maxBytes === undefined
+    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))
+    : boundedTail(stream, maxBytes, overflow);
+const unbounded = (command, options) => Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const settings = {
+        ...(options.args === undefined ? { shell: true } : {}),
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env: ChildProcessEnvironment.make(process.env, options.env),
+        extendEnv: false,
+        ...(options.stdin === undefined
+            ? {}
+            : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) })
+    };
+    const handle = yield* spawner.spawn(options.args === undefined
+        ? ChildProcess.make(command, settings)
+        : ChildProcess.make(command, [...options.args], settings));
+    // stdout, stderr, and the exit code have to be consumed concurrently: a
+    // command that fills a pipe blocks until the pipe is drained, so waiting
+    // for exit first would deadlock on any output larger than the buffer.
+    const [stdout, stderr, exitCode] = yield* Effect.all([
+        capture(handle.stdout, options.maxCaptureBytes, options.overflow),
+        capture(handle.stderr, options.maxCaptureBytes, options.overflow),
+        handle.exitCode
+    ], { concurrency: "unbounded" });
+    if (options.overflow === "refuse") {
+        const overflowed = [
+            stdout.droppedBytes > 0 ? "stdout" : undefined,
+            stderr.droppedBytes > 0 ? "stderr" : undefined
+        ]
+            .filter((stream) => stream !== undefined);
+        if (overflowed.length > 0) {
+            return yield* Effect.fail(new ExecError({
+                code: "capture_overflow",
+                message: `${command} ${overflowed.join(" and ")} exceeded the ${options.maxCaptureBytes}-byte capture cap; refusing partial output`
+            }));
+        }
+    }
+    return {
+        stdout: stdout.text,
+        stderr: stderr.text,
+        exitCode,
+        stdoutDroppedBytes: stdout.droppedBytes,
+        stderrDroppedBytes: stderr.droppedBytes
+    };
+}).pipe(Effect.scoped, Effect.mapError((error) => error instanceof ExecError ? error : new ExecError({
+    code: "spawn_error",
+    message: `exec: ${command}: ${error.message}`
+})));
+/**
+ * Runs a command line through the platform shell and buffers its output.
+ *
+ * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber
+ * — including the one a `timeoutMs` interrupts — terminates the process rather
+ * than leaking it.
+ *
+ * @category execution
+ * @since 1.0.0
+ */
+export const exec = (command, options = {}) => options.timeoutMs === undefined
+    ? unbounded(command, options)
+    : Effect.timeoutOrElse(unbounded(command, options), {
+        duration: options.timeoutMs,
+        orElse: () => Effect.fail(new ExecError({
+            code: "timeout",
+            message: `exec: \`${command}\` exceeded ${options.timeoutMs}ms`,
+            limitMillis: options.timeoutMs
+        }))
+    });
+/**
+ * The model-facing failure code a command that never produced an exit code
+ * carries.
+ *
+ * A timeout keeps its own code, because "the command never finished" and "the
+ * command never started" are different things to a caller deciding whether to
+ * retry. Every other way of producing no exit code is a host failure.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const toStdErrorCode = (error) => error.code === "timeout" ? "timeout" : "command_failed";
+/**
+ * The model-facing failure one execution error becomes.
+ *
+ * A timeout names the command, which is what the caller asked for and all a
+ * timeout has to say. Any other failure carries the message the execution
+ * produced, which already names the command.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const toStdError = (command, error) => new StdError.StdError({
+    code: toStdErrorCode(error),
+    message: error.code === "timeout"
+        ? `Command timed out: ${command}`
+        : `Command failed to start: ${error.message}`,
+    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })
+});
+//# sourceMappingURL=Exec.js.map

package/dist/esm/internal/Exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exec.js","sourceRoot":"","sources":["../../../src/internal/Exec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Buffered shell execution over the permission-aware process spawner.\n *\n * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a\n * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with\n * `ChildProcessSpawner`, Effect's own process boundary, which streams and has\n * no buffered form. This module is the buffered form the shell flows still\n * want, expressed in terms of the spawner so the `proc:spawn` capability check\n * and the command-line resource stay exactly where the kernel put them.\n *\n * Commands run through the platform shell (`shell: true`), matching the old\n * service: the flows take a command *line*, not an argv.\n *\n * @since 1.0.0\n */\n\nimport * as ChildProcessEnvironment from \"@smthrs/kernel/ChildProcessEnvironment\"\nimport * as ChildProcessSpawner from \"@smthrs/kernel/ChildProcessSpawner\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as Stream from \"effect/Stream\"\nimport * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport * as StdError from \"../StdError.ts\"\n\n/**\n * Failure codes a buffered execution can report, matching the codes the\n * removed kernel `Shell` used so handler-level mapping is unchanged.\n *\n * @category models\n * @since 1.0.0\n */\nexport const ExecErrorCode = Schema.Literals([\"timeout\", \"spawn_error\", \"capture_overflow\"])\n\n/**\n * Failure codes a buffered execution can report.\n *\n * @category models\n * @since 1.0.0\n */\nexport type ExecErrorCode = typeof ExecErrorCode.Type\n\n/**\n * A command that never produced an exit code.\n *\n * A non-zero exit is a successful {@link ExecResult}, not a failure; this\n * error is reserved for a command that could not start or was cut off by its\n * timeout, or whose captured output exceeded a refusing capture bound.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class ExecError extends Schema.TaggedError<ExecError>()(\"@smthrs/std/ExecError\", {\n  code: ExecErrorCode,\n  message: Schema.String,\n  /** The limit a `timeout` ran past, in milliseconds. */\n  limitMillis: Schema.optional(Schema.Number)\n}) {}\n\n/**\n * The buffered result of one command.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecResult {\n  readonly stdout: string\n  readonly stderr: string\n  readonly exitCode: number\n  /** UTF-8 bytes dropped from the head of stdout to stay inside the capture bound. */\n  readonly stdoutDroppedBytes: number\n  /** UTF-8 bytes dropped from the head of stderr to stay inside the capture bound. */\n  readonly stderrDroppedBytes: number\n}\n\n/**\n * Options accepted by {@link exec}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecOptions {\n  readonly cwd?: string | undefined\n  readonly env?: Readonly<Record<string, string>> | undefined\n  readonly timeoutMs?: number | undefined\n  /**\n   * The program's arguments. Present means an argv, absent means a command\n   * line for the platform shell. An argv is how a payload reaches a program\n   * without being quoted into a string: nothing between here and `execve`\n   * re-parses it.\n   */\n  readonly args?: ReadonlyArray<string> | undefined\n  /**\n   * Text written to the program's standard input, as data. A script delivered\n   * this way is never quoted, escaped, or heredoc-terminated, which is the\n   * whole point: quoting corruption cost the measured SWE-bench program twelve\n   * probe failures and one instance's most expensive frame.\n   */\n  readonly stdin?: string | undefined\n  /**\n   * Bytes retained per captured stream. A stream that prints more keeps its\n   * tail and reports what it dropped, so a command printing gigabytes costs a\n   * bounded amount of memory rather than the whole of what it printed.\n   *\n   * Absent means unbounded, which is what a caller wants when it needs every\n   * byte a tool produced (`rg --files`, `git worktree list`).\n   */\n  readonly maxCaptureBytes?: number | undefined\n  /** Defaults to `tail`; `refuse` fails if either stream exceeds the bound. */\n  readonly overflow?: \"tail\" | \"refuse\" | undefined\n}\n\n/** One captured stream: the text kept, and the bytes dropped to keep it bounded. */\ninterface Capture {\n  readonly text: string\n  readonly droppedBytes: number\n}\n\ninterface Tail {\n  chunks: Array<Uint8Array>\n  bytes: number\n  dropped: number\n}\n\nconst decoder = new TextDecoder(\"utf-8\")\n\n/**\n * Joins the retained chunks and decodes them, skipping the partial code point a\n * dropped head can leave behind.\n *\n * A UTF-8 continuation byte is `10xxxxxx`, and a code point is at most four\n * bytes, so at most three leading continuation bytes can precede the first\n * whole character. Skipping them is counted as dropped rather than decoded to a\n * replacement character the process never printed.\n */\nconst decodeTail = (state: Tail): Capture => {\n  const bytes = new Uint8Array(state.bytes)\n  let offset = 0\n  for (const chunk of state.chunks) {\n    bytes.set(chunk, offset)\n    offset += chunk.byteLength\n  }\n  if (state.dropped === 0) return { text: decoder.decode(bytes), droppedBytes: 0 }\n  let start = 0\n  while (start < bytes.byteLength && start < 3 && (bytes[start]! & 0b1100_0000) === 0b1000_0000) start++\n  return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start }\n}\n\nconst boundedTail = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number,\n  overflow: \"tail\" | \"refuse\" | undefined\n): Effect.Effect<Capture, E> =>\n  Stream.runFold(\n    stream,\n    (): Tail => ({ chunks: [], bytes: 0, dropped: 0 }),\n    (state, chunk) => {\n      if (chunk.byteLength === 0) return state\n      state.chunks.push(chunk)\n      state.bytes += chunk.byteLength\n      while (state.bytes > maxBytes && state.chunks.length > 0) {\n        const excess = state.bytes - maxBytes\n        const first = state.chunks[0]!\n        if (first.byteLength <= excess) {\n          state.chunks.shift()\n          state.bytes -= first.byteLength\n          state.dropped += first.byteLength\n        } else {\n          state.chunks[0] = first.subarray(excess)\n          state.bytes -= excess\n          state.dropped += excess\n        }\n      }\n      return state\n    }\n  ).pipe(Effect.map((state) =>\n    overflow === \"refuse\" && state.dropped > 0\n      ? { text: \"\", droppedBytes: state.dropped }\n      : decodeTail(state)\n  ))\n\nconst capture = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number | undefined,\n  overflow: \"tail\" | \"refuse\" | undefined\n): Effect.Effect<Capture, E> =>\n  maxBytes === undefined\n    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))\n    : boundedTail(stream, maxBytes, overflow)\n\nconst unbounded = (\n  command: string,\n  options: ExecOptions\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n    const settings: ChildProcess.CommandOptions = {\n      ...(options.args === undefined ? { shell: true } : {}),\n      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),\n      env: ChildProcessEnvironment.make(process.env, options.env),\n      extendEnv: false,\n      ...(options.stdin === undefined\n        ? {}\n        : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) })\n    }\n    const handle = yield* spawner.spawn(\n      options.args === undefined\n        ? ChildProcess.make(command, settings)\n        : ChildProcess.make(command, [...options.args], settings)\n    )\n    // stdout, stderr, and the exit code have to be consumed concurrently: a\n    // command that fills a pipe blocks until the pipe is drained, so waiting\n    // for exit first would deadlock on any output larger than the buffer.\n    const [stdout, stderr, exitCode] = yield* Effect.all(\n      [\n        capture(handle.stdout, options.maxCaptureBytes, options.overflow),\n        capture(handle.stderr, options.maxCaptureBytes, options.overflow),\n        handle.exitCode\n      ],\n      { concurrency: \"unbounded\" }\n    )\n    if (options.overflow === \"refuse\") {\n      const overflowed = [\n        stdout.droppedBytes > 0 ? \"stdout\" : undefined,\n        stderr.droppedBytes > 0 ? \"stderr\" : undefined\n      ]\n        .filter((stream): stream is string => stream !== undefined)\n      if (overflowed.length > 0) {\n        return yield* Effect.fail(\n          new ExecError({\n            code: \"capture_overflow\",\n            message: `${command} ${\n              overflowed.join(\" and \")\n            } exceeded the ${options.maxCaptureBytes}-byte capture cap; refusing partial output`\n          })\n        )\n      }\n    }\n    return {\n      stdout: stdout.text,\n      stderr: stderr.text,\n      exitCode,\n      stdoutDroppedBytes: stdout.droppedBytes,\n      stderrDroppedBytes: stderr.droppedBytes\n    }\n  }).pipe(\n    Effect.scoped,\n    Effect.mapError((error) =>\n      error instanceof ExecError ? error : new ExecError({\n        code: \"spawn_error\",\n        message: `exec: ${command}: ${error.message}`\n      })\n    )\n  )\n\n/**\n * Runs a command line through the platform shell and buffers its output.\n *\n * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber\n * — including the one a `timeoutMs` interrupts — terminates the process rather\n * than leaking it.\n *\n * @category execution\n * @since 1.0.0\n */\nexport const exec = (\n  command: string,\n  options: ExecOptions = {}\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  options.timeoutMs === undefined\n    ? unbounded(command, options)\n    : Effect.timeoutOrElse(unbounded(command, options), {\n      duration: options.timeoutMs,\n      orElse: () =>\n        Effect.fail(\n          new ExecError({\n            code: \"timeout\",\n            message: `exec: \\`${command}\\` exceeded ${options.timeoutMs}ms`,\n            limitMillis: options.timeoutMs\n          })\n        )\n    })\n\n/**\n * The model-facing failure code a command that never produced an exit code\n * carries.\n *\n * A timeout keeps its own code, because \"the command never finished\" and \"the\n * command never started\" are different things to a caller deciding whether to\n * retry. Every other way of producing no exit code is a host failure.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdErrorCode = (error: ExecError): StdError.Code =>\n  error.code === \"timeout\" ? \"timeout\" : \"command_failed\"\n\n/**\n * The model-facing failure one execution error becomes.\n *\n * A timeout names the command, which is what the caller asked for and all a\n * timeout has to say. Any other failure carries the message the execution\n * produced, which already names the command.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdError = (command: string, error: ExecError): StdError.StdError =>\n  new StdError.StdError({\n    code: toStdErrorCode(error),\n    message: error.code === \"timeout\"\n      ? `Command timed out: ${command}`\n      : `Command failed to start: ${error.message}`,\n    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })\n  })\n"]}