@tangle-network/agent-eval 0.172.1 → 0.173.0

package/dist/types-gvRsyJLh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-gvRsyJLh.d.ts","names":[],"sources":["../src/judge-families.ts","../src/integrity/served-model.ts","../src/trace/raw-provider-sink.ts","../src/llm-client.ts","../src/analyst/chat-client.ts","../src/types.ts"],"mappings":"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"}

package/dist/wire/index.d.ts

@@ -1,7 +1,7 @@
 import { b as CustomTokenPricing, c as CostLedgerHandle } from "../cost-ledger-DbQdN3nO.js";
-import { p as ChatClient } from "../types-Bfk0uxRj.js";
-import { s as TraceStore } from "../store-Cq9oOrI1.js";
-import { m as FeedbackTrajectoryStore } from "../feedback-trajectory-DIqpCyF0.js";
+import { p as ChatClient } from "../types-gvRsyJLh.js";
+import { s as TraceStore } from "../store-BErPvYBr.js";
+import { m as FeedbackTrajectoryStore } from "../feedback-trajectory-CMnv_uYs.js";
 import { z } from "zod";
 import { ServerType } from "@hono/node-server";
 import { Hono } from "hono";

package/dist/wire/index.js

@@ -1,2 +1,2 @@
-import { A as WIRE_VERSION, C as RUBRIC_VERSION_SCHEME, D as TracesIngestRequestSchema, E as TraceEventSchema, O as TracesIngestResponseSchema, S as ListRubricsResponseSchema, T as RubricSchema, _ as FeedbackIngestResponseSchema, a as runRpcBatch, b as JudgeRequestSchema, c as WireError, d as handleListRubrics, f as handleTracesIngest, g as ErrorResponseSchema, h as listBuiltinRubrics, i as dispatchRpc, j as hashRubric, k as VersionResponseSchema, l as handleFeedbackIngest, m as getBuiltinRubric, n as startServer, o as runRpcOnce, p as handleVersion, r as startServerAsync, s as buildOpenApi, t as createApp, u as handleJudge, v as FeedbackTrajectorySchema, w as RubricDimensionSchema, x as JudgeResultSchema, y as HealthResponseSchema } from "../server-CCEnywOR.js";
+import { A as WIRE_VERSION, C as RUBRIC_VERSION_SCHEME, D as TracesIngestRequestSchema, E as TraceEventSchema, O as TracesIngestResponseSchema, S as ListRubricsResponseSchema, T as RubricSchema, _ as FeedbackIngestResponseSchema, a as runRpcBatch, b as JudgeRequestSchema, c as WireError, d as handleListRubrics, f as handleTracesIngest, g as ErrorResponseSchema, h as listBuiltinRubrics, i as dispatchRpc, j as hashRubric, k as VersionResponseSchema, l as handleFeedbackIngest, m as getBuiltinRubric, n as startServer, o as runRpcOnce, p as handleVersion, r as startServerAsync, s as buildOpenApi, t as createApp, u as handleJudge, v as FeedbackTrajectorySchema, w as RubricDimensionSchema, x as JudgeResultSchema, y as HealthResponseSchema } from "../server-BR6onwZB.js";
 export { ErrorResponseSchema, FeedbackIngestResponseSchema, FeedbackTrajectorySchema, HealthResponseSchema, JudgeRequestSchema, JudgeResultSchema, ListRubricsResponseSchema, RUBRIC_VERSION_SCHEME, RubricDimensionSchema, RubricSchema, TraceEventSchema, TracesIngestRequestSchema, TracesIngestResponseSchema, VersionResponseSchema, WIRE_VERSION, WireError, buildOpenApi, createApp, dispatchRpc, getBuiltinRubric, handleFeedbackIngest, handleJudge, handleListRubrics, handleTracesIngest, handleVersion, hashRubric, listBuiltinRubrics, runRpcBatch, runRpcOnce, startServer, startServerAsync };

package/docs/plants.md

@@ -49,6 +49,74 @@ const report = catchRate(results, manifest)
 | `missingIds` | Every plant id with no result at all. |
 | `unseeded` | How the same grader treated the rest of the set. |
 
