@theokit/sdk 4.37.2 → 4.39.0

package/dist/compact-session-PYEC3NZV.js

@@ -0,0 +1,18 @@
+export { COMPACT_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, autoCompactIfNeeded, buildDefaultSummarizer, compactSessionTranscript, isCompactSummary, resolveSummarizerRoute, shouldAutoCompact } from './chunk-ZYB6B7QJ.js';
+import './chunk-HWNVAUK4.js';
+import './chunk-5KOW3GLE.js';
+import './chunk-SCFW5MJZ.js';
+import './chunk-FD2UT76F.js';
+import './chunk-U54XCYG3.js';
+import './chunk-JRLXEYR4.js';
+import './chunk-2XLKLVVR.js';
+import './chunk-KX7JV5KM.js';
+import './chunk-65ONFZWM.js';
+import './chunk-TOTP24P6.js';
+import './chunk-DKFGUOWL.js';
+import './chunk-5NBUH3NO.js';
+import './chunk-J3UK2GMN.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
+//# sourceMappingURL=compact-session-PYEC3NZV.js.map
+//# sourceMappingURL=compact-session-PYEC3NZV.js.map

package/dist/{compact-session-WNKKIIDW.js.map → compact-session-PYEC3NZV.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"compact-session-WNKKIIDW.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"compact-session-PYEC3NZV.js"}

package/dist/compact-session-VVT6IBJG.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+var chunkBPN5ONSW_cjs = require('./chunk-BPN5ONSW.cjs');
+require('./chunk-ECW2MLEW.cjs');
+require('./chunk-BURYFNOM.cjs');
+require('./chunk-6YNYA7GD.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-6JSIEDKL.cjs');
+require('./chunk-Z2CUEBXV.cjs');
+require('./chunk-YLQQX5W2.cjs');
+require('./chunk-DGLLVCNB.cjs');
+require('./chunk-J6T5LWJ4.cjs');
+require('./chunk-G4XUXSRN.cjs');
+require('./chunk-6NEHIHFU.cjs');
+require('./chunk-C6Y6CWYD.cjs');
+require('./chunk-7YBJZS5P.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "COMPACT_SUMMARY_MARKER", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.COMPACT_SUMMARY_MARKER; }
+});
+Object.defineProperty(exports, "COMPACT_USER_MESSAGE_MAX_TOKENS", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.COMPACT_USER_MESSAGE_MAX_TOKENS; }
+});
+Object.defineProperty(exports, "autoCompactIfNeeded", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.autoCompactIfNeeded; }
+});
+Object.defineProperty(exports, "buildDefaultSummarizer", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.buildDefaultSummarizer; }
+});
+Object.defineProperty(exports, "compactSessionTranscript", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.compactSessionTranscript; }
+});
+Object.defineProperty(exports, "isCompactSummary", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.isCompactSummary; }
+});
+Object.defineProperty(exports, "resolveSummarizerRoute", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.resolveSummarizerRoute; }
+});
+Object.defineProperty(exports, "shouldAutoCompact", {
+  enumerable: true,
+  get: function () { return chunkBPN5ONSW_cjs.shouldAutoCompact; }
+});
+//# sourceMappingURL=compact-session-VVT6IBJG.cjs.map
+//# sourceMappingURL=compact-session-VVT6IBJG.cjs.map

