@nanobpm/agentic 0.1.0 → 0.4.0

package/README.md

@@ -16,6 +16,7 @@ The **Nano agentic protocol** (ADR 0056): one app-tier channel carrying agent pr
 | `@nanobpm/agentic/transcript` | Transcript store, retention-by-lifecycle (S6) |
 | `@nanobpm/agentic/blackboard` | Blackboard channel family (S7) |
 | `@nanobpm/agentic/cockpit` | Operator visibility page — the cockpit (S8) |
+| `@nanobpm/agentic/session` | Canonical `SessionEvent` + authoritative session log for durable agent-session resume (ADR 0062) |
 
 The barrel `@nanobpm/agentic` re-exports each family as a namespace (`protocol`, `channel`, …). The worker-side client ships separately as `@nanobpm/urban-agent-client`.
 

package/dist/demand/model.d.ts

@@ -34,10 +34,13 @@ export interface DemandSupplyReport {
     /** The overall SLO state: worst of the missing-agent signal and diversity. */
     readonly status: SloStatus;
     /**
-     * Deployed `taskDefinition` types that are NOT valid routing tokens — ordinary
-     * (non-agentic) C8 jobs the engine also runs. Surfaced (not silently dropped)
-     * so an operator can spot a mistyped agentic token, but excluded from the
-     * agentic demand×supply accounting.
+     * Deployed `taskDefinition` types that carry NO `linkName="prompt"` linked
+     * resource — ordinary (non-agentic) in-process C8 jobs the engine also runs
+     * (e.g. the deterministic `pr.*` workers). Classification is by the prompt
+     * signal, not the token string, so a prompt-less type is `nonAgentic` even when
+     * it happens to parse as a routing token. Surfaced (not silently dropped) so an
+     * operator can spot a mis-modelled task, but excluded from the agentic
+     * demand×supply accounting.
      */
     readonly nonAgentic: readonly string[];
 }

package/dist/demand/model.js

@@ -31,7 +31,15 @@ const SEVERITY = { green: 0, amber: 1, red: 2 };
 function worst(a, b) {
     return SEVERITY[a] >= SEVERITY[b] ? a : b;
 }
