@maxanstey-meridian/tandem 0.1.0-alpha.1 → 0.1.2

package/dist/index.d.ts

@@ -104,6 +104,10 @@ export interface OpenAiCompatibleChatClient {
     readonly wireApi: "completions" | "responses";
     readonly apiKeyEnvironmentVariable?: string;
     readonly verifyModel?: boolean;
+    /** Per-attempt transport limits; omitted preserves provider defaults. */
+    readonly requestTimeoutMs?: number;
+    readonly idleTimeoutMs?: number;
+    readonly maxAttempts?: number;
 }
 export type ChatClient = OpenAiCompatibleChatClient;
 export type AgentReasoning = {
@@ -117,24 +121,11 @@ export interface AgentSkill {
     readonly directory: string;
 }
 export type AgentToolName = "read_file" | "ls" | "grep" | "write_file" | "delete_file" | "replace" | "replace_lines" | "git:ro" | "shell" | "web_search" | "web_fetch";
-interface AgentCommandArgumentBase {
-    readonly name: string;
-    readonly description: string;
-    readonly flag: string;
-    readonly maxLength?: number;
-}
-export type AgentCommandArgument = AgentCommandArgumentBase & ({
-    readonly pattern: string;
-    readonly allowedValues?: never;
-} | {
-    readonly allowedValues: readonly string[];
-    readonly pattern?: never;
-});
 export interface AgentCommand {
     readonly name: string;
     readonly description: string;
     readonly command: string;
-    readonly arguments?: readonly AgentCommandArgument[];
+    readonly arguments?: readonly string[];
 }
 interface AgentCommandSelection {
     readonly [commandSelectionBrand]: object;
@@ -182,6 +173,12 @@ export interface AgentDefinition<TState, TOutput = never> {
         readonly schema: z.ZodType<TOutput>;
         readonly validateFor?: (state: TState, output: TOutput) => readonly ValidationProblem[];
         readonly apply: (state: TState, output: TOutput) => TState;
+    } | {
+        readonly instructions: string;
+        readonly raw: true;
+        readonly parse: (response: string) => TOutput;
+        readonly validateFor?: (state: TState, output: TOutput) => readonly ValidationProblem[];
+        readonly apply: (state: TState, output: TOutput) => TState;
     };
     readonly capabilities?: readonly Capability<TState>[];
     readonly skills?: readonly AgentSkill[];
@@ -211,6 +208,8 @@ type ParallelDefinition<TState, TBranches extends ParallelBranches<TState>> = {
     readonly merge: (baseline: TState, results: {
         readonly [K in keyof TBranches]: TState;
     }) => TState;
+    /** Maximum active branches per invocation; omitted means all branches. */
+    readonly max?: number;
     readonly persist?: boolean;
 };
 export declare function parallel<TState>(): <const TBranches extends ParallelBranches<TState>>(definition: ParallelDefinition<TState, TBranches>) => Parallel<TState>;
@@ -256,6 +255,48 @@ export declare function pipeline<TState>(definition: {
     outputs: readonly Terminal<NoInfer<TState>>[];
     persist?: boolean;
 }): Pipeline<TState>;
+export interface PipelineInspection {
+    readonly name: string;
+    readonly stateSchema: unknown;
+    readonly start: string;
+    readonly persist: boolean;
+    readonly nodes: readonly InspectedNode[];
+    readonly routes: readonly InspectedRoute[];
+    readonly outputs: readonly string[];
+}
+export interface InspectedRoute {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly label: string;
+    readonly order: number;
+    readonly outcome?: "success" | "failed";
+    readonly conditional: boolean;
+}
+export interface InspectedNode {
+    readonly id: string;
+    readonly kind: "stage" | "interaction" | "agent" | "parallel" | "completion" | "failure";
+    readonly persist?: boolean;
+    readonly interaction?: {
+        readonly requestSchema: unknown;
+        readonly responseSchema: unknown;
+    };
+    readonly agent?: {
+        readonly capabilities: readonly {
+            readonly name: string;
+            readonly requestSchema: unknown;
+        }[];
+        readonly outputSchema?: unknown;
+        readonly workspace: boolean;
+    };
+    readonly max?: number;
+    readonly branches?: readonly {
+        readonly id: string;
+        readonly participant: InspectedNode;
+    }[];
+}
+/** Projects an instantiated pipeline without compiling, registering, or invoking callbacks. */
+export declare function inspectPipeline<TState>(graph: Pipeline<TState>): PipelineInspection;
 export interface RunResult<TState> {
     readonly runId: string;
     readonly succeeded: boolean;
@@ -319,6 +360,8 @@ export interface TerminalPresentationOptions {
 }
 export interface RunOptions {
     readonly ledgerPath?: string;
+    /** Expose ledger read/search tools to agents. Disabled by default; does not affect logging. */
+    readonly enableLedgerTools?: boolean;
     readonly signal?: AbortSignal;
     readonly interactions?: InteractionHandlers;
     readonly presentation?: "terminal";

package/dist/index.js

@@ -494,9 +494,7 @@ function copyAgentCommand(command) {
         ? { ...command }
         : {
             ...command,
-            arguments: command.arguments.map((argument) => argument.pattern !== undefined
-                ? { ...argument }
-                : { ...argument, allowedValues: [...argument.allowedValues] }),
+            arguments: [...command.arguments],
         };
 }
 function validateAgentCommands(commands, context) {
@@ -519,65 +517,22 @@ function validateAgentCommands(commands, context) {
             throw new TandemError(`${commandContext}.command must be non-blank.`);
         }
         if (candidate.arguments !== undefined && !Array.isArray(candidate.arguments)) {
-            throw new TandemError(`${commandContext}.arguments must be an array.`);
+            throw new TandemError(`${commandContext}.arguments must be an array of strings.`);
         }
-        const argumentNames = new Set();
-        for (const [argumentIndex, argument] of (candidate.arguments ?? []).entries()) {
+        const argumentList = candidate.arguments ?? [];
+        if (argumentList.length > 16) {
+            throw new TandemError(`${commandContext}.arguments accepts at most 16 arguments.`);
+        }
+        for (const [argumentIndex, argument] of argumentList.entries()) {
             const argumentContext = `${commandContext}.arguments[${argumentIndex}]`;
-            if (typeof argument !== "object" || argument === null) {
-                throw new TandemError(`${argumentContext} must be an argument.`);
-            }
-            const candidateArgument = argument;
-            if (typeof candidateArgument.name !== "string" ||
-                !/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidateArgument.name)) {
-                throw new TandemError(`${argumentContext}.name must be a valid JSON property identifier.`);
-            }
-            if (argumentNames.has(candidateArgument.name)) {
-                throw new TandemError(`${argumentContext}.name duplicates '${candidateArgument.name}'.`);
-            }
-            argumentNames.add(candidateArgument.name);
-            if (typeof candidateArgument.description !== "string" ||
-                candidateArgument.description.trim().length === 0) {
-                throw new TandemError(`${argumentContext}.description must be non-blank.`);
-            }
-            if (typeof candidateArgument.flag !== "string" ||
-                candidateArgument.flag.trim().length === 0 ||
-                /\s/.test(candidateArgument.flag)) {
-                throw new TandemError(`${argumentContext}.flag must be a whitespace-free switch token.`);
+            if (typeof argument !== "string") {
+                throw new TandemError(`${argumentContext} must be a string.`);
             }
-            if (candidateArgument.pattern !== undefined &&
-                typeof candidateArgument.pattern !== "string") {
-                throw new TandemError(`${argumentContext}.pattern must be a string.`);
+            if (argument.trim().length === 0) {
+                throw new TandemError(`${argumentContext} must not be blank.`);
             }
-            if (candidateArgument.allowedValues !== undefined &&
-                !Array.isArray(candidateArgument.allowedValues)) {
-                throw new TandemError(`${argumentContext}.allowedValues must be an array.`);
-            }
-            const hasPattern = typeof candidateArgument.pattern === "string";
-            const hasAllowedValues = Array.isArray(candidateArgument.allowedValues);
-            if (hasPattern === hasAllowedValues) {
-                throw new TandemError(`${argumentContext} requires exactly one of pattern or allowedValues.`);
-            }
-            if (candidateArgument.maxLength !== undefined &&
-                (!Number.isSafeInteger(candidateArgument.maxLength) ||
-                    candidateArgument.maxLength <= 0 ||
-                    candidateArgument.maxLength > 2_147_483_647)) {
-                throw new TandemError(`${argumentContext}.maxLength must be a positive integer.`);
-            }
-            if (candidateArgument.allowedValues !== undefined) {
-                if (candidateArgument.allowedValues.length === 0) {
-                    throw new TandemError(`${argumentContext}.allowedValues must not be empty.`);
-                }
-                const values = new Set();
-                for (const value of candidateArgument.allowedValues) {
-                    if (typeof value !== "string" || value.trim().length === 0) {
-                        throw new TandemError(`${argumentContext}.allowedValues must be non-blank strings.`);
-                    }
-                    if (values.has(value)) {
-                        throw new TandemError(`${argumentContext}.allowedValues duplicates '${value}'.`);
-                    }
-                    values.add(value);
-                }
+            if (argument.length > 200) {
+                throw new TandemError(`${argumentContext} must be at most 200 characters.`);
             }
         }
     }
@@ -641,6 +596,20 @@ export function agent(definition) {
     }
     if (definition.output) {
         requireInstructions(definition.output.instructions, `Agent '${definition.id}' output instructions`);
+        if ("raw" in definition.output) {
+            if (definition.output.raw !== true) {
+                throw new TandemError(`Agent '${definition.id}' output raw must be true.`);
+            }
+            if ("schema" in definition.output) {
+                throw new TandemError(`Agent '${definition.id}' output schema is forbidden for raw output.`);
+            }
+            if (typeof definition.output.parse !== "function") {
+                throw new TandemError(`Agent '${definition.id}' raw output requires a parse function.`);
+            }
+        }
+        else if ("parse" in definition.output) {
+            throw new TandemError(`Agent '${definition.id}' output parse requires raw output mode.`);
+        }
     }
     const capabilities = definition.capabilities ?? [];
     const names = new Set();
@@ -710,11 +679,13 @@ export function agent(definition) {
 }
 class ParallelImplementation extends NodeImplementation {
     branches;
+    max;
     merge;
     kind = "parallel";
-    constructor(id, persist, branches, merge) {
+    constructor(id, persist, branches, max, merge) {
         super(id, persist);
         this.branches = branches;
+        this.max = max;
         this.merge = merge;
     }
 }
@@ -725,6 +696,10 @@ export function parallel(definition) {
     return createParallel(definition);
 }
 function createParallel(definition) {
+    if (definition.max !== undefined &&
+        (!Number.isInteger(definition.max) || definition.max < 1 || definition.max > 2147483647)) {
+        throw new TandemError(`Parallel group '${definition.id}' max must be a positive 32-bit integer.`);
+    }
     const entries = Object.entries(definition.branches);
     if (entries.length < 2) {
         throw new TandemError(`Parallel group '${definition.id}' requires at least two branches.`);
@@ -733,7 +708,7 @@ function createParallel(definition) {
     if (participants.size !== entries.length) {
         throw new TandemError(`Parallel group '${definition.id}' must own a distinct participant per branch.`);
     }
-    return new ParallelImplementation(definition.id, definition.persist, definition.branches, definition.merge);
+    return new ParallelImplementation(definition.id, definition.persist, definition.branches, definition.max, definition.merge);
 }
 class TerminalImplementation extends NodeImplementation {
     failed;
@@ -838,6 +813,78 @@ export function pipeline(definition) {
     }
     return { ...definition, persist: definition.persist ?? false };
 }
+/** Projects an instantiated pipeline without compiling, registering, or invoking callbacks. */
+export function inspectPipeline(graph) {
+    const inspectNode = (node) => {
+        const implementation = node;
+        const persist = implementation.persist;
+        if (node.kind === "interaction") {
+            const interaction = implementation;
+            return {
+                id: node.id,
+                kind: "interaction",
+                persist,
+                interaction: {
+                    requestSchema: z.toJSONSchema(interaction.requestSchema, { io: "input" }),
+                    responseSchema: z.toJSONSchema(interaction.responseSchema, { io: "input" }),
+                },
+            };
+        }
+        if (node.kind === "agent") {
+            const agent = implementation;
+            return {
+                id: node.id,
+                kind: "agent",
+                persist,
+                agent: {
+                    capabilities: agent.granted.map((item) => ({
+                        name: item.name,
+                        requestSchema: JSON.parse(item.requestJsonSchema),
+                    })),
+                    ...(!agent.output || "raw" in agent.output
+                        ? {}
+                        : { outputSchema: z.toJSONSchema(agent.output.schema, { io: "input" }) }),
+                    workspace: agent.workspace !== undefined,
+                },
+            };
+        }
+        if (node.kind === "parallel") {
+            const parallel = implementation;
+            return {
+                id: node.id,
+                kind: "parallel",
+                persist,
+                ...(parallel.max !== undefined ? { max: parallel.max } : {}),
+                branches: Object.entries(parallel.branches).map(([id, participant]) => ({
+                    id,
+                    participant: inspectNode(participant),
+                })),
+            };
+        }
+        if (node.kind === "terminal") {
+            const terminal = implementation;
+            return { id: node.id, kind: terminal.failed ? "failure" : "completion", persist };
+        }
+        return { id: node.id, kind: "stage", persist };
+    };
+    return {
+        name: graph.name,
+        stateSchema: z.toJSONSchema(graph.state, { io: "input" }),
+        start: graph.start.id,
+        persist: graph.persist,
+        nodes: graph.nodes.map(inspectNode),
+        routes: graph.routes.map((item, order) => ({
+            id: `route:${order}`,
+            source: item.from.id,
+            target: item.to.id,
+            label: item.label,
+            order,
+            ...(item.outcome === undefined ? {} : { outcome: item.outcome }),
+            conditional: item.when !== undefined,
+        })),
+        outputs: graph.outputs.map((item) => item.id),
+    };
+}
 const runObservationSchema = z.discriminatedUnion("kind", [
     z
         .object({ version: z.literal(1), kind: z.literal("stepStarted"), stepId: z.string().min(1) })
@@ -932,7 +979,7 @@ const runResultSchema = z
     .strict();
 export async function inspectAccepted(options) {
     try {
-        const { inspectAcceptedAsync } = await import("@maxanstey-meridian/tandem-runtime");
+        const { inspectAcceptedAsync } = await import("./runtime/loader.mjs");
         return parseJson(acceptedValuesSchema, await inspectAcceptedAsync(options.ledgerPath, options.runId), "accepted values").map((value) => ({
             version: 1,
             kind: value.kind,
@@ -994,7 +1041,7 @@ export async function run(graph, initial, options = {}) {
                 return "";
             })
             : undefined;
-        const { runRegisteredGraphAsync } = await import("@maxanstey-meridian/tandem-runtime");
+        const { runRegisteredGraphAsync } = await import("./runtime/loader.mjs");
         const resultJson = await runRegisteredGraphAsync(JSON.stringify({
             contractVersion: 10,
             name: graph.name,
@@ -1002,6 +1049,7 @@ export async function run(graph, initial, options = {}) {
             initialState,
             persist: graph.persist,
             ledgerPath: options.ledgerPath,
+            enableLedgerTools: options.enableLedgerTools ?? false,
             presentation: options.presentation,
             terminal: options.terminal,
             observationCallback,
@@ -1047,6 +1095,9 @@ function issues(schema, input) {
     catch {
         return JSON.stringify([{ path: "$", message: "Invalid JSON" }]);
     }
+    return issuesParsed(schema, value);
+}
+function issuesParsed(schema, value) {
     try {
         parse(schema, value, "agent contract");
         return "";
@@ -1169,6 +1220,7 @@ function compileNode(node, stateSchema, callbacks) {
         return {
             ...base,
             kind: "parallel",
+            ...(implementation.max !== undefined ? { max: implementation.max } : {}),
             branches: entries.map(([id, participant]) => ({
                 id,
                 participant: compileNode(participant, stateSchema, callbacks),
@@ -1203,18 +1255,7 @@ function compileWorkspace(id, configuration, stateSchema, callbacks) {
             name: z.string(),
             description: z.string(),
             command: z.string(),
-            arguments: z
-                .array(z
-                .object({
-                name: z.string(),
-                description: z.string(),
-                flag: z.string(),
-                pattern: z.string().optional(),
-                allowedValues: z.array(z.string()).optional(),
-                maxLength: z.number().optional(),
-            })
-                .strict())
-                .optional(),
+            arguments: z.array(z.string()).optional(),
         })
             .strict()), value, `${id} workspace commands`);
     });
@@ -1275,15 +1316,29 @@ function compileWorkspace(id, configuration, stateSchema, callbacks) {
     return { pathCallback, commandsCallback, toolGroups, interceptCallback };
 }
 function compileAgentOutput(id, output, stateSchema, callbacks) {
-    const validate = callbacks.registerSync((_, input) => issues(output.schema, input));
+    const raw = output.raw === true;
+    const validate = raw
+        ? 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`), 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`), 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,
-        jsonSchema: inputJsonSchema(output.schema, `${id} output schema`),
-        validateCallback: validate,
+        ...(raw
+            ? {
+                raw: true,
+                rawParseCallback: callbacks.registerSync((_, input) => JSON.stringify(output.parse(input))),
+            }
+            : {
+                jsonSchema: inputJsonSchema(output.schema, `${id} output schema`),
+                validateCallback: validate,
+            }),
         validateForCallback: validateFor,
         applyCallback: apply,
         valueType: `${id}.output`,

package/dist/runtime/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/Tandem.NodeApiSpike.Bridge.d.ts

@@ -0,0 +1,23 @@
+// 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 {
+	/** 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>;
+}