@namzu/sdk 5.0.0 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,468 @@
 # Changelog
 
+## 5.2.0
+
+### Minor Changes
+
+- 604a56a: completed is not succeeded — run_completed says why it stopped, and namzu run exits accordingly
+
+  `run_failed` is emitted from exactly one place in the kernel: the throw path.
+  Every other way a run can end badly arrives as `run_completed` — the token
+  budget, the timeout, the iteration cap, a cancellation, a rejected plan, a
+  refused structured output, and both guardrails.
+
+  Measured: a `max_iterations` stop reports `status: 'completed'`, and the event
+  carried nothing that distinguished it from an answered question.
+
+  **SDK.** `run_completed` now carries `stopReason`. It is optional and additive,
+  so nothing breaks; a consumer that wants to tell "answered" from "ran out of
+  budget" no longer has to hold the `Run` alongside the event stream.
+
+  **CLI — read this before upgrading if you script `namzu run`.** The command
+  exited `0` for all of those. The sharp case is the output guardrail: an answer
+  that was _refused_ exited `0` with empty text, so
+
+  ```sh
+  namzu run "write the release notes" > notes.md && publish notes.md
+  ```
+
+  published an empty file and reported success. `namzu run` now exits `1` when
+  the run did not finish normally, and names the reason on stderr. The text still
+  prints — partial output is real output, and a caller who piped it wants what
+  there is — but `$?` can now say it is partial.
+
+  If you have a script that depends on `namzu run` exiting 0 for a truncated run,
+  it was depending on not being told. Check `$?` and read the stderr line.
+
+  Also in the CLI, internally: the `done` agent event's `finishReason?: string`
+  had no producer and no reader anywhere in the package, and the name belonged to
+  a different concept — a "finish reason" here is `MessageStopReason`, reported
+  per model message, not the run-level `StopReason` a caller asks about at the end
+  of a turn. Replaced by `stopReason`. The type is not exported from the package
+  entry, so this is internal.
+
+- f25ebce: a model id's date suffix is no longer read as its minor version
+
+  Three copies of one regular expression matched Claude model ids — the capability
+  table plus two drivers — and all three had the same defect: the minor-version
+  group was `(\d+)`, which swallowed the 8-digit date suffix.
+
+  Measured against the shipped pattern:
+
+  ```
+  claude-sonnet-4-20250514   ->  major=4  minor=20250514
+  claude-opus-4-1-20250805   ->  major=4  minor=1
+  ```
+
+  So a dated id naming no minor version compared as enormously _newer_ than one
+  that does, and every capability gate keyed on `minor >= n` inverted for exactly
+  those ids. `claude-sonnet-4-20250514` was classified as a 4.7+ model: the driver
+  sent it `thinking: {type: 'adaptive'}`, silently discarding a caller's
+  `budgetTokens`, and cleared the 4.5 gate that enables strict tool inputs.
+
+  `parseClaudeModelVersion` and `claudeVersionAtLeast` are now exported from
+  `@namzu/sdk` and used by both drivers and the capability table. A real minor
+  version is one to three digits; a date is eight, and the group is bounded
+  accordingly. An id the parser does not recognise makes `claudeVersionAtLeast`
+  return `false` — a capability gate must not open for a name it does not
+  understand.
+
+  The comment above the old parser warned that "a second, subtly different model
+  matcher is how two capability decisions drift apart on the same model name."
+  There were three.
+
+- 5496fb2: the agent-directory loader is part of the SDK
+
+  It shipped briefly as a separate package. The name was the tell: nothing fit.
+  `project` collided with `ProjectId`, the tenancy bucket every run already
+  carries, and it described a scope that no longer existed once `channels/` and
+  `schedules/` were cut. `agent-dir` was a hyphenated abbreviation, out of family
+  with `skills`, `plugin`, `registry`, `sandbox`.
+
+  A directory reader that needs the kernel to be useful is a function of the
+  kernel, not a product beside it. So it is one now:
+
+  ```ts
+  import { loadDirectory, deriveRunOptions, runAgent } from "@namzu/sdk";
+
+  const { manifest, ok, diagnostics } = await loadDirectory("./agent");
+  if (!ok) console.error(diagnostics);
+
+  const { output } = await runAgent(
+    deriveRunOptions(manifest, { provider, prompt: "What is the weather?" })
+  );
+  ```
+
+  Nothing about the convention changed — the same `agent.ts`, `instructions.md`,
+  `tools/`, `skills/`, `agents/` layout, the same `modules: 'skip'` mode, the same
+  diagnostics, the same `deriveSupervisorOptions` for a directory that declares
+  delegates. Only the import path and the names.
+
+  **Nobody has to migrate.** The package was never published — a `@namzu/project`
+  install has always 404'd — so there is no consumer to move and no deprecation
+  window owed. The rename that would have cost a major after publishing cost
+  nothing before it.
+
+  Renames, if you were following the source: `loadProject` → `loadDirectory`,
+  `ProjectManifest` → `DirectoryManifest`, `ProjectConfig` → `DirectoryConfig`,
+  `ProjectSlot` → `DirectorySlot`, `ProjectLoadResult` → `DirectoryLoadResult`,
+  `ProjectDiagnostic` → `DirectoryDiagnostic`, `LoadProjectOptions` →
+  `LoadDirectoryOptions`. `DiagnosticCode` and `DiagnosticSeverity` gained a
+  `Directory` prefix as well — bare, in a shared namespace, they read as the
+  SDK's own diagnostic vocabulary rather than one loader's.
+
+  A side effect worth naming: `@namzu/project` was the one package the release
+  pipeline could not publish, so every release since `#102` ended red on its
+  `E404`. That failure goes with it.
+
+- ca64062: runAgent forwards skills and the verification gate
+
+  `runAgent` built its `drainQuery` call with an `as never` cast. The cast was
+  not load-bearing — removing it typechecks clean — but while it was there the
+  kernel seam was unchecked in both directions, and two options the kernel
+  accepts were never forwarded.
+
+  **`skills`** is the one with a caller. `@namzu/sdk` reads a whole `skills/`
+  directory, puts them on the options, and every one was dropped: the run was
+  assembled without them and nothing reported it. If you passed `skills` to
+  `runAgent` and wondered why the model behaved as though it had never seen them,
+  this is why. No change needed on your side — the field now arrives.
+
+  **`verificationGate`** is the safety one. The kernel builds a `VerificationGate`
+  from it and consults it on every tool call; the front door had no way to supply
+  one, so a `runAgent` run was strictly less mediated than a `drainQuery` run. A
+  host that hands `runAgent` an agent directory it did not write should now set
+  it.
+
+  Both are optional and default to today's behaviour, so nothing breaks.
+
+  Three fixes in `@namzu/sdk`, each a check that existed and read the wrong
+  thing:
+
+  - **A tool with no `inputSchema` is refused.** It used to pass `isToolDefinition`
+    — which checked only `name` and `execute` — register clean, then die inside
+    `toLLMTools()` on `inputSchema._def`, in a `TypeError` naming neither the tool
+    file nor the loader. The check is now the four fields `ToolDefinition`
+    declares as required, and no more: demanding `defineTool`'s extras would make
+    the loader refuse an object the SDK's own published type accepts. A directory
+    that previously loaded with `ok: true` and crashed on first use now loads with
+    `ok: false` and a `not_a_tool` diagnostic naming the file.
+  - **Import failures explain themselves again.** `explainImportFailure` chose its
+    hint by matching Node's error code against `err.message`, and Node does not
+    put the code in the message — probed: `ERR_MODULE_NOT_FOUND` arrives as
+    "Cannot find module …". Every hint in the function was unreachable. It reads
+    `err.code` now, and a Node too old for type stripping gets a hint of its own.
+  - **`metadata` values are checked.** Typed `Record<string, string>` and admitted
+    on `typeof === 'object'` alone, which an array also satisfies and which says
+    nothing about the values, so `{ count: 1 }` and `["a"]` both reached a
+    consumer that had been promised strings.
+
+- 61ca851: a tool whose schema cannot carry the guarantee it asks for is refused at registration
+
+  The previous release fixed the `edit` tool's schema and added a check in the
+  Anthropic driver. That caught the bug, but in the wrong place: per request, in
+  one of the **two** drivers that mark tools strict, and only once something
+  actually ran.
+
+  `ToolRegistry` already refused `enforceModelInput` without a
+  `modelInputSchema`, and the comment above that check states the principle
+  exactly — _"Refusing at registration puts the error where the author can fix it
+  rather than at the first request."_ The rule was written down; the new check was
+  somewhere else.
+
+  It is now beside its sibling. One asks whether a model schema **exists**; the
+  other asks whether it can **carry the guarantee the tool just requested**. A
+  tool that asks for constrained generation and supplies a schema the constrained
+  dialect cannot express is wrong at the moment it is declared, whichever model it
+  later meets — so it never registers, and can never reach a request.
+
+  ```
+  Tool "edit" is marked for strict input validation, but its model-facing schema
+  uses 1 construct(s) the strict subset does not accept…
+    edit.properties.insertLine.oneOf — use `anyOf` — for disjoint branches the two are equivalent
+  ```
+
+  This is the only path that matters in practice: the kernel builds its tool list
+  with `ToolRegistry.toLLMTools()`, so every tool reaching a driver through the
+  normal loop passed the gate.
+
+  **A tool that never asked for the guarantee is untouched.** Without
+  `enforceModelInput` nothing is marked strict, the schema is sent as ordinary
+  JSON Schema, and `oneOf` is perfectly legal there. Refusing it would break
+  working setups for no reason.
+
+  `@namzu/http` also marks tools strict and had no check at all — the same bug
+  was reachable through it. It now has the driver-level check the Anthropic driver
+  already carried. Both remain as a second boundary for a host that hand-builds
+  `ChatCompletionParams` and calls a provider directly, bypassing the registry.
+
+  **If you author a tool with `enforceModelInput: true`,** a schema using `oneOf`,
+  `not`, `if`/`then`/`else`, numeric or length bounds, `patternProperties`, or an
+  `additionalProperties` other than `false` now throws at registration instead of
+  failing the first request that carries it. The message names the path and the
+  replacement.
+
+- f25ebce: the edit tool's schema could not be sent under strict validation
+
+  Strict tool input is not "JSON Schema, enforced" — it is a **subset** of JSON
+  Schema, and a keyword outside that subset is not degraded. The vendor rejects
+  the whole request, so one unexpressible field in one tool takes every other
+  tool down with it and the turn dies before producing a token.
+
+  The `edit` tool declared its integer-or-`"end"` field with `oneOf`, which is
+  outside the subset while the equivalent `anyOf` is inside it. Measured against
+  the live API:
+
+  | body                      | result                                           |
+  | ------------------------- | ------------------------------------------------ |
+  | `strict: true` + `oneOf`  | **400** — `Schema type 'oneOf' is not supported` |
+  | `strict: false` + `oneOf` | accepted                                         |
+  | `strict: true` + `anyOf`  | accepted                                         |
+
+  The middle row is why nothing caught it. Neither half is wrong on its own — the
+  schema is valid JSON Schema, and marking the tool strict is correct policy — so
+  no test of either one failed. Only the pairing did, and the pairing had no
+  owner. Every agent using the built-in `edit` tool on a model at or above the
+  strict gate lost its first tool-carrying turn to a 400.
+
+  `oneOf` is now `anyOf` (equivalent here — the branches are disjoint), and
+  `minimum` is gone from the model-facing schema for the same reason: numeric
+  bounds are outside the subset too. The bound is not lost, the execution schema
+  still enforces it.
+
+  **The general fix is the second half.** `assertStrictSchema` and
+  `findStrictSchemaViolations` are exported from `@namzu/sdk`, and the driver now
+  checks every schema it is about to mark strict — refusing with the exact path
+  and the remedy rather than letting the request go and getting back an error
+  that names the keyword but not where it lives:
+
+  ```
+  Tool "edit" is marked for strict input validation, but its model-facing schema
+  uses 1 construct(s) the strict subset does not accept…
+    edit.properties.insertLine.oneOf — use `anyOf` — for disjoint branches the two are equivalent
+  ```
+
+  A test sweeps every built-in tool that asks for strict validation, so the next
+  one is caught in the suite rather than in production.
+
+- f25ebce: a directory-derived supervisor now has a token budget, a wall clock, and its skills
+
+  `BaseAgentConfig` declares `tokenBudget` and `timeoutMs` as **required**.
+  `deriveSupervisorOptions` supplied them only when `agent.ts` happened to name
+  them — the uncommon case — and an `as SupervisorAgentConfig` made that compile.
+  The returned object was therefore typed `tokenBudget: number` while holding
+  `undefined`.
+
+  That is not a type-level nicety. `buildLimitConfig` defaults only
+  `maxIterations`, so an undefined budget and timeout disable **both** hard stops:
+  a supervisor derived from a directory ran with no token cap and no wall clock.
+  And the child-spawn guard computes a delegate's allocation from the parent
+  budget, so `undefined` became `NaN` — and `NaN <= 0` is `false`, meaning the
+  refusal that exists to stop an unfunded child let it through with a `NaN`
+  budget.
+
+  Both now default to the same numbers `runAgent` uses, which are exported as
+  `DEFAULT_TOKEN_BUDGET`, `DEFAULT_TIMEOUT_MS` and `DEFAULT_MAX_ITERATIONS` so the
+  two front doors cannot drift. Anything `agent.ts` declares still wins, and
+  `overrides` still wins over that.
+
+  The cast is now `satisfies`, so the next missing required field is a compile
+  error rather than a run with its limits quietly switched off.
+
+  Same file, same cast: `skills` were loaded from the project's `skills/`
+  directory, put on the manifest, and then left out of the config the supervisor
+  actually ran with. `SupervisorAgentConfig` accepts them and the kernel drives
+  them; they are now supplied.
+
+- c6b8aa8: An agent directory can declare delegates, and `deriveSupervisorOptions` turns them into
+  a `SupervisorAgent` configuration.
+
+  `SupervisorAgent` needs an `agentIds` roster and a manager that can spawn them.
+  Nothing led from a directory to either, so a multi-agent system could be
+  described on disk and not run.
+
+  A directory under `agents/` is read by the same loader that read the root — a
+  delegate has the same shape as its parent, so this is recursion rather than a
+  new concept.
+
+  ```
+  agent/
+  ├── instructions.md
+  └── agents/
+      ├── researcher/   ← its own agent.ts, instructions.md, tools/
+      └── writer/
+  ```
+
+  `deriveSupervisorOptions` supplies the roster and leaves the manager to the
+  host, the same contract `deriveRunOptions` follows: it converts, it does not
+  run. Delegates come back as plans rather than registered agents, because
+  registration mutates the host's manager and a function that quietly mutates an
+  object it was handed for reference is the surprise this package avoids.
+
+  A delegate may name its own model and inherits the coordinator's only when it
+  does not — a cheap model for a narrow job is the common case, and inheriting
+  unconditionally would bill every specialist at the coordinator's rate.
+
+  **One level only.** A delegate may not declare delegates of its own. How deep a
+  system fans out is a topology decision that belongs to whoever composes it, and
+  answering it by default is how a directory layout ends up deciding a system's
+  shape. It also removes the cycle: `agents/a/agents/b/agents/a` cannot be built
+  if the second level is never read.
+
+  A delegate that fails to load is reported in the parent's diagnostics, prefixed
+  with its path, and is not offered in the roster. A caller reading one list
+  should not have to walk the tree to find out the run will be short a specialist.
+
+### Patch Changes
+
+- f25ebce: the fork-bomb entry in the dangerous-command list could not match a fork bomb
+
+  `DANGEROUS_PATTERNS` is what the `deny_dangerous_patterns` verification rule
+  consults, and what `namzu run`'s own docstring means when it promises that in a
+  non-interactive run "the safety gate still hard-denies catastrophic commands".
+
+  The fork-bomb entry was written `/:(){ :\|:& };:/`. In a regular expression
+  `()` is an empty capture group, not two literal parentheses — so that pattern
+  described the string `:{ :|:& };:`, which is not valid shell and which nobody
+  would ever type. Probed: it returned `false` for `:(){ :|:& };:` and for every
+  other spelling of it.
+
+  The replacement matches on **self-reference** rather than on one literal
+  spelling — a fork bomb is a function whose own name appears on both sides of a
+  pipe, is backgrounded, and is then invoked. So `bomb(){ bomb|bomb& }; bomb` is
+  denied along with the `:` form, while `watch(){ tail -f log | grep E & }` — a
+  function that merely contains a pipe and a background job — is not.
+
+  No test named a fork bomb before this change, which is how it survived. There
+  are now sixteen.
+
+- c8672ed: The plugin subsystem contains its paths. It had none, and it is the part of
+  this SDK that loads third-party code.
+
+  **A manifest could name any file on disk.** `PluginLifecycleManager` built its
+  import path with `join(plugin.rootDir, toolPath)`, and `toolPath` comes out of
+  the plugin's own manifest — a file the plugin author writes. A manifest reading
+  `"tools": ["../../../../somewhere/evil.js"]` left the plugin directory entirely
+  and was imported, which is to say executed, in-process. The same held for
+  `hooks`. Both now resolve through `resolveWithinReal`, so a path that escapes
+  the plugin root is refused before anything is imported.
+
+  **Discovery followed symlinks.** `discoverPlugins` used `stat`, which reports
+  on a link's _target_, so a symlinked entry pointing anywhere on disk was
+  admitted as a plugin directory and its manifest read from there — the directory
+  listed was not the directory loaded (CWE-59). It now uses `lstat` and refuses a
+  link with a warning naming the path.
+
+  Found by comparing the plugin loader against `@namzu/sdk`'s scanner, which
+  was written this week with both protections. The subsystem that had them was
+  the one loading code the repo's own reviewers wrote; the one without them was
+  the one loading code from a home directory those reviewers never see.
+
+  If you ship a plugin whose manifest points outside its own directory, it now
+  fails at enable with a message naming the path. Move the file inside the plugin.
+
+## 5.1.0
+
+### Minor Changes
+
+- 8dbb98b: Adds `@namzu/project` — a conventional agent directory, read into typed,
+  inspectable definitions.
+
+  ```
+  my-agent/agent/
+  ├── agent.ts          # optional — model, temperature, budgets
+  ├── instructions.md   # optional — the system prompt
+  ├── tools/search.ts   # default-exports defineTool(…)
+  └── skills/plan-a-trip/SKILL.md
+  ```
+
+  ```ts
+  const { manifest, ok, diagnostics } = await loadProject("./agent");
+  await runAgent(deriveRunOptions(manifest, { provider, prompt: "go" }));
+  ```
+
+  A **loader, not a runner**, and not in `@namzu/sdk`: the kernel does not
+  mandate a directory layout any more than a kernel mandates `/etc/foo.conf`.
+  `deriveRunOptions` returns ordinary `RunAgentOptions`, so there is no second
+  code path and no behaviour reachable only through the convention.
+
+  **Importing a directory runs it.** `loadProject` imports every module-backed
+  file, in this process, with this process's privileges — a top-level side effect
+  in `tools/search.ts` happens during the load. There is no in-process boundary
+  that would change that, and `@namzu/sandbox` confines tool execution rather
+  than module import. For a directory whose author you are not,
+  `modules: 'skip'` imports nothing while still returning the full structural
+  truth: every path, the instructions, the skills, duplicate detection. That is
+  also the mode a CI gate and a UI file tree want.
+
+  **TypeScript without a build step.** Files load through `await import()`, so
+  `.ts` is handled by Node's own type stripping. Stripping erases types rather
+  than transforming code, so `enum`, decorators, parameter properties, runtime
+  `namespace`, extensionless relative imports and tsconfig `paths` aliases do not
+  work — the README tables each one against what to write instead, and the errors
+  name the remedy. A host that needs them passes `importModule` and hands in
+  `jiti` or a `tsx`-registered importer: three lines in the host, no bundler in
+  this dependency tree.
+
+  **Nothing fails silently.** A file that cannot load is reported with its path
+  and reason, never dropped. Two behaviours worth knowing: a symlink is refused
+  rather than followed, because the file that would be imported is not the file
+  that was listed; and a timed-out import is `'abandoned'`, not `'failed'`, since
+  `import()` cannot be cancelled — the module may still finish, and Node caches
+  it, so a later load in the same process can see the same file succeed.
+
+  `channels/` and `schedules/` are **not** in this version. A trigger of
+  `{ id, handler }` cannot express a signed webhook — verification needs the raw
+  body, and a handler receiving a parsed one can never check an HMAC — carries no
+  idempotency key while webhooks retry and schedules double-fire, and a cron
+  field with no timezone story is a declaration nothing drives. Each would be a
+  breaking change to a published type; the shape question gets its own pass.
+
+  `@namzu/sdk` additionally exports `resolveWithin`, `resolveWithinReal` and
+  `isWithin`, the containment helpers its own filesystem tools use. They were
+  internal while three call sites outside that file needed them.
+
+### Patch Changes
+
+- 7ac89da: A driver that classified its own failure was being punished for it, in two
+  places, and both shipped in 5.0.0.
+
+  **`classifyProviderError` never read `kind`.** A `ProviderRequestError` — the
+  type first-party drivers throw when they have diagnosed a failure themselves —
+  fell through to the status heuristics, where a carefully-determined
+  `context_overflow` carrying a 400 became `invalid_request`. Three of the six
+  kinds landed wrong that way:
+
+  | kind               | was                              | now                                      |
+  | ------------------ | -------------------------------- | ---------------------------------------- |
+  | `context_overflow` | `invalid_request`, not retryable | `context_length_exceeded`, not retryable |
+  | `server`           | `invalid_request`, not retryable | `server_error`, **retryable**            |
+  | `network`          | `invalid_request`, not retryable | `network`, **retryable**                 |
+
+  The overflow case was not cosmetic. The run loop reaches for compaction when it
+  sees `context_length_exceeded`, so relief — the one provider failure this
+  kernel can actually do something about — was unreachable for exactly the
+  drivers that had diagnosed the problem correctly.
+
+  **`withProviderRetry` rethrew such errors before the retry loop.** Its comment
+  justified preserving the driver's classification, which is right; the code also
+  skipped retrying, which is a separate decision nobody made. A first-party HTTP
+  or OpenRouter driver reporting a 429 as `kind: 'throttle'` got exactly one
+  attempt, while the identical failure from a driver that classified nothing got
+  the full backoff.
+
+  Retry is now decided the same way for both, from the classification's
+  `retryable`. The original error still escapes to the run boundary, so
+  `run.lastProviderError` keeps reporting the driver's own
+  `{ kind, status, retryAfterMs }` — wrapping there would have fixed the retry
+  and lost the vendor's `kind`, which the existing stream-recovery test caught.
+
+  **What changes for you.** A 429, a 5xx or a socket failure from
+  `@namzu/http` or `@namzu/openrouter` is now retried with backoff instead of
+  failing on the first attempt, and a context overflow from those drivers now
+  triggers compaction instead of failing the run. If you were relying on a typed
+  error failing fast, `retry: { maxRetries: 0 }` on `drainQuery` restores that.
+
 ## 5.0.0
 
 ### Major Changes