-/** A demanded token's network-prefix bucket, or `undefined` if not a routing token. */
+/**
+ * A demanded token's bucket. For a valid routing token this is its network
+ * prefix (or a bare token's own role). For an arbitrary agentic type that is not
+ * a routing token (colon-form `senior:retro`, etc.) this is best-effort: the
+ * segment before the first `:` when present, else the whole type — a synthetic
+ * bucket so the leaf still surfaces as demand rather than being dropped. This is
+ * only ever called for prompt-bearing (agentic) leaves; non-agentic leaves are
+ * classified out before bucketing.
+ */
 function bucketOf(token) {
     try {
         const parsed = parseToken(token);
@@ -39,7 +47,8 @@ function bucketOf(token) {
         return parsed.network ?? parsed.role;
     }
     catch {
-        return undefined;
+        const colon = token.indexOf(":");
+        return colon > 0 ? token.slice(0, colon) : token;
     }
 }
 function sortedUnique(values) {
@@ -67,14 +76,23 @@ export function computeDemandSupply(input) {
         }
     }
     const demandTokens = distinctTaskTypes(input.taskDefinitions);
+    // Agentic-ness is the prompt signal, OR-folded across every leaf of a type: a
+    // type is agentic demand iff at least one deployed leaf carries a
+    // `linkName="prompt"` linked resource. This is independent of the type string,
+    // so colon-form fleet types (`senior:retro`) are admitted and prompt-less
+    // deterministic `pr.*` tasks are excluded — regardless of token grammar.
+    const agenticByToken = new Map();
+    for (const leaf of input.taskDefinitions) {
+        agenticByToken.set(leaf.taskType, (agenticByToken.get(leaf.taskType) ?? false) || leaf.agentic);
+    }
     const byNetwork = new Map();
     const nonAgentic = [];
     for (const token of demandTokens) {
-        const network = bucketOf(token);
-        if (network === undefined) {
+        if (!(agenticByToken.get(token) ?? false)) {
             nonAgentic.push(token);
             continue;
         }
+        const network = bucketOf(token);
         const instances = sortedUnique(supplyByToken.get(token) ?? []);
         const demand = {
             token,

package/dist/demand/taskdef.d.ts

@@ -21,6 +21,17 @@ export interface TaskDefinitionLeaf {
     readonly process: string;
     /** The service-task element id carrying the leaf (best-effort, may be empty). */
     readonly elementId: string;
+    /**
+     * True when the service task carries a `<zeebe:linkedResource … linkName="prompt">`
+     * — its base-prompt side-car. This is the *structural* agentic signal (per nwf
+     * `SPEC.md` §"Agent job contract"): every external agent task delivers its base
+     * prompt through a `linkName="prompt"` linked resource, and no in-process
+     * (deterministic) worker task does. Agentic-ness is read from this flag, NOT
+     * from the `taskType` string — the deployed models use arbitrary type strings
+     * (colon-form `senior:retro`, dot-form, bare) that a routing-token grammar
+     * would mis-classify.
+     */
+    readonly agentic: boolean;
 }
 /**
  * Scan one BPMN document for its service-task `taskDefinition` leaves.
@@ -28,7 +39,8 @@ export interface TaskDefinitionLeaf {
  * Every `<bpmn:serviceTask>` carrying a `<zeebe:taskDefinition type="…">` with a
  * non-empty type yields a leaf; tasks without a task definition (or with an empty
  * type) are skipped. The scan is order-preserving and tolerant of attribute
- * ordering and self-closing task-definition tags.
+ * ordering and self-closing task-definition tags. Each leaf also records whether
+ * the task carries a `linkName="prompt"` linked resource (its `agentic` flag).
  */
 export declare function scanTaskDefinitions(xml: string): TaskDefinitionLeaf[];
 /**

package/dist/demand/taskdef.js

@@ -21,13 +21,31 @@ function processId(xml) {
     const match = xml.match(/<bpmn:process\b[^>]*\bid\s*=\s*"([^"]*)"/);
     return match ? match[1] : "";
 }
+/**
+ * True when a service-task body carries a `linkName="prompt"` linked resource —
+ * the base-prompt side-car that marks a task as external agentic work.
+ *
+ * Scans every `<zeebe:linkedResource …>` in the body (tolerating attribute
+ * ordering and self-closing tags, consistent with {@link scanTaskDefinitions})
+ * and returns true as soon as one carries `linkName="prompt"`.
+ */
+function hasPromptLink(body) {
+    const linkRe = /<zeebe:linkedResource\b[^>]*?\/?>/g;
+    let link;
+    while ((link = linkRe.exec(body)) !== null) {
+        if (attr(link[0], "linkName") === "prompt")
+            return true;
+    }
+    return false;
+}
 /**
  * Scan one BPMN document for its service-task `taskDefinition` leaves.
  *
  * Every `<bpmn:serviceTask>` carrying a `<zeebe:taskDefinition type="…">` with a
  * non-empty type yields a leaf; tasks without a task definition (or with an empty
  * type) are skipped. The scan is order-preserving and tolerant of attribute
- * ordering and self-closing task-definition tags.
+ * ordering and self-closing task-definition tags. Each leaf also records whether
+ * the task carries a `linkName="prompt"` linked resource (its `agentic` flag).
  */
 export function scanTaskDefinitions(xml) {
     const proc = processId(xml);
@@ -44,7 +62,7 @@ export function scanTaskDefinitions(xml) {
         const taskType = attr(tdMatch[0], "type");
         if (!taskType)
             continue;
-        out.push({ taskType, elementId, process: proc });
+        out.push({ taskType, elementId, process: proc, agentic: hasPromptLink(body) });
     }
     return out;
 }

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * as presence from "./presence/index.ts";
 export * as vocab from "./vocab/index.ts";
 export * as demand from "./demand/index.ts";
 export * as relay from "./relay/index.ts";
+export * as session from "./session/index.ts";
 export * as transcript from "./transcript/index.ts";
 export * as blackboard from "./blackboard/index.ts";
 export * as cockpit from "./cockpit/index.ts";

package/dist/index.js

@@ -12,6 +12,7 @@ export * as presence from "./presence/index.js";
 export * as vocab from "./vocab/index.js";
 export * as demand from "./demand/index.js";
 export * as relay from "./relay/index.js";
+export * as session from "./session/index.js";
 export * as transcript from "./transcript/index.js";
 export * as blackboard from "./blackboard/index.js";
 export * as cockpit from "./cockpit/index.js";

package/dist/protocol/conformance/frames.js

@@ -75,15 +75,43 @@ export const GOLDEN_FRAMES = [
         hex: "4e4101010600000065000000187b226f70223a2272656164222c2273696e6365223a31327d",
     },
     {
-        name: "relay-chunk-bulk",
+        name: "relay-produce-bulk",
         direction: "worker->hub",
         frame: {
             lane: "bulk",
             family: "relay",
             seq: 5,
-            payload: { stream: "job-1223", offset: 2048, chunk: "hello world\n" },
+            payload: { op: "produce", stream: "job-1223", incarnation: 1, chunk: "hello world\n" },
         },
-        hex: "4e41010207000000050000003b7b2273747265616d223a226a6f622d31323233222c226f6666736574223a323034382c226368756e6b223a2268656c6c6f20776f726c645c6e227d",
+        hex: "4e41010207000000050000004c7b226f70223a2270726f64756365222c2273747265616d223a226a6f622d31323233222c22696e6361726e6174696f6e223a312c226368756e6b223a2268656c6c6f20776f726c645c6e227d",
+    },
+    {
+        name: "relay-subscribe-control",
+        direction: "worker->hub",
+        frame: {
+            lane: "control",
+            family: "relay",
+            seq: 6,
+            payload: { op: "subscribe", stream: "job-1223", from: 0, credit: 1024 },
+        },
+        hex: "4e41010007000000060000003d7b226f70223a22737562736372696265222c2273747265616d223a226a6f622d31323233222c2266726f6d223a302c22637265646974223a313032347d",
+    },
+    {
+        name: "relay-credit-control",
+        direction: "worker->hub",
+        frame: { lane: "control", family: "relay", seq: 7, payload: { op: "credit", credit: 512 } },
+        hex: "4e41010007000000070000001c7b226f70223a22637265646974222c22637265646974223a3531327d",
+    },
+    {
+        name: "relay-subscribed-ack-control",
+        direction: "hub->worker",
+        frame: {
+            lane: "control",
+            family: "relay",
+            seq: 8,
+            payload: { op: "subscribed", stream: "job-1223", gap: false, nextOffset: 2048 },
+        },
+        hex: "4e4101000700000008000000457b226f70223a2273756273637269626564222c2273747265616d223a226a6f622d31323233222c22676170223a66616c73652c226e6578744f6666736574223a323034387d",
     },
     {
         name: "relay-seq-max-bulk",
@@ -104,7 +132,7 @@ export const GOLDEN_FRAMES = [
     },
     {
         name: "unicode-payload-relay",
-        direction: "worker->hub",
+        direction: "hub->worker",
         frame: {
             lane: "bulk",
             family: "relay",

package/dist/protocol/index.d.ts

@@ -19,5 +19,5 @@ export { QOS_LANES, LANE_CODES, laneForCode, lanePriority, isQosLane, compareFra
 export { encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, FRAME_MAGIC, FRAME_VERSION, FRAME_HEADER_BYTES, MAX_SEQ, type Frame, type FrameDecodeErrorCode, type FrameEncodeErrorCode, } from "./frame.ts";
 export { parseToken, formatToken, isValidToken, isSegmentName, isSeatLabel, TokenParseError, type RoutingToken, type TokenParseErrorCode, } from "./token.ts";
 export { validateVocabDocument, type VocabDocument, type VocabNetwork, type VocabRole, type VocabError, type VocabValidationResult, } from "./vocab/schema.ts";
-export { validatePayload, type Capability, type RegisterPayload, type HeartbeatPayload, type DeregisterPayload, type ServePayload, type DemandPayload, type BlackboardPayload, type BlackboardOp, type RelayPayload, type PayloadError, type PayloadValidationResult, } from "./payloads.ts";
+export { validatePayload, type Capability, type RegisterPayload, type HeartbeatPayload, type DeregisterPayload, type ServePayload, type DemandPayload, type BlackboardPayload, type BlackboardOp, type RelayPayload, type RelayProducePayload, type RelaySubscribePayload, type RelayCreditPayload, type RelaySubscribedPayload, type PayloadError, type PayloadValidationResult, } from "./payloads.ts";
 export { bytesToHex, hexToBytes } from "./hex.ts";

package/dist/protocol/payloads.d.ts

@@ -43,11 +43,55 @@ export interface BlackboardPayload {
     readonly dedupeKey?: string;
     readonly since?: number;
 }
+/**
+ * The `relay` family multiplexes two roles on one message family:
+ *
+ *  - CONTROL frames a peer sends the hub: a producer's {@link RelayProducePayload}
+ *    (`op: "produce"`), and a consumer's {@link RelaySubscribePayload} /
+ *    {@link RelayCreditPayload}.
+ *  - DELIVERY frames the hub sends a consumer: a data chunk ({@link RelayPayload},
+ *    no `op`) and a resume ack ({@link RelaySubscribedPayload}, `op: "subscribed"`).
+ *
+ * {@link RelayPayload} is the DELIVERY data chunk specifically (`{ stream, offset,
+ * chunk }`, no `op`) — the hub assigns the authoritative `offset` from its ring.
+ * A producer must NOT send this shape; it sends {@link RelayProducePayload}.
+ */
 export interface RelayPayload {
     readonly stream: string;
     readonly offset: number;
     readonly chunk: string;
 }
+/** A producer appends bytes to a stream. `incarnation` is the producer's
+ * generation, stamped so the hub can fence a stale predecessor (a retried job on
+ * a fresh runner takes over with a strictly higher incarnation). The hub assigns
+ * the offset — a producer never carries one. */
+export interface RelayProducePayload {
+    readonly op: "produce";
+    readonly stream: string;
+    readonly incarnation: number;
+    readonly chunk: string;
+}
+/** A consumer subscribes to a stream, optionally resuming from `from` with an
+ * initial `credit` budget. */
+export interface RelaySubscribePayload {
+    readonly op: "subscribe";
+    readonly stream: string;
+    readonly from?: number;
+    readonly credit?: number;
+}
+/** A consumer replenishes its flow-control budget. */
+export interface RelayCreditPayload {
+    readonly op: "credit";
+    readonly credit: number;
+}
+/** The hub's ack to a subscribe: `gap` is true when `from` predated the retained
+ * ring (bytes were missed), `nextOffset` is where delivery resumes. */
+export interface RelaySubscribedPayload {
+    readonly op: "subscribed";
+    readonly stream: string;
+    readonly gap: boolean;
+    readonly nextOffset: number;
+}
 export interface PayloadError {
     readonly code: string;
     readonly message: string;

package/dist/protocol/payloads.js

@@ -6,6 +6,9 @@ function isPlainObject(value) {
 function nonEmptyString(value) {
     return typeof value === "string" && value.length > 0;
 }
+function nonNegInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
 function validateRegister(p, errors) {
     if (!nonEmptyString(p.instance)) {
         errors.push({ code: "bad-instance", message: "register.instance must be a non-empty string" });
@@ -74,14 +77,65 @@ function validateBlackboard(p, errors) {
     }
 }
 function validateRelay(p, errors) {
-    if (!nonEmptyString(p.stream)) {
-        errors.push({ code: "bad-stream", message: "relay.stream must be a non-empty string" });
-    }
-    if (typeof p.offset !== "number" || !Number.isInteger(p.offset) || p.offset < 0) {
-        errors.push({ code: "bad-offset", message: "relay.offset must be a non-negative integer" });
+    const op = p.op;
+    // No `op`: a DELIVERY data chunk (hub -> consumer) — `{ stream, offset, chunk }`.
+    if (op === undefined) {
+        if (!nonEmptyString(p.stream)) {
+            errors.push({ code: "bad-stream", message: "relay.stream must be a non-empty string" });
+        }
+        if (!nonNegInt(p.offset)) {
+            errors.push({ code: "bad-offset", message: "relay.offset must be a non-negative integer" });
+        }
+        if (typeof p.chunk !== "string") {
+            errors.push({ code: "bad-chunk", message: "relay.chunk must be a string" });
+        }
+        return;
     }
-    if (typeof p.chunk !== "string") {
-        errors.push({ code: "bad-chunk", message: "relay.chunk must be a string" });
+    // Otherwise an op-tagged CONTROL/ack frame.
+    switch (op) {
+        case "produce":
+            if (!nonEmptyString(p.stream)) {
+                errors.push({ code: "bad-stream", message: "relay.produce.stream must be a non-empty string" });
+            }
+            if (!nonNegInt(p.incarnation)) {
+                errors.push({ code: "bad-incarnation", message: "relay.produce.incarnation must be a non-negative integer" });
+            }
+            if (typeof p.chunk !== "string") {
+                errors.push({ code: "bad-chunk", message: "relay.produce.chunk must be a string" });
+            }
+            return;
+        case "subscribe":
+            if (!nonEmptyString(p.stream)) {
+                errors.push({ code: "bad-stream", message: "relay.subscribe.stream must be a non-empty string" });
+            }
+            if ("from" in p && !nonNegInt(p.from)) {
+                errors.push({ code: "bad-from", message: "relay.subscribe.from must be a non-negative integer when present" });
+            }
+            if ("credit" in p && !nonNegInt(p.credit)) {
+                errors.push({ code: "bad-credit", message: "relay.subscribe.credit must be a non-negative integer when present" });
+            }
+            return;
+        case "credit":
+            if (!nonNegInt(p.credit)) {
+                errors.push({ code: "bad-credit", message: "relay.credit.credit must be a non-negative integer" });
+            }
+            return;
+        case "subscribed":
+            if (!nonEmptyString(p.stream)) {
+                errors.push({ code: "bad-stream", message: "relay.subscribed.stream must be a non-empty string" });
+            }
+            if (typeof p.gap !== "boolean") {
+                errors.push({ code: "bad-gap", message: "relay.subscribed.gap must be a boolean" });
+            }
+            if (!nonNegInt(p.nextOffset)) {
+                errors.push({ code: "bad-next-offset", message: "relay.subscribed.nextOffset must be a non-negative integer" });
+            }
+            return;
+        default:
+            errors.push({
+                code: "bad-op",
+                message: `relay.op must be one of produce|subscribe|credit|subscribed, got ${String(op)}`,
+            });
     }
 }
 /**

package/dist/session/acp/client.d.ts

@@ -0,0 +1,109 @@
+import type { SessionEvent } from "../events.ts";
+import { AcpConnection } from "./jsonrpc.ts";
+import { type AcpPromptCapabilities } from "./protocol.ts";
+import type { AcpTransport } from "./transport.ts";
+/**
+ * The narrow port the ingestion client writes canonical events to. A Slice-1
+ * {@link SessionAdapter} (e.g. a `SessionBackend`) satisfies it structurally, so
+ * the ACP stream can feed the authoritative log directly; a test can pass a
+ * plain collector.
+ */
+export interface SessionEventSink {
+    emit(event: SessionEvent): void;
+}
+/** A single ACP content block sent in a prompt. `text` is the baseline shape. */
+export interface AcpTextContentBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+/** The prompt payload: a content-block array, or a bare string (wrapped as text). */
+export type AcpPromptInput = string | readonly AcpTextContentBlock[];
+/** The durable-resume capability probe read from the `initialize` handshake. */
+export interface AcpCapabilityProbe {
+    /** The protocol version the agent negotiated. */
+    readonly protocolVersion: number;
+    /** The raw `agentCapabilities.loadSession` flag. */
+    readonly loadSession: boolean;
+    /**
+     * The nano-workforce enrolment-gate signal (slice 5): `true` iff the agent can
+     * durably resume via `session/load`. Equal to {@link loadSession} — named for
+     * the gate that consumes it, so the enrolment site reads intent, not wire detail.
+     */
+    readonly durableResume: boolean;
+    /** The agent's advertised prompt-content capabilities. */
+    readonly promptCapabilities: AcpPromptCapabilities;
+    /** The full, unmodified `agentCapabilities` object for consumers that need more. */
+    readonly agentCapabilities: unknown;
+}
+/** The result of a completed `session/prompt`, plus the events it produced. */
+export interface AcpPromptResult {
+    /** The agent's stop reason (`end_turn`, `cancelled`, …) when it reports one. */
+    readonly stopReason: string | null;
+    /** The canonical events emitted while this prompt ran, in emission order. */
+    readonly events: readonly SessionEvent[];
+}
+/** Parameters shared by `session/new` and `session/load`. */
+export interface AcpSessionParams {
+    /** The session working directory (absolute path). */
+    readonly cwd: string;
+    /** MCP servers to attach; defaults to none. */
+    readonly mcpServers?: readonly unknown[];
+}
+export interface AcpSessionClientOptions {
+    /** Injectable event-id generator (deterministic tests). Default `crypto.randomUUID`. */
+    readonly newEventId?: () => string;
+    /** Client name/version reported in `initialize`. */
+    readonly clientInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /**
+     * How to answer an agent's `session/request_permission`. Default: select the
+     * first "allow"-flavoured option the agent offers (or a cancel outcome when
+     * none is), so a driven session is never silently blocked on approval.
+     */
+    readonly onPermissionRequest?: (params: unknown) => unknown;
+}
+/**
+ * The ACP ingestion client. Bind it to a transport and a sink, `initialize`, then
+ * either `newSession` + `prompt` (drive) or `restore` an existing session id.
+ */
+export declare class AcpSessionClient {
+    #private;
+    constructor(connection: AcpConnection, sink: SessionEventSink, options?: AcpSessionClientOptions);
+    /** The active session id (after `newSession`/`restore`), or `undefined`. */
+    get sessionId(): string | undefined;
+    /**
+     * Perform the `initialize` handshake and return the durable-resume capability
+     * probe. Must be called before any `session/*` method.
+     */
+    initialize(): Promise<AcpCapabilityProbe>;
+    /** Open a fresh session (`session/new`); stores and returns its id. */
+    newSession(params: AcpSessionParams): Promise<string>;
+    /**
+     * **restore** — load an existing session (`session/load`). The agent replays its
+     * prior history as `session/update` notifications, which this client ingests
+     * into the sink; when the load resolves, the pending message is flushed. Returns
+     * the canonical events reconstructed from the replayed history, in order.
+     *
+     * Only valid against an agent whose probe reported `durableResume: true`.
+     */
+    restore(sessionId: string, params: AcpSessionParams): Promise<readonly SessionEvent[]>;
+    /**
+     * **drive** — send a prompt (`session/prompt`) and resolve when the turn ends.
+     * All assistant output arrives as `session/update` notifications and is emitted
+     * to the sink during the call; the final buffered message is flushed on
+     * completion.
+     */
+    prompt(input: AcpPromptInput): Promise<AcpPromptResult>;
+    /** **steer** — request cancellation of the running turn (`session/cancel`, a notification). */
+    cancel(): void;
+    /** Close the underlying connection and flush any pending buffered message. */
+    close(): void;
+}
+/**
+ * Open an ACP ingestion client over `transport`, emitting into `sink`. Wraps the
+ * transport in an {@link AcpConnection} and returns the ready client; call
+ * {@link AcpSessionClient.initialize} first.
+ */
+export declare function openAcpSession(transport: AcpTransport, sink: SessionEventSink, options?: AcpSessionClientOptions): AcpSessionClient;