@theokit/sdk 1.5.0

package/dist/types/eval.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Public type contract for `Eval.create / .run` and the `Scorers` namespace
+ * (Adoption Roadmap #2; ADRs D202-D213).
+ *
+ * Consumers import these types via `@theokit/sdk` — they're re-exported
+ * from the package barrel. Implementation lives in `eval.ts`, `scorers.ts`,
+ * and `internal/eval/**`.
+ *
+ * @public
+ */
+import type { SDKAgent } from "./agent.js";
+/** Inferred `Agent.create` options shape — avoid cycling through `AgentOptions` directly. */
+export type EvalAgentOptions = Parameters<typeof import("../agent.js").Agent.create>[0];
+/** A single dataset row — input prompt + optional reference + free-form metadata. */
+export interface DatasetEntry {
+    readonly input: string;
+    readonly expected?: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * `Dataset` is either an array OR a factory returning a (sync or async)
+ * iterable (D210). The runner normalizes both shapes into an
+ * `AsyncIterable<DatasetEntry>` internally.
+ */
+export type Dataset = ReadonlyArray<DatasetEntry> | (() => Iterable<DatasetEntry> | AsyncIterable<DatasetEntry>);
+/** Outcome of a single scoring decision. `score` in [0, 1]; the runner clamps. */
+export interface Score {
+    readonly score: number;
+    readonly reason?: string;
+}
+/**
+ * Scorer signature (D207). Returns `Score` synchronously OR via Promise —
+ * the runner always awaits.
+ */
+export type Scorer = (output: string, expected?: unknown) => Score | Promise<Score>;
+/** A named scorer — produced by every `Scorers.*` factory. */
+export interface NamedScorer {
+    readonly name: string;
+    readonly score: Scorer;
+}
+/** Lifecycle hooks. Each fires inside a `safeHook` wrapper (EC-4); a throw never aborts the run. */
+export interface EvalHooks {
+    readonly beforeRun?: (info: {
+        name: string;
+        totalEstimate: number | undefined;
+    }) => void;
+    readonly afterRow?: (row: EvalRowResult, index: number) => void;
+    readonly afterRun?: (run: EvalRun) => void;
+}
+/** Public options for `Eval.create`. */
+export interface EvalOptions {
+    /**
+     * Unique-per-process name for telemetry correlation + report titles.
+     * Concurrent runs with the same name throw `EvalAlreadyRunningError` (D213).
+     */
+    readonly name: string;
+    /** The dataset to evaluate. See {@link Dataset}. */
+    readonly dataset: Dataset;
+    /** At least one scorer. Plain `Scorer` is wrapped with an auto-name. */
+    readonly scorers: ReadonlyArray<Scorer | NamedScorer>;
+    /**
+     * Agent to evaluate. Three accepted shapes:
+     *  - `SDKAgent` instance — same agent used for every row (no state isolation).
+     *  - `EvalAgentOptions` — a fresh agent is constructed per row (state isolation; default).
+     *  - `(entry) => SDKAgent | Promise<SDKAgent>` — dynamic agent selection.
+     */
+    readonly agent: SDKAgent | EvalAgentOptions | ((entry: DatasetEntry) => SDKAgent | Promise<SDKAgent>);
+    /**
+     * Row concurrency. Default 4 (matches `Agent.batch` D136). MUST be in
+     * `[1, 64]` (EC-3 — 0 deadlocks the semaphore, Infinity DoSs the provider).
+     */
+    readonly concurrency?: number;
+    /** Optional metadata persisted to `EvalRun.metadata` (tags, env, version). */
+    readonly metadata?: Record<string, unknown>;
+    /** Optional progress / lifecycle hooks. */
+    readonly hooks?: EvalHooks;
+}
+/** Per-row outcome. */
+export interface EvalRowResult {
+    readonly index: number;
+    readonly input: string;
+    readonly output: string;
+    readonly expected?: unknown;
+    readonly scores: ReadonlyArray<{
+        readonly name: string;
+        readonly score: number;
+        readonly reason?: string;
+    }>;
+    readonly meanScore: number;
+    readonly durationMs: number;
+    readonly tokensIn?: number;
+    readonly tokensOut?: number;
+    readonly error?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Per-scorer breakdown computed across all rows. */
+export interface PerScorerStats {
+    readonly mean: number;
+    readonly median: number;
+    readonly min: number;
+    readonly max: number;
+}
+/** Aggregate stats — the production-decision dashboard data (D211). */
+export interface EvalAggregate {
+    readonly meanScore: number;
+    readonly medianScore: number;
+    /** Ratio of rows where `meanScore >= 0.5`. */
+    readonly passRatio: number;
+    readonly perScorer: Record<string, PerScorerStats>;
+    readonly totalRows: number;
+    readonly errorRows: number;
+    readonly durationMsP50: number;
+    readonly durationMsP95: number;
+    readonly tokensInTotal: number;
+    readonly tokensOutTotal: number;
+}
+/** Final run result — plain serializable JSON (D209). */
+export interface EvalRun {
+    readonly id: string;
+    readonly name: string;
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly durationMs: number;
+    readonly aggregate: EvalAggregate;
+    readonly rows: ReadonlyArray<EvalRowResult>;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Per-call options for `eval.run(...)`. */
+export interface EvalRunOptions {
+    /** Cancels pending rows; in-flight rows complete (D140 pattern). */
+    readonly signal?: AbortSignal;
+}

package/dist/types/goal-events.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Public event types emitted by {@link SDKAgent.runUntil} (ADRs D115-D117).
+ *
+ * Discriminated union by `type` field so consumers can `switch (event.type)`
+ * with full TypeScript exhaustiveness. Mirrors the
+ * {@link import("../stream-object.js").StreamObjectEvent} pattern (ADR D39).
+ *
+ * @public
+ */
+/**
+ * Single event emitted while iterating a goal-driven loop. Five variants:
+ *
+ * - `turn_start` — the agent is about to invoke `send()`. Emitted once
+ *   per turn.
+ * - `agent_response` — the agent's `send()` resolved; carries the text
+ *   reply.
+ * - `judge_verdict` — the auxiliary judge model evaluated the response.
+ *   `parseFailed: true` indicates the judge returned a malformed reply
+ *   (fail-safe verdict = `continue`, see ADR D121).
+ * - `continuation` — the judge ruled `continue`; carries the prompt that
+ *   was sent on THIS turn (i.e., the input that produced the agent
+ *   response just yielded). Useful for consumers who want to audit the
+ *   exact continuation message that drove each iteration. The prompt
+ *   for the NEXT turn is composed lazily at the start of that turn
+ *   from the latest `agent_response.content`.
+ * - `status_change` — transition of the overall goal state. Always
+ *   emitted once at start (`active`) and once at end
+ *   (`completed | failed | paused`).
+ *
+ * @public
+ */
+export type GoalEvent = {
+    type: "turn_start";
+    turn: number;
+    goal: string;
+} | {
+    type: "agent_response";
+    turn: number;
+    content: string;
+} | {
+    type: "judge_verdict";
+    turn: number;
+    verdict: "done" | "continue" | "skipped";
+    reason: string;
+    parseFailed: boolean;
+} | {
+    type: "continuation";
+    turn: number;
+    prompt: string;
+} | {
+    type: "status_change";
+    status: "active" | "paused" | "completed" | "failed";
+    reason: string;
+};
+/**
+ * Return value of the `runUntil` async generator. Consumer reads via
+ * `const { value } = await gen.next()` (when `done: true`).
+ *
+ * @public
+ */
+export interface GoalResult {
+    status: "completed" | "failed" | "paused";
+    turnsUsed: number;
+    finalResponse: string | undefined;
+}
+/**
+ * Return type of {@link import("../internal/runtime/local-agent.js").LocalAgent.runUntil}.
+ * Extracted so the LocalAgent method signature stays a single line (G8 LoC budget).
+ *
+ * @public
+ */
+export type RunUntilIterator = AsyncGenerator<GoalEvent, GoalResult, void>;
+/**
+ * Per-call configuration for `Agent.runUntil`.
+ *
+ * @public
+ */
+export interface GoalOptions {
+    /** Hard cap on iterations. Default `20`. */
+    maxTurns?: number;
+    /** Bail after N consecutive judge parse failures. Default `3` (ADR D121). */
+    maxConsecutiveJudgeFailures?: number;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
+    judgeApiKey?: string;
+    /** Optional subgoals fed to the judge prompt. */
+    subgoals?: string[];
+    /**
+     * Cancel mid-loop via `AbortController.signal`. The generator yields
+     * a `status_change: paused` event and returns at the next turn
+     * boundary (ADR D117).
+     */
+    signal?: AbortSignal;
+}

package/dist/types/handoff.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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
+ */
+import type { ZodType } from "zod";
+import type { SDKAgent } from "./agent.js";
+/**
+ * Context handed to `onHandoff` callbacks and `isEnabled` predicates.
+ * Read-only snapshot of the handoff dispatch state.
+ */
+export 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).
+ */
+export interface HandoffHistory {
+    readonly messages: ReadonlyArray<unknown>;
+}
+/**
+ * Options accepted by `Handoff.create(target, opts?)`.
+ *
+ * @public
+ */
+export 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
+ */
+export 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). */
+export 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). */
+export 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). */
+export declare class HandoffSelfReferenceError extends Error {
+    readonly name = "HandoffSelfReferenceError";
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+/** Throw when receiver is disposed at dispatch time (EC-5). */
+export 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). */
+export 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
+ */
+export 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;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,20 @@
+export type * from "./agent.js";
+export type * from "./batch.js";
+export type * from "./budget.js";
+export type * from "./cache.js";
+export type * from "./context.js";
+export type * from "./conversation.js";
+export type * from "./conversation-storage.js";
+export type * from "./cron.js";
+export type * from "./goal-events.js";
+export type * from "./handoff.js";
+export type * from "./mcp.js";
+export type * from "./memory-adapter.js";
+export type * from "./messages.js";
+export type * from "./providers.js";
+export type * from "./run.js";
+export type * from "./task.js";
+export type * from "./theokit.js";
+export type * from "./trajectory.js";
+export type * from "./updates.js";
+export type * from "./usage.js";

