@boardwalk-labs/workflow 0.1.0 → 0.1.1

package/README.md

@@ -31,7 +31,7 @@ A workflow is **a script**: the `meta` export is a **pure literal** (engines der
 | `@boardwalk-labs/workflow/runtime` | The **engine-facing** API: install a `WorkflowHost` before evaluating a program. Authors never import this                                                                                                    |
 | `@boardwalk-labs/workflow/extract` | Static `meta` → manifest extraction (AST-based, never executes the program). Used by engines and tooling                                                                                                      |
 
-## The primitives, in one minute
+## The primitives
 
 - **`agent(prompt, opts?)`** — run an agent loop and get its final text (or `schema`-validated JSON). `model` is optional: name one explicitly, or let the engine resolve it. Loops can use **tools** (built-in or program-defined), **MCP servers**, **skills**, and **memory** — each brought **per call** on `agent()`; the manifest declares none of them.
 - **`sleep(ms | { until })`** — durable wait; the run holds, locals survive.
@@ -42,7 +42,7 @@ A workflow is **a script**: the `meta` export is a **pure literal** (engines der
 
 ## Where workflows run
 
-One file, three engines: `boardwalk dev` (run it now, locally, no account), the self-hosted Boardwalk engine (your server), or [the Boardwalk platform](https://boardwalk.sh) (`boardwalk deploy` — hosted, scheduled, with automatic model routing). The same manifest schema and event stream everywhere; engine differences are limited to documented resolution behavior.
+The same file runs on three engines: `boardwalk dev` (locally, no account), the self-hosted Boardwalk engine (your own server), or [the Boardwalk platform](https://boardwalk.sh) (`boardwalk deploy` — hosted, scheduled, with automatic model routing). The manifest schema and event stream are the same everywhere; engine differences are limited to documented resolution behavior.
 
 The full authoring contract — every primitive, the manifest field inventory, and the run-event wire format — is in [`SPEC.md`](./SPEC.md).
 

package/dist/events.d.ts

@@ -64,13 +64,14 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     seq: z.ZodNumber;
     t: z.ZodNumber;
 }, z.core.$strict>, z.ZodObject<{
+    agentId: z.ZodString;
+    agentName: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"turn_started">;
     runId: z.ZodString;
     turnId: z.ZodString;
     seq: z.ZodNumber;
     t: z.ZodNumber;
 }, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"turn_ended">;
     reason: z.ZodEnum<{
         error: "error";
         cancelled: "cancelled";
@@ -87,6 +88,9 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
     }, z.core.$strict>>;
+    agentId: z.ZodString;
+    agentName: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"turn_ended">;
     runId: z.ZodString;
     turnId: z.ZodString;
     seq: z.ZodNumber;

package/dist/events.js

@@ -96,10 +96,29 @@ const programOutputEvent = z.strictObject({
     text: z.string(),
 });
 // -- agent channel ----------------------------------------------------------------
-const turnStarted = z.strictObject({ ...envelopeShape, kind: z.literal("turn_started") });
+//
+// `turn_started`/`turn_ended` bracket the turns of ONE `agent()` leaf and carry that leaf's
+// identity: a stable, run-unique `agentId` (engine-assigned) and the author's optional
+// `agentName` (from `AgentOptions.name`). The high-frequency frames in between (text/tool/
+// reasoning) stay lean — a consumer attributes them to a leaf by their envelope `turnId`, which
+// the bracketing `turn_started` maps to its `agentId`/`agentName`. This is what lets a viewer
+// tell concurrent agents apart instead of seeing one interleaved blur.
+/** Identity of the `agent()` leaf a turn belongs to (shared by its turn_started/turn_ended). */
+const agentIdentityShape = {
+    /** Stable, run-unique id for the `agent()` call. Engine-assigned; same across all its turns. */
+    agentId: z.string().min(1),
+    /** The author's `AgentOptions.name`, if one was given. Display-only; absent otherwise. */
+    agentName: z.string().min(1).optional(),
+};
+const turnStarted = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("turn_started"),
+    ...agentIdentityShape,
+});
 const turnEnded = z.strictObject({
     ...envelopeShape,
     kind: z.literal("turn_ended"),
+    ...agentIdentityShape,
     reason: z.enum(["complete", "cancelled", "error"]),
     usage: tokenUsageSchema.optional(),
     error: eventErrorSchema.optional(),

package/dist/types.d.ts

@@ -26,6 +26,14 @@ export interface ToolDef {
  * declares none of them. A plain `agent(prompt)` is simple inference.
  */
 export interface AgentOptions {
+    /**
+     * A human label for this leaf, echoed onto its `turn_started`/`turn_ended` events as
+     * `agentName`. Purely for display — it lets a stream consumer tell concurrent agents apart
+     * (e.g. a `reviewer` and a `summarizer` running under `parallel`). It is NOT an identifier and
+     * need not be unique; the engine always assigns a stable, run-unique `agentId` regardless.
+     * Defaults to none (consumers fall back to a generic label).
+     */
+    name?: string;
     /**
      * The model, as an OPAQUE string passed VERBATIM to the provider — engines never parse,
      * prefix, or rewrite it. Use whatever identifier your provider expects (e.g.

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@boardwalk-labs/workflow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Author Boardwalk workflows in TypeScript: agent(), sleep(), workflows.call(), secrets, the manifest schema, and the run-event wire format.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boardwalk-labs/sdk.git"
+  },
+  "homepage": "https://github.com/boardwalk-labs/sdk#readme",
   "type": "module",
   "engines": {
     "node": ">=24"