@theokit/sdk 1.6.1 → 1.7.0

package/dist/{run-DkCD5DeO.d.cts → cron-BnywDYLq.d.cts}

@@ -1,4 +1,4 @@
-import { ZodType } from 'zod';
+import { C as CustomTool, M as ModelSelection, D as SDKUserMessage, F as SendOptions, b as Run, a as McpServerConfig } from './run-DrwUpFxZ.cjs';
 
 /**
  * Public event types emitted by {@link SDKAgent.runUntil} (ADRs D115-D117).
@@ -96,218 +96,6 @@ interface GoalOptions {
     signal?: AbortSignal;
 }
 
-/**
- * Pluggable persistence for conversation history (Production-Readiness #1, ADRs D303-D306).
- *
- * The default {@link FileSystemConversationStorage} writes append-only JSONL
- * to `<cwd>/.theokit/agents/<id>/messages.jsonl`. Custom adapters back the
- * SDK against Postgres, Redis, Durable Objects, or any other store — required
- * for serverless deploys (Vercel, Cloudflare Workers) and multi-host setups
- * (K8s replicas, TheoCloud) where the filesystem is ephemeral or not shared.
- *
- * @public
- */
-/**
- * Persisted message envelope used by {@link ConversationStorageAdapter}.
- *
- * The shape is deliberately narrower than the full {@link SDKMessage} variant
- * tree — only durable content survives. `role` covers all message origins the
- * SDK persists today (user/assistant) plus the forward-compat slots for
- * tool-shaped messages (ADR D310 / EC-10).
- *
- * @public
- */
-interface StoredMessage {
-    /** Origin of the message. `tool_call` / `tool_result` reserved for forward compat. */
-    role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
-    /** UTF-8 payload. May be empty string (e.g., a tool with no return value). */
-    content: string;
-    /** Optional epoch-ms timestamp. Implementations MAY default to `Date.now()` on append. */
-    at?: number;
-}
-/**
- * Pluggable conversation persistence contract.
- *
- * Implementations MUST be safe under concurrent append from a single process
- * — the SDK runtime serializes per-(agent,cwd) but adapters serving multiple
- * processes are responsible for their own atomicity.
- *
- * All methods return `Promise<>` even for synchronous backends (in-memory).
- * Polymorphism uniformity beats the ~1μs microtask cost (ADR D306).
- *
- * @public
- */
-interface ConversationStorageAdapter {
-    /**
-     * Return the full message history for a conversation, in insertion order.
-     * MUST return `[]` (not throw) when the conversation does not exist.
-     */
-    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
-    /**
-     * Append a single message to the conversation.
-     * MUST be atomic — concurrent appends MUST NOT corrupt the log.
-     * MUST create the conversation lazily if it does not exist.
-     */
-    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
-    /**
-     * Delete the entire conversation. MUST be idempotent (delete-of-missing = ok).
-     */
-    deleteConversation(conversationId: string): Promise<void>;
-    /**
-     * Optional: list conversation ids. Used by housekeeping flows.
-     * Implementations that cannot enumerate (e.g., wildcards too expensive on
-     * production Redis) MAY return `undefined` to signal "not supported".
-     */
-    listConversationIds?(opts?: {
-        limit?: number;
-    }): Promise<readonly string[] | undefined>;
-    /**
-     * Optional FS-specific compaction trigger (ADR D304). The default FS adapter
-     * trims old turns past a soft cap; other backends typically no-op.
-     */
-    compact?(conversationId: string, maxTurns: number): Promise<void>;
-    /**
-     * Optional: dispose underlying handles (close DB pool, etc.).
-     * MUST be safe to call multiple times.
-     */
-    dispose?(): Promise<void>;
-}
-
-/**
- * Public types for `Agent.create({ handoffs })` + `Handoff.create()` +
- * `Agent.handoffTo()` (Adoption Roadmap #4; ADRs D214-D229).
- *
- * Pattern: handoff-as-tool. Each handoff destination becomes a synthetic
- * `transfer_to_<receiver>` function tool exposed to the LLM. Runtime
- * intercepts the tool call and routes the next turn to the receiver.
- *
- * @public
- */
-
-/**
- * Context handed to `onHandoff` callbacks and `isEnabled` predicates.
- * Read-only snapshot of the handoff dispatch state.
- */
-interface HandoffContext {
-    readonly senderAgentId: string;
-    readonly receiverAgentId: string;
-    /** Depth counter AT dispatch time (post-increment; first handoff = 1). */
-    readonly currentDepth: number;
-    /** Chain of agentIds traversed so far in this send(). Always ends with sender. */
-    readonly chain: ReadonlyArray<string>;
-}
-/**
- * The transcript wrapper passed to `inputFilter`. `messages` is widened to
- * `unknown[]` so this type doesn't import from `messages.ts` (avoids cycle
- * — implementations cast to `SDKMessage[]` internally).
- */
-interface HandoffHistory {
-    readonly messages: ReadonlyArray<unknown>;
-}
-/**
- * Options accepted by `Handoff.create(target, opts?)`.
- *
- * @public
- */
-interface HandoffOptions<TInput extends ZodType = ZodType> {
-    /** Override the default tool name `transfer_to_<receiver.name>` (D215). */
-    readonly toolName?: string;
-    /** Override the default tool description. */
-    readonly toolDescription?: string;
-    /**
-     * Side-effect callback fired BEFORE the receiver takes over.
-     *
-     * **Semantics (D227):** throwing aborts the handoff — the synthetic tool
-     * returns `tool_error: onHandoff_failed: <message>` so the LLM sees the
-     * conflict. Logger-style consumers MUST wrap their own try/catch to
-     * swallow exceptions.
-     */
-    readonly onHandoff?: (ctx: HandoffContext, parsed: TInput extends ZodType ? unknown : undefined) => void | Promise<void>;
-    /**
-     * Zod schema for the handoff tool-call arguments (structured payload).
-     * When set, LLM-provided args are validated before `onHandoff` fires.
-     *
-     * **Edge case (D229):** empty/null `inputJson` parses as `{}` before
-     * Zod refinements fire — required-field schemas still throw normally.
-     */
-    readonly inputType?: TInput;
-    /**
-     * Filter the history passed to the receiver (D216 default = full; D219).
-     *
-     * **Resilience (D228):** if this callback throws, the runtime logs once
-     * to stderr and falls back to the un-filtered history. Use this for
-     * privacy redaction; if you need fatal-on-failure semantics, throw in
-     * `onHandoff` instead.
-     */
-    readonly inputFilter?: (history: HandoffHistory) => HandoffHistory | Promise<HandoffHistory>;
-    /**
-     * Restrict the receiver's tools for the post-handoff turn ONLY (D224).
-     * Subsequent receiver-internal turns use the receiver's full tool set.
-     */
-    readonly tools?: ReadonlyArray<string>;
-    /**
-     * Dynamically enable/disable this handoff. Bool = static; predicate =
-     * called per-`Agent.send()` to evaluate.
-     */
-    readonly isEnabled?: boolean | ((ctx: HandoffContext) => boolean | Promise<boolean>);
-}
-/**
- * Result of a single handoff dispatch (for telemetry / observability).
- *
- * @public
- */
-interface HandoffResult {
-    readonly from: string;
-    readonly to: string;
-    readonly depth: number;
-    readonly toolName: string;
-    readonly reasonFromLlm?: string;
-}
-/** Throw when handoff depth exceeds `maxHandoffDepth` (default 5; D218). */
-declare class HandoffLoopError extends Error {
-    readonly name = "HandoffLoopError";
-    readonly depth: number;
-    readonly chain: ReadonlyArray<string>;
-    constructor(depth: number, chain: ReadonlyArray<string>);
-}
-/** Throw when the same (sender, receiver) pair invoked twice in one send() (D221). */
-declare class HandoffPairLoopError extends Error {
-    readonly name = "HandoffPairLoopError";
-    readonly senderAgentId: string;
-    readonly receiverAgentId: string;
-    constructor(senderAgentId: string, receiverAgentId: string);
-}
-/** Throw when an agent's `handoffs[]` includes a self-reference (EC-6). */
-declare class HandoffSelfReferenceError extends Error {
-    readonly name = "HandoffSelfReferenceError";
-    readonly agentId: string;
-    constructor(agentId: string);
-}
-/** Throw when receiver is disposed at dispatch time (EC-5). */
-declare class HandoffReceiverDisposedError extends Error {
-    readonly name = "HandoffReceiverDisposedError";
-    readonly receiverAgentId: string;
-    constructor(receiverAgentId: string);
-}
-/** Throw when two handoffs in the same parent collide on tool name (D215). */
-declare class HandoffNameCollisionError extends Error {
-    readonly name = "HandoffNameCollisionError";
-    readonly conflictingName: string;
-    constructor(conflictingName: string);
-}
-/**
- * Public `Handoff` shape — what `Handoff.create()` returns. Read-only
- * accessors only; behavior lives in the engine.
- *
- * @public
- */
-interface HandoffDescriptor<TInput extends ZodType = ZodType> {
-    readonly target: SDKAgent;
-    readonly options: HandoffOptions<TInput>;
-    /** Resolved tool name (after applying toolName override or default `transfer_to_<receiver>`). */
-    readonly resolvedToolName: string;
-}
-
 /**
  * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
@@ -484,6 +272,322 @@ interface AgentMemory {
     adapter(): MemoryAdapter | null;
 }
 
+/**
+ * `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.
+ */
+
+/** 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. */
+    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(...)`. */
+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
+ */
+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(...)`. */
+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.
+ */
+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.
+ */
+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;
+}
+
+/**
+ * `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. */
+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. */
+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. */
+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.
+ */
+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;
+}
+
+/**
+ * Pluggable persistence for conversation history (Production-Readiness #1, ADRs D303-D306).
+ *
+ * The default {@link FileSystemConversationStorage} writes append-only JSONL
+ * to `<cwd>/.theokit/agents/<id>/messages.jsonl`. Custom adapters back the
+ * SDK against Postgres, Redis, Durable Objects, or any other store — required
+ * for serverless deploys (Vercel, Cloudflare Workers) and multi-host setups
+ * (K8s replicas, TheoCloud) where the filesystem is ephemeral or not shared.
+ *
+ * @public
+ */
+/**
+ * Persisted message envelope used by {@link ConversationStorageAdapter}.
+ *
+ * The shape is deliberately narrower than the full {@link SDKMessage} variant
+ * tree — only durable content survives. `role` covers all message origins the
+ * SDK persists today (user/assistant) plus the forward-compat slots for
+ * tool-shaped messages (ADR D310 / EC-10).
+ *
+ * @public
+ */
+interface StoredMessage {
+    /** Origin of the message. `tool_call` / `tool_result` reserved for forward compat. */
+    role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
+    /** UTF-8 payload. May be empty string (e.g., a tool with no return value). */
+    content: string;
+    /** Optional epoch-ms timestamp. Implementations MAY default to `Date.now()` on append. */
+    at?: number;
+}
+/**
+ * Pluggable conversation persistence contract.
+ *
+ * Implementations MUST be safe under concurrent append from a single process
+ * — the SDK runtime serializes per-(agent,cwd) but adapters serving multiple
+ * processes are responsible for their own atomicity.
+ *
+ * All methods return `Promise<>` even for synchronous backends (in-memory).
+ * Polymorphism uniformity beats the ~1μs microtask cost (ADR D306).
+ *
+ * @public
+ */
+interface ConversationStorageAdapter {
+    /**
+     * Return the full message history for a conversation, in insertion order.
+     * MUST return `[]` (not throw) when the conversation does not exist.
+     */
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    /**
+     * Append a single message to the conversation.
+     * MUST be atomic — concurrent appends MUST NOT corrupt the log.
+     * MUST create the conversation lazily if it does not exist.
+     */
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    /**
+     * Delete the entire conversation. MUST be idempotent (delete-of-missing = ok).
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Optional: list conversation ids. Used by housekeeping flows.
+     * Implementations that cannot enumerate (e.g., wildcards too expensive on
+     * production Redis) MAY return `undefined` to signal "not supported".
+     */
+    listConversationIds?(opts?: {
+        limit?: number;
+    }): Promise<readonly string[] | undefined>;
+    /**
+     * Optional FS-specific compaction trigger (ADR D304). The default FS adapter
+     * trims old turns past a soft cap; other backends typically no-op.
+     */
+    compact?(conversationId: string, maxTurns: number): Promise<void>;
+    /**
+     * Optional: dispose underlying handles (close DB pool, etc.).
+     * MUST be safe to call multiple times.
+     */
+    dispose?(): Promise<void>;
+}
+
 /**
  * Context manager backend.
  *
@@ -578,71 +682,6 @@ interface SDKContextManager {
     snapshot(): Promise<ContextSnapshot>;
 }
 
-/**
- * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
- *
- * @public
- */
-type McpStdioServerConfig = {
-    type?: "stdio";
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-    /** Local agents only. Cloud rejects this field. */
-    cwd?: string;
-};
-/**
- * OAuth-style auth bundle for HTTP/SSE MCP servers.
- *
- * @public
- */
-interface McpAuthConfig {
-    CLIENT_ID: string;
-    CLIENT_SECRET?: string;
-    scopes?: string[];
-    /**
-     * OAuth 2.1 PKCE flow configuration (ADR D41, v1.2+). When present, the
-     * SDK runs the PKCE flow on first use and stores tokens via keychain or
-     * file. Without this, the SDK relies on `CLIENT_SECRET` + manual headers.
-     */
-    oauth?: McpOAuthConfig;
-}
-/**
- * OAuth 2.1 PKCE flow descriptor. See ADR D41.
- *
- * @public
- */
-interface McpOAuthConfig {
-    /** Authorization endpoint (e.g. https://api.notion.com/v1/oauth/authorize). */
-    authorizationEndpoint: string;
-    /** Token endpoint (e.g. https://api.notion.com/v1/oauth/token). */
-    tokenEndpoint: string;
-    /** Where the OAuth `code` is received. */
-    redirectMode: "manual" | "localhost";
-    /** Localhost callback port (0 = random free port, default). */
-    localhostPort?: number;
-    /** Flow timeout in ms (default 300_000 = 5min). */
-    timeoutMs?: number;
-}
-/**
- * HTTP or SSE MCP server.
- *
- * @public
- */
-type McpHttpServerConfig = {
-    type?: "http" | "sse";
-    url: string;
-    /** Passed through. `Authorization` works here. */
-    headers?: Record<string, string>;
-    auth?: McpAuthConfig;
-};
-/**
- * Union of MCP server configs. See `docs.md` for the full reference.
- *
- * @public
- */
-type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
-
 /**
  * Capability slot a provider can fulfill.
  *
@@ -746,26 +785,6 @@ interface SDKProvider {
     setupSchema: object;
 }
 
-/**
- * One slot in a {@link ModelSelection.params} array.
- *
- * @public
- */
-interface ModelParameterValue {
-    id: string;
-    value: string;
-}
-/**
- * Identifies a model plus optional per-model parameters (e.g. reasoning effort).
- *
- * Use `Theokit.models.list()` to discover valid ids and parameter definitions.
- *
- * @public
- */
-interface ModelSelection {
-    id: string;
-    params?: ModelParameterValue[];
-}
 /**
  * Which on-disk settings layers a local agent loads.
  *
@@ -983,38 +1002,6 @@ interface MemorySettings {
         persistTranscripts?: boolean;
     };
 }
-/**
- * Inline custom tool — registered with the LLM under the given name + schema
- * and dispatched locally to {@link CustomTool.handler} when the model emits a
- * `tool_use` for it.
- *
- * Local runtime only (SDK v1.0). Cloud agents reject `tools` (handlers cannot
- * cross the wire — use MCP servers or subagents for cloud tool surfaces).
- *
- * Handlers MUST be re-passed on `Agent.resume()` because closures cannot be
- * persisted. The tool catalog (name + description + schema) is NOT serialized.
- *
- * @public
- */
-interface CustomTool {
-    /**
-     * Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
-     * and must not collide with `shell`, `memory_search`, `memory_get`, or any
-     * `mcp_*` prefix (reserved for the SDK's built-in tools).
-     */
-    name: string;
-    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
-    description: string;
-    /** JSON Schema (Draft-7 subset) describing the `input` argument. Must be `type: "object"`. */
-    inputSchema: Record<string, unknown>;
-    /**
-     * Local handler invoked when the model emits `tool_use` for this tool.
-     * Returns a string (becomes the `tool_result.content` surfaced back to the
-     * model). Throws → SDK converts to `tool_result` with `isError: true` and
-     * the error `message` as content.
-     */
-    handler: (input: Record<string, unknown>) => string | Promise<string>;
-}
 /**
  * Telemetry configuration for an agent. When `enabled: true`, the SDK emits
  * OpenTelemetry spans for `agent.send`, `llm.call`, `tool.call`, and
@@ -1148,7 +1135,7 @@ interface AgentOptions {
      *
      * @public
      */
