@maxanstey-meridian/tandem 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Anstey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @maxanstey-meridian/tandem
+
+The TypeScript authoring API for [Tandem](https://github.com/maxanstey-meridian/tandem), a typed
+agentic pipeline SDK running on .NET and Microsoft Agent Framework.
+
+## Requirements
+
+- macOS on Apple silicon
+- Node.js 22 or newer
+- .NET 10 runtime
+
+## Install
+
+```sh
+npm install @maxanstey-meridian/tandem zod
+```
+
+Install only this package in application code. Its runtime packages are selected automatically.
+
+## Quick Start
+
+```ts
+import { output, pipeline, route, run, stage } from "@maxanstey-meridian/tandem";
+import { z } from "zod";
+
+const State = z.object({
+  input: z.string(),
+  normalized: z.string().nullable(),
+});
+type State = z.infer<typeof State>;
+
+const normalize = stage<State>({
+  id: "normalize",
+  execute: (state) => ({
+    ...state,
+    normalized: state.input.trim().toLowerCase(),
+  }),
+});
+
+const done = output<State>({
+  id: "done",
+  summary: (state) => state.normalized!,
+});
+
+const normalizeInput = pipeline({
+  name: "normalize-input",
+  state: State,
+  nodes: [normalize, done],
+  start: normalize,
+  routes: [route({ from: normalize, to: done, label: "normalized" })],
+  outputs: [done],
+});
+
+const result = await run(normalizeInput, { input: "  Hello  ", normalized: null });
+console.log(result.state.normalized);
+```
+
+State holds application facts, participants perform work, and routes decide what runs next. See the
+[TypeScript guide](https://github.com/maxanstey-meridian/tandem/tree/main/typescript) for agents,
+capabilities, interactions, persistence, and complete examples.
+
+Licensed under the [MIT License](./LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+import { type Pipeline, type RunOptions, type RunResult } from "./index.js";
+export interface RunCliOptions<TState> extends Omit<RunOptions, "presentation"> {
+    readonly formatResult: (result: RunResult<TState>) => string | Promise<string>;
+}
+export declare function runCli<TState>(graph: Pipeline<TState>, initial: unknown, options: RunCliOptions<TState>): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,60 @@
+import { run } from "./index.js";
+export async function runCli(graph, initial, options) {
+    let exitCode = 2;
+    let signalExitCode = null;
+    let pipelineCompleted = false;
+    const shutdown = new AbortController();
+    const requestShutdown = (code, signal) => {
+        signalExitCode ??= code;
+        shutdown.abort(new Error(`Received ${signal}.`));
+    };
+    const onSigInt = () => requestShutdown(130, "SIGINT");
+    const onSigTerm = () => requestShutdown(143, "SIGTERM");
+    process.once("SIGINT", onSigInt);
+    process.once("SIGTERM", onSigTerm);
+    try {
+        const { formatResult, signal, ...runOptions } = options;
+        const runSignal = signal ? AbortSignal.any([signal, shutdown.signal]) : shutdown.signal;
+        const result = await run(graph, initial, {
+            ...runOptions,
+            signal: runSignal,
+            presentation: "terminal",
+        });
+        pipelineCompleted = true;
+        const formatted = await formatResult(result);
+        await write(process.stdout, `${formatted}\n`);
+        exitCode = result.succeeded ? 0 : 1;
+    }
+    catch (error) {
+        if (signalExitCode === null) {
+            const prefix = pipelineCompleted ? "Pipeline completed, but result output failed: " : "";
+            await write(process.stderr, `${prefix}${formatError(error)}\n`);
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", onSigInt);
+        process.removeListener("SIGTERM", onSigTerm);
+        process.exitCode = signalExitCode ?? exitCode;
+    }
+}
+function formatError(error, seen = new Set()) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    if (seen.has(error)) {
+        return error.stack ?? `${error.name}: ${error.message}`;
+    }
+    seen.add(error);
+    const stack = error.stack;
+    const detail = stack?.startsWith(`${error.name}: `)
+        ? stack.slice(error.name.length + 2)
+        : (stack ?? error.message);
+    if (error.cause === undefined) {
+        return detail;
+    }
+    const cause = formatError(error.cause, seen);
+    return detail.includes(cause) ? detail : `${detail}\nCaused by: ${cause}`;
+}
+function write(stream, value) {
+    return new Promise((resolve, reject) => stream.write(value, (error) => (error ? reject(error) : resolve())));
+}

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+import { z } from "zod";
+type SyncCallback = (state: string, input: string) => string;
+type AsyncCallback = (state: string, input: string, signal: AbortSignal) => Promise<string>;
+declare const participantBrand: unique symbol;
+declare const compileCapabilityBrand: unique symbol;
+declare const interactionHandlersBrand: unique symbol;
+declare const workspaceBrand: unique symbol;
+declare const toolGroupBrand: unique symbol;
+declare const commandSelectionBrand: unique symbol;
+export declare class TandemError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class TandemRuntimeError extends TandemError {
+    readonly operation: "run" | "inspect";
+    constructor(operation: "run" | "inspect", cause: unknown);
+}
+export declare class TandemCancellationError extends TandemRuntimeError {
+    constructor(cause: unknown);
+}
+export declare class ContractValidationError extends TandemError {
+    readonly boundary: string;
+    readonly problems: readonly ValidationProblem[];
+    constructor(boundary: string, problems: readonly ValidationProblem[]);
+}
+export type ValidationProblem = {
+    readonly path: string;
+    readonly message: string;
+};
+declare class CallbackRegistry {
+    #private;
+    registerSync(callback: SyncCallback): string;
+    registerAsync(callback: AsyncCallback): string;
+    invokeSync(id: string, state: string, input: string): string;
+    invokeAsync(id: string, state: string, input: string, signal: AbortSignal): Promise<string>;
+    dispose(): void;
+}
+interface Participant<TState> {
+    readonly id: string;
+    readonly [participantBrand]: (state: TState) => TState;
+}
+export interface Stage<TState> extends Participant<TState> {
+    readonly kind: "stage";
+}
+export interface Interaction<TState, TRequest, TResponse> extends Participant<TState> {
+    readonly kind: "interaction";
+    readonly requestType?: TRequest;
+    readonly responseType?: TResponse;
+}
+export interface Agent<TState> extends Participant<TState> {
+    readonly kind: "agent";
+}
+export interface Parallel<TState> extends Participant<TState> {
+    readonly kind: "parallel";
+}
+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>;
+export declare function stage<TState>(definition: {
+    id: string;
+    execute: (state: TState, context: {
+        readonly signal: AbortSignal;
+    }) => TState | Promise<TState>;
+    persist?: boolean;
+}): Stage<TState>;
+export declare function interaction<TState, TRequest, TResponse>(definition: {
+    id: string;
+    requestSchema: z.ZodType<TRequest>;
+    responseSchema: z.ZodType<TResponse>;
+    request: (state: TState) => TRequest;
+    apply: (state: TState, response: TResponse) => TState;
+    persist?: boolean;
+}): Interaction<TState, TRequest, TResponse>;
+type InteractionHandler<TRequest, TResponse> = (request: TRequest, context: {
+    readonly signal: AbortSignal;
+}) => TResponse | Promise<TResponse>;
+export interface InteractionHandlers {
+    handle<TState, TRequest, TResponse>(interaction: Interaction<TState, TRequest, TResponse>, handler: InteractionHandler<TRequest, TResponse>): InteractionHandlers;
+    readonly [interactionHandlersBrand]: true;
+}
+export declare function interactions(): InteractionHandlers;
+interface CapabilityCompileContext<TState> {
+    readonly id: string;
+    readonly stateSchema: z.ZodType<TState>;
+    readonly callbacks: CallbackRegistry;
+}
+export interface Capability<TState> {
+    readonly name: string;
+    readonly [compileCapabilityBrand]: (context: CapabilityCompileContext<TState>) => object;
+}
+export declare function capability<TState, TRequest>(definition: {
+    readonly name: string;
+    readonly instructions: string;
+    readonly schema: z.ZodType<TRequest>;
+    readonly validateFor?: (state: TState, request: TRequest) => readonly ValidationProblem[];
+    readonly apply: (state: TState, request: TRequest) => TState;
+    readonly summarize: (request: TRequest) => string;
+}): Capability<TState>;
+export interface OpenAiCompatibleChatClient {
+    readonly kind: "openai-compatible";
+    readonly version: 1;
+    readonly endpoint: string;
+    readonly model: string;
+    readonly wireApi: "completions" | "responses";
+    readonly apiKeyEnvironmentVariable?: string;
+    readonly verifyModel?: boolean;
+}
+export type ChatClient = OpenAiCompatibleChatClient;
+export type AgentReasoning = {
+    readonly effort: "none" | "low" | "medium" | "high";
+    readonly maxTokens?: never;
+} | {
+    readonly maxTokens: number;
+    readonly effort?: never;
+};
+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[];
+}
+interface AgentCommandSelection {
+    readonly [commandSelectionBrand]: object;
+}
+type AgentToolSelection = AgentToolName | AgentCommandSelection;
+export interface AgentToolGroup<TState> {
+    readonly [toolGroupBrand]: (state: TState) => boolean;
+}
+export type AgentToolEffect = "read" | "workspaceMutation" | "processExecution" | "lifecycleTransition" | "unclassified";
+export interface AgentToolInvocation {
+    readonly name: string;
+    readonly effect: AgentToolEffect;
+    readonly arguments: unknown;
+}
+export type AgentToolInterceptor<TState> = (state: TState, invocation: AgentToolInvocation, context: {
+    readonly signal: AbortSignal;
+}) => string | null | Promise<string | null>;
+export declare const agentTools: {
+    always: (...tools: readonly AgentToolSelection[]) => AgentToolGroup<never>;
+    when: <TState>(predicate: (state: TState) => boolean, ...tools: readonly AgentToolSelection[]) => AgentToolGroup<TState>;
+};
+export interface AgentWorkspaceConfiguration<TState> {
+    readonly [workspaceBrand]: (state: TState) => TState;
+}
+export interface AgentWorkspace<TState> {
+    readonly commands: AgentCommandSelection;
+    withTools(groups: readonly (AgentToolGroup<TState> | AgentToolGroup<never>)[], options?: {
+        readonly interceptTool?: AgentToolInterceptor<TState>;
+    }): AgentWorkspaceConfiguration<TState>;
+}
+export declare function agentWorkspace<TState>(definition: {
+    readonly path: (state: TState) => string;
+    readonly commands?: readonly AgentCommand[] | ((state: TState) => readonly AgentCommand[]);
+}): AgentWorkspace<TState>;
+export declare function skill(definition: {
+    readonly directory: string;
+}): AgentSkill;
+export interface AgentDefinition<TState, TOutput = never> {
+    readonly id: string;
+    readonly instructions: string;
+    readonly client: ChatClient;
+    readonly message: (state: TState) => string;
+    readonly output?: {
+        readonly instructions: string;
+        readonly schema: z.ZodType<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[];
+    readonly workspace?: AgentWorkspaceConfiguration<TState>;
+    readonly temperature?: number;
+    readonly maxOutputTokens?: number;
+    readonly reasoning?: AgentReasoning;
+    readonly continueSession?: boolean;
+    readonly checkpoint?: {
+        readonly contextWindowTokens: number;
+        readonly maxOutputTokens: number;
+        readonly checkpointAtPercent: number;
+        readonly capability: Capability<TState>;
+        readonly instructions: string;
+        readonly message: (state: TState, currentContextTokens: number) => string;
+        readonly session?: "retain" | "reset";
+        readonly disableCompaction?: boolean;
+    };
+    readonly timeoutMs?: number;
+    readonly persist?: boolean;
+}
+export declare function agent<TState, TOutput = never>(definition: AgentDefinition<TState, TOutput>): Agent<TState>;
+type ParallelBranches<TState> = Readonly<Record<string, Stage<TState> | Agent<TState>>>;
+type ParallelDefinition<TState, TBranches extends ParallelBranches<TState>> = {
+    readonly id: string;
+    readonly branches: TBranches;
+    readonly merge: (baseline: TState, results: {
+        readonly [K in keyof TBranches]: TState;
+    }) => TState;
+    readonly persist?: boolean;
+};
+export declare function parallel<TState>(): <const TBranches extends ParallelBranches<TState>>(definition: ParallelDefinition<TState, TBranches>) => Parallel<TState>;
+export declare function parallel<TState, const TBranches extends ParallelBranches<TState>>(definition: ParallelDefinition<TState, TBranches>): Parallel<TState>;
+export declare function output<TState>(definition: {
+    id: string;
+    summary: (state: TState) => string;
+    failed?: boolean;
+    persist?: boolean;
+}): Terminal<TState>;
+export interface OrdinaryRoute<TState> {
+    readonly from: Stage<TState> | Interaction<TState, unknown, unknown>;
+    readonly to: Node<TState>;
+    readonly label: string;
+    readonly outcome?: never;
+    readonly when?: (state: TState) => boolean;
+}
+export interface StandardOutcomeRoute<TState> {
+    readonly from: Agent<TState> | Parallel<TState>;
+    readonly to: Node<TState>;
+    readonly label: string;
+    readonly outcome: "success" | "failed";
+    readonly when?: (state: TState) => boolean;
+}
+export type Route<TState> = OrdinaryRoute<TState> | StandardOutcomeRoute<TState>;
+export declare function route<TState>(definition: OrdinaryRoute<TState>): OrdinaryRoute<TState>;
+export declare function route<TState>(definition: StandardOutcomeRoute<TState>): StandardOutcomeRoute<TState>;
+export interface Pipeline<TState> {
+    readonly name: string;
+    readonly state: z.ZodType<TState>;
+    readonly nodes: readonly Node<TState>[];
+    readonly start: Exclude<Node<TState>, Terminal<TState>>;
+    readonly routes: readonly Route<TState>[];
+    readonly outputs: readonly Terminal<TState>[];
+    readonly persist: boolean;
+}
+export declare function pipeline<TState>(definition: {
+    name: string;
+    state: z.ZodType<TState>;
+    nodes: readonly Node<NoInfer<TState>>[];
+    start: Exclude<Node<NoInfer<TState>>, Terminal<NoInfer<TState>>>;
+    routes: readonly Route<NoInfer<TState>>[];
+    outputs: readonly Terminal<NoInfer<TState>>[];
+    persist?: boolean;
+}): Pipeline<TState>;
+export interface RunResult<TState> {
+    readonly runId: string;
+    readonly succeeded: boolean;
+    readonly state: TState;
+    readonly summary: string | null;
+}
+export type RunObservation = {
+    readonly version: 1;
+    readonly kind: "stepStarted";
+    readonly stepId: string;
+} | {
+    readonly version: 1;
+    readonly kind: "stepCompleted";
+    readonly stepId: string;
+} | {
+    readonly version: 1;
+    readonly kind: "stepCancelled";
+    readonly stepId: string;
+} | {
+    readonly version: 1;
+    readonly kind: "stepFaulted";
+    readonly stepId: string;
+    readonly error: string;
+} | {
+    readonly version: 1;
+    readonly kind: "agentText";
+    readonly stepId: string;
+    readonly text: string;
+} | {
+    readonly version: 1;
+    readonly kind: "agentReasoning";
+    readonly stepId: string;
+    readonly text: string;
+} | {
+    readonly version: 1;
+    readonly kind: "agentModelSelected";
+    readonly stepId: string;
+    readonly modelId: string;
+} | {
+    readonly version: 1;
+    readonly kind: "agentUsage";
+    readonly stepId: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokens: number;
+    readonly currentContextTokens: number;
+    readonly contextWindowTokens: number | null;
+} | {
+    readonly version: 1;
+    readonly kind: "structuredOutputRejected";
+    readonly stepId: string;
+    readonly attempt: number;
+    readonly problems: readonly {
+        readonly field: string;
+        readonly message: string;
+    }[];
+    readonly rawResponse: string;
+};
+export interface TerminalPresentationOptions {
+    readonly truncatedToolNames?: readonly string[];
+}
+export interface RunOptions {
+    readonly ledgerPath?: string;
+    readonly signal?: AbortSignal;
+    readonly interactions?: InteractionHandlers;
+    readonly presentation?: "terminal";
+    readonly terminal?: TerminalPresentationOptions;
+    readonly observe?: (event: RunObservation, context: {
+        readonly signal: AbortSignal;
+    }) => void | Promise<void>;
+}
+declare const acceptedKinds: readonly ["StructuredOutputAccepted", "CapabilityAccepted", "InteractionRequested", "InteractionAnswered", "StepCompleted"];
+type AcceptedKind = (typeof acceptedKinds)[number];
+export type AcceptedValue = {
+    [K in AcceptedKind]: {
+        readonly version: 1;
+        readonly kind: K;
+        readonly stepId: string;
+        readonly valueType: string | null;
+        readonly payload: unknown | null;
+    };
+}[AcceptedKind];
+export declare function inspectAccepted(options: {
+    ledgerPath: string;
+    runId: string;
+}): Promise<readonly AcceptedValue[]>;
+export declare function run<TState>(graph: Pipeline<TState>, initial: unknown, options?: RunOptions): Promise<RunResult<TState>>;
+export {};