@nanobpm/agentic 0.1.0

package/dist/cockpit/view.js

@@ -0,0 +1,58 @@
+function tokenRow(token) {
+    return {
+        token: token.token,
+        supply: token.supply,
+        instances: token.instances,
+        satisfied: token.satisfied,
+        status: token.satisfied ? "green" : "red",
+    };
+}
+function networkRow(network) {
+    return {
+        network: network.network,
+        tokens: network.tokens.map(tokenRow),
+        missing: network.missing,
+        status: network.missing.length > 0 ? "red" : "green",
+    };
+}
+function missingLight(token) {
+    return {
+        id: `missing:${token}`,
+        label: token,
+        status: "red",
+        detail: "missing agent type — no registered worker serves this token",
+    };
+}
+function diversityDetail(diversity) {
+    const offenders = diversity.roles.filter((role) => role.status !== "green");
+    if (offenders.length === 0)
+        return "family(#red) ≠ family(#blue) holds for every role";
+    return offenders
+        .map((role) => `${role.token}: ${role.collidingFamilies.join(", ")} (${role.status})`)
+        .join("; ");
+}
+function diversityLight(diversity) {
+    return {
+        id: "diversity",
+        label: "diversity SLO",
+        status: diversity.status,
+        detail: diversityDetail(diversity),
+    };
+}
+/**
+ * Derive the renderable cockpit view from an S4 demand×supply report.
+ *
+ * Pure and total: every list is already sorted by S4, so the derived view is
+ * stable and diff-friendly; no input mutates and no I/O happens.
+ */
+export function cockpitView(report) {
+    return {
+        status: report.status,
+        networks: report.networks.map(networkRow),
+        missing: report.missing,
+        missingLights: report.missing.map(missingLight),
+        diversity: report.diversity,
+        diversityLight: diversityLight(report.diversity),
+        nonAgentic: report.nonAgentic,
+    };
+}

package/dist/demand/c8-rest.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Read deployed models' `taskDefinition` leaves from the engine's C8 REST API.
+ *
+ * S4 is a read-only mirror: it reads what the *engine* already has deployed and
+ * diffs it against live supply — it never places work. The Camunda-8 engine stays
+ * frozen (design invariant 2): we speak the ordinary C8 v2 REST API over the
+ * app's own HTTP client, on a connection entirely separate from the agentic
+ * channel and from the worker's C8 job protocol. Nothing here rides the engine's
+ * transport or mutates engine state.
+ *
+ * The concrete reader ({@link httpC8RestReader}) is a thin fetch adapter over two
+ * C8 v2 endpoints:
+ *
+ *  - `POST {rest}/process-definitions/search` → the deployed definition keys.
+ *  - `GET  {rest}/process-definitions/{key}/xml` → each definition's BPMN XML.
+ *
+ * It is expressed against a small structural {@link C8RestReader} seam so the
+ * model can be driven by an in-memory reader in tests without a live engine.
+ */
+import { type TaskDefinitionLeaf } from "./taskdef.ts";
+/**
+ * The minimal C8 REST surface the demand reader needs: enumerate deployed
+ * process-definition keys and fetch each one's BPMN XML. Structural so tests can
+ * supply an in-memory implementation.
+ */
+export interface C8RestReader {
+    /** Every deployed process-definition key currently known to the engine. */
+    searchProcessDefinitionKeys(): Promise<string[]>;
+    /** The BPMN XML of one process definition. */
+    getProcessDefinitionXml(processDefinitionKey: string): Promise<string>;
+}
+/** A `fetch`-shaped function, so the HTTP reader is testable without the global. */
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+/** Options for {@link httpC8RestReader}. */
+export interface HttpC8RestReaderOptions {
+    /** The C8 REST base address, e.g. `http://localhost:8080/v2`. */
+    readonly restAddress: string;
+    /** Optional bearer token for the C8 REST API. */
+    readonly token?: string;
+    /** Injected `fetch` (defaults to the global). */
+    readonly fetch?: FetchLike;
+    /** Search page size (C8 caps the result set; the reader pages until drained). Must be a positive integer. */
+    readonly pageSize?: number;
+}
+/**
+ * Build a {@link C8RestReader} backed by the live C8 v2 REST API.
+ *
+ * `searchProcessDefinitionKeys` pages `POST /process-definitions/search` until the
+ * engine returns fewer than a full page, de-duplicating keys. `getProcessDefinitionXml`
+ * reads `GET /process-definitions/{key}/xml`. Both raise on a non-2xx response so a
+ * misconfigured endpoint fails loudly rather than reporting phantom zero demand.
+ */
+export declare function httpC8RestReader(options: HttpC8RestReaderOptions): C8RestReader;
+/**
+ * Read every deployed model's `taskDefinition` leaves through a {@link C8RestReader}.
+ *
+ * Enumerates the deployed definitions, fetches each one's BPMN XML, and scans out
+ * its service-task task-definition leaves. The result is the raw demand corpus the
+ * {@link ./model.ts} model buckets and diffs against supply.
+ */
+export declare function readDeployedTaskDefinitions(reader: C8RestReader): Promise<TaskDefinitionLeaf[]>;
+/**
+ * Read the distinct demanded job types (routing tokens) from the engine — the
+ * convenience path for callers that only need the demand token set, not element
+ * provenance.
+ */
+export declare function readDeployedTaskTypes(reader: C8RestReader): Promise<string[]>;