package/dist/types/mcp.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
+ *
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;

package/dist/types/memory-adapter.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
+ *
+ * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
+ * `createProvider` factory; this file types its return value formally.
+ * Adapters implement `write` / `recall` / `delete` plus optional methods
+ * gated by `capabilities`. `MemoryId` is a branded string prefixed with
+ * the adapter id so cross-adapter use throws on `extractRawId` (EC-B).
+ *
+ * Each provider-specific package (`@theokit-memory-supermemory`, etc)
+ * exports a factory returning a `Plugin { kind: "memory" }` whose
+ * `createProvider` resolves to a `MemoryAdapter` instance.
+ *
+ * @public
+ */
+/**
+ * Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
+ * Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
+ * to construct and unwrap with cross-adapter safety (EC-B).
+ *
+ * @public
+ */
+export type MemoryId = string & {
+    readonly __brand: "MemoryId";
+};
+/**
+ * Portable identity context. `userId` is the only required field —
+ * the lowest common denominator across Supermemory / Honcho / Mem0.
+ * Adapter implementations translate the optional fields to their
+ * provider's native primitives (Honcho session, Mem0 run_id, etc).
+ *
+ * @public
+ */
+export interface MemoryContext {
+    /** End-user identity. */
+    userId: string;
+    /** Agent / persona writing the memory. */
+    agentId?: string;
+    /** Logical conversation / run boundary. */
+    sessionId?: string;
+    /** Tenant / workspace partition. */
+    tenantId?: string;
+    /** Free-form tags for filtering / categorization. */
+    tags?: string[];
+    /** Provider-passthrough metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A single memory fact returned by `recall` or `get`.
+ *
+ * @public
+ */
+export interface MemoryFact {
+    id: MemoryId;
+    content: string;
+    /** Semantic relevance score (provider-defined scale) when result of `recall`. */
+    score?: number;
+    /** ISO 8601 timestamp of creation. */
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Versioned snapshot of a memory's history. Only emitted by providers
+ * with `capabilities.history === true` (Mem0 today).
+ *
+ * @public
+ */
+export interface MemoryRevision {
+    id: MemoryId;
+    content: string;
+    version: number;
+    changedAt: string;
+}
+/**
+ * Statically declared adapter feature flags. Consumers feature-detect
+ * at compile time via `if (adapter.capabilities.history)`.
+ *
+ * @public
+ */
+export interface MemoryAdapterCapabilities {
+    /** Returns prior versions of a memory via `history(id)`. */
+    history: boolean;
+    /** First-class `sessionId` scoping. */
+    sessions: boolean;
+    /** First-class `tenantId` scoping. */
+    tenancy: boolean;
+    /** Provider performs reasoning over memory (e.g., Honcho dialectic). */
+    reasoning: boolean;
+    /** Exposes LLM-callable function-calling schemas. */
+    toolSchemas: boolean;
+    /** Supports background prefetch (currently informational). */
+    prefetch: boolean;
+}
+/**
+ * One assistant-turn message in the canonical `{role, content}` shape
+ * an adapter may receive instead of a flat string when writing a turn.
+ *
+ * @public
+ */
+export interface MemoryTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * OpenAI-format function-calling schema exposed to the LLM.
+ *
+ * @public
+ */
+export interface MemoryToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Portable third-party memory adapter contract. Implementations live
+ * in `@theokit-memory-*` packages; the SDK never imports them.
+ *
+ * @public
+ */
+export interface MemoryAdapter {
+    /** Short identifier — matches the `${adapterId}` prefix in `MemoryId`. */
+    readonly id: string;
+    readonly capabilities: MemoryAdapterCapabilities;
+    /** Synchronous availability probe — no network, no I/O. */
+    isAvailable(): boolean;
+    /** One-shot initialization. Idempotent: safe to call multiple times. */
+    initialize?(): Promise<void>;
+    /**
+     * Persist a fact or full turn to memory. Returns the stored
+     * `MemoryId`. Throws `MemoryAdapterError(code: "invalid_input")` on
+     * empty content or invalid identifiers in `ctx`.
+     */
+    write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId>;
+    /**
+     * Semantic recall — top-`k` facts ordered by relevance. Returns
+     * empty array when `k === 0` or no matches.
+     */
+    recall(query: string, ctx: MemoryContext, k?: number): Promise<MemoryFact[]>;
+    /**
+     * Delete a memory by id. Throws `MemoryAdapterError(code:
+     * "invalid_input")` when the id was minted by a different adapter
+     * (EC-B). Throws `code: "not_found"` when the id does not exist.
+     */
+    delete(id: MemoryId): Promise<void>;
+    list?(ctx: MemoryContext, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): AsyncIterable<MemoryFact>;
+    get?(id: MemoryId): Promise<MemoryFact | null>;
+    history?(id: MemoryId): Promise<MemoryRevision[]>;
+    /** Empty array when `capabilities.toolSchemas === false`. */
+    getToolSchemas?(): MemoryToolSchema[];
+    handleToolCall?(name: string, args: Record<string, unknown>, ctx: MemoryContext): Promise<string>;
+    /** Graceful shutdown — flush queues, close connections. */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
+ * memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.
+ *
+ * @public
+ */
+export interface AgentMemory {
+    /**
+     * Persist a fact. Returns the first adapter's id; in multi-adapter
+     * setups all adapters receive the write (fan-out).
+     */
+    write(content: string | MemoryTurnMessage[], ctx?: Partial<MemoryContext>): Promise<MemoryId>;
+    /** Semantic recall — merged + deduped across registered adapters. */
+    recall(query: string, ctx?: Partial<MemoryContext>, k?: number): Promise<MemoryFact[]>;
+    /** Delete a memory by id — routes to the owning adapter via prefix. */
+    delete(id: MemoryId): Promise<void>;
+    /** Returns the first registered adapter or `null` when none exists. */
+    adapter(): MemoryAdapter | null;
+}