@theokit/sdk 4.63.3 → 5.0.0-next.1

package/dist/{agent-BFno7Sfn.d.ts → agent-CdYJfKr6.d.ts}

@@ -1,7 +1,10 @@
-import { m as MemoryFact, j as MemoryAdapter, S as SDKAgent, l as MemoryContext, D as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings } from './sdk-agent-D8qJVkuV.js';
-import { C as CustomTool, c as PermissionMode, M as ModelSelection, a as McpServerConfig, P as Processor } from './run-BYSHf58D.js';
+import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-ldzpyAaF.js';
+import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-CTAdRU3U.js';
 
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `SessionRecord` — the native on-disk transcript record shape (SE40).
  *
  * The theokit session format IS the Claude Code record shape: a
@@ -103,6 +106,9 @@ interface SessionRecord {
 }
 
 /**
+ * Owner: `internal/session/` (4 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
  *
  * A minimal, two-method port so an external store (Postgres / Redis / KV /
@@ -118,6 +124,19 @@ interface SessionRecord {
  * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
  * consumer change). Injected via `local.sessionStore` for external stores.
  *
+ * THIS SEAM DOES NOT HIDE THE STORAGE, AND IS NOT MEANT TO. A Repository
+ * abstracts a persistence model away; this one is defined in terms of the
+ * native one — the port speaks {@link SessionRecord}, "the exact SessionRecord
+ * the SDK writes", and the on-disk layout's path helpers (`encodeProjectDir`,
+ * `transcriptPath`, `transcriptRoot`) are published on purpose at
+ * `@theokit/sdk/persistence` so a consumer can locate a transcript file.
+ *
+ * That is the whole design and the reason the seam is two methods rather than
+ * ten: the format is the contract, and a store implements read/append over it.
+ * A consumer supplying `local.sessionStore` is NOT bound by those paths — they
+ * describe where the DEFAULT `FsSessionStore` puts files, not where an external
+ * store must.
+ *
  * Consistency contract: `appendRecords` is append-only and ordering-preserving.
  * The FS default serializes appends per agent with a cross-process file lock;
  * external implementations own (and MUST document) their own concurrency
@@ -159,6 +178,35 @@ interface SessionStore {
      * which MUST throw on failure (a resume cannot proceed on a silent partial history).
      */
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    /**
+     * Claim the single-writer lease for `agentId`, if this store has one. OPTIONAL.
+     *
+     * The SDK calls it when an agent starts and skips it when absent, so a two-method store keeps
+     * working unchanged — declaring it here does not require it, which is the whole reason it is
+     * optional. What declaring it DOES is make the capability discoverable: the SDK probed for this
+     * method through an `as unknown` cast against an interface that never mentioned it, so a
+     * third-party store author — the serverless / multi-pod case this port exists to serve — read a
+     * two-method interface, implemented two methods, and never learned the hook was there.
+     *
+     * CONTRACT, and the half that matters: a rejection whose `name` is `"SessionBusyError"` PROPAGATES
+     * to the caller, because another process holding the session is a decision the caller has to make
+     * (`exec` forks to a new id). Any other rejection is treated as "no lease available here" —
+     * logged, and the turn proceeds without single-writer protection, since the write is best-effort
+     * by contract anyway.
+     */
+    acquire?(agentId: string): Promise<void>;
+    /**
+     * Release the lease `acquire` claimed, if this store has one. OPTIONAL.
+     *
+     * Called on agent disposal. A rejection is not handled specially.
+     */
+    release?(agentId: string): Promise<void>;
+    /**
+     * Release store-level resources — a connection pool, a file handle. OPTIONAL.
+     *
+     * Called once, on agent disposal, after {@link SessionStore.release}.
+     */
+    dispose?(): Promise<void>;
 }
 
 /**
@@ -210,13 +258,19 @@ interface CreateSkillSpec {
     /** SE21 — supporting documents (filename → content), like a filesystem skill's `references/`. */
     references?: Record<string, string>;
 }
