@theokit/sdk 1.6.1 → 1.7.0

package/dist/index.d.cts

@@ -1,10 +1,11 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-CK8brCJ1.cjs';
-export { A as AgentRunError, c as AgentRunErrorCode, d as AuthenticationError, e as BudgetExceedEvent, f as BudgetExceededError, g as BudgetLimit, h as BudgetMode, i as BudgetScope, j as BudgetThresholdEvent, k as BudgetWindow, C as ConfigurationError, E as ErrorCode, l as ErrorMetadata, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, o as TaskNotFoundError, U as UnknownAgentError, p as UnsupportedBudgetOperationError, q as UnsupportedRunOperationError, r as UnsupportedTaskOperationError } from './errors-CK8brCJ1.cjs';
-import { A as AgentOptions, R as RunResult, M as ModelSelection, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, a as MemorySettings, b as CustomTool, c as McpServerConfig, d as AgentDefinition, e as ContextSettings, f as PluginsSettings, g as SkillsSettings, h as SDKAgent, i as ListAgentsOptions, j as ListResult, k as SDKAgentInfo, G as GetAgentOptions, l as ListRunsOptions, m as Run, n as GetRunOptions, o as AgentOperationOptions, H as HandoffOptions, p as HandoffDescriptor, q as ConversationStorageAdapter, r as StoredMessage, s as MemoryId, t as SDKProvider, u as SDKMessage } from './run-DkCD5DeO.cjs';
-export { v as AgentConversationTurn, w as AgentMemory, x as AssistantMessage, y as CloudEnv, z as CloudRepo, B as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, I as ContextSourceStatus, J as ConversationStep, K as ConversationTurn, N as CostBreakdown, O as CostSource, Q as CostStatus, T as GoalEvent, U as GoalOptions, V as GoalResult, W as HandoffContext, X as HandoffHistory, Y as HandoffLoopError, Z as HandoffNameCollisionError, _ as HandoffPairLoopError, $ as HandoffReceiverDisposedError, a0 as HandoffResult, a1 as HandoffSelfReferenceError, a2 as InteractionUpdate, a3 as InvalidateCacheOptions, a4 as McpAuthConfig, a5 as McpHttpServerConfig, a6 as McpOAuthConfig, a7 as McpStdioServerConfig, a8 as MemoryAdapter, a9 as MemoryAdapterCapabilities, aa as MemoryContext, ab as MemoryFact, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as ModelParameterValue, ag as PartialToolCallUpdate, ah as PersonalityPreset, ai as ProviderCapability, aj as ProviderRoute, ak as ResolvedProviderRoute, al as RunErrorDetail, am as RunGitInfo, an as RunOperation, ao as RunStatus, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKAssistantMessage, au as SDKContextManager, av as SDKImage, aw as SDKImageDimension, ax as SDKObjectDelta, ay as SDKPluginMetadata, az as SDKProvidersManager, aA as SDKRequestMessage, aB as SDKStatusMessage, aC as SDKSystemMessage, aD as SDKTaskMessage, aE as SDKThinkingMessage, aF as SDKToolUseMessage, aG as SDKUserMessage, aH as SDKUserMessageEvent, aI as SendOptions, aJ as SettingSource, aK as ShellCommand, aL as ShellConversationTurn, aM as ShellOutput, aN as ShellOutputDeltaUpdate, aO as StepCompletedUpdate, aP as StepStartedUpdate, aQ as SummaryCompletedUpdate, aR as SummaryStartedUpdate, aS as SummaryUpdate, aT as SystemPromptContext, aU as SystemPromptMemoryFact, aV as SystemPromptSkillRef, aW as TelemetrySettings, aX as TextBlock, aY as TextDeltaUpdate, aZ as ThinkingCompletedUpdate, a_ as ThinkingDeltaUpdate, a$ as ThinkingMessage, b0 as TokenDeltaUpdate, b1 as TokenUsage, b2 as ToolCall, b3 as ToolCallCompletedUpdate, b4 as ToolCallStartedUpdate, b5 as ToolUseBlock, b6 as TurnEndedUpdate, b7 as UserMessage, b8 as UserMessageAppendedUpdate } from './run-DkCD5DeO.cjs';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-ChqOmFH1.cjs';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError } from './errors-ChqOmFH1.cjs';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ConversationStorageAdapter, m as StoredMessage, n as MemoryContext, B as BudgetTracker, o as MemoryProvider, p as MemoryId, q as SDKProvider } from './cron-BnywDYLq.cjs';
+export { r as ActiveMemoryPassArgs, s as ActiveMemoryPassResult, t as AgentMemory, u as BudgetCheck, v as BudgetTotal, w as BudgetUsageEvent, x as CloudEnv, y as CloudRepo, z as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, H as ContextSourceStatus, I as Cron, J as CronCreateOptions, K as CronGetOptions, N as CronJob, O as CronJobStatus, Q as CronListOptions, R as CronOperationOptions, T as CronRunOptions, U as CronRuntime, V as CronSchedulerStatus, W as CronStartOptions, X as GoalEvent, Y as GoalOptions, Z as GoalResult, _ as InvalidateCacheOptions, $ as MemoryAdapter, a0 as MemoryAdapterCapabilities, a1 as MemoryFact, a2 as MemoryProviderHandle, a3 as MemoryProviderInitOptions, a4 as MemoryRevision, a5 as MemoryToolSchema, a6 as MemoryTurnMessage, a7 as PersonalityPreset, a8 as ProviderCapability, a9 as ProviderRoute, aa as RecordSessionSummaryArgs, ab as ResolvedProviderRoute, ac as RunUntilIterator, ad as SDKAgentPlugins, ae as SDKAgentSkills, af as SDKArtifact, ag as SDKContextManager, ah as SDKPluginMetadata, ai as SDKProvidersManager, aj as SettingSource, ak as SystemPromptContext, al as SystemPromptMemoryFact, am as SystemPromptSkillRef, an as TelemetrySettings } from './cron-BnywDYLq.cjs';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-DrwUpFxZ.cjs';
+export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as SDKAssistantMessage, s as SDKImage, t as SDKImageDimension, u as SDKObjectDelta, v as SDKRequestMessage, w as SDKStatusMessage, x as SDKSystemMessage, y as SDKTaskMessage, z as SDKThinkingMessage, B as SDKToolUseMessage, D as SDKUserMessage, E as SDKUserMessageEvent, F as SendOptions, G as ShellCommand, H as ShellConversationTurn, J as ShellOutput, K as ShellOutputDeltaUpdate, L as StepCompletedUpdate, N as StepStartedUpdate, O as SummaryCompletedUpdate, Q as SummaryStartedUpdate, T as SummaryUpdate, U as TextBlock, V as TextDeltaUpdate, W as ThinkingCompletedUpdate, X as ThinkingDeltaUpdate, Y as ThinkingMessage, Z as TokenDeltaUpdate, _ as TokenUsage, $ as ToolCall, a0 as ToolCallCompletedUpdate, a1 as ToolCallStartedUpdate, a2 as ToolResult, a3 as ToolUseBlock, a4 as TurnEndedUpdate, a5 as UserMessage, a6 as UserMessageAppendedUpdate } from './run-DrwUpFxZ.cjs';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-1yxL3K2S.cjs';
 
 /**
  * Public types for `Agent.batch` (ADRs D134-D140).
@@ -765,6 +766,27 @@ declare class UsageAccumulator {
  * (preflight throw before LLM call).
  *
  * @public
+ *
+ * @deprecated since SDK 2.0 (iter 18+) — import this facade from
+ * `@theokit/sdk-budget` instead. The sources backing this facade have
+ * been physically extracted to `@theokit/sdk-budget/internal/` per
+ * ADR-008. The sdk-core copies are retained for the v1.x sync API
+ * contract; consumers MUST migrate before sdk-core v3.0.
+ *
+ * Migration:
+ *
+ * ```ts
+ * // Before (sdk-core, deprecated):
+ * import { Budget, computeCost } from "@theokit/sdk";
+ *
+ * // After (sdk-budget, authoritative):
+ * import {
+ *   chargeAndCheckThresholds,
+ *   createBudget,
+ *   computeUsdCost,  // replaces computeCost
+ *   createUsdBudgetTracker,
+ * } from "@theokit/sdk-budget";
+ * ```
  */
 
 declare class Budget {
@@ -799,232 +821,6 @@ declare class Budget {
     static snapshot(): readonly BudgetSnapshot[];
 }
 
-/**
- * ProviderProfile + ApiMode types (T3.1, ADR D105).
- *
- * Profile is **data-only** — no methods. Adding a provider is declaring an
- * object literal; the Transport layer (D106) consumes `apiMode` to pick
- * the HTTP dialect.
- *
- * @public
- */
-type ApiMode = "chat_completions" | "anthropic_messages" | "responses_api" | "bedrock" | "bedrock_anthropic";
-type AuthType = "api_key" | "oauth_device_code" | "oauth_external" | "aws_sdk" | "aws_bearer" | "gcp_oauth" | "none";
-interface ProviderProfile {
-    name: string;
-    apiMode: ApiMode;
-    aliases?: ReadonlyArray<string>;
-    displayName?: string;
-    description?: string;
-    signupUrl?: string;
-    envVars: ReadonlyArray<string>;
-    authType: AuthType;
-    baseUrl: string;
-    modelsUrl?: string;
-    hostname?: string;
-    fallbackModels: ReadonlyArray<string>;
-    extraHeaders?: Record<string, string>;
-    bodyOverrides?: Record<string, unknown>;
-}
-
-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";
-interface PreToolCallContext {
-    name: string;
-    args: Record<string, unknown>;
-    agentId: string;
-    runId: string;
-}
-interface PreToolCallDecision {
-    block: true;
-    message: string;
-}
-type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
-type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
-interface CommandOptions {
-    description?: string;
-}
-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;
-}
-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
- */
-declare function definePlugin<P extends Plugin>(p: P): P;
-
-/**
- * Public type contract for `Cache.semantic / .asPlugin / .stats / .clear`
- * (Adoption Roadmap #6; ADRs D249-D266).
- *
- * @public
- */
-interface CacheTTLConfig {
-    /** Default TTL applied to all entries. Format: `"1h" | "30m" | 86400 (seconds)`. */
-    readonly default: string | number;
-    /** Regex marking queries that must NEVER be cached (e.g. /weather|today|now/i). */
-    readonly exclude?: RegExp;
-}
-interface CachePersistenceOptions {
-    readonly backend: "memory" | "json";
-    /** Required when backend = "json". */
-    readonly dir?: string;
-}
-/**
- * Embedder runtime shape — minimal subset of `EmbeddingRuntime` (D11) the
- * Cache actually uses. Lets tests inject fake embedders without pulling
- * the full memory subsystem.
- */
-interface CacheEmbedderRuntime {
-    readonly id: string;
-    readonly model: string;
-    readonly dimension: number;
-    embed(texts: ReadonlyArray<string>): Promise<number[][]>;
-}
-interface CacheSemanticOptions {
-    /** Embedder instance. REQUIRED in v1 — no autoselect (avoids surprise API calls). */
-    readonly embedder: CacheEmbedderRuntime;
-    /** Cosine distance threshold (0..2). Default 0.85; lower = stricter. */
-    readonly threshold?: number;
-    /** TTL config. Default `{ default: "1h" }`. */
-    readonly ttl?: CacheTTLConfig;
-    /** Multi-tenant namespace. Default `"global"`. */
-    readonly namespace?: string;
-    /** Default modelId attached to entries when caller doesn't override. */
-    readonly modelId?: string;
-    /** Max entries (LRU eviction). Default 1000. */
-    readonly maxEntries?: number;
-    /** Persistence backend. Default in-memory. */
-    readonly persistence?: CachePersistenceOptions;
-}
-interface CacheEntry {
-    readonly key: string;
-    readonly namespace: string;
-    readonly embedderId: string;
-    readonly modelId: string;
-    readonly prompt: string;
-    readonly response: string;
-    readonly vector: ReadonlyArray<number>;
-    readonly createdAt: number;
-    readonly expiresAt: number;
-    readonly accessedAt: number;
-    readonly accessCount: number;
-}
-interface CacheStats {
-    readonly entries: number;
-    readonly kvHits: number;
-    readonly semanticHits: number;
-    readonly misses: number;
-    readonly excluded: number;
-    readonly evicted: number;
-    readonly embedderFailures: number;
-}
-declare class CacheEmbedderError extends Error {
-    readonly name = "CacheEmbedderError";
-    readonly cause?: Error;
-    constructor(message: string, cause?: Error);
-}
-declare class CacheInvalidTtlError extends Error {
-    readonly input: string | number;
-    readonly name = "CacheInvalidTtlError";
-    constructor(input: string | number);
-}
-
-/**
- * Public `Cache` class — semantic LLM response cache (Adoption Roadmap #6;
- * ADRs D249-D266).
- *
- * Usage:
- *
- *   import { Agent, Cache, definePlugin } from "@theokit/sdk";
- *
- *   const cache = Cache.semantic({
- *     embedder: myEmbedderRuntime,    // EmbeddingRuntime (D11)
- *     threshold: 0.85,
- *     ttl: { default: "1h", exclude: /weather|today|now/i },
- *     namespace: "my-app",
- *     modelId: "openai/gpt-4o-mini",
- *   });
- *
- *   const agent = await Agent.create({
- *     model: { id: "openai/gpt-4o-mini" },
- *     plugins: [cache.asPlugin()],
- *     // ...
- *   });
- *
- *   await agent.send("What is the capital of France?");   // miss → LLM
- *   await agent.send("Tell me the capital of France");    // semantic hit
- *
- * @public
- */
-
-declare class Cache {
-    private readonly embedder;
-    private readonly threshold;
-    private readonly ttl;
-    private readonly namespace;
-    private readonly modelId;
-    private readonly store;
-    private _plugin?;
-    private constructor();
-    static semantic(options: CacheSemanticOptions): Cache;
-    /**
-     * EC-4 absorbed: memoized so repeated `asPlugin()` calls return the SAME
-     * plugin descriptor — no duplicate hook registration.
-     */
-    asPlugin(): Plugin;
-    /**
-     * Explicit cache lookup — callers that want true LLM short-circuit
-     * call this BEFORE `agent.send()`, then dispatch to the LLM only on miss.
-     *
-     * v1 plugin mode provides recall + context-inject (LLM still called).
-     * v1.x will add transparent short-circuit via an agent-loop refactor.
-     */
-    consult(prompt: string): Promise<{
-        hit: false;
-    } | {
-        hit: true;
-        response: string;
-        source: "kv" | "semantic";
-        distance?: number;
-    }>;
-    /**
-     * Explicit cache store — pair with `consult()` to manually feed the
-     * cache after dispatching the LLM call yourself.
-     */
-    remember(prompt: string, response: string, opts?: {
-        usedTools?: boolean;
-    }): Promise<void>;
-    /** Stats snapshot — primary observable for dogfood verification. */
-    stats(): CacheStats;
-    /** Clear all entries (and flush to disk if JSON backend). */
-    clear(): Promise<void>;
-    /** Force-evict expired entries. Returns count removed. */
-    evictExpired(now?: number): number;
-}
-
 /**
  * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
  * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
@@ -1060,57 +856,27 @@ interface DefineToolSpec<T extends ZodType> {
 declare function defineTool<T extends ZodType>(spec: DefineToolSpec<T>): CustomTool;
 
 /**
- * Public `Handoff` class — factory for handoff descriptors (Adoption
- * Roadmap #4; ADRs D214-D229).
- *
- * Usage:
- *
- *   import { Agent, Handoff } from "@theokit/sdk";
- *
- *   const billing = await Agent.create({
- *     name: "billing",
- *     systemPrompt: "You handle billing questions.",
- *     model: { id: "openai/gpt-4o-mini" },
- *     apiKey: process.env.OPENROUTER_API_KEY,
- *   });
+ * `EventBus` — typed EventEmitter wrapper.
  *
- *   const triage = await Agent.create({
- *     name: "triage",
- *     systemPrompt: "Classify the user's intent and transfer to the right specialist.",
- *     model: { id: "openai/gpt-4o-mini" },
- *     apiKey: process.env.OPENROUTER_API_KEY,
- *     handoffs: [
- *       billing,  // auto-wrapped as Handoff.create(billing)
- *       Handoff.create(supportAgent, { inputFilter: redactCreditCards }),
- *     ],
- *   });
- *
- * @public
+ * Provides type-safe publish/subscribe with automatic unsubscribe cleanup.
+ * Each handler is try-caught (EC-2) so one failing handler cannot break others.
  */
