condukt 0.6.21 → 0.7.0

package/README.md

@@ -140,9 +140,44 @@ condukt is split into sub-path exports so you only pull in what you need.
 - **Fan-out** — one node fans out to multiple parallel branches
 - **Fan-in** — multiple branches converge into a single node (waits for all)
 - **Loop-back** — edges that point backward with `maxIterations` bounds and `loopFallback` strategy
+- **Loop regions** — bounded multi-node producer/critic/refinement loops with an explicit entry and decision node
 - **Per-node timeout** — individual deadline per node
 - **Abort / Resume** — stop mid-execution and pick up where you left off
 
+### Multi-node loop regions
+
+Declare a `LoopRegion` alongside the graph. The decision node's `continueOn` action resets only the declared region and re-dispatches its entry. Its `exitOn` action follows the normal graph edge.
+
+```typescript
+import type { FlowGraph, LoopRegion } from 'condukt';
+
+const reviewLoop: LoopRegion = {
+  id: 'review-loop',
+  nodes: ['producer', 'critic', 'refine'],
+  entry: 'producer',
+  decision: 'refine',
+  continueOn: 'revise',
+  exitOn: 'accepted',
+  maxIterations: 3,
+  onExhausted: 'manualReview',
+  feedback: (decisionOutput, iteration) =>
+    `Round ${iteration}: ${decisionOutput ?? 'revise the prior output'}`,
+};
+
+const graph: FlowGraph = {
+  nodes: { producer, critic, refine, done, manualReview },
+  edges: {
+    producer: { default: 'critic' },
+    critic: { default: 'refine' },
+    refine: { revise: 'producer', accepted: 'done' },
+  },
+  start: ['producer'],
+  loops: [reviewLoop],
+};
+```
+
+External fan-in contributions to region nodes are preserved across resets. Fired contributions from predecessors inside the region are cleared and rebuilt by the next iteration.
+
 ## UI components
 
 The UI layer is a complete React component library with a warm charcoal dark theme.

package/dist/runtimes/mock/mock-runtime.d.ts