-/** SE36 — `Skill.create` replaces `createSkill` (ADR 0015). @public */
+/** SE36 — `Skill.create` replaces `createSkill` (ADR 0015). @public  *
+ * `Skill.create` returns an **`InlineSkill`**, not a `Skill`. The class is the namespace;
+ * the inline skill descriptor is the product.
+ */
 declare class Skill {
     private constructor();
     static create(spec: CreateSkillSpec): InlineSkill;
 }
 
 /**
+ * Owner: `internal/budget/tracker/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `BudgetTracker` — runtime contract for budget/usage tracking in the
  * agent loop (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface inversion).
  *
@@ -295,25 +349,50 @@ interface BudgetTracker {
 }
 
 /**
- * A path that {@link resolveMemoryRoot} produced — the only thing the subsystem's path helpers
- * accept.
- *
- * The brand is what makes "every path derives from one resolution" a compiler rule rather than a
- * convention. Both a `cwd` and a root are strings, so without it the helpers would go on accepting
- * either, and the next one added would have the same even chance of taking the wrong one that
- * produced #463 in the first place. It costs one cast, at the one place a caller legitimately has a
- * directory that did not come from here.
- *
- * STRUCTURAL, not a `unique symbol`. A `unique symbol` brand is identity-based, and the d.ts
- * bundler inlines the declaration into each package that re-exports it — so `@theokit/sdk-memory`
- * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
- * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
- * the package boundary, which is where this type has to work.
+ * Owner: `internal/memory/storage/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * `MemoryProvider` — kernel-facing port for the memory subsystem
+ * (SDK 2.0 Phase 1 / T1.1 — Hexagonal Architecture / Ports & Adapters,
+ * SOLID Dependency Inversion).
+ *
+ * The agent loop kernel depends on THIS CONTRACT — not on the concrete
+ * `internal/memory/*` modules. Default adapter ships with `@theokit/sdk`
+ * (no-op for back-compat); rich impl ships in `@theokit/sdk-memory`.
+ * Consumers opt-in via `Agent.create({ memoryProvider: ... })`.
+ *
+ * DIP-correct home (SE46): the port + companion contract types live in the
+ * domain `types/` layer; the application-layer module
+ * (`internal/runtime/memory-glue/memory-provider.ts`) re-exports them for
+ * back-compat while the concrete providers live under `internal/`.
+ *
+ * Layered model (mirrors Budget):
+ *   - `MemoryAdapter` (in `types/memory-adapter.ts`) — LOW-LEVEL data port:
+ *     write / recall / delete primitives.
+ *   - `MemoryProvider` (THIS FILE) — HIGH-LEVEL lifecycle port: init,
+ *     tool factories, active memory pass, embedding runtime selection.
+ *
+ * @public — surface-level interface; impls are internal-but-replaceable.
  */
-type MemoryRoot = string & {
-    readonly __memoryRoot: "resolved";
-};
 
+/**
+ * The agent identity a `MemoryProvider` is given — the whole of it.
+ *
+ * `buildTools` used to declare `agent: SDKAgent`, a 33-member interface, and the agent loop satisfied
+ * it with `{ agentId, model } as SDKAgent`. The cast is what made it compile, and it suppressed
+ * exactly the check that mattered: an implementation reaching for any of the other 31 members —
+ * `send()`, `fork()`, `dispose()` — gets `undefined is not a function` at runtime with no
+ * compile-time signal.
+ *
+ * Two fields is what the port actually offers, so two fields is what it declares. `SDKAgent`
+ * structurally satisfies this, so a caller holding a real agent still passes it, and TypeScript's
+ * bivariant method parameters mean an existing implementation typed `agent: SDKAgent` still compiles.
+ * What changes is that the fabricated ref no longer needs a cast to exist.
+ */
+interface MemoryProviderAgentRef {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+}
 /** Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call. */
 interface ActiveMemoryPassResult {
     /** Compressed memory facts to seed the LLM's context window for this turn. */
@@ -411,7 +490,7 @@ interface MemoryProvider {
     /** Construct or fetch the per-agent handle. Lazy + idempotent. */
     init(opts: MemoryProviderInitOptions): Promise<MemoryProviderHandle>;
     /** Build the LLM-facing tool catalog (memory_search, memory_get, …). */
-    buildTools(handle: MemoryProviderHandle, agent: SDKAgent): ReadonlyArray<CustomTool>;
+    buildTools(handle: MemoryProviderHandle, agent: MemoryProviderAgentRef): ReadonlyArray<CustomTool>;
     /** Run the active-memory pre-LLM pass — recall + compress + format. */
     runActivePass(handle: MemoryProviderHandle, args: ActiveMemoryPassArgs): Promise<ActiveMemoryPassResult>;
     /**
@@ -455,8 +534,30 @@ interface MemoryProvider {
     /** Release the handle (close index, flush caches). Idempotent + non-throwing. */
     dispose(handle: MemoryProviderHandle): Promise<void> | void;
 }
+/**
+ * A directory that has been RESOLVED as a memory root, distinguished from a bare `cwd`.
+ *
+ * Structural rather than a `unique symbol` brand: a `unique symbol` is identity-based and the d.ts
+ * bundler inlines the declaration into each package that re-exports it, so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ *
+ * G7 / DIP — defined HERE, in the domain types layer, rather than in
+ * `internal/memory/storage/memory-root.ts`. It was defined in the adapter and reached for from this
+ * file, which made the port depend on the adapter for a field of its own argument type; the runtime
+ * helpers (`resolveMemoryRoot`, `asMemoryRoot`) stay in the adapter and import it from here.
+ *
+ * @public
+ */
+type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};
 
 /**
+ * Owner: `internal/providers/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * ProviderProfile + ApiMode + AuthType contract types (T3.1, ADR D105).
  *
  * Profile is **data-only** — no methods. Adding a provider is declaring an
@@ -746,6 +847,12 @@ type CommandHandler = (args: Record<string, unknown>) => Promise<string> | strin
 interface CommandOptions {
     description?: string;
 }
+/**
+ * Detaches a hook handler attached with {@link PluginContext.on}. Idempotent.
+ *
+ * @public
+ */
+type PluginHookDisposer = () => void;
 /**
  * The registration surface passed to a `"general"` plugin's `register(ctx)`, and the plugin's only
  * route into the agent. Outside production it is a sealed Proxy that throws when a plugin assigns a
@@ -760,14 +867,33 @@ interface CommandOptions {
  * has no effect on a programmatic run. And `on` drops a handler that is not a function, with a
  * warning on stderr rather than an error at registration: the gentler failure, and the easier one to
  * miss.
+ *
+ * `on` returns a {@link PluginHookDisposer}: calling it detaches that one handler, and calling it
+ * again is a no-op. A plugin that registers a hook per run and never detaches is the leak this
+ * exists to make fixable.
+ *
+ * @public
  */
 interface PluginContext {
     /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
     registerTool(tool: CustomTool): void;
     /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */
     registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;
-    /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */
-    on(hook: HookName, handler: HookHandler): void;
+    /**
+     * Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`.
+     *
+     * Returns a disposer that detaches THIS handler. Calling it twice is a no-op, and a handler the
+     * SDK refused (a non-function, which is warned and ignored) returns a disposer that does nothing —
+     * so the caller never has to branch on whether the registration took.
+     *
+     * It used to return `void`, which made this a one-way door: a plugin registered through
+     * `initialize()` had no removal path and its handlers ran for the life of the process. The one
+     * documented dynamic case — the ACP permission plugin, re-installed on every prompt — worked only
+     * because `#byName` keys the replacement, so re-registering the WHOLE plugin was the only way to
+     * detach one hook. Two observers in this package already return their own disposer
+     * (`FixtureRunBase.onDidChangeStatus`) or offer an explicit removal (`MessageBus.unregister`).
+     */
+    on(hook: HookName, handler: HookHandler): PluginHookDisposer;
     /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
     injectMessage(content: string, role?: "user" | "system"): void;
 }
