@maxanstey-meridian/tandem 0.2.0 → 0.3.1

package/README.md

@@ -56,29 +56,19 @@ 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
-[examples](https://github.com/maxanstey-meridian/tandem-ts/tree/main/examples) for agents,
-capabilities, interactions, persistence, and complete examples.
-
-Licensed under the [MIT License](./LICENSE).
-
-For a specialised model that requires a plain user message, a raw-output agent
-can set both `instructions` and `output.instructions` to `""`. Tandem then sends
-the authored message without system instructions or a response-format constraint.
-Other agent/output modes still require nonblank instructions.
-
-## Development and publishing
+The package is ESM-only, and a project created by `npm init` is CommonJS, so save the code as
+`index.mts`:
 
 ```sh
-pnpm install
-pnpm build
-pnpm test
-npm pack
+node index.mts
 ```
 
-`npm pack` and `npm publish` build fresh output before packaging. The npm package contains
-`dist`, including the vendored platform bridge bundles in `dist/runtime`. Update each runtime
-bundle from a tested Tandem bridge build before releasing runtime changes.
+To use `index.ts` instead, first mark the project as ESM with `npm pkg set type=module`, then run
+`node index.ts`. Node.js 22.18 or newer runs TypeScript directly by stripping types; on older
+Node.js 22 releases, use `npx tsx index.mts`. The program prints `hello`.
+
+State holds application facts, participants perform work, and routes decide what runs next. See the
+[examples](#examples) for routing, persistence and complete model-backed pipelines.
 
 ## Runtime-sized collections
 
@@ -94,6 +84,33 @@ completion and sibling parallel agent calls are rejected. Operational failure
 fails the collection, drains active work, and skips application of results.
 
 ```ts
+import { collection, taskAgent, type ChatClient } from "@maxanstey-meridian/tandem";
+import { z } from "zod";
+
+const client = {
+  kind: "openai-compatible",
+  version: 1,
+  endpoint: "https://openrouter.ai/api/v1",
+  model: "deepseek/deepseek-v4-flash-0731",
+  wireApi: "completions",
+  apiKeyEnvironmentVariable: "OPENROUTER_API_KEY",
+} as const satisfies ChatClient;
+
+const Proposition = z.string();
+const Claim = z.object({ subject: z.string(), statement: z.string() });
+const SourceState = z.object({ propositions: z.array(Proposition), claims: z.array(Claim) });
+type SourceState = z.infer<typeof SourceState>;
+
+const canonicaliser = taskAgent({
+  id: "canonicaliser",
+  instructions: "Restate the proposition as one canonical claim.",
+  client,
+  input: Proposition,
+  result: Claim,
+  message: (proposition) => proposition,
+  output: { instructions: "Return the claim's subject and statement.", schema: Claim },
+});
+
 const canonicalise = collection({
   id: "canonicalise",
   item: Proposition,
@@ -102,11 +119,13 @@ const canonicalise = collection({
   max: 6,
   items: (state: SourceState) => state.propositions,
   execute: (proposition, context) => context.run(canonicaliser, proposition),
-  apply: (state, claims) => ({ ...state, claims }),
+  apply: (state, claims) => ({ ...state, claims: [...claims] }),
 });
 ```
 
-The executable [collection example](tests/collection-child.ts) includes
+Add `canonicalise` to a pipeline's `nodes` and `routes` like any other participant.
+
+The executable [collection test](tests/collection-child.ts) includes
 conditional recovery, persistence, cancellation and concurrent source runs.
 Agent visits remain in the source run's native observations and ledger.
 
@@ -114,3 +133,74 @@ Agent definitions may be reused across collections. Native Tandem binds each und
 its collection name. Scoped observations and accepted ledger values carry a
 `visitId` so concurrent calls can be correlated without changing their semantic
 `stepId`.
+
+## Raw-output agents
+
+For a specialised model that requires a plain user message, a raw-output agent
+can set both `instructions` and `output.instructions` to `""`. Tandem then sends
+the authored message without system instructions or a response-format constraint.
+Other agent/output modes still require nonblank instructions.
+
+## Examples
+
+The [examples](https://github.com/maxanstey-meridian/tandem-ts/tree/main/examples) run from a
+clone of this repository. The getting-started examples need no model or API key; the songwriter,
+debate and code-writer examples need an OpenRouter API key. See
+[examples/README.md](https://github.com/maxanstey-meridian/tandem-ts/blob/main/examples/README.md)
+for the commands and environment variables.
+
+## Development and publishing
+
+This repository is a [pnpm](https://pnpm.io) workspace. `package.json` pins pnpm 11.22.0 in
+`packageManager`; a newer pnpm switches to that version on its own, or run
+`corepack enable pnpm`. Tests also need the .NET 10 runtime.
+
+```sh
+pnpm install
+pnpm build
+pnpm test
+npm pack
+```
+
+`npm pack` and `npm publish` build fresh output before packaging. The npm package contains
+`dist`, including the vendored platform bridge bundles in `dist/runtime`.
+
+### Repository layout
+
+- `src`: the published SDK. `runtime/loader.mjs` picks the bridge bundle for the current platform.
+- `runtime/darwin-arm64`, `runtime/linux-x64`: the vendored .NET bridge bundles, copied into
+  `dist/runtime` by `pnpm build`.
+- `packets`: `@maxanstey-meridian/tandem-packets`, which reads Markdown packet files with YAML
+  frontmatter into a Zod schema. `pnpm test` builds it.
+- `studio`: Tandem Studio, a local Nuxt viewer and route editor for the pipeline exported by a
+  `tandem.config.ts`. Run `pnpm -C studio build`, then `node ../../../studio/dist/cli.js` from
+  `examples/debate/typescript`. It has its own `typecheck` and `test` scripts.
+- `examples`: see [examples/README.md](examples/README.md).
+
+### Updating the runtime bundles
+
+The bundles are built from the [Tandem](https://github.com/maxanstey-meridian/tandem) .NET
+repository; only bundles from a tested Tandem build should be released. Each Tandem release attaches
+`tandem-bridge-<version>-darwin-arm64.tar.gz` and `tandem-bridge-<version>-linux-x64.tar.gz`;
+replace each platform's directory with its archive's contents:
+
+```sh
+rm -rf runtime/darwin-arm64 && mkdir runtime/darwin-arm64
+tar -xzf tandem-bridge-<version>-darwin-arm64.tar.gz -C runtime/darwin-arm64
+```
+
+To build a bundle from a Tandem checkout instead, run this there for each RID (`osx-arm64` for
+`darwin-arm64`, `linux-x64` for `linux-x64`), then replace the matching `runtime/<platform>`
+directory with `bridge-runtime/` (delete it first, so files the new build dropped do not linger):
+
+```sh
+dotnet publish bridge/Tandem.Bridge.csproj -c Release -p:Version=<version> -r osx-arm64 --self-contained false --output .runtime-publish
+node scripts/stage-runtime.mjs osx-arm64
+```
+
+Then run `pnpm test`, which exercises the bundle for the current platform. The Linux package
+workflow tests the linux-x64 bundle.
+
+## License
+
+Licensed under the [MIT License](./LICENSE).

package/dist/index.js

@@ -94,38 +94,6 @@ class CallbackRegistry {
         return id;
     }
 }
-// The bridge surfaces JS callback errors and .NET cancellations only as exception message text,
-// so these markers are how a failure's origin is recovered (until the bridge returns structured
-// errors).
-const CALLBACK_CONTRACT_MARKER = "TANDEM_CALLBACK_CONTRACT:";
-const CALLBACK_FAILURE_MARKER = "JavaScript callback failed:";
-const BRIDGE_CANCELLATION_MESSAGE = /\boperation was (?:cancell?ed|aborted)\b/i;
-const callbackFailureSchema = z.object({
-    boundary: z.string(),
-    problems: z.array(z.object({ path: z.string(), message: z.string() })),
-});
-function callbackContractFailure(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const start = message.indexOf(CALLBACK_CONTRACT_MARKER);
-    if (start < 0) {
-        return null;
-    }
-    try {
-        const failure = callbackFailureSchema.safeParse(JSON.parse(message.slice(start + CALLBACK_CONTRACT_MARKER.length)));
-        return failure.success ? failure.data : null;
-    }
-    catch {
-        return null;
-    }
-}
-function isCancellation(error, signal) {
-    if (signal?.aborted) {
-        return true;
-    }
-    return (error instanceof Error &&
-        !error.message.includes(CALLBACK_FAILURE_MARKER) &&
-        (error.name === "AbortError" || BRIDGE_CANCELLATION_MESSAGE.test(error.message)));
-}
 function path(parts) {
     return parts.length === 0
         ? "$"
@@ -830,14 +798,28 @@ const acceptedValueFields = z
 const acceptedValuesSchema = z.array(acceptedValueFields.refine((value) => value.valueType !== null || value.payload !== null, {
     message: "valueType and payload cannot both be null",
 }));
-const runResultSchema = z
-    .object({
-    runId: z.uuid(),
-    succeeded: z.boolean(),
-    state: z.unknown(),
-    summary: z.string().nullable(),
-})
-    .strict();
+const validationProblemsSchema = z.array(z.object({ path: z.string(), message: z.string() }).strict());
+/** How the bridge reports the end of a run; only a bridge defect rejects instead. */
+const runEnvelopeSchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        status: z.enum(["succeeded", "failed"]),
+        runId: z.uuid(),
+        state: z.unknown(),
+        summary: z.string().nullable(),
+    })
+        .strict(),
+    z.object({ status: z.literal("cancelled"), runId: z.uuid() }).strict(),
+    z
+        .object({
+        status: z.literal("contract"),
+        runId: z.uuid(),
+        boundary: z.string(),
+        problems: validationProblemsSchema,
+    })
+        .strict(),
+    z.object({ status: z.literal("faulted"), runId: z.uuid(), message: z.string() }).strict(),
+]);
 /** Lazy (and cached by the module loader) so importing the authoring API never starts .NET. */
 const loadRuntime = () => import("./runtime/loader.mjs");
 export async function inspectAccepted(options) {
@@ -925,20 +907,28 @@ export async function run(graph, initial, options = {}) {
                 ? result
                 : callbackFailed(new Error(`Internal callback '${id}' is asynchronous.`));
         }, async (id, state, input, signal) => callbacks.invoke(id, state, input, signal), options.signal);
-        const result = parseJson(runResultSchema, resultJson, "run result");
-        return { ...result, state: parse(graph.state, result.state, "final state") };
+        const envelope = parseJson(runEnvelopeSchema, resultJson, "run result");
+        switch (envelope.status) {
+            case "succeeded":
+            case "failed":
+                return {
+                    runId: envelope.runId,
+                    succeeded: envelope.status === "succeeded",
+                    state: parse(graph.state, envelope.state, "final state"),
+                    summary: envelope.summary,
+                };
+            case "cancelled":
+                throw new TandemCancellationError(new Error("The run was cancelled."));
+            case "contract":
+                throw new ContractValidationError(envelope.boundary, envelope.problems);
+            case "faulted":
+                throw new TandemRuntimeError("run", new Error(envelope.message));
+        }
     }
     catch (error) {
         if (error instanceof TandemError) {
             throw error;
         }
-        const callbackFailure = callbackContractFailure(error);
-        if (callbackFailure) {
-            throw new ContractValidationError(callbackFailure.boundary, callbackFailure.problems);
-        }
-        if (isCancellation(error, options.signal)) {
-            throw new TandemCancellationError(error);
-        }
         throw new TandemRuntimeError("run", error);
     }
     finally {
@@ -962,7 +952,6 @@ function issues(schema, input) {
         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));
 }

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