-
-/** Recommended system-prompt prefix for senders (D215 / EC-13). */
-declare const RECOMMENDED_HANDOFF_PROMPT_PREFIX: string;
-declare class Handoff {
-    private constructor();
+type EventHandler<T> = (payload: T) => void;
+declare class EventBus<Events extends Record<string, unknown>> {
+    private handlers;
     /**
-     * Build a `HandoffDescriptor` for a target agent. Wrap with custom options
-     * (filter / inputType / callback / whitelist / etc); pass to
-     * `Agent.create({ handoffs: [...] })`.
-     *
-     * Raw `SDKAgent` instances in `handoffs[]` are auto-wrapped by the runtime
-     * — call `Handoff.create()` explicitly only when you need to customize.
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    subscribe<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
+    /**
+     * Publish an event to all subscribers. EC-2: try-catch per handler.
+     */
+    publish<K extends keyof Events>(event: K, payload: Events[K]): void;
+    /**
+     * Subscribe to an event for a single firing. Returns an unsubscribe function.
      */
-    static create<TInput extends ZodType = ZodType>(target: SDKAgent, options?: HandoffOptions<TInput>): HandoffDescriptor<TInput>;
+    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
 }
-/**
- * Imperative escape hatch (D225). Useful for tests / programmatic flows
- * that need deterministic handoff without LLM routing.
- *
- * NOTE: this is a STANDALONE helper rather than a method on `SDKAgent`
- * to avoid invasive refactor of the agent class. Behavior is identical
- * to invoking the corresponding synthetic tool would be.
- */
-declare function handoffTo(sender: SDKAgent, target: SDKAgent, message: string, options?: HandoffOptions): Promise<string>;
 
 /**
  * Filesystem-backed implementation of {@link ConversationStorageAdapter}
@@ -1175,6 +941,218 @@ declare class InMemoryConversationStorage implements ConversationStorageAdapter
     dispose(): Promise<void>;
 }
 
+declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * ProviderProfile + ApiMode types (T3.1, ADR D105).
+ *
+ * Profile is **data-only** — no methods. Adding a provider is declaring an
+ * object literal; the Transport layer (D106) consumes `apiMode` to pick
+ * the HTTP dialect.
+ *
+ * @public
+ */
+type ApiMode = "chat_completions" | "anthropic_messages" | "responses_api" | "bedrock" | "bedrock_anthropic";
+type AuthType = "api_key" | "oauth_device_code" | "oauth_external" | "aws_sdk" | "aws_bearer" | "gcp_oauth" | "none";
+interface ProviderProfile {
+    name: string;
+    apiMode: ApiMode;
+    aliases?: ReadonlyArray<string>;
+    displayName?: string;
+    description?: string;
+    signupUrl?: string;
+    envVars: ReadonlyArray<string>;
+    authType: AuthType;
+    baseUrl: string;
+    modelsUrl?: string;
+    hostname?: string;
+    fallbackModels: ReadonlyArray<string>;
+    extraHeaders?: Record<string, string>;
+    bodyOverrides?: Record<string, unknown>;
+}
+
+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";
+interface PreToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+    agentId: string;
+    runId: string;
+}
+interface PreToolCallDecision {
+    block: true;
+    message: string;
+}
+/**
+ * Context passed to `pre_user_send` hook handlers (ADR D145).
+ *
+ * @public
+ */
+interface PreUserSendContext {
+    prompt: string;
+    agentId: string;
+    runId: string;
+    /** Caller-supplied memory context, flowing through from `AgentOptions.memoryContext`. */
+    memoryContext?: 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
+ */
+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
+ */
+interface PostAssistantReplyContext {
+    prompt: string;
+    reply: string;
+    agentId: string;
+    runId: string;
+    memoryContext?: MemoryContext;
+}
+type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
+type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
+interface CommandOptions {
+    description?: string;
+}
+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;
+}
+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
+ */
+declare function definePlugin<P extends Plugin>(p: P): P;
+
+/**
+ * Reference `BudgetTracker` impl — pure token + iteration counter
+ * (SDK 2.0 Phase 2 / T2.1 — ADR D1 reference implementation).
+ *
+ * Counts tokens per type (input/output) + iteration count. Enforces
+ * optional `maxTokens` / `maxIterations` ceilings via `check()`.
+ *
+ * Does NOT compute USD cost — leaves that to richer impls in
+ * `@theokit/sdk-budget` (post-Phase-2). This file is intentionally
+ * minimal so consumers can:
+ *   - use it as-is for simple guard-rails;
+ *   - read it as a worked example before authoring a custom tracker;
+ *   - rely on it as a fallback before sdk-budget ships.
+ *
+ * @public — surface-level reference impl.
+ */
+
+/** Options for `createCounterBudgetTracker`. */
+interface CounterBudgetTrackerOptions {
+    /** Hard ceiling on total tokens (input + output). When reached, `check()` returns `allowed: false`. */
+    readonly maxTokens?: number;
+    /** Hard ceiling on iterations counted by `nextIteration()`. */
+    readonly maxIterations?: number;
+}
+/**
+ * Build a fresh tracker. The returned object is independent — call
+ * `createCounterBudgetTracker()` per Agent instance.
+ *
+ * The tracker exposes the `BudgetTracker` contract PLUS a `nextIteration()`
+ * helper for impls that want explicit iteration counting (the agent loop
+ * calls it once per turn). Without `nextIteration()` calls, the iteration
+ * cap is never reached.
+ */
+declare function createCounterBudgetTracker(options?: CounterBudgetTrackerOptions): BudgetTracker & {
+    nextIteration(): void;
+};
+
+/**
+ * Reference `MemoryProvider` impl — no-op fallback (SDK 2.0 Phase 1 /
+ * T1.2 reference implementation, mirrors `createCounterBudgetTracker`).
+ *
+ * Every method is a degenerate identity:
+ *   - `init()` returns a handle wrapping a no-op `MemoryAdapter`.
+ *   - `buildTools()` returns `[]` (no memory tools surfaced to the LLM).
+ *   - `runActivePass()` returns `{ facts: [] }` (no recall fires).
+ *   - `dispose()` is a no-op.
+ *
+ * Why ship this:
+ *   - Default safety net before `@theokit/sdk-memory` is installed.
+ *   - Worked reference for authors of custom providers.
+ *   - Enables `Agent.create({ memoryProvider: createNoopMemoryProvider() })`
+ *     unit tests without pulling memory infrastructure.
+ *
+ * NOT a substitute for the existing `Memory` class — the legacy class
+ * stays authoritative until the subsystem fully ports to providers
+ * (Phase 1 / T1.6).
+ *
+ * @public — surface-level reference impl.
+ */
+
+/**
+ * Build a fresh no-op MemoryProvider. The returned object is independent —
+ * call `createNoopMemoryProvider()` per Agent instance. `init()` is
+ * idempotent: subsequent calls return a NEW handle (no per-agent cache —
+ * the no-op has no state worth caching).
+ */
+declare function createNoopMemoryProvider(): MemoryProvider;
+
+/**
+ * `JobQueue` — background job queue with status tracking.
+ *
+ * EC-1: all enqueued functions are wrapped in Promise.resolve().then()
+ * to ensure synchronous throws become rejections.
+ */
+type JobStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+interface Job<T> {
+    id: string;
+    status: JobStatus;
+    result?: T;
+    error?: string;
+}
+declare class JobQueue {
+    private jobs;
+    /**
+     * Enqueue a background function. Returns the job ID immediately.
+     * EC-1: wraps fn in Promise.resolve().then() so sync throws are caught.
+     */
+    enqueue<T>(fn: () => Promise<T>): string;
+    getJob(id: string): Job<unknown> | undefined;
+    list(): Job<unknown>[];
+    /**
+     * Cancel a pending or running job. Returns true if cancelled.
+     */
+    cancel(id: string): boolean;
+}
+
 /**
  * Public handle to an open memory index. Mirrors the internal `MemoryIndex`
  * contract structurally; defined here (NOT re-exported from internal/) so
@@ -1362,6 +1340,28 @@ interface MigrateResult {
  */
 declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateResult>;
 