@@ -7,39 +7,42 @@
  */
 import type { AgentRuntime, AgentSession, SessionConfig } from '../../src/types';
 export interface MockNodeConfig {
-    /** Text lines to emit (each becomes a 'text' event). */
-    text?: string[];
+    /** Text lines to emit, or one text value per send. */
+    readonly text?: readonly string[] | readonly (readonly string[])[];
     /** Reasoning lines to emit (each becomes a 'reasoning' event, emitted before text). */
-    reasoning?: string[];
+    readonly reasoning?: readonly string[];
     /** Tool call sequence to emit as tool_start / tool_complete pairs. */
-    tools?: Array<{
-        name: string;
-        input: string;
-        output: string;
+    readonly tools?: ReadonlyArray<{
+        readonly name: string;
+        readonly input: string;
+        readonly output: string;
     }>;
-    /** Artifact content to write to `<cwd>/<artifactFilename>` (if provided). */
-    artifact?: string;
+    /** Artifact content to write, or one artifact value per send. */
+    readonly artifact?: string | readonly string[];
+    /** Override the SessionConfig-derived artifact filename. */
+    readonly artifactFilename?: string;
     /** If provided, emit this error instead of idle. */
-    error?: Error;
+    readonly error?: Error;
     /** Delay in milliseconds before emitting events (simulates work). */
-    delay?: number;
+    readonly delay?: number;
 }
 /**
  * A deterministic mock runtime that replays configured events per node.
  *
- * The node is identified by the `cwd` basename of the SessionConfig —
- * this maps to how the scheduler sets `cwd` to include the node directory.
- * Alternatively, callers can provide a `nodeResolver` function to map
- * SessionConfig to a config key.
+ * The node is identified by `SessionConfig.nodeId` when provided, falling back
+ * to the `cwd` basename for callers that create sessions directly. Callers can
+ * also provide a `nodeResolver` function to map SessionConfig to a config key.
  */
 export declare class MockRuntime implements AgentRuntime {
     readonly name = "mock";
     private readonly configs;
     private readonly nodeResolver;
-    constructor(configs: Record<string, MockNodeConfig>, options?: {
-        nodeResolver?: (config: SessionConfig) => string;
+    private readonly responseIndexes;
+    constructor(configs: Readonly<Record<string, MockNodeConfig>>, options?: {
+        readonly nodeResolver?: (config: SessionConfig) => string;
     });
     isAvailable(): Promise<boolean>;
     createSession(config: SessionConfig): Promise<AgentSession>;
+    private claimResponseIndex;
 }
 //# sourceMappingURL=mock-runtime.d.ts.map

package/dist/runtimes/mock/mock-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-runtime.d.ts","sourceRoot":"","sources":["../../../runtimes/mock/mock-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIjF,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAWD;;;;;;;GAOG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;gBAG/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACvC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,MAAM,CAAA;KAAE;IAM1D,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CAKlE"}
+{"version":3,"file":"mock-runtime.d.ts","sourceRoot":"","sources":["../../../runtimes/mock/mock-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIjF,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACnE,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC,CAAC;IACH,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAyCD;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IACnE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IACjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;gBAG3D,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EACjD,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,MAAM,CAAA;KAAE;IAOnE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAkBjE,OAAO,CAAC,kBAAkB;CAK3B"}

package/dist/runtimes/mock/mock-runtime.js

@@ -43,21 +43,44 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MockRuntime = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+function sequenceValue(values, index) {
+    if (values.length === 0)
+        return undefined;
+    return values[Math.min(index, values.length - 1)];
+}
+function resolveText(configured, responseIndex) {
+    if (!configured)
+        return [];
+    const arrayCount = configured.filter((value) => Array.isArray(value)).length;
+    if (arrayCount > 0 && arrayCount < configured.length) {
+        throw new Error('MockNodeConfig.text must be string[] (one response) or string[][] (per-send), not mixed');
+    }
+    if (arrayCount === configured.length && configured.length > 0) {
+        return sequenceValue(configured, responseIndex) ?? [];
+    }
+    return configured;
+}
+function resolveArtifact(configured, responseIndex) {
+    if (configured === undefined || typeof configured === 'string')
+        return configured;
+    return sequenceValue(configured, responseIndex);
+}
 /**
  * A deterministic mock runtime that replays configured events per node.
  *
- * The node is identified by the `cwd` basename of the SessionConfig —
- * this maps to how the scheduler sets `cwd` to include the node directory.
- * Alternatively, callers can provide a `nodeResolver` function to map
- * SessionConfig to a config key.
+ * The node is identified by `SessionConfig.nodeId` when provided, falling back
+ * to the `cwd` basename for callers that create sessions directly. Callers can
+ * also provide a `nodeResolver` function to map SessionConfig to a config key.
  */
 class MockRuntime {
     name = 'mock';
     configs;
     nodeResolver;
+    responseIndexes = new Map();
     constructor(configs, options) {
         this.configs = configs;
-        this.nodeResolver = options?.nodeResolver ?? ((config) => path.basename(config.cwd));
+        this.nodeResolver = options?.nodeResolver
+            ?? ((config) => config.nodeId ?? path.basename(config.cwd));
     }
     async isAvailable() {
         return true;
@@ -65,7 +88,19 @@ class MockRuntime {
     async createSession(config) {
         const nodeKey = this.nodeResolver(config);
         const nodeConfig = this.configs[nodeKey] ?? {};
-        return new MockAgentSession(nodeConfig, config.cwd);
+        // Parity: the node's real configured output (SessionConfig.artifactFilename,
+        // set by agent() from config.output) wins so the mock writes where the node
+        // actually reads. nodeConfig.artifactFilename is only an override for tests
+        // driving MockRuntime directly (no SessionConfig filename present).
+        const artifactFilename = config.artifactFilename
+            ?? nodeConfig.artifactFilename
+            ?? 'output.md';
+        return new MockAgentSession(nodeConfig, config.cwd, artifactFilename, () => this.claimResponseIndex(nodeKey));
+    }
+    claimResponseIndex(nodeKey) {
+        const index = this.responseIndexes.get(nodeKey) ?? 0;
+        this.responseIndexes.set(nodeKey, index + 1);
+        return index;
     }
 }
 exports.MockRuntime = MockRuntime;
@@ -74,14 +109,19 @@ class MockAgentSession {
     handlers = [];
     nodeConfig;
     cwd;
+    artifactFilename;
+    claimResponseIndex;
     aborted = false;
     timer = null;
-    constructor(nodeConfig, cwd) {
+    constructor(nodeConfig, cwd, artifactFilename, claimResponseIndex) {
         this.nodeConfig = nodeConfig;
         this.cwd = cwd;
+        this.artifactFilename = artifactFilename;
+        this.claimResponseIndex = claimResponseIndex;
     }
     send(_prompt) {
         const delay = this.nodeConfig.delay ?? 0;
+        const responseIndex = this.claimResponseIndex();
         const execute = () => {
             if (this.aborted)
                 return;
@@ -94,12 +134,11 @@ class MockAgentSession {
                 }
             }
             // Emit text events
-            if (this.nodeConfig.text) {
-                for (const line of this.nodeConfig.text) {
-                    if (this.aborted)
-                        return;
-                    this.emit('text', line);
-                }
+            const text = resolveText(this.nodeConfig.text, responseIndex);
+            for (const line of text) {
+                if (this.aborted)
+                    return;
+                this.emit('text', line);
             }
             // Emit tool events
             if (this.nodeConfig.tools) {
@@ -111,15 +150,16 @@ class MockAgentSession {
                 }
             }
             // Write artifact if configured
-            if (this.nodeConfig.artifact !== undefined) {
+            const artifact = resolveArtifact(this.nodeConfig.artifact, responseIndex);
+            if (artifact !== undefined) {
                 try {
-                    // Write the artifact content to a file named 'output.md' in cwd
-                    const artifactPath = path.join(this.cwd, 'output.md');
-                    fs.mkdirSync(this.cwd, { recursive: true });
-                    fs.writeFileSync(artifactPath, this.nodeConfig.artifact, 'utf-8');
+                    const artifactPath = path.join(this.cwd, this.artifactFilename);
+                    fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+                    fs.writeFileSync(artifactPath, artifact, 'utf-8');
                 }
-                catch {
-                    // Best effort — test may not have a writable cwd
+                catch (error) {
+                    this.emit('error', error instanceof Error ? error : new Error(String(error)));
+                    return;
                 }
             }
             if (this.aborted)

package/dist/runtimes/mock/mock-runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"mock-runtime.js","sourceRoot":"","sources":["../../../runtimes/mock/mock-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mock-runtime.js","sourceRoot":"","sources":["../../../runtimes/mock/mock-runtime.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGH,uCAAyB;AACzB,2CAA6B;AAgC7B,SAAS,aAAa,CAAI,MAAoB,EAAE,KAAa;IAC3D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,WAAW,CAClB,UAAkC,EAClC,aAAqB;IAErB,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAC3B,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7E,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,UAAU,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,OAAO,aAAa,CAAC,UAA4C,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC;IAC1F,CAAC;IACD,OAAO,UAA+B,CAAC;AACzC,CAAC;AAED,SAAS,eAAe,CACtB,UAAsC,EACtC,aAAqB;IAErB,IAAI,UAAU,KAAK,SAAS,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC;IAClF,OAAO,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAa,WAAW;IACb,IAAI,GAAG,MAAM,CAAC;IACN,OAAO,CAA2C;IAClD,YAAY,CAAoC;IAChD,eAAe,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE7D,YACE,OAAiD,EACjD,OAAuE;QAEvE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY;eACpC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,MAAqB;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAC/C,6EAA6E;QAC7E,4EAA4E;QAC5E,4EAA4E;QAC5E,oEAAoE;QACpE,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB;eAC3C,UAAU,CAAC,gBAAgB;eAC3B,WAAW,CAAC;QACjB,OAAO,IAAI,gBAAgB,CACzB,UAAU,EACV,MAAM,CAAC,GAAG,EACV,gBAAgB,EAChB,GAAG,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CACvC,CAAC;IACJ,CAAC;IAEO,kBAAkB,CAAC,OAAe;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AA1CD,kCA0CC;AAED,MAAM,gBAAgB;IACX,GAAG,GAAkB,IAAI,CAAC;IAC3B,QAAQ,GAAmB,EAAE,CAAC;IACrB,UAAU,CAAiB;IAC3B,GAAG,CAAS;IACZ,gBAAgB,CAAS;IACzB,kBAAkB,CAAe;IAC1C,OAAO,GAAG,KAAK,CAAC;IAChB,KAAK,GAAyC,IAAI,CAAC;IAE3D,YACE,UAA0B,EAC1B,GAAW,EACX,gBAAwB,EACxB,kBAAgC;QAEhC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,CAAC;QACzC,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAEhD,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YAEzB,oEAAoE;YACpE,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;gBAC9B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;oBAC7C,IAAI,IAAI,CAAC,OAAO;wBAAE,OAAO;oBACzB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YAED,mBAAmB;YACnB,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAC9D,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;gBACxB,IAAI,IAAI,CAAC,OAAO;oBAAE,OAAO;gBACzB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC1B,CAAC;YAED,mBAAmB;YACnB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBAC1B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;oBACzC,IAAI,IAAI,CAAC,OAAO;wBAAE,OAAO;oBACzB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBACnD,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;YAED,+BAA+B;YAC/B,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;YAC1E,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;oBAChE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC9D,EAAE,CAAC,aAAa,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;gBACpD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,CAAC,IAAI,CACP,OAAO,EACP,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC1D,CAAC;oBACF,OAAO;gBACT,CAAC;YACH,CAAC;YAED,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YAEzB,qBAAqB;YACrB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,kDAAkD;YAClD,cAAc,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAkBD,EAAE,CAAC,KAAa,EAAE,OAAmC;QACnD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAkB,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAEO,IAAI,CAAC,KAAa,EAAE,GAAG,IAAe;QAC5C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;gBACrB,CAAC,CAAC,OAAqC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/src/agent-node.d.ts

@@ -0,0 +1,84 @@
+import type { ExecutionContext, NodeEntry, NodeInput, ThinkingBudget, ToolRef } from './types';
+export type SchemaValidationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+/** Minimal validation contract used by agentNode(). */
+export interface SchemaValidator<T> {
+    readonly validate: (value: unknown) => SchemaValidationResult<T> | Promise<SchemaValidationResult<T>>;
+}
+export type SchemaValidationFunction<T> = (value: unknown) => T | undefined;
+interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: readonly unknown[];
+}
+type StandardSchemaResult<T> = {
+    readonly value: T;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaIssue[];
+};
+/** Structural subset of Standard Schema, kept local to avoid a runtime dependency. */
+export interface StandardSchemaValidator<T> {
+    readonly '~standard': {
+        readonly validate: (value: unknown) => StandardSchemaResult<T> | PromiseLike<StandardSchemaResult<T>>;
+    };
+}
+export type AgentNodeSchema<T> = SchemaValidator<T> | SchemaValidationFunction<T> | StandardSchemaValidator<T>;
+export interface AgentNodeConfig<T> {
+    readonly prompt: string | ((input: NodeInput, reads: Readonly<Record<string, unknown>>) => string);
+    readonly model: string;
+    readonly schema?: AgentNodeSchema<T>;
+    readonly system?: string;
+    readonly output?: string;
+    readonly reads?: readonly string[];
+    readonly displayName?: string;
+    readonly thinkingBudget?: ThinkingBudget;
+    readonly timeout?: number;
+    readonly isolation?: boolean;
+    readonly tools?: readonly ToolRef[] | readonly string[];
+    readonly route?: (result: T) => string;
+    readonly fallback?: (raw: string, error: Error) => T;
+    readonly structuredRetry?: number;
+}
+/** Normalize condukt, function, and Standard Schema validators. */
+export declare function toValidator<T>(schema: AgentNodeSchema<T>): SchemaValidator<T>;
+/**
+ * Yield every parseable JSON value in `text`, best first: the whole trimmed
+ * string, then each balanced object/array span in start order (so a top-level
+ * value is tried before a nested one). The caller validates candidates in order
+ * and takes the first that satisfies the schema — so an example snippet that
+ * precedes the real answer, or a span that parses but fails validation, does not
+ * mask a later valid value.
+ */
+export declare function extractJsonCandidates(text: string): Generator<unknown>;
+export declare function loadReads(input: NodeInput, names: readonly string[] | undefined): Readonly<Record<string, unknown>>;
+export declare function repairPrompt(prompt: string, raw: string, error: Error): string;
+export declare function validationError(issues: readonly string[]): Error;
+export declare function validateCandidate<T>(validator: SchemaValidator<T>, value: unknown): Promise<SchemaValidationResult<T>>;
+export declare function serialize(value: unknown): string;
+export declare function writeOutput(input: NodeInput, output: string | undefined, content: string): void;
+export declare function removeInvalidOutput(input: NodeInput, output: string | undefined): void;
+export declare function retryCount(value: number | undefined): number;
+export interface ProducerResult {
+    readonly artifact?: string;
+    readonly text: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface RawCandidate {
+    readonly label: string;
+    readonly raw: string;
+}
+export declare function rawCandidates(result: ProducerResult): readonly RawCandidate[];
+export declare function produce<T>(config: AgentNodeConfig<T>, prompt: string, input: NodeInput, ctx: ExecutionContext): Promise<ProducerResult>;
+/**
+ * Create a batteries-included agent NodeEntry with optional validated structured output.
+ *
+ * @experimental Experimental — API may change before it stabilizes into condukt core.
+ */
+export declare function agentNode<T = string>(config: AgentNodeConfig<T>): NodeEntry;
+export {};
+//# sourceMappingURL=agent-node.d.ts.map

package/dist/src/agent-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-node.d.ts","sourceRoot":"","sources":["../../src/agent-node.ts"],"names":[],"mappings":"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"}