@theokit/sdk 1.6.2 → 1.8.0

package/dist/internal/plugins/types.d.cts

@@ -0,0 +1,102 @@
+/**
+ * Plugin contract types (T1.1, ADRs D97-D101).
+ *
+ * Discriminated union by `kind`:
+ *   - `"general"` — registers tools/hooks/commands via `register(ctx)`.
+ *   - `"model-provider"` — declares a `ProviderProfile` consumed by router.
+ *   - `"memory"` — supplies a memory provider factory.
+ *
+ * Hooks are a fixed enum (D100) to prevent sprawl; `pre_tool_call` supports
+ * veto via `{ block: true, message }` (D101) so plugins can implement safety
+ * guards without crashing the agent loop.
+ *
+ * @public
+ */
+import type { CustomTool } from "../../types/agent.js";
+import type { ProviderProfile } from "../providers/types.js";
+export type HookName = "pre_tool_call" | "post_tool_call" | "pre_llm_call" | "post_llm_call" | "on_session_start" | "on_session_end" | "transform_tool_result" | "transform_llm_output" | "pre_user_send" | "post_assistant_reply";
+export interface PreToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+    agentId: string;
+    runId: string;
+}
+export interface PreToolCallDecision {
+    block: true;
+    message: string;
+}
+/**
+ * Context passed to `pre_user_send` hook handlers (ADR D145).
+ *
+ * @public
+ */
+export interface PreUserSendContext {
+    prompt: string;
+    agentId: string;
+    runId: string;
+    /** Caller-supplied memory context, flowing through from `AgentOptions.memoryContext`. */
+    memoryContext?: import("../../types/memory-adapter.js").MemoryContext;
+    /** Forwarded `AbortSignal` so adapter recall HTTP can be cancelled mid-flight (EC-H). */
+    signal?: AbortSignal;
+}
+/**
+ * Optional result returned by `pre_user_send` handlers. The agent loop
+ * concatenates `recalledContext` from all handlers and injects it as a
+ * `<memory-context>...</memory-context>` block before the user prompt.
+ *
+ * @public
+ */
+export interface PreUserSendResult {
+    recalledContext?: string;
+}
+/**
+ * Context passed to `post_assistant_reply` hook handlers (ADR D145).
+ * Fire-and-forget — exceptions are caught and surfaced to stderr; the
+ * caller's `wait()` never blocks on this dispatch.
+ *
+ * @public
+ */
+export interface PostAssistantReplyContext {
+    prompt: string;
+    reply: string;
+    agentId: string;
+    runId: string;
+    memoryContext?: import("../../types/memory-adapter.js").MemoryContext;
+}
+export type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
+export type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
+export interface CommandOptions {
+    description?: string;
+}
+export 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;
+    /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
+    injectMessage(content: string, role?: "user" | "system"): void;
+}
+interface BasePlugin {
+    name: string;
+    version: string;
+}
+export type Plugin = (BasePlugin & {
+    kind: "general";
+    register: (ctx: PluginContext) => void | Promise<void>;
+}) | (BasePlugin & {
+    kind: "model-provider";
+    profile: ProviderProfile;
+}) | (BasePlugin & {
+    kind: "memory";
+    createProvider: MemoryProviderFactory;
+});
+/**
+ * Identity helper for plugin authors. TS-only convenience — preserves
+ * inferred type without forcing manual `Plugin` annotation.
+ *
+ * @public
+ */
+export declare function definePlugin<P extends Plugin>(p: P): P;
+export {};

package/dist/internal/providers/catalog-loader.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Dynamic provider catalog loader (T10.1, ADR D447).
+ *
+ * Loads provider metadata from `provider-catalog.json` at runtime.
+ * Malformed entries are skipped with WARN (EC-1) — never crash.
+ *
+ * @internal
+ */
+import type { ApiMode, AuthType } from "./types.js";
+export interface ProviderCapabilities {
+    supportsToolUse: boolean;
+    supportsVision: boolean;
+    supportsStructuredOutput: boolean;
+    supportsStreaming: boolean;
+    supportsCacheControl: boolean;
+    maxContextTokens?: number;
+    maxOutputTokens?: number;
+}
+export interface CatalogEntry {
+    id: string;
+    displayName: string;
+    apiMode: ApiMode;
+    authType: AuthType;
+    baseUrl: string;
+    envVars: string[];
+    fallbackModels: string[];
+    capabilities: ProviderCapabilities;
+    aliases?: string[];
+    modelsUrl?: string;
+    hostname?: string;
+    extraHeaders?: Record<string, string>;
+}
+interface LoadOptions {
+    _testInjectMalformed?: boolean;
+}
+export declare function loadProviderCatalog(opts?: LoadOptions): Record<string, CatalogEntry>;
+export declare function getCatalogCapabilities(providerId: string): ProviderCapabilities | undefined;
+export declare function registerCatalogProviders(opts?: LoadOptions): void;
+export {};