package/dist/demand/c8-rest.js

@@ -0,0 +1,123 @@
+/**
+ * Read deployed models' `taskDefinition` leaves from the engine's C8 REST API.
+ *
+ * S4 is a read-only mirror: it reads what the *engine* already has deployed and
+ * diffs it against live supply — it never places work. The Camunda-8 engine stays
+ * frozen (design invariant 2): we speak the ordinary C8 v2 REST API over the
+ * app's own HTTP client, on a connection entirely separate from the agentic
+ * channel and from the worker's C8 job protocol. Nothing here rides the engine's
+ * transport or mutates engine state.
+ *
+ * The concrete reader ({@link httpC8RestReader}) is a thin fetch adapter over two
+ * C8 v2 endpoints:
+ *
+ *  - `POST {rest}/process-definitions/search` → the deployed definition keys.
+ *  - `GET  {rest}/process-definitions/{key}/xml` → each definition's BPMN XML.
+ *
+ * It is expressed against a small structural {@link C8RestReader} seam so the
+ * model can be driven by an in-memory reader in tests without a live engine.
+ */
+import { distinctTaskTypes, scanTaskDefinitions } from "./taskdef.js";
+function trimSlash(address) {
+    return address.endsWith("/") ? address.slice(0, -1) : address;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asKey(item) {
+    if (!isRecord(item))
+        return undefined;
+    const key = item.processDefinitionKey;
+    if (typeof key === "string")
+        return key;
+    if (typeof key === "number")
+        return String(key);
+    return undefined;
+}
+function itemsOf(body) {
+    if (!isRecord(body))
+        return [];
+    return Array.isArray(body.items) ? body.items : [];
+}
+/**
+ * Build a {@link C8RestReader} backed by the live C8 v2 REST API.
+ *
+ * `searchProcessDefinitionKeys` pages `POST /process-definitions/search` until the
+ * engine returns fewer than a full page, de-duplicating keys. `getProcessDefinitionXml`
+ * reads `GET /process-definitions/{key}/xml`. Both raise on a non-2xx response so a
+ * misconfigured endpoint fails loudly rather than reporting phantom zero demand.
+ */
+export function httpC8RestReader(options) {
+    const base = trimSlash(options.restAddress);
+    const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const pageSize = options.pageSize ?? 100;
+    if (!Number.isInteger(pageSize) || pageSize <= 0) {
+        throw new Error(`httpC8RestReader: pageSize must be a positive integer, got ${pageSize}`);
+    }
+    const headers = { "content-type": "application/json" };
+    if (options.token !== undefined)
+        headers.authorization = `Bearer ${options.token}`;
+    return {
+        async searchProcessDefinitionKeys() {
+            const keys = [];
+            const seen = new Set();
+            let from = 0;
+            for (;;) {
+                const response = await doFetch(`${base}/process-definitions/search`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify({ page: { from, limit: pageSize } }),
+                });
+                if (!response.ok) {
+                    throw new Error(`C8 REST process-definitions/search failed: ${response.status} ${response.statusText}`);
+                }
+                const items = itemsOf(await response.json());
+                for (const item of items) {
+                    const key = asKey(item);
+                    if (key !== undefined && !seen.has(key)) {
+                        seen.add(key);
+                        keys.push(key);
+                    }
+                }
+                if (items.length < pageSize)
+                    break;
+                from += items.length;
+            }
+            return keys;
+        },
+        async getProcessDefinitionXml(processDefinitionKey) {
+            const response = await doFetch(`${base}/process-definitions/${encodeURIComponent(processDefinitionKey)}/xml`, {
+                method: "GET",
+                headers,
+            });
+            if (!response.ok) {
+                throw new Error(`C8 REST process-definitions/${processDefinitionKey}/xml failed: ${response.status} ${response.statusText}`);
+            }
+            return response.text();
+        },
+    };
+}
+/**
+ * Read every deployed model's `taskDefinition` leaves through a {@link C8RestReader}.
+ *
+ * Enumerates the deployed definitions, fetches each one's BPMN XML, and scans out
+ * its service-task task-definition leaves. The result is the raw demand corpus the
+ * {@link ./model.ts} model buckets and diffs against supply.
+ */
+export async function readDeployedTaskDefinitions(reader) {
+    const keys = await reader.searchProcessDefinitionKeys();
+    const leaves = [];
+    for (const key of keys) {
+        const xml = await reader.getProcessDefinitionXml(key);
+        leaves.push(...scanTaskDefinitions(xml));
+    }
+    return leaves;
+}
+/**
+ * Read the distinct demanded job types (routing tokens) from the engine — the
+ * convenience path for callers that only need the demand token set, not element
+ * provenance.
+ */
+export async function readDeployedTaskTypes(reader) {
+    return distinctTaskTypes(await readDeployedTaskDefinitions(reader));
+}