package/README.md

@@ -29,7 +29,7 @@ Namzu is a single-process TypeScript kernel with the following responsibilities:
 - **Scheduling.** Per-run token, cost, wall-clock, and iteration budgets. Limit checker, task router (cheap model for compaction, expensive for coding), tool tiering (LLM learns to prefer cheaper tools first).
 - **Signals.** `AbortController` tree spanning parent and children. `cancel(taskId)` and `cancelAll(parentRunId)` propagate. Runs can be paused and resumed, aborted cleanly, and emit lifecycle events for every transition.
 - **Memory management.** Working memory via structured compaction to a typed `WorkingState`. Long-term memory via an indexed, tag/query/status-searchable store with disk persistence. No vector database required by default.
-- **Durability.** Atomic per-iteration checkpoints, automatic emergency core-dump on SIGINT/SIGTERM, separate storage for runs, threads, conversations, activities, memories, and tasks.
+- **Durability.** Atomic per-iteration checkpoints, an opt-in emergency core-dump on SIGINT/SIGTERM (`emergencySave: true` — a library must not seize a host process termination path by default), separate storage for runs, threads, conversations, activities, memories, and tasks.
 - **IPC.** Native A2A (agent-to-agent) and MCP (Model Context Protocol) — both client and server, one SDK. An internal event bus with circuit breakers, file lock manager, and edit ownership tracking so concurrent agents do not stomp on each other.
 - **Capability system.** Tools are first-class, typed, permissioned, and progressively disclosed. The LLM does not see the full tool catalog; tools start deferred, get activated on demand, and can be suspended. Each tool declares `readOnly`, `destructive`, `concurrencySafe`, `permissions`, `category`.
 - **Syscall filtering.** Every tool call goes through a verification gate — allow / deny / ask, with built-in rules for read-only allowlist and dangerous pattern deny-list, plus custom regex rules. This is separate from sandbox isolation; it is the decision layer, the sandbox is the enforcement layer.
