@theokit/sdk 1.5.0

package/dist/agent-builder.d.ts

@@ -0,0 +1,52 @@
+import type { AgentDefinition, AgentOptions, CloudOptions, CustomTool, LocalOptions, MemorySettings, ModelSelection, SDKAgent, SkillsSettings, SystemPromptResolver } from "./types/agent.js";
+import type { ContextSettings } from "./types/context.js";
+import type { McpServerConfig } from "./types/mcp.js";
+import type { PluginsSettings, ProviderRoutingSettings } from "./types/providers.js";
+/**
+ * Fluent builder for {@link AgentOptions}. Chainable setters mutate internal
+ * state and return `this`. Three terminals:
+ *
+ * - `.build()` — synchronous snapshot (shallow clone) of accumulated options.
+ * - `.create()` — calls the injected `create` (Agent.create).
+ * - `.getOrCreate(agentId)` — calls the injected `getOrCreate` (Agent.getOrCreate).
+ *
+ * Validation runs inside the terminals via `validateAgentOptions`. See ADR D25.
+ *
+ * @public
+ */
+export declare class AgentBuilder {
+    private opts;
+    private readonly deps;
+    constructor(deps?: AgentBuilderDeps);
+    model(m: ModelSelection): this;
+    apiKey(k: string): this;
+    name(n: string): this;
+    systemPrompt(p: string | SystemPromptResolver): this;
+    local(l: LocalOptions): this;
+    cloud(c: CloudOptions): this;
+    memory(m: MemorySettings): this;
+    tools(t: CustomTool[]): this;
+    mcpServers(s: Record<string, McpServerConfig>): this;
+    agents(a: Record<string, AgentDefinition>): this;
+    context(c: ContextSettings): this;
+    providers(p: ProviderRoutingSettings): this;
+    plugins(p: PluginsSettings): this;
+    skills(s: SkillsSettings): this;
+    agentId(id: string): this;
+    /**
+     * Synchronous snapshot of the accumulated options. Returns a SHALLOW CLONE
+     * so external mutation of the result doesn't pollute the builder state (EC-2).
+     */
+    build(): AgentOptions;
+    /**
+     * Validate + create a fresh agent. Delegates to `Agent.create` via the
+     * injected `deps.create`. Throws if the builder was instantiated without
+     * deps (i.e., direct `new AgentBuilder()` instead of `Agent.builder()`).
+     */
+    create(): Promise<SDKAgent>;
+    /**
+     * Resume an existing agent or create one if the ID is unknown. Delegates to
+     * `Agent.getOrCreate` via the injected `deps.getOrCreate` (ADR D22).
+     */
+    getOrCreate(agentId: string): Promise<SDKAgent>;
+}

package/dist/agent-factory.d.ts

@@ -0,0 +1,39 @@
+import type { AgentOptions, SDKAgent } from "./types/agent.js";
+/**
+ * Handle returned by {@link createAgentFactory}. See ADR D23 for merge
+ * semantics.
+ *
+ * @public
+ */
+export interface AgentFactory {
+    /**
+     * Create a fresh agent for this session. Equivalent to `Agent.create(merged)`
+     * where `merged` is `common` ⊕ `overrides` ⊕ `{ agentId }`.
+     */
+    forSession(agentId: string, overrides?: Partial<AgentOptions>): Promise<SDKAgent>;
+    /**
+     * Resume an existing agent for this session, or create one if the ID is
+     * unknown. Equivalent to `Agent.getOrCreate(agentId, merged)`.
+     */
+    getOrCreate(agentId: string, overrides?: Partial<AgentOptions>): Promise<SDKAgent>;
+}
+/**
+ * Capture a common {@link AgentOptions} prefix and produce per-session agents
+ * with focused overrides. Useful for chat-bot patterns where most config is
+ * shared across users/sessions.
+ *
+ * Merge rules (ADR D23):
+ * - Top-level shallow merge with `overrides` winning.
+ * - Deep merge for `local`, `memory`, `cloud` (configuration objects with
+ *   non-conflicting flat keys).
+ * - Total replace for `mcpServers`, `agents`, `tools`, `providers`,
+ *   `plugins`, `skills`, `context` (collection-shaped).
+ * - The function-level `agentId` always wins over both `common.agentId` and
+ *   `overrides.agentId`.
+ *
+ * The factory holds `common` by reference — mutating it after construction
+ * leaks to subsequent `forSession` calls (documented caveat).
+ *
+ * @public
+ */
+export declare function createAgentFactory(common: Partial<AgentOptions>): AgentFactory;

package/dist/agent.d.ts