package/dist/{compact-session-H5TKLD55.cjs.map → compact-session-VVT6IBJG.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"compact-session-H5TKLD55.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"compact-session-VVT6IBJG.cjs"}

package/dist/compaction.cjs

@@ -1,62 +1,62 @@
 'use strict';
 
-var chunk4YB7B3RP_cjs = require('./chunk-4YB7B3RP.cjs');
-require('./chunk-MHCKWQR3.cjs');
-require('./chunk-LTCOPATU.cjs');
+var chunkJ6T5LWJ4_cjs = require('./chunk-J6T5LWJ4.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 
 
+Object.defineProperty(exports, "ABSOLUTE_CONTEXT_WINDOW_CAP", {
+  enumerable: true,
+  get: function () { return chunkJ6T5LWJ4_cjs.ABSOLUTE_CONTEXT_WINDOW_CAP; }
+});
 Object.defineProperty(exports, "CHECKPOINT_MARKER", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.CHECKPOINT_MARKER; }
+  get: function () { return chunkJ6T5LWJ4_cjs.CHECKPOINT_MARKER; }
 });
 Object.defineProperty(exports, "CONTEXT_WINDOW_FLOOR", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.CONTEXT_WINDOW_FLOOR; }
+  get: function () { return chunkJ6T5LWJ4_cjs.CONTEXT_WINDOW_FLOOR; }
 });
 Object.defineProperty(exports, "CONTEXT_WINDOW_MARGIN", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.CONTEXT_WINDOW_MARGIN; }
+  get: function () { return chunkJ6T5LWJ4_cjs.CONTEXT_WINDOW_MARGIN; }
 });
 Object.defineProperty(exports, "ContextWindowMarginError", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.ContextWindowMarginError; }
+  get: function () { return chunkJ6T5LWJ4_cjs.ContextWindowMarginError; }
 });
 Object.defineProperty(exports, "SUMMARY_TEMPLATE", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.SUMMARY_TEMPLATE; }
-});
-Object.defineProperty(exports, "TETO_ABSOLUTO_DE_JANELA", {
-  enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.TETO_ABSOLUTO_DE_JANELA; }
+  get: function () { return chunkJ6T5LWJ4_cjs.SUMMARY_TEMPLATE; }
 });
 Object.defineProperty(exports, "buildCheckpoint", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.buildCheckpoint; }
+  get: function () { return chunkJ6T5LWJ4_cjs.buildCheckpoint; }
 });
 Object.defineProperty(exports, "compactTranscript", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.compactTranscript; }
+  get: function () { return chunkJ6T5LWJ4_cjs.compactTranscript; }
 });
 Object.defineProperty(exports, "estimateTokens", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.estimateTokens; }
+  get: function () { return chunkJ6T5LWJ4_cjs.estimateTokens; }
 });
 Object.defineProperty(exports, "filterFromLatestCheckpoint", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.filterFromLatestCheckpoint; }
+  get: function () { return chunkJ6T5LWJ4_cjs.filterFromLatestCheckpoint; }
 });
 Object.defineProperty(exports, "isContextOverflowError", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.isContextOverflowError; }
+  get: function () { return chunkJ6T5LWJ4_cjs.isContextOverflowError; }
 });
 Object.defineProperty(exports, "resolveEffectiveContextWindow", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.resolveEffectiveContextWindow; }
+  get: function () { return chunkJ6T5LWJ4_cjs.resolveEffectiveContextWindow; }
 });
 Object.defineProperty(exports, "shouldCompact", {
   enumerable: true,
-  get: function () { return chunk4YB7B3RP_cjs.shouldCompact; }
+  get: function () { return chunkJ6T5LWJ4_cjs.shouldCompact; }
 });
 //# sourceMappingURL=compaction.cjs.map
 //# sourceMappingURL=compaction.cjs.map

package/dist/compaction.d.cts