package/dist/demand/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @nanobpm/agentic-demand — the demand×supply model for the Nano agentic
+ * protocol (ADR 0056, slice S4).
+ *
+ * A **read-only mirror + enrolment gate**: it reads the deployed models'
+ * `taskDefinition` leaves from the engine's C8 REST API ({@link httpC8RestReader},
+ * {@link readDeployedTaskDefinitions}), buckets them by network prefix, and diffs
+ * that demand against the live supply — the S2 presence registry resolved through
+ * the S3 vocabulary ({@link computeDemandSupply}) — to surface, per network, the
+ * *missing agent types* (`demand ∖ supply`) and the SLO state (missing-agent RED
+ * folded together with the S3 diversity SLO).
+ *
+ * It does NOT match-make: it never places work on a worker or holds a seat's job.
+ * Active placement is explicitly out of scope for v1. Nothing here rides the
+ * Camunda-8 engine or its transport — the C8 REST read is an ordinary read over a
+ * separate connection; the engine and the C8 job protocol stay frozen.
+ *
+ * The wire contract (routing-token grammar, `demand` payload) lives in
+ * `@nanobpm/agentic-protocol`; the registry rows and vocab resolver come from
+ * `@nanobpm/agentic-vocab`. This package builds on both and never redefines them.
+ */
+export { scanTaskDefinitions, distinctTaskTypes, type TaskDefinitionLeaf } from "./taskdef.ts";
+export { httpC8RestReader, readDeployedTaskDefinitions, readDeployedTaskTypes, type C8RestReader, type FetchLike, type HttpC8RestReaderOptions, } from "./c8-rest.ts";
+export { computeDemandSupply, toDemandPayloads, type DemandSupplyInput, type DemandSupplyReport, type NetworkDemand, type TokenDemand, type SloStatus, } from "./model.ts";

