@theokit/agents 9.3.0 → 10.0.0

package/CHANGELOG.md

@@ -1,5 +1,202 @@
 # @theokit/agents
 
+## 10.0.0
+
+### Major Changes
+
+- 4cd49ef: BREAKING: `deleteSession` and `runTranscriptGC` are now `async`.
+
+  Their return type goes from `T` to `Promise<T>`. A caller that does not `await` reads `undefined`
+  instead of the result and throws on the first field access — which is what happened to this repo's
+  own `theokit agent sessions gc` command, unnoticed for a day because the workspace typecheck was
+  measured against a stale `.d.ts`.
+
+  The change is required rather than cosmetic: the only agent registry in the ecosystem is
+  `Agent.delete(id): Promise<void>`, and the registry half of session deletion is unreachable without
+  awaiting it. Migration is `await`.
+
+  BREAKING: `SessionRegistryRemoverError` changes constructor arity and meaning. It was
+  `constructor(sessionId)` for "you passed a thenable to a synchronous seam"; it is now
+  `constructor(sessionId, timeoutMs)` for "the registry did not answer in time". The old condition no
+  longer exists, so a `catch` that depended on it will never fire again. The class moved module and is
+  re-exported from its old home, so import paths are unaffected.
+
+  Also: the registry timeout now has a bounded DEFAULT (`DEFAULT_REGISTRY_TIMEOUT_MS`, 30s) where it
+  previously waited forever. Unbounded remains available by passing a non-finite value.
+
+### Minor Changes
+
+- 7519927: Security: `auto-edit` no longer auto-approves from a framework-chosen default. A product declares its own set.
+
+  `shouldAutoApprove`'s `auto-edit` branch defaulted to `WRITE_SCOPED_TOOLS` — `apply_patch`, `edit_file`, `write_file`. The only real consumer auto-approves one of those and registers two, so adopting the framework symbol would have made `edit_file` stop requiring a human: a live, model-callable write tool, silently un-gated as a side effect of deleting duplicated code.
+
+  Two questions had been conflated. "Does this tool bound its own writes to a write root?" is a fact about the SDK's tool factories, and the framework can answer it. "May this tool run without asking a human?" is the product's policy, and the framework cannot answer it — it does not know which tools the product registered or what it renamed them to.
+
+  `auto-edit` with no `writeScopedTools` now approves nothing, which is the same shape the module already applies to sandbox posture (an absent posture counts as unconfined). `WRITE_SCOPED_TOOLS` is still exported as the catalog; passing it is a decision rather than an inheritance.
+
+  `WRITE_SCOPED_TOOLS` is now genuinely immutable — its mutators throw. `ReadonlySet` is erased at runtime, and one cast on an approval gate reachable from every consumer would widen what auto-approves everywhere. `Object.freeze` alone is not enough for a `Set`: entries live in internal slots, not own properties, so freezing leaves `add` working.
+
+  Not a breaking change for published consumers: `npm pack @theokit/agents@9.4.0` exports neither `shouldAutoApprove` nor `WRITE_SCOPED_TOOLS`. Anyone already calling it on a pre-release build must pass `{ writeScopedTools }` to keep `auto-edit` approving anything.
+
+- 0513d03: `deleteSession` re-checks protection immediately before unlinking, instead of trusting a snapshot taken before an await.
+
+  The protection check ran at the top of the function; control then left for as long as the caller's registry remover took — 30s by default, unbounded with `registryTimeoutMs: Infinity` — and only then was the transcript removed. Anything concluded before that await is a snapshot, and a user resuming the session during the window makes it false. The file was deleted anyway and `SessionInUseError` never fired, which is the outcome that error exists to prevent.
+
+  The batch path already treats this as non-negotiable: `transcript-gc.ts` invariant 4 is "the apply phase re-checks — a plan is a snapshot, and between snapshot and delete a user can resume a session". The single-session path skipped it, and it is the one with no later sweep to catch the mistake.
+
+  `SessionInUseError` gains `registryRemoved`. Refusing after the registry half has run leaves an orphan file — the recoverable direction the function already chose in its ordering — but the caller has to be told, or it retries a removal that is already done and reads the resulting `false` ("no entry to remove") as a failure. The constructor parameter is optional and defaults to `false`, so existing construction sites are unaffected.
+
+- 01735c7: `classifyProjects` (`@theokit/agents/session`) — answers "does the project behind `projects/<encoded>/` still exist?" without the caller writing the search itself.
+
+  `minor`, not `major`, and the distinction was measured rather than assumed: `npm pack @theokit/agents@9.4.0` ships the `./session` subpath but contains neither `classifyProjects` nor `FsSeam`. This is a new export on an existing subpath, so the option and seam changes made while stabilising it break no published consumer — there is none. The only migration note that would be honest is the one for the consumer this was absorbed from, and it is written as adoption guidance below rather than as a break.
+
+  The question is hard because `encodeProjectDir(cwd)` is `cwd.replace(/[^a-zA-Z0-9]/g, '-')` — one-way and many-to-one, so a directory name cannot be turned back into a path, only CHECKED against candidates. Every product that retains or garbage-collects transcripts has to answer it; the consumer's own version is 188 lines whose docstring measured 13,269 project directories, ~3,200 falling through to filesystem search and ~64M syscalls without a shared budget.
+
+  Three properties carry the safety of this module, and each exists because dropping it produced a measured deletion of live data:
+
+  - **The verdict is three-valued and `undetermined` is not a soft `dead`.** Callers DELETE on `dead`. Budget spent, unreadable directory, enumeration threw — all resolve to `undetermined`, because deleting on "could not tell" is data loss and the two errors are not symmetric.
+  - **`FsSeam.exists` returns `boolean | undefined`.** The third state is in the return type rather than in prose because that is the only place an adapter author reliably reads it. A signature of `=> boolean` invites `try { return existsSync(p) } catch { return false }` — which is exactly the consumer's scar B-020, where a cwd that exists but cannot be stat-ed (EACCES on a non-traversable parent, ENOTDIR mid-path, EMFILE under a wide sweep) was classified DEAD.
+  - **Every member of the collision class is probed, not the first match.** Because the encoding is many-to-one, `encodeProjectDir(cwd) === name` narrows to a CLASS, never to a path — `/home/op/my-app` and `/home/op/my/app` share one project directory. First-match-wins lets one record condemn the rest, and transcripts are user-writable, so that record can be PLANTED. Any live member now yields `alive`; `dead` requires every member to be definitively gone.
+
+  **The budget is shared across the whole sweep, not per project.** A bound that resets each iteration is not a bound — that is what produced the 64M figure.
+
+  Adoption (for a product that already wrote this search): supply `candidatePaths` returning REAL ABSOLUTE PATHS — not encoded directory names, which is the distinction that made 6 of 6 live projects classify `dead` while the two sides were being wired together — pass `projectsRoot` via the exported `projectsRoot()` rather than joining the segment by hand, and give `fs` an `exists` that returns `undefined` for every errno except ENOENT.
+
+## 9.4.0
+
+### Minor Changes
+
+- 299a014: `createDelegateTool` — the agent can now ask the framework to delegate.
+
+  `@theokit/agents/tools` handed the model 23 tools and none of them delegated to a local sub-agent.
+  The capability shipped — `delegate()`, `delegateWithScoring()`, `delegateBackground()`, `Squad` —
+  but only the app could reach it. `createA2ATool` did not cover the case: its target is a remote peer,
+  inheriting none of the parent's tools, budget or authority.
+
+  The factory is deliberately thin. `delegate()` already merges the parent's tools, clamps the budget
+  and propagates authority; re-deriving any of that here would create a second owner of one rule.
+
+  It refuses at construction what would otherwise fail on the model's first call: an empty roster,
+  duplicate names (which collapse in the enum and dispatch silently to the wrong sub-agent) and a
+  missing credential. Budget and timeout failures come back as JSON the model can act on rather than
+  ending the parent's turn; an unexpected error propagates.
+
+- d6a5928: `CustomCommand.frontmatter` carries the frontmatter lines, so a product can read its own keys.
+
+  The loader knows one key (`description`). A product's commands declare more, and the sets do not
+  agree: the closest consumer reads `model`, `agent`, `subtask` and `hints`, while Claude Code's custom
+  commands declare `model` and `argument-hint`. Two vocabularies already, and neither is the
+  framework's to adopt.
+
+  Measured cost of not carrying them: that consumer wrote a 122-line loader — same directories, same
+  trust gate, same precedence — because the result gave it nowhere to read its own keys from. The lines
+  travel now, and `frontmatterValue` (already exported) reads whichever key the caller cares about.
+
+- 7825605: `loadInstructionTree` takes an `order`, so a rules folder is walked the way a rules folder means.
+
+  The predicate made a rules directory walkable and left the ordering the one an instruction TREE
+  needs — every file at a level before descending, because there the outer file states the general rule
+  and the inner one refines it. A rules FOLDER is the opposite shape: the files are peers, and the
+  contract its users depend on is that the same directory assembles the same prompt on any machine, in
+  one alphabetical pass.
+
+  Half a capability is its own kind of defect: offering the walk without the order left a caller able
+  to read a rules folder only in an order that misrepresents it.
+
+  Additive — `'outward-in'` stays the default, so no existing caller shifts.
+
+- c70eadb: `loadInstructionTree` now accepts a predicate for `fileNames`, so a rules DIRECTORY can be walked.
+
+  `fileNames.includes(entry)` matched a basename, so the walk could only collect files the caller
+  could name in advance. A rules directory is the opposite shape: the user drops arbitrarily named
+  files in and expects all of them read. That is not one product's idiosyncrasy — Claude Code reads
+  `.claude/rules/` and Cursor reads `.cursor/rules/*.mdc`, both arbitrary-name directories.
+
+  Measured consequence of the gap: the closest consumer wrote its own 112-line walk — budget, depth
+  ceiling, cycle guard and all — to ask `entry.endsWith('.md')`. The walk was ours; only the question
+  was theirs.
+
+  Additive: `fileNames` still accepts an array, with unchanged semantics.
+
+- 339852d: `loadCustomCommands` reads subdirectories, so a namespaced command is no longer invisible.
+
+  The loader stopped at `!statSync(path).isFile()`, which means a command in a subdirectory was not
+  "unsupported" — it was invisible. No warning, no error: the file sits there and the command does not
+  exist.
+
+  Namespacing is not one product's idea. Claude Code reads `.claude/commands/frontend/component.md` as
+  a namespaced command, and the closest consumer names nested files by their relative path for the same
+  reason a flat directory stops scaling past a dozen commands.
+
+  The name is now the path relative to the commands root with the extension removed
+  (`frontend/component`). How it is rendered — `frontend:component`, `frontend/component` — stays the
+  product's, because the two known products already disagree.
+
+- b30fe9f: `projectsRoot(root?)` — one owner for where every project's transcripts live.
+
+  `join(root, 'projects', …)` was written in three places: twice inside `project-index.ts`, and once in
+  the closest consumer, which restated it as `join(transcriptRoot(), 'projects')` to enumerate every
+  project for a GC sweep.
+
+  The failure mode is what makes it worth a function rather than a comment. That consumer guards its
+  enumeration with `existsSync(root) ? readdir(root) : []`, so a segment that stops matching does not
+  throw — it returns an empty list. The sweep then finds nothing, deletes nothing, and reports success.
+  A wrong path that throws is a bug report; a wrong path that returns nothing is a collector that
+  quietly stopped collecting.
+
+- e7c4d28: `InstructionBlock.scopesUnreadable` — a declared `paths:` that yields nothing is no longer
+  indistinguishable from no scope at all.
+
+  `parsePathsScope` reads lines and never fails, so a `paths:` whose value it cannot extract returned
+  `[]` — the same value as a file that declared no scope. A consumer rendering `scopes` then turned a
+  rule written for one subtree into a rule applying everywhere, and nothing said so.
+
+  Widening a scope silently is the one frontmatter failure with a consequence: the model obeys a rule
+  outside the files it was written for. The flag lets a product with a fail-closed policy drop the
+  block instead of publishing it unscoped, and `onWarn` now reports the case.
+
+### Patch Changes
+
+- 6b15741: Frontmatter is read on CRLF files instead of being reported as never closing.
+
+  `splitFrontmatter` split on `'\n'`, so on a CRLF checkout the closing line is `'---\r'`, which never
+  equalled the fence: a perfectly valid file returned "frontmatter never closes" and was skipped. On
+  Windows that is every instruction file with frontmatter, silently, with a warning blaming a missing
+  `---` that is sitting right there.
+
+  The trap ran one level deeper. `.` does not match `\r` and `$` does not match before it, so the
+  list-item pattern behind `paths:` failed on `'  - src/**\r'`. Fixing only the fence would have
+  turned "the file is skipped" into "the file is read and silently unscoped" — worse, because a rule
+  that applies everywhere looks like it works.
+
+  Line endings are now normalised at the boundary, and the closing fence is compared trimmed like the
+  opening one already was — an asymmetry that let a file open a frontmatter block it could never close.
+
+- b8f47a9: Two silent failures in the instruction-tree walk.
+
+  `paths: [unclosed` produced the scope `unclose`. The inline branch did
+  `inline.slice(1, inline.lastIndexOf(']'))`, and `lastIndexOf` returns -1 when the bracket never
+  arrives — so the slice quietly dropped the last character and handed back a scope nobody wrote.
+  Worse than an empty list, because a scope that exists suppresses `scopesUnreadable`: the block looked
+  correctly scoped, to a path matching nothing, so the rule stopped applying anywhere and said nothing.
+
+  The depth ceiling stopped in silence. The file ceiling already announced itself
+  (`instruction budget: stopped at N files`) and this one was a bare `return false` — indistinguishable
+  from a directory that had nothing left in it, which sends the reader looking for a typo in a filename
+  that is spelled correctly.
+
+- b023cef: `deleteSession` now refuses an async `removeFromRegistry` instead of reporting a delete that has not
+  happened.
+
+  The seam is synchronous by contract, and `options.removeFromRegistry?.(id) ?? false` sat at the
+  return: hand it an async remover and the field evaluated to a Promise — truthy — so `registryRemoved`
+  said the entry was gone before the removal occurred, and any rejection surfaced as an unhandled
+  rejection. That is not a corner case. `Agent.delete` returns `Promise<void>` and is the only agent
+  registry in the ecosystem, so every real caller has an async remover.
+
+  The check now runs BEFORE the transcript is unlinked, so a refused call leaves the session intact and
+  the caller can retry: await the registry removal first, then pass its outcome.
+
 ## 9.3.0
 
 ### Minor Changes