package/dist/internal/runtime/agent-session-store.d.ts

@@ -1,3 +1,3 @@
-import type { SessionMessage } from "./agent-session.js";
+import type { SessionMessage } from "./session-types.js";
 export declare function sessionFilePath(cwd: string, agentId: string): string;
 export declare function readSessionFile(cwd: string, agentId: string): Promise<SessionMessage[]>;

package/dist/internal/runtime/agent-session.d.ts

@@ -1,2 +1,3 @@
+import type { SessionMessage } from "./session-types.js";
 export declare function getSessionMessages(agentId: string): SessionMessage[];
 export declare function clearSession(agentId: string): void;

package/dist/internal/runtime/budget-tracker.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `BudgetTracker` — runtime contract for budget/usage tracking in the
+ * agent loop (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface inversion).
+ *
+ * This interface is the FOUNDATION for the eventual extraction of the
+ * Budget subsystem to `@theokit/sdk-budget`. The kernel depends on this
+ * contract (not on `UsageAccumulator` / `IterationBudget` concrete classes)
+ * so the implementation can move to a separate package without circular
+ * imports.
+ *
+ * Until Phase 2 completes, the legacy `UsageAccumulator` + `IterationBudget`
+ * remain wired in `internal/agent-loop/loop.ts` as the default impl. Future
+ * iterations:
+ *   - Refactor `Agent.create` to accept `budgetTracker?: BudgetTracker`.
+ *   - When provided, agent-loop uses it; when absent, falls back to the
+ *     internal default for back-compat.
+ *   - Move the default impl to `@theokit/sdk-budget` (extracted package).
+ *   - Phase 6 cohort: drop the internal default, require explicit tracker.
+ *
+ * @public — surface-level interface; impl is internal-but-replaceable.
+ */
+/** Single usage event recorded during one LLM call. */
+export interface BudgetUsageEvent {
+    /** Token count for this event. */
+    readonly tokens: number;
+    /** Provider/model identifier (e.g., `"openai/gpt-4o-mini"`). */
+    readonly model: string;
+    /** Whether this is an input (prompt) or output (completion) measurement. */
+    readonly type: "input" | "output";
+    /** Optional ISO 8601 timestamp; defaults to now() if omitted. */
+    readonly at?: string;
+}
+/** Decision the tracker returns on each iteration / pre-flight check. */
+export interface BudgetCheck {
+    /** Whether the agent loop is allowed to proceed. */
+    readonly allowed: boolean;
+    /**
+     * When `allowed` is false, names the reason in a stable, codemod-friendly
+     * form. Consumers map this to retry / surface to user / abort behavior.
+     */
+    readonly reason?: "budget_exceeded" | "iteration_limit" | "cost_limit" | "token_limit" | "custom";
+    /** Free-form details for logs / diagnostics. */
+    readonly detail?: string;
+}
+/** Aggregate snapshot of usage so far. */
+export interface BudgetTotal {
+    /** Sum of all input + output tokens. */
+    readonly tokens: number;
+    /** USD cost when pricing data is available; `undefined` otherwise. */
+    readonly costUsd?: number;
+    /** Iteration count if the impl tracks it. */
+    readonly iterations?: number;
+}
+/**
+ * The kernel-facing contract. Implementations live OUTSIDE the agent loop
+ * (in `@theokit/sdk-budget` after Phase 2 / in `internal/budget/` until then).
+ *
+ * Implementations MUST be:
+ *   - **Synchronous** — every method returns a value, never a Promise.
+ *     `track()` is on the hot path (called on every iteration); async would
+ *     bloat the loop with floating promises and force every call site to
+ *     await.
+ *   - **Non-throwing in track()** — record-only semantics. Validation
+ *     failures bubble up via `check()` instead.
+ */
+export interface BudgetTracker {
+    /** Record a single usage event. MUST be synchronous and non-throwing. */
+    track(event: BudgetUsageEvent): void;
+    /** Pre-flight check before the next iteration. */
+    check(): BudgetCheck;
+    /** Snapshot of accumulated totals (for telemetry / final reporting). */
+    getTotal(): BudgetTotal;
+}