+/**
+ * `PermissionEngine` — first-match permission rules for tool invocations.
+ *
+ * Evaluates a tool name against an ordered list of rules.
+ * First matching rule wins; default is "allow" when no rule matches.
+ */
+type PermissionAction = "allow" | "deny" | "ask";
+interface PermissionRule {
+    /** Tool name (exact string) or pattern (RegExp). */
+    tool: string | RegExp;
+    /** Action to take when rule matches. */
+    action: PermissionAction;
+}
+declare class PermissionEngine {
+    private readonly rules;
+    constructor(rules: PermissionRule[]);
+    /**
+     * Evaluate a tool name against the rules. First match wins; default "allow".
+     */
+    evaluate(toolName: string): PermissionAction;
+}
+
 /**
  * Public security namespace (T2.1, ADR D68).
  *
@@ -1650,6 +1650,25 @@ declare class Task {
     static subscribe(id: string): AsyncIterable<TaskEvent>;
 }
 
+/**
+ * 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
+ */
+
+interface ProviderCapabilities {
+    supportsToolUse: boolean;
+    supportsVision: boolean;
+    supportsStructuredOutput: boolean;
+    supportsStreaming: boolean;
+    supportsCacheControl: boolean;
+    maxContextTokens?: number;
+    maxOutputTokens?: number;
+}
+
 /**
  * Account-level user info returned by `Theokit.me()`.
  *
@@ -1751,6 +1770,7 @@ declare class Theokit {
      */
     static readonly models: {
         list: (options?: TheokitRequestOptions) => Promise<SDKModel[]>;
+        capabilities: (providerOrModelId: string) => ProviderCapabilities | undefined;
     };
     /**
      * Connected GitHub repositories for the calling user's team. Cloud only.
@@ -1875,4 +1895,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, Cache, CacheEmbedderError, type CacheEmbedderRuntime, type CacheEntry, CacheInvalidTtlError, type CachePersistenceOptions, type CacheSemanticOptions, type CacheStats, type CacheTTLConfig, CloudOptions, ContextSettings, ConversationStorageAdapter, CustomTool, type DeepPartial, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, Handoff, HandoffDescriptor, HandoffOptions, type HookName, InMemoryConversationStorage, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type Plugin, type PluginContext, PluginsSettings, type PreToolCallContext, type PreToolCallDecision, type ProviderProfile, ProviderRoutingSettings, RECOMMENDED_HANDOFF_PROMPT_PREFIX, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, StoredMessage, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createAgentFactory, definePlugin, defineTool, extractRawId, getPricingEntry, handoffTo, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory };
+export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, PermissionEngine, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, StoredMessage, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, definePlugin, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };