@nanobpm/agentic 0.1.0 → 0.4.0

package/dist/session/normalizer/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The `@nanobpm/agentic/session/normalizer` contract — ADR 0062, slice 3 (the
+ * `stream-json`/native-transcript **fallback** ingestion backend).
+ *
+ * Slice 2 speaks ACP directly; this slice covers every harness that does *not*
+ * (yet) speak ACP. ADR 0062 §5 frames `stream-json` as a *transport with N
+ * vendor dialects*, so there is no single "stream-json backend": each harness
+ * gets a small **normalizer** that maps its native/streaming session output onto
+ * Nano's canonical {@link SessionEvent} (slice 1), plus a **resume shim** over
+ * that harness's native `--resume <id>` (or SDK equivalent).
+ *
+ * The three moving parts a harness normalizer exposes:
+ *
+ *  - {@link HarnessNormalizer.toDrafts} — the dialect map: one native record →
+ *    zero-or-more {@link DraftEvent}s (canonical events *minus* the causal-chain
+ *    fields the shared {@link linkDrafts} threads in, so a per-harness dialect
+ *    never re-implements chaining).
+ *  - {@link HarnessNormalizer.resume} — the resume shim: given a native session
+ *    id, the exact native invocation ({@link ResumeShim}) that restores it.
+ *  - {@link HarnessNormalizer.capabilities} — the {@link HarnessCapabilities}
+ *    the {@link capabilityProbe} folds into a `durable-resume` advertisement
+ *    (slice 5's enrolment gate reads this).
+ *
+ * Nothing here interprets a harness schema as *ours*: the native shapes are
+ * ingestion details owned entirely by each dialect module; the union they all
+ * target is the stable slice-1 contract.
+ */
+import type { SessionEvent } from "../events.ts";
+/**
+ * Distributive `Omit` over a discriminated union: applies `Omit` to *each* union
+ * member, preserving the `type` discriminant. A plain `Omit<Union, K>` collapses
+ * to the members' common properties (losing the per-member fields), so we cannot
+ * use it to describe "a session event without its chain fields".
+ */
+export type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+/**
+ * A canonical {@link SessionEvent} as a dialect first produces it — the full
+ * semantic payload (`type` + type-specific fields) but *without* the causal-chain
+ * responsibilities (`parentId`, and an optional-only `id`). The shared
+ * {@link linkDrafts} threads `parentId` in emission order and fills any missing
+ * `id`, so an individual dialect never re-implements chain bookkeeping; it just
+ * says "here is the event this record means". A dialect that already knows a
+ * stable native id (a tool-call id, a provider message id) may supply it as
+ * `id` to preserve correlation across a resume.
+ */
+export type DraftEvent = DistributiveOmit<SessionEvent, "id" | "parentId"> & {
+    readonly id?: string;
+};
+/**
+ * The native resume invocation a harness's shim resolves for a session id. Two
+ * transports cover the fleet:
+ *
+ *  - `cli` — a flag-driven harness: `args` are the argv tail to append to the
+ *    harness command to resume that session (e.g. Claude's `["--resume", id]`,
+ *    Qwen's `["-r", id]`). Nano spawns; it never parses the harness's output
+ *    beyond the dialect map.
+ *  - `sdk` — an in-process harness (Copilot's `copilot-sdk`, the DeepSeek live
+ *    feed): `call` names the SDK method and `args` are its arguments (e.g.
+ *    `resumeSession(id)`), so the host invokes it directly rather than spawning.
+ *
+ * `sessionId` echoes the id the shim resumed, so a caller that only kept the
+ * {@link ResumeShim} still knows which session it targets.
+ */
+export type ResumeShim = {
+    readonly transport: "cli";
+    readonly sessionId: string;
+    readonly args: readonly string[];
+} | {
+    readonly transport: "sdk";
+    readonly sessionId: string;
+    readonly call: string;
+    readonly args: readonly unknown[];
+};
+/**
+ * What a harness can do, from the perspective of durable resume. `streaming` is
+ * "exposes a machine-readable streaming/native mind source we can normalize";
+ * `resumeById` is "can restore a *specific* prior session by id" (not merely
+ * `--continue` the latest). {@link CapabilityAdvertisement.durableResume} is
+ * derived, never declared — see {@link capabilityProbe}.
+ */
+export interface HarnessCapabilities {
+    readonly streaming: boolean;
+    readonly resumeById: boolean;
+}
+/**
+ * The advertisement {@link capabilityProbe} produces: the raw capabilities plus
+ * the single **derived** `durableResume` bit slice 5's enrolment gate consumes.
+ * Keeping `durableResume` derived (never a hand-set field on a normalizer)
+ * eliminates the drift surface where a harness claims durability it can't honour.
+ */
+export interface CapabilityAdvertisement {
+    readonly harness: string;
+    readonly streaming: boolean;
+    readonly resumeById: boolean;
+    /** `true` iff the harness both streams a mind source AND resumes by id. */
+    readonly durableResume: boolean;
+}
+/**
+ * One harness's fallback ingestion adapter: a dialect map, a resume shim, and its
+ * capabilities. Independent per harness (they fan out in parallel), and all
+ * target the one canonical {@link SessionEvent} union.
+ */
+export interface HarnessNormalizer {
+    /** The harness id this normalizer speaks for, e.g. `"@github/copilot"`. */
+    readonly harness: string;
+    /** Raw capabilities; `durable-resume` is derived from these by {@link capabilityProbe}. */
+    readonly capabilities: HarnessCapabilities;
+    /**
+     * Map one native record (a parsed `stream-json` line, an SDK `SessionEvent`, a
+     * live-feed frame) to zero-or-more canonical {@link DraftEvent}s. Returns `[]`
+     * for records that carry no session-log meaning (transport keep-alives, init
+     * frames the canonical model does not represent). Throws
+     * {@link NormalizerDialectError} on a record that *should* map but is
+     * structurally invalid — a corrupt transcript fails loudly, it never
+     * fabricates an event.
+     */
+    toDrafts(record: unknown): readonly DraftEvent[];
+    /** Resolve the native invocation that resumes `sessionId` for this harness. */
+    resume(sessionId: string): ResumeShim;
+}
+/**
+ * Derive a harness's `durable-resume` advertisement from its raw capabilities.
+ * A harness advertises `durable-resume` **iff** it both exposes a streaming mind
+ * source we can normalize AND can restore a specific session by id — either half
+ * alone is insufficient (a stream we can't resume, or a resume with no mind to
+ * replay). This is the single place the bit is computed.
+ */
+export declare function capabilityProbe(normalizer: HarnessNormalizer): CapabilityAdvertisement;
+/**
+ * Raised when a native record that a dialect *should* map is structurally
+ * invalid (a missing tool-call id, a message with no content). Mirrors slice 1's
+ * `SessionEventShapeError` at the ingestion boundary: normalization is a trusted
+ * map, so a malformed native record surfaces loudly rather than silently
+ * dropping or fabricating a canonical event.
+ */
+export declare class NormalizerDialectError extends Error {
+    readonly harness: string;
+    constructor(harness: string, message: string);
+}

package/dist/session/normalizer/types.js

@@ -0,0 +1,31 @@
+/**
+ * Derive a harness's `durable-resume` advertisement from its raw capabilities.
+ * A harness advertises `durable-resume` **iff** it both exposes a streaming mind
+ * source we can normalize AND can restore a specific session by id — either half
+ * alone is insufficient (a stream we can't resume, or a resume with no mind to
+ * replay). This is the single place the bit is computed.
+ */
+export function capabilityProbe(normalizer) {
+    const { streaming, resumeById } = normalizer.capabilities;
+    return {
+        harness: normalizer.harness,
+        streaming,
+        resumeById,
+        durableResume: streaming && resumeById,
+    };
+}
+/**
+ * Raised when a native record that a dialect *should* map is structurally
+ * invalid (a missing tool-call id, a message with no content). Mirrors slice 1's
+ * `SessionEventShapeError` at the ingestion boundary: normalization is a trusted
+ * map, so a malformed native record surfaces loudly rather than silently
+ * dropping or fabricating a canonical event.
+ */
+export class NormalizerDialectError extends Error {
+    harness;
+    constructor(harness, message) {
+        super(`[${harness}] ${message}`);
+        this.name = "NormalizerDialectError";
+        this.harness = harness;
+    }
+}

package/dist/session/schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The canonical authoritative session-log schema — ADR 0062, slice 1.
+ *
+ * The DDL here is the single source of truth {@link SqliteSessionLog.ensureSchema}
+ * applies, and is mirrored statement-for-statement by the app-boot migration
+ * `db/migrations/005_agentic_session.sql`. `schema.test.ts` normalises both and
+ * asserts they are identical — drift is a red test, not a silent boot mismatch.
+ * This mirrors the S6 transcript store's drift-guard exactly (ADR 0056 §12), the
+ * advisory precedent this authoritative log is promoted from.
+ *
+ * Three tables back the log:
+ *  - `agentic_session_log` — one row per **activation** `(processInstanceKey,
+ *    elementId)`: its fence high-water (`incarnation`), retention lifecycle,
+ *    status, and the retained offset window (`first_offset` … `next_offset`).
+ *  - `agentic_session_event` — the durable, authoritative events, keyed
+ *    `(process_instance_key, element_id, event_offset)` so a re-lease can replay
+ *    from any offset and a resuming incarnation can overwrite an uncommitted tail
+ *    idempotently.
+ *  - `agentic_session_checkpoint` — the mind/world join points, keyed
+ *    `(process_instance_key, element_id, checkpoint_id)` with the pinned offset.
+ *
+ * `event_offset`/`checkpoint_offset` (not `offset`) is deliberate: `OFFSET` is a
+ * SQLite keyword, so the columns are named to avoid quoting it everywhere.
+ */
+/** The per-activation metadata + fence table name. */
+export declare const SESSION_LOG_TABLE = "agentic_session_log";
+/** The durable per-event table name. */
+export declare const SESSION_EVENT_TABLE = "agentic_session_event";
+/** The checkpoint table name. */
+export declare const SESSION_CHECKPOINT_TABLE = "agentic_session_checkpoint";
+/**
+ * The canonical session-log DDL. Forward-only and additive; every column added
+ * here must also be added to the boot migration (the drift guard enforces it).
+ * Events are immutable once committed under an incarnation; a resume overwrites
+ * only the *uncommitted* tail past the last checkpoint (a re-key at the same
+ * `(activation, offset)`), never a committed row.
+ */
+export declare const SESSION_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_session_log (\n  process_instance_key  TEXT NOT NULL,\n  element_id            TEXT NOT NULL,\n  incarnation           INTEGER NOT NULL DEFAULT 0,\n  lifecycle             TEXT NOT NULL DEFAULT 'activation',\n  status                TEXT NOT NULL DEFAULT 'open',\n  created_at            TEXT NOT NULL,\n  completed_at          TEXT,\n  first_offset          INTEGER,\n  next_offset           INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY (process_instance_key, element_id)\n);\nCREATE TABLE IF NOT EXISTS agentic_session_event (\n  process_instance_key  TEXT NOT NULL,\n  element_id            TEXT NOT NULL,\n  event_offset          INTEGER NOT NULL,\n  incarnation           INTEGER NOT NULL,\n  event_id              TEXT NOT NULL,\n  parent_id             TEXT,\n  event_type            TEXT NOT NULL,\n  payload               TEXT NOT NULL,\n  appended_at           TEXT NOT NULL,\n  PRIMARY KEY (process_instance_key, element_id, event_offset)\n);\nCREATE TABLE IF NOT EXISTS agentic_session_checkpoint (\n  process_instance_key  TEXT NOT NULL,\n  element_id            TEXT NOT NULL,\n  checkpoint_id         TEXT NOT NULL,\n  checkpoint_offset     INTEGER NOT NULL,\n  incarnation           INTEGER NOT NULL,\n  commit_sha            TEXT NOT NULL,\n  effect_ledger         TEXT NOT NULL,\n  created_at            TEXT NOT NULL,\n  PRIMARY KEY (process_instance_key, element_id, checkpoint_id)\n);\nCREATE INDEX IF NOT EXISTS idx_agentic_session_checkpoint_offset ON agentic_session_checkpoint (process_instance_key, element_id, checkpoint_offset);\nCREATE INDEX IF NOT EXISTS idx_agentic_session_log_retention ON agentic_session_log (lifecycle, status, completed_at);";

package/dist/session/schema.js

@@ -0,0 +1,74 @@
+/**
+ * The canonical authoritative session-log schema — ADR 0062, slice 1.
+ *
+ * The DDL here is the single source of truth {@link SqliteSessionLog.ensureSchema}
+ * applies, and is mirrored statement-for-statement by the app-boot migration
+ * `db/migrations/005_agentic_session.sql`. `schema.test.ts` normalises both and
+ * asserts they are identical — drift is a red test, not a silent boot mismatch.
+ * This mirrors the S6 transcript store's drift-guard exactly (ADR 0056 §12), the
+ * advisory precedent this authoritative log is promoted from.
+ *
+ * Three tables back the log:
+ *  - `agentic_session_log` — one row per **activation** `(processInstanceKey,
+ *    elementId)`: its fence high-water (`incarnation`), retention lifecycle,
+ *    status, and the retained offset window (`first_offset` … `next_offset`).
+ *  - `agentic_session_event` — the durable, authoritative events, keyed
+ *    `(process_instance_key, element_id, event_offset)` so a re-lease can replay
+ *    from any offset and a resuming incarnation can overwrite an uncommitted tail
+ *    idempotently.
+ *  - `agentic_session_checkpoint` — the mind/world join points, keyed
+ *    `(process_instance_key, element_id, checkpoint_id)` with the pinned offset.
+ *
+ * `event_offset`/`checkpoint_offset` (not `offset`) is deliberate: `OFFSET` is a
+ * SQLite keyword, so the columns are named to avoid quoting it everywhere.
+ */
+/** The per-activation metadata + fence table name. */
+export const SESSION_LOG_TABLE = "agentic_session_log";
+/** The durable per-event table name. */
+export const SESSION_EVENT_TABLE = "agentic_session_event";
+/** The checkpoint table name. */
+export const SESSION_CHECKPOINT_TABLE = "agentic_session_checkpoint";
+/**
+ * The canonical session-log DDL. Forward-only and additive; every column added
+ * here must also be added to the boot migration (the drift guard enforces it).
+ * Events are immutable once committed under an incarnation; a resume overwrites
+ * only the *uncommitted* tail past the last checkpoint (a re-key at the same
+ * `(activation, offset)`), never a committed row.
+ */
+export const SESSION_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${SESSION_LOG_TABLE} (
+  process_instance_key  TEXT NOT NULL,
+  element_id            TEXT NOT NULL,
+  incarnation           INTEGER NOT NULL DEFAULT 0,
+  lifecycle             TEXT NOT NULL DEFAULT 'activation',
+  status                TEXT NOT NULL DEFAULT 'open',
+  created_at            TEXT NOT NULL,
+  completed_at          TEXT,
+  first_offset          INTEGER,
+  next_offset           INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (process_instance_key, element_id)
+);
+CREATE TABLE IF NOT EXISTS ${SESSION_EVENT_TABLE} (
+  process_instance_key  TEXT NOT NULL,
+  element_id            TEXT NOT NULL,
+  event_offset          INTEGER NOT NULL,
+  incarnation           INTEGER NOT NULL,
+  event_id              TEXT NOT NULL,
+  parent_id             TEXT,
+  event_type            TEXT NOT NULL,
+  payload               TEXT NOT NULL,
+  appended_at           TEXT NOT NULL,
+  PRIMARY KEY (process_instance_key, element_id, event_offset)
+);
+CREATE TABLE IF NOT EXISTS ${SESSION_CHECKPOINT_TABLE} (
+  process_instance_key  TEXT NOT NULL,
+  element_id            TEXT NOT NULL,
+  checkpoint_id         TEXT NOT NULL,
+  checkpoint_offset     INTEGER NOT NULL,
+  incarnation           INTEGER NOT NULL,
+  commit_sha            TEXT NOT NULL,
+  effect_ledger         TEXT NOT NULL,
+  created_at            TEXT NOT NULL,
+  PRIMARY KEY (process_instance_key, element_id, checkpoint_id)
+);
+CREATE INDEX IF NOT EXISTS idx_${SESSION_CHECKPOINT_TABLE}_offset ON ${SESSION_CHECKPOINT_TABLE} (process_instance_key, element_id, checkpoint_offset);
+CREATE INDEX IF NOT EXISTS idx_${SESSION_LOG_TABLE}_retention ON ${SESSION_LOG_TABLE} (lifecycle, status, completed_at);`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/agentic",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "The Nano agentic protocol (ADR 0056): one app-tier channel carrying agent presence/registry, demand×supply, a shared blackboard and live terminal relay — with the wire contract, channel/hub, family modules and the operator cockpit, as subpath exports.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,6 +15,7 @@
     "transcript",
     "blackboard",
     "cockpit",
+    "session",
     "conformance"
   ],
   "publishConfig": {
@@ -63,6 +64,21 @@
       "default": "./dist/relay/index.js"
     },
     "./source/relay": "./src/relay/index.ts",
+    "./session": {
+      "types": "./dist/session/index.d.ts",
+      "default": "./dist/session/index.js"
+    },
+    "./source/session": "./src/session/index.ts",
+    "./session/acp": {
+      "types": "./dist/session/acp/index.d.ts",
+      "default": "./dist/session/acp/index.js"
+    },
+    "./source/session/acp": "./src/session/acp/index.ts",
+    "./session/normalizer": {
+      "types": "./dist/session/normalizer/index.d.ts",
+      "default": "./dist/session/normalizer/index.js"
+    },
+    "./source/session/normalizer": "./src/session/normalizer/index.ts",
     "./transcript": {
       "types": "./dist/transcript/index.d.ts",
       "default": "./dist/transcript/index.js"

package/src/demand/model.test.ts

@@ -25,8 +25,8 @@ const AMBER_VOCAB: VocabDocument = {
 };
 const amberResolver = new VocabResolver(AMBER_VOCAB);
 
-function leaf(taskType: string, process = "p", elementId = "e"): TaskDefinitionLeaf {
-  return { taskType, process, elementId };
+function leaf(taskType: string, process = "p", elementId = "e", agentic = true): TaskDefinitionLeaf {
+  return { taskType, process, elementId, agentic };
 }
 
 function worker(instance: string, cognition: string, family: string, weight?: number): RegisteredWorker {
@@ -155,9 +155,9 @@ test("distinct demand: a token demanded by many elements is one entry", () => {
   assert.equal(qa.tokens[0].supply, 1);
 });
 
-test("non-routing-token task types are surfaced but excluded from accounting", () => {
+test("non-agentic (prompt-less) task types are surfaced but excluded from accounting", () => {
   const report = computeDemandSupply({
-    taskDefinitions: [leaf("planning.planner"), leaf("legacy:job#bad#token")],
+    taskDefinitions: [leaf("planning.planner"), leaf("legacy:job#bad#token", "p", "e", false)],
     workers: [worker("w", "planning", "gpt")],
     resolver,
   });
@@ -169,6 +169,84 @@ test("non-routing-token task types are surfaced but excluded from accounting", (
   assert.deepEqual(report.missing, []);
 });
 
+test("a prompt-less pr.* leaf is nonAgentic (not falsely reported missing)", () => {
+  // `pr.retro-record` parses as a routing token, but with no prompt link it is a
+  // deterministic in-process worker — it must NOT show as missing agentic demand.
+  const report = computeDemandSupply({
+    taskDefinitions: [leaf("pr.retro-record", "p", "e", false)],
+    workers: [],
+    resolver,
+  });
+  assert.deepEqual(report.nonAgentic, ["pr.retro-record"]);
+  assert.deepEqual(report.networks, []);
+  assert.deepEqual(report.missing, []);
+  assert.equal(report.status, "green");
+});
+
+test("a prompt-bearing colon-form fleet type is agentic demand, not nonAgentic", () => {
+  // `senior:retro` / `senior:rebase` do not parse as routing tokens, but carry a
+  // prompt link → they must appear as agentic demand (bucketed), never dropped.
+  const report = computeDemandSupply({
+    taskDefinitions: [leaf("senior:retro"), leaf("senior:rebase")],
+    workers: [],
+    resolver,
+  });
+  assert.deepEqual(report.nonAgentic, []);
+  assert.deepEqual(
+    report.networks.map((n) => n.network),
+    ["senior"],
+  );
+  const senior = report.networks[0];
+  assert.deepEqual(
+    senior.tokens.map((t) => t.token),
+    ["senior:rebase", "senior:retro"],
+  );
+  assert.deepEqual(senior.missing, ["senior:rebase", "senior:retro"]);
+});
+
+// Defect-class guard: classification must follow the prompt signal, NOT the
+// token string. This table pairs adversarial type strings (colon-form, dot-form,
+// bare, malformed) with a hasPrompt flag and asserts agentic-ness tracks the
+// flag alone — locking the class so a future naming convention can't re-invert
+// the buckets.
+const CLASSIFICATION_CASES: ReadonlyArray<{ type: string; hasPrompt: boolean }> = [
+  { type: "senior:retro", hasPrompt: true },
+  { type: "senior:retro", hasPrompt: false },
+  { type: "planning.planner", hasPrompt: true },
+  { type: "planning.planner", hasPrompt: false },
+  { type: "pr.retro-record", hasPrompt: true },
+  { type: "pr.retro-record", hasPrompt: false },
+  { type: "decide", hasPrompt: true },
+  { type: "decide", hasPrompt: false },
+  { type: "legacy:job#bad#token", hasPrompt: true },
+  { type: "legacy:job#bad#token", hasPrompt: false },
+  { type: "UPPER::weird!!", hasPrompt: true },
+  { type: "UPPER::weird!!", hasPrompt: false },
+  { type: "", hasPrompt: true },
+];
+
+for (const { type, hasPrompt } of CLASSIFICATION_CASES) {
+  test(`classification follows the prompt signal, not the token: ${JSON.stringify(type)} hasPrompt=${hasPrompt}`, () => {
+    const report = computeDemandSupply({
+      taskDefinitions: [{ taskType: type, process: "p", elementId: "e", agentic: hasPrompt }],
+      workers: [],
+      resolver,
+    });
+    if (hasPrompt) {
+      // Prompt-bearing → agentic demand: bucketed, never dumped in nonAgentic,
+      // and admitted without throwing regardless of how pathological the string.
+      assert.deepEqual(report.nonAgentic, []);
+      assert.equal(report.networks.length, 1);
+      assert.equal(report.networks[0].tokens[0].token, type);
+    } else {
+      // Prompt-less → nonAgentic, whatever the string parses to.
+      assert.deepEqual(report.nonAgentic, [type]);
+      assert.deepEqual(report.networks, []);
+      assert.deepEqual(report.missing, []);
+    }
+  });
+}
+
 test("the report is deterministic: lists sorted regardless of input order", () => {
   const a = computeDemandSupply({
     taskDefinitions: [leaf("qa.tester"), leaf("ci.runner"), leaf("planning.planner")],

package/src/demand/model.ts

@@ -72,10 +72,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[];
 }
@@ -90,14 +93,23 @@ export interface DemandSupplyInput {
   readonly resolver: VocabResolver;
 }
 
-/** A demanded token's network-prefix bucket, or `undefined` if not a routing token. */
-function bucketOf(token: string): string | undefined {
+/**
+ * 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: string): string {
   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;
+    const colon = token.indexOf(":");
+    return colon > 0 ? token.slice(0, colon) : token;
   }
 }
 
@@ -127,15 +139,24 @@ export function computeDemandSupply(input: DemandSupplyInput): DemandSupplyRepor
   }
 
   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<string, boolean>();
+  for (const leaf of input.taskDefinitions) {
+    agenticByToken.set(leaf.taskType, (agenticByToken.get(leaf.taskType) ?? false) || leaf.agentic);
+  }
   const byNetwork = new Map<string, Map<string, TokenDemand>>();
   const nonAgentic: string[] = [];
 
   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: TokenDemand = {
       token,

package/src/demand/taskdef.test.ts

@@ -27,8 +27,8 @@ const MODEL = `<?xml version="1.0" encoding="UTF-8"?>
 test("scans taskDefinition leaves with process and element provenance", () => {
   const leaves = scanTaskDefinitions(MODEL);
   assert.deepEqual(leaves, [
-    { taskType: "planning.planner", process: "plan-fanout", elementId: "plan" },
-    { taskType: "qa.tester", process: "plan-fanout", elementId: "test" },
+    { taskType: "planning.planner", process: "plan-fanout", elementId: "plan", agentic: false },
+    { taskType: "qa.tester", process: "plan-fanout", elementId: "test", agentic: false },
   ]);
 });
 
@@ -69,17 +69,62 @@ test("tolerates whitespace around attribute equals signs (id / type / process id
   </bpmn:definitions>`;
   const leaves = scanTaskDefinitions(xml);
   assert.deepEqual(leaves, [
-    { taskType: "ci.runner", process: "spaced-proc", elementId: "t" },
+    { taskType: "ci.runner", process: "spaced-proc", elementId: "t", agentic: false },
   ]);
 });
 
 test("distinctTaskTypes de-duplicates in first-occurrence order", () => {
   assert.deepEqual(
     distinctTaskTypes([
-      { taskType: "b", process: "p", elementId: "1" },
-      { taskType: "a", process: "p", elementId: "2" },
-      { taskType: "b", process: "p", elementId: "3" },
+      { taskType: "b", process: "p", elementId: "1", agentic: false },
+      { taskType: "a", process: "p", elementId: "2", agentic: false },
+      { taskType: "b", process: "p", elementId: "3", agentic: false },
     ]),
     ["b", "a"],
   );
 });
+
+test("marks a leaf agentic when it carries a linkName=\"prompt\" linked resource", () => {
+  const xml = `<bpmn:definitions xmlns:bpmn="x" xmlns:zeebe="y">
+    <bpmn:process id="nwf-retro">
+      <bpmn:serviceTask id="retro">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="senior:retro" />
+          <zeebe:linkedResources>
+            <zeebe:linkedResource resourceId="retro.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          </zeebe:linkedResources>
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+      <bpmn:serviceTask id="gather">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="pr.retro-gather" />
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+    </bpmn:process>
+  </bpmn:definitions>`;
+  const leaves = scanTaskDefinitions(xml);
+  assert.deepEqual(leaves, [
+    { taskType: "senior:retro", process: "nwf-retro", elementId: "retro", agentic: true },
+    { taskType: "pr.retro-gather", process: "nwf-retro", elementId: "gather", agentic: false },
+  ]);
+});
+
+test("prompt detection tolerates attribute ordering (linkName before resourceId)", () => {
+  const xml = `<bpmn:definitions xmlns:bpmn="x" xmlns:zeebe="y">
+    <bpmn:serviceTask id="t">
+      <zeebe:taskDefinition type="senior:feature" />
+      <zeebe:linkedResource linkName="prompt" resourceId="feature.md" />
+    </bpmn:serviceTask>
+  </bpmn:definitions>`;
+  assert.equal(scanTaskDefinitions(xml)[0].agentic, true);
+});
+
+test("a non-prompt linked resource (other linkName) does not mark a leaf agentic", () => {
+  const xml = `<bpmn:definitions xmlns:bpmn="x" xmlns:zeebe="y">
+    <bpmn:serviceTask id="t">
+      <zeebe:taskDefinition type="senior:feature" />
+      <zeebe:linkedResource resourceId="schema.md" linkName="schema" />
+    </bpmn:serviceTask>
+  </bpmn:definitions>`;
+  assert.equal(scanTaskDefinitions(xml)[0].agentic, false);
+});

package/src/demand/taskdef.ts

@@ -22,6 +22,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;
 }
 
 function attr(tag: string, name: string): string {
@@ -34,13 +45,31 @@ function processId(xml: string): string {
   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: string): boolean {
+  const linkRe = /<zeebe:linkedResource\b[^>]*?\/?>/g;
+  let link: RegExpExecArray | null;
+  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: string): TaskDefinitionLeaf[] {
   const proc = processId(xml);
@@ -55,7 +84,7 @@ export function scanTaskDefinitions(xml: string): TaskDefinitionLeaf[] {
     if (!tdMatch) continue;
     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/src/index.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";