+## Authoring the wrong item
+
+`definePlant` takes an item that is already wrong.
+It never derives a wrong item from a right one, so every caller used to hand-roll the perturbation.
+That is where the measurement breaks quietly.
+
+`plantByPerturbation` is the authoring step.
+Give it a claim a grader **verified** and it alters exactly one load-bearing value in the claim's evidence, so the grader is asked a question it must fail.
+
+```ts
+import { catchRate, plantByPerturbation, seedPlants } from '@tangle-network/agent-eval/meta-eval'
+
+const derived = plantByPerturbation({
+  id: 'plant-throughput',
+  itemId: 'claim-118-plant',
+  evidence: { check: 'test "$rows" -ge 100', expect: 'rows=42' },
+})
+
+// derived.plant     — a `wrong-value` plant the grader owes a `reject`
+// derived.evidence  — { check: 'test "$rows" -ge 100', expect: 'rows=43' }
+// derived.field     — 'expect'
+// derived.how       — 'number-off-by-one'
+// derived.original  — '42'
+// derived.perturbed — '43'
+
+const { items, manifest } = seedPlants(dataset, [derived.plant], { seed: 7 })
+```
+
+Write `derived.evidence` into the item the grader is handed; `derived.plant` goes into the manifest and nowhere the grader can read.
+`humanScore` defaults to 0 and must sit below the run's accept threshold, or `definePlant` refuses the record.
+The call returns `null` when nothing in the evidence can be perturbed — a claim with no executable evidence cannot be made wrong in a way a grader could execute, and seeding it would measure prose.
+
+`perturbEvidence` is the same rule without the plant record, for callers that already own their item type.
+
+### One value changes, and which one is a safety order
+
+A perturbation that moves two values does not name the defect it seeded, so exactly one changes or the call returns `null`.
+The order below is the order of preference, and it is ranked by how likely the change is to keep the check **executing**.
+
+| Rank | Change | Why it sits here |
+| --- | --- | --- |
+| 1 | The last standalone number in `expect` | It falsifies the claim while the command runs exactly as it did. |
+| 2 | A flipped comparison in `check` | It inverts a test that was passing. |
+| 3 | The last standalone number in `check` | Last: a number in a command can name an input — a port, a width, a version — rather than a threshold, and renaming an input breaks execution, not the claim. |
+
+The **last** match is taken because a measured value trails its label (`count=42`, `n>=5 OK cells=8`), and because the choice must be deterministic: the same claim has to yield the same plant, or two runs of the authoring step seed two different answer keys for one item.
+
+### The identity-number defect
+
+"Standalone" excludes a digit run glued to a word, a dot, a slash, or a hyphen.
+
+| Not perturbed | What a bump would do |
+| --- | --- |
+| `python3` | Names a program that is not installed. |
+| `file42.txt` | Names a file that does not exist. |
+| `1.5` | Rewrites one side of a decimal into a different literal. |
+| `utf-8` | Names an encoding that does not exist. |
+
+Each of those stops the check **executing**.
+The plant then measures the environment rather than the grader: it reads as caught, for a reason that has nothing to do with the seeded defect.
+That is the failure this helper exists to prevent, and it is asserted directly in `src/meta-eval/plants.test.ts`.
+
+Only unambiguous comparison tokens flip — ` -ge `/` -lt `, ` -gt `/` -le `, ` -le `/` -gt `, ` -lt `/` -ge `, ` -eq `/` -ne `, ` -ne `/` -eq `, `>=`/`<`, `<=`/`>`, `==`/`!=`, `!=`/`==`.
+A bare `>` or `<` is a shell redirection, never a comparison, so flipping it would rewrite where output goes rather than what the test asks.
+
+A number is bumped with `BigInt`, so a value wider than `Number.MAX_SAFE_INTEGER` moves by exactly one.
+Bumped as a `number` it rounds back onto itself, and the plant is then a correct claim the grader is right to verify.
+
 ## What each call composes
 
 Plants add no parallel calibration machinery.
@@ -73,7 +141,7 @@ It changes nothing about how the item is graded; it exists so `byKind` can show
 
 | Kind | Authored by |
 | --- | --- |