package/dist/demand/index.js

@@ -0,0 +1,24 @@
+/**
+ * @nanobpm/agentic-demand — the demand×supply model for the Nano agentic
+ * protocol (ADR 0056, slice S4).
+ *
+ * A **read-only mirror + enrolment gate**: it reads the deployed models'
+ * `taskDefinition` leaves from the engine's C8 REST API ({@link httpC8RestReader},
+ * {@link readDeployedTaskDefinitions}), buckets them by network prefix, and diffs
+ * that demand against the live supply — the S2 presence registry resolved through
+ * the S3 vocabulary ({@link computeDemandSupply}) — to surface, per network, the
+ * *missing agent types* (`demand ∖ supply`) and the SLO state (missing-agent RED
+ * folded together with the S3 diversity SLO).
+ *
+ * It does NOT match-make: it never places work on a worker or holds a seat's job.
+ * Active placement is explicitly out of scope for v1. Nothing here rides the
+ * Camunda-8 engine or its transport — the C8 REST read is an ordinary read over a
+ * separate connection; the engine and the C8 job protocol stay frozen.
+ *
+ * The wire contract (routing-token grammar, `demand` payload) lives in
+ * `@nanobpm/agentic-protocol`; the registry rows and vocab resolver come from
+ * `@nanobpm/agentic-vocab`. This package builds on both and never redefines them.
+ */
+export { scanTaskDefinitions, distinctTaskTypes } from "./taskdef.js";
+export { httpC8RestReader, readDeployedTaskDefinitions, readDeployedTaskTypes, } from "./c8-rest.js";
+export { computeDemandSupply, toDemandPayloads, } from "./model.js";

package/dist/demand/model.d.ts

@@ -0,0 +1,68 @@
+import type { DemandPayload } from "../protocol/index.ts";
+import { type DiversityReport, type RegisteredWorker, type VocabResolver } from "../vocab/index.ts";
+import { type TaskDefinitionLeaf } from "./taskdef.ts";
+/** The SLO grade — same three-level scale as the S3 diversity SLO. */
+export type SloStatus = "green" | "amber" | "red";
+/** One demanded routing token and the live supply against it. */
+export interface TokenDemand {
+    /** The demanded routing token (a `taskDefinition` leaf's type). */
+    readonly token: string;
+    /** How many registered workers currently serve this token. */
+    readonly supply: number;
+    /** The instances serving it, sorted — provenance for the cockpit drill-in. */
+    readonly instances: readonly string[];
+    /** False when no registered worker serves it — a missing agent type. */
+    readonly satisfied: boolean;
+}
+/** The demand×supply picture for one network prefix. */
+export interface NetworkDemand {
+    /** The network prefix bucket (`network` segment, or a bare token's own name). */
+    readonly network: string;
+    /** Every demanded token in the bucket, sorted by token. */
+    readonly tokens: readonly TokenDemand[];
+    /** The demanded tokens in this bucket with zero supply, sorted. */
+    readonly missing: readonly string[];
+}
+/** The full demand×supply report. */
+export interface DemandSupplyReport {
+    /** Per-network demand×supply, sorted by network. */
+    readonly networks: readonly NetworkDemand[];
+    /** Every missing agent type across all networks, sorted and de-duplicated. */
+    readonly missing: readonly string[];
+    /** The S3 diversity SLO over the correlated live registry. */
+    readonly diversity: DiversityReport;
+    /** 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.
+     */
+    readonly nonAgentic: readonly string[];
+}
+/** Input to {@link computeDemandSupply}. */
+export interface DemandSupplyInput {
+    /** Demand: the deployed `taskDefinition` leaves (order-insensitive). */
+    readonly taskDefinitions: readonly TaskDefinitionLeaf[];
+    /** Supply: the live S2 registry rows. */
+    readonly workers: readonly RegisteredWorker[];
+    /** The S3 resolver over the resolved vocabulary artifact. */
+    readonly resolver: VocabResolver;
+}
+/**
+ * Compute the demand×supply model from deployed demand and live supply.
+ *
+ * Pure and deterministic: the same demand + registry + vocab always yields the
+ * same report, with every list sorted, so it is safe to diff frame-to-frame and
+ * to render straight into the cockpit.
+ */
+export declare function computeDemandSupply(input: DemandSupplyInput): DemandSupplyReport;
+/**
+ * Project the report onto the S0 `demand` message family — one {@link DemandPayload}
+ * per network carrying its missing agent types, so the gap can cross the agentic
+ * channel's control/facts lane. Emits an entry for every network (missing may be
+ * empty), sorted by network, so a consumer sees a cleared network flip from a
+ * non-empty `missing` back to `[]`.
+ */
+export declare function toDemandPayloads(report: DemandSupplyReport): DemandPayload[];

