@theokit/sdk 1.5.0

package/dist/types/batch.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Public types for `Agent.batch` (ADRs D134-D140).
+ *
+ * Run N prompts in parallel with bounded concurrency. Each prompt gets
+ * a fresh agent (create → send → wait → dispose). Failures isolated
+ * per-prompt; the batch never aborts on a single failure.
+ *
+ * @public
+ */
+import type { TheokitAgentError } from "../errors.js";
+import type { AgentOptions } from "./agent.js";
+import type { RunResult } from "./run.js";
+/**
+ * Single prompt in a batch. Plain string is shorthand for `{ prompt }`.
+ *
+ * @public
+ */
+export interface BatchItem {
+    /** Prompt text sent to the agent. */
+    prompt: string;
+    /** Per-prompt system prompt override (wins over `BatchOptions.systemPrompt`). */
+    systemPrompt?: string;
+    /**
+     * Caller-supplied metadata, round-tripped to `BatchResult.metadata`.
+     * Passed by reference — do NOT mutate while the batch is in-flight (EC-I).
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options accepted by `Agent.batch`. Extends `AgentOptions` — every
+ * prompt gets an agent created with these options (ADR D138 isolation),
+ * plus the batch-specific knobs below.
+ *
+ * @public
+ */
+export interface BatchOptions extends AgentOptions {
+    /**
+     * Maximum parallel agents. Default 4 (ADR D136). Must be a positive
+     * integer. Capped to `prompts.length` to avoid spinning idle workers.
+     */
+    concurrency?: number;
+    /** Optional filter applied post-collection. Return `false` to discard. */
+    filter?: (result: BatchResult) => boolean;
+    /**
+     * Streaming callback fired once per completed prompt (success OR failure).
+     * Caller exceptions are caught + logged to stderr without poisoning
+     * the batch (EC-5).
+     */
+    onResult?: (result: BatchResult) => void | Promise<void>;
+    /** Progress callback fired after each result. */
+    onProgress?: (progress: BatchProgress) => void;
+    /**
+     * Cancel pending prompts (ADR D140). In-flight prompts continue to
+     * completion (Node `AbortSignal` semantics). When `signal.reason` is
+     * an Error, it propagates to `BatchResult.error`; otherwise a generic
+     * "aborted" error is used.
+     */
+    signal?: AbortSignal;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). When set, the batch is
+     * registered as a `Task` (kind="batch") in the SDK's observable
+     * registry. The parent task transitions `finished` when every
+     * prompt is resolved (success OR failure).
+     *
+     * Use cases: surfacing a long-running batch in the `theokit tasks
+     * list` CLI, programmatic `Task.cancel(id)` aborting the batch, or
+     * binding a user-facing job dashboard. v1 does NOT yet emit one
+     * task PER prompt (single parent only); per-prompt tasks land in
+     * v0.2.
+     *
+     * Auto-generated id uses the `b-` reserved prefix (D368, EC-5).
+     *
+     * @public
+     */
+    task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+/**
+ * Per-prompt outcome. Discriminated union — check `ok` before reading
+ * `result` or `error`.
+ *
+ * @public
+ */
+export type BatchResult = {
+    ok: true;
+    index: number;
+    prompt: string;
+    result: RunResult;
+    metadata?: Record<string, unknown>;
+    durationMs: number;
+} | {
+    ok: false;
+    index: number;
+    prompt: string;
+    error: TheokitAgentError;
+    metadata?: Record<string, unknown>;
+    durationMs: number;
+};
+/**
+ * Live progress snapshot delivered to `onProgress`.
+ *
+ * @public
+ */
+export interface BatchProgress {
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    inFlight: number;
+}

package/dist/types/budget.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Public type contract for the Budget enforcement primitive
+ * (ADRs D375, D382-D387). The runtime facade lives in `budget.ts`.
+ *
+ * @public
+ */
+/**
+ * Scope of a budget — where the charge is attributed. v1 supports
+ * `process` (shared global) only; `agent` and `call` reserved for
+ * v0.2 multi-tenant scenarios.
+ */
+export type BudgetScope = "agent" | "call" | "process";
+/**
+ * Time window for a budget limit (D382 — UTC calendar-aligned).
+ * - `1h` is relative (last 60 minutes).
+ * - `1d` / `1w` / `30d` / `365d` are aligned to UTC calendar
+ *   boundaries (UTC midnight / monday 00:00 UTC / 1st 00:00 UTC).
+ */
+export type BudgetWindow = "1h" | "1d" | "1w" | "30d" | "365d";
+/**
+ * Enforcement mode (D383).
+ * - `audit`: log only, never throw, never block.
+ * - `warn`: callbacks fire at 80/95/100% thresholds; no throw.
+ * - `block`: preflightCheck throws `BudgetExceededError` BEFORE LLM call
+ *   when would-exceed.
+ */
+export type BudgetMode = "audit" | "warn" | "block";
+/** A single limit; stacked in an array (D384, ANY exceeded blocks). */
+export interface BudgetLimit {
+    readonly window: BudgetWindow;
+    readonly limitUsd: number;
+}
+/** Threshold event emitted at 80% and 95% in `warn` and `block` modes. */
+export interface BudgetThresholdEvent {
+    readonly budgetName: string;
+    readonly window: BudgetWindow;
+    readonly threshold: 0.8 | 0.95;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+}
+/** Exceed event emitted at 100% across all modes. */
+export interface BudgetExceedEvent {
+    readonly budgetName: string;
+    readonly window: BudgetWindow;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+    readonly mode: BudgetMode;
+}
+/** Options for `Budget.create`. */
+export interface BudgetOptions {
+    /**
+     * Identifier. Must match grammar `^[a-z0-9][a-z0-9_-]*$` (EC-7);
+     * empty/invalid → `ConfigurationError({ code: "invalid_budget_name" })`.
+     */
+    readonly name: string;
+    readonly scope: BudgetScope;
+    /**
+     * Stacked limits — at least one is expected for `warn`/`block`. Empty
+     * array (EC-19) is allowed → registry-only tracking, callbacks never
+     * fire.
+     */
+    readonly limits: ReadonlyArray<BudgetLimit>;
+    /** Default `warn` (D383). */
+    readonly mode?: BudgetMode;
+    /** Fires at 80% and 95% of any limit. Caller throws are isolated (EC-8). */
+    readonly onThreshold?: (event: BudgetThresholdEvent) => void | Promise<void>;
+    /** Fires at 100%. Caller throws are isolated (EC-8). */
+    readonly onExceed?: (event: BudgetExceedEvent) => void | Promise<void>;
+}
+/** Returned by `Budget.create` and `Budget.get` — read-only view. */
+export interface BudgetHandle {
+    readonly name: string;
+    readonly mode: BudgetMode;
+    readonly scope: BudgetScope;
+    readonly limits: ReadonlyArray<BudgetLimit>;
+    /** Snapshot spend for the given window. */
+    spentIn(window: BudgetWindow): number;
+    /** Remaining USD before the given window's limit is reached. */
+    remainingIn(window: BudgetWindow): number;
+}
+/** Per-window snapshot returned by `Budget.snapshot()`. */
+export interface BudgetSnapshot {
+    readonly name: string;
+    readonly window: BudgetWindow;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+    readonly ratio: number;
+}

package/dist/types/cache.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Public type contract for `Cache.semantic / .asPlugin / .stats / .clear`
+ * (Adoption Roadmap #6; ADRs D249-D266).
+ *
+ * @public
+ */
+export 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;
+}
+export 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.
+ */
+export interface CacheEmbedderRuntime {
+    readonly id: string;
+    readonly model: string;
+    readonly dimension: number;
+    embed(texts: ReadonlyArray<string>): Promise<number[][]>;
+}
+export 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;
+}
+export 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;
+}
+export interface CacheStats {
+    readonly entries: number;
+    readonly kvHits: number;
+    readonly semanticHits: number;
+    readonly misses: number;
+    readonly excluded: number;
+    readonly evicted: number;
+    readonly embedderFailures: number;
+}
+export declare class CacheEmbedderError extends Error {
+    readonly name = "CacheEmbedderError";
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+export declare class CacheInvalidTtlError extends Error {
+    readonly input: string | number;
+    readonly name = "CacheInvalidTtlError";
+    constructor(input: string | number);
+}

package/dist/types/context.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Context manager backend.
+ *
+ * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the
+ *   cloned repo (cloud).
+ *
+ * @public
+ */
+export type ContextManagerKind = "file";
+/**
+ * Context configuration accepted by `Agent.create()` via {@link AgentOptions.context}.
+ *
+ * @public
+ */
+export interface ContextSettings {
+    /** Which backend reads context. Defaults to `"file"`. */
+    manager?: ContextManagerKind;
+    /** Hard cap on tokens emitted into the agent's system prompt. */
+    maxTokens?: number;
+    /**
+     * Per-file truncation cap in characters. Default 40_000 (~10k tokens).
+     * Larger files are truncated with 70%/20% head/tail + marker (ADR D155).
+     *
+     * @public
+     */
+    maxBytesPerFile?: number;
+    /**
+     * Aggregate cap across all context files in characters. Default 120_000.
+     * When total exceeds this, lower-priority sources are dropped (ADR D155).
+     *
+     * Note: context snapshot is **refresh-time** (EC-T); modifying context
+     * files mid-flight does not auto-update. Call `agent.reload()` to pick
+     * up changes.
+     *
+     * @public
+     */
+    maxBytesTotal?: number;
+}
+/**
+ * Inclusion state of a single context source in a {@link ContextSnapshot}.
+ *
+ * @public
+ */
+export type ContextSourceStatus = "included" | "excluded" | "summarized";
+/**
+ * A single context source resolved by the context manager.
+ *
+ * @public
+ */
+export interface ContextSource {
+    /** Stable identifier — usually the filename without extension. */
+    name: string;
+    /** Path relative to the workspace root, when applicable. */
+    path?: string;
+    /** Whether the source was included, dropped, or summarized to fit the budget. */
+    status: ContextSourceStatus;
+    /** Free-text reason when `status !== "included"`. */
+    reason?: string;
+}
+/**
+ * Token budget used by the context manager for a single agent.
+ *
+ * @public
+ */
+export interface ContextBudget {
+    maxTokens?: number;
+    /**
+     * Either a token count or a list of token strings extracted from source
+     * content. Normalized to `<tokens>` in golden comparisons.
+     */
+    usedTokens?: number | string[];
+}
+/**
+ * Result of `agent.context.snapshot()`. Public and secret-free by design — safe
+ * to log and persist. Raw secrets, local absolute paths, and exact token values
+ * are never present.
+ *
+ * @public
+ */
+export interface ContextSnapshot {
+    runtime: "local" | "cloud";
+    sources: ContextSource[];
+    budget?: ContextBudget;
+}
+/**
+ * Public context manager handle exposed as `agent.context`.
+ *
+ * @public
+ */
+export interface SDKContextManager {
+    /** Inspect what the context manager actually loaded for the agent. */
+    snapshot(): Promise<ContextSnapshot>;
+}

package/dist/types/conversation-storage.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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
+ */
+export 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
+ */
+export 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>;
+}