-    handoffs?: ReadonlyArray<SDKAgent | HandoffDescriptor>;
+    handoffs?: ReadonlyArray<SDKAgent | unknown>;
     /**
      * Maximum chain depth across handoffs per `agent.send()` call (D218).
      * Default 5. Exceeding throws `HandoffLoopError`. Set to 0 to disable
@@ -1251,7 +1238,52 @@ interface AgentOptions {
      *
      * @public
      */
-    conversationStorage?: ConversationStorageAdapter;
+    conversationStorage?: ConversationStorageAdapter;
+    /**
+     * Pluggable budget/usage tracker (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface
+     * 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.
+     *
+     * Default impls available today via `@theokit/sdk`:
+     *   - `createCounterBudgetTracker({ maxTokens, maxIterations })`
+     *
+     * Future: post-Phase-2, `@theokit/sdk-budget` ships a richer impl with
+     * USD pricing.
+     *
+     * @public
+     */
+    budgetTracker?: BudgetTracker;
+    /**
+     * Pluggable memory subsystem (SDK 2.0 Phase 1 / T1.3 — Hexagonal
+     * Architecture interface inversion). When provided, the agent loop
+     * calls `provider.init(...)` once per agent, surfaces tools from
+     * `provider.buildTools(...)` to the LLM, runs `provider.runActivePass(...)`
+     * 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.
+     *
+     * Default impls available today via `@theokit/sdk`:
+     *   - `createNoopMemoryProvider()` — degenerate fallback / worked example
+     *
+     * Future: post-Phase-1, `@theokit/sdk-memory` ships a rich impl with
+     * LanceDB / embeddings / circuit breaker / active-memory cache.
+     *
+     * @public
+     */
+    memoryProvider?: MemoryProvider;
 }
 /**
  * Artifact produced inside an agent's workspace. Cloud-only.
@@ -1515,667 +1547,221 @@ interface ListResult<T> {
 }
 
 /**
- * Single tool call event. The internal `args` and `result` shapes are NOT stable.
- *
- * @public
- */
-interface ToolCall {
-    callId: string;
-    name: string;
-    args?: unknown;
-    result?: unknown;
-}
-/**
- * Incremental text token from the assistant.
- *
- * @public
- */
-interface TextDeltaUpdate {
-    type: "text-delta";
-    text: string;
-}
-/**
- * Incremental reasoning token.
- *
- * @public
- */
-interface ThinkingDeltaUpdate {
-    type: "thinking-delta";
-    text: string;
-}
-/**
- * Emitted when a reasoning block completes.
- *
- * @public
- */
-interface ThinkingCompletedUpdate {
-    type: "thinking-completed";
-    thinkingDurationMs: number;
-}
-/**
- * Tool call started — args committed.
- *
- * @public
- */
-interface ToolCallStartedUpdate {
-    type: "tool-call-started";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
-}
-/**
- * Tool call arguments streaming in incrementally.
- *
- * @public
- */
-interface PartialToolCallUpdate {
-    type: "partial-tool-call";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
-}
-/**
- * Tool call completed.
- *
- * @public
- */
-interface ToolCallCompletedUpdate {
-    type: "tool-call-completed";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
-}
-/**
- * Token count delta for usage tracking.
- *
- * @public
- */
-interface TokenDeltaUpdate {
-    type: "token-delta";
-    tokens: number;
-}
-/**
- * Conversation step started.
- *
- * @public
- */
-interface StepStartedUpdate {
-    type: "step-started";
-    stepId: number;
-}
-/**
- * Conversation step completed.
- *
- * @public
- */
-interface StepCompletedUpdate {
-    type: "step-completed";
-    stepId: number;
-    stepDurationMs: number;
-}
-/**
- * Turn ended with usage summary.
- *
- * @public
- */
-interface TurnEndedUpdate {
-    type: "turn-ended";
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-    };
-}
-/**
- * User message appended to the conversation.
+ * Runtime hosting a cron job. Mirrors the agent runtime split.
  *
- * @public
- */
-interface UserMessageAppendedUpdate {
-    type: "user-message-appended";
-    userMessage: UserMessage;
-}
-/** @public */
-interface SummaryUpdate {
-    type: "summary";
-    summary: string;
-}
-/** @public */
-interface SummaryStartedUpdate {
-    type: "summary-started";
-}
-/** @public */
-interface SummaryCompletedUpdate {
-    type: "summary-completed";
-}
-/** @public */
-interface ShellOutputDeltaUpdate {
-    type: "shell-output-delta";
-    event: Record<string, unknown>;
-}
-/**
- * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
- * consume these. Finer-grained than `SDKMessage` events.
+ * - `local` — the in-process scheduler activated via `Cron.start()` fires the
+ *   job while the host process is alive.
+ * - `cloud` — Theo PaaS schedules the job server-side; fires independent of
+ *   any SDK process.
  *
  * @public
  */