@@ -816,6 +942,17 @@ type Plugin = (BasePlugin & {
  * @public
  */
 type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
+/**
+ * A foreign configuration dialect this SDK can read.
+ *
+ * A DIFFERENT axis from {@link SettingSource}, and collapsing the two would be wrong: that one is
+ * about SCOPE (user vs project, and the trust posture behind it), this one about which product's
+ * format a project wants imported. A project can legitimately want project scope with `.theokit/`
+ * only — which is now the default.
+ *
+ * @public
+ */
+type CompatSource = "claude-code";
 /**
  * A tool the SDK declares to the model on its own initiative — not one the consumer passed in
  * {@link AgentOptions.tools}, and not one an MCP server exposed.
@@ -860,6 +997,27 @@ interface LocalOptions {
      */
     cwd?: string | string[];
     settingSources?: SettingSource[];
+    /**
+     * Foreign configuration dialects to import. Default: none — `.theokit/` only.
+     *
+     * `.claude/` used to be read unconditionally across hooks, plugins, skills and subagents, so a
+     * repository that merely had Claude Code set up had its hooks executed, its skills folded into
+     * the system prompt and its subagents registered, having configured nothing for this SDK
+     * (usetheokit/theokit-sdk#524). One consequence was every turn being denied, because those hook
+     * commands are written against a runtime that defines `$CLAUDE_PROJECT_DIR` and this one did not
+     * (#522).
+     *
+     * A trust gate answers "do I trust the code in this directory?". That is a different question
+     * from "do I want another product's configuration imported into this one?", and they come apart
+     * in the ordinary case: a repository you trust completely is exactly where `.claude/` is
+     * populated — for a different tool, by a different contract, often by a teammate who never heard
+     * of this SDK.
+     *
+     * Listing a dialect is all-or-nothing for that dialect, and restores exactly the previous
+     * behaviour. On a name collision `.theokit/` wins: the native definition is the one the project
+     * wrote for this runtime.
+     */
+    compatSources?: CompatSource[];
     sandboxOptions?: {
         enabled: boolean;
     };
@@ -1435,12 +1593,18 @@ interface AgentOptions {
      * inversion). When provided, the agent loop calls `tracker.track(...)`
      * after each LLM completion and `tracker.check()` before each iteration.
      *
-     * **Status (Phase 2 incremental):** the option is wired to the type
-     * surface only. Agent-loop runtime wiring is additive and lands in a
-     * subsequent iteration — for now, the kernel still uses the legacy
-     * `UsageAccumulator` + `IterationBudget` from `internal/budget/`.
-     * Consumers passing a custom tracker today get the type guarantee but
-     * NOT runtime enforcement.
+     * **Runtime enforcement is live.** Verified against the call graph on
+     * 2026-09-01: `internal/agent-loop/loop.ts:78-81` reads the tracker and
+     * gates the iteration through `evaluateBudgetGate`, `:110` calls
+     * `nextIteration()`, and `:390`/`:397` call `track(...)` per completion;
+     * the option reaches the loop from `AgentOptions` at
+     * `internal/local-agent/real-local-run.ts:342`.
+     *
+     * This paragraph previously said the opposite — "wired to the type surface
+     * only ... NOT runtime enforcement" — and it was wrong in the expensive stale-claim-ok: verbatim quote of the corrected text
+     * direction: a consumer reading the published `.d.ts` was told the SDK would
+     * not enforce their cost ceiling, so the rational response was to build a
+     * second control outside it, or to stop trusting the option.
      *
      * Default impls available today via `@theokit/sdk`:
      *   - `createCounterBudgetTracker({ maxTokens, maxIterations })`
@@ -1459,12 +1623,17 @@ interface AgentOptions {
      * pre-LLM to inject recalled facts, and `provider.dispose(...)` on
      * Agent shutdown.
      *
-     * **Status (Phase 1 incremental):** the option is wired to the type
-     * surface only. Agent-loop runtime wiring is additive and lands in
-     * subsequent iterations (T1.4 plumbing, T1.5 runtime hooks). For now,
-     * the kernel still uses the legacy `Memory` class + `internal/memory/*`
-     * runtime files. Consumers passing a custom provider today get the type
-     * guarantee but NOT runtime enforcement.
+     * **Runtime enforcement is live.** Verified against the call graph on
+     * 2026-09-01: `internal/agent-loop/loop-context-init.ts:95` calls
+     * `provider.init(...)`, `:129` surfaces `provider.buildTools(...)` to the
+     * model, `:166` runs `provider.runActivePass(...)`, and
+     * `internal/agent-loop/loop.ts:176`/`:204` call `sync` and `dispose`.
+     *
+     * This paragraph previously said the opposite — "wired to the type surface
+     * only ... NOT runtime enforcement". A stale "not implemented yet" note on a stale-claim-ok: verbatim quote of the corrected text
+     * `@public` symbol is worse than no note: it is believed, it survives the
+     * work it describes, and nothing in this repo compares such a claim against
+     * the call graph.
      *
      * Default impls available today via `@theokit/sdk`:
      *   - `createNoopMemoryProvider()` — degenerate fallback / worked example
@@ -1653,4 +1822,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type SystemPromptMemoryFact as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type PluginContext as D, type PostAssistantReplyContext as E, type PostToolCallContext as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type PreToolCallContext as J, type PreUserSendContext as K, type LocalOptions as L, type MemorySettings as M, type PreUserSendResult as N, type ProviderTransform as O, type Plugin as P, type ProviderTransformContext as Q, type RecordSessionSummaryArgs as R, type SystemPromptResolver as S, type SessionLifecycleContext as T, type SessionRecord as U, type SessionStore as V, type SettingSource as W, Skill as X, type SkillsResolver as Y, type SkillsResolverContext as Z, type SystemPromptContext as _, type AgentDefinition as a, type TelemetrySettings as a0, type ToolCallSummary as a1, type ToolResultTransformContext as a2, type TransformContext as a3, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CreateSkillSpec as w, type MemoryProviderFactory as x, type MemoryProviderHandle as y, type MemoryProviderInitOptions as z };
+export { type SkillsResolver as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type MemoryProviderHandle as D, type MemoryProviderInitOptions as E, type PluginContext as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type PluginHookDisposer as J, type PostAssistantReplyContext as K, type LocalOptions as L, type MemorySettings as M, type PostToolCallContext as N, type PreToolCallContext as O, type Plugin as P, type PreUserSendContext as Q, type PreUserSendResult as R, type SystemPromptResolver as S, type ProviderTransform as T, type ProviderTransformContext as U, type RecordSessionSummaryArgs as V, type SessionLifecycleContext as W, type SessionRecord as X, type SessionStore as Y, type SettingSource as Z, Skill as _, type AgentDefinition as a, type SkillsResolverContext as a0, type SystemPromptContext as a1, type SystemPromptMemoryFact as a2, type TelemetrySettings as a3, type ToolCallSummary as a4, type ToolResultTransformContext as a5, type TransformContext as a6, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CompatSource as w, type CreateSkillSpec as x, type MemoryProviderAgentRef as y, type MemoryProviderFactory as z };