-| `wrong-value` | Altering one load-bearing value: a number off by one, a comparison flipped. |
+| `wrong-value` | Altering one load-bearing value: a number off by one, a comparison flipped. `plantByPerturbation` authors this kind. |
 | `self-certifying` | Giving the item a check that passes without testing the claim. |
 | `unreachable-input` | Pointing the check at an input that does not exist, so it cannot run at all. |
 | `duplicate` | Copying an item already in the set, which is owed a duplicate flag rather than a second grade. |

package/docs/public-api.md

@@ -7,10 +7,10 @@ Generated by `pnpm api:census` on demand — this is a dated reading, not a gate
 | measure | count |
 | --- | --- |
 | export subpaths | 28 |
-| published value exports (subpath x symbol) | 1378 |
-| distinct symbols | 1209 |
+| published value exports (subpath x symbol) | 1380 |
+| distinct symbols | 1211 |
 | production | 931 |
-| planned | 216 |
+| planned | 218 |
 | none | 231 |
 
 Type-only exports are not listed: a type binds no runtime surface, and removing one cannot break a caller at run time.
@@ -974,7 +974,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 ### `./meta-eval`
 
-16 value exports — 10 production, 4 planned, 2 none.
+18 value exports — 10 production, 6 planned, 2 none.
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
@@ -988,6 +988,8 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `InMemoryOutcomeStore` | planned | consumer tests: phony:products/builder/api/src/eval/outcomes-correlate.test.ts |
 | `inMemorySentinelStore` | none | only this package's tests: tests/judge-sentinel.test.ts:7 |
 | `judgeSentinelReport` | production | creative-agent:eval/lib/judge-sentinel.ts |
+| `perturbEvidence` | planned | doc: docs/plants.md |
+| `plantByPerturbation` | planned | doc: README.md |
 | `rubricPredictiveValidity` | production | physim:apps/server/src/scripts/agent-eval/validate-rubrics.ts |
 | `seedPlants` | planned | doc: README.md |
 | `snapshotFromAgreement` | production | physim:apps/server/src/scripts/agent-eval/judge-sentinel.ts |

package/docs/trace-analysis.md

@@ -13,28 +13,71 @@ Agent Eval separates five concerns:
 | Finding | Records one structured claim with exact evidence |
 | Analysis result | Returns the prose answer, findings, investigation steps, model calls, tool calls, and runtime |
 
-The built-in model-backed analysts use the official DSPy `RLM`.
-DSPy runs the research loop and a sandboxed Python interpreter.
-Agent Eval owns trace access, cancellation, cost accounting, and output validation.
-The calling application owns model execution, credentials, retries, and provider policy.
+Two engines ship, and an analyst definition runs on either without change.
+`createChatTraceEngine` runs the research loop in Node over a caller-owned `ChatClient`.
+`createDspyRlmTraceEngine` runs it in the official DSPy `RLM`, which brings a sandboxed Python interpreter.
+Choose the Node engine unless the question needs the interpreter; it needs no Python install.
+Agent Eval owns trace access, cancellation, cost accounting, and output validation in both.
+The calling application owns model execution, credentials, retries, and provider policy in both.
 
 `createPublicBenchmarkDirectRunner()` is the direct-call baseline; it runs through the loopback model proxy against a caller-owned execution owner, so agent-eval issues no provider request.
 They are not trace analysts.
 
 ## Install
 
-Install the TypeScript package and the matching Python package with DSPy:
+The Node engine needs the TypeScript package alone:
 
 ```sh
 pnpm add @tangle-network/agent-eval
+```
+
+The DSPy engine also needs the matching Python package:
+
+```sh
 python -m venv .venv
 .venv/bin/pip install "agent-eval-rpc[dspy]"
 ```
 
 The Python extra pins the tested stable DSPy and Deno versions.
 