package/dist/{define-agent-3Kuf6iKM.d.ts → agent-compiler-CIPQkehU.d.ts}

@@ -1,7 +1,6 @@
-import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, TrustPosture, CustomTool } from '@theokit/sdk';
-import { z } from 'zod';
+import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
 import { TheokitAgentError } from '@theokit/sdk/errors';
-import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
+import { z } from 'zod';
 
 /**
  * Provider-agnostic extended-thinking knob (M1 reasoning-visibility). The common set autocompletes;
@@ -401,233 +400,4 @@ interface CompiledAgentOptions {
     skillsResolver?: SkillsSelection;
 }
 
-/**
- * M68 — the trust gate for `settingSources`.
- *
- * ## The defect this module closes
- *
- * `settingSources` enables on-disk config discovery. `'user'` reads `~/.theokit/` — the operator's
- * own machine, which no third party controls. `'project'` reads `<cwd>/.theokit/`, **including
- * `hooks.json`, which executes shell**.
- *
- * The previous API took `readonly SettingSource[]`, and its JSDoc justified the risk this way:
- * *"it is opt-in because `.theokit/` is the app's own repo (informed consent)"*. That premise holds
- * for a web app whose `cwd` is its own deploy. It does **not** hold for the class of product this
- * framework addresses — an agent whose `cwd` is a repository the user just cloned. There `.theokit/`
- * is attacker-controlled content, and enabling `'project'` is remote code execution on the first
- * `build()`.
- *
- * Documenting it did not prevent it. The measured consumer (TheoCode) did not trust the API: it
- * gated from the outside, with a `posture.allows` of its own (`chat.ts:386`, comment B-008). It
- * already **had** the right decision and could not pass it through, because the API only accepted
- * strings. The gate existed on its side and evaporated at the boundary.
- *
- * ## The evidence is the SDK's, not one invented here
- *
- * `TrustPosture` is `@theokit/sdk`'s own trust primitive, and `recordWiring`'s doc says *"a posture
- * is the only thing in this package that retains a capability"*. A bespoke type would make two trust
- * grammars coexist and drift apart (ADR 0063).
- */
-/**
- * The framework's capability vocabulary — deliberately a single name (ADR 0065).
- *
- * `allows` is all-or-nothing in the SDK: every declared `K` gets the same boolean. A finer
- * vocabulary (`hooks`, `skills`, `subagents`, `mcp`) would promise the consumer it can gate one
- * without gating the other, and the primitive does not deliver that. An API that suggests a
- * distinction the runtime does not make teaches the wrong thing, and the error only surfaces when
- * somebody depends on the distinction.
- */
-type SettingSourceCapability = 'projectSettings';
-/** Authorization to read config from the working directory. Requires the posture, never a claim. */
-interface ProjectSettingsGrant {
-    /**
-     * Typically the output of `resolveTrustPosture` — which is what gives it `source` (`'env' |
-     * 'store' | 'default'`) and therefore a refusal that says WHERE the decision came from instead of
-     * merely denying.
-     */
-    readonly trustedBy: TrustPosture<SettingSourceCapability>;
-}
-/**
- * Which on-disk config roots the agent may read.
- *
- * The asymmetry is the design: `user` is a boolean because `~/.theokit/` belongs to the operator;
- * `project` requires evidence because `<cwd>/.theokit/` may not. Omitting a root is not enabling it
- * — never "enabling without a gate". The asymmetry is inherited from the SDK itself, whose
- * `TrustPostureInput.envOverride` documents that `false` and `undefined` both mean "the operator did
- * not turn it on", not "turned it off".
- */
-interface SettingSourcesSelection {
-    /** `~/.theokit/` — the operator's machine. No gate: no third party controls it. */
-    readonly user?: boolean;
-    /** `<cwd>/.theokit/` — controlled by whoever wrote the open repository. Requires evidence. */
-    readonly project?: ProjectSettingsGrant;
-}
-/**
- * Refusal to read the working directory for lack of trust.
- *
- * Descends from `TheokitAgentError` because typed errors are an unbreakable rule here — and because
- * `isTransientError` only sees this hierarchy. A class extending plain `Error` would be invisible to
- * the predicate that separates recoverable from unrecoverable (the defect M67 fixed in five
- * classes).
- */
-declare class UntrustedSettingSourceError extends TheokitAgentError {
-    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
-    readonly trustSource: string;
-    /** The refused capability. */
-    readonly capability: SettingSourceCapability;
-    readonly name = "UntrustedSettingSourceError";
-    constructor(message: string, 
-    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
-    trustSource: string, 
-    /** The refused capability. */
-    capability: SettingSourceCapability);
-}
-/**
- * Translate the declared selection into the `SettingSource`s the SDK accepts, refusing what the
- * posture does not authorize.
- *
- * Refuses rather than ignores (ADR 0064). Ignoring would leave the product running in the belief
- * that the repository's hooks are active — a silent failure mode, on the wrong side. The SDK already
- * picked that side for the same problem: `recordWiring` throws `UngatedCapabilityError` when
- * somebody registers a capability the posture does not gate.
- *
- * @throws {UntrustedSettingSourceError} when `project` is requested and the posture does not grant it.
- */
-declare function resolveSettingSources(selection: SettingSourcesSelection | undefined): readonly SettingSource[];
-
-/**
- * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
- *
- * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
- * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
- * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
- * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
- *
- * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
- * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
- * core, preserving the agents → (nothing) dependency direction (G1).
- */
-
-/**
- * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
- * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
- * brand-check then works regardless of which copy created the definition.
- */
-declare const AGENT_BRAND: unique symbol;
-/** Config accepted by {@link defineAgent}. */
-interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
-    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
-    input?: TInput;
-    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
-    model?: string;
-    /** Static system prompt. */
-    system?: string;
-    /** Extended-thinking effort. */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
-     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
-     * normalized to the internal {@link CompiledTool} shape at compile time.
-     */
-    tools?: readonly CustomTool[];
-    /**
-     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
-     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
-     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
-     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
-     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
-     */
-    context?: Record<string, unknown>;
-    /**
-     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
-     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
-     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
-     * `unicodeNormalizer`, `outputModeration`).
-     */
-    guardrails?: readonly Guardrail[];
-    /**
-     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
-     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
-     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
-     * compile time.
-     */
-    approvals?: Record<string, HumanInTheLoopOptions>;
-    /**
-     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
-     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
-     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
-     */
-    skills?: SkillsSelection;
-    /**
-     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
-     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
-     * `project` = `<cwd>/.theokit/`, `user` = `~/.theokit/`. Absent ⇒ inline (code) config only.
-     *
-     * SECURITY (M68): `project` reads `.theokit/hooks.json`, which **executes shell**, so it requires
-     * a `TrustPosture` rather than a string. This field used to take `readonly SettingSource[]`, and
-     * its own JSDoc justified the risk as *"opt-in because `.theokit/` is the app's own repo (informed
-     * consent)"*. That premise holds for a web app whose `cwd` is its own deploy; it does not hold for
-     * an agent whose `cwd` is a repository the user just cloned, where `.theokit/` is
-     * attacker-controlled content.
-     *
-     * `user` stays a plain boolean — `~/.theokit/` is the operator's own machine. Omitting a root is
-     * not enabling it. The SDK owns discovery + execution (G2 / ADR-0040); theokit resolves the
-     * selection through `resolveSettingSources` and wires the result into
-     * `Agent.create({ local.settingSources })`.
-     */
-    settingSources?: SettingSourcesSelection;
-    /**
-     * M49 — durable memory (the SDK's `.theokit/memory/` subsystem: `Remember:` capture, MEMORY.md
-     * store, auto-injected `<memory>` block, `memory_search`/`memory_get` tools). The shape is the
-     * SDK's own `MemorySettings` — the canonical runtime contract. Projected into
-     * `Agent.create({ memory })` by `assembleM8CreateOptions`.
-     */
-    memory?: MemorySettings;
-    /**
-     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
-     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
-     */
-    plugins?: readonly unknown[];
-    /**
-     * Lifecycle hooks keyed by `HookName` (`pre_tool_call` may veto via `{ block, message }`). Set by
-     * the builder's `hooks()`; converted into a code plugin at `build()` and never reaching the SDK
-     * under this name — the plugin is the TRANSPORT, this is the contract callers write against.
-     */
-    hooks?: HookHandlers | Readonly<Record<string, unknown>>;
-    /**
-     * MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
-     * decorator. Each key is a server name; the value is the server configuration. Forwarded
-     * unchanged to `Agent.create({ mcpServers })` (the SDK owns MCP execution). Absent ⇒ no MCP.
-     */
-    mcpServers?: McpServersMap;
-}
-/**
- * A branded agent definition — the value {@link defineAgent} returns.
- *
- * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `AgentBuilder.create()` builder
- * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
- * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
- * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
- * names). Never present at runtime.
- */
-type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
-    readonly [AGENT_BRAND]: true;
-    readonly __toolNames?: TTools;
-};
-/** Infer the request type of an agent definition from its `input` Zod schema. */
-type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
-/**
- * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
- * with the `AgentBuilder.create()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
- * whose tools array carries no literal names.
- */
-type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
-/** Brand-check: is `value` a {@link defineAgent} result? */
-declare function isAgentDefinition(value: unknown): value is AgentDefinition;
-/**
- * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
- * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
- */
-declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
-
-export { type AgentDefinition as A, type BudgetOptions as B, type CompiledAgentOptions as C, type DefineAgentConfig as D, type Guardrail as G, type HumanInTheLoopOptions as H, type InferAgentInput as I, type MainLoopMeta as M, type PolicyHandler as P, type ReasoningEffort as R, type SettingSourcesSelection as S, type ToolOptions as T, UntrustedSettingSourceError as U, type CompiledTool as a, type ApprovalOptions as b, AGENT_BRAND as c, type AgentOptions as d, CostBudgetExceededError as e, type GuardrailAction as f, type GuardrailPhase as g, type GuardrailResult as h, GuardrailViolationError as i, type InferAgentToolNames as j, type MainLoopOptions as k, type McpServersMap as l, type ProjectSettingsGrant as m, type SettingSourceCapability as n, type SkillsRequestContext as o, type SkillsSelection as p, type TimeoutAction as q, type ToolWalkResult as r, type ToolboxOptions as s, type ToolboxWalkResult as t, compileAgentDefinition as u, compileTools as v, isAgentDefinition as w, resolveEnabledSkills as x, resolveSettingSources as y, type ProjectContextOptions as z };
+export { type ApprovalOptions as A, type BudgetOptions as B, type CompiledAgentOptions as C, type Guardrail as G, type HumanInTheLoopOptions as H, type McpServersMap as M, type PolicyHandler as P, type ReasoningEffort as R, type SkillsSelection as S, type ToolOptions as T, type MainLoopMeta as a, type CompiledTool as b, type AgentOptions as c, CostBudgetExceededError as d, type GuardrailAction as e, type GuardrailPhase as f, type GuardrailResult as g, GuardrailViolationError as h, type MainLoopOptions as i, type SkillsRequestContext as j, type TimeoutAction as k, type ToolWalkResult as l, type ToolboxOptions as m, type ToolboxWalkResult as n, compileTools as o, type ProjectContextOptions as p, resolveEnabledSkills as r };

