@theokit/sdk 2.19.0 → 2.21.0

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

@@ -0,0 +1,84 @@
+/**
+ * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
+ *
+ * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
+ * out-of-band runtime-OBSERVABILITY signals — the model's content is unaffected —
+ * delivered opt-in via `SendOptions.onRunEvent`. Discriminate on `type`. Mirrors
+ * the Anthropic `SDKMessage`-union approach (rate-limit, permission-denied, task
+ * lifecycle, compaction boundary).
+ *
+ * The union is the forward-compatible CONTRACT (discriminate exhaustively). As of
+ * SE2 the runtime EMITS `tool_progress` and `permission_denied` end-to-end (from
+ * the agent-loop tool-dispatch seam). `rate_limit`, `task_*`, and `compact_boundary`
+ * are part of the contract; their emission is wired incrementally as the sink is
+ * threaded into the LLM-client retry / task / session-compaction subsystems (they
+ * live below the loop). A consumer switching on `type` is future-proof either way.
+ *
+ * @public
+ */
+export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent;
+/** A tool call is being dispatched (before its result). */
+export interface RunToolProgressEvent {
+    readonly type: "tool_progress";
+    readonly toolName: string;
+    readonly toolCallId: string;
+}
+/** The provider returned a rate-limit (HTTP 429); the loop will back off + retry. */
+export interface RunRateLimitEvent {
+    readonly type: "rate_limit";
+    /** Retry attempt number (1-based) about to be delayed. */
+    readonly attempt: number;
+    /** Delay in ms before the retry, when the provider/policy supplied one. */
+    readonly retryAfterMs?: number;
+}
+/**
+ * A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),
+ * an operator file-hook `preToolUse`, or the fork tool-whitelist. `source`
+ * discriminates which. `toolCallId` joins the event to the tool-call log.
+ */
+export interface RunPermissionDeniedEvent {
+    readonly type: "permission_denied";
+    readonly toolName: string;
+    readonly toolCallId: string;
+    /** Which layer blocked the call. */
+    readonly source: "plugin" | "file_hook" | "fork_whitelist";
+    /** The rejection message surfaced to the model. */
+    readonly message: string;
+}
+/** A background task/subagent started. */
+export interface RunTaskStartedEvent {
+    readonly type: "task_started";
+    readonly taskId: string;
+    readonly description?: string;
+}
+/** A background task/subagent changed state. */
+export interface RunTaskUpdatedEvent {
+    readonly type: "task_updated";
+    readonly taskId: string;
+    readonly status: string;
+}
+/** A background task/subagent finished. */
+export interface RunTaskCompletedEvent {
+    readonly type: "task_completed";
+    readonly taskId: string;
+    readonly status: "completed" | "failed" | "stopped";
+}
+/** The conversation crossed a compaction boundary (history was summarized). */
+export interface RunCompactBoundaryEvent {
+    readonly type: "compact_boundary";
+    readonly trigger: "manual" | "auto";
+    /** Token count before compaction, when known. */
+    readonly preTokens?: number;
+}
+/**
+ * SE2 — the opt-in sink for {@link RunEvent}s. Supplied via `SendOptions.onRunEvent`.
+ * Synchronous + best-effort: a throwing sink must never break the run (the emitter
+ * try-catches it), so keep it fast (push to a queue, don't await).
+ */
+export type RunEventSink = (event: RunEvent) => void;
+/**
+ * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
+ * observability can never break the run (fail-safe, mirrors the EventBus EC-2
+ * contract). No-op when the sink is absent.
+ */
+export declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;

package/dist/types/run.d.ts

@@ -32,6 +32,49 @@ export interface RunGitInfo {
         prUrl?: string;
     }>;
 }