@@ -179,18 +179,18 @@ export interface EffectiveContextWindow {
  * Pure — no catalog lookup, no I/O. The caller supplies the numbers, mirroring `shouldCompact`.
  */
 /**
- * Teto absoluto de janela declarada, usado quando não há entrada de catálogo para comparar.
+ * Absolute cap on a declared context window, applied when no catalog entry exists to compare against.
  *
- * **10M**, não 2M. A primeira versão usou 2M com a justificativa de estar "acima da maior janela
- * publicada com folga larga" — e a revisão adversarial mediu o contrário: o Llama 4 Scout publica
- * **10M**, e chega justamente por OpenRouter, que é o provider **sem** catálogo, isto é, o caso que
- * este teto existe para cobrir. O usuário perderia 80% da janela declarada, em silêncio.
+ * **10M**, not 2M. The first version used 2M on the rationale that it sat "comfortably above the
+ * largest published window" — adversarial review measured the opposite: Llama 4 Scout publishes
+ * **10M**, and it arrives precisely via OpenRouter, the provider **without** a catalog, which is the
+ * case this cap exists to cover. The user would have silently lost 80% of the declared window.
  *
- * O teto continua servindo ao que motiva sua existência — um zero a mais em 400k dá 4M, que passa;
- * dois zeros dão 40M, que não. Um limite que recusa configuração legítima é pior que limite nenhum,
- * porque o fail-OPEN é visível quando acontece e a perda silenciosa de 80% não é.
+ * The cap still serves what motivates it — one extra zero on 400k gives 4M, which passes; two zeros
+ * give 40M, which does not. A limit that rejects legitimate configuration is worse than no limit,
+ * because failing OPEN is visible when it happens and silently losing 80% is not.
  */
-export declare const TETO_ABSOLUTO_DE_JANELA = 10000000;
+export declare const ABSOLUTE_CONTEXT_WINDOW_CAP = 10000000;
 export declare function resolveEffectiveContextWindow(input: EffectiveContextWindowInput): EffectiveContextWindow;
 /** Input to {@link shouldCompact}: an estimate, the model's window, and reserved headroom. */
 export interface ShouldCompactInput {

package/dist/compaction.d.ts

@@ -179,18 +179,18 @@ export interface EffectiveContextWindow {
  * Pure — no catalog lookup, no I/O. The caller supplies the numbers, mirroring `shouldCompact`.
  */
 /**
- * Teto absoluto de janela declarada, usado quando não há entrada de catálogo para comparar.
+ * Absolute cap on a declared context window, applied when no catalog entry exists to compare against.
  *
- * **10M**, não 2M. A primeira versão usou 2M com a justificativa de estar "acima da maior janela
- * publicada com folga larga" — e a revisão adversarial mediu o contrário: o Llama 4 Scout publica
- * **10M**, e chega justamente por OpenRouter, que é o provider **sem** catálogo, isto é, o caso que
- * este teto existe para cobrir. O usuário perderia 80% da janela declarada, em silêncio.
+ * **10M**, not 2M. The first version used 2M on the rationale that it sat "comfortably above the
+ * largest published window" — adversarial review measured the opposite: Llama 4 Scout publishes
+ * **10M**, and it arrives precisely via OpenRouter, the provider **without** a catalog, which is the
+ * case this cap exists to cover. The user would have silently lost 80% of the declared window.
  *
- * O teto continua servindo ao que motiva sua existência — um zero a mais em 400k dá 4M, que passa;
- * dois zeros dão 40M, que não. Um limite que recusa configuração legítima é pior que limite nenhum,
- * porque o fail-OPEN é visível quando acontece e a perda silenciosa de 80% não é.
+ * The cap still serves what motivates it — one extra zero on 400k gives 4M, which passes; two zeros
+ * give 40M, which does not. A limit that rejects legitimate configuration is worse than no limit,
+ * because failing OPEN is visible when it happens and silently losing 80% is not.
  */
-export declare const TETO_ABSOLUTO_DE_JANELA = 10000000;
+export declare const ABSOLUTE_CONTEXT_WINDOW_CAP = 10000000;
 export declare function resolveEffectiveContextWindow(input: EffectiveContextWindowInput): EffectiveContextWindow;
 /** Input to {@link shouldCompact}: an estimate, the model's window, and reserved headroom. */
 export interface ShouldCompactInput {

package/dist/compaction.js

@@ -1,5 +1,5 @@
-export { CHECKPOINT_MARKER, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN, ContextWindowMarginError, SUMMARY_TEMPLATE, TETO_ABSOLUTO_DE_JANELA, buildCheckpoint, compactTranscript, estimateTokens, filterFromLatestCheckpoint, isContextOverflowError, resolveEffectiveContextWindow, shouldCompact } from './chunk-6VP3XGEK.js';
-import './chunk-CD73YHEH.js';
-import './chunk-TAPQWDW2.js';
+export { ABSOLUTE_CONTEXT_WINDOW_CAP, CHECKPOINT_MARKER, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN, ContextWindowMarginError, SUMMARY_TEMPLATE, buildCheckpoint, compactTranscript, estimateTokens, filterFromLatestCheckpoint, isContextOverflowError, resolveEffectiveContextWindow, shouldCompact } from './chunk-65ONFZWM.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 //# sourceMappingURL=compaction.js.map
 //# sourceMappingURL=compaction.js.map

package/dist/concurrency.cjs

@@ -1,22 +1,22 @@
 'use strict';
 
-var chunkSWIBQFPH_cjs = require('./chunk-SWIBQFPH.cjs');
-var chunkMRODLUGY_cjs = require('./chunk-MRODLUGY.cjs');
-require('./chunk-MHCKWQR3.cjs');
-require('./chunk-LTCOPATU.cjs');
+var chunk7OLG7VI4_cjs = require('./chunk-7OLG7VI4.cjs');
+var chunkTIMPJL5V_cjs = require('./chunk-TIMPJL5V.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 // src/concurrency.ts
 var Semaphore = class {
   constructor() {
   }
   static create(permits) {
-    return chunkMRODLUGY_cjs.createSemaphore(permits);
+    return chunkTIMPJL5V_cjs.createSemaphore(permits);
   }
 };
 
 Object.defineProperty(exports, "mapWithConcurrency", {
   enumerable: true,
-  get: function () { return chunkSWIBQFPH_cjs.mapWithConcurrency; }
+  get: function () { return chunk7OLG7VI4_cjs.mapWithConcurrency; }
 });
 exports.Semaphore = Semaphore;
 //# sourceMappingURL=concurrency.cjs.map

package/dist/concurrency.js

@@ -1,7 +1,7 @@
-export { mapWithConcurrency } from './chunk-QGDKZDPN.js';
-import { createSemaphore } from './chunk-NFCKEBHI.js';
-import './chunk-CD73YHEH.js';
-import './chunk-TAPQWDW2.js';
+export { mapWithConcurrency } from './chunk-LGILIGV3.js';
+import { createSemaphore } from './chunk-PI4RO4GR.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 
 // src/concurrency.ts
 var Semaphore = class {

package/dist/context-2FZSC6VQ.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+var chunk6LGQECT7_cjs = require('./chunk-6LGQECT7.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "currentPersonalityContext", {
+  enumerable: true,
+  get: function () { return chunk6LGQECT7_cjs.currentPersonalityContext; }
+});
+Object.defineProperty(exports, "warnPersonalitySwitchInsideFork", {
+  enumerable: true,
+  get: function () { return chunk6LGQECT7_cjs.warnPersonalitySwitchInsideFork; }
+});
+Object.defineProperty(exports, "withPersonalityContext", {
+  enumerable: true,
+  get: function () { return chunk6LGQECT7_cjs.withPersonalityContext; }
+});
+//# sourceMappingURL=context-2FZSC6VQ.cjs.map
+//# sourceMappingURL=context-2FZSC6VQ.cjs.map

package/dist/{context-ZV33V4DC.cjs.map → context-2FZSC6VQ.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"context-ZV33V4DC.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"context-2FZSC6VQ.cjs"}

package/dist/context-ATJJAFOS.js

@@ -0,0 +1,5 @@
+export { currentPersonalityContext, warnPersonalitySwitchInsideFork, withPersonalityContext } from './chunk-ML5A5DOJ.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
+//# sourceMappingURL=context-ATJJAFOS.js.map
+//# sourceMappingURL=context-ATJJAFOS.js.map

package/dist/{context-VAYLPT4O.js.map → context-ATJJAFOS.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"context-VAYLPT4O.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"context-ATJJAFOS.js"}

package/dist/{cron-Dx7B-3WB.d.ts → cron-Bx7tzm5R.d.ts}

@@ -1,6 +1,6 @@
 import { ZodType } from 'zod';
-import { e as SDKAgent, A as AgentOptions, g as ListResult } from './agent-SmxntivO.js';
-import { u as MessageOrigin, ac as SDKUserMessage, b as Run } from './run-CwEJtLPE.js';
+import { e as SDKAgent, A as AgentOptions, g as ListResult } from './agent-ZCZa7YQv.js';
+import { u as MessageOrigin, ad as SDKUserMessage, b as Run } from './run-i2-fUohR.js';
 
 /**
  * Public type contract for `Workflow.create / .run / .resume` (Adoption
@@ -83,6 +83,42 @@ 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
+ */
+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
+ */
+interface WorkflowDescription {
+    readonly name: string;
+    readonly steps: readonly WorkflowStepDescription[];
+}
 /** D237 — retry policy applied per fn/agent step. */
 interface RetryPolicy {
     /** Total attempts (MIN 1, MAX 20). `1` = no retry. */
@@ -312,6 +348,22 @@ 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/{cron-BiK_aNJI.d.cts → cron-D-DVjGQe.d.cts}

@@ -1,6 +1,6 @@
 import { ZodType } from 'zod';
-import { e as SDKAgent, A as AgentOptions, g as ListResult } from './agent-DGv1-d81.cjs';
-import { u as MessageOrigin, ac as SDKUserMessage, b as Run } from './run-CwEJtLPE.cjs';
+import { e as SDKAgent, A as AgentOptions, g as ListResult } from './agent-D7bRK9Kg.cjs';
+import { u as MessageOrigin, ad as SDKUserMessage, b as Run } from './run-i2-fUohR.cjs';
 
 /**
  * Public type contract for `Workflow.create / .run / .resume` (Adoption
@@ -83,6 +83,42 @@ 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
+ */
+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
+ */
+interface WorkflowDescription {
+    readonly name: string;
+    readonly steps: readonly WorkflowStepDescription[];
+}
 /** D237 — retry policy applied per fn/agent step. */
 interface RetryPolicy {
     /** Total attempts (MIN 1, MAX 20). `1` = no retry. */
@@ -312,6 +348,22 @@ 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/cron.cjs

@@ -1,52 +1,56 @@
 'use strict';
 
-var chunkG6AASL5T_cjs = require('./chunk-G6AASL5T.cjs');
-require('./chunk-W52DKZBR.cjs');
+var chunkFRUBE44B_cjs = require('./chunk-FRUBE44B.cjs');
+require('./chunk-INSFS5GT.cjs');
 require('./chunk-BV2MWEMV.cjs');
-require('./chunk-6EDQBX7U.cjs');
-require('./chunk-H5YVJB4K.cjs');
+require('./chunk-N475ETD6.cjs');
 require('./chunk-BUUUWQMB.cjs');
-require('./chunk-ITLS5LRF.cjs');
-require('./chunk-ALU3KC4G.cjs');
-require('./chunk-U2WLFOA3.cjs');
-require('./chunk-IT3PWBW4.cjs');
-require('./chunk-2423XDPT.cjs');
-require('./chunk-FAY3QDGC.cjs');
+require('./chunk-DCXRHCZJ.cjs');
+require('./chunk-74D7KSBP.cjs');
+require('./chunk-BPN5ONSW.cjs');
+require('./chunk-ECW2MLEW.cjs');
+require('./chunk-BURYFNOM.cjs');
+require('./chunk-XYOHKCYG.cjs');
+require('./chunk-CN6UX5EV.cjs');
+require('./chunk-6LGQECT7.cjs');
 require('./chunk-WPZTYOUX.cjs');
-require('./chunk-D4ZUJTFB.cjs');
+require('./chunk-LALG2K33.cjs');
+require('./chunk-7U2HAAWB.cjs');
+require('./chunk-6YNYA7GD.cjs');
+require('./chunk-2RW7K6FN.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
 require('./chunk-6JSIEDKL.cjs');
-require('./chunk-G2F67XUR.cjs');
+require('./chunk-B4YA6BRS.cjs');
 require('./chunk-NINIJCHU.cjs');
 require('./chunk-YPEPCZHF.cjs');
 require('./chunk-VJ26EKGJ.cjs');
-require('./chunk-SWIBQFPH.cjs');
-require('./chunk-MRODLUGY.cjs');
-require('./chunk-P34DHHYQ.cjs');
-require('./chunk-TQI3KRXZ.cjs');
-require('./chunk-FK4EJD2I.cjs');
+require('./chunk-7OLG7VI4.cjs');
+require('./chunk-TIMPJL5V.cjs');
+require('./chunk-I53ZQHU6.cjs');
+require('./chunk-Z2CUEBXV.cjs');
+require('./chunk-DMTZ3FII.cjs');
+require('./chunk-75DSEWTJ.cjs');
 require('./chunk-YLQQX5W2.cjs');
-require('./chunk-IEUDKUPM.cjs');
-require('./chunk-W4QN5CMG.cjs');
+require('./chunk-DWY25VLP.cjs');
 require('./chunk-WJVHMTKB.cjs');
-require('./chunk-ICYBIC6N.cjs');
-require('./chunk-GM7QDQ24.cjs');
-require('./chunk-4YB7B3RP.cjs');
+require('./chunk-DGLLVCNB.cjs');
+require('./chunk-W4WKVOOQ.cjs');
+require('./chunk-J6T5LWJ4.cjs');
 require('./chunk-VYHJZVL5.cjs');
-require('./chunk-56ZM6P7Z.cjs');
-require('./chunk-PAEJPLVN.cjs');
+require('./chunk-G4XUXSRN.cjs');
+require('./chunk-6NEHIHFU.cjs');
 require('./chunk-C6Y6CWYD.cjs');
-require('./chunk-QUFSDDNU.cjs');
-require('./chunk-YBFDBOUN.cjs');
-require('./chunk-7DXLNNKH.cjs');
-require('./chunk-MHCKWQR3.cjs');
-require('./chunk-LTCOPATU.cjs');
+require('./chunk-E4IUN3JB.cjs');
+require('./chunk-7YBJZS5P.cjs');
+require('./chunk-G2Q3ZC6C.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 
 
 Object.defineProperty(exports, "Cron", {
   enumerable: true,
-  get: function () { return chunkG6AASL5T_cjs.Cron; }
+  get: function () { return chunkFRUBE44B_cjs.Cron; }
 });
 //# sourceMappingURL=cron.cjs.map
 //# sourceMappingURL=cron.cjs.map

package/dist/cron.d.cts

@@ -1,4 +1,4 @@
-export { C as Cron } from './cron-BiK_aNJI.cjs';
-import './run-CwEJtLPE.cjs';
-import './agent-DGv1-d81.cjs';
+export { C as Cron } from './cron-D-DVjGQe.cjs';
+import './run-i2-fUohR.cjs';
+import './agent-D7bRK9Kg.cjs';
 import 'zod';

package/dist/cron.d.ts

@@ -1,4 +1,4 @@
-export { C as Cron } from './cron-Dx7B-3WB.js';
-import './run-CwEJtLPE.js';
-import './agent-SmxntivO.js';
+export { C as Cron } from './cron-Bx7tzm5R.js';
+import './run-i2-fUohR.js';
+import './agent-ZCZa7YQv.js';
 import 'zod';