@theokit/sdk 4.38.0 → 4.39.0

package/dist/stream-object-4FDU76YW.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkHIQFVHC6_cjs = require('./chunk-HIQFVHC6.cjs');
+require('./chunk-FWBSDQZ7.cjs');
+require('./chunk-WJVHMTKB.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "StreamObjectError", {
+  enumerable: true,
+  get: function () { return chunkHIQFVHC6_cjs.StreamObjectError; }
+});
+Object.defineProperty(exports, "streamObjectImpl", {
+  enumerable: true,
+  get: function () { return chunkHIQFVHC6_cjs.streamObjectImpl; }
+});
+//# sourceMappingURL=stream-object-4FDU76YW.cjs.map
+//# sourceMappingURL=stream-object-4FDU76YW.cjs.map

package/dist/{stream-object-YPXZ4F5P.cjs.map → stream-object-4FDU76YW.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-YPXZ4F5P.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-4FDU76YW.cjs"}

package/dist/stream-object-HWDEEQN4.js

@@ -0,0 +1,7 @@
+export { StreamObjectError, streamObjectImpl } from './chunk-DU7DE543.js';
+import './chunk-JZUPMTJY.js';
+import './chunk-4VPXM6UU.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
+//# sourceMappingURL=stream-object-HWDEEQN4.js.map
+//# sourceMappingURL=stream-object-HWDEEQN4.js.map

package/dist/{stream-object-AFERZU63.js.map → stream-object-HWDEEQN4.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-AFERZU63.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-HWDEEQN4.js"}

package/dist/subagents-loader-A4W6C3QP.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+var chunkW4WKVOOQ_cjs = require('./chunk-W4WKVOOQ.cjs');
+require('./chunk-G2Q3ZC6C.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunkW4WKVOOQ_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-A4W6C3QP.cjs.map
+//# sourceMappingURL=subagents-loader-A4W6C3QP.cjs.map

package/dist/subagents-loader-A4W6C3QP.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-A4W6C3QP.cjs"}

package/dist/subagents-loader-X33KH2SZ.js

@@ -0,0 +1,6 @@
+export { loadSubagents } from './chunk-YRXY2A5L.js';
+import './chunk-AR5MQZ3J.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
+//# sourceMappingURL=subagents-loader-X33KH2SZ.js.map
+//# sourceMappingURL=subagents-loader-X33KH2SZ.js.map

package/dist/subagents-loader-X33KH2SZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-X33KH2SZ.js"}

package/dist/subagents-loader.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkMXRBNJ6D_cjs = require('./chunk-MXRBNJ6D.cjs');
-require('./chunk-XKBJT7WI.cjs');
-var chunkA3MHE2MQ_cjs = require('./chunk-A3MHE2MQ.cjs');
-require('./chunk-BE3W4HYV.cjs');
+var chunkW4WKVOOQ_cjs = require('./chunk-W4WKVOOQ.cjs');
+require('./chunk-G2Q3ZC6C.cjs');
+var chunkIHFNRNTJ_cjs = require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 // src/subagents-loader.ts
 var FONTES_ACEITAS = ["project"];
@@ -12,7 +12,7 @@ function resolverFontes(options) {
   if (declaradas === void 0) return FONTES_ACEITAS;
   for (const fonte of declaradas) {
     if (!FONTES_ACEITAS.includes(fonte)) {
-      throw new chunkA3MHE2MQ_cjs.ConfigurationError(
+      throw new chunkIHFNRNTJ_cjs.ConfigurationError(
         `Unknown subagent setting source "${String(fonte)}" (accepted: ${FONTES_ACEITAS.join(", ")})`,
         { code: "subagent_unknown_setting_source" }
       );
@@ -22,7 +22,7 @@ function resolverFontes(options) {
 }
 async function discoverSubagents(cwd, options) {
   const fontes = resolverFontes(options);
-  return chunkMXRBNJ6D_cjs.loadSubagents(cwd, fontes.includes("project"), void 0);
+  return chunkW4WKVOOQ_cjs.loadSubagents(cwd, fontes.includes("project"), void 0);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.d.cts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-U3lBX-5t.cjs';
-import './run-vJHg2eGw.cjs';
+import { a as AgentDefinition } from './agent-D7bRK9Kg.cjs';
+import './run-i2-fUohR.cjs';
 import 'zod';
 
 /**

package/dist/subagents-loader.d.ts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-C3AEtM-W.js';
-import './run-vJHg2eGw.js';
+import { a as AgentDefinition } from './agent-ZCZa7YQv.js';
+import './run-i2-fUohR.js';
 import 'zod';
 
 /**

package/dist/subagents-loader.js

@@ -1,7 +1,7 @@
-import { loadSubagents } from './chunk-HHUDNTZC.js';
-import './chunk-QFWQLXCL.js';
-import { ConfigurationError } from './chunk-ZYOHF37V.js';
-import './chunk-KCZW75PI.js';
+import { loadSubagents } from './chunk-YRXY2A5L.js';
+import './chunk-AR5MQZ3J.js';
+import { ConfigurationError } from './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 
 // src/subagents-loader.ts
 var FONTES_ACEITAS = ["project"];

package/dist/subscription/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkA3MHE2MQ_cjs = require('../chunk-A3MHE2MQ.cjs');
-require('../chunk-BE3W4HYV.cjs');
+var chunkIHFNRNTJ_cjs = require('../chunk-IHFNRNTJ.cjs');
+require('../chunk-BCQ3E2ZG.cjs');
 
 // src/subscription/define-subscription.ts
 function defineSubscription(opts) {
@@ -138,7 +138,7 @@ function tracked(id, payload) {
   }
   return [id, payload];
 }
-var SubscriptionError = class extends chunkA3MHE2MQ_cjs.TheokitAgentError {
+var SubscriptionError = class extends chunkIHFNRNTJ_cjs.TheokitAgentError {
   name = "SubscriptionError";
   constructor(message, options = {}) {
     super(message, { ...options, isRetryable: false });

package/dist/subscription/index.js

@@ -1,5 +1,5 @@
-import { TheokitAgentError } from '../chunk-ZYOHF37V.js';
-import '../chunk-KCZW75PI.js';
+import { TheokitAgentError } from '../chunk-SG5ZWT6C.js';
+import '../chunk-IVSD7L22.js';
 
 // src/subscription/define-subscription.ts
 function defineSubscription(opts) {

package/dist/task-store.cjs

@@ -1,23 +1,23 @@
 'use strict';
 
-var chunkVVMLMKYZ_cjs = require('./chunk-VVMLMKYZ.cjs');
-require('./chunk-YVI4YPUP.cjs');
-require('./chunk-A3MHE2MQ.cjs');
-require('./chunk-BE3W4HYV.cjs');
+var chunkDWY25VLP_cjs = require('./chunk-DWY25VLP.cjs');
+require('./chunk-DGLLVCNB.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 
 
 Object.defineProperty(exports, "InMemoryTaskStore", {
   enumerable: true,
-  get: function () { return chunkVVMLMKYZ_cjs.InMemoryTaskStore; }
+  get: function () { return chunkDWY25VLP_cjs.InMemoryTaskStore; }
 });
 Object.defineProperty(exports, "JsonFileTaskStore", {
   enumerable: true,
-  get: function () { return chunkVVMLMKYZ_cjs.JsonFileTaskStore; }
+  get: function () { return chunkDWY25VLP_cjs.JsonFileTaskStore; }
 });
 Object.defineProperty(exports, "getTaskStoreFor", {
   enumerable: true,
-  get: function () { return chunkVVMLMKYZ_cjs.getTaskStoreFor; }
+  get: function () { return chunkDWY25VLP_cjs.getTaskStoreFor; }
 });
 //# sourceMappingURL=task-store.cjs.map
 //# sourceMappingURL=task-store.cjs.map

package/dist/task-store.js

@@ -1,6 +1,6 @@
-export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor } from './chunk-SGTMDQ4O.js';
-import './chunk-LGCEYEU2.js';
-import './chunk-ZYOHF37V.js';
-import './chunk-KCZW75PI.js';
+export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor } from './chunk-6EEYRFJC.js';
+import './chunk-KX7JV5KM.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 //# sourceMappingURL=task-store.js.map
 //# sourceMappingURL=task-store.js.map

package/dist/types/agent.d.ts

@@ -337,9 +337,11 @@ export interface AgentOptions {
      *
      * `'run'` (DEFAULT, and the historical behaviour) spawns a client per `send` and drops it when the
      * run ends. `'session'` pools clients per `(agentId, server, config)` and keeps them across turns,
-     * which is what the reference does — Codex holds its connection manager in `SessionServices`
-     * (`core/src/state/service.rs:116`). Measured cost of the per-run path: 193 / 138 / 134 ms of
-     * spawn + handshake on every turn.
+     * which is what the reference does — Codex holds its MCP runtime in `SessionServices`
+     * (`codex-rs/core/src/state/service.rs:51-58`; theokit#155 corrected the earlier
+     * `core/src/state/service.rs:116`, which named a parameter of `install_mcp_runtime`, not the
+     * owning field). Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
+     * every turn.
      *
      * Opt-in rather than default because it changes the FAILURE model: a server that dies mid-session
      * becomes a reachable state. One-shot and cron runs gain nothing from pooling and would pay that
@@ -607,6 +609,69 @@ export type SDKAgentInfo = {
     env?: CloudEnv;
     repos?: string[];
 });
+/**
+ * theokit#123 — one tool of a registered agent, as a reflection surface sees it.
+ *
+ * A projection, not the `CustomTool` itself: the handler is an executable that cannot cross a
+ * process boundary and has no meaning to a caller enumerating a registry.
+ *
+ * @public
+ */
+export interface AgentToolDescription {
+    name: string;
+    description: string;
+    /** The JSON Schema sent to the model verbatim — the tool's callable signature. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * theokit#123 — one subagent of a registered agent (what theokit-studio calls a workflow).
+ *
+ * `prompt` is deliberately absent. Enumeration asks what a subagent IS and what it may call; its
+ * system prompt is instructions, not signature, and a reflection endpoint that serializes it
+ * publishes the agent's behaviour to anyone who can reach the endpoint.
+ *
+ * @public
+ */
+export interface AgentSubagentDescription {
+    /** The key under `AgentOptions.agents` — how the parent addresses it. */
+    name: string;
+    description: string;
+    /** `"inherit"` (or absent) means it runs on the parent's model. */
+    model?: ModelSelection | "inherit";
+    /** Tool whitelist, when the subagent is scoped to a subset of the parent's tools. */
+    tools?: string[];
+}
+/**
+ * theokit#123 — the read-only introspection of a registered agent, returned by `Agent.describe()`.
+ *
+ * `Agent.list()` / `Agent.get()` enumerate agents and `agent.skills.list()` covers skills; this
+ * fills the remaining gap, so a reflection endpoint can report the live registry instead of
+ * degrading to empty lists.
+ *
+ * `tools` and `subagents` are always arrays — never `undefined` — so a caller can distinguish
+ * "this agent has none" from "the SDK did not say".
+ *
+ * @public
+ */
+export interface AgentDescription {
+    agentId: string;
+    /** Inlined rather than imported from the registry contract: `types/` stays a leaf (theokit#146). */
+    runtime: "local" | "cloud";
+    model?: ModelSelection;
+    /**
+     * The agent's DECLARED tool catalog.
+     *
+     * Plugin-contributed tools and the internal `think` tool (added when `reasoning` is on) are
+     * assembled per run and are not knowable from the registry, so they are absent here. Stated
+     * rather than implied: a reflection endpoint should not present this as the complete runtime set.
+     */
+    tools: readonly AgentToolDescription[];
+    /**
+     * Every subagent the runtime would resolve — file-based roles from `.theokit/agents/*.md` merged
+     * with the inline `agentOptions.agents`, the same set `loadSubagents` builds for a run.
+     */
+    subagents: readonly AgentSubagentDescription[];
+}
 /**
  * Options for `Agent.list()`.
  *

package/dist/types/conversation.d.ts

@@ -17,6 +17,13 @@ export interface AssistantMessage {
 export interface ThinkingMessage {
     text: string;
     thinkingDurationMs?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Persisted with the block so a resumed conversation can replay it byte-identically;
+     * Anthropic rejects a modified or unsigned thinking block with
+     * `400 "thinking blocks cannot be modified"`.
+     */
+    signature?: string;
 }
 /**
  * Shell command executed during a run.

package/dist/types/messages.d.ts

@@ -65,6 +65,15 @@ export interface SDKThinkingMessage {
     run_id: string;
     text: string;
     thinking_duration_ms?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Anthropic requires a resumed conversation to replay each thinking block WITH its
+     * signature; without it the next request fails with `400 "thinking blocks cannot be modified"`,
+     * which made an extended-thinking session unresumable.
+     *
+     * Absent for providers that stream reasoning text unsigned (the OpenAI-compatible wire).
+     */
+    signature?: string;
 }
 /**
  * Tool invocation lifecycle event. Emitted at start with `args`, then again on

package/dist/types/session-message.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The shape of a persisted session turn, as a HOST reads it.
+ *
+ * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).
+ * `internal/session/session-types.ts` re-exports it so the runtime and the store keep importing
+ * from the leaf they always did.
+ *
+ * @public
+ */
+import type { ToolResultContentBlock } from "./content-blocks.js";
+/**
+ * One turn of a session.
+ *
+ * Two projections of the same turn, and they answer different questions:
+ *
+ * - `text` is the flat rendering the model replay uses. A tool call folds to `[tool call] NAME` and
+ *   a result to `[tool result] <body>`.
+ * - `parts` is the same turn unflattened, for a host that draws tool CARDS: the call id, the tool
+ *   name, the arguments, and the `toolUseId` that ties a result back to its call — none of which
+ *   survive the flat form.
+ *
+ * `parts` was added in theokit#146 and is additive: `text` is byte-identical to what it always was,
+ * so every existing reader is untouched.
+ *
+ * @public
+ */
+export interface SessionMessage {
+    role: "user" | "assistant";
+    text: string;
+    /**
+     * The structured view. Optional because a `SessionMessage` can also be built in memory during a
+     * live turn, where only the text projection exists. Absent means "this projection carries no
+     * structure", never "this turn had none".
+     */
+    parts?: readonly SessionMessagePart[];
+}
+/**
+ * One structured element of a {@link SessionMessage}.
+ *
+ * Deliberately a session-DISPLAY shape rather than a re-export of the internal LLM part union: the
+ * two answer different questions (what to send a provider vs. what to draw), and coupling them
+ * would make every provider-wire change a change to what hosts render.
+ *
+ * @public
+ */
+export type SessionMessagePart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+} | {
+    readonly type: "tool_result";
+    readonly toolUseId: string;
+    readonly content: string | ReadonlyArray<ToolResultContentBlock>;
+    readonly isError?: boolean;
+};

package/dist/types/workflow.d.ts

@@ -81,6 +81,42 @@ export interface SuspendStep {
     readonly id: string;
     readonly payloadSchema?: ZodType;
 }
+/**
+ * theokit#161 — one step of a workflow, as a reflection surface sees it.
+ *
+ * `id` and `kind` are the only fields every step variant shares, and they are what a reflection
+ * endpoint renders. Everything else a step carries is an executable — a predicate, a condition, an
+ * agent, a prompt template — which cannot cross a process boundary and means nothing to a caller
+ * enumerating shape.
+ *
+ * @public
+ */
+export interface WorkflowStepDescription {
+    readonly id: string;
+    readonly kind: Step["kind"];
+    /**
+     * Nested steps, for the variants that contain them: `parallel` (all branches, flattened — the
+     * branch grouping is a scheduling detail, not shape a reader needs), `branch` (each predicate's
+     * steps plus the fallback), `foreach` and `dowhile` (their single inner step).
+     *
+     * Absent for leaf steps. A flat list would misreport a parallel or branching workflow as linear.
+     */
+    readonly steps?: readonly WorkflowStepDescription[];
+}
+/**
+ * theokit#161 — the read-only shape of a committed workflow.
+ *
+ * Returned by `Workflow.describe()`. There is deliberately NO workflow registry to enumerate: a
+ * `Workflow` is a value the caller constructs and holds, so the caller already knows which ones
+ * exist. What it lacked was a way to DESCRIBE one. A registry would have added process-global state
+ * that nothing ever releases, to re-answer a question the host can answer itself.
+ *
+ * @public
+ */
+export interface WorkflowDescription {
+    readonly name: string;
+    readonly steps: readonly WorkflowStepDescription[];
+}
 /** D237 — retry policy applied per fn/agent step. */
 export interface RetryPolicy {
     /** Total attempts (MIN 1, MAX 20). `1` = no retry. */

package/dist/workflow.cjs

@@ -1,99 +1,99 @@
 'use strict';
 
-var chunkOFWU6UKF_cjs = require('./chunk-OFWU6UKF.cjs');
-var chunkBUGVDCI5_cjs = require('./chunk-BUGVDCI5.cjs');
+var chunkC7OP3FAK_cjs = require('./chunk-C7OP3FAK.cjs');
+var chunkCEIHCKTO_cjs = require('./chunk-CEIHCKTO.cjs');
 require('./chunk-PNVDQL5Y.cjs');
 require('./chunk-WJVHMTKB.cjs');
-require('./chunk-YVI4YPUP.cjs');
-require('./chunk-QJQ2MAZF.cjs');
-require('./chunk-A3MHE2MQ.cjs');
-require('./chunk-BE3W4HYV.cjs');
+require('./chunk-DGLLVCNB.cjs');
+require('./chunk-7YBJZS5P.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.Workflow; }
+  get: function () { return chunkC7OP3FAK_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.WorkflowBuilder; }
+  get: function () { return chunkC7OP3FAK_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.WorkflowToolError; }
+  get: function () { return chunkC7OP3FAK_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.agentStep; }
+  get: function () { return chunkC7OP3FAK_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.cloneWorkflow; }
+  get: function () { return chunkC7OP3FAK_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.fn; }
+  get: function () { return chunkC7OP3FAK_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.workflowAsTool; }
+  get: function () { return chunkC7OP3FAK_cjs.workflowAsTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunkOFWU6UKF_cjs.workflowStep; }
+  get: function () { return chunkC7OP3FAK_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowAlreadyRunningError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowAlreadyRunningError; }
 });
 Object.defineProperty(exports, "WorkflowCompensateNotImplementedError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowCompensateNotImplementedError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowCompensateNotImplementedError; }
 });
 Object.defineProperty(exports, "WorkflowDuplicateStepIdError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowDuplicateStepIdError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowDuplicateStepIdError; }
 });
 Object.defineProperty(exports, "WorkflowInputError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowInputError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowInputError; }
 });
 Object.defineProperty(exports, "WorkflowMaxIterationsExceededError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowMaxIterationsExceededError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowMaxIterationsExceededError; }
 });
 Object.defineProperty(exports, "WorkflowNestedError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowNestedError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowNestedError; }
 });
 Object.defineProperty(exports, "WorkflowNotSerializableError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowNotSerializableError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowNotSerializableError; }
 });
 Object.defineProperty(exports, "WorkflowOutputError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowOutputError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowOutputError; }
 });
 Object.defineProperty(exports, "WorkflowParallelError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowParallelError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowParallelError; }
 });
 Object.defineProperty(exports, "WorkflowResumeStepNotFoundError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowResumeStepNotFoundError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowResumeStepNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowSnapshotNotFoundError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowSnapshotNotFoundError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowSnapshotNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowStateError", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.WorkflowStateError; }