package/dist/ask.d.ts

@@ -118,7 +118,7 @@ declare function createAskBridge(): AskBridge;
  * and tested without a mock.
  */
 /** A decision waiting for a human, as the surface knows it. */
-interface PendingItem {
+interface PendingItem<TPayload = undefined> {
     /** The framework's id for the decision (an approval id, a question id). */
     readonly id: string;
     /**
@@ -128,15 +128,27 @@ interface PendingItem {
      * everything attached to messages that no longer exist.
      */
     readonly messageIndex: number;
+    /**
+     * The SURFACE's own state for this item — render timestamps, collapsed flags, whatever it needs.
+     *
+     * T2.7. The framework never reads it; it is carried, not interpreted. Without this slot a surface
+     * adopting the ledger has to keep a SECOND map keyed by the same id, which is strictly worse than
+     * the single map it already maintains — and that is the measured reason `createPendingLedger`
+     * shipped and went unused while a hand-written ledger stayed in the only real consumer.
+     *
+     * The default of `undefined` is what keeps this non-breaking: every existing caller writes
+     * `PendingItem` with no argument and passes items with no payload.
+     */
+    readonly payload?: TPayload;
 }
-interface PendingLedger {
+interface PendingLedger<TPayload = undefined> {
     /**
      * Record what the framework reports as pending.
      *
      * Additive and idempotent: the same list arrives on every poll. An id already settled is NOT
      * re-added — that single rule is what stops the dismissed card from coming back.
      */
-    ingest(items: readonly PendingItem[]): void;
+    ingest(items: readonly PendingItem<TPayload>[]): void;
     /**
      * Mark one as answered. `false` when it was unknown or already settled.
      *
@@ -145,7 +157,7 @@ interface PendingLedger {
      */
     settle(id: string): boolean;
     /** The oldest unsettled item, or `undefined`. A surface shows one at a time. */
-    findNext(): PendingItem | undefined;
+    findNext(): PendingItem<TPayload> | undefined;
     /**
      * Forget everything attached to a message before `messageIndex`, settled or not. Returns how many
      * unsettled items were dropped.
@@ -154,7 +166,7 @@ interface PendingLedger {
      */
     pruneBefore(messageIndex: number): number;
 }
-declare function createPendingLedger(): PendingLedger;
+declare function createPendingLedger<TPayload = undefined>(): PendingLedger<TPayload>;
 
 /**
  * M77 — adapt an {@link AskBridge} to the `askUser` shape the question tool expects.

package/dist/ask.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ask/ask-bridge.ts","../src/ask/pending-ledger.ts","../src/ask/ask-user-via.ts"],"mappings":";;;;;AAAA,SAASA,yBAAyB;AAmC3B,IAAMC,0BAAN,cAAsCC,kBAAAA;EAnC7C,OAmC6CA;;;EACzBC,OAAO;EACzB,YAAYC,UAAkB;AAC5B;MACE,WAAWA,QAAAA;;;;MAMX;QAAEC,MAAM;MAA2B;IAAA;EAEvC;AACF;AAGO,IAAMC,0BAAN,cAAsCJ,kBAAAA;EAnD7C,OAmD6CA;;;EACzBC,OAAO;EACzB,YAAYC,UAAkB;AAC5B,UACE,WAAWA,QAAAA,4LAGX;MAAEC,MAAM;IAA4B,CAAA;EAExC;AACF;AAMO,IAAME,yBAAN,cAAqCL,kBAAAA;EAnE5C,OAmE4CA;;;EACxBC,OAAO;EACzB,YAAYC,UAAkBI,KAAa;AACzC,UAAM,uBAAuBJ,QAAAA,oBAA4BI,GAAAA,IAAO;MAC9DH,MAAM;IACR,CAAA;EACF;AACF;AAgEO,SAASI,kBAAAA;AACd,QAAMC,kBAAkB,oBAAIC,IAAAA;AAC5B,QAAMC,cAAc,oBAAID,IAAAA;AACxB,QAAME,YAAY,oBAAIF,IAAAA;AAEtB,QAAMG,SAAS,wBAACV,UAAkBW,OAAAA;AAChCL,oBAAgBM,OAAOZ,QAAAA;AACvBQ,gBAAYI,OAAOD,EAAAA;EACrB,GAHe;AAKf,SAAO;IACLE,IAAIb,UAAUc,UAAQ;AACpB,UAAIR,gBAAgBS,IAAIf,QAAAA,GAAW;AACjC,eAAOgB,QAAQC,OAAO,IAAIpB,wBAAwBG,QAAAA,CAAAA;MACpD;AACA,YAAMkB,WAAWT,UAAUU,IAAInB,QAAAA;AAC/B,UAAIkB,aAAaE,QAAW;AAG1B,eAAOJ,QAAQC,OACb,IAAId,uBAAuBH,UAAU,wCAAA,CAAA;MAEzC;AAEA,YAAMW,KAAKU,OAAOC,WAAU;AAC5B,YAAMC,UAAU,IAAIP,QAAgB,CAACQ,SAASP,WAAAA;AAC5C,cAAMQ,QAAiB;UACrBd;UACAe,QAAQ,wBAACC,WAAAA;AACPjB,mBAAOV,UAAUW,EAAAA;AACjBa,oBAAQG,MAAAA;UACV,GAHQ;UAIRC,MAAM,wBAACC,UAAAA;AACLnB,mBAAOV,UAAUW,EAAAA;AACjBM,mBAAOY,KAAAA;UACT,GAHM;QAIR;AACAvB,wBAAgBwB,IAAI9B,UAAUyB,KAAAA;AAC9BjB,oBAAYsB,IAAInB,IAAI;UAAE,GAAGc;UAAOzB;QAAS,CAAA;MAC3C,CAAA;AAEAkB,eAASa,OAAO;QAAEpB;QAAIX;QAAUc;MAAS,CAAA;AACzC,aAAOS;IACT;IAEAI,OAAOhB,IAAIgB,QAAM;AACf,YAAMF,QAAQjB,YAAYW,IAAIR,EAAAA;AAG9B,UAAIc,UAAUL,OAAW,QAAO;AAChCK,YAAMC,OAAOC,MAAAA;AACb,aAAO;IACT;IAEAK,QAAQhC,UAAQ;AACd,YAAMyB,QAAQnB,gBAAgBa,IAAInB,QAAAA;AAElC,UAAIyB,UAAUL,OAAW,QAAO;AAChCK,YAAMG,KACJ,IAAIzB,uBAAuBH,UAAU,+CAAA,CAAA;AAEvCS,gBAAUU,IAAInB,QAAAA,GAAWiC,YAAYjC,QAAAA;AACrC,aAAO;IACT;IAEAkC,YAAYlC,UAAUkB,UAAUiB,SAAO;AACrC,UAAI1B,UAAUM,IAAIf,QAAAA,EAAW,OAAM,IAAIE,wBAAwBF,QAAAA;AAC/D,YAAMyB,QAAkB;QACtBM,QAAQb;QACR,GAAIiB,SAASF,cAAcb,UAAa;UAAEa,WAAWE,QAAQF;QAAU;MACzE;AACAxB,gBAAUqB,IAAI9B,UAAUyB,KAAAA;AACxB,aAAO,MAAA;AAGL,YAAIhB,UAAUU,IAAInB,QAAAA,MAAcyB,MAAOhB,WAAUG,OAAOZ,QAAAA;MAC1D;IACF;EACF;AACF;AA/EgBK;;;AC3ET,SAAS+B,sBAAAA;AACd,QAAMC,OAAO,oBAAIC,IAAAA;AAGjB,QAAMC,UAAU,oBAAID,IAAAA;AAEpB,SAAO;IACLE,OAAOC,OAAK;AACV,iBAAWC,QAAQD,OAAO;AACxB,YAAIF,QAAQI,IAAID,KAAKE,EAAE,KAAKP,KAAKM,IAAID,KAAKE,EAAE,EAAG;AAC/CP,aAAKQ,IAAIH,KAAKE,IAAIF,IAAAA;MACpB;IACF;IAEAI,OAAOF,IAAE;AACP,YAAMF,OAAOL,KAAKU,IAAIH,EAAAA;AACtB,UAAIF,SAASM,OAAW,QAAO;AAC/BX,WAAKY,OAAOL,EAAAA;AACZL,cAAQM,IAAID,IAAIF,KAAKQ,YAAY;AACjC,aAAO;IACT;IAEAC,WAAAA;AACE,UAAIC;AACJ,iBAAWV,QAAQL,KAAKgB,OAAM,GAAI;AAGhC,YAAID,WAAWJ,UAAaN,KAAKQ,eAAeE,OAAOF,aAAcE,UAASV;MAChF;AACA,aAAOU;IACT;IAEAE,YAAYJ,cAAY;AACtB,UAAIK,UAAU;AACd,iBAAW,CAACX,IAAIF,IAAAA,KAASL,MAAM;AAC7B,YAAIK,KAAKQ,eAAeA,cAAc;AACpCb,eAAKY,OAAOL,EAAAA;AACZW,qBAAW;QACb;MACF;AAKA,iBAAW,CAACX,IAAIY,EAAAA,KAAOjB,SAAS;AAC9B,YAAIiB,KAAKN,aAAcX,SAAQU,OAAOL,EAAAA;MACxC;AACA,aAAOW;IACT;EACF;AACF;AAlDgBnB;;;AC/BT,SAASqB,WACdC,QAAiB;AAEjB,SAAO,CAACC,UAAUC,aAAAA;AAChB,QAAIA,aAAaC,UAAaD,aAAa,IAAI;AAC7C,aAAOE,QAAQC,OACb,IAAIC,uBACF,UACA,0KACE,CAAA;IAGR;AACA,WAAON,OAAOO,IAAIL,UAAUD,QAAAA;EAC9B;AACF;AAfgBF;","names":["TheokitAgentError","ConcurrentQuestionError","TheokitAgentError","name","threadId","code","ConcurrentListenerError","QuestionAbandonedError","why","createAskBridge","pendingByThread","Map","pendingById","listeners","forget","id","delete","ask","question","has","Promise","reject","listener","get","undefined","crypto","randomUUID","promise","resolve","entry","settle","answer","fail","error","set","notify","abandon","onAbandon","setListener","options","createPendingLedger","open","Map","settled","ingest","items","item","has","id","set","settle","get","undefined","delete","messageIndex","findNext","oldest","values","pruneBefore","dropped","at","askUserVia","bridge","question","threadId","undefined","Promise","reject","QuestionAbandonedError","ask"]}
+{"version":3,"sources":["../src/ask/ask-bridge.ts","../src/ask/pending-ledger.ts","../src/ask/ask-user-via.ts"],"mappings":"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","names":["TheokitAgentError","ConcurrentQuestionError","TheokitAgentError","name","threadId","code","ConcurrentListenerError","QuestionAbandonedError","why","createAskBridge","pendingByThread","Map","pendingById","listeners","forget","id","delete","ask","question","has","Promise","reject","listener","get","undefined","crypto","randomUUID","promise","resolve","entry","settle","answer","fail","error","set","notify","abandon","onAbandon","setListener","options","createPendingLedger","open","Map","settled","ingest","items","item","has","id","set","settle","get","undefined","delete","messageIndex","findNext","oldest","values","pruneBefore","dropped","at","askUserVia","bridge","question","threadId","undefined","Promise","reject","QuestionAbandonedError","ask"]}