@@ -0,0 +1,175 @@
+import { AgentBuilder } from "./agent-builder.js";
+import { type LiveAgentRegistry } from "./internal/runtime/live-agent-registry.js";
+import type { AgentOperationOptions, AgentOptions, GetAgentOptions, GetRunOptions, ListAgentsOptions, ListResult, ListRunsOptions, SDKAgent, SDKAgentInfo } from "./types/agent.js";
+import type { Run, RunResult } from "./types/run.js";
+/**
+ * Result of a one-shot {@link Agent.prompt} call.
+ *
+ * @public
+ */
+export type AgentPromptResult = RunResult;
+/**
+ * Static façade for creating and managing Theo agents.
+ *
+ * @public
+ */
+export declare class Agent {
+    private constructor();
+    /**
+     * Live-agent cache for production deploys (Production-Readiness #2, ADRs D307-D310).
+     *
+     * Caches `SDKAgent` instances by id with LRU eviction (when `size > maxAgents`)
+     * and an idle-timeout sweep. Solves the OOM failure mode for long-running
+     * Node servers spawning fresh agents per conversation.
+     *
+     * Defaults: `maxAgents: 100`, `idleTimeoutMs: 30 min`, sweep `60s`.
+     * Configure for high-traffic SaaS:
+     *
+     * ```ts
+     * Agent.registry.configure({ maxAgents: 1000, idleTimeoutMs: 15 * 60_000 });
+     * process.on("SIGTERM", () => Agent.registry.evictAll());
+     * ```
+     *
+     * Cache hits are automatic in `Agent.getOrCreate` (T2.6). Disable the cache
+     * entirely via `configure({ maxAgents: 0 })` — every getOrCreate then
+     * re-initializes.
+     *
+     * @public
+     */
+    static readonly registry: LiveAgentRegistry;
+    /**
+     * Create a new agent. Pass either `local` or `cloud` to pick a runtime.
+     *
+     * @public
+     */
+    static create(options: AgentOptions): Promise<SDKAgent>;
+    /**
+     * One-shot prompt: create an agent, send a single message, wait, dispose.
+     *
+     * When `options.throwOnError === true`, rejects with `AgentRunError` if
+     * the run terminates with `status: 'error'` (instead of resolving with the
+     * error wrapped in the RunResult). Cancelled runs still resolve normally.
+     *
+     * @public
+     */
+    static prompt(message: string, options: AgentOptions): Promise<AgentPromptResult>;
+    /**
+     * Reattach to an existing agent by ID.
+     *
+     * @public
+     */
+    static resume(agentId: string, options?: Partial<AgentOptions>): Promise<SDKAgent>;
+    /**
+     * Start building an {@link AgentOptions} via fluent chain. See ADR D25.
+     * Terminals: `.build()`, `.create()`, `.getOrCreate(id)`.
+     *
+     * The builder receives `create` + `getOrCreate` as injected callbacks so
+     * that `agent-builder.ts` doesn't need a static import of `Agent` — keeps
+     * the module graph acyclic (G6).
+     *
+     * @public
+     */
+    static builder(): AgentBuilder;
+    /**
+     * Generate a typed object matching a Zod schema via a synthetic forced
+     * tool call (ADR D33). One-shot: create transient agent → send prompt →
+     * model calls `output` tool → parse args via Zod → return typed.
+     *
+     * @public
+     */
+    static generateObject<T extends import("zod").ZodType>(options: import("./generate-object.js").GenerateObjectOptions<T>): Promise<import("./generate-object.js").GenerateObjectResult<import("zod").z.infer<T>>>;
+    /**
+     * Stream a structured output object alongside intermediate `partial`
+     * deltas as the model accumulates its response (ADR D39). Returns an
+     * `AsyncIterator<StreamObjectEvent<T>>` that yields zero or more
+     * `partial` events and exactly one `complete` event at the end.
+     *
+     * The `complete` event carries the same `object: z.infer<T>` you would get
+     * from `Agent.generateObject` — same prompt + schema + model produces
+     * the same final object.
+     *
+     * @public
+     */
+    static streamObject<T extends import("zod").ZodType>(options: import("./stream-object.js").StreamObjectOptions<T>): AsyncGenerator<import("./stream-object.js").StreamObjectEvent<import("zod").z.infer<T>>, void, void>;
+    /**
+     * Run N prompts in parallel with bounded concurrency (ADRs D134-D140).
+     *
+     * Each prompt gets a fresh agent (create → send → wait → dispose). Failures
+     * are isolated per-prompt; the batch never throws on a single failure —
+     * inspect `result.ok` to discriminate success vs error. Default
+     * concurrency is 4. When `options.providers.apiKeys` has ≥2 keys per
+     * provider, all in-flight agents share a single credential pool via
+     * `AsyncLocalStorage` (EC-A) so rate-limit cooldowns are observed once
+     * instead of duplicated per agent.
+     *
+     * Streaming progress is opt-in via `onResult` / `onProgress`. `AbortSignal`
+     * cancels pending prompts; in-flight ones continue to completion (Node
+     * AbortSignal semantics). `signal.reason` propagates to `error` when set.
+     *
+     * @public
+     */
+    static batch(prompts: ReadonlyArray<string | import("./types/batch.js").BatchItem>, options: import("./types/batch.js").BatchOptions): Promise<import("./types/batch.js").BatchResult[]>;
+    /**
+     * Get an existing agent by ID, or create one with the supplied options if
+     * the ID is not yet registered. Eliminates the resume-vs-create boilerplate
+     * common to chat bots and other long-running agent consumers. See ADR D22.
+     *
+     * Resolution:
+     * 1. Try `Agent.resume(agentId, options)`. Return on success.
+     * 2. On `UnknownAgentError`, fall through to `Agent.create({ ...options, agentId })`.
+     * 3. On same-process race (`ConfigurationError(code: "agent_id_already_exists")`
+     *    during step 2), retry `Agent.resume` once and return the winner's handle.
+     * 4. Any other error propagates verbatim.
+     *
+     * Caveats:
+     * - The function-level `agentId` always wins over `options.agentId`.
+     * - Options differ between calls? Last-call-wins for this handle (matches `Agent.resume`).
+     * - Disposed agents are NOT auto-deleted from the registry. To force a fresh
+     *   agent, call `Agent.delete(agentId)` first.
+     *
+     * @public
+     */
+    static getOrCreate(agentId: string, options: AgentOptions): Promise<SDKAgent>;
+    /**
+     * List agents (local or cloud).
+     *
+     * @public
+     */
+    static list(options?: ListAgentsOptions): Promise<ListResult<SDKAgentInfo>>;
+    /**
+     * Get metadata for a single agent.
+     *
+     * @public
+     */
+    static get(agentId: string, _options?: GetAgentOptions): Promise<SDKAgentInfo>;
+    /**
+     * List runs for an agent.
+     *
+     * @public
+     */
+    static listRuns(agentId: string, _options?: ListRunsOptions): Promise<ListResult<Run>>;
+    /**
+     * Get a single run.
+     *
+     * @public
+     */
+    static getRun(runId: string, options?: GetRunOptions): Promise<Run>;
+    /**
+     * Archive a cloud agent.
+     *
+     * @public
+     */
+    static archive(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * Restore an archived cloud agent.
+     *
+     * @public
+     */
+    static unarchive(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * Permanently delete a cloud agent.
+     *
+     * @public
+     */
+    static delete(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+}

package/dist/batch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `Agent.batch(prompts, options)` core (ADRs D134-D140).
+ *
+ * Fans out N prompts via bounded concurrency, isolates failures per-prompt,
+ * preserves input order in the result array, supports streaming callbacks
+ * + AbortSignal. The credential pool (D131) is shared across all
+ * in-flight agents via `withCredentialPool` ALS scope (EC-A fix).
+ *
+ * @internal
+ */
+export {};

package/dist/budget.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `Budget` — token cost enforcement primitive (Adoption Roadmap #1
+ * post-Tasks, ADRs D375-D388).
+ *
+ * Static facade delegating to the in-process registry + ledger.
+ * 3 modes: `audit` (log-only), `warn` (callbacks + log), `block`
+ * (preflight throw before LLM call).
+ *
+ * @public
+ */
+import { computeCost } from "./internal/budget/compute-cost.js";
+import { chargeAndCheckThresholds, preflightCheck } from "./internal/budget/enforcement.js";
+import { inferApiMode, normalizeUsage } from "./internal/budget/normalize-usage.js";
+import { getPricingEntry } from "./internal/budget/pricing-registry.js";
+import { UsageAccumulator } from "./internal/budget/usage-accumulator.js";
+import type { BudgetHandle, BudgetOptions, BudgetSnapshot } from "./types/budget.js";
+export { chargeAndCheckThresholds, computeCost, getPricingEntry, inferApiMode, normalizeUsage, preflightCheck, UsageAccumulator, };
+export declare class Budget {
+    private constructor();
+    /**
+     * Create a budget. `name` must match `^[a-z0-9][a-z0-9_-]*$` (EC-7).
+     * Throws `ConfigurationError` if name is invalid OR already exists
+     * (EC-16: duplicate surface caller bug).
+     *
+     * `limits` is stacked (D384) — ANY exceeded triggers enforcement.
+     * Empty `limits[]` is valid: pure tracking, no thresholds/exceed
+     * callbacks fire (EC-19).
+     *
+     * Default `mode` is `"warn"` (D383). For emergency stop, use
+     * `mode: "block", limits: [{ window: "1d", limitUsd: 0 }]` (EC-18).
+     */
+    static create(options: BudgetOptions): BudgetHandle;
+    /** Returns the handle for an active budget, or `undefined`. */
+    static get(name: string): BudgetHandle | undefined;
+    /** Returns all active budgets. */
+    static list(): readonly BudgetHandle[];
+    /**
+     * Deletes a budget from the registry. Returns `true` if it existed.
+     * In-flight `agent.send` calls referencing the name treat the
+     * subsequent charge as a silent no-op + stderr warn (EC-20).
+     */
+    static delete(name: string): boolean;
+    /**
+     * Returns per-window spend snapshot for all active budgets. Each
+     * entry has `{ name, window, spentUsd, limitUsd, ratio }`.
+     */
+    static snapshot(): readonly BudgetSnapshot[];
+}

package/dist/cache.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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
+ */
+import type { Plugin } from "./internal/plugins/types.js";
+import type { CacheSemanticOptions, CacheStats } from "./types/cache.js";
+export 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;
+}
+export { CacheEmbedderError, CacheInvalidTtlError } from "./types/cache.js";

package/dist/cron-1yxL3K2S.d.cts

@@ -0,0 +1,221 @@
+import { aG as SDKUserMessage, A as AgentOptions, j as ListResult, m as Run } from './run-DkCD5DeO.cjs';
+
+/**
+ * Runtime hosting a cron job. Mirrors the agent runtime split.
+ *
+ * - `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 CronRuntime = "local" | "cloud";
+/**
+ * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
+ *
+ * @public
+ */
+type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
+/**
+ * Persistent cron-scheduled invocation of the Theo agent.
+ *
+ * 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 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;
+}
+/**
+ * Options for `Cron.create()`.
+ *
+ * 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 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;
+}
+/**
+ * Options for `Cron.list()`.
+ *
+ * @public
+ */
+type CronListOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: string;
+});
+/**
+ * Options for `Cron.get()`.
+ *
+ * @public
+ */
+interface CronGetOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
+ *
+ * @public
+ */
+interface CronOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.run()` — manually trigger a job off-schedule.
+ *
+ * @public
+ */
+interface CronRunOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.start()` — activates the in-process scheduler for local
+ * jobs.
+ *
+ * @public
+ */
+interface CronStartOptions {
+    /** Local workspace whose `.theokit/cron/jobs.json` to load. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override the env API key. */
+    apiKey?: string;
+}
+/**
+ * Snapshot of the local scheduler returned by `Cron.status()`.
+ *
+ * @public
+ */
+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;
+    };
+}
+
+/**
+ * Static façade for scheduling Theo agent runs on a cron expression.
+ *
+ * @public
+ */
+declare class Cron {
+    private constructor();
+    /**
+     * Create and persist a cron job.
+     *
+     * @public
+     */
+    static create(options: CronCreateOptions): Promise<CronJob>;
+    /**
+     * List cron jobs (local, cloud, or both).
+     *
+     * @public
+     */
+    static list(options?: CronListOptions): Promise<ListResult<CronJob>>;
+    /**
+     * Get a single cron job by ID.
+     *
+     * @public
+     */
+    static get(jobId: string, _options?: CronGetOptions): Promise<CronJob>;
+    /**
+     * Delete a cron job permanently.
+     *
+     * @public
+     */
+    static delete(jobId: string, _options?: CronOperationOptions): Promise<void>;
+    /**
+     * Re-enable a paused cron job.
+     *
+     * @public
+     */
+    static enable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Pause a cron job without deleting it.
+     *
+     * @public
+     */
+    static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Manually trigger a cron job off-schedule. Returns the resulting `Run`.
+     *
+     * @public
+     */
+    static run(jobId: string, _options?: CronRunOptions): Promise<Run>;
+    /**
+     * Activate the in-process scheduler for local cron jobs.
+     *
+     * @public
+     */
+    static start(options?: CronStartOptions): Promise<void>;
+    /**
+     * Stop the in-process scheduler. Jobs are preserved.
+     *
+     * @public
+     */
+    static stop(): Promise<void>;
+    /**
+     * Snapshot of the local scheduler.
+     *
+     * @public
+     */
+    static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
+}
+
+export { Cron as C, type CronCreateOptions as a, type CronGetOptions as b, type CronJob as c, type CronJobStatus as d, type CronListOptions as e, type CronOperationOptions as f, type CronRunOptions as g, type CronRuntime as h, type CronSchedulerStatus as i, type CronStartOptions as j };