@maxanstey-meridian/tandem 0.1.4 → 0.1.6

package/README.md

@@ -5,7 +5,7 @@ agentic pipeline SDK running on .NET and Microsoft Agent Framework.
 
 ## Requirements
 
-- macOS on Apple silicon
+- macOS on Apple silicon or Linux x64
 - Node.js 22 or newer
 - .NET 10 runtime
 
@@ -15,8 +15,8 @@ agentic pipeline SDK running on .NET and Microsoft Agent Framework.
 npm install @maxanstey-meridian/tandem zod
 ```
 
-The package includes compiled JavaScript, TypeScript declarations, and the macOS Apple silicon
-bridge runtime. Installation does not compile the SDK or download a bridge.
+The package includes compiled JavaScript, TypeScript declarations, and bridge runtimes for
+macOS Apple silicon and Linux x64. Installation does not compile the SDK or download a bridge.
 
 ## Quick Start
 
@@ -77,5 +77,40 @@ npm pack
 ```
 
 `npm pack` and `npm publish` build fresh output before packaging. The npm package contains
-`dist`, including one copy of the vendored bridge in `dist/runtime`. Update `runtime` from
-a tested Tandem bridge build before releasing runtime changes.
+`dist`, including the vendored platform bridge bundles in `dist/runtime`. Update each runtime
+bundle from a tested Tandem bridge build before releasing runtime changes.
+
+## Runtime-sized collections
+
+Use `collection` for a list whose size is known at execution time. Declare its
+item/result schemas and agents, select items from state, and apply the ordered
+results. Native Tandem owns scheduling through `max`; zero and one item need no
+special graph.
+
+`taskAgent<Input, Output>` defines a model participant with validated input and
+output. Inside a collection, `context.run(agent, input)` invokes only agents
+declared on that collection. Await each call before the next. Scope use after
+completion and sibling parallel agent calls are rejected. Operational failure
+fails the collection, drains active work, and skips application of results.
+
+```ts
+const canonicalise = collection({
+  id: "canonicalise",
+  item: Proposition,
+  result: Claim,
+  agents: [canonicaliser],
+  max: 6,
+  items: (state: SourceState) => state.propositions,
+  execute: (proposition, context) => context.run(canonicaliser, proposition),
+  apply: (state, claims) => ({ ...state, claims }),
+});
+```
+
+The executable [collection example](tests/collection-child.ts) includes
+conditional recovery, persistence, cancellation and concurrent source runs.
+Agent visits remain in the source run's native observations and ledger.
+
+Agent definitions may be reused across collections. Native Tandem binds each under
+its collection name. Scoped observations and accepted ledger values carry a
+`visitId` so concurrent calls can be correlated without changing their semantic
+`stepId`.

package/dist/index.d.ts

