@theokit/sdk 1.5.0

package/dist/types/messages.d.ts

@@ -0,0 +1,154 @@
+import type { ModelSelection } from "./agent.js";
+/**
+ * Plain text content block emitted by the assistant or user.
+ *
+ * @public
+ */
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+/**
+ * Tool invocation block emitted by the assistant.
+ *
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export interface SDKUserMessageEvent {
+    type: "user";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "user";
+        content: TextBlock[];
+    };
+}
+/**
+ * Model text output for this run.
+ *
+ * @public
+ */
+export interface SDKAssistantMessage {
+    type: "assistant";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "assistant";
+        content: Array<TextBlock | ToolUseBlock>;
+    };
+}
+/**
+ * Reasoning content.
+ *
+ * @public
+ */
+export 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
+ */
+export 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;
+    };
+}
+/**
+ * Cloud run lifecycle transitions.
+ *
+ * @public
+ */
+export interface SDKStatusMessage {
+    type: "status";
+    agent_id: string;
+    run_id: string;
+    status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED";
+    message?: string;
+}
+/**
+ * Task-level milestones and summaries.
+ *
+ * @public
+ */
+export interface SDKTaskMessage {
+    type: "task";
+    agent_id: string;
+    run_id: string;
+    status?: string;
+    text?: string;
+}
+/**
+ * Awaiting user input or approval.
+ *
+ * @public
+ */
+export interface SDKRequestMessage {
+    type: "request";
+    agent_id: string;
+    run_id: string;
+    request_id: 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.
+ *
+ * @public
+ */
+export interface SDKObjectDelta {
+    type: "object_delta";
+    agent_id: string;
+    run_id: string;
+    partial: unknown;
+    attempt: number;
+}
+/**
+ * Discriminated union of all stream events. Discriminate on `type`.
+ *
+ * All events include `agent_id` and `run_id`.
+ *
+ * @public
+ */
+export type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;

package/dist/types/providers.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Capability slot a provider can fulfill.
+ *
+ * @public
+ */
+export type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
+/**
+ * A single user-declared routing rule. Maps a capability to a provider, and
+ * optionally pins a specific model.
+ *
+ * @public
+ */
+export interface ProviderRoute {
+    capability: ProviderCapability;
+    provider: string;
+    model?: string;
+}
+/**
+ * Provider routing configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.providers}.
+ *
+ * @public
+ */
+export interface ProviderRoutingSettings {
+    /** Explicit `{ capability → provider }` map. First match wins per capability. */
+    routes: ProviderRoute[];
+    /** Provider names to try in order when a route has no provider available. */
+    fallback?: string[];
+    /**
+     * Multiple API keys per provider for same-provider key rotation
+     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
+     * or 401, the SDK rotates to the next entry transparently before
+     * falling back to a different provider.
+     *
+     * Example:
+     * ```ts
+     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
+     * ```
+     *
+     * Empty arrays and empty strings are filtered out. If a provider has
+     * exactly 1 effective key, the pool is transparent (no rotation behavior).
+     *
+     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
+     * use one OR the other, not both.
+     *
+     * @public
+     */
+    apiKeys?: Record<string, string[]>;
+    /**
+     * Rotation strategy per provider for the credential pool. Default is
+     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
+     * `apiKeys[provider]` has ≥2 entries.
+     *
+     * @public
+     */
+    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
+}
+/**
+ * Plugins configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.plugins}.
+ *
+ * @public
+ */
+export interface PluginsSettings {
+    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
+    enabled?: string[];
+}
+/**
+ * Resolved routing decision returned by `agent.providers.routes()`. Public and
+ * secret-free by design — safe to log.
+ *
+ * @public
+ */
+export interface ResolvedProviderRoute {
+    capability: string;
+    provider: string;
+    model?: string;
+    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
+    reason: string;
+}
+/**
+ * Public providers manager handle exposed as `agent.providers`.
+ *
+ * @public
+ */
+export interface SDKProvidersManager {
+    /** Inspect which provider serves each capability for this agent. */
+    routes(): Promise<ResolvedProviderRoute[]>;
+}
+/**
+ * Provider catalog entry returned by `Theokit.providers.list()`.
+ *
+ * @public
+ */
+export interface SDKProvider {
+    name: string;
+    displayName: string;
+    capabilities: string[];
+    isAvailable: boolean;
+    /** JSON Schema describing the env vars / fields needed to enable this provider. */
+    setupSchema: object;
+}

package/dist/types/run.d.ts

@@ -0,0 +1,215 @@
+import type { CustomTool, ModelSelection } from "./agent.js";
+import type { ConversationStep, ConversationTurn } from "./conversation.js";
+import type { McpServerConfig } from "./mcp.js";
+import type { SDKMessage } from "./messages.js";
+import type { InteractionUpdate } from "./updates.js";
+import type { CostBreakdown, TokenUsage } from "./usage.js";
+/**
+ * Lifecycle status of a {@link Run}.
+ *
+ * @public
+ */
+export 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
+ */
+export type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "usePersonality" | "workflow";
+/**
+ * Git metadata attached to cloud runs.
+ *
+ * @public
+ */
+export interface RunGitInfo {
+    branches: Array<{
+        repoUrl: string;
+        branch?: string;
+        prUrl?: string;
+    }>;
+}
+/**
+ * Terminal result of a {@link Run}.
+ *
+ * @public
+ */
+export interface RunResult {
+    id: string;
+    status: "finished" | "error" | "cancelled";
+    result?: string;
+    model?: ModelSelection;
+    durationMs?: number;
+    git?: RunGitInfo;
+    /**
+     * 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()`.
+     *
+     * For successful runs (`status: "finished"`) this is undefined.
+     *
+     * @public
+     */
+    error?: RunErrorDetail;
+    /**
+     * 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).
+     *
+     * @public
+     */
+    usage?: TokenUsage;
+    /**
+     * Estimated/actual USD cost for this run (ADR D377). Always paired
+     * with `usage` when populated. `cost.status` tells caller how to
+     * trust the figure.
+     *
+     * @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
+ */
+export interface RunErrorDetail {
+    message: string;
+    code?: string;
+    cause?: unknown;
+}
+/**
+ * Dimensions of an inline image attachment.
+ *
+ * @public
+ */
+export interface SDKImageDimension {
+    width: number;
+    height: number;
+}
+/**
+ * Either a remote URL or inline base64 payload.
+ *
+ * @public
+ */
+export 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
+ */
+export interface SDKUserMessage {
+    text: string;
+    images?: SDKImage[];
+}
+/**
+ * Per-send overrides and callbacks.
+ *
+ * @public
+ */
+export interface SendOptions {
+    model?: ModelSelection;
+    /**
+     * 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).
+     */
+    systemPrompt?: string;
+    /** Fully replaces creation-time servers for this run (not merged). */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * 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
+     */
+    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;
+    };
+    /**
+     * 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).
+     *
+     * @public
+     */
+    signal?: AbortSignal;
+    /**
+     * 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).
+     *
+     * 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.
+     *
+     * The work-fn `signal` is **merged** with `options.signal` (whichever
+     * aborts first wins). Local agents only — CloudAgent throws
+     * `UnsupportedTaskOperationError` (D370).
+     *
+     * @public
+     */
+    task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+/**
+ * Handle to a single prompt submission.
+ *
+ * @public
+ */
+export 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;
+}

package/dist/types/task.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Public type contract for the Task observability registry (ADRs D361-D374).
+ *
+ * Tasks are an opt-in observability layer over async work in the SDK
+ * (`Agent.send`, `Agent.batch`, `Workflow.run`, `Cron` fires). They have
+ * a closed 5-state lifecycle (D362), discriminated events (D366), and a
+ * pluggable store (D364). The `Task` facade in `task.ts` is the public
+ * surface; consumers import these types from `@theokit/sdk`.
+ *
+ * @public
+ */
+/**
+ * Closed enum of the 5 lifecycle states (D362).
+ *
+ * Transitions are acyclic:
+ *   queued → running → (finished | error | cancelled)
+ *   queued → cancelled (direct, no run started)
+ */
+export type TaskState = "queued" | "running" | "finished" | "error" | "cancelled";
+/** Discriminator of the runtime that produced a task (D374). */
+export type TaskKind = "run" | "batch" | "workflow" | "cron" | "custom";
+/** Discriminated union of task lifecycle events (D366). */
+export type TaskEvent = {
+    readonly type: "submitted";
+    readonly taskId: string;
+    readonly kind: TaskKind;
+    readonly submittedAt: number;
+    readonly meta?: Record<string, unknown>;
+    /** D372 — flag set on the first yielded event when the ring buffer was at cap. */
+    readonly truncated?: boolean;
+} | {
+    readonly type: "started";
+    readonly taskId: string;
+    readonly startedAt: number;
+} | {
+    readonly type: "progress";
+    readonly taskId: string;
+    readonly at: number;
+    readonly payload: unknown;
+} | {
+    readonly type: "finished";
+    readonly taskId: string;
+    readonly finishedAt: number;
+    readonly result: unknown;
+} | {
+    readonly type: "errored";
+    readonly taskId: string;
+    readonly erroredAt: number;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "cancelled";
+    readonly taskId: string;
+    readonly cancelledAt: number;
+    readonly reason?: string;
+};
+/** Public read-only view of a task entry in the registry. */
+export interface TaskHandle {
+    readonly id: string;
+    readonly kind: TaskKind;
+    readonly state: TaskState;
+    readonly submittedAt: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly cancelledAt?: number;
+    readonly erroredAt?: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly meta?: Record<string, unknown>;
+    /**
+     * EC-7 — cross-process best-effort cancel flag. Set by CLI
+     * `theokit tasks cancel` via JsonFileTaskStore. The owning process
+     * polls at checkpoints and honors via AbortController. Always
+     * `undefined` for in-process cancel paths (which go directly through
+     * AbortController).
+     */
+    readonly cancelRequested?: boolean;
+}
+/** Query filter for `Task.list`. */
+export interface TaskFilter {
+    readonly state?: TaskState | readonly TaskState[];
+    readonly kind?: TaskKind | readonly TaskKind[];
+    readonly submittedAfter?: number;
+    readonly submittedBefore?: number;
+    /** Defaults to 100. JsonFileTaskStore hard-caps loaded entries at 256 (D364). */
+    readonly limit?: number;
+}
+/** Options for `Task.submit`. */
+export interface TaskSubmitOptions {
+    /**
+     * Optional user-supplied ID. Must match grammar `^[a-z0-9][a-z0-9_-]*$`
+     * and MUST NOT start with the reserved prefixes `wf-` / `b-` / `cron-`
+     * (D368, EC-5). When omitted, `crypto.randomUUID()` is used.
+     */
+    readonly id?: string;
+    readonly meta?: Record<string, unknown>;
+    /**
+     * Optional caller-provided AbortSignal. If already aborted at submit
+     * time, the registry short-circuits to `cancelled` without acquiring
+     * a semaphore slot (EC-4).
+     */
+    readonly signal?: AbortSignal;
+}
+/** Options shape for `TaskStore` factory (D364). */
+export type TaskStoreOptions = {
+    readonly backend: "memory";
+} | {
+    readonly backend: "json";
+    readonly dir: string;
+};
+/** Result of `Task.cancel` (D365 — idempotent). */
+export interface TaskCancelResult {
+    readonly cancelled: boolean;
+    readonly alreadyTerminal: boolean;
+}
+/**
+ * Validates a task ID against the public grammar + reserved prefixes.
+ * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
+ *
+ * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
+ * to register their own IDs; user-facing surfaces (`Task.submit`,
+ * `agent.send({ task: { id } })`) leave it false.
+ */
+export declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
+/** Re-exported for adapter implementations + tests. */
+export declare const TASK_RESERVED_PREFIXES: readonly string[];

package/dist/types/theokit.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Account-level user info returned by `Theokit.me()`.
+ *
+ * @public
+ */
+export interface SDKUser {
+    apiKeyName: string;
+    userEmail?: string;
+    createdAt: string;
+}
+/**
+ * Per-model parameter definition discovered from `Theokit.models.list()`.
+ *
+ * @public
+ */
+export interface ModelParameterDefinition {
+    id: string;
+    displayName?: string;
+    values: Array<{
+        value: string;
+        displayName?: string;
+    }>;
+}
+/**
+ * Preset variant for a model — pre-filled parameter combinations.
+ *
+ * @public
+ */
+export interface ModelVariant {
+    params: Array<{
+        id: string;
+        value: string;
+    }>;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+}
+/**
+ * Single model entry in the catalog.
+ *
+ * @public
+ */
+export interface ModelListItem {
+    id: string;
+    /** Short, plain-text model name. Mirrors `displayName` for typical SDKs. */
+    name?: string;
+    displayName: string;
+    description?: string;
+    parameters?: ModelParameterDefinition[];
+    variants?: ModelVariant[];
+}
+/** @public */
+export type SDKModel = ModelListItem;
+/**
+ * GitHub repository connected to the team. Cloud-only.
+ *
+ * @public
+ */
+export interface SDKRepository {
+    url: string;
+}

package/dist/types/trajectory.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Public types for ShareGPT trajectory export (ADR D139).
+ *
+ * Output format for fine-tuning datasets — consumed by HuggingFace, Axolotl,
+ * LLaMA-Factory, and most modern fine-tuning toolchains. Pure data shape;
+ * no runtime dependency.
+ *
+ * @public
+ */
+/**
+ * One ShareGPT message in a conversation. `from` identifies the role and
+ * `value` carries the textual content. Tool calls live in `tool_calls`
+ * (assistant-only) and tool results re-enter as `from: "tool"` entries.
+ *
+ * @public
+ */
+export interface ShareGptMessage {
+    /** "human" for user, "gpt" for assistant, "tool" for tool result, "system" for system. */
+    from: "human" | "gpt" | "tool" | "system";
+    /** The message text. Empty string is valid (preserves turn boundary). */
+    value: string;
+    /** Optional tool calls — only emitted when `from === "gpt"`. */
+    tool_calls?: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+}
+/**
+ * One full ShareGPT-format trajectory — a single conversation plus
+ * metadata. JSONL-friendly (one trajectory per line when serialized).
+ *
+ * @public
+ */
+export interface ShareGptTrajectory {
+    conversations: ShareGptMessage[];
+    metadata?: {
+        model?: string;
+        timestamp: string;
+        durationMs: number;
+        promptIndex: number;
+    };
+    /** `true` when the source `BatchResult.ok === true`. Always `true` in current shape. */
+    completed: boolean;
+    /** Token usage when surfaced by the underlying RunResult (provider-specific). */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}