@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/types/task.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Owner: `internal/task/` (4 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * 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;
+    /**
+     * Why the task was cancelled, when whoever cancelled it said. Free text, written alongside
+     * `cancelledAt` for a `queued` task and alongside `cancelRequested` for a `running` one.
+     *
+     * Absent when no reason was given — an empty string is not a reason, and a default like
+     * "cancelled" would put words in the operator's mouth. `theokit tasks cancel --reason` is what
+     * writes it (#351); nothing in the runtime reads it, because it exists for the human reading the
+     * registry later.
+     */
+    readonly cancelReason?: string;
+}
+/** 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` returns the newest matching tasks first and reads its
+     * whole directory to find them (256 files at a time); page past this limit with
+     * `submittedBefore` (#362).
+     */
+    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;
+    /**
+     * SE2 — an opt-in {@link import("./run-events.js").RunEventSink}. The task's
+     * lifecycle is forwarded to it as typed `task_started` / `task_updated` /
+     * `task_completed` RunEvents, so a caller that spawned the task can observe it
+     * through the same `onRunEvent` channel as the rest of the run. Best-effort (a
+     * throwing sink never breaks the task). The dedicated `Task.subscribe(id)`
+     * channel is unaffected.
+     */
+    readonly onRunEvent?: import("./run-events.js").RunEventSink;
+}
+/** 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;
+}

package/dist/types/theokit.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Owner: `internal/catalog/` (2 of 3 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * 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[];
+}
+/**
+ * Alias of {@link ModelListItem}, used where a model comes back from the Theokit platform rather
+ * than from a catalog listing.
+ *
+ * It is the SAME type, not a narrowed one — the alias exists so platform-facing signatures read in
+ * platform vocabulary alongside `SDKRepository` and `SDKUser`, and a value of either name is
+ * assignable to the other.
+ *
+ * @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,52 @@
+/**
+ * Owner: `src/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * 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;
+    };
+}

package/dist/types/updates.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Owner: `internal/agent-loop/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+import type { UserMessage } from "./messages-base.js";
+/**
+ * Single tool call event. The internal `args` and `result` shapes are NOT stable.
+ *
+ * @public
+ */
+export interface ToolCall {
+    callId: string;
+    name: string;
+    args?: unknown;
+    result?: unknown;
+}
+/**
+ * Incremental text token from the assistant.
+ *
+ * @public
+ */
+export interface TextDeltaUpdate {
+    type: "text-delta";
+    text: string;
+}
+/**
+ * Incremental reasoning token.
+ *
+ * @public
+ */
+export interface ThinkingDeltaUpdate {
+    type: "thinking-delta";
+    text: string;
+}
+/**
+ * Emitted when a reasoning block completes.
+ *
+ * @public
+ */
+export interface ThinkingCompletedUpdate {
+    type: "thinking-completed";
+    thinkingDurationMs: number;
+}
+/**
+ * Tool call started — args committed.
+ *
+ * @public
+ */
+export interface ToolCallStartedUpdate {
+    type: "tool-call-started";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call arguments streaming in incrementally.
+ *
+ * @public
+ */
+export interface PartialToolCallUpdate {
+    type: "partial-tool-call";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call completed.
+ *
+ * @public
+ */
+export interface ToolCallCompletedUpdate {
+    type: "tool-call-completed";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Token count delta for usage tracking.
+ *
+ * @public
+ */
+export interface TokenDeltaUpdate {
+    type: "token-delta";
+    tokens: number;
+}
+/**
+ * Conversation step started.
+ *
+ * @public
+ */
+export interface StepStartedUpdate {
+    type: "step-started";
+    stepId: number;
+}
+/**
+ * Conversation step completed.
+ *
+ * @public
+ */
+export interface StepCompletedUpdate {
+    type: "step-completed";
+    stepId: number;
+    stepDurationMs: number;
+}
+/**
+ * Turn ended with usage summary.
+ *
+ * @public
+ */
+export interface TurnEndedUpdate {
+    type: "turn-ended";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    };
+}
+/**
+ * User message appended to the conversation.
+ *
+ * @public
+ */
+export interface UserMessageAppendedUpdate {
+    type: "user-message-appended";
+    userMessage: UserMessage;
+}
+/**
+ * A conversation summary produced during a run, delivered through `SendOptions.onDelta`.
+ *
+ * Nothing in this package emits it. It is declared so an exhaustive `switch` over
+ * {@link InteractionUpdate} compiles, and so a runtime that does produce summaries has a typed
+ * channel — do not build a feature that waits on it against the local runtime.
+ *
+ * @public
+ */
+export interface SummaryUpdate {
+    type: "summary";
+    summary: string;
+}
+/**
+ * Opens the bracket around a {@link SummaryUpdate}, for a UI that wants to show a pending state
+ * before the summary text exists. Paired with {@link SummaryCompletedUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
+export interface SummaryStartedUpdate {
+    type: "summary-started";
+}
+/**
+ * Closes the bracket opened by {@link SummaryStartedUpdate}. Carries no payload — the summary text
+ * itself arrives as {@link SummaryUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
+export interface SummaryCompletedUpdate {
+    type: "summary-completed";
+}
+/**
+ * Incremental output from a shell command running inside a run.
+ *
+ * `event` is an untyped bag on purpose: this package neither produces nor narrows it, so a consumer
+ * that receives one should treat it as unvalidated input and check for the fields it needs rather
+ * than casting. As with the summary variants, nothing here emits this — it exists so the
+ * {@link InteractionUpdate} union covers a runtime that does.
+ *
+ * @public
+ */
+export 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.
+ *
+ * @public
+ */
+export type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;

package/dist/types/usage.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Owner: `internal/budget/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * 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`.
+ *
+ * @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 a peer SDK)
+ * — populated only when the run made > 1 LLM call.
+ */
+export 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.
+ */
+export type CostStatus = "actual" | "estimated" | "included" | "unknown";
+/** Source of the cost figure for caller-side audit. */
+export 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 (a lie). The UI shows
+ * `n/a` for unknown, `~$1.23` for estimated, `$1.23` for actual.
+ */
+export 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;
+    };
+}