package/dist/internal/runtime/{context-manager.d.ts → context/context-manager.d.ts}

@@ -1,4 +1,4 @@
-import type { ContextSettings, ContextSnapshot, SDKContextManager } from "../../types/context.js";
+import type { ContextSettings, ContextSnapshot, SDKContextManager } from "../../../types/context.js";
 export declare class FileContextManager implements SDKContextManager {
     private readonly cwd;
     private readonly settings;

package/dist/internal/runtime/{fixture-events.d.ts → fixtures/fixture-events.d.ts}

@@ -1,4 +1,4 @@
-import type { SDKAssistantMessage, SDKRequestMessage, SDKStatusMessage, SDKSystemMessage, SDKTaskMessage, SDKThinkingMessage, SDKToolUseMessage, SDKUserMessageEvent } from "../../types/messages.js";
+import type { SDKAssistantMessage, SDKRequestMessage, SDKStatusMessage, SDKSystemMessage, SDKTaskMessage, SDKThinkingMessage, SDKToolUseMessage, SDKUserMessageEvent } from "../../../types/messages.js";
 import type { FixtureRequest } from "./fixture-types.js";
 export declare function systemEvent(request: FixtureRequest, tools: string[]): SDKSystemMessage;
 export declare function userEvent(request: FixtureRequest): SDKUserMessageEvent;

package/dist/internal/runtime/{fixture-run-base.d.ts → fixtures/fixture-run-base.d.ts}

@@ -1,7 +1,7 @@
-import type { ModelSelection } from "../../types/agent.js";
-import type { ConversationTurn } from "../../types/conversation.js";
-import type { SDKMessage } from "../../types/messages.js";
-import type { Run, RunOperation, RunResult, RunStatus } from "../../types/run.js";
+import type { ModelSelection } from "../../../types/agent.js";
+import type { ConversationTurn } from "../../../types/conversation.js";
+import type { SDKMessage } from "../../../types/messages.js";
+import type { Run, RunOperation, RunResult, RunStatus } from "../../../types/run.js";
 import type { FixtureScript } from "./fixture-types.js";
 export declare abstract class FixtureRunBase implements Run {
     readonly id: string;

package/dist/internal/runtime/{fixture-scripts.d.ts → fixtures/fixture-scripts.d.ts}

@@ -1,5 +1,5 @@
 import type { FixtureRequest, FixtureScript } from "./fixture-types.js";
-export { extractMemoryFact, isMemoryWritePrompt } from "./memory-store.js";
+export { extractMemoryFact, isMemoryWritePrompt } from "../memory-store.js";
 export declare function isMemoryRecallPrompt(message: string, request: FixtureRequest): boolean;
 export declare function memoryWriteScript(request: FixtureRequest): FixtureScript;
 export declare function memoryRecallScript(request: FixtureRequest): FixtureScript;

package/dist/internal/runtime/local-agent-bootstrap.d.ts

@@ -7,8 +7,8 @@
  *
  * @internal
  */
-import { FileContextManager } from "./context-manager.js";
-import { type PluginMetadata, PluginsManager } from "./plugins-manager.js";
+import { FileContextManager } from "./context/context-manager.js";
+import { type PluginMetadata, PluginsManager } from "./plugins/plugins-manager.js";
 import { ProvidersManagerImpl } from "./providers-manager.js";
 import { type SkillMetadata, SkillsManager } from "./skills-manager.js";
 export declare function registerLocalAgent(args: {

package/dist/internal/runtime/local-agent-memory-provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `createLocalAgentMemoryProvider` — bridges the legacy LocalAgentMemory
+ * rich impl (sdk-core's internal/memory/* subsystem) to the
+ * MemoryProvider port (SDK 2.0 Phase 1 physical Stage 2a — iter 19+).
+ *
+ * Goal: ONE memory path inside the kernel. Today there are TWO:
+ *   1. Legacy via `LocalAgentMemory` (when consumer didn't pass memoryProvider)
+ *   2. Port via `MemoryProvider` (when consumer passed memoryProvider in T1.3)
+ *
+ * This adapter wraps path 1 as a MemoryProvider, so the kernel can use
+ * the port uniformly. Stage 2b will refactor LocalAgent.send() to use
+ * the port + this adapter as default. Stage 3 will move the internal/
+ * memory/* sources to sdk-memory + ship a richer LanceDB-backed
+ * provider replacing this adapter.
+ *
+ * Why a separate file (not modifying LocalAgentMemory):
+ *   - Preserves LocalAgentMemory's existing public API for callers that
+ *     haven't migrated to the port yet.
+ *   - Adapter pattern: the rich logic stays where it is; the adapter
+ *     translates between LocalAgentMemory's signature and the port's.
+ *   - Allows incremental migration: kernel call sites move one at a
+ *     time from `memoryGlue.X()` direct calls to `provider.X(handle)`
+ *     calls.
+ *
+ * @internal — sdk-core's bridging glue. Replaced by sdk-memory rich impl
+ * in Stage 3.
+ */
+import type { TelemetryHandle } from "../telemetry/tracer.js";
+import type { MemoryProvider } from "./memory-provider.js";
+/**
+ * Options for `createLocalAgentMemoryProvider`. Mirrors what
+ * `LocalAgentMemory`'s constructor needs.
+ */
+export interface LocalAgentMemoryProviderOptions {
+    /** AgentOptions slice — required for memory subsystem config (cfg.memory). */
+    readonly agentOptions: AgentOptions;
+    /** Workspace cwd — used for `.theokit/memory/` paths. */
+    readonly workspaceCwd: string;
+    /** Agent id — required for per-agent cache + telemetry. */
+    readonly agentId: string;
+    /** Telemetry handle (optional) — forwarded to active-memory recall. */
+    readonly telemetry?: TelemetryHandle;
+}
+/**
+ * Build a `MemoryProvider` whose lifecycle methods delegate to an
+ * underlying `LocalAgentMemory` instance.
+ *
+ * Mapping:
+ *   - `init()`        → constructs LocalAgentMemory + warms tool cache via ensureTools()
+ *   - `buildTools()`  → wraps ensureTools() result, renaming `execute` to `handler`
+ *   - `runActivePass()` → calls runActiveMemoryIfEnabled() with synthesized args;
+ *                         returns the summary as `systemPromptAdditions`
+ *   - `sync()`        → calls syncIfReady()
+ *   - `dispose()`     → no-op (LocalAgentMemory's caches are per-agent + GC'd
+ *                       when the agent is GC'd)
+ */
+export declare function createLocalAgentMemoryProvider(opts: LocalAgentMemoryProviderOptions): MemoryProvider;

package/dist/internal/runtime/memory-path-selector.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Memory path selector (SDK 2.0 Phase 1 physical Stage 2b — iter 22).
+ *
+ * Pure helpers the future kernel flip will use to choose between
+ * legacy direct-call path and new MemoryProvider port path. Shipped
+ * in isolation so the helpers are tested + frozen BEFORE the actual
+ * `LocalAgent.send()` refactor wires them.
+ *
+ * Gate semantics (option A from the progress doc):
+ *   - Default: legacy path (zero behavior change).
+ *   - `THEOKIT_PORT_MEMORY_PATH=1` (env var): port path active.
+ *
+ * Why env var (vs option flag):
+ *   - Easy to flip on/off at runtime without rebuild.
+ *   - No public API surface added (the env var is internal-only;
+ *     consumers don't see it in their TypeScript types).
+ *   - Future iter can remove the env var once port path is the
+ *     unconditional default — no deprecation cycle on the public API.
+ *
+ * @internal
+ */
+import type { MemoryToolSpec } from "../agent-loop/loop-types.js";
+import type { MemoryProvider } from "./memory-provider.js";
+/** Env var name — internal, not in public docs yet. */
+export declare const PORT_MEMORY_PATH_ENV_VAR = "THEOKIT_PORT_MEMORY_PATH";
+/**
+ * Returns true when the port-memory-path should be active for this send.
+ *
+ * Checks both `process.env` (Node) and `globalThis.process?.env`
+ * (defensive — some test environments stub process differently).
+ */
+export declare function shouldUsePortMemoryPath(): boolean;
+/**
+ * Pick which `MemoryProvider` (if any) gets passed to the agent loop.
+ *
+ * Semantics:
+ *   - When consumer-supplied `options.memoryProvider` is set: ALWAYS
+ *     honor it (regardless of env flag). The flag only affects the
+ *     fall-back default.
+ *   - When consumer didn't supply AND port path enabled: return the
+ *     auto-installed `defaultMemoryProviderForLoop` (the adapter).
+ *   - When consumer didn't supply AND port path disabled: return
+ *     `undefined` (legacy path; agent-loop sees no provider).
+ */
+export declare function resolveMemoryProviderForLoop(consumerSupplied: MemoryProvider | undefined, defaultAdapter: MemoryProvider, portPathEnabled: boolean): MemoryProvider | undefined;
+/**
+ * Pick which `memoryTools` (if any) get passed to the agent loop's
+ * `inputs.memoryTools` field.
+ *
+ * Semantics:
+ *   - When port path active: return `undefined` (tools surface via
+ *     `provider.buildTools()` inside agent-loop instead — iter 18 T1.5.2).
+ *   - When port path inactive: return the legacy tools (from
+ *     `memoryGlue.ensureTools()`).
+ */
+export declare function resolveMemoryToolsForLoop(legacyTools: ReadonlyArray<MemoryToolSpec> | undefined, portPathEnabled: boolean): ReadonlyArray<MemoryToolSpec> | undefined;
+/**
+ * Pick the `activeMemorySummary` value to fold into the system-prompt
+ * assembly.
+ *
+ * Semantics:
+ *   - When port path active: return `undefined` (additions surface via
+ *     `provider.runActivePass()` inside agent-loop instead — iter 18 T1.5.3).
+ *   - When port path inactive: return the legacy summary (from
+ *     `memoryGlue.runActiveMemoryIfEnabled(...)`).
+ */
+export declare function resolveActiveMemorySummaryForSend(legacySummary: string | undefined, portPathEnabled: boolean): string | undefined;
+/**
+ * Type-only re-export for downstream consumers of the helpers.
+ * `CustomTool` is the port's tool shape; future iter may need it
+ * when assembling memoryTools via the port path.
+ */
+export type { CustomTool };

package/dist/internal/runtime/memory-provider.d.ts

@@ -0,0 +1,165 @@
+/**
+ * `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: ... })` (wiring
+ * lands in subsequent iteration).
+ *
+ * Design rationale (ADR-001 + ADR-003 in
+ * `sdk-2-0-phase-1-2-adr.md`):
+ *   - Memory subsystem is deeply integrated with the agent loop (active
+ *     memory pass, LLM tool injection, lifecycle ownership) — cannot
+ *     extract via plugin-protocol alone like Cache / Handoff.
+ *   - Interface inversion is the canonical FAANG-style answer: the kernel
+ *     defines what it NEEDS; impls satisfy the contract; package boundary
+ *     is the seam.
+ *   - Mirrors the `BudgetTracker` interface inversion (iter 10-16): same
+ *     pattern, different subsystem.
+ *
+ * Layered model (mirrors Budget):
+ *   - `MemoryAdapter` (existing 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.
+ */
+import type { CustomTool, SDKAgent } from "../../types/agent.js";
+import type { MemoryAdapter, MemoryFact } from "../../types/memory-adapter.js";
+/** Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call. */
+export interface ActiveMemoryPassResult {
+    /** Compressed memory facts to seed the LLM's context window for this turn. */
+    readonly facts: ReadonlyArray<MemoryFact>;
+    /** Optional system-prompt enrichment derived from the recalled facts. */
+    readonly systemPromptAdditions?: string;
+    /** Whether the active-memory circuit breaker tripped (degraded mode). */
+    readonly breakerTripped?: boolean;
+}
+/** Arguments for `MemoryProvider.runActivePass(...)`. */
+export interface ActiveMemoryPassArgs {
+    /** The current user message — used as the recall query. */
+    readonly userMessage: string;
+    /** Conversation history (most recent first). */
+    readonly history: ReadonlyArray<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+    /** Agent identity for scope. */
+    readonly agentId: string;
+}
+/**
+ * Arguments for `MemoryProvider.recordSessionSummary(...)`
+ * (SDK 2.0 Phase 1 physical Stage 3 prep — iter 27).
+ *
+ * The "session summary" is the markdown that gets written to disk
+ * after a finished run + indexed under `corpus="sessions"`. This
+ * port method lets sdk-core's `post-run-lifecycle.ts` delegate the
+ * write to the provider instead of importing
+ * `internal/memory/storage/session-summary-writer.ts` directly.
+ *
+ * @public
+ */
+export interface RecordSessionSummaryArgs {
+    /**
+     * Workspace cwd where on-disk artefacts live. Included on the args
+     * (not on a handle) because `recordSessionSummary` is STATELESS — it
+     * runs AFTER `runAgentLoop`'s `dispose()` releases the per-run handle.
+     * The kernel passes its own `workspaceCwd`; the impl uses it to
+     * compute the markdown file path.
+     */
+    readonly cwd: string;
+    /** Run id used as the filename key. */
+    readonly runId: string;
+    /** Agent identity for scope (foldering). */
+    readonly agentId: string;
+    /** Verbatim user message that started the run. */
+    readonly userText: string;
+    /** Final assistant text the run produced. */
+    readonly assistantText: string;
+    /** Final run status (only "finished" is recorded today). */
+    readonly status: "finished" | "error" | "cancelled";
+    /** Wall-clock ms at write time. */
+    readonly at: number;
+}
+/** Options for `MemoryProvider.init(...)`. */
+export interface MemoryProviderInitOptions {
+    /** Workspace cwd where on-disk artefacts live (`.theokit/memory/...`). */
+    readonly cwd: string;
+    /** Embedding-provider id (`"openai" | "ollama" | ...`); when omitted the impl picks a default. */
+    readonly embeddingProviderId?: string;
+}
+/**
+ * Opaque handle returned by `init()`. Carried back into other methods so
+ * the impl can stash per-agent state (index, breaker, cache, …) without
+ * exposing it to the kernel.
+ */
+export interface MemoryProviderHandle {
+    /** Adapter interface for direct read/write — matches existing `MemoryAdapter` shape. */
+    readonly adapter: MemoryAdapter;
+    /** Implementation-defined opaque field (private state pointer / index handle). */
+    readonly [implState: symbol]: unknown;
+}
+/**
+ * The kernel-facing contract. Implementations live OUTSIDE the agent loop
+ * (in `@theokit/sdk-memory` after Phase 1; in `internal/memory/` until then).
+ *
+ * Implementations MUST be:
+ *   - **Lazy** — `init()` may be called once per agent; subsequent calls
+ *     return the same handle (impl decides via cache). Heavy work
+ *     (loading the index, opening SQLite) deferred until first use.
+ *   - **Non-throwing on the hot path** — `runActivePass()` returns an
+ *     empty `facts: []` on degradation rather than throwing. Errors
+ *     surface via the breakerTripped flag + telemetry.
+ */
+export 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>;
+    /** Run the active-memory pre-LLM pass — recall + compress + format. */
+    runActivePass(handle: MemoryProviderHandle, args: ActiveMemoryPassArgs): Promise<ActiveMemoryPassResult>;
+    /**
+     * Optional post-run hook (SDK 2.0 Phase 1 physical Stage 1 — iter 19).
+     * Called by the agent loop AFTER a successful send so the impl can
+     * incorporate the session summary into its index (e.g., re-index the
+     * `sessions` corpus so the next recall sees it).
+     *
+     * Fire-and-forget at the call site; impl MUST be idempotent +
+     * non-throwing. Optional so existing impls (createNoopMemoryProvider,
+     * sdk-memory@0.1.0) keep working without modification.
+     *
+     * Mirrors the role of `LocalAgentMemory.syncIfReady()` in sdk-core's
+     * legacy memory path — exposing it via the port is the seam that
+     * unblocks moving LocalAgentMemory's logic out to sdk-memory.
+     */
+    sync?(handle: MemoryProviderHandle): Promise<void> | void;
+    /**
+     * Optional session-summary write hook (SDK 2.0 Phase 1 physical
+     * Stage 3 prep — iter 27, refined iter 28).
+     *
+     * Called by `post-run-lifecycle.ts` AFTER a finished run to persist
+     * the run's session-summary markdown under `corpus="sessions"`. When
+     * defined, the kernel delegates the write to the provider; when
+     * undefined, post-run-lifecycle falls back to the direct
+     * `writeSessionSummary` import (legacy path, until Stage 3 source
+     * move drops that import entirely).
+     *
+     * STATELESS — does NOT take a `MemoryProviderHandle` because post-run-
+     * lifecycle runs AFTER `runAgentLoop` disposed the per-run handle.
+     * `cwd` lives on `args` instead. Impls that need per-agent state can
+     * cache it via closure inside the provider factory.
+     *
+     * Impl MUST be non-throwing on the hot path. The kernel swallows
+     * any throw + emits a stderr warning.
+     *
+     * Optional so existing impls (createNoopMemoryProvider,
+     * createInMemoryMarkdownProvider) keep working without modification.
+     */
+    recordSessionSummary?(args: RecordSessionSummaryArgs): Promise<void> | void;
+    /** Release the handle (close index, flush caches). Idempotent + non-throwing. */
+    dispose(handle: MemoryProviderHandle): Promise<void> | void;
+}

package/dist/internal/runtime/{agent-registry.d.ts → registry/agent-registry-contract.d.ts}

@@ -1,4 +1,14 @@
-import type { AgentOptions, ModelSelection } from "../../types/agent.js";
+/**
+ * Whether an agent runs in the local or cloud runtime. Drives storage routing,
+ * fork semantics, and the cross-runtime UnsupportedRunOperationError contract
+ * (ADR D122).
+ */
+export type AgentRuntime = "local" | "cloud";
+/**
+ * In-memory agent registry record. Persisted via the
+ * `agent-registry-store.ts` serialization layer (which strips secrets per
+ * ADR D17 + D68 — see `stripSecretsFromOptions`).
+ */
 export interface RegisteredAgent {
     agentId: string;
     runtime: AgentRuntime;
@@ -9,8 +19,10 @@ export interface RegisteredAgent {
     lastModified: number;
     archived: boolean;
     options: AgentOptions;
-    /** Local workspace cwd; only set when runtime is local. Also used as the
-     * persistence routing key (cloud agents default to `process.cwd()`). */
+    /**
+     * Local workspace cwd; only set when runtime is local. Also used as the
+     * persistence routing key (cloud agents default to `process.cwd()`).
+     */
     cwd?: string;
     /** Cloud repo URLs; only set when runtime is cloud. */
     repos?: string[];
@@ -26,9 +38,3 @@ export interface RegisteredAgent {
      */
     requiresCustomStorage?: boolean;
 }
-export declare function registerAgent(agent: RegisteredAgent): void;
-export declare function getRegisteredAgent(agentId: string): RegisteredAgent | undefined;
-export declare function listRegisteredAgents(runtime?: AgentRuntime): RegisteredAgent[];
-export declare function updateRegisteredAgent(agentId: string, update: Partial<RegisteredAgent>): RegisteredAgent | undefined;
-export declare function removeRegisteredAgent(agentId: string): boolean;
-export declare function clearAgentRegistry(): void;

package/dist/internal/runtime/registry/agent-registry.d.ts

@@ -0,0 +1,7 @@
+import type { AgentRuntime, RegisteredAgent } from "./agent-registry-contract.js";
+export declare function registerAgent(agent: RegisteredAgent): void;
+export declare function getRegisteredAgent(agentId: string): RegisteredAgent | undefined;
+export declare function listRegisteredAgents(runtime?: AgentRuntime): RegisteredAgent[];
+export declare function updateRegisteredAgent(agentId: string, update: Partial<RegisteredAgent>): RegisteredAgent | undefined;
+export declare function removeRegisteredAgent(agentId: string): boolean;
+export declare function clearAgentRegistry(): void;

package/dist/internal/runtime/{live-agent-registry.d.ts → registry/live-agent-registry.d.ts}

@@ -17,7 +17,7 @@
  *
  * @public (singleton exposed via `Agent.registry`)
  */
-import type { SDKAgent } from "../../types/agent.js";
+import type { SDKAgent } from "../../../types/agent.js";
 export type EvictReason = "lru" | "idle" | "explicit";
 export interface AgentRegistryOptions {
     /**

package/dist/internal/runtime/{run-registry.d.ts → registry/run-registry.d.ts}

@@ -1,4 +1,4 @@
-import type { Run } from "../../types/run.js";
+import type { Run } from "../../../types/run.js";
 export declare function registerRun(run: Run): void;
 export declare function getRun(runId: string): Run | undefined;
 export declare function listRunsByAgent(agentId: string): Run[];