package/dist/types/conversation.d.ts

@@ -0,0 +1,90 @@
+import type { ToolCall } from "./updates.js";
+/**
+ * Plain assistant message in a conversation history.
+ *
+ * @public
+ */
+export interface AssistantMessage {
+    text: string;
+}
+/**
+ * Reasoning step in a conversation history.
+ *
+ * @public
+ */
+export interface ThinkingMessage {
+    text: string;
+    thinkingDurationMs?: number;
+}
+/**
+ * User-authored message in a conversation history.
+ *
+ * @public
+ */
+export interface UserMessage {
+    text: string;
+}
+/**
+ * Shell command executed during a run.
+ *
+ * @public
+ */
+export interface ShellCommand {
+    command: string;
+    workingDirectory?: string;
+}
+/**
+ * Output of a shell command.
+ *
+ * @public
+ */
+export interface ShellOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Single step inside an agent turn.
+ *
+ * @public
+ */
+export type ConversationStep = {
+    type: "assistantMessage";
+    message: AssistantMessage;
+} | {
+    type: "toolCall";
+    message: ToolCall;
+} | {
+    type: "thinkingMessage";
+    message: ThinkingMessage;
+};
+/**
+ * Agent turn: user message + assistant/tool/thinking steps.
+ *
+ * @public
+ */
+export interface AgentConversationTurn {
+    userMessage?: UserMessage;
+    steps: ConversationStep[];
+}
+/**
+ * Shell turn: a command and its output.
+ *
+ * @public
+ */
+export interface ShellConversationTurn {
+    shellCommand?: ShellCommand;
+    shellOutput?: ShellOutput;
+}
+/**
+ * Structured per-turn view of a run.
+ *
+ * @public
+ */
+export type ConversationTurn = {
+    type: "agentConversationTurn";
+    turn: AgentConversationTurn;
+} | {
+    type: "shellConversationTurn";
+    turn: ShellConversationTurn;
+};

package/dist/types/cron.d.ts

@@ -0,0 +1,150 @@
+import type { AgentOptions } from "./agent.js";
+import type { SDKUserMessage } from "./run.js";
+/**
+ * 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
+ */
+export type CronRuntime = "local" | "cloud";
+/**
+ * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
+ *
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export type CronListOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: string;
+});
+/**
+ * Options for `Cron.get()`.
+ *
+ * @public
+ */
+export interface CronGetOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
+ *
+ * @public
+ */
+export interface CronOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.run()` — manually trigger a job off-schedule.
+ *
+ * @public
+ */
+export interface CronRunOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.start()` — activates the in-process scheduler for local
+ * jobs.
+ *
+ * @public
+ */
+export 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
+ */
+export 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;
+    };
+}