+/**
+ * SE3 — provenance of the turn that produced a run: WHO triggered it. Stamped in
+ * the multi-agent path (Squad / a2a / handoff / background-delegation) and
+ * forwarded onto {@link RunResult.origin} — so consumers can attribute/route
+ * turns by their trigger. Metadata-only; discriminate on `kind`. Mirrors the
+ * Anthropic Agent SDK's `origin` shape.
+ *
+ * Encoding note (distinct from absence): an ABSENT origin (`undefined`) means the
+ * provenance was NOT stamped — the default for a plain `agent.send()`. The explicit
+ * `{ kind: "human" }` is a positive marker a HOST stamps to say "this turn is
+ * definitely from a human" (e.g. to distinguish a real user message from an
+ * un-attributed one in an audit UI). The two are not interchangeable: `undefined`
+ * = unknown/unstamped; `{ kind: "human" }` = explicitly human. Consumers writing an
+ * exhaustive `switch (origin?.kind)` therefore handle `undefined` (unstamped) and
+ * `"human"` (explicit) as separate, meaningful cases.
+ *
+ * @public
+ */
+export type MessageOrigin = 
+/** Explicitly a human-triggered turn — a positive marker a host stamps (NOT the
+ *  same as an absent/unstamped origin, which is `undefined`). */
+{
+    readonly kind: "human";
+}
+/** Another agent (a Squad peer or an a2a sender) triggered this turn. */
+ | {
+    readonly kind: "peer";
+    readonly from: string;
+}
+/** A background task's completion re-entered the agent as a follow-up turn. */
+ | {
+    readonly kind: "task-notification";
+}
+/** A delegating/handoff coordinator triggered this turn. `from` is the coordinator's
+ *  id when known, omitted for an anonymous coordinator. */
+ | {
+    readonly kind: "coordinator";
+    readonly from?: string;
+}
+/** The loop's continuation driver re-sent to continue truncated work. */
+ | {
+    readonly kind: "auto-continuation";
+};
 /**
  * Terminal result of a {@link Run}.
  *
@@ -44,6 +87,15 @@ export interface RunResult {
     model?: ModelSelection;
     durationMs?: number;
     git?: RunGitInfo;
+    /**
+     * SE3 — provenance forwarded from {@link SendOptions.origin}: who triggered
+     * this turn (human / peer / task-notification / coordinator / auto-continuation).
+     * `undefined` means the provenance was not stamped (a plain `agent.send()`).
+     * Metadata-only — never affects routing.
+     *
+     * @public
+     */
+    origin?: MessageOrigin;
     /**
      * Structured error detail, populated when `status === "error"`. Surfaces
      * the diagnostic that emit-error-event pushes into the stream so callers
@@ -218,7 +270,27 @@ export interface SDKUserMessage {
  * @public
  */
 export interface SendOptions {
-    model?: ModelSelection;
+    /**
+     * Per-send model override. SE8 — accepts a bare-string id shorthand
+     * (`"openai/gpt-4o-mini"`, normalized to `{ id }`) OR a {@link ModelSelection}
+     * object (use the object form to pass `params`).
+     */
+    model?: string | ModelSelection;
+    /**
+     * SE3 — provenance of this turn (who triggered it). Stamped by the multi-agent
+     * path (Squad peer, a2a sender, coordinator/handoff, background task-notification)
+     * and forwarded onto {@link RunResult.origin}. Metadata-only — the value never
+     * changes routing or dispatch. Omit to leave the turn un-attributed; a host may
+     * pass `{ kind: "human" }` to positively mark a human turn.
+     */
+    origin?: MessageOrigin;
+    /**
+     * SE2 — opt-in typed runtime-EVENT sink. Receives out-of-band `RunEvent`s
+     * (permission_denied, tool_progress, rate_limit, task_*, compact_boundary) for
+     * observability, ADDITIVE to the `SDKMessage` content stream. Best-effort: a
+     * throwing sink never breaks the run. Discriminate on `event.type`.
+     */
+    onRunEvent?: import("./run-events.js").RunEventSink;
     /**
      * Doom-loop guard config. The loop stops (with `terminal: "no_progress"`, `RunResult.stoppedByDoomLoop`)
      * when the model repeats IDENTICAL tool calls to the hard threshold. On by default with generous
@@ -356,3 +428,45 @@ export interface Run {
     /** Subscribe to status changes. Returns an unsubscribe function. */
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
+/**
+ * SE9 — options for the integrated structured-output method `agent.generate`: the
+ * {@link SendOptions} that drive the tool loop (phase 1) plus the required `output`
+ * Zod schema and structuring knobs (phase 2). Co-located with `SendOptions` /
+ * `RunResult` (which they extend/use) so the public `SDKAgent` interface does not
+ * import the runtime `agent-generate` module (breaks the type cycle).
+ *
+ * @public
+ */
+export interface GenerateOptions<T extends import("zod").ZodType> extends SendOptions {
+    /** Zod schema the final answer is coerced into (the structuring contract). */
+    output: T;
+    /** Retry budget on the structuring phase's parse-failures (reused from generateObject). Default 1. */
+    maxRetries?: number;
+    /**
+     * What the STRUCTURING phase (phase 2) does when the model's output still fails
+     * Zod validation after retries. Default `"throw"`. `"return-partial"` / `"return-raw"`
+     * salvage the object; the salvaged/raw value is in {@link GenerateRunResult.raw}
+     * (the pre-parse structuring input) — NOT the phase-1 text answer, which is in
+     * `result.result`.
+     */
+    errorStrategy?: "throw" | "return-partial" | "return-raw";
+}
+/**
+ * SE9 — result of `agent.generate`: the validated typed object plus the underlying
+ * tool-loop {@link RunResult} (status / usage / model) and the raw pre-parse input.
+ *
+ * @public
+ */
+export interface GenerateRunResult<O> {
+    /** The validated object — inferred type from the `output` schema. */
+    object: O;
+    /** The underlying tool-loop run (phase 1). */
+    result: RunResult;
+    /** Raw model input to the synthetic `output` tool, before the Zod parse. */
+    raw: unknown;
+    /** Combined token usage of the structuring phase. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}

package/dist/types/session.d.ts

@@ -0,0 +1,99 @@
+/**
+ * SE4 — public types for the session-management surface (`createSessionManager`).
+ *
+ * A "session" is one conversation in a {@link ConversationStorageAdapter}. These
+ * DTOs are deliberately LIGHT — derived display metadata, not raw store rows — so
+ * a host (TheoKit) can build a session list/UI without reaching into storage
+ * internals.
+ *
+ * @public
+ */
+import type { StoredMessage } from "./conversation-storage.js";
+/**
+ * Light, display-oriented metadata for one session, derived from its transcript
+ * plus any host-set title/tag. All fields except `id`/`messageCount` are optional
+ * because a fresh or empty session may lack them.
+ *
+ * @public
+ */
+export interface SessionSummary {
+    /** The conversation id (verbatim — includes any scope prefix like `user__`). */
+    readonly id: string;
+    /** Number of stored messages in the transcript. */
+    readonly messageCount: number;
+    /** Content of the first `user` message, when present — the opening prompt. */
+    readonly firstPrompt?: string;
+    /** Largest message timestamp (`StoredMessage.at`) seen, when any is stamped. */
+    readonly lastModified?: number;
+    /** Host-set title (via `renameSession`), when set. */
+    readonly title?: string;
+    /** Host-set tag (via `tagSession`), when set. */
+    readonly tag?: string;
+    /**
+     * A short display preview: the `title` when set, otherwise the `firstPrompt`
+     * (truncated). Undefined only when the session has neither a title nor a first
+     * user prompt.
+     */
+    readonly summary?: string;
+}
+/**
+ * Windowing for {@link SessionManager.listSessions}. `offset` counts from the
+ * first listed session; `limit` bounds the returned count. Omitting both lists
+ * all sessions (bounded only by the adapter's own `listConversationIds` limit).
+ *
+ * @public
+ */
+export interface SessionListOptions {
+    readonly offset?: number;
+    readonly limit?: number;
+}
+/**
+ * Typed capability result — the graceful-degradation signal for operations an
+ * adapter cannot perform (listing, or writing session metadata). Prefer this over
+ * throwing on every call: a host inspects `supported` once and hides the
+ * corresponding UI affordance. Mirrors the SDK's existing degradation precedent
+ * (`ConversationStorageAdapter.listConversationIds` returning `undefined`,
+ * `Run.unsupportedReason`).
+ *
+ * @public
+ */
+export type SessionCapabilityResult<T> = {
+    readonly supported: true;
+    readonly value: T;
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+/**
+ * The session-management surface returned by `createSessionManager`. Bound to a
+ * single {@link ConversationStorageAdapter} instance (the same one a host passed
+ * to `Agent.create({ conversationStorage })`).
+ *
+ * @public
+ */
+export interface SessionManager {
+    /**
+     * List sessions with light derived metadata. Returns an unsupported result
+     * when the adapter cannot enumerate conversations (`listConversationIds`
+     * absent or returning `undefined`).
+     */
+    listSessions(opts?: SessionListOptions): Promise<SessionCapabilityResult<readonly SessionSummary[]>>;
+    /**
+     * Read a session's stored transcript (passthrough to the adapter's mandatory
+     * `getMessages`). Always supported. `{ offset, limit }` windows the result.
+     */
+    getSessionMessages(id: string, opts?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<readonly StoredMessage[]>;
+    /**
+     * Set a session's title. Unsupported when the adapter cannot write session
+     * metadata (`setSessionMeta` absent).
+     */
+    renameSession(id: string, title: string): Promise<SessionCapabilityResult<void>>;
+    /**
+     * Set (`tag`) or clear (`null`) a session's tag. Unsupported when the adapter
+     * cannot write session metadata (`setSessionMeta` absent).
+     */
+    tagSession(id: string, tag: string | null): Promise<SessionCapabilityResult<void>>;
+}

package/dist/types/workflow.d.ts

@@ -10,6 +10,7 @@
  */
 import type { ZodType } from "zod";
 import type { SDKAgent } from "./agent.js";
+import type { MessageOrigin } from "./run.js";
 export type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
 /** A pure function step. */
 export interface FnStep {
@@ -29,6 +30,12 @@ export interface AgentStep {
     readonly agent: SDKAgent;
     readonly promptTemplate: string | ((input: unknown) => string);
     readonly retry?: RetryPolicy;
+    /**
+     * SE3 — provenance stamped onto this step's `agent.send()` (forwarded to
+     * `RunResult.origin`). Squad sets `{ kind: "peer", from: "agent-<i-1>" }` on
+     * every step after the first so a peer-driven turn is attributable.
+     */
+    readonly origin?: MessageOrigin;
 }
 /** N concurrent branches, each its own mini-step-list. */
 export interface ParallelStep {

package/dist/workflow.cjs

@@ -681,7 +681,10 @@ async function runAgentStep(step, input, ctx) {
     };
   }
   const exec = async () => {
-    const run = await step.agent.send(prompt);
+    const run = await step.agent.send(
+      prompt,
+      step.origin !== void 0 ? { origin: step.origin } : void 0
+    );
     const result = await run.wait();
     if (result.status === "finished") {
       return result.result ?? "";
@@ -2462,7 +2465,9 @@ function agentStep(id, agent, promptTemplate, opts) {
     id,
     agent,
     promptTemplate,
-    ...opts?.retry !== void 0 ? { retry: opts.retry } : {}
+    ...opts?.retry !== void 0 ? { retry: opts.retry } : {},
+    // SE3 — carry the turn's provenance down to `agent.send()` (metadata-only).
+    ...opts?.origin !== void 0 ? { origin: opts.origin } : {}
   };
 }
 function validateStepId(id) {