@maxanstey-meridian/tandem 0.1.0-alpha.1

package/dist/index.js

@@ -0,0 +1,1291 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+const participantBrand = Symbol("participant");
+const compileCapabilityBrand = Symbol("compileCapability");
+const interactionHandlersBrand = Symbol("interactionHandlers");
+const workspaceBrand = Symbol("workspace");
+const toolGroupBrand = Symbol("toolGroup");
+const commandSelectionBrand = Symbol("commandSelection");
+export class TandemError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TandemError";
+    }
+}
+export class TandemRuntimeError extends TandemError {
+    operation;
+    constructor(operation, cause) {
+        super(`Tandem ${operation} failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+            cause,
+        });
+        this.operation = operation;
+        this.name = "TandemRuntimeError";
+    }
+}
+export class TandemCancellationError extends TandemRuntimeError {
+    constructor(cause) {
+        super("run", cause);
+        this.name = "AbortError";
+    }
+}
+export class ContractValidationError extends TandemError {
+    boundary;
+    problems;
+    constructor(boundary, problems) {
+        super(`${boundary} validation failed: ${problems.map((p) => `${p.path}: ${p.message}`).join("; ")}`);
+        this.boundary = boundary;
+        this.name = "ContractValidationError";
+        this.problems = problems;
+    }
+}
+function callbackError(error) {
+    return error instanceof ContractValidationError
+        ? {
+            name: error.name,
+            message: error.message,
+            boundary: error.boundary,
+            problems: error.problems,
+        }
+        : {
+            name: error instanceof Error ? error.name : "Error",
+            message: error instanceof Error ? error.message : String(error),
+        };
+}
+class CallbackRegistry {
+    #sync = new Map();
+    #async = new Map();
+    #next = 0;
+    #disposed = false;
+    registerSync(callback) {
+        const id = this.#allocate();
+        this.#sync.set(id, callback);
+        return id;
+    }
+    registerAsync(callback) {
+        const id = this.#allocate();
+        this.#async.set(id, callback);
+        return id;
+    }
+    invokeSync(id, state, input) {
+        try {
+            const callback = this.#sync.get(id);
+            if (!callback) {
+                throw new Error(`Unknown internal callback '${id}'.`);
+            }
+            return JSON.stringify({
+                succeeded: true,
+                value: callback(state, input),
+            });
+        }
+        catch (error) {
+            return JSON.stringify({
+                succeeded: false,
+                error: callbackError(error),
+            });
+        }
+    }
+    async invokeAsync(id, state, input, signal) {
+        try {
+            const callback = this.#async.get(id);
+            if (!callback) {
+                throw new Error(`Unknown internal async callback '${id}'.`);
+            }
+            return JSON.stringify({
+                succeeded: true,
+                value: await callback(state, input, signal),
+            });
+        }
+        catch (error) {
+            return JSON.stringify({
+                succeeded: false,
+                error: callbackError(error),
+            });
+        }
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#sync.clear();
+        this.#async.clear();
+    }
+    #allocate() {
+        if (this.#disposed) {
+            throw new Error("Callback registry has been disposed.");
+        }
+        return `c${this.#next++}`;
+    }
+}
+function callbackContractFailure(error) {
+    const marker = "TANDEM_CALLBACK_CONTRACT:";
+    const message = error instanceof Error ? error.message : String(error);
+    const start = message.indexOf(marker);
+    if (start < 0) {
+        return null;
+    }
+    try {
+        return JSON.parse(message.slice(start + marker.length));
+    }
+    catch {
+        return null;
+    }
+}
+function isCancellationError(error, signalAborted) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if (error.message.includes("JavaScript callback failed:") && !signalAborted) {
+        return false;
+    }
+    return (error.name === "AbortError" ||
+        /\b(?:operation was cancel(?:l)?ed|operation was aborted|this operation was aborted)\b/i.test(error.message));
+}
+function path(parts) {
+    return parts.length === 0
+        ? "$"
+        : `$${parts.map((part) => (typeof part === "number" ? `[${part}]` : `.${String(part)}`)).join("")}`;
+}
+function parseValidated(schema, value, boundary) {
+    let result;
+    try {
+        result = schema.safeParse(value);
+    }
+    catch (error) {
+        if (error instanceof Error && /async/i.test(error.message)) {
+            throw new ContractValidationError(boundary, [
+                {
+                    path: "$",
+                    message: "Async Zod refinements are unsupported; Tandem contracts must validate synchronously.",
+                },
+            ]);
+        }
+        throw error;
+    }
+    if (!result.success) {
+        throw new ContractValidationError(boundary, result.error.issues.map((issue) => ({ path: path(issue.path), message: issue.message })));
+    }
+    return result.data;
+}
+function parse(schema, value, boundary) {
+    const result = parseValidated(schema, value, boundary);
+    if (!isDeepStrictEqual(result, value)) {
+        throw new ContractValidationError(boundary, [
+            {
+                path: "$",
+                message: "Zod contract changed the boundary value. Coercion, defaults, transforms, and stripping are unsupported.",
+            },
+        ]);
+    }
+    return result;
+}
+function serializeBoundary(schema, value, boundary) {
+    const parsed = parse(schema, value, boundary);
+    const problem = jsonValueProblem(parsed, "$", new WeakSet());
+    if (problem) {
+        throw new ContractValidationError(boundary, [problem]);
+    }
+    let json;
+    try {
+        json = JSON.stringify(parsed);
+    }
+    catch (error) {
+        throw new ContractValidationError(boundary, [
+            {
+                path: "$",
+                message: `Value is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        ]);
+    }
+    if (json === undefined) {
+        throw new ContractValidationError(boundary, [
+            { path: "$", message: "Top-level undefined is not JSON-serializable." },
+        ]);
+    }
+    const roundTripped = JSON.parse(json);
+    if (!isDeepStrictEqual(roundTripped, parsed)) {
+        throw new ContractValidationError(boundary, [
+            { path: "$", message: "Value is not losslessly JSON-serializable." },
+        ]);
+    }
+    return json;
+}
+function jsonValueProblem(value, valuePath, seen) {
+    if (value === undefined) {
+        return { path: valuePath, message: "undefined is not JSON-serializable." };
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        return { path: valuePath, message: "Non-finite numbers are not JSON-serializable." };
+    }
+    if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function") {
+        return { path: valuePath, message: `${typeof value} values are not JSON-serializable.` };
+    }
+    if (value === null || typeof value !== "object") {
+        return null;
+    }
+    if (seen.has(value)) {
+        return { path: valuePath, message: "Cyclic values are not JSON-serializable." };
+    }
+    seen.add(value);
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        return { path: valuePath, message: "Symbol properties are not JSON-serializable." };
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, index);
+            if (!descriptor) {
+                return {
+                    path: `${valuePath}[${index}]`,
+                    message: "Sparse arrays are not JSON-serializable.",
+                };
+            }
+            if (!("value" in descriptor)) {
+                return {
+                    path: `${valuePath}[${index}]`,
+                    message: "Accessor properties are not supported at JSON boundaries.",
+                };
+            }
+            const problem = jsonValueProblem(descriptor.value, `${valuePath}[${index}]`, seen);
+            if (problem) {
+                return problem;
+            }
+        }
+        const additionalProperty = Object.getOwnPropertyNames(value).find((name) => {
+            if (name === "length") {
+                return false;
+            }
+            const index = Number(name);
+            return (!Number.isInteger(index) || index < 0 || index >= value.length || String(index) !== name);
+        });
+        if (additionalProperty) {
+            return {
+                path: `${valuePath}.${additionalProperty}`,
+                message: "Additional array properties are not JSON-serializable.",
+            };
+        }
+        seen.delete(value);
+        return null;
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        return {
+            path: valuePath,
+            message: "Only plain objects are JSON-serializable boundary values.",
+        };
+    }
+    for (const name of Object.getOwnPropertyNames(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, name);
+        if (!descriptor?.enumerable) {
+            return {
+                path: `${valuePath}.${name}`,
+                message: "Non-enumerable properties are not JSON-serializable.",
+            };
+        }
+        if (!("value" in descriptor)) {
+            return {
+                path: `${valuePath}.${name}`,
+                message: "Accessor properties are not supported at JSON boundaries.",
+            };
+        }
+        const problem = jsonValueProblem(descriptor.value, `${valuePath}.${name}`, seen);
+        if (problem) {
+            return problem;
+        }
+    }
+    seen.delete(value);
+    return null;
+}
+function parseJson(schema, json, boundary) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        throw new ContractValidationError(boundary, [{ path: "$", message: "Invalid JSON" }]);
+    }
+    return parse(schema, value, boundary);
+}
+function inputJsonSchema(schema, boundary) {
+    try {
+        z.toJSONSchema(schema, { io: "output" });
+        return JSON.stringify(z.toJSONSchema(schema, { io: "input" }));
+    }
+    catch (error) {
+        throw new ContractValidationError(boundary, [
+            { path: "$", message: error instanceof Error ? error.message : String(error) },
+        ]);
+    }
+}
+class NodeImplementation {
+    id;
+    persist;
+    [participantBrand];
+    constructor(id, persist) {
+        this.id = id;
+        this.persist = persist;
+    }
+}
+class StageImplementation extends NodeImplementation {
+    execute;
+    kind = "stage";
+    constructor(id, persist, execute) {
+        super(id, persist);
+        this.execute = execute;
+    }
+}
+export function stage(definition) {
+    return new StageImplementation(definition.id, definition.persist, definition.execute);
+}
+class InteractionImplementation extends NodeImplementation {
+    requestSchema;
+    responseSchema;
+    request;
+    apply;
+    kind = "interaction";
+    requestType;
+    responseType;
+    constructor(id, persist, requestSchema, responseSchema, request, apply) {
+        super(id, persist);
+        this.requestSchema = requestSchema;
+        this.responseSchema = responseSchema;
+        this.request = request;
+        this.apply = apply;
+    }
+}
+export function interaction(definition) {
+    return new InteractionImplementation(definition.id, definition.persist, definition.requestSchema, definition.responseSchema, definition.request, definition.apply);
+}
+class InteractionHandlersImplementation {
+    [interactionHandlersBrand] = true;
+    entries = [];
+    #interactions = new Set();
+    handle(interaction, handler) {
+        const opaque = interaction;
+        if (this.#interactions.has(opaque)) {
+            throw new TandemError(`Interaction '${interaction.id}' already has a handler.`);
+        }
+        this.#interactions.add(opaque);
+        this.entries.push({
+            interaction: opaque,
+            handle: handler,
+        });
+        return this;
+    }
+}
+export function interactions() {
+    return new InteractionHandlersImplementation();
+}
+class CapabilityImplementation {
+    name;
+    instructions;
+    schema;
+    validateFor;
+    apply;
+    summarize;
+    requestJsonSchema;
+    constructor(name, instructions, schema, validateFor, apply, summarize) {
+        this.name = name;
+        this.instructions = instructions;
+        this.schema = schema;
+        this.validateFor = validateFor;
+        this.apply = apply;
+        this.summarize = summarize;
+        this.requestJsonSchema = inputJsonSchema(schema, `capability '${name}' schema`);
+    }
+    [compileCapabilityBrand]({ id, stateSchema, callbacks, }) {
+        const validate = callbacks.registerSync((_, input) => issues(this.schema, input));
+        const validateFor = this.validateFor
+            ? callbacks.registerSync((state, input) => validationProblems(this.validateFor(parseJson(stateSchema, state, `${id} state`), parseJson(this.schema, input, `${id} capability '${this.name}' request`)), `${id} capability '${this.name}' contextual validation`))
+            : undefined;
+        const apply = callbacks.registerSync((state, input) => serializeBoundary(stateSchema, this.apply(parseJson(stateSchema, state, `${id} state`), parseJson(this.schema, input, `${id} capability '${this.name}' request`)), `${id} applied state`));
+        const summary = callbacks.registerSync((_, input) => this.summarize(parseJson(this.schema, input, `${id} capability '${this.name}' request`)));
+        return {
+            name: this.name,
+            instructions: this.instructions,
+            jsonSchema: this.requestJsonSchema,
+            validateCallback: validate,
+            validateForCallback: validateFor,
+            applyCallback: apply,
+            summaryCallback: summary,
+            valueType: `${id}.capability.${this.name}`,
+        };
+    }
+}
+export function capability(definition) {
+    requireInstructions(definition.instructions, `Capability '${definition.name}' instructions`);
+    return new CapabilityImplementation(definition.name, definition.instructions, definition.schema, definition.validateFor, definition.apply, definition.summarize);
+}
+class AgentToolGroupImplementation {
+    predicate;
+    tools;
+    [toolGroupBrand];
+    constructor(predicate, tools) {
+        this.predicate = predicate;
+        this.tools = tools;
+        this[toolGroupBrand] = predicate ?? (() => true);
+    }
+}
+function createToolGroup(predicate, tools) {
+    if (tools.length === 0) {
+        throw new TandemError("An agent tool group cannot be empty.");
+    }
+    const seen = new Set();
+    for (const tool of tools) {
+        if (typeof tool !== "string" && !(commandSelectionBrand in tool)) {
+            throw new TandemError("Agent tools must be built-in names or workspace.commands.");
+        }
+        if (seen.has(tool)) {
+            throw new TandemError("An agent tool group cannot select a tool twice.");
+        }
+        seen.add(tool);
+    }
+    return new AgentToolGroupImplementation(predicate, tools);
+}
+export const agentTools = {
+    always: (...tools) => createToolGroup(undefined, tools),
+    when: (predicate, ...tools) => createToolGroup(predicate, tools),
+};
+class AgentWorkspaceImplementation {
+    path;
+    commands;
+    commandSource;
+    constructor(path, commandSource) {
+        this.path = path;
+        this.commandSource =
+            typeof commandSource === "function" || commandSource === undefined
+                ? commandSource
+                : commandSource.map(copyAgentCommand);
+        this.commands = { [commandSelectionBrand]: this };
+    }
+    withTools(groups, options) {
+        if (groups.length === 0) {
+            throw new TandemError("An agent workspace requires tool groups.");
+        }
+        const implementations = groups.map((group) => {
+            if (!(group instanceof AgentToolGroupImplementation)) {
+                throw new TandemError("Agent tool groups must be created by agentTools.");
+            }
+            return group;
+        });
+        if (options?.interceptTool !== undefined && typeof options.interceptTool !== "function") {
+            throw new TandemError("Workspace tool interceptor must be a function.");
+        }
+        return new AgentWorkspaceConfigurationImplementation(this, implementations, options?.interceptTool);
+    }
+}
+class AgentWorkspaceConfigurationImplementation {
+    workspace;
+    groups;
+    interceptTool;
+    [workspaceBrand];
+    constructor(workspace, groups, interceptTool) {
+        this.workspace = workspace;
+        this.groups = groups;
+        this.interceptTool = interceptTool;
+    }
+}
+export function agentWorkspace(definition) {
+    if (typeof definition.path !== "function") {
+        throw new TandemError("Workspace path is required.");
+    }
+    if (definition.commands !== undefined && typeof definition.commands !== "function") {
+        validateAgentCommands(definition.commands, "Workspace commands");
+    }
+    return new AgentWorkspaceImplementation(definition.path, definition.commands);
+}
+function copyAgentCommand(command) {
+    return command.arguments === undefined
+        ? { ...command }
+        : {
+            ...command,
+            arguments: command.arguments.map((argument) => argument.pattern !== undefined
+                ? { ...argument }
+                : { ...argument, allowedValues: [...argument.allowedValues] }),
+        };
+}
+function validateAgentCommands(commands, context) {
+    if (!Array.isArray(commands)) {
+        throw new TandemError(`${context} must be an array.`);
+    }
+    for (const [commandIndex, command] of commands.entries()) {
+        const commandContext = `${context}[${commandIndex}]`;
+        if (typeof command !== "object" || command === null) {
+            throw new TandemError(`${commandContext} must be a command.`);
+        }
+        const candidate = command;
+        if (typeof candidate.name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidate.name)) {
+            throw new TandemError(`${commandContext}.name must be a valid tool name.`);
+        }
+        if (typeof candidate.description !== "string" || candidate.description.trim().length === 0) {
+            throw new TandemError(`${commandContext}.description must be non-blank.`);
+        }
+        if (typeof candidate.command !== "string" || candidate.command.trim().length === 0) {
+            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.`);
+        }
+        const argumentNames = new Set();
+        for (const [argumentIndex, argument] of (candidate.arguments ?? []).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 (candidateArgument.pattern !== undefined &&
+                typeof candidateArgument.pattern !== "string") {
+                throw new TandemError(`${argumentContext}.pattern must be a string.`);
+            }
+            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);
+                }
+            }
+        }
+    }
+}
+export function skill(definition) {
+    if (typeof definition.directory !== "string" || definition.directory.trim().length === 0) {
+        throw new TandemError("Skill directory must be a non-blank string.");
+    }
+    return { directory: definition.directory };
+}
+class AgentImplementation extends NodeImplementation {
+    instructions;
+    client;
+    message;
+    output;
+    granted;
+    skills;
+    workspace;
+    temperature;
+    maxOutputTokens;
+    reasoning;
+    continueSession;
+    checkpoint;
+    timeoutMs;
+    kind = "agent";
+    constructor(id, persist, instructions, client, message, output, granted, skills, workspace, temperature, maxOutputTokens, reasoning, continueSession, checkpoint, timeoutMs) {
+        super(id, persist);
+        this.instructions = instructions;
+        this.client = client;
+        this.message = message;
+        this.output = output;
+        this.granted = granted;
+        this.skills = skills;
+        this.workspace = workspace;
+        this.temperature = temperature;
+        this.maxOutputTokens = maxOutputTokens;
+        this.reasoning = reasoning;
+        this.continueSession = continueSession;
+        this.checkpoint = checkpoint;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export function agent(definition) {
+    requireInstructions(definition.instructions, `Agent '${definition.id}' instructions`);
+    const reasoningEffort = definition.reasoning?.effort;
+    const reasoningMaxTokens = definition.reasoning?.maxTokens;
+    if (definition.reasoning &&
+        (reasoningEffort !== undefined) === (reasoningMaxTokens !== undefined)) {
+        throw new TandemError(`Agent '${definition.id}' reasoning must specify exactly one of effort or maxTokens.`);
+    }
+    if (reasoningEffort !== undefined &&
+        !["none", "low", "medium", "high"].includes(reasoningEffort)) {
+        throw new TandemError(`Agent '${definition.id}' has an invalid reasoning effort.`);
+    }
+    if (reasoningMaxTokens !== undefined) {
+        if (!Number.isSafeInteger(reasoningMaxTokens) ||
+            reasoningMaxTokens < 1024 ||
+            reasoningMaxTokens > 2_147_483_647) {
+            throw new TandemError(`Agent '${definition.id}' reasoning maxTokens must be a 32-bit integer of at least 1024.`);
+        }
+    }
+    if (definition.output) {
+        requireInstructions(definition.output.instructions, `Agent '${definition.id}' output instructions`);
+    }
+    const capabilities = definition.capabilities ?? [];
+    const names = new Set();
+    for (const item of capabilities) {
+        if (names.has(item.name)) {
+            throw new TandemError(`Agent '${definition.id}' has duplicate capability '${item.name}'.`);
+        }
+        else {
+            names.add(item.name);
+        }
+    }
+    const skills = definition.skills ?? [];
+    const skillDirectories = new Set();
+    for (const item of skills) {
+        if (typeof item?.directory !== "string" || item.directory.trim().length === 0) {
+            throw new TandemError(`Agent '${definition.id}' has a skill with an invalid directory.`);
+        }
+        if (!skillDirectories.add(item.directory)) {
+            throw new TandemError(`Agent '${definition.id}' has the skill directory '${item.directory}' more than once.`);
+        }
+    }
+    if (definition.temperature !== undefined &&
+        (!Number.isFinite(definition.temperature) ||
+            definition.temperature < 0 ||
+            definition.temperature > 2)) {
+        throw new TandemError(`Agent '${definition.id}' temperature must be between 0 and 2.`);
+    }
+    if (definition.maxOutputTokens !== undefined &&
+        (!Number.isSafeInteger(definition.maxOutputTokens) ||
+            definition.maxOutputTokens <= 0 ||
+            definition.maxOutputTokens > 2_147_483_647)) {
+        throw new TandemError(`Agent '${definition.id}' maxOutputTokens must be a positive 32-bit integer.`);
+    }
+    if (definition.checkpoint) {
+        const checkpoint = definition.checkpoint;
+        if (!Number.isSafeInteger(checkpoint.contextWindowTokens) ||
+            checkpoint.contextWindowTokens <= 0 ||
+            checkpoint.contextWindowTokens > 2_147_483_647) {
+            throw new TandemError(`Agent '${definition.id}' checkpoint contextWindowTokens must be a positive 32-bit integer.`);
+        }
+        if (!Number.isSafeInteger(checkpoint.maxOutputTokens) ||
+            checkpoint.maxOutputTokens <= 0 ||
+            checkpoint.maxOutputTokens > 2_147_483_647 ||
+            checkpoint.maxOutputTokens >= checkpoint.contextWindowTokens) {
+            throw new TandemError(`Agent '${definition.id}' checkpoint maxOutputTokens must be a positive 32-bit integer smaller than contextWindowTokens.`);
+        }
+        if (!Number.isSafeInteger(checkpoint.checkpointAtPercent) ||
+            checkpoint.checkpointAtPercent <= 0 ||
+            checkpoint.checkpointAtPercent >= 100) {
+            throw new TandemError(`Agent '${definition.id}' checkpoint checkpointAtPercent must be between 1 and 99.`);
+        }
+        if (!capabilities.includes(checkpoint.capability)) {
+            throw new TandemError(`Agent '${definition.id}' checkpoint capability must be attached to the agent.`);
+        }
+        requireInstructions(checkpoint.instructions, `Agent '${definition.id}' checkpoint instructions`);
+        if (checkpoint.session !== undefined &&
+            checkpoint.session !== "retain" &&
+            checkpoint.session !== "reset") {
+            throw new TandemError(`Agent '${definition.id}' checkpoint session must be 'retain' or 'reset'.`);
+        }
+        if (checkpoint.disableCompaction !== undefined &&
+            typeof checkpoint.disableCompaction !== "boolean") {
+            throw new TandemError(`Agent '${definition.id}' checkpoint disableCompaction must be a boolean.`);
+        }
+    }
+    return new AgentImplementation(definition.id, definition.persist, definition.instructions, definition.client, definition.message, definition.output, capabilities, skills, definition.workspace, definition.temperature, definition.maxOutputTokens, definition.reasoning, definition.continueSession ?? false, definition.checkpoint, definition.timeoutMs);
+}
+class ParallelImplementation extends NodeImplementation {
+    branches;
+    merge;
+    kind = "parallel";
+    constructor(id, persist, branches, merge) {
+        super(id, persist);
+        this.branches = branches;
+        this.merge = merge;
+    }
+}
+export function parallel(definition) {
+    if (!definition) {
+        return (value) => createParallel(value);
+    }
+    return createParallel(definition);
+}
+function createParallel(definition) {
+    const entries = Object.entries(definition.branches);
+    if (entries.length < 2) {
+        throw new TandemError(`Parallel group '${definition.id}' requires at least two branches.`);
+    }
+    const participants = new Set(entries.map(([, participant]) => participant));
+    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);
+}
+class TerminalImplementation extends NodeImplementation {
+    failed;
+    summary;
+    kind = "terminal";
+    constructor(id, persist, failed, summary) {
+        super(id, persist);
+        this.failed = failed;
+        this.summary = summary;
+    }
+}
+export function output(definition) {
+    return new TerminalImplementation(definition.id, definition.persist, definition.failed ?? false, definition.summary);
+}
+export function route(definition) {
+    return definition;
+}
+export function pipeline(definition) {
+    const start = definition.start;
+    const members = new Set(definition.nodes);
+    if (members.size !== definition.nodes.length) {
+        throw new Error("Pipeline nodes must contain each participant object exactly once.");
+    }
+    const ids = new Set(definition.nodes.map((node) => node.id));
+    if (ids.size !== definition.nodes.length) {
+        throw new Error("Pipeline node IDs must be unique.");
+    }
+    const ownedParticipants = new Set();
+    for (const node of definition.nodes) {
+        if (node.kind !== "parallel") {
+            continue;
+        }
+        const parallelNode = node;
+        for (const [branchId, participant] of Object.entries(parallelNode.branches)) {
+            if (branchId.trim().length === 0) {
+                throw new Error(`Parallel group '${node.id}' contains a blank branch ID.`);
+            }
+            if (members.has(participant)) {
+                throw new Error(`Parallel branch participant '${participant.id}' cannot also be a parent pipeline node.`);
+            }
+            if (!ownedParticipants.add(participant)) {
+                throw new Error(`Parallel branch participant '${participant.id}' is owned more than once.`);
+            }
+            if (ids.has(participant.id)) {
+                throw new Error(`Pipeline participant ID '${participant.id}' must be globally unique.`);
+            }
+            ids.add(participant.id);
+        }
+    }
+    if (!members.has(definition.start)) {
+        throw new Error(`Pipeline start '${definition.start.id}' must be the registered participant object.`);
+    }
+    if (start.kind === "terminal") {
+        throw new Error(`Pipeline start '${start.id}' cannot be a terminal.`);
+    }
+    for (const item of definition.routes) {
+        if (!members.has(item.from) || !members.has(item.to)) {
+            throw new Error(`Route '${item.label}' endpoints must be registered participant objects.`);
+        }
+    }
+    const unconditionalRoutes = new Map();
+    for (const item of definition.routes) {
+        if (item.when) {
+            continue;
+        }
+        const key = `${item.from.id}\u0000${item.outcome ?? "default"}`;
+        const existing = unconditionalRoutes.get(key);
+        if (existing) {
+            throw new Error(`Routes '${existing.label}' and '${item.label}' are both unconditional from '${item.from.id}'.`);
+        }
+        unconditionalRoutes.set(key, item);
+    }
+    if (new Set(definition.outputs).size !== definition.outputs.length) {
+        throw new Error("Pipeline outputs must contain each terminal exactly once.");
+    }
+    for (const item of definition.outputs) {
+        if (!members.has(item)) {
+            throw new Error(`Output '${item.id}' must be the registered participant object.`);
+        }
+    }
+    const reachable = new Set([start]);
+    const pending = [start];
+    while (pending.length > 0) {
+        const source = pending.pop();
+        for (const item of definition.routes) {
+            if (item.from === source && !reachable.has(item.to)) {
+                reachable.add(item.to);
+                pending.push(item.to);
+            }
+        }
+    }
+    const outputs = new Set(definition.outputs);
+    for (const node of reachable) {
+        if (node.kind === "terminal" && !outputs.has(node)) {
+            throw new Error(`Reachable terminal '${node.id}' must be listed in outputs.`);
+        }
+    }
+    for (const item of definition.outputs) {
+        if (!reachable.has(item)) {
+            throw new Error(`Output '${item.id}' must be reachable from start '${start.id}'.`);
+        }
+    }
+    return { ...definition, persist: definition.persist ?? false };
+}
+const runObservationSchema = z.discriminatedUnion("kind", [
+    z
+        .object({ version: z.literal(1), kind: z.literal("stepStarted"), stepId: z.string().min(1) })
+        .strict(),
+    z
+        .object({ version: z.literal(1), kind: z.literal("stepCompleted"), stepId: z.string().min(1) })
+        .strict(),
+    z
+        .object({ version: z.literal(1), kind: z.literal("stepCancelled"), stepId: z.string().min(1) })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        kind: z.literal("stepFaulted"),
+        stepId: z.string().min(1),
+        error: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        kind: z.literal("agentText"),
+        stepId: z.string().min(1),
+        text: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        kind: z.literal("agentModelSelected"),
+        stepId: z.string().min(1),
+        modelId: z.string().min(1),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        kind: z.literal("agentReasoning"),
+        stepId: z.string().min(1),
+        text: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        kind: z.literal("agentUsage"),
+        stepId: z.string().min(1),
+        inputTokens: z.number().int().nonnegative(),
+        outputTokens: z.number().int().nonnegative(),
+        reasoningTokens: z.number().int().nonnegative(),
+        currentContextTokens: z.number().int().nonnegative(),
+        contextWindowTokens: z.number().int().nonnegative().nullable(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        kind: z.literal("structuredOutputRejected"),
+        stepId: z.string().min(1),
+        attempt: z.number().int().positive(),
+        problems: z.array(z.object({ field: z.string(), message: z.string().min(1) }).strict()),
+        rawResponse: z.string(),
+    })
+        .strict(),
+]);
+const acceptedKinds = [
+    "StructuredOutputAccepted",
+    "CapabilityAccepted",
+    "InteractionRequested",
+    "InteractionAnswered",
+    "StepCompleted",
+];
+const acceptedValueSchema = z
+    .object({
+    kind: z.enum(acceptedKinds),
+    stepId: z.string().min(1),
+    valueType: z.string().min(1).nullable(),
+    payload: z.unknown().nullable(),
+})
+    .strict()
+    .refine((value) => value.valueType !== null || value.payload !== null, {
+    message: "valueType and payload cannot both be null",
+});
+const acceptedValuesSchema = z.array(acceptedValueSchema);
+const runResultSchema = z
+    .object({
+    runId: z.uuid(),
+    succeeded: z.boolean(),
+    state: z.unknown(),
+    summary: z.string().nullable(),
+})
+    .strict();
+export async function inspectAccepted(options) {
+    try {
+        const { inspectAcceptedAsync } = await import("@maxanstey-meridian/tandem-runtime");
+        return parseJson(acceptedValuesSchema, await inspectAcceptedAsync(options.ledgerPath, options.runId), "accepted values").map((value) => ({
+            version: 1,
+            kind: value.kind,
+            stepId: value.stepId,
+            valueType: value.valueType,
+            payload: value.payload,
+        }));
+    }
+    catch (error) {
+        if (error instanceof TandemError) {
+            throw error;
+        }
+        throw new TandemRuntimeError("inspect", error);
+    }
+}
+export async function run(graph, initial, options = {}) {
+    const initialState = serializeBoundary(graph.state, initial, "initial state");
+    if ((graph.persist || graph.nodes.some(participantPersists)) && !options.ledgerPath) {
+        throw new TandemError("ledgerPath is required when persistence is enabled.");
+    }
+    const callbacks = new CallbackRegistry();
+    try {
+        const nodes = graph.nodes.map((node) => compileNode(node, graph.state, callbacks));
+        const routes = graph.routes.map((item) => {
+            const callback = item.when
+                ? callbacks.registerSync((state) => String(item.when(parseJson(graph.state, state, `route '${item.label}' state`))))
+                : undefined;
+            return {
+                source: item.from.id,
+                target: item.to.id,
+                label: item.label,
+                outcome: item.outcome,
+                predicateCallback: callback,
+            };
+        });
+        const handlerEntries = interactionHandlerEntries(options.interactions);
+        const members = new Set(graph.nodes);
+        const interactionHandlers = handlerEntries.map((entry, index) => {
+            if (!members.has(entry.interaction)) {
+                throw new TandemError(`Interaction handler '${entry.interaction.id}' must target a participant in pipeline '${graph.name}'.`);
+            }
+            const implementation = entry.interaction;
+            const handleCallback = callbacks.registerAsync(async (_, input, signal) => {
+                const response = await entry.handle(parseJson(implementation.requestSchema, input, `${implementation.id} request input`), { signal });
+                signal.throwIfAborted();
+                return serializeBoundary(implementation.responseSchema, response, `${implementation.id} response`);
+            });
+            return { id: `h${index}`, target: entry.interaction.id, handleCallback };
+        });
+        const observationCallback = options.observe
+            ? callbacks.registerAsync(async (_, input, signal) => {
+                const event = parseJson(runObservationSchema, input, "run observation");
+                const observationSignal = options.signal?.aborted === true
+                    ? AbortSignal.abort(options.signal.reason)
+                    : event.kind === "stepCancelled" && !signal.aborted
+                        ? AbortSignal.abort()
+                        : signal;
+                await options.observe(event, { signal: observationSignal });
+                return "";
+            })
+            : undefined;
+        const { runRegisteredGraphAsync } = await import("@maxanstey-meridian/tandem-runtime");
+        const resultJson = await runRegisteredGraphAsync(JSON.stringify({
+            contractVersion: 10,
+            name: graph.name,
+            start: graph.start.id,
+            initialState,
+            persist: graph.persist,
+            ledgerPath: options.ledgerPath,
+            presentation: options.presentation,
+            terminal: options.terminal,
+            observationCallback,
+            nodes,
+            routes,
+            outputs: graph.outputs.map((item) => item.id),
+            interactionHandlers,
+        }), (id, state, input) => callbacks.invokeSync(id, state, input), (id, state, input, signal) => callbacks.invokeAsync(id, state, input, signal), options.signal);
+        const result = parseJson(runResultSchema, resultJson, "run result");
+        return { ...result, state: parse(graph.state, result.state, "final state") };
+    }
+    catch (error) {
+        if (error instanceof TandemError) {
+            throw error;
+        }
+        const callbackFailure = callbackContractFailure(error);
+        if (callbackFailure) {
+            throw new ContractValidationError(callbackFailure.boundary, callbackFailure.problems);
+        }
+        if (isCancellationError(error, options.signal?.aborted === true)) {
+            throw new TandemCancellationError(error);
+        }
+        throw new TandemRuntimeError("run", error);
+    }
+    finally {
+        callbacks.dispose();
+    }
+}
+function participantPersists(node) {
+    const implementation = node;
+    if (implementation.persist) {
+        return true;
+    }
+    return implementation instanceof ParallelImplementation
+        ? Object.values(implementation.branches).some((branch) => branch.persist === true)
+        : false;
+}
+function issues(schema, input) {
+    let value;
+    try {
+        value = JSON.parse(input);
+    }
+    catch {
+        return JSON.stringify([{ path: "$", message: "Invalid JSON" }]);
+    }
+    try {
+        parse(schema, value, "agent contract");
+        return "";
+    }
+    catch (error) {
+        if (error instanceof ContractValidationError) {
+            return JSON.stringify(error.problems);
+        }
+        throw error;
+    }
+}
+const validationProblemsSchema = z.array(z.object({ path: z.string(), message: z.string() }).strict());
+function validationProblems(problems, boundary) {
+    return JSON.stringify(parse(validationProblemsSchema, problems, boundary));
+}
+function requireInstructions(instructions, boundary) {
+    if (typeof instructions !== "string" || instructions.trim().length === 0) {
+        throw new ContractValidationError(boundary, [
+            { path: "$", message: "Instructions must be a non-blank string." },
+        ]);
+    }
+}
+function interactionHandlerEntries(handlers) {
+    if (!handlers) {
+        return [];
+    }
+    if (!(handlers instanceof InteractionHandlersImplementation)) {
+        throw new TandemError("interactions must be created by interactions().");
+    }
+    return handlers.entries;
+}
+function compileNode(node, stateSchema, callbacks) {
+    const implementation = node;
+    const base = { id: node.id, persist: implementation.persist };
+    if (implementation instanceof StageImplementation) {
+        const run = callbacks.registerAsync(async (state, _, signal) => serializeBoundary(stateSchema, await implementation.execute(parseJson(stateSchema, state, `${node.id} input`), {
+            signal,
+        }), `${node.id} output`));
+        return { ...base, kind: "stage", runCallback: run };
+    }
+    if (implementation instanceof InteractionImplementation) {
+        const request = callbacks.registerSync((state) => serializeBoundary(implementation.requestSchema, implementation.request(parseJson(stateSchema, state, `${node.id} state`)), `${node.id} request`));
+        const apply = callbacks.registerSync((state, input) => serializeBoundary(stateSchema, implementation.apply(parseJson(stateSchema, state, `${node.id} state`), parseJson(implementation.responseSchema, input, `${node.id} response input`)), `${node.id} applied state`));
+        return {
+            ...base,
+            kind: "interaction",
+            requestCallback: request,
+            applyCallback: apply,
+        };
+    }
+    if (implementation instanceof AgentImplementation) {
+        const message = callbacks.registerSync((state) => implementation.message(parseJson(stateSchema, state, `${node.id} message state`)));
+        const output = implementation.output
+            ? compileAgentOutput(node.id, implementation.output, stateSchema, callbacks)
+            : undefined;
+        const capabilities = implementation.granted.map((item) => item[compileCapabilityBrand]({ id: node.id, stateSchema, callbacks }));
+        const workspace = implementation.workspace
+            ? compileWorkspace(node.id, implementation.workspace, stateSchema, callbacks)
+            : undefined;
+        return {
+            ...base,
+            kind: "agent",
+            instructions: implementation.instructions,
+            client: { ...implementation.client, verifyModel: implementation.client.verifyModel ?? false },
+            messageCallback: message,
+            output,
+            capabilities,
+            skillDirectories: implementation.skills.map((item) => item.directory),
+            temperature: implementation.temperature,
+            maxOutputTokens: implementation.maxOutputTokens,
+            reasoning: implementation.reasoning,
+            continueSession: implementation.continueSession,
+            checkpoint: implementation.checkpoint
+                ? {
+                    contextWindowTokens: implementation.checkpoint.contextWindowTokens,
+                    maxOutputTokens: implementation.checkpoint.maxOutputTokens,
+                    checkpointAtPercent: implementation.checkpoint.checkpointAtPercent,
+                    capabilityName: implementation.checkpoint.capability.name,
+                    instructions: implementation.checkpoint.instructions,
+                    messageCallback: callbacks.registerSync((state, input) => implementation.checkpoint.message(parseJson(stateSchema, state, `${node.id} checkpoint state`), Number(input))),
+                    resetSession: (implementation.checkpoint.session ?? "reset") === "reset",
+                    disableCompaction: implementation.checkpoint.disableCompaction ?? false,
+                }
+                : undefined,
+            timeoutMilliseconds: implementation.timeoutMs,
+            workspace,
+        };
+    }
+    if (implementation instanceof ParallelImplementation) {
+        const entries = Object.entries(implementation.branches);
+        const branchIds = entries.map(([branchId]) => branchId);
+        const mergeCallback = callbacks.registerSync((state, input) => {
+            const baseline = parseJson(stateSchema, state, `${node.id} merge baseline`);
+            let raw;
+            try {
+                raw = JSON.parse(input);
+            }
+            catch {
+                throw new ContractValidationError(`${node.id} merge branches`, [
+                    { path: "$", message: "Invalid JSON" },
+                ]);
+            }
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                throw new ContractValidationError(`${node.id} merge branches`, [
+                    { path: "$", message: "Expected a branch-state object." },
+                ]);
+            }
+            const values = raw;
+            if (!isDeepStrictEqual(Object.keys(values).sort(), [...branchIds].sort())) {
+                throw new ContractValidationError(`${node.id} merge branches`, [
+                    { path: "$", message: "Branch-state keys do not match the authored branches." },
+                ]);
+            }
+            const parsed = Object.fromEntries(branchIds.map((branchId) => [
+                branchId,
+                parse(stateSchema, values[branchId], `${node.id} branch '${branchId}' state`),
+            ]));
+            return serializeBoundary(stateSchema, implementation.merge(baseline, parsed), `${node.id} merged state`);
+        });
+        return {
+            ...base,
+            kind: "parallel",
+            branches: entries.map(([id, participant]) => ({
+                id,
+                participant: compileNode(participant, stateSchema, callbacks),
+            })),
+            mergeCallback,
+        };
+    }
+    const terminal = implementation;
+    const summary = callbacks.registerSync((state) => terminal.summary(parseJson(stateSchema, state, `${node.id} state`)));
+    return { ...base, kind: terminal.failed ? "failure" : "completion", summaryCallback: summary };
+}
+function compileWorkspace(id, configuration, stateSchema, callbacks) {
+    if (!(configuration instanceof AgentWorkspaceConfigurationImplementation)) {
+        throw new TandemError(`Agent '${id}' workspace must be created by agentWorkspace().withTools().`);
+    }
+    const workspace = configuration.workspace;
+    const pathCallback = callbacks.registerSync((state) => {
+        const value = workspace.path(parseJson(stateSchema, state, `${id} workspace path state`));
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new TandemError(`Agent '${id}' workspace path must be non-blank.`);
+        }
+        return value;
+    });
+    const commandsCallback = callbacks.registerSync((state) => {
+        const typedState = parseJson(stateSchema, state, `${id} workspace commands state`);
+        const value = typeof workspace.commandSource === "function"
+            ? workspace.commandSource(typedState)
+            : (workspace.commandSource ?? []);
+        validateAgentCommands(value, `Agent '${id}' workspace commands`);
+        return serializeBoundary(z.array(z
+            .object({
+            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(),
+        })
+            .strict()), value, `${id} workspace commands`);
+    });
+    const selected = new Set();
+    const toolGroups = configuration.groups.map((group, index) => {
+        let includeCommands = false;
+        const tools = [];
+        for (const tool of group.tools) {
+            if (typeof tool === "string") {
+                if (selected.has(tool)) {
+                    throw new TandemError(`Agent '${id}' selects '${tool}' more than once.`);
+                }
+                selected.add(tool);
+                tools.push(tool);
+            }
+            else {
+                if (tool[commandSelectionBrand] !== workspace) {
+                    throw new TandemError(`Agent '${id}' selects commands from another workspace.`);
+                }
+                if (workspace.commandSource === undefined) {
+                    throw new TandemError(`Agent '${id}' selects workspace commands without declaring a command catalogue.`);
+                }
+                if (selected.has(tool)) {
+                    throw new TandemError(`Agent '${id}' selects workspace commands twice.`);
+                }
+                selected.add(tool);
+                includeCommands = true;
+            }
+        }
+        const whenCallback = group.predicate
+            ? callbacks.registerSync((state) => {
+                const value = group.predicate(parseJson(stateSchema, state, `${id} tool group ${index} state`));
+                if (typeof value !== "boolean") {
+                    throw new TandemError(`Agent '${id}' tool group ${index} predicate must return a boolean.`);
+                }
+                return String(value);
+            })
+            : undefined;
+        return { tools, includeCommands, whenCallback };
+    });
+    const interceptCallback = configuration.interceptTool
+        ? callbacks.registerAsync(async (state, input, signal) => {
+            const typedState = parseJson(stateSchema, state, `${id} tool interception state`);
+            let invocation;
+            try {
+                invocation = JSON.parse(input);
+            }
+            catch {
+                throw new TandemError(`Agent '${id}' received an invalid tool interception payload.`);
+            }
+            const result = await configuration.interceptTool(typedState, invocation, { signal });
+            if (result !== null && typeof result !== "string") {
+                throw new TandemError(`Agent '${id}' tool interceptor must return a string or null.`);
+            }
+            return JSON.stringify(result);
+        })
+        : undefined;
+    return { pathCallback, commandsCallback, toolGroups, interceptCallback };
+}
+function compileAgentOutput(id, output, stateSchema, callbacks) {
+    const validate = 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`))
+        : 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`));
+    return {
+        instructions: output.instructions,
+        jsonSchema: inputJsonSchema(output.schema, `${id} output schema`),
+        validateCallback: validate,
+        validateForCallback: validateFor,
+        applyCallback: apply,
+        valueType: `${id}.output`,
+    };
+}