@@ -55,7 +55,7 @@ export interface Parallel<TState> extends Participant<TState> {
 export interface Terminal<TState> extends Participant<TState> {
     readonly kind: "terminal";
 }
-type Node<TState> = Stage<TState> | Interaction<TState, unknown, unknown> | Agent<TState> | Parallel<TState> | Terminal<TState>;
+type Node<TState> = Collection<TState> | Stage<TState> | Interaction<TState, unknown, unknown> | Agent<TState> | Parallel<TState> | Terminal<TState>;
 export declare function stage<TState>(definition: {
     id: string;
     execute: (state: TState, context: {
@@ -63,6 +63,44 @@ export declare function stage<TState>(definition: {
     }) => TState | Promise<TState>;
     persist?: boolean;
 }): Stage<TState>;
+declare const taskAgentBrand: unique symbol;
+export interface TaskAgentReference {
+    readonly id: string;
+    readonly [taskAgentBrand]: true;
+}
+export interface TaskAgent<TInput, TOutput> extends TaskAgentReference {
+    readonly input: z.ZodType<TInput>;
+    readonly result: z.ZodType<TOutput>;
+}
+export interface CollectionContext {
+    readonly signal: AbortSignal;
+    run<TInput, TOutput>(agent: TaskAgent<TInput, TOutput>, input: NoInfer<TInput>): Promise<TOutput>;
+}
+export interface Collection<TState> extends Participant<TState> {
+    readonly kind: "collection";
+}
+export interface TaskAgentDefinition<TInput, TOutput> extends Omit<AgentDefinition<TInput, TOutput>, "output" | "capabilities" | "workspace" | "checkpoint"> {
+    input: z.ZodType<TInput>;
+    result: z.ZodType<TOutput>;
+    output: Omit<Extract<NonNullable<AgentDefinition<TInput, TOutput>["output"]>, {
+        schema: unknown;
+    }>, "apply"> | Omit<Extract<NonNullable<AgentDefinition<TInput, TOutput>["output"]>, {
+        raw: true;
+    }>, "apply">;
+}
+export declare function taskAgent<TInput, TOutput>(definition: TaskAgentDefinition<TInput, TOutput>): TaskAgent<TInput, TOutput>;
+interface CollectionDefinition<TState, TItem, TResult> {
+    id: string;
+    item: z.ZodType<TItem>;
+    result: z.ZodType<TResult>;
+    items: (state: TState) => readonly TItem[];
+    agents: readonly TaskAgentReference[];
+    execute: (item: TItem, context: CollectionContext) => Promise<TResult> | TResult;
+    apply: (state: TState, results: readonly TResult[]) => TState;
+    max: number;
+    persist?: boolean;
+}
+export declare function collection<TState, TItem, TResult>(definition: CollectionDefinition<TState, TItem, TResult>): Collection<TState>;
 export declare function interaction<TState, TRequest, TResponse>(definition: {
     id: string;
     requestSchema: z.ZodType<TRequest>;
@@ -221,7 +259,7 @@ export declare function output<TState>(definition: {
     persist?: boolean;
 }): Terminal<TState>;
 export interface OrdinaryRoute<TState> {
-    readonly from: Stage<TState> | Interaction<TState, unknown, unknown>;
+    readonly from: Stage<TState> | Collection<TState> | Interaction<TState, unknown, unknown>;
     readonly to: Node<TState>;
     readonly label: string;
     readonly outcome?: never;
@@ -275,7 +313,8 @@ export interface InspectedRoute {
 }
 export interface InspectedNode {
     readonly id: string;
-    readonly kind: "stage" | "interaction" | "agent" | "parallel" | "completion" | "failure";
+    readonly kind: "stage" | "interaction" | "agent" | "parallel" | "collection" | "completion" | "failure";
+    readonly agents?: readonly string[];
     readonly persist?: boolean;
     readonly interaction?: {
         readonly requestSchema: unknown;
@@ -304,6 +343,8 @@ export interface RunResult<TState> {
     readonly summary: string | null;
 }
 export type RunObservation = {
+    readonly visitId?: string | null;
+} & ({
     readonly version: 1;
     readonly kind: "stepStarted";
     readonly stepId: string;
@@ -354,7 +395,7 @@ export type RunObservation = {
         readonly message: string;
     }[];
     readonly rawResponse: string;
-};
+});
 export interface TerminalPresentationOptions {
     readonly truncatedToolNames?: readonly string[];
 }
@@ -377,6 +418,7 @@ export type AcceptedValue = {
         readonly version: 1;
         readonly kind: K;
         readonly stepId: string;
+        readonly visitId?: string | null;
         readonly valueType: string | null;
         readonly payload: unknown | null;
     };

package/dist/index.js

@@ -332,6 +332,55 @@ class StageImplementation extends NodeImplementation {
 export function stage(definition) {
     return new StageImplementation(definition.id, definition.persist, definition.execute);
 }
+const taskAgentBrand = Symbol("taskAgent");
+class TaskAgentImplementation {
+    id;
+    input;
+    result;
+    [taskAgentBrand] = true;
+    state;
+    participant;
+    constructor(id, input, result, definition) {
+        this.id = id;
+        this.input = input;
+        this.result = result;
+        this.state = z.object({ input, output: z.object({ value: result }).nullable() });
+        this.participant = agent({
+            ...definition,
+            message: (state) => definition.message(state.input),
+            output: {
+                ...definition.output,
+                validateFor: definition.output.validateFor
+                    ? (state, value) => definition.output.validateFor(state.input, value)
+                    : undefined,
+                apply: (state, value) => ({
+                    ...state,
+                    output: { value },
+                }),
+            },
+        });
+    }
+}
+export function taskAgent(definition) {
+    return new TaskAgentImplementation(definition.id, definition.input, definition.result, definition);
+}
+class CollectionImplementation extends NodeImplementation {
+    definition;
+    kind = "collection";
+    constructor(definition) {
+        super(definition.id, definition.persist);
+        this.definition = definition;
+    }
+}
+export function collection(definition) {
+    if (!Number.isInteger(definition.max) || definition.max < 1 || definition.max > 2147483647) {
+        throw new TandemError("Collection max must be a positive 32-bit integer.");
+    }
+    if (new Set(definition.agents.map((agent) => agent.id)).size !== definition.agents.length) {
+        throw new TandemError("Collection agent IDs must be unique.");
+    }
+    return new CollectionImplementation(definition);
+}
 class InteractionImplementation extends NodeImplementation {
     requestSchema;
     responseSchema;
@@ -823,6 +872,15 @@ export function inspectPipeline(graph) {
     const inspectNode = (node) => {
         const implementation = node;
         const persist = implementation.persist;
+        if (implementation instanceof CollectionImplementation) {
+            return {
+                id: node.id,
+                kind: "collection",
+                persist,
+                max: implementation.definition.max,
+                agents: implementation.definition.agents.map((agent) => node.id + "/" + agent.id),
+            };
+        }
         if (node.kind === "interaction") {
             const interaction = implementation;
             return {
@@ -892,19 +950,35 @@ export function inspectPipeline(graph) {
 }
 const runObservationSchema = z.discriminatedUnion("kind", [
     z
-        .object({ version: z.literal(1), kind: z.literal("stepStarted"), stepId: z.string().min(1) })
+        .object({
+        version: z.literal(1),
+        kind: z.literal("stepStarted"),
+        stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
+    })
         .strict(),
     z
-        .object({ version: z.literal(1), kind: z.literal("stepCompleted"), stepId: z.string().min(1) })
+        .object({
+        version: z.literal(1),
+        kind: z.literal("stepCompleted"),
+        stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
+    })
         .strict(),
     z
-        .object({ version: z.literal(1), kind: z.literal("stepCancelled"), stepId: z.string().min(1) })
+        .object({
+        version: z.literal(1),
+        kind: z.literal("stepCancelled"),
+        stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
+    })
         .strict(),
     z
         .object({
         version: z.literal(1),
         kind: z.literal("stepFaulted"),
         stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
         error: z.string(),
     })
         .strict(),
@@ -913,6 +987,7 @@ const runObservationSchema = z.discriminatedUnion("kind", [
         version: z.literal(1),
         kind: z.literal("agentText"),
         stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
         text: z.string(),
     })
         .strict(),
@@ -921,6 +996,7 @@ const runObservationSchema = z.discriminatedUnion("kind", [
         version: z.literal(1),
         kind: z.literal("agentModelSelected"),
         stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
         modelId: z.string().min(1),
     })
         .strict(),
@@ -929,6 +1005,7 @@ const runObservationSchema = z.discriminatedUnion("kind", [
         version: z.literal(1),
         kind: z.literal("agentReasoning"),
         stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
         text: z.string(),
     })
         .strict(),
@@ -937,6 +1014,7 @@ const runObservationSchema = z.discriminatedUnion("kind", [
         version: z.literal(1),
         kind: z.literal("agentUsage"),
         stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
         inputTokens: z.number().int().nonnegative(),
         outputTokens: z.number().int().nonnegative(),
         reasoningTokens: z.number().int().nonnegative(),
@@ -949,6 +1027,7 @@ const runObservationSchema = z.discriminatedUnion("kind", [
         version: z.literal(1),
         kind: z.literal("structuredOutputRejected"),
         stepId: z.string().min(1),
+        visitId: z.string().nullable().optional(),
         attempt: z.number().int().positive(),
         problems: z.array(z.object({ field: z.string(), message: z.string().min(1) }).strict()),
         rawResponse: z.string(),
@@ -965,6 +1044,7 @@ const acceptedKinds = [
 const acceptedValueSchema = z
     .object({
     kind: z.enum(acceptedKinds),
+    visitId: z.string().nullable().optional(),
     stepId: z.string().min(1),
     valueType: z.string().min(1).nullable(),
     payload: z.unknown().nullable(),
@@ -989,6 +1069,7 @@ export async function inspectAccepted(options) {
             version: 1,
             kind: value.kind,
             stepId: value.stepId,
+            ...(value.visitId == null ? {} : { visitId: value.visitId }),
             valueType: value.valueType,
             payload: value.payload,
         }));
@@ -1137,6 +1218,64 @@ function interactionHandlerEntries(handlers) {
 function compileNode(node, stateSchema, callbacks) {
     const implementation = node;
     const base = { id: node.id, persist: implementation.persist };
+    if (implementation instanceof CollectionImplementation) {
+        const definition = implementation.definition;
+        const agents = definition.agents.map((value) => {
+            if (!(value instanceof TaskAgentImplementation))
+                throw new TandemError("Use taskAgent to declare collection agents.");
+            return compileNode(value.participant, value.state, callbacks);
+        });
+        const itemsCallback = callbacks.registerSync((state) => serializeBoundary(z.array(definition.item), definition.items(parseJson(stateSchema, state, node.id + " state")), node.id + " items"));
+        const runCallback = callbacks.registerAsync(async (item, scopeId, signal) => {
+            let active = false;
+            let closed = false;
+            const context = {
+                signal,
+                async run(value, input) {
+                    if (closed)
+                        throw new TandemError("Collection scope has ended.");
+                    if (active)
+                        throw new TandemError("Collection item agents must be awaited serially.");
+                    if (!definition.agents.includes(value) || !(value instanceof TaskAgentImplementation)) {
+                        throw new TandemError("Agent is not declared in this collection.");
+                    }
+                    signal.throwIfAborted();
+                    active = true;
+                    try {
+                        const { runCollectionAgentAsync } = await import("./runtime/loader.mjs");
+                        const response = await runCollectionAgentAsync(scopeId, value.id, serializeBoundary(value.state, { input, output: null }, value.id + " input"));
+                        const state = parseJson(value.state, response, value.id + " output");
+                        if (state.output === null)
+                            throw new TandemError("Agent returned no output.");
+                        return parse(value.result, state.output.value, value.id + " result");
+                    }
+                    finally {
+                        active = false;
+                    }
+                },
+            };
+            try {
+                const result = await definition.execute(parseJson(definition.item, item, node.id + " item"), context);
+                if (active)
+                    throw new TandemError("Collection item returned before its agent completed.");
+                signal.throwIfAborted();
+                return serializeBoundary(definition.result, result, node.id + " result");
+            }
+            finally {
+                closed = true;
+            }
+        });
+        const applyCallback = callbacks.registerSync((state, results) => serializeBoundary(stateSchema, definition.apply(parseJson(stateSchema, state, node.id + " state"), parseJson(z.array(definition.result), results, node.id + " results")), node.id + " output"));
+        return {
+            ...base,
+            kind: "collection",
+            agents,
+            max: definition.max,
+            itemsCallback,
+            runCallback,
+            applyCallback,
+        };
+    }
     if (implementation instanceof StageImplementation) {
         const run = callbacks.registerAsync(async (state, _, signal) => serializeBoundary(stateSchema, await implementation.execute(parseJson(stateSchema, state, `${node.id} input`), {
             signal,
@@ -1326,13 +1465,9 @@ function compileAgentOutput(id, output, stateSchema, callbacks) {
         ? callbacks.registerSync((_, input) => issuesParsed(z.unknown(), output.parse(JSON.parse(input))))
         : callbacks.registerSync((_, input) => issues(output.schema, input));
     const validateFor = output.validateFor
-        ? callbacks.registerSync((state, input) => validationProblems(output.validateFor(parseJson(stateSchema, state, `${id} state`), raw
-            ? JSON.parse(input)
-            : parseJson(output.schema, input, `${id} output`)), `${id} output contextual validation`))
+        ? callbacks.registerSync((state, input) => validationProblems(output.validateFor(parseJson(stateSchema, state, `${id} state`), raw ? JSON.parse(input) : parseJson(output.schema, input, `${id} output`)), `${id} output contextual validation`))
         : undefined;
-    const apply = callbacks.registerSync((state, input) => serializeBoundary(stateSchema, output.apply(parseJson(stateSchema, state, `${id} state`), raw
-        ? JSON.parse(input)
-        : parseJson(output.schema, input, `${id} output`)), `${id} applied state`));
+    const apply = callbacks.registerSync((state, input) => serializeBoundary(stateSchema, output.apply(parseJson(stateSchema, state, `${id} state`), raw ? JSON.parse(input) : parseJson(output.schema, input, `${id} output`)), `${id} applied state`));
     return {
         instructions: output.instructions,
         ...(raw

package/dist/runtime/{Tandem.NodeApiSpike.Bridge.d.ts → darwin-arm64/Tandem.NodeApiSpike.Bridge.d.ts}

@@ -7,6 +7,13 @@ import './System.Runtime';
 
 /** Adapts JavaScript-authored participants to the Tandem runtime. */
 export namespace NodePipelineBridge {
+	/** Executes a declared agent within an active collection item. */
+	export function runCollectionAgentAsync(
+		scopeId: string,
+		agentId: string,
+		state: string,
+	): Promise<string>;
+
 	/** Reads accepted semantic journal values from a packaged SQLite ledger. */
 	export function inspectAcceptedAsync(
 		ledgerPath: string,

package/dist/runtime/linux-x64/Tandem.NodeApiSpike.Bridge.cjs

@@ -0,0 +1,26 @@
+// Generated for: Tandem.NodeApiSpike.Bridge 0.1.0.0
+// Generated by: Microsoft.JavaScript.NodeApi.Generator 0.9.0.0
+/* eslint-disable */
+
+const dotnet = require('node-api-dotnet/net10.0');
+const path = require('node:path');
+// @ts-ignore - https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/65252
+const { dlopen, platform, arch } = require('node:process');
+
+const moduleName = path.basename(__filename, __filename.match(/(\.[cm]?js)?$/)[0]);
+module.exports = dotnet ? importDotnetModule(moduleName) : importAotModule(moduleName);
+
+function importDotnetModule(moduleName) {
+	const moduleFilePath = path.join(__dirname, moduleName + '.dll');
+	return dotnet.require(moduleFilePath);
+}
+
+function importAotModule(moduleName) {
+	const ridPlatform = platform === 'win32' ? 'win' : platform === 'darwin' ? 'osx' : platform;
+	const ridArch = arch === 'ia32' ? 'x86' : arch;
+	const rid = `${ridPlatform}-${ridArch}`;
+	const moduleFilePath = path.join(__dirname, rid, moduleName + '.node');
+	const module = { exports: {} };
+	dlopen(module, moduleFilePath);
+	return module.exports;
+}

package/dist/runtime/linux-x64/Tandem.NodeApiSpike.Bridge.d.ts

@@ -0,0 +1,30 @@
+// Generated for: Tandem.NodeApiSpike.Bridge 0.1.0.0
+// Generated by: Microsoft.JavaScript.NodeApi.Generator 0.9.0.0
+/* eslint-disable */
+
+import './System.Runtime';
+
+
+/** Adapts JavaScript-authored participants to the Tandem runtime. */
+export namespace NodePipelineBridge {
+	/** Executes a declared agent within an active collection item. */
+	export function runCollectionAgentAsync(
+		scopeId: string,
+		agentId: string,
+		state: string,
+	): Promise<string>;
+
+	/** Reads accepted semantic journal values from a packaged SQLite ledger. */
+	export function inspectAcceptedAsync(
+		ledgerPath: string,
+		runId: string,
+	): Promise<string>;
+
+	/** Registers and runs a complete JavaScript-authored Tandem graph. */
+	export function runRegisteredGraphAsync(
+		definitionJson: string,
+		invokeSyncCallback: Func$4<string, string, string, string>,
+		invokeAsyncCallback: Func$5<string, string, string, AbortSignal, Promise<string>>,
+		cancellationToken?: AbortSignal,
+	): Promise<string>;
+}