+## Build An Engine Without Python
+
+`createChatTraceEngine` binds the transport the application already owns.
+It offers the analyst's trace tools as native function calls, loops until the model answers with no tool call or a budget is spent, then takes one report turn that returns the answer and the findings.
+Findings pass through the same decoder the DSPy engine uses, so both engines accept the same rows.
+
+```ts
+import {
+  createChatClient,
+  createChatTraceEngine,
+} from '@tangle-network/agent-eval/analyst'
+
+const engine = createChatTraceEngine({
+  chat: createChatClient({
+    transport: 'custom',
+    // The application reaches the provider. Agent Eval never holds the key.
+    chat: (request, options) => callMyProvider(request, options),
+    defaultModel: 'deepseek-v4-flash',
+    maximumAttempts: 3,
+  }),
+  pricing: {
+    inputUsdPerMillion: 3,
+    outputUsdPerMillion: 15,
+  },
+})
+```
+
+`maximumAttempts` states how many provider attempts one call can make.
+A capped cost ledger reserves for all of them before the call runs, so an omitted value under-reserves.
+
+Every call is metered on the shared cost ledger.
+The result's `runtime.served_models` carries the model ids the provider echoed, because a gateway can accept one model id and answer from another on HTTP 200.
+An analyst's `maxLlmCalls` must be at least 2, because this engine spends one call on the report turn.
+
 ## Answer One Question
 
