@theokit/sdk 1.5.0

package/dist/types/updates.d.ts

@@ -0,0 +1,148 @@
+import type { UserMessage } from "./conversation.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;
+}
+/** @public */
+export interface SummaryUpdate {
+    type: "summary";
+    summary: string;
+}
+/** @public */
+export interface SummaryStartedUpdate {
+    type: "summary-started";
+}
+/** @public */
+export interface SummaryCompletedUpdate {
+    type: "summary-completed";
+}
+/** @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,61 @@
+/**
+ * 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 openai-agents-python)
+ * — 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 (mentira). UI exibe
+ * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para 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;
+    };
+}

package/dist/types/workflow.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Public type contract for `Workflow.create / .run / .resume` (Adoption
+ * Roadmap #5; ADRs D230-D248).
+ *
+ * Step types form a discriminated union by `kind`. Helper factory functions
+ * (`fn()`, `agentStep()`) live in `workflow.ts` and hide the discriminator
+ * from end users.
+ *
+ * @public
+ */
+import type { ZodType } from "zod";
+import type { SDKAgent } from "./agent.js";
+export type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
+/** A pure function step. */
+export interface FnStep {
+    readonly kind: "fn";
+    readonly id: string;
+    readonly fn: (input: unknown, ctx: StepContext) => Promise<unknown> | unknown;
+    readonly inputSchema?: ZodType;
+    readonly outputSchema?: ZodType;
+    readonly retry?: RetryPolicy;
+    /** D238 — slot reserved; runtime throws if engine not yet implemented. */
+    readonly compensate?: (input: unknown, output: unknown, error: Error) => Promise<void> | void;
+}
+/** An agent.send-driven step. */
+export interface AgentStep {
+    readonly kind: "agent";
+    readonly id: string;
+    readonly agent: SDKAgent;
+    readonly promptTemplate: string | ((input: unknown) => string);
+    readonly retry?: RetryPolicy;
+}
+/** N concurrent branches, each its own mini-step-list. */
+export interface ParallelStep {
+    readonly kind: "parallel";
+    readonly id: string;
+    readonly branches: ReadonlyArray<ReadonlyArray<Step>>;
+    readonly concurrency?: number;
+    readonly errorPolicy?: "fail-fast" | "collect";
+}
+/** First-match-wins predicates + optional fallback. */
+export interface BranchStep {
+    readonly kind: "branch";
+    readonly id: string;
+    readonly predicates: ReadonlyArray<readonly [(input: unknown) => boolean | Promise<boolean>, ReadonlyArray<Step>]>;
+    readonly fallback?: ReadonlyArray<Step>;
+}
+/** Map a step over an upstream array output. */
+export interface ForeachStep {
+    readonly kind: "foreach";
+    readonly id: string;
+    /** ID of an upstream top-level step whose output is iterable. */
+    readonly iterableFrom: string;
+    readonly step: Step;
+    readonly concurrency?: number;
+}
+/** Loop a step until condFn returns false. */
+export interface DowhileStep {
+    readonly kind: "dowhile";
+    readonly id: string;
+    readonly step: Step;
+    readonly condFn: (output: unknown, iteration: number) => boolean | Promise<boolean>;
+    readonly maxIterations?: number;
+}
+/** Pause for a fixed duration. */
+export interface SleepStep {
+    readonly kind: "sleep";
+    readonly id: string;
+    readonly durationMs: number;
+}
+/** Standalone explicit suspend point. */
+export interface SuspendStep {
+    readonly kind: "suspend";
+    readonly id: string;
+    readonly payloadSchema?: ZodType;
+}
+/** D237 — retry policy applied per fn/agent step. */
+export interface RetryPolicy {
+    /** Total attempts (MIN 1, MAX 20). `1` = no retry. */
+    readonly maxAttempts: number;
+    readonly initialBackoffMs?: number;
+    readonly backoffCoefficient?: number;
+    readonly maximumBackoffMs?: number;
+    readonly nonRetryableErrors?: ReadonlyArray<string>;
+}
+/** D247 — context handed to every step.fn. */
+export interface StepContext {
+    readonly runId: string;
+    readonly signal: AbortSignal;
+    readonly log: {
+        debug: (msg: string, attrs?: Record<string, unknown>) => void;
+        info: (msg: string, attrs?: Record<string, unknown>) => void;
+        warn: (msg: string, attrs?: Record<string, unknown>) => void;
+    };
+    /** Pause the workflow; resume via `Workflow.resume({...})`. */
+    readonly suspend: (payload?: unknown) => Promise<never>;
+}
+export interface StepResult {
+    readonly stepId: string;
+    readonly kind: Step["kind"];
+    readonly status: "completed" | "failed" | "skipped" | "suspended";
+    readonly attempts: number;
+    readonly durationMs: number;
+    readonly output?: unknown;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+}
+export interface WorkflowRun<TOutput = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
+    readonly output?: TOutput;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly stepResults: ReadonlyArray<StepResult>;
+}
+export interface WorkflowSnapshot {
+    readonly _schemaVersion: 1;
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly currentStepId: string;
+    readonly suspendedPayload?: unknown;
+    readonly stepResults: ReadonlyArray<StepResult>;
+    readonly accumulatedInput: unknown;
+    readonly suspendedAt: number;
+}
+export interface WorkflowPersistenceOptions {
+    readonly backend: "memory" | "json";
+    /** Required for `backend: "json"`. */
+    readonly dir?: string;
+}
+export interface WorkflowOptions {
+    readonly name: string;
+    readonly persistence?: WorkflowPersistenceOptions;
+    /** Internal — minted at `.commit()`. Not user-facing. */
+    readonly workflowId?: string;
+}
+export interface WorkflowRunOptions {
+    readonly signal?: AbortSignal;
+    /** Override run ID for deterministic resume (advanced; default = mintRunId). */
+    readonly runId?: string;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). Registers the workflow run
+     * as a `Task` (kind="workflow") with a `wf-` namespaced id (D368,
+     * EC-5). The task transitions terminal when `Workflow.run` resolves.
+     *
+     * Auto-id: `wf-{runId}`.
+     *
+     * @public
+     */
+    readonly task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+export interface WorkflowResumeOptions<TI = unknown> {
+    readonly runId: string;
+    readonly workflow: {
+        run: (input: TI, opts?: WorkflowRunOptions) => Promise<WorkflowRun>;
+    };
+    readonly payload?: unknown;
+    readonly signal?: AbortSignal;
+}
+export declare class WorkflowDuplicateStepIdError extends Error {
+    readonly stepId: string;
+    readonly name = "WorkflowDuplicateStepIdError";
+    constructor(stepId: string);
+}
+export declare class WorkflowAlreadyRunningError extends Error {
+    readonly workflowName: string;
+    readonly runId: string;
+    readonly name = "WorkflowAlreadyRunningError";
+    constructor(workflowName: string, runId: string);
+}
+export declare class WorkflowSnapshotNotFoundError extends Error {
+    readonly runId: string;
+    readonly name = "WorkflowSnapshotNotFoundError";
+    constructor(runId: string);
+}
+export declare class WorkflowMaxIterationsExceededError extends Error {
+    readonly stepId: string;
+    readonly maxIterations: number;
+    readonly name = "WorkflowMaxIterationsExceededError";
+    constructor(stepId: string, maxIterations: number);
+}
+/** EC-4 absorbed — JSON.stringify failed on snapshot payload. */
+export declare class WorkflowNotSerializableError extends Error {
+    readonly stepId: string;
+    readonly underlying: Error;
+    readonly name = "WorkflowNotSerializableError";
+    constructor(stepId: string, underlying: Error);
+}
+/** EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow. */
+export declare class WorkflowResumeStepNotFoundError extends Error {
+    readonly stepId: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeStepNotFoundError";
+    constructor(stepId: string, workflowName: string);
+}
+/** Aggregate failure from parallel branches. */
+export declare class WorkflowParallelError extends AggregateError {
+    readonly stepId: string;
+    readonly name = "WorkflowParallelError";
+    constructor(errors: ReadonlyArray<Error>, stepId: string);
+}
+/** D238 — saga engine not yet implemented. */
+export declare class WorkflowCompensateNotImplementedError extends Error {
+    readonly stepId: string;
+    readonly name = "WorkflowCompensateNotImplementedError";
+    constructor(stepId: string);
+}