@boardwalk-labs/workflow 0.1.0 → 0.1.2

package/README.md

@@ -27,11 +27,11 @@ A workflow is **a script**: the `meta` export is a **pure literal** (engines der
 
 | Import                             | What it is                                                                                                                                                                                                    |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@boardwalk-labs/workflow`         | The author API: `agent()`, `sleep()`, `workflows.call()`, `secrets.get()`, `artifacts.write()`, `parallel()`, `input` / `output()` / `config`, `Phase()` — plus the manifest schema and run-event wire format |
+| `@boardwalk-labs/workflow`         | The author API: `agent()`, `sleep()`, `workflows.call()`, `secrets.get()`, `artifacts.write()`, `parallel()`, `input` / `output()` / `config`, `phase()` — plus the manifest schema and run-event wire format |
 | `@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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // The run-event wire format — one typed, ordered stream per run, identical in every engine.
 //
 // Every event carries an envelope (runId, turnId, per-turn 1-based seq, server timestamp) and
@@ -96,10 +97,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/extract.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // @boardwalk-labs/workflow/extract — static extraction of a workflow program's `meta` → manifest.
 //
 // A workflow is a TS/JS program file whose `export const meta = { … }` is a PURE LITERAL.

package/dist/host.js

@@ -1,14 +1,4 @@
-// The host seam — the engine-implementation boundary of the SDK.
-//
-// `@boardwalk-labs/workflow` is a host-backed package: the hooks authors import (agent, sleep,
-// workflows.call, secrets.get, input) are thin facades over a `WorkflowHost` the *engine*
-// installs at runtime. hosted Boardwalk installs its hosted adapter; the local engine installs
-// one backed by the developer's environment. The author's program is identical either way —
-// explicit hooks instead of injected globals.
-//
-// State is a module-level singleton. Node ESM caches a module by resolved path, so the
-// program (which imports the hooks) and the engine (which installs the host) share ONE
-// instance of this module and therefore one host + one `input`.
+// SPDX-License-Identifier: MIT
 let currentHost = null;
 /**
  * The trigger payload for the current run, exposed to the program as

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import type { AgentOptions, ArtifactBody, ArtifactRef, CallOptions, JsonValue, PhaseOptions, SleepArg } from "./types.js";
 /**
  * Mark the current run phase for live-tail and run-log grouping. Everything after this call
- * belongs to the named phase until the next `Phase(...)` marker or the run ends. This is
+ * belongs to the named phase until the next `phase(...)` marker or the run ends. This is
  * observability-only; it does not checkpoint or skip code on restart.
  */
-export declare function Phase(name: string, opts?: PhaseOptions): void;
+export declare function phase(name: string, opts?: PhaseOptions): void;
 /**
  * Run an agent leaf to completion. Without `opts.schema`, resolves to the leaf's final text
  * (`T` defaults to `string`); with a schema, resolves to the validated object — pass the

package/dist/index.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // @boardwalk-labs/workflow — the author-facing API a workflow program imports.
 //
 //   import { agent, workflows, sleep, secrets, input, type WorkflowMeta } from "@boardwalk-labs/workflow"
@@ -13,13 +14,13 @@
 import { requireHost, recordOutput } from "./host.js";
 /**
  * Mark the current run phase for live-tail and run-log grouping. Everything after this call
- * belongs to the named phase until the next `Phase(...)` marker or the run ends. This is
+ * belongs to the named phase until the next `phase(...)` marker or the run ends. This is
  * observability-only; it does not checkpoint or skip code on restart.
  */
-export function Phase(name, opts) {
+export function phase(name, opts) {
     const host = requireHost();
     if (host.setPhase === undefined) {
-        throw new Error("Phase is not supported by the installed engine");
+        throw new Error("phase is not supported by the installed engine");
     }
     host.setPhase(name, opts);
 }

package/dist/manifest.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // workflowManifestSchema — the validator of record for a workflow's `meta`.
 //
 // One Zod schema, consumed by every engine (local `dev`, the self-hosted server, Boardwalk

package/dist/meta.js

@@ -1,8 +1,2 @@
-// WorkflowMeta — the TypeScript shape of a workflow's `meta` export.
-//
-// A workflow program declares `export const meta = { … } satisfies WorkflowMeta`. The
-// `satisfies` operator is type-only and erased at compile time, so it does NOT break the
-// pure-literal static extraction engines perform over the source (see extract.ts). This type
-// is the author-facing typing; `workflowManifestSchema` (manifest.ts) is the validator of
-// record — the two are kept faithful to each other.
+// SPDX-License-Identifier: MIT
 export {};

package/dist/runtime.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // @boardwalk-labs/workflow/runtime — the ENGINE-facing API.
 //
 // An engine imports this to install the host adapter and the trigger payload BEFORE

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.
@@ -89,7 +97,7 @@ export type SleepArg = number | {
 } | {
     until: string | Date;
 };
-/** Options for {@link import("./index.js").Phase}, the run-timeline marker. */
+/** Options for {@link import("./index.js").phase}, the run-timeline marker. */
 export interface PhaseOptions {
     /**
      * Optional stable identifier for the phase. Omit for the engine to assign one in marker order.

package/dist/types.js

@@ -1,2 +1,2 @@
-// Option/argument types for the workflow hooks (Phase, agent, workflows.call, sleep, secrets).
+// SPDX-License-Identifier: MIT
 export {};

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@boardwalk-labs/workflow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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"