+This example uses the DSPy engine; substitute the engine above to drop Python.
+
 ```ts
 import {
   createDspyRlmTraceEngine,
@@ -92,7 +135,7 @@ Each trace read also crosses an authenticated loopback callback and counts again
 ## Define A Reusable Analyst
 
 An analyst definition contains no model, credentials, or execution state.
-The same definition can run with DSPy or another engine that implements `TraceAnalysisEngine`.
+The same definition runs on either shipped engine, or on any other that implements `TraceAnalysisEngine`.
 
 ```ts
 import {
@@ -141,13 +184,17 @@ Keep exact trace facts in deterministic tools or checks.
 ## Run The Built-In Set
 
 The default registry always includes deterministic behavior checks.
-It adds the four recursive analysts only when an engine is supplied:
+It adds the five recursive analysts only when an engine is supplied:
 
 - `failure-mode`
+- `intent-divergence`
 - `knowledge-gap`
 - `knowledge-poisoning`
 - `improvement`
 
+Either engine satisfies this.
+`agent-runtime`'s `analystsFromRegistry` refuses a registry that is missing one of the five, so a registry built with no engine cannot reach a supervised run.
+
 ```ts
 import {
   buildDefaultAnalystRegistry,
@@ -164,7 +211,7 @@ for (const finding of run.findings) {
 `run.per_analyst` records each analyst's status, latency, calls, tokens, and cost.
 One analyst failure does not become an agent failure.
 
-Pass `definitions` to replace the four built-ins.
+Pass `definitions` to replace the five built-ins.
 Omit `engine` for deterministic-only analysis.
 
 ## Trace Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-eval",
-  "version": "0.172.1",
+  "version": "0.173.0",
   "description": "Evaluate and improve AI agents from runs, traces, judges, and feedback. Compare candidates, cluster failures, measure lift, and gate releases.",
   "homepage": "https://github.com/tangle-network/agent-eval#readme",
   "repository": {

package/dist/backend-integrity-e79K3UPD.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"backend-integrity-e79K3UPD.d.ts","names":[],"sources":["../src/artifact-validator.ts","../src/completion-verifier.ts","../src/produced-state.ts","../src/integrity/backend-integrity.ts"],"mappings":";;;;;;;;;;;;;;;;;;;UAaiB;;EAEf;;EAEA;;EAEA;;EAEA,QAAQ;;EAER,WAAW;;;;;KCsBD;UAEK;;EAEf;;EAEA;;EAEA;;EAEA,cAAc;;UAGC;EACf;EACA,cAAc;;UAGC;EACf;EACA;EACA;;EAEA;;;UAIe;;EAEf,WAAW;;EAEX,WAAW;;EAEX;;UAGe;EACf;EACA;;EAEA;;;;;;EAMA;;EAEA;;;;;;;;;EASA;;EAEA;;EAEA;;;;;UAMe,0BAA0B;EACzC;EACA,cAAc;;EAEd;;EAEA;;EAEA;;;;;;;;;iBAUc,kBAAkB;EAChC;EACA,cAAc;;;EAGd,gBAAgB;IACd;;;;;;UAqCa;EACf,UAAU;EACV,SAAS;EACT;;;;;;;;;;;;UAae;GAEb,aAAa,uBACb,kBACC;IAAU;IAAkB;;EAC/B,cAAc;;;;;;;;;iBAsLM,iBACpB,MAAM,UACN,OAAO,eACP,kBAAkB,qBACjB,QAAQ;UAyGM;EACf;;EAEA,aAAa;EACb;EACA,WAAW;EACX,SAAS;;EAET;;;;;;EAMA;;;;;;EAMA,UAAU;;;;;;;;iBA2CI,4BACd,MAAM,YACN,OAAM,4BACL;;;;UCnhBc;EACf;EACA;;;;;;;UAQe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA;EACA;EAIA;;;;;;;;KASU,mBACR,oBACA,oBACA;EACE;;;;;;;;;;;;iBAmBU,qBAAqB,iBAAiB,qBAAqB;;;UCpD1D;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;cAQW,8BAA8B;WAGvB,QAAQ;EAF1B,YACE,iBACgB,QAAQ;;;;;;;iBAWZ,0BACd,SAAS,cAAc,aACtB;;;;;;;;iBAuHa,kBACd,SAAS,cAAc,YACvB;EAAQ;IACP"}

package/dist/bounded-process-VIi0KSL2.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"bounded-process-VIi0KSL2.js","names":[],"sources":["../src/bounded-process.ts"],"sourcesContent":["/**\n * `runBoundedProcess` — run one command under a wall-clock bound and return\n * what it produced, leaving no descendant behind.\n *\n * The child leads its own process group (`detached` on every non-win32\n * platform), so a deadline or an abort kills the group with\n * `process.kill(-pid, 'SIGKILL')` rather than only the shell that was\n * spawned. That distinction is the whole point of this module: `sh -c\n * 'solver & wait'` puts the real work in a grandchild, and a kill aimed at\n * the shell alone leaves that grandchild running, holding the stdout and\n * stderr pipes open. `close` then never fires, so the deadline produces no\n * result the caller can observe and the descendant outlives the run.\n *\n * Two further guarantees the caller depends on:\n *\n *   - A killed run never reports success. A SIGKILLed child can still close\n *     with exit code 0, so a run killed by the deadline or by an abort has\n *     its exit code forced non-zero.\n *   - A run always resolves. If a grandchild escaped the group and still\n *     holds the pipes, the result is delivered {@link KILL_DRAIN_MS} after\n *     the kill instead of waiting on a `close` that will not come.\n *\n * The captured output is bounded. Once the cap is reached the streams are\n * still drained — the child needs its pipes read to reach `close` — but the\n * bytes are discarded and `outputTruncated` is set.\n */\n\nimport { spawn } from 'node:child_process'\n\n/** Wall-clock bound applied when the caller names none. */\nconst DEFAULT_TIMEOUT_MS = 10 * 60_000\n\n/** Cap on captured stdout+stderr applied when the caller names none. */\nconst DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024\n\n/**\n * Window `close` is given after the process group is killed. A grandchild\n * that escaped the group can hold the pipes open indefinitely; the caller\n * receives its result at the end of this window rather than hanging.\n */\nconst KILL_DRAIN_MS = 2000\n\n/** Exit code reported for a run the wall-clock bound killed (GNU `timeout`). */\nconst TIMEOUT_EXIT_CODE = 124\n\n/** Exit code reported for a run an `AbortSignal` killed (128 + SIGKILL). */\nconst ABORT_EXIT_CODE = 137\n\n/** Exit code reported when the process could not be spawned at all. */\nconst SPAWN_FAILURE_EXIT_CODE = 127\n\n/** Exit code reported when a process closed with no code and was not killed. */\nconst UNKNOWN_EXIT_CODE = 1\n\nexport interface BoundedProcessInput {\n  /**\n   * The command line, interpreted by a shell unless `shell` is `false`. When\n   * {@link BoundedProcessInput.args} is present this is a program path\n   * instead, and no shell reads it.\n   */\n  command: string\n  /**\n   * Argument vector for `command`, delivered to the program as separate\n   * argv entries with no shell between them.\n   *\n   * This is the form to use whenever an argument carries text the caller did\n   * not author — a script body, a path, a pattern. Without it, `interpreter\n   * -flag <script>` can only be expressed by quoting the script into a\n   * shell string, and a quoting bug there is a command injection rather than\n   * a wrong answer. Each entry arrives verbatim, so there is nothing to\n   * quote: `{ command: 'bash', args: ['-n', '-c', body] }` parses `body`\n   * whatever shell metacharacters it holds.\n   *\n   * Two limits are the platform's, not this module's. A NUL byte in an entry\n   * cannot be passed to a process at all, and is reported as a `runnerError`\n   * rather than thrown. A lone surrogate is encoded to UTF-8 as U+FFFD, and a\n   * non-string entry from an untypechecked caller is coerced with `String()`,\n   * so an entry is verbatim exactly when it is a string a UTF-8 argv can hold.\n   *\n   * A shell cannot interpret an argument vector, so `args` and a truthy\n   * `shell` are contradictory. Passing both spawns nothing and reports\n   * `runnerError`.\n   */\n  args?: string[]\n  /**\n   * Shell that interprets `command`. `true` (the default) uses the platform\n   * default — `/bin/sh` on POSIX, `cmd.exe` on Windows. A string names the\n   * shell binary, e.g. `'bash'`, which is required for a bash-only construct\n   * such as `[[ ]]` or `$BASH_VERSION`. `false` executes `command` directly\n   * as a program path with no arguments. Ignored — and refused when truthy —\n   * once {@link BoundedProcessInput.args} is present.\n   */\n  shell?: boolean | string\n  /** Working directory. The parent's cwd is inherited when omitted. */\n  cwd?: string\n  /**\n   * Environment for the child. How it combines with the parent environment\n   * is decided by {@link BoundedProcessInput.envMode}.\n   */\n  env?: NodeJS.ProcessEnv\n  /**\n   * `'merge'` (the default) layers `env` on top of `process.env`, so the\n   * child sees every variable this process has plus the named ones.\n   * `'replace'` passes exactly `env` and nothing else, which is what a\n   * grader needs when the claim under test is about the variables the\n   * command could read. `PATH` is not re-added under `'replace'`, and a\n   * command that must find a binary on `PATH` names `PATH` itself.\n   *\n   * With no `PATH` in the child environment the two forms do NOT search the\n   * same directories, so a caller under `'replace'` that names no `PATH` gets\n   * a resolution that depends on which form it picked. The shell form execs\n   * the shell, which applies its own compiled-in default; the argv form\n   * reaches `execvp`, which falls back to `confstr(_CS_PATH)`. Measured on\n   * Linux/glibc: `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`\n   * against `/bin:/usr/bin`, so a binary in `/usr/local/bin` resolves on the\n   * shell form and reports ENOENT on the argv form. Name `PATH` and both\n   * forms search exactly what was named.\n   */\n  envMode?: 'merge' | 'replace'\n  /** Wall-clock bound in ms. Defaults to 10 minutes. */\n  timeoutMs?: number\n  /**\n   * Cap on captured stdout+stderr. Reaching it truncates the captured text\n   * and sets `outputTruncated`; it never kills the process. Defaults to\n   * 16 MiB.\n   */\n  maxOutputBytes?: number\n  /**\n   * Kills the process group when it aborts, the same way the deadline does.\n   * A signal that is already aborted when `runBoundedProcess` is called\n   * prevents the spawn entirely — nothing runs.\n   */\n  signal?: AbortSignal\n}\n\nexport interface BoundedProcessResult {\n  /**\n   * Exit code. Forced non-zero whenever `killedByTimeout` or\n   * `killedBySignal` is set, because a SIGKILLed child can close with 0 and\n   * a killed run must never read as a pass.\n   */\n  exitCode: number\n  /** Captured stdout, truncated at `maxOutputBytes`. */\n  stdout: string\n  /**\n   * Captured stderr, truncated at `maxOutputBytes`. A runner-side failure is\n   * reported in `runnerError`, not appended here; the caller decides whether\n   * the command's own stderr and the runner's diagnosis belong together.\n   */\n  stderr: string\n  /** Wall-clock duration in ms, measured across the whole call. */\n  wallMs: number\n  /** The wall-clock bound was reached and the process group was killed. */\n  killedByTimeout: boolean\n  /** `signal` aborted and the process group was killed. */\n  killedBySignal: boolean\n  /** `maxOutputBytes` was reached and later output was discarded. */\n  outputTruncated: boolean\n  /**\n   * Runner-side failure: the process could not be spawned, or the signal was\n   * already aborted so nothing was spawned. Absent when the command itself\n   * ran, however it exited.\n   */\n  runnerError?: string\n}\n\nexport async function runBoundedProcess(input: BoundedProcessInput): Promise<BoundedProcessResult> {\n  const start = Date.now()\n  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES\n  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS\n  const envMode = input.envMode ?? 'merge'\n  const env =\n    input.env === undefined && envMode === 'merge'\n      ? undefined\n      : envMode === 'replace'\n        ? { ...input.env }\n        : { ...process.env, ...input.env }\n\n  if (input.signal?.aborted) {\n    return {\n      exitCode: ABORT_EXIT_CODE,\n      stdout: '',\n      stderr: '',\n      wallMs: Date.now() - start,\n      killedByTimeout: false,\n      killedBySignal: true,\n      outputTruncated: false,\n      runnerError: 'aborted before spawn: the AbortSignal was already aborted',\n    }\n  }\n\n  // Reported rather than thrown, because this module's contract is that a\n  // call always resolves. A caller bug still reads as a failure and never as\n  // a pass: the exit code is non-zero and `runnerError` names the cause.\n  if (input.args !== undefined && input.shell) {\n    return {\n      exitCode: SPAWN_FAILURE_EXIT_CODE,\n      stdout: '',\n      stderr: '',\n      wallMs: Date.now() - start,\n      killedByTimeout: false,\n      killedBySignal: false,\n      outputTruncated: false,\n      // Shares `SPAWN_FAILURE_EXIT_CODE` with a program that does not exist,\n      // because both mean nothing ran. The `not spawned:` prefix is the stable\n      // discriminator: it marks the caller's own bug, which no retry fixes.\n      runnerError:\n        'not spawned: `args` passes an argument vector directly to the program, so a shell ' +\n        'cannot interpret it — pass `args` or a truthy `shell`, never both',\n    }\n  }\n\n  return await new Promise<BoundedProcessResult>((resolve) => {\n    const spawnOptions = {\n      cwd: input.cwd,\n      env,\n      // Own process group so a kill reaches the whole tree, not just the\n      // shell — otherwise a runaway grandchild keeps the pipes open and\n      // `close` never fires.\n      detached: process.platform !== 'win32',\n    }\n    // The argv form takes the same bounds, the same group and the same kill\n    // path. Two things differ, and both are stated where they are decided:\n    // no shell reads the command, and executable lookup falls back to a\n    // different default `PATH` when the caller names none (see `envMode`).\n    //\n    // `spawn` validates its arguments and THROWS synchronously — a NUL byte in\n    // `command` or in an `args` entry, or an `args` that is not an array from\n    // an untypechecked caller. A throw inside this executor would reject, and\n    // this module's contract is that a call always resolves. A caller that\n    // grades untrusted text must be able to score that text as failed rather\n    // than die on it.\n    let child: ReturnType<typeof spawn>\n    try {\n      child =\n        input.args === undefined\n          ? spawn(input.command, { ...spawnOptions, shell: input.shell ?? true })\n          : spawn(input.command, input.args, { ...spawnOptions, shell: false })\n    } catch (err) {\n      resolve({\n        exitCode: SPAWN_FAILURE_EXIT_CODE,\n        stdout: '',\n        stderr: '',\n        wallMs: Date.now() - start,\n        killedByTimeout: false,\n        killedBySignal: false,\n        outputTruncated: false,\n        runnerError: String(err),\n      })\n      return\n    }\n    let stdout = ''\n    let stderr = ''\n    let outputBytes = 0\n    let outputTruncated = false\n    let killedByTimeout = false\n    let killedBySignal = false\n    let settled = false\n\n    // Bound the in-memory buffer so a runaway process can't OOM the caller.\n    // Once the cap is hit the streams are still drained (the child needs them\n    // read to reach `close`) but the bytes are discarded.\n    function capture(s: string): string {\n      if (outputBytes >= maxOutputBytes) {\n        outputTruncated = true\n        return ''\n      }\n      const room = maxOutputBytes - outputBytes\n      if (s.length > room) {\n        outputBytes = maxOutputBytes\n        outputTruncated = true\n        return s.slice(0, room)\n      }\n      outputBytes += s.length\n      return s\n    }\n\n    const onStdout = (d: unknown) => {\n      const chunk = capture(String(d))\n      if (chunk) stdout += chunk\n    }\n    const onStderr = (d: unknown) => {\n      const chunk = capture(String(d))\n      if (chunk) stderr += chunk\n    }\n\n    child.stdout?.on('data', onStdout)\n    child.stderr?.on('data', onStderr)\n\n    let forceResolve: ReturnType<typeof setTimeout> | undefined\n\n    const cleanup = () => {\n      clearTimeout(timeout)\n      if (forceResolve) clearTimeout(forceResolve)\n      input.signal?.removeEventListener('abort', onAbort)\n      child.stdout?.off('data', onStdout)\n      child.stderr?.off('data', onStderr)\n      child.removeAllListeners('close')\n      child.removeAllListeners('error')\n    }\n\n    // Resolve exactly once. `code` comes from `close`; on a kill path the\n    // exit code is forced non-zero so a SIGKILLed child that reports 0 can\n    // never read as a clean pass downstream.\n    const finish = (outcome: { code: number | null; runnerError?: string }) => {\n      if (settled) return\n      settled = true\n      cleanup()\n      resolve({\n        exitCode: exitCodeFor(outcome.code, killedByTimeout, killedBySignal),\n        stdout,\n        stderr,\n        wallMs: Date.now() - start,\n        killedByTimeout,\n        killedBySignal,\n        outputTruncated,\n        runnerError: outcome.runnerError,\n      })\n    }\n\n    // SIGKILL the whole process group (we spawned detached). On a clean close\n    // this never runs.\n    const killTree = () => {\n      try {\n        if (process.platform !== 'win32' && typeof child.pid === 'number') {\n          process.kill(-child.pid, 'SIGKILL')\n        } else {\n          child.kill('SIGKILL')\n        }\n      } catch (err) {\n        // ESRCH means the group exited between the decision to kill and the\n        // signal, which `close` reports on its own. Anything else means the\n        // group may still be running, which the caller must hear about.\n        if ((err as NodeJS.ErrnoException)?.code !== 'ESRCH') {\n          console.warn('[bounded-process] SIGKILL of the process group failed:', err)\n        }\n      }\n    }\n\n    // Give `close` a brief window to fire (flushing any final output) after\n    // the group dies; if an orphaned grandchild keeps the pipes open, resolve\n    // anyway so the caller can't hang on a runaway. The deadline and an abort\n    // can both fire, so the kill happens at most once and the drain window is\n    // not restarted by the second one.\n    let killed = false\n    const killAndDrain = () => {\n      if (killed) return\n      killed = true\n      killTree()\n      forceResolve = setTimeout(() => finish({ code: null }), KILL_DRAIN_MS)\n    }\n\n    function onAbort() {\n      if (settled) return\n      killedBySignal = true\n      killAndDrain()\n    }\n\n    const timeout = setTimeout(() => {\n      killedByTimeout = true\n      killAndDrain()\n    }, timeoutMs)\n\n    input.signal?.addEventListener('abort', onAbort, { once: true })\n\n    child.on('close', (code) => {\n      if (forceResolve) clearTimeout(forceResolve)\n      finish({ code })\n    })\n    child.on('error', (err) => {\n      if (forceResolve) clearTimeout(forceResolve)\n      finish({ code: SPAWN_FAILURE_EXIT_CODE, runnerError: String(err) })\n    })\n  })\n}\n\n/**\n * A killed run reports the code the child closed with only when that code is\n * already non-zero; otherwise it reports the conventional code for the kind\n * of kill. A run that closed on its own with no code at all reports 1.\n */\nfunction exitCodeFor(\n  code: number | null,\n  killedByTimeout: boolean,\n  killedBySignal: boolean,\n): number {\n  if (code !== null && code !== 0) return code\n  if (killedByTimeout) return TIMEOUT_EXIT_CODE\n  if (killedBySignal) return ABORT_EXIT_CODE\n  return code ?? UNKNOWN_EXIT_CODE\n}\n"],"mappings":"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"}