@@ -1,4 +1,4 @@
-// Generated for: Tandem.NodeApiSpike.Bridge 0.1.0.0
+// Generated for: Tandem.Bridge 0.3.1.0
 // Generated by: Microsoft.JavaScript.NodeApi.Generator 0.9.0.0
 /* eslint-disable */
 

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

@@ -1,4 +1,4 @@
-// Generated for: Tandem.NodeApiSpike.Bridge 0.1.0.0
+// Generated for: Tandem.Bridge 0.3.1.0
 // Generated by: Microsoft.JavaScript.NodeApi.Generator 0.9.0.0
 /* eslint-disable */
 
@@ -20,7 +20,13 @@ export namespace NodePipelineBridge {
 		runId: string,
 	): Promise<string>;
 
-	/** Registers and runs a complete JavaScript-authored Tandem graph. */
+	/**
+	 * Registers and runs a complete JavaScript-authored Tandem graph and reports how it
+	 * ended as a {@link Tandem.Bridge.RunEnvelope}. Once a run is attempted every failure is
+	 * reported, because a fault raised inside the run cannot be told apart from a bridge
+	 * defect; a fault carries the full exception text. Only a caller without a JavaScript
+	 * synchronization context gets an exception.
+	 */
 	export function runRegisteredGraphAsync(
 		definitionJson: string,
 		invokeSyncCallback: Func$4<string, string, string, string>,