+  get: function () { return chunkCEIHCKTO_cjs.WorkflowStateError; }
 });
 Object.defineProperty(exports, "__resetSnapshotStoresForTests", {
   enumerable: true,
-  get: function () { return chunkBUGVDCI5_cjs.__resetSnapshotStoresForTests; }
+  get: function () { return chunkCEIHCKTO_cjs.__resetSnapshotStoresForTests; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.d.cts

@@ -26,7 +26,7 @@ import type { ZodType } from "zod";
 import { z } from "zod";
 import type { CustomTool, SDKAgent } from "./types/agent.js";
 import type { MessageOrigin } from "./types/run.js";
-import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions, WorkflowStream } from "./types/workflow.js";
+import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowDescription, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions, WorkflowStream } from "./types/workflow.js";
 export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
     private readonly options;
     private readonly _steps;
@@ -67,6 +67,22 @@ export declare class Workflow<TInput = unknown, TOutput = unknown> {
      * immutable `Workflow`.
      */
     static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
+    /**
+     * theokit#161 — describe this workflow's shape, for a reflection surface.
+     *
+     * Returns `{ name, steps }`, each step carrying its `id` and `kind`, recursing into `parallel`,
+     * `branch`, `foreach` and `dowhile`. Every executable a step holds — predicates, conditions,
+     * agents, prompt templates — is omitted: it cannot cross a process boundary and says nothing about
+     * shape.
+     *
+     * There is deliberately no `Workflow.list()`. A workflow is a value the caller constructs and
+     * holds, so the caller already knows which ones exist; a registry would add process-global state
+     * nothing releases in order to re-answer a question the host can answer itself. A reflection
+     * endpoint maps over its own workflows and calls this.
+     *
+     * @public
+     */
+    describe(): WorkflowDescription;
     /**
      * Run this workflow with the given input. Returns a populated
      * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via

package/dist/workflow.d.ts

@@ -26,7 +26,7 @@ import type { ZodType } from "zod";
 import { z } from "zod";
 import type { CustomTool, SDKAgent } from "./types/agent.js";
 import type { MessageOrigin } from "./types/run.js";
-import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions, WorkflowStream } from "./types/workflow.js";
+import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowDescription, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions, WorkflowStream } from "./types/workflow.js";
 export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
     private readonly options;
     private readonly _steps;
@@ -67,6 +67,22 @@ export declare class Workflow<TInput = unknown, TOutput = unknown> {
      * immutable `Workflow`.
      */
     static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
+    /**
+     * theokit#161 — describe this workflow's shape, for a reflection surface.
+     *
+     * Returns `{ name, steps }`, each step carrying its `id` and `kind`, recursing into `parallel`,
+     * `branch`, `foreach` and `dowhile`. Every executable a step holds — predicates, conditions,
+     * agents, prompt templates — is omitted: it cannot cross a process boundary and says nothing about
+     * shape.
+     *
+     * There is deliberately no `Workflow.list()`. A workflow is a value the caller constructs and
+     * holds, so the caller already knows which ones exist; a registry would add process-global state
+     * nothing releases in order to re-answer a question the host can answer itself. A reflection
+     * endpoint maps over its own workflows and calls this.
+     *
+     * @public
+     */
+    describe(): WorkflowDescription;
     /**
      * Run this workflow with the given input. Returns a populated
      * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via

package/dist/workflow.js

@@ -1,10 +1,10 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-ACHGT3D2.js';
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-XS7SKY2F.js';
+export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-MC5EINBV.js';
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-V2RBCCN5.js';
 import './chunk-CAH3G4IS.js';
 import './chunk-4VPXM6UU.js';
-import './chunk-LGCEYEU2.js';
-import './chunk-JCXIDFRI.js';
-import './chunk-ZYOHF37V.js';
-import './chunk-KCZW75PI.js';
+import './chunk-KX7JV5KM.js';
+import './chunk-J3UK2GMN.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 //# sourceMappingURL=workflow.js.map
 //# sourceMappingURL=workflow.js.map