@nanobpm/agentic 0.1.0 → 0.5.0

package/dist/transcript/store.js

@@ -22,9 +22,17 @@
  * ({@link SqliteDb}), so it works against any app DataLayer source without pulling
  * in the whole runtime.
  */
-import { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE } from "./schema.js";
+import { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE, TRANSCRIPT_TURN_SCHEMA_SQL, TRANSCRIPT_TURN_TABLE, } from "./schema.js";
 /** The default clock: `Date.now()`. */
 export const systemClock = { now: () => Date.now() };
+const TURN_ROLES = [
+    "USER",
+    "ASSISTANT",
+    "TOOL_RESULT",
+    "CONFIGURATION",
+    "UNSPECIFIED",
+];
+const CONTENT_TYPES = ["TEXT", "DOCUMENT", "OBJECT", "UNSPECIFIED"];
 const DEFAULT_EPHEMERAL_RETENTION_MS = 86_400_000;
 function isNonNegInt(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -63,6 +71,208 @@ function toStream(row) {
         out.firstOffset = row.first_offset;
     return out;
 }
+/**
+ * A plain JSON-shaped object: an ordinary or null-prototype object, never an array or a
+ * class instance (e.g. `Date`, `Map`). Rejecting exotic instances at the boundary stops a
+ * value that would serialise via `toJSON()` into a non-object (making the stored turn
+ * unreadable) from ever being persisted.
+ */
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function toTurnRole(value) {
+    const match = TURN_ROLES.find((role) => role === value);
+    if (match !== undefined)
+        return match;
+    throw new TranscriptCorruptionError(`invalid transcript turn role: ${JSON.stringify(value)}`);
+}
+function toContentType(value) {
+    const match = CONTENT_TYPES.find((type) => type === value);
+    if (match !== undefined)
+        return match;
+    throw new TranscriptCorruptionError(`invalid transcript content type: ${JSON.stringify(value)}`);
+}
+/**
+ * The payload key each content type carries: TEXT→`text`, DOCUMENT→`documentReference`,
+ * OBJECT→`object`; UNSPECIFIED carries none. Drives the per-`contentType` payload
+ * invariant enforced by {@link toContentBlock}.
+ */
+const CONTENT_PAYLOAD_KEYS = ["text", "documentReference", "object"];
+const CONTENT_TYPE_PAYLOAD = {
+    TEXT: "text",
+    DOCUMENT: "documentReference",
+    OBJECT: "object",
+    UNSPECIFIED: null,
+};
+/**
+ * Validate a value into a canonical content block, enforcing the per-`contentType`
+ * payload invariant: a block carries exactly the one payload its type mandates
+ * (TEXT→text, DOCUMENT→documentReference, OBJECT→object) — never a missing, mismatched
+ * or multiple payload — and UNSPECIFIED carries none. This is the single validator both
+ * the write path (record) and the read path (deserialise) run through, so the two can
+ * never drift and a malformed block can neither persist nor round-trip. It emits only
+ * that one payload key, so serialise/deserialise round-trips exactly.
+ */
+function toContentBlock(value) {
+    if (!isPlainObject(value)) {
+        throw new TranscriptCorruptionError(`transcript content block must be an object, got ${JSON.stringify(value)}`);
+    }
+    const contentType = toContentType(value.contentType);
+    const present = CONTENT_PAYLOAD_KEYS.filter((key) => key in value && value[key] !== undefined);
+    const expected = CONTENT_TYPE_PAYLOAD[contentType];
+    if (expected === null) {
+        if (present.length > 0) {
+            throw new TranscriptCorruptionError(`${contentType} content block must carry no payload, got ${JSON.stringify(present)}`);
+        }
+        return { contentType };
+    }
+    if (present.length !== 1 || present[0] !== expected) {
+        throw new TranscriptCorruptionError(`${contentType} content block must carry exactly its ${expected} payload, got ${JSON.stringify(present)}`);
+    }
+    if (expected === "text") {
+        const text = value.text;
+        if (typeof text !== "string") {
+            throw new TranscriptCorruptionError(`content block text must be a string, got ${JSON.stringify(text)}`);
+        }
+        return { contentType, text };
+    }
+    if (expected === "documentReference") {
+        const documentReference = value.documentReference;
+        if (typeof documentReference !== "string") {
+            throw new TranscriptCorruptionError(`content block documentReference must be a string, got ${JSON.stringify(documentReference)}`);
+        }
+        return { contentType, documentReference };
+    }
+    return { contentType, object: value.object };
+}
+/**
+ * Validate a value into a canonical tool call — the single validator both the write and
+ * read paths run through. Mirrors Camunda's `AgentHistoryEmbeddedToolCallValue`.
+ */
+function toToolCall(value) {
+    if (!isPlainObject(value)) {
+        throw new TranscriptCorruptionError(`transcript tool call must be an object, got ${JSON.stringify(value)}`);
+    }
+    const { toolCallId, toolName, elementId } = value;
+    if (typeof toolCallId !== "string") {
+        throw new TranscriptCorruptionError(`tool call toolCallId must be a string, got ${JSON.stringify(toolCallId)}`);
+    }
+    if (typeof toolName !== "string") {
+        throw new TranscriptCorruptionError(`tool call toolName must be a string, got ${JSON.stringify(toolName)}`);
+    }
+    const args = value.arguments;
+    if (!isPlainObject(args)) {
+        throw new TranscriptCorruptionError(`tool call arguments must be an object, got ${JSON.stringify(args)}`);
+    }
+    const out = {
+        toolCallId,
+        toolName,
+        arguments: args,
+    };
+    if (elementId !== undefined) {
+        if (typeof elementId !== "string") {
+            throw new TranscriptCorruptionError(`tool call elementId must be a string, got ${JSON.stringify(elementId)}`);
+        }
+        out.elementId = elementId;
+    }
+    return out;
+}
+function readMetric(source, key) {
+    const value = source[key];
+    if (!isNonNegInt(value)) {
+        throw new TranscriptCorruptionError(`transcript metric "${key}" must be a non-negative safe integer, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/**
+ * Validate a value into canonical per-turn metrics — the single validator both the write
+ * and read paths run through. Every field must be a non-negative safe integer: Camunda's
+ * `AgentHistoryMetricsValue` token counts and `durationMs` are integer-valued and cannot be
+ * negative, so an out-of-domain value is treated as corruption rather than round-tripped.
+ */
+function toMetrics(value) {
+    if (!isPlainObject(value)) {
+        throw new TranscriptCorruptionError(`transcript turn metrics must be an object, got ${JSON.stringify(value)}`);
+    }
+    return {
+        inputTokens: readMetric(value, "inputTokens"),
+        outputTokens: readMetric(value, "outputTokens"),
+        reasoningTokenCount: readMetric(value, "reasoningTokenCount"),
+        cacheCreationTokenCount: readMetric(value, "cacheCreationTokenCount"),
+        cacheReadTokenCount: readMetric(value, "cacheReadTokenCount"),
+        durationMs: readMetric(value, "durationMs"),
+    };
+}
+/**
+ * Parse a JSON column, re-raising a malformed-JSON `SyntaxError` as a
+ * {@link TranscriptCorruptionError} so every read-back failure surfaces through the store's
+ * single corruption signal rather than a raw parse error.
+ */
+function parseJsonColumn(json, label) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (err) {
+        throw new TranscriptCorruptionError(`transcript turn ${label} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Parse a JSON array column, failing with a corruption error on invalid JSON or non-arrays. */
+function parseJsonArray(json, label) {
+    const parsed = parseJsonColumn(json, label);
+    if (!Array.isArray(parsed)) {
+        throw new TranscriptCorruptionError(`transcript turn ${label} must be a JSON array, got ${JSON.stringify(parsed)}`);
+    }
+    return parsed;
+}
+/**
+ * Serialise a validated turn payload for storage, re-raising a non-serialisable value
+ * (e.g. a `bigint`, which makes `JSON.stringify` throw a `TypeError`) as a
+ * {@link TranscriptCorruptionError} so the untyped write boundary only ever surfaces the
+ * store's own error taxonomy.
+ */
+function stringifyJson(value, label) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch (err) {
+        throw new TranscriptCorruptionError(`transcript turn ${label} is not JSON-serialisable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Reconstruct a structured turn from its DB row, validating every field so a corrupted
+ * or hand-edited row fails fast with a {@link TranscriptCorruptionError} rather than
+ * silently propagating an out-of-domain value. `turn_sequence`, `loop_iteration` and
+ * `produced_at` are held to the same non-negative-safe-integer domain the write path
+ * enforces.
+ */
+function toTurn(row) {
+    if (!isRecordableOffset(row.turn_sequence)) {
+        throw new TranscriptCorruptionError(`transcript turn sequence must be a non-negative safe integer, got ${JSON.stringify(row.turn_sequence)}`);
+    }
+    if (!isNonNegInt(row.loop_iteration)) {
+        throw new TranscriptCorruptionError(`transcript turn loopIteration must be a non-negative safe integer, got ${JSON.stringify(row.loop_iteration)}`);
+    }
+    const out = {
+        sequence: row.turn_sequence,
+        loopIteration: row.loop_iteration,
+        role: toTurnRole(row.role),
+        content: parseJsonArray(row.content, "content").map(toContentBlock),
+        toolCalls: parseJsonArray(row.tool_calls, "toolCalls").map(toToolCall),
+    };
+    if (row.metrics !== null) {
+        out.metrics = toMetrics(parseJsonColumn(row.metrics, "metrics"));
+    }
+    if (row.produced_at !== null) {
+        if (!isNonNegInt(row.produced_at)) {
+            throw new TranscriptCorruptionError(`transcript turn producedAt must be a non-negative safe integer, got ${JSON.stringify(row.produced_at)}`);
+        }
+        out.producedAt = row.produced_at;
+    }
+    return out;
+}
 /**
  * Raised when a transcript row read back from storage holds a value outside its
  * domain (e.g. an unknown `lifecycle`/`status`), signalling schema corruption or a
@@ -106,12 +316,15 @@ export class TranscriptStore {
     }
     /**
      * Apply the canonical transcript DDL (idempotent). Callers that let the app
-     * DataLayer migration runner apply `db/migrations/002_agentic_transcript.sql`
-     * do not need this — but it is provided so the store is usable against a bare
-     * source too. The DDL is identical to the migration (drift-guarded).
+     * DataLayer migration runner apply the transcript migrations
+     * (`db/migrations/002_agentic_transcript.sql` for the chunk stream and
+     * `db/migrations/008_agentic_transcript_turns.sql` for the turn-structured
+     * view) do not need this — but it is provided so the store is usable against a
+     * bare source too. The DDL is identical to the migrations (drift-guarded).
      */
     ensureSchema() {
         this.#db.exec(TRANSCRIPT_SCHEMA_SQL);
+        this.#db.exec(TRANSCRIPT_TURN_SCHEMA_SQL);
     }
     /**
      * Open (or fetch) a stream's transcript with the given lifecycle. Idempotent:
@@ -228,6 +441,72 @@ export class TranscriptStore {
             .all(`SELECT chunk_offset, chunk FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ? ORDER BY chunk_offset`, [stream])
             .map((r) => ({ offset: r.chunk_offset, chunk: r.chunk }));
     }
+    /**
+     * Record structured turns into a stream's additive turn-structured view — the
+     * Camunda `AgentHistoryRecordValue` parity layer (issue #475). Each turn is
+     * keyed `(stream, sequence)` so re-recording an already-stored sequence (a
+     * retry, a re-emit, an overlapping reattach) is a no-op — never a duplicate,
+     * exactly the idempotency the chunk stream gets from `(stream, offset)`.
+     *
+     * This is purely additive: it never reads or writes the raw chunk stream or the
+     * stream's offset window, so it cannot regress any existing chunk reader. It
+     * auto-opens the stream (default `long-lived`) so the turns hang off a stream
+     * row; a lifecycle mismatch throws a {@link TranscriptLifecycleError} before
+     * writing anything (lifecycle is first-wins). The batch is atomic: an invalid
+     * turn (or any failed write) partway through rolls the whole call back — it
+     * records every turn or none. Returns the number of newly-persisted turns.
+     */
+    recordTurns(stream, turns, lifecycle = "long-lived") {
+        const meta = this.open(stream, lifecycle);
+        if (meta.lifecycle !== lifecycle) {
+            throw new TranscriptLifecycleError(stream, `refusing to record turns into "${stream}" with lifecycle=${lifecycle}; the stream is ${meta.lifecycle} (lifecycle is first-wins)`);
+        }
+        const at = new Date(this.#clock.now()).toISOString();
+        return this.#atomic(() => {
+            let written = 0;
+            for (const turn of turns) {
+                if (!isPlainObject(turn)) {
+                    throw new TranscriptCorruptionError(`transcript turn must be an object, got ${JSON.stringify(turn)}`);
+                }
+                if (!isRecordableOffset(turn.sequence)) {
+                    throw new RangeError(`transcript turn sequence must be a non-negative safe integer below Number.MAX_SAFE_INTEGER, got ${turn.sequence}`);
+                }
+                if (!isNonNegInt(turn.loopIteration)) {
+                    throw new RangeError(`transcript turn loopIteration must be a non-negative safe integer, got ${turn.loopIteration}`);
+                }
+                const role = toTurnRole(turn.role);
+                if (!Array.isArray(turn.content)) {
+                    throw new TranscriptCorruptionError(`transcript turn content must be an array, got ${JSON.stringify(turn.content)}`);
+                }
+                if (!Array.isArray(turn.toolCalls)) {
+                    throw new TranscriptCorruptionError(`transcript turn toolCalls must be an array, got ${JSON.stringify(turn.toolCalls)}`);
+                }
+                const content = stringifyJson(turn.content.map(toContentBlock), "content");
+                const toolCalls = stringifyJson(turn.toolCalls.map(toToolCall), "toolCalls");
+                const metrics = turn.metrics === undefined ? null : stringifyJson(toMetrics(turn.metrics), "metrics");
+                let producedAt = null;
+                if (turn.producedAt !== undefined) {
+                    if (!isNonNegInt(turn.producedAt)) {
+                        throw new RangeError(`transcript turn producedAt must be a non-negative safe integer (epoch millis), got ${turn.producedAt}`);
+                    }
+                    producedAt = turn.producedAt;
+                }
+                const { changes } = this.#db.run(`INSERT INTO ${TRANSCRIPT_TURN_TABLE}
+             (stream, turn_sequence, loop_iteration, role, content, tool_calls, metrics, produced_at, recorded_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(stream, turn_sequence) DO NOTHING`, [stream, turn.sequence, turn.loopIteration, role, content, toolCalls, metrics, producedAt, at]);
+                written += changes;
+            }
+            return written;
+        });
+    }
+    /** Read a stream's whole turn-structured transcript in `sequence` order. */
+    readTurns(stream) {
+        return this.#db
+            .all(`SELECT turn_sequence, loop_iteration, role, content, tool_calls, metrics, produced_at
+         FROM ${TRANSCRIPT_TURN_TABLE} WHERE stream = ? ORDER BY turn_sequence`, [stream])
+            .map(toTurn);
+    }
     /**
      * Apply a rolling retention window to a long-lived stream: drop every chunk with
      * `offset < before`. A subsequent {@link since} from an offset older than
@@ -253,8 +532,9 @@ export class TranscriptStore {
     /**
      * Retention sweep for completed ephemeral transcripts: drop every stream whose
      * `status = 'completed'` and whose `completed_at` is older than the retention
-     * window, along with its chunks. Long-lived streams are never time-swept (they
-     * are bounded by {@link truncateBefore} instead). Returns the removed stream ids.
+     * window, along with its chunks and structured turns. Long-lived streams are
+     * never time-swept (they are bounded by {@link truncateBefore} instead). Returns
+     * the removed stream ids.
      *
      * The selection and all deletes run inside a single SAVEPOINT (#atomic) so the
      * sweep is all-or-nothing: if any delete throws mid-sweep the whole batch rolls
@@ -271,6 +551,7 @@ export class TranscriptStore {
                 .map((r) => r.stream);
             for (const stream of removed) {
                 this.#db.run(`DELETE FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ?`, [stream]);
+                this.#db.run(`DELETE FROM ${TRANSCRIPT_TURN_TABLE} WHERE stream = ?`, [stream]);
                 this.#db.run(`DELETE FROM ${TRANSCRIPT_STREAM_TABLE} WHERE stream = ?`, [stream]);
             }
             return removed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/agentic",
-  "version": "0.1.0",
+  "version": "0.5.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);
+});