-type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
-
+type CronRuntime = "local" | "cloud";
 /**
- * Plain assistant message in a conversation history.
+ * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
  *
  * @public
  */
-interface AssistantMessage {
-    text: string;
-}
+type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
 /**
- * Reasoning step in a conversation history.
+ * Persistent cron-scheduled invocation of the Theo agent.
  *
- * @public
- */
-interface ThinkingMessage {
-    text: string;
-    thinkingDurationMs?: number;
-}
-/**
- * User-authored message in a conversation history.
+ * Exactly one of {@link CronJob.agent} (ephemeral agent created on each fire)
+ * or {@link CronJob.agentId} (bound to an existing agent for context
+ * continuity) is set.
  *
  * @public
  */
-interface UserMessage {
-    text: string;
+interface CronJob {
+    id: string;
+    name?: string;
+    /** Standard 5-field POSIX cron expression or shorthand (`@hourly`, `@daily`, ...). */
+    cron: string;
+    /** IANA timezone identifier. Defaults to `"UTC"`. */
+    timezone?: string;
+    /** Message sent to the agent on each fire. */
+    message: string | SDKUserMessage;
+    /** Ephemeral agent options. Mutually exclusive with `agentId`. */
+    agent?: AgentOptions;
+    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`. */
+    agentId?: string;
+    /** Whether the scheduler will fire this job on schedule. */
+    enabled: boolean;
+    /** Current status. */
+    status: CronJobStatus;
+    /** Runtime that hosts this job. Inferred from `agent`/`agentId` at create time. */
+    runtime: CronRuntime;
+    /** Unix ms of the last successful fire, if any. */
+    lastRunAt?: number;
+    /** Unix ms of the next scheduled fire, computed by the scheduler. */
+    nextRunAt?: number;
+    /** Unix ms when the job was created. */
+    createdAt: number;
 }
 /**
- * Shell command executed during a run.
+ * Options for `Cron.create()`.
  *
- * @public
- */
-interface ShellCommand {
-    command: string;
-    workingDirectory?: string;
-}
-/**
- * Output of a shell command.
+ * Pass `agent` for an ephemeral agent created fresh on each fire, OR
+ * `agentId` to reuse an existing agent (preserves conversation context across
+ * fires). Setting both is a `ConfigurationError`.
  *
  * @public
  */
-interface ShellOutput {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
+interface CronCreateOptions {
+    cron: string;
+    message: string | SDKUserMessage;
+    agent?: AgentOptions;
+    agentId?: string;
+    name?: string;
+    timezone?: string;
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Falls back to `THEOKIT_API_KEY`. */
+    apiKey?: string;
 }
 /**
- * Single step inside an agent turn.
+ * Options for `Cron.list()`.
  *
  * @public
  */
-type ConversationStep = {
-    type: "assistantMessage";
-    message: AssistantMessage;
-} | {
-    type: "toolCall";
-    message: ToolCall;
+type CronListOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
 } | {
-    type: "thinkingMessage";
-    message: ThinkingMessage;
-};
-/**
- * Agent turn: user message + assistant/tool/thinking steps.
- *
- * @public
- */
-interface AgentConversationTurn {
-    userMessage?: UserMessage;
-    steps: ConversationStep[];
-}
-/**
- * Shell turn: a command and its output.
- *
- * @public
- */
-interface ShellConversationTurn {
-    shellCommand?: ShellCommand;
-    shellOutput?: ShellOutput;
-}
-/**
- * Structured per-turn view of a run.
- *
- * @public
- */
-type ConversationTurn = {
-    type: "agentConversationTurn";
-    turn: AgentConversationTurn;
+    runtime: "local";
+    cwd?: string;
 } | {
-    type: "shellConversationTurn";
-    turn: ShellConversationTurn;
-};
-
-/**
- * Plain text content block emitted by the assistant or user.
- *
- * @public
- */
-interface TextBlock {
-    type: "text";
-    text: string;
-}
-/**
- * Tool invocation block emitted by the assistant.
- *
- * @public
- */
-interface ToolUseBlock {
-    type: "tool_use";
-    id: string;
-    name: string;
-    /** Tool args are not part of the stable schema. Treat as unknown and parse defensively. */
-    input: unknown;
-}
-/**
- * Init metadata. Emitted once at the start of a run.
- *
- * @public
- */
-interface SDKSystemMessage {
-    type: "system";
-    subtype?: "init";
-    agent_id: string;
-    run_id: string;
-    model?: ModelSelection;
-    tools?: string[];
-}
-/**
- * Echo of the user prompt for this run.
- *
- * @public
- */
-interface SDKUserMessageEvent {
-    type: "user";
-    agent_id: string;
-    run_id: string;
-    message: {
-        role: "user";
-        content: TextBlock[];
-    };
-}
-/**
- * Model text output for this run.
- *
- * @public
- */
-interface SDKAssistantMessage {
-    type: "assistant";
-    agent_id: string;
-    run_id: string;
-    message: {
-        role: "assistant";
-        content: Array<TextBlock | ToolUseBlock>;
-    };
-}
-/**
- * Reasoning content.
- *
- * @public
- */
-interface SDKThinkingMessage {
-    type: "thinking";
-    agent_id: string;
-    run_id: string;
-    text: string;
-    thinking_duration_ms?: number;
-}
-/**
- * Tool invocation lifecycle event. Emitted at start with `args`, then again on
- * completion with `result`.
- *
- * Tool `args` and `result` are NOT part of the stable schema — treat as unknown.
- *
- * @public
- */
-interface SDKToolUseMessage {
-    type: "tool_call";
-    agent_id: string;
-    run_id: string;
-    call_id: string;
-    name: string;
-    status: "running" | "completed" | "error";
-    args?: unknown;
-    result?: unknown;
-    truncated?: {
-        args?: boolean;
-        result?: boolean;
-    };
-}
+    runtime: "cloud";
+    apiKey?: string;
+});
 /**
- * Cloud run lifecycle transitions.
+ * Options for `Cron.get()`.
  *
  * @public
  */
-interface SDKStatusMessage {
-    type: "status";
-    agent_id: string;
-    run_id: string;
-    status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED";
-    message?: string;
+interface CronGetOptions {
+    cwd?: string;
+    apiKey?: string;
 }
 /**
- * Task-level milestones and summaries.
+ * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
  *
  * @public
  */
-interface SDKTaskMessage {
-    type: "task";
-    agent_id: string;
-    run_id: string;
-    status?: string;
-    text?: string;
+interface CronOperationOptions {
+    cwd?: string;
+    apiKey?: string;
 }
 /**
- * Awaiting user input or approval.
+ * Options for `Cron.run()` — manually trigger a job off-schedule.
  *
  * @public
  */
-interface SDKRequestMessage {
-    type: "request";
-    agent_id: string;
-    run_id: string;
-    request_id: string;
+interface CronRunOptions {
+    cwd?: string;
+    apiKey?: string;
 }
 /**
- * Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
- * `partial` is `DeepPartial<z.infer<T>>` at the typed iterator level but
- * erased to `unknown` here because SDKMessage union is non-generic.
+ * Options for `Cron.start()` — activates the in-process scheduler for local
+ * jobs.
  *
  * @public
  */
-interface SDKObjectDelta {
-    type: "object_delta";
-    agent_id: string;
-    run_id: string;
-    partial: unknown;
-    attempt: number;
+interface CronStartOptions {
+    /** Local workspace whose `.theokit/cron/jobs.json` to load. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override the env API key. */
+    apiKey?: string;
 }
 /**
- * Discriminated union of all stream events. Discriminate on `type`.
- *
- * All events include `agent_id` and `run_id`.
- *
- * @public
- */
-type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;
-
-/**
- * Public type contract for token usage + cost tracking (ADRs D376-D379).
- *
- * Surfaces via `RunResult.usage` + `RunResult.cost` after every Run.
- * Re-exported through the package barrel; consumers import from
- * `@theokit/sdk`.
+ * Snapshot of the local scheduler returned by `Cron.status()`.
  *
  * @public
  */
-/**
- * Token usage observed during a Run. 5 closed buckets (D376) cover
- * 100% of providers in 2026: OpenAI Chat / OpenAI Responses (o-series
- * with reasoning) / Anthropic Messages (with prompt caching).
- *
- * `totalTokens` is derived (`inputTokens + outputTokens`); EC-10
- * invariant: SDK must never emit `totalTokens !== inputTokens + outputTokens`.
- *
- * `requests[]` is the per-request breakdown (mirror openai-agents-python)
- * — populated only when the run made > 1 LLM call.
- */
-interface TokenUsage {
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    readonly cacheReadTokens?: number;
-    readonly cacheWriteTokens?: number;
-    readonly reasoningTokens?: number;
-    readonly totalTokens: number;
-    /** Per-request breakdown; absent when the run made a single LLM call. */
-    readonly requests?: ReadonlyArray<Omit<TokenUsage, "requests">>;
-}
-/**
- * Cost confidence level (D377).
- * - `actual`: returned by a provider billing API (e.g. OpenRouter `/generation`).
- * - `estimated`: computed from bundled pricing snapshot.
- * - `included`: subscription-included route (Codex CLI, Claude Pro).
- * - `unknown`: pricing data unavailable; `amountUsd` is undefined.
- */
-type CostStatus = "actual" | "estimated" | "included" | "unknown";
-/** Source of the cost figure for caller-side audit. */
-type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override" | "subscription_included" | "unknown";
-/**
- * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
- * `amountUsd` is `undefined` — DO NOT default to 0 (mentira). UI exibe
- * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
- */
-interface CostBreakdown {
-    readonly amountUsd: number | undefined;
-    readonly status: CostStatus;
-    readonly currency: "USD";
-    readonly source: CostSource;
-    readonly pricingVersion: string | undefined;
-    readonly notes?: ReadonlyArray<string>;
-    /** Per-bucket detail (in USD) for caller analytics. */
-    readonly detail?: {
-        readonly input?: number;
-        readonly output?: number;
-        readonly cacheRead?: number;
-        readonly cacheWrite?: number;
-        readonly reasoning?: number;
+interface CronSchedulerStatus {
+    /** Whether the in-process scheduler is currently running. */
+    running: boolean;
+    /** Number of jobs loaded into the scheduler. */
+    jobCount: number;
+    /** Unix ms of the next scheduled fire across all jobs, if any. */
+    nextFireAt?: number;
+    /** Last error observed in the scheduler, if any. */
+    lastError?: {
+        jobId: string;
+        message: string;
+        at: number;
     };
 }
 
 /**
- * Lifecycle status of a {@link Run}.
- *
- * @public
- */
-type RunStatus = "running" | "finished" | "error" | "cancelled";
-/**
- * Operations that may or may not be supported on a given {@link Run}, or on
- * its parent agent.
- *
- * Runtime-specific availability — query at runtime with `run.supports(op)` and
- * read the human reason via `run.unsupportedReason(op)`.
- *
- * @public
- */
-type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "usePersonality" | "workflow";
-/**
- * Git metadata attached to cloud runs.
+ * Static façade for scheduling Theo agent runs on a cron expression.
  *
  * @public
  */
-interface RunGitInfo {
-    branches: Array<{
-        repoUrl: string;
-        branch?: string;
-        prUrl?: string;
-    }>;
-}
-/**
- * Terminal result of a {@link Run}.
- *
- * @public
- */
-interface RunResult {
-    id: string;
-    status: "finished" | "error" | "cancelled";
-    result?: string;
-    model?: ModelSelection;
-    durationMs?: number;
-    git?: RunGitInfo;
+declare class Cron {
+    private constructor();
     /**
-     * Structured error detail, populated when `status === "error"`. Surfaces
-     * the diagnostic that emit-error-event pushes into the stream so callers
-     * that don't drain `run.stream()` still get the cause via `run.wait()`.
+     * Create and persist a cron job.
      *
-     * For successful runs (`status: "finished"`) this is undefined.
+     * @public
+     */
+    static create(options: CronCreateOptions): Promise<CronJob>;
+    /**
+     * List cron jobs (local, cloud, or both).
      *
      * @public
      */
-    error?: RunErrorDetail;
+    static list(options?: CronListOptions): Promise<ListResult<CronJob>>;
     /**
-     * Token usage observed for this run (ADR D376). Populated in every
-     * status where ≥1 LLM call completed — including partial-failure
-     * runs (EC-5). `undefined` only when zero LLM calls executed (e.g.,
-     * abort before send).
+     * Get a single cron job by ID.
      *
      * @public
      */
-    usage?: TokenUsage;
+    static get(jobId: string, _options?: CronGetOptions): Promise<CronJob>;
     /**
-     * Estimated/actual USD cost for this run (ADR D377). Always paired
-     * with `usage` when populated. `cost.status` tells caller how to
-     * trust the figure.
+     * Delete a cron job permanently.
      *
      * @public
      */
-    cost?: CostBreakdown;
-}
-/**
- * Structured error attached to a {@link RunResult} when the underlying run
- * transitioned to `"error"` status. `message` is always present; `code` is
- * a stable identifier suitable for branching (e.g. `"llm_4xx"`,
- * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the raw error
- * for further inspection when available.
- *
- * @public
- */
-interface RunErrorDetail {
-    message: string;
-    code?: string;
-    cause?: unknown;
-}
-/**
- * Dimensions of an inline image attachment.
- *
- * @public
- */
-interface SDKImageDimension {
-    width: number;
-    height: number;
-}
-/**
- * Either a remote URL or inline base64 payload.
- *
- * @public
- */
-type SDKImage = {
-    url: string;
-    dimension?: SDKImageDimension;
-} | {
-    data: string;
-    mimeType: string;
-    dimension?: SDKImageDimension;
-};
-/**
- * Structured form of `agent.send()`'s message argument. Use it to send images
- * alongside text.
- *
- * @public
- */
-interface SDKUserMessage {
-    text: string;
-    images?: SDKImage[];
-}
-/**
- * Per-send overrides and callbacks.
- *
- * @public
- */
-interface SendOptions {
-    model?: ModelSelection;
+    static delete(jobId: string, _options?: CronOperationOptions): Promise<void>;
     /**
-     * Per-call system prompt override. Wins over `AgentOptions.systemPrompt`.
-     * String only — for dynamic resolvers, configure on `AgentOptions`. An
-     * empty string is honoured (it explicitly clears the system context).
+     * Re-enable a paused cron job.
+     *
+     * @public
      */
-    systemPrompt?: string;
-    /** Fully replaces creation-time servers for this run (not merged). */
-    mcpServers?: Record<string, McpServerConfig>;
+    static enable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
     /**
-     * Per-call inline custom tools. Fully replaces `AgentOptions.tools` for
-     * this run (not merged). Local runtime only — cloud agents reject any
-     * non-empty per-call tools array with the same error code as creation
-     * (`cloud_custom_tools_rejected`). Semantics:
-     * - `undefined` → fall back to `AgentOptions.tools`
-     * - `[]` → explicitly clear (no custom tools for this run)
-     * - `[t1, t2]` → use exactly these tools for this run
+     * Pause a cron job without deleting it.
+     *
+     * @public
      */
-    tools?: CustomTool[];
-    onStep?: (args: {
-        step: ConversationStep;
-    }) => void | Promise<void>;
-    onDelta?: (args: {
-        update: InteractionUpdate;
-    }) => void | Promise<void>;
-    /** Local agents only. Expire a stuck active run before starting this message. */
-    local?: {
-        force?: boolean;
-    };
+    static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
     /**
-     * Optional `AbortSignal` propagated to memory adapter `pre_user_send`
-     * hooks (EC-H). Note: the LLM HTTP call itself is NOT cancellable
-     * mid-stream — same constraint as `Agent.batch` (ADR D140).
+     * Manually trigger a cron job off-schedule. Returns the resulting `Run`.
      *
      * @public
      */
-    signal?: AbortSignal;
+    static run(jobId: string, _options?: CronRunOptions): Promise<Run>;
     /**
-     * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
-     * run is registered as a `Task` in the SDK's observable registry —
-     * caller can list / inspect / cancel / subscribe via the `Task`
-     * namespace. Default behavior (no `task` option) is byte-identical
-     * to v1.1 (no Task overhead).
+     * Activate the in-process scheduler for local cron jobs.
      *
-     * Accepts:
-     * - `true` — auto-generate task id; no extra metadata.
-     * - `{ id, meta }` — user-supplied id (D368 grammar enforced) and/or
-     *   metadata attached to the handle's `meta` field.
+     * @public
+     */
+    static start(options?: CronStartOptions): Promise<void>;
+    /**
+     * Stop the in-process scheduler. Jobs are preserved.
      *
-     * The work-fn `signal` is **merged** with `options.signal` (whichever
-     * aborts first wins). Local agents only — CloudAgent throws
-     * `UnsupportedTaskOperationError` (D370).
+     * @public
+     */
+    static stop(): Promise<void>;
+    /**
+     * Snapshot of the local scheduler.
      *
      * @public
      */
-    task?: true | {
-        id?: string;
-        meta?: Record<string, unknown>;
-    };
-}
-/**
- * Handle to a single prompt submission.
- *
- * @public
- */
-interface Run {
-    readonly id: string;
-    readonly agentId: string;
-    readonly status: RunStatus;
-    readonly result?: string;
-    readonly model?: ModelSelection;
-    readonly durationMs?: number;
-    readonly git?: RunGitInfo;
-    readonly createdAt?: number;
-    /** AsyncGenerator of normalized stream events. Discriminate on `event.type`. */
-    stream(): AsyncGenerator<SDKMessage, void>;
-    /** Resolves to the terminal {@link RunResult}. */
-    wait(): Promise<RunResult>;
-    /** Move status to `"cancelled"`, abort the stream, stop in-flight tool calls. */
-    cancel(): Promise<void>;
-    /** Structured per-turn view of the conversation. */
-    conversation(): Promise<ConversationTurn[]>;
-    /** Whether the given operation is available on this run's runtime. */
-    supports(operation: RunOperation): boolean;
-    /** Human-readable reason that `supports(operation)` returned `false`. */
-    unsupportedReason(operation: RunOperation): string | undefined;
-    /** Subscribe to status changes. Returns an unsubscribe function. */
-    onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
+    static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { HandoffReceiverDisposedError as $, type AgentOptions as A, type ContextBudget as B, type CloudOptions as C, type ContextManagerKind as D, type ContextSnapshot as E, type ContextSource as F, type GetAgentOptions as G, type HandoffOptions as H, type ContextSourceStatus as I, type ConversationStep as J, type ConversationTurn as K, type LocalOptions as L, type ModelSelection as M, type CostBreakdown as N, type CostSource as O, type ProviderRoutingSettings as P, type CostStatus as Q, type RunResult as R, type SystemPromptResolver as S, type GoalEvent as T, type GoalOptions as U, type GoalResult as V, type HandoffContext as W, type HandoffHistory as X, HandoffLoopError as Y, HandoffNameCollisionError as Z, HandoffPairLoopError as _, type MemorySettings as a, type ThinkingMessage as a$, type HandoffResult as a0, HandoffSelfReferenceError as a1, type InteractionUpdate as a2, type InvalidateCacheOptions as a3, type McpAuthConfig as a4, type McpHttpServerConfig as a5, type McpOAuthConfig as a6, type McpStdioServerConfig as a7, type MemoryAdapter as a8, type MemoryAdapterCapabilities as a9, type SDKRequestMessage as aA, type SDKStatusMessage as aB, type SDKSystemMessage as aC, type SDKTaskMessage as aD, type SDKThinkingMessage as aE, type SDKToolUseMessage as aF, type SDKUserMessage as aG, type SDKUserMessageEvent as aH, type SendOptions as aI, type SettingSource as aJ, type ShellCommand as aK, type ShellConversationTurn as aL, type ShellOutput as aM, type ShellOutputDeltaUpdate as aN, type StepCompletedUpdate as aO, type StepStartedUpdate as aP, type SummaryCompletedUpdate as aQ, type SummaryStartedUpdate as aR, type SummaryUpdate as aS, type SystemPromptContext as aT, type SystemPromptMemoryFact as aU, type SystemPromptSkillRef as aV, type TelemetrySettings as aW, type TextBlock as aX, type TextDeltaUpdate as aY, type ThinkingCompletedUpdate as aZ, type ThinkingDeltaUpdate as a_, type MemoryContext as aa, type MemoryFact as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type ModelParameterValue as af, type PartialToolCallUpdate as ag, type PersonalityPreset as ah, type ProviderCapability as ai, type ProviderRoute as aj, type ResolvedProviderRoute as ak, type RunErrorDetail as al, type RunGitInfo as am, type RunOperation as an, type RunStatus as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKAssistantMessage as at, type SDKContextManager as au, type SDKImage as av, type SDKImageDimension as aw, type SDKObjectDelta as ax, type SDKPluginMetadata as ay, type SDKProvidersManager as az, type CustomTool as b, type TokenDeltaUpdate as b0, type TokenUsage as b1, type ToolCall as b2, type ToolCallCompletedUpdate as b3, type ToolCallStartedUpdate as b4, type ToolUseBlock as b5, type TurnEndedUpdate as b6, type UserMessage as b7, type UserMessageAppendedUpdate as b8, type McpServerConfig as c, type AgentDefinition as d, type ContextSettings as e, type PluginsSettings as f, type SkillsSettings as g, type SDKAgent as h, type ListAgentsOptions as i, type ListResult as j, type SDKAgentInfo as k, type ListRunsOptions as l, type Run as m, type GetRunOptions as n, type AgentOperationOptions as o, type HandoffDescriptor as p, type ConversationStorageAdapter as q, type StoredMessage as r, type MemoryId as s, type SDKProvider as t, type SDKMessage as u, type AgentConversationTurn as v, type AgentMemory as w, type AssistantMessage as x, type CloudEnv as y, type CloudRepo as z };
+export { type MemoryAdapter as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type ContextManagerKind as D, type ContextSnapshot as E, type ContextSource as F, type GetAgentOptions as G, type ContextSourceStatus as H, Cron as I, type CronCreateOptions as J, type CronGetOptions as K, type LocalOptions as L, type MemorySettings as M, type CronJob as N, type CronJobStatus as O, type ProviderRoutingSettings as P, type CronListOptions as Q, type CronOperationOptions as R, type SystemPromptResolver as S, type CronRunOptions as T, type CronRuntime as U, type CronSchedulerStatus as V, type CronStartOptions as W, type GoalEvent as X, type GoalOptions as Y, type GoalResult as Z, type InvalidateCacheOptions as _, type AgentDefinition as a, type MemoryAdapterCapabilities as a0, type MemoryFact as a1, type MemoryProviderHandle as a2, type MemoryProviderInitOptions as a3, type MemoryRevision as a4, type MemoryToolSchema as a5, type MemoryTurnMessage as a6, type PersonalityPreset as a7, type ProviderCapability as a8, type ProviderRoute as a9, type RecordSessionSummaryArgs as aa, type ResolvedProviderRoute as ab, type RunUntilIterator as ac, type SDKAgentPlugins as ad, type SDKAgentSkills as ae, type SDKArtifact as af, type SDKContextManager as ag, type SDKPluginMetadata as ah, type SDKProvidersManager as ai, type SettingSource as aj, type SystemPromptContext as ak, type SystemPromptMemoryFact as al, type SystemPromptSkillRef as am, type TelemetrySettings as an, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ConversationStorageAdapter as l, type StoredMessage as m, type MemoryContext as n, type MemoryProvider as o, type MemoryId as p, type SDKProvider as q, type ActiveMemoryPassArgs as r, type ActiveMemoryPassResult as s, type AgentMemory as t, type BudgetCheck as u, type BudgetTotal as v, type BudgetUsageEvent as w, type CloudEnv as x, type CloudRepo as y, type ContextBudget as z };