@@ -375,7 +375,7 @@ const result = await agent.run(
 )
 ```
 
-That is a complete, sandbox-isolated, checkpointed, telemetrized agent run with prompt caching, progressive tool disclosure, structured compaction, and emergency save all wired in by default. Those are not features you enable; they are how the kernel runs. Swap `registerOpenRouter()` for `registerOllama()`, `registerAnthropic()`, `registerBedrock()`, `registerOpenAI()`, `registerLMStudio()`, or `registerHttp()` — the code below the registration line stays identical.
+That is a complete, sandbox-isolated, checkpointed, telemetrized agent run with prompt caching, progressive tool disclosure, and structured compaction all wired in by default — those are not features you enable, they are how the kernel runs. Emergency save is the exception and is opt-in: pass `emergencySave: true` when the process owns its run end to end. Swap `registerOpenRouter()` for `registerOllama()`, `registerAnthropic()`, `registerBedrock()`, `registerOpenAI()`, `registerLMStudio()`, or `registerHttp()` — the code below the registration line stays identical.
 
 Examples for `PipelineAgent`, `RouterAgent`, and `SupervisorAgent` are in `src/agents/`.
 

package/dist/agents/__tests__/run-agent-forwarding.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-agent-forwarding.test.d.ts.map

package/dist/agents/__tests__/run-agent-forwarding.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent-forwarding.test.d.ts","sourceRoot":"","sources":["../../../src/agents/__tests__/run-agent-forwarding.test.ts"],"names":[],"mappings":""}

package/dist/agents/__tests__/run-agent-forwarding.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { MockLLMProvider, registerMock } from '../../provider/index.js';
+import { ToolRegistry } from '../../registry/index.js';
+import { runAgent } from '../runAgent.js';
+/**
+ * The `drainQuery` call in `runAgent` was written `as never`.
+ *
+ * That cast was not load-bearing — removing it typechecks clean — but while it
+ * was there the kernel seam was unchecked in both directions: a field the
+ * kernel accepts and this door forgot to forward produced no error, and neither
+ * did a field spelled wrong. Two were already missing when it was removed.
+ *
+ * `skills` is the one with a caller in this repo. `@namzu/project` reads a
+ * whole `skills/` directory, put them on the options, and every one was dropped
+ * on the floor — the run was assembled without them and said nothing. These
+ * pin the forwarding rather than the cast, because the cast can come back and
+ * a test that only asserted its absence would not notice.
+ */
+registerMock();
+describe('runAgent forwards what the kernel takes', () => {
+    it('puts skills in front of the model', async () => {
+        const provider = new MockLLMProvider({ turns: [{ text: 'ok' }] });
+        await runAgent({
+            provider,
+            model: 'mock-model',
+            prompt: 'plan something',
+            skills: [
+                {
+                    metadata: { name: 'plan-a-trip', description: 'Plan a trip end to end' },
+                    body: 'Ask for dates first.',
+                    dirPath: '/tmp/skills/plan-a-trip',
+                },
+            ],
+        });
+        // Serialized rather than reached into: the prompt builder decides where a
+        // skill lands, and pinning that path here would make this test fail on a
+        // refactor that kept the behaviour. What matters is that it arrived.
+        expect(JSON.stringify(provider.requests[0])).toContain('plan-a-trip');
+    });
+    it('forwards the verification gate, so a denied tool does not run', async () => {
+        // The first version of this test asserted `run.status === 'completed'`
+        // with the gate set. It passed with the forwarding deleted — a run with
+        // no gate completes too — so it proved nothing. A gate is only observable
+        // through a call it stops, which means the assertion has to be about
+        // whether the tool body ran.
+        let ran = false;
+        const tools = new ToolRegistry();
+        tools.register({
+            name: 'delete_everything',
+            description: 'Deletes everything.',
+            inputSchema: z.object({}),
+            execute: async () => {
+                ran = true;
+                return { success: true, output: 'deleted' };
+            },
+        });
+        await runAgent({
+            provider: new MockLLMProvider({
+                turns: [{ toolCalls: [{ name: 'delete_everything', args: {} }] }, { text: 'done' }],
+            }),
+            model: 'mock-model',
+            prompt: 'clean up',
+            tools,
+            verificationGate: {
+                enabled: true,
+                rules: [{ type: 'deny_by_name', toolNames: ['delete_everything'] }],
+                allowReadOnlyTools: false,
+                denyDangerousPatterns: false,
+                logDecisions: false,
+            },
+        });
+        expect(ran).toBe(false);
+    });
+});
+//# sourceMappingURL=run-agent-forwarding.test.js.map

package/dist/agents/__tests__/run-agent-forwarding.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent-forwarding.test.js","sourceRoot":"","sources":["../../../src/agents/__tests__/run-agent-forwarding.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,CAAA;AAEd,QAAQ,CAAC,yCAAyC,EAAE,GAAG,EAAE;IACxD,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;QAClD,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;QAEjE,MAAM,QAAQ,CAAC;YACd,QAAQ;YACR,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,gBAAgB;YACxB,MAAM,EAAE;gBACP;oBACC,QAAQ,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,wBAAwB,EAAE;oBACxE,IAAI,EAAE,sBAAsB;oBAC5B,OAAO,EAAE,yBAAyB;iBAClC;aACD;SACD,CAAC,CAAA;QAEF,0EAA0E;QAC1E,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAA;IACtE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC9E,uEAAuE;QACvE,wEAAwE;QACxE,0EAA0E;QAC1E,qEAAqE;QACrE,6BAA6B;QAC7B,IAAI,GAAG,GAAG,KAAK,CAAA;QAEf,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAA;QAChC,KAAK,CAAC,QAAQ,CAAC;YACd,IAAI,EAAE,mBAAmB;YACzB,WAAW,EAAE,qBAAqB;YAClC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,KAAK,IAAI,EAAE;gBACnB,GAAG,GAAG,IAAI,CAAA;gBACV,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;YAC5C,CAAC;SACD,CAAC,CAAA;QAEF,MAAM,QAAQ,CAAC;YACd,QAAQ,EAAE,IAAI,eAAe,CAAC;gBAC7B,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;aACnF,CAAC;YACF,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,UAAU;YAClB,KAAK;YACL,gBAAgB,EAAE;gBACjB,OAAO,EAAE,IAAI;gBACb,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC;gBACnE,kBAAkB,EAAE,KAAK;gBACzB,qBAAqB,EAAE,KAAK;gBAC5B,YAAY,EAAE,KAAK;aACnB;SACD,CAAC,CAAA;QAEF,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA"}

package/dist/agents/__tests__/run-completed-stop-reason.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-completed-stop-reason.test.d.ts.map

package/dist/agents/__tests__/run-completed-stop-reason.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-completed-stop-reason.test.d.ts","sourceRoot":"","sources":["../../../src/agents/__tests__/run-completed-stop-reason.test.ts"],"names":[],"mappings":""}

package/dist/agents/__tests__/run-completed-stop-reason.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { MockLLMProvider, registerMock } from '../../provider/index.js';
+import { runAgent } from '../runAgent.js';
+/**
+ * `completed` is not `succeeded`.
+ *
+ * `run_failed` is emitted from exactly one place — the throw path in
+ * `result.ts` — so every other way a run can end badly arrives as
+ * `run_completed`: the token budget, the timeout, the iteration cap, a
+ * cancellation, and a blocking output guardrail. A consumer reading that event
+ * as success reported one for a run whose answer was refused, and the CLI did:
+ * it mapped `run_completed` to a bare `done` and exited 0.
+ *
+ * Measured before the fix: a `max_iterations` stop reports
+ * `status: 'completed'`, and the event carried nothing to distinguish it.
+ */
+registerMock();
+async function eventsOf(options) {
+    const events = [];
+    await runAgent({ ...options, listener: (e) => void events.push(e) });
+    return events;
+}
+function completion(events) {
+    return events.find((e) => e.type === 'run_completed');
+}
+describe('run_completed says why the run stopped', () => {
+    it('reports end_turn when the model finished its answer', async () => {
+        const events = await eventsOf({
+            provider: new MockLLMProvider({ turns: [{ text: 'done' }] }),
+            model: 'mock-model',
+            prompt: 'x',
+        });
+        expect(completion(events)?.stopReason).toBe('end_turn');
+    });
+    it('reports max_iterations when the loop was cut short', async () => {
+        const events = await eventsOf({
+            provider: new MockLLMProvider({ turns: [{ toolCalls: [{ name: 'absent', args: {} }] }] }),
+            model: 'mock-model',
+            prompt: 'x',
+            maxIterations: 1,
+        });
+        const done = completion(events);
+        // The event that a consumer treats as "the run ended" — and the field
+        // that stops it being read as "the run succeeded".
+        expect(done).toBeDefined();
+        expect(done?.stopReason).toBe('max_iterations');
+        expect(events.some((e) => e.type === 'run_failed')).toBe(false);
+    });
+});
+//# sourceMappingURL=run-completed-stop-reason.test.js.map

package/dist/agents/__tests__/run-completed-stop-reason.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-completed-stop-reason.test.js","sourceRoot":"","sources":["../../../src/agents/__tests__/run-completed-stop-reason.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAE7C,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAEvE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC;;;;;;;;;;;;GAYG;AAEH,YAAY,EAAE,CAAA;AAEd,KAAK,UAAU,QAAQ,CAAC,OAAuC;IAC9D,MAAM,MAAM,GAAe,EAAE,CAAA;IAC7B,MAAM,QAAQ,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACpE,OAAO,MAAM,CAAA;AACd,CAAC;AAED,SAAS,UAAU,CAAC,MAAkB;IACrC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAU,CAAA;AAC/D,CAAC;AAED,QAAQ,CAAC,wCAAwC,EAAE,GAAG,EAAE;IACvD,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACpE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;YAC7B,QAAQ,EAAE,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YAC5D,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,GAAG;SACX,CAAC,CAAA;QAEF,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACxD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;YAC7B,QAAQ,EAAE,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;YACzF,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,GAAG;YACX,aAAa,EAAE,CAAC;SAChB,CAAC,CAAA;QAEF,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;QAC/B,sEAAsE;QACtE,mDAAmD;QACnD,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;QAC1B,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;QAC/C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAChE,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA"}

package/dist/agents/index.d.ts

@@ -8,5 +8,6 @@ export type { DefineAgentOptions } from './defineAgent.js';
 export { InvocationLock, ConcurrentInvocationError } from './lock.js';
 export type { Disposable } from './lock.js';
 export { runAgent } from './runAgent.js';
+export { DEFAULT_MAX_ITERATIONS, DEFAULT_TIMEOUT_MS, DEFAULT_TOKEN_BUDGET, } from './runAgent.js';
 export type { AgentIdentity, RunAgentOptions, RunAgentResult } from './runAgent.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAIxC,OAAO,EACN,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}