package/dist/demand/model.js

@@ -0,0 +1,118 @@
+/**
+ * The demand×supply model — S4.
+ *
+ * Given the demand (the routing tokens deployed models ask for, as
+ * `taskDefinition` leaves) and the supply (the live S2 registry, resolved to the
+ * SERVE tokens each worker fills through the S3 vocab), this computes, per
+ * network:
+ *
+ *  - **demand** — the distinct routing tokens the deployed models declare,
+ *    bucketed by the token's network prefix;
+ *  - **supply** — how many registered workers currently serve each token;
+ *  - **missing agent type** — `demand ∖ supply`: a demanded token no registered
+ *    worker can fill (the enrolment gap the cockpit lights up red);
+ *  - **the SLO state** — the worst of the missing-agent signal (a missing token
+ *    is RED) and the S3 diversity SLO (`family(#red) ≠ family(#blue)`).
+ *
+ * This is a **read-only mirror + enrolment gate**. It reads what the engine has
+ * deployed and what the registry reports and reconciles the two; it does NOT
+ * match-make — it never places work on, or holds a seat for, a worker. Active
+ * placement is explicitly out of scope for v1.
+ *
+ * Supply resolution reuses the S3 {@link VocabResolver}: a worker *serves* a token
+ * iff that token is in `resolver.resolve(worker.capability).tokens` — capability
+ * is the enrolment attribute the vocab's `requires` gate reads, never part of the
+ * token itself (design invariant 3).
+ */
+import { parseToken } from "../protocol/index.js";
+import { correlateRegistry } from "../vocab/index.js";
+import { distinctTaskTypes } from "./taskdef.js";
+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. */
+function bucketOf(token) {
+    try {
+        const parsed = parseToken(token);
+        // A bare (network-less) token like `decide` buckets under its own role name.
+        return parsed.network ?? parsed.role;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+/**
+ * Compute the demand×supply model from deployed demand and live supply.
+ *
+ * Pure and deterministic: the same demand + registry + vocab always yields the
+ * same report, with every list sorted, so it is safe to diff frame-to-frame and
+ * to render straight into the cockpit.
+ */
+export function computeDemandSupply(input) {
+    const { workers, resolver } = input;
+    // Supply index: each worker's SERVE token set, resolved once.
+    const supplyByToken = new Map();
+    for (const worker of workers) {
+        const tokens = resolver.resolve(worker.capability).tokens;
+        for (const token of tokens) {
+            const instances = supplyByToken.get(token);
+            if (instances === undefined)
+                supplyByToken.set(token, [worker.instance]);
+            else
+                instances.push(worker.instance);
+        }
+    }
+    const demandTokens = distinctTaskTypes(input.taskDefinitions);
+    const byNetwork = new Map();
+    const nonAgentic = [];
+    for (const token of demandTokens) {
+        const network = bucketOf(token);
+        if (network === undefined) {
+            nonAgentic.push(token);
+            continue;
+        }
+        const instances = sortedUnique(supplyByToken.get(token) ?? []);
+        const demand = {
+            token,
+            supply: instances.length,
+            instances,
+            satisfied: instances.length > 0,
+        };
+        const bucket = byNetwork.get(network) ?? new Map();
+        // A token can only appear once (distinctTaskTypes), so no merge is needed.
+        bucket.set(token, demand);
+        byNetwork.set(network, bucket);
+    }
+    const networks = [...byNetwork.entries()]
+        .map(([network, tokenMap]) => {
+        const tokens = [...tokenMap.values()].sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+        const missing = tokens.filter((token) => !token.satisfied).map((token) => token.token);
+        return { network, tokens, missing };
+    })
+        .sort((a, b) => (a.network < b.network ? -1 : a.network > b.network ? 1 : 0));
+    const missing = sortedUnique(networks.flatMap((network) => network.missing));
+    const diversity = correlateRegistry(resolver, workers);
+    const missingStatus = missing.length > 0 ? "red" : "green";
+    const status = worst(missingStatus, diversity.status);
+    return {
+        networks,
+        missing,
+        diversity,
+        status,
+        nonAgentic: [...nonAgentic].sort(),
+    };
+}
+/**
+ * Project the report onto the S0 `demand` message family — one {@link DemandPayload}
+ * per network carrying its missing agent types, so the gap can cross the agentic
+ * channel's control/facts lane. Emits an entry for every network (missing may be
+ * empty), sorted by network, so a consumer sees a cleared network flip from a
+ * non-empty `missing` back to `[]`.
+ */
+export function toDemandPayloads(report) {
+    return report.networks.map((network) => ({ network: network.network, missing: network.missing }));
+}

package/dist/demand/taskdef.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parse `taskDefinition` leaves out of a deployed BPMN model.
+ *
+ * The demand side of the demand×supply model (S4) is the set of routing tokens
+ * the deployed processes ask for. In a Nano/Camunda-8 model each demand is a
+ * service task's `<zeebe:taskDefinition type="…">` — the job type the engine
+ * matches 1:1 against a worker's routing token. This scanner reads those leaves
+ * out of the raw BPMN XML so the model can bucket them by network prefix and
+ * diff them against live supply.
+ *
+ * It is deliberately a small, dependency-free regex scan over the same surface
+ * the Urban toolkit's worker-io deriver reads, so it stays app-tier and never
+ * touches the engine internals — the XML arrives from the C8 REST API
+ * ({@link ./c8-rest.ts}).
+ */
+/** One deployed `taskDefinition` leaf: a job type demanded by a model element. */
+export interface TaskDefinitionLeaf {
+    /** The `zeebe:taskDefinition` `type` — the routing token the engine matches. */
+    readonly taskType: string;
+    /** The `bpmn:process` id the leaf was declared in (best-effort, may be empty). */
+    readonly process: string;
+    /** The service-task element id carrying the leaf (best-effort, may be empty). */
+    readonly elementId: string;
+}
+/**
+ * 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.
+ */
+export declare function scanTaskDefinitions(xml: string): TaskDefinitionLeaf[];
+/**
+ * Scan many BPMN documents and return the distinct demanded job types, in first
+ * occurrence order. The demand×supply model only needs the distinct set of
+ * routing tokens; {@link scanTaskDefinitions} keeps the full leaves for callers
+ * that want element provenance.
+ */
+export declare function distinctTaskTypes(leaves: readonly TaskDefinitionLeaf[]): string[];

package/dist/demand/taskdef.js

@@ -0,0 +1,67 @@
+/**
+ * Parse `taskDefinition` leaves out of a deployed BPMN model.
+ *
+ * The demand side of the demand×supply model (S4) is the set of routing tokens
+ * the deployed processes ask for. In a Nano/Camunda-8 model each demand is a
+ * service task's `<zeebe:taskDefinition type="…">` — the job type the engine
+ * matches 1:1 against a worker's routing token. This scanner reads those leaves
+ * out of the raw BPMN XML so the model can bucket them by network prefix and
+ * diff them against live supply.
+ *
+ * It is deliberately a small, dependency-free regex scan over the same surface
+ * the Urban toolkit's worker-io deriver reads, so it stays app-tier and never
+ * touches the engine internals — the XML arrives from the C8 REST API
+ * ({@link ./c8-rest.ts}).
+ */
+function attr(tag, name) {
+    const match = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    return match ? match[1] : "";
+}
+function processId(xml) {
+    const match = xml.match(/<bpmn:process\b[^>]*\bid\s*=\s*"([^"]*)"/);
+    return match ? match[1] : "";
+}
+/**
+ * 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.
+ */
+export function scanTaskDefinitions(xml) {
+    const proc = processId(xml);
+    const out = [];
+    const blockRe = /<bpmn:serviceTask\b([^>]*)>([\s\S]*?)<\/bpmn:serviceTask>/g;
+    let block;
+    while ((block = blockRe.exec(xml)) !== null) {
+        const openAttrs = block[1];
+        const body = block[2];
+        const elementId = attr(`<x ${openAttrs}>`, "id");
+        const tdMatch = body.match(/<zeebe:taskDefinition\b[^>]*>/);
+        if (!tdMatch)
+            continue;
+        const taskType = attr(tdMatch[0], "type");
+        if (!taskType)
+            continue;
+        out.push({ taskType, elementId, process: proc });
+    }
+    return out;
+}
+/**
+ * Scan many BPMN documents and return the distinct demanded job types, in first
+ * occurrence order. The demand×supply model only needs the distinct set of
+ * routing tokens; {@link scanTaskDefinitions} keeps the full leaves for callers
+ * that want element provenance.
+ */
+export function distinctTaskTypes(leaves) {
+    const seen = new Set();
+    const out = [];
+    for (const leaf of leaves) {
+        if (seen.has(leaf.taskType))
+            continue;
+        seen.add(leaf.taskType);
+        out.push(leaf.taskType);
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @nanobpm/agentic — the Nano agentic protocol (ADR 0056).
+ *
+ * One app-tier channel carrying agent presence/registry, demand×supply, a shared
+ * blackboard and a live terminal relay. This barrel re-exports every family as a
+ * namespace; most consumers import the specific subpath they need instead, e.g.
+ * `@nanobpm/agentic/channel`, `@nanobpm/agentic/relay`, `@nanobpm/agentic/cockpit`.
+ */
+export * as protocol from "./protocol/index.ts";
+export * as channel from "./channel/index.ts";
+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 transcript from "./transcript/index.ts";
+export * as blackboard from "./blackboard/index.ts";
+export * as cockpit from "./cockpit/index.ts";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @nanobpm/agentic — the Nano agentic protocol (ADR 0056).
+ *
+ * One app-tier channel carrying agent presence/registry, demand×supply, a shared
+ * blackboard and a live terminal relay. This barrel re-exports every family as a
+ * namespace; most consumers import the specific subpath they need instead, e.g.
+ * `@nanobpm/agentic/channel`, `@nanobpm/agentic/relay`, `@nanobpm/agentic/cockpit`.
+ */
+export * as protocol from "./protocol/index.js";
+export * as channel from "./channel/index.js";
+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 transcript from "./transcript/index.js";
+export * as blackboard from "./blackboard/index.js";
+export * as cockpit from "./cockpit/index.js";