@carlonicora/nestjs-neo4jsonapi 2.3.0 → 2.4.0

package/dist/agents/common/usage-attribution.d.ts

@@ -0,0 +1,218 @@
+import { DataLimits } from "../../common/types/data.limits";
+import { EmbedderAttribution } from "../../core/llm/services/embedder.service";
+/**
+ * Cost attribution for one assistant LLM call, in the exact shape
+ * `LLMService.call` / `LLMService.callStep` accept.
+ *
+ * The agents carry their run scope as a JSON:API TYPE (`"campaigns"`), but a
+ * TokenUsage record's `USED_FOR` edge is matched on the Neo4j LABEL
+ * (`"Campaign"`). Passing the type through verbatim writes a record whose edge
+ * matches nothing — it looks attributed and silently bills against no entity.
+ * The registry is the only mapping that stays correct as entities are added, so
+ * every assistant call site goes through this one translation.
+ */
+export interface ScopeAttribution {
+    tokenUsageType: string;
+    relationshipId?: string;
+    relationshipType?: string;
+}
+/**
+ * JSON:API type ("campaigns") to Neo4j label ("Campaign"); undefined when the
+ * type is absent or unregistered.
+ *
+ * A MISS IS LOUD. An unresolvable type would otherwise leave `relationshipType`
+ * undefined while `relationshipId` is set, and `persistUsage` skips silently on
+ * exactly that shape — the "looks attributed, records nothing" failure this
+ * helper exists to prevent. The caller also falls back to the thread, so a miss
+ * degrades to a coarser attribution rather than to no billing at all.
+ */
+export declare function resolveScopeLabel(scopeType?: string): string | undefined;
+/**
+ * Builds the attribution triple for one assistant call. Spread into the LLM call
+ * params so no site can apply half of it.
+ *
+ * Precedence:
+ *  1. the run's SCOPE ROOT (a campaign) — the most useful unit of spend, used
+ *     whenever the turn has one AND its label is known. `scopeLabel` is the
+ *     label the caller already resolved (the catalog carries `rootLabel`
+ *     alongside `rootType`); the registry lookup is the fallback for callers
+ *     that only have the JSON:API type.
+ *  2. the ASSISTANT THREAD itself — every turn has one, whatever the thread is
+ *     bound to, so an unscoped turn still bills instead of running free.
+ *  3. nothing — only when the caller supplied neither, in which case
+ *     `persistUsage` skips the record.
+ */
+export declare function buildScopeAttribution(params: {
+    tokenUsageType: string;
+    scopeId?: string;
+    scopeType?: string;
+    /** Neo4j label of the scope root, when the caller already knows it. */
+    scopeLabel?: string;
+    /** Id of the `Assistant` (thread) node this turn belongs to. */
+    assistantId?: string;
+}): ScopeAttribution;
+/**
+ * The caller's cost attribution, carried through a SUB-AGENT's graph state.
+ *
+ * The contextualiser and DRIFT are never invoked on their own behalf: another
+ * agent calls them, and that agent's ledger entry is the one the spend belongs
+ * to. So they own no `TokenUsageType` value of their own and name no entity of
+ * their own — they carry the caller's, verbatim, and apply it at every LLM call
+ * they make.
+ *
+ * EVERY FIELD IS OPTIONAL. A direct library consumer that supplies none still
+ * runs; its calls simply record nothing (`persistUsage` skips a record with no
+ * relationship), exactly like every other unattributed path in the package.
+ */
+export interface CallerAttributionState {
+    /**
+     * Ledger category of the CALLING agent (e.g. `TokenUsageType.Responder`).
+     * Absent = the library default (`text_generation`); a sub-agent never
+     * substitutes an identity of its own here.
+     */
+    tokenUsageType?: string;
+    /** Id of the caller's scope-root node. Absent = the caller ran unscoped. */
+    scopeId?: string;
+    /** JSON:API type of that scope root, e.g. "campaigns". */
+    scopeType?: string;
+    /** Neo4j label of that scope root, e.g. "Campaign". */
+    scopeLabel?: string;
+    /** Id of the caller's `Assistant` (thread) node — the unscoped fallback. */
+    assistantId?: string;
+}
+/**
+ * Packs a CALLING agent's own attribution into the shape its sub-agents accept.
+ *
+ * `source` is whatever the caller already holds — its graph state, or the
+ * per-turn tool context — both of which carry the scope triple and the thread
+ * id under these exact names. `tokenUsageType` is always the caller's own; a
+ * sub-agent must never appear in the ledger under a category of its own.
+ */
+export declare function buildCallerAttribution(params: {
+    tokenUsageType: string;
+    source?: {
+        scopeId?: string;
+        scopeType?: string;
+        scopeLabel?: string;
+        assistantId?: string;
+    };
+}): CallerAttributionState;
+/**
+ * What a caller actually handed a sub-agent, so the sub-agent can log
+ * PROPORTIONATELY. These are three different situations and only one of them is
+ * a fault:
+ *
+ *  - `"billable"` — an entity the usage record can point at. Nothing to say.
+ *  - `"none"` — the caller named NO entity at all. This is LEGITIMATE and
+ *    permanent for some callers: an MCP tool call has no scope root and no
+ *    assistant thread (`McpUserContext` carries only userId/companyId/
+ *    userModuleIds), and a direct library consumer need not attribute anything.
+ *    Nothing is recorded, nothing is wrong, and warning here would mean a
+ *    warning on EVERY MCP `search_documents` call forever.
+ *  - `"unresolvable"` — the caller DID name something, but it cannot become a
+ *    `USED_FOR` edge (a `scopeType` no model claims, a `scopeId` with no label,
+ *    a `scopeLabel` with no id). That IS a fault: it looks attributed and bills
+ *    nothing, which is the exact failure this whole helper exists to prevent.
+ *
+ * `tokenUsageType` deliberately does NOT count as "named something": every
+ * caller supplies a category unconditionally (`buildCallerAttribution` always
+ * sets it), so counting it would collapse `"none"` into `"unresolvable"` and
+ * bring the spam straight back.
+ *
+ * The registry is only consulted once something was named, so the `"none"` path
+ * costs nothing and cannot emit `resolveScopeLabel`'s own warning.
+ */
+export declare function classifyCallerAttribution(state?: CallerAttributionState): "billable" | "none" | "unresolvable";
+/**
+ * Attribution for one LLM call made by a SUB-AGENT, derived entirely from the
+ * caller's. Spread into the LLM call params — always last — so no site can
+ * apply half of it.
+ *
+ * Identical precedence to {@link buildScopeAttribution} (scope root → assistant
+ * thread → nothing); the only addition is the `tokenUsageType` default, which
+ * is the LIBRARY's default rather than any sub-agent name. Inventing
+ * `"contextualiser"` / `"drift"` here would split one agent's spend across
+ * ledger categories the app never asked for.
+ */
+export declare function buildInheritedAttribution(state?: CallerAttributionState): ScopeAttribution;
+/**
+ * Attribution for one EMBEDDING call (`EmbedderService.vectoriseText` /
+ * `vectoriseTextBatch`), or `undefined` when the caller holds no entity to bill
+ * it to — `EmbedderService.persistUsage` then skips the record entirely rather
+ * than writing one whose `USED_FOR` edge matches nothing.
+ *
+ * `entityIdentifier` is whatever the call site happens to hold: a Neo4j LABEL
+ * ("Npc"), a JSON:API type ("npcs"), or a nodeName. `modelRegistry.resolveModel`
+ * accepts all three and yields the label the `USED_FOR` edge is matched on —
+ * the same translation `resolveScopeLabel` performs for LLM calls.
+ *
+ * DIFFERENCE FROM `resolveScopeLabel`: an unresolvable identifier FALLS BACK to
+ * itself instead of dropping the attribution. That is safe at the INGESTION call
+ * sites, which already interpolate the same value into Cypher as a label
+ * (`MATCH (nodeType:${params.nodeType} {id: $nodeId})`), so an identifier the
+ * registry does not know is still a valid label there — and if it were not, that
+ * Cypher would have matched nothing and there would be no chunk to embed.
+ * Dropping it would silently lose a real, attributable cost.
+ *
+ * IT IS NOT SAFE AT THE QUERY-TIME CALL SITES. `GraphSearchService.tierSemantic`
+ * passes `scopeType` — always a JSON:API type — and `buildRetrievalAttribution`
+ * passes `contentType`, which is whichever of the two the caller set (narr8 sets
+ * a JSON:API type; the contextualiser's own chunk-vector node compares it
+ * against the LABEL "Conversation"). Either way an UNRESOLVED value is written
+ * verbatim into `MATCH (relEntity:${relationshipType} {id: $relationshipId})`
+ * and matches nothing — precisely the failure this helper exists to prevent.
+ * Every such input is registry-registered today, so the fallback is latent
+ * rather than live, which is why it WARNS rather than throws: the warning names
+ * the identifier so the regression is visible the moment it appears, instead of
+ * surfacing as a TokenUsage row with no `USED_FOR` edge.
+ */
+export declare function buildEmbedderAttribution(params: {
+    /** Id of the node the spend is billed against. */
+    entityId?: string;
+    /** Neo4j label, JSON:API type or nodeName of that node. */
+    entityIdentifier?: string;
+    /** Overrides the recorder's default (`TokenUsageType.Embedding`). */
+    tokenUsageType?: string;
+}): EmbedderAttribution | undefined;
+/**
+ * Attribution for an EMBEDDING made by a SUB-AGENT, derived from the caller's
+ * attribution through the SAME precedence chain as
+ * {@link buildInheritedAttribution} (scope root → assistant thread → nothing),
+ * so a turn's LLM spend and its embedding spend always land on one entity.
+ *
+ * `tokenUsageType` is deliberately omitted: the recorder's own default
+ * (`embedding`) classifies the OPERATION, and it is not the sub-agent inventing
+ * an identity — the caller's identity is already expressed by the entity the
+ * record points at.
+ */
+export declare function buildInheritedEmbedderAttribution(state?: CallerAttributionState): EmbedderAttribution | undefined;
+/**
+ * Attribution for a QUERY-time (retrieval) embedding — the contextualiser
+ * embedding the user's question to search chunks / key concepts.
+ *
+ * A search has no entity of its own, so it is billed to the SCOPE BEING
+ * SEARCHED, in the order the retrieval itself narrows:
+ *  1. the CALLER's scope root, when the contextualiser was invoked by another
+ *     agent that confined the whole turn to one (`scope`). It is the widest
+ *     honest unit of spend and the same entity that agent's own LLM calls bill,
+ *     so a turn is not split across two ledger targets;
+ *  2. the content the run is bound to (`contentId` + `contentType`, a JSON:API
+ *     type resolved to its label) — the retrieval scope the caller passes in;
+ *  3. help mode's single HowTo (`dataLimits.limitToHowToId`), which is the only
+ *     scope a help-mode run has;
+ *  4. nothing — an unbound, non-help run genuinely searches the whole company,
+ *     so there is no honest entity to name and `persistUsage` skips the record
+ *     rather than inventing one.
+ *
+ * `dataLimits.howToMode` on its own carries NO id, so it deliberately does not
+ * produce an attribution: guessing one would write a `USED_FOR` edge that
+ * matches nothing.
+ */
+export declare function buildRetrievalAttribution(params: {
+    contentId?: string;
+    contentType?: string;
+    dataLimits?: DataLimits;
+    /** The calling agent's attribution, when this retrieval runs inside another agent's turn. */
+    scope?: CallerAttributionState;
+}): EmbedderAttribution | undefined;
+//# sourceMappingURL=usage-attribution.d.ts.map

package/dist/agents/common/usage-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-attribution.d.ts","sourceRoot":"","sources":["../../../src/agents/common/usage-attribution.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAO/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,gBAAgB,CAenB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9F,GAAG,sBAAsB,CAQzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,CAAC,EAAE,sBAAsB,GAAG,UAAU,GAAG,MAAM,GAAG,cAAc,CAI9G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,CAAC,EAAE,sBAAsB,GAAG,gBAAgB,CAQ1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,mBAAmB,GAAG,SAAS,CAelC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,CAAC,EAAE,sBAAsB,GAAG,mBAAmB,GAAG,SAAS,CAIjH;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC,GAAG,mBAAmB,GAAG,SAAS,CAelC"}

package/dist/agents/common/usage-attribution.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveScopeLabel = resolveScopeLabel;
+exports.buildScopeAttribution = buildScopeAttribution;
+exports.buildCallerAttribution = buildCallerAttribution;
+exports.classifyCallerAttribution = classifyCallerAttribution;
+exports.buildInheritedAttribution = buildInheritedAttribution;
+exports.buildEmbedderAttribution = buildEmbedderAttribution;
+exports.buildInheritedEmbedderAttribution = buildInheritedEmbedderAttribution;
+exports.buildRetrievalAttribution = buildRetrievalAttribution;
+const common_1 = require("@nestjs/common");
+const registry_1 = require("../../common/registries/registry");
+const assistant_meta_1 = require("../../foundations/assistant/entities/assistant.meta");
+const how_to_meta_1 = require("../../foundations/how-to/entities/how-to.meta");
+const tokenusage_type_1 = require("../../foundations/tokenusage/enums/tokenusage.type");
+const logger = new common_1.Logger("UsageAttribution");
+/**
+ * JSON:API type ("campaigns") to Neo4j label ("Campaign"); undefined when the
+ * type is absent or unregistered.
+ *
+ * A MISS IS LOUD. An unresolvable type would otherwise leave `relationshipType`
+ * undefined while `relationshipId` is set, and `persistUsage` skips silently on
+ * exactly that shape — the "looks attributed, records nothing" failure this
+ * helper exists to prevent. The caller also falls back to the thread, so a miss
+ * degrades to a coarser attribution rather than to no billing at all.
+ */
+function resolveScopeLabel(scopeType) {
+    if (!scopeType)
+        return undefined;
+    const labelName = registry_1.modelRegistry.resolveModel(scopeType)?.labelName;
+    if (!labelName) {
+        logger.warn(`scopeType "${scopeType}" resolves to no registered model — cannot translate it to a Neo4j label. ` +
+            `Falling back to thread-level attribution for this call.`);
+    }
+    return labelName;
+}
+/**
+ * Builds the attribution triple for one assistant call. Spread into the LLM call
+ * params so no site can apply half of it.
+ *
+ * Precedence:
+ *  1. the run's SCOPE ROOT (a campaign) — the most useful unit of spend, used
+ *     whenever the turn has one AND its label is known. `scopeLabel` is the
+ *     label the caller already resolved (the catalog carries `rootLabel`
+ *     alongside `rootType`); the registry lookup is the fallback for callers
+ *     that only have the JSON:API type.
+ *  2. the ASSISTANT THREAD itself — every turn has one, whatever the thread is
+ *     bound to, so an unscoped turn still bills instead of running free.
+ *  3. nothing — only when the caller supplied neither, in which case
+ *     `persistUsage` skips the record.
+ */
+function buildScopeAttribution(params) {
+    const scopeLabel = params.scopeId ? (params.scopeLabel ?? resolveScopeLabel(params.scopeType)) : undefined;
+    if (params.scopeId && scopeLabel) {
+        return { tokenUsageType: params.tokenUsageType, relationshipId: params.scopeId, relationshipType: scopeLabel };
+    }
+    if (params.assistantId) {
+        return {
+            tokenUsageType: params.tokenUsageType,
+            relationshipId: params.assistantId,
+            relationshipType: assistant_meta_1.assistantMeta.labelName,
+        };
+    }
+    return { tokenUsageType: params.tokenUsageType };
+}
+/**
+ * Packs a CALLING agent's own attribution into the shape its sub-agents accept.
+ *
+ * `source` is whatever the caller already holds — its graph state, or the
+ * per-turn tool context — both of which carry the scope triple and the thread
+ * id under these exact names. `tokenUsageType` is always the caller's own; a
+ * sub-agent must never appear in the ledger under a category of its own.
+ */
+function buildCallerAttribution(params) {
+    return {
+        tokenUsageType: params.tokenUsageType,
+        scopeId: params.source?.scopeId,
+        scopeType: params.source?.scopeType,
+        scopeLabel: params.source?.scopeLabel,
+        assistantId: params.source?.assistantId,
+    };
+}
+/**
+ * What a caller actually handed a sub-agent, so the sub-agent can log
+ * PROPORTIONATELY. These are three different situations and only one of them is
+ * a fault:
+ *
+ *  - `"billable"` — an entity the usage record can point at. Nothing to say.
+ *  - `"none"` — the caller named NO entity at all. This is LEGITIMATE and
+ *    permanent for some callers: an MCP tool call has no scope root and no
+ *    assistant thread (`McpUserContext` carries only userId/companyId/
+ *    userModuleIds), and a direct library consumer need not attribute anything.
+ *    Nothing is recorded, nothing is wrong, and warning here would mean a
+ *    warning on EVERY MCP `search_documents` call forever.
+ *  - `"unresolvable"` — the caller DID name something, but it cannot become a
+ *    `USED_FOR` edge (a `scopeType` no model claims, a `scopeId` with no label,
+ *    a `scopeLabel` with no id). That IS a fault: it looks attributed and bills
+ *    nothing, which is the exact failure this whole helper exists to prevent.
+ *
+ * `tokenUsageType` deliberately does NOT count as "named something": every
+ * caller supplies a category unconditionally (`buildCallerAttribution` always
+ * sets it), so counting it would collapse `"none"` into `"unresolvable"` and
+ * bring the spam straight back.
+ *
+ * The registry is only consulted once something was named, so the `"none"` path
+ * costs nothing and cannot emit `resolveScopeLabel`'s own warning.
+ */
+function classifyCallerAttribution(state) {
+    const namedSomething = !!(state?.scopeId || state?.scopeType || state?.scopeLabel || state?.assistantId);
+    if (!namedSomething)
+        return "none";
+    return buildInheritedAttribution(state).relationshipId ? "billable" : "unresolvable";
+}
+/**
+ * Attribution for one LLM call made by a SUB-AGENT, derived entirely from the
+ * caller's. Spread into the LLM call params — always last — so no site can
+ * apply half of it.
+ *
+ * Identical precedence to {@link buildScopeAttribution} (scope root → assistant
+ * thread → nothing); the only addition is the `tokenUsageType` default, which
+ * is the LIBRARY's default rather than any sub-agent name. Inventing
+ * `"contextualiser"` / `"drift"` here would split one agent's spend across
+ * ledger categories the app never asked for.
+ */
+function buildInheritedAttribution(state) {
+    return buildScopeAttribution({
+        tokenUsageType: state?.tokenUsageType ?? tokenusage_type_1.TokenUsageType.TextGeneration,
+        scopeId: state?.scopeId,
+        scopeType: state?.scopeType,
+        scopeLabel: state?.scopeLabel,
+        assistantId: state?.assistantId,
+    });
+}
+/**
+ * Attribution for one EMBEDDING call (`EmbedderService.vectoriseText` /
+ * `vectoriseTextBatch`), or `undefined` when the caller holds no entity to bill
+ * it to — `EmbedderService.persistUsage` then skips the record entirely rather
+ * than writing one whose `USED_FOR` edge matches nothing.
+ *
+ * `entityIdentifier` is whatever the call site happens to hold: a Neo4j LABEL
+ * ("Npc"), a JSON:API type ("npcs"), or a nodeName. `modelRegistry.resolveModel`
+ * accepts all three and yields the label the `USED_FOR` edge is matched on —
+ * the same translation `resolveScopeLabel` performs for LLM calls.
+ *
+ * DIFFERENCE FROM `resolveScopeLabel`: an unresolvable identifier FALLS BACK to
+ * itself instead of dropping the attribution. That is safe at the INGESTION call
+ * sites, which already interpolate the same value into Cypher as a label
+ * (`MATCH (nodeType:${params.nodeType} {id: $nodeId})`), so an identifier the
+ * registry does not know is still a valid label there — and if it were not, that
+ * Cypher would have matched nothing and there would be no chunk to embed.
+ * Dropping it would silently lose a real, attributable cost.
+ *
+ * IT IS NOT SAFE AT THE QUERY-TIME CALL SITES. `GraphSearchService.tierSemantic`
+ * passes `scopeType` — always a JSON:API type — and `buildRetrievalAttribution`
+ * passes `contentType`, which is whichever of the two the caller set (narr8 sets
+ * a JSON:API type; the contextualiser's own chunk-vector node compares it
+ * against the LABEL "Conversation"). Either way an UNRESOLVED value is written
+ * verbatim into `MATCH (relEntity:${relationshipType} {id: $relationshipId})`
+ * and matches nothing — precisely the failure this helper exists to prevent.
+ * Every such input is registry-registered today, so the fallback is latent
+ * rather than live, which is why it WARNS rather than throws: the warning names
+ * the identifier so the regression is visible the moment it appears, instead of
+ * surfacing as a TokenUsage row with no `USED_FOR` edge.
+ */
+function buildEmbedderAttribution(params) {
+    if (!params.entityId || !params.entityIdentifier)
+        return undefined;
+    const resolved = registry_1.modelRegistry.resolveModel(params.entityIdentifier)?.labelName;
+    if (!resolved) {
+        logger.warn(`entityIdentifier "${params.entityIdentifier}" resolves to no registered model — using it verbatim as the ` +
+            `Neo4j label for this usage record. Correct if it already IS a label; if it is a JSON:API type, the ` +
+            `record's USED_FOR edge will match nothing and the spend will be billed against no entity.`);
+    }
+    return {
+        relationshipId: params.entityId,
+        relationshipType: resolved ?? params.entityIdentifier,
+        ...(params.tokenUsageType ? { tokenUsageType: params.tokenUsageType } : {}),
+    };
+}
+/**
+ * Attribution for an EMBEDDING made by a SUB-AGENT, derived from the caller's
+ * attribution through the SAME precedence chain as
+ * {@link buildInheritedAttribution} (scope root → assistant thread → nothing),
+ * so a turn's LLM spend and its embedding spend always land on one entity.
+ *
+ * `tokenUsageType` is deliberately omitted: the recorder's own default
+ * (`embedding`) classifies the OPERATION, and it is not the sub-agent inventing
+ * an identity — the caller's identity is already expressed by the entity the
+ * record points at.
+ */
+function buildInheritedEmbedderAttribution(state) {
+    const { relationshipId, relationshipType } = buildInheritedAttribution(state);
+    if (!relationshipId || !relationshipType)
+        return undefined;
+    return { relationshipId, relationshipType };
+}
+/**
+ * Attribution for a QUERY-time (retrieval) embedding — the contextualiser
+ * embedding the user's question to search chunks / key concepts.
+ *
+ * A search has no entity of its own, so it is billed to the SCOPE BEING
+ * SEARCHED, in the order the retrieval itself narrows:
+ *  1. the CALLER's scope root, when the contextualiser was invoked by another
+ *     agent that confined the whole turn to one (`scope`). It is the widest
+ *     honest unit of spend and the same entity that agent's own LLM calls bill,
+ *     so a turn is not split across two ledger targets;
+ *  2. the content the run is bound to (`contentId` + `contentType`, a JSON:API
+ *     type resolved to its label) — the retrieval scope the caller passes in;
+ *  3. help mode's single HowTo (`dataLimits.limitToHowToId`), which is the only
+ *     scope a help-mode run has;
+ *  4. nothing — an unbound, non-help run genuinely searches the whole company,
+ *     so there is no honest entity to name and `persistUsage` skips the record
+ *     rather than inventing one.
+ *
+ * `dataLimits.howToMode` on its own carries NO id, so it deliberately does not
+ * produce an attribution: guessing one would write a `USED_FOR` edge that
+ * matches nothing.
+ */
+function buildRetrievalAttribution(params) {
+    const inherited = buildInheritedEmbedderAttribution(params.scope);
+    if (inherited)
+        return inherited;
+    const content = buildEmbedderAttribution({ entityId: params.contentId, entityIdentifier: params.contentType });
+    if (content)
+        return content;
+    // Built directly rather than via `buildEmbedderAttribution`: `howToMeta.labelName`
+    // IS the Neo4j label, so there is nothing to resolve, and routing it through the
+    // registry would emit that helper's unresolved-identifier warning whenever the
+    // HowTo model happens not to be registered — a false alarm.
+    const howToId = params.dataLimits?.limitToHowToId;
+    if (howToId)
+        return { relationshipId: howToId, relationshipType: how_to_meta_1.howToMeta.labelName };
+    return undefined;
+}
+//# sourceMappingURL=usage-attribution.js.map

package/dist/agents/common/usage-attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-attribution.js","sourceRoot":"","sources":["../../../src/agents/common/usage-attribution.ts"],"names":[],"mappings":";;AAqCA,8CAUC;AAiBD,sDAuBC;AAwCD,wDAWC;AA2BD,8DAIC;AAaD,8DAQC;AAiCD,4DAsBC;AAaD,8EAIC;AAwBD,8DAqBC;AAnTD,2CAAwC;AACxC,+DAAiE;AAGjE,wFAAoF;AACpF,+EAA0E;AAC1E,wFAAoF;AAEpF,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,kBAAkB,CAAC,CAAC;AAmB9C;;;;;;;;;GASG;AACH,SAAgB,iBAAiB,CAAC,SAAkB;IAClD,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,SAAS,GAAG,wBAAa,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IACnE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CACT,cAAc,SAAS,4EAA4E;YACjG,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,qBAAqB,CAAC,MAQrC;IACC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,IAAI,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3G,IAAI,MAAM,CAAC,OAAO,IAAI,UAAU,EAAE,CAAC;QACjC,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC;IACjH,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,OAAO;YACL,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,cAAc,EAAE,MAAM,CAAC,WAAW;YAClC,gBAAgB,EAAE,8BAAa,CAAC,SAAS;SAC1C,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC;AACnD,CAAC;AAgCD;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CAAC,MAGtC;IACC,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO;QAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS;QACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU;QACrC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,yBAAyB,CAAC,KAA8B;IACtE,MAAM,cAAc,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,IAAI,KAAK,EAAE,SAAS,IAAI,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,WAAW,CAAC,CAAC;IACzG,IAAI,CAAC,cAAc;QAAE,OAAO,MAAM,CAAC;IACnC,OAAO,yBAAyB,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC;AACvF,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,yBAAyB,CAAC,KAA8B;IACtE,OAAO,qBAAqB,CAAC;QAC3B,cAAc,EAAE,KAAK,EAAE,cAAc,IAAI,gCAAc,CAAC,cAAc;QACtE,OAAO,EAAE,KAAK,EAAE,OAAO;QACvB,SAAS,EAAE,KAAK,EAAE,SAAS;QAC3B,UAAU,EAAE,KAAK,EAAE,UAAU;QAC7B,WAAW,EAAE,KAAK,EAAE,WAAW;KAChC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,wBAAwB,CAAC,MAOxC;IACC,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,gBAAgB;QAAE,OAAO,SAAS,CAAC;IACnE,MAAM,QAAQ,GAAG,wBAAa,CAAC,YAAY,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAChF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,CAAC,IAAI,CACT,qBAAqB,MAAM,CAAC,gBAAgB,+DAA+D;YACzG,qGAAqG;YACrG,2FAA2F,CAC9F,CAAC;IACJ,CAAC;IACD,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,QAAQ;QAC/B,gBAAgB,EAAE,QAAQ,IAAI,MAAM,CAAC,gBAAgB;QACrD,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,iCAAiC,CAAC,KAA8B;IAC9E,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,CAAC,cAAc,IAAI,CAAC,gBAAgB;QAAE,OAAO,SAAS,CAAC;IAC3D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,yBAAyB,CAAC,MAMzC;IACC,MAAM,SAAS,GAAG,iCAAiC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClE,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,MAAM,OAAO,GAAG,wBAAwB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,SAAS,EAAE,gBAAgB,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/G,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,mFAAmF;IACnF,iFAAiF;IACjF,+EAA+E;IAC/E,4DAA4D;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC;IAClD,IAAI,OAAO;QAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,EAAE,uBAAS,CAAC,SAAS,EAAE,CAAC;IAEvF,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/agents/community.summariser/services/community.summariser.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"community.summariser.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/community.summariser/services/community.summariser.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,0DAA0D,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAEvG,eAAO,MAAM,MAAM,ozCA6BlB,CAAC;AAmBF,qBACa,0BAA0B;IAInC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPhC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,UAAU,EAAE,UAAU,EACtB,eAAe,EAAE,eAAe,EAChC,mBAAmB,EAAE,mBAAmB,EACxC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC;IAMpE;;OAEG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D;;OAEG;IACG,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAkE3D"}
+{"version":3,"file":"community.summariser.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/community.summariser/services/community.summariser.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,0DAA0D,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAGvG,eAAO,MAAM,MAAM,ozCA6BlB,CAAC;AAmBF,qBACa,0BAA0B;IAInC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPhC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,UAAU,EAAE,UAAU,EACtB,eAAe,EAAE,eAAe,EAChC,mBAAmB,EAAE,mBAAmB,EACxC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC;IAMpE;;OAEG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D;;OAEG;IACG,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CA4E3D"}

package/dist/agents/community.summariser/services/community.summariser.service.js

@@ -16,7 +16,9 @@ const zod_1 = require("zod");
 const core_1 = require("../../../core");
 const llm_service_1 = require("../../../core/llm/services/llm.service");
 const logging_service_1 = require("../../../core/logging/services/logging.service");
+const community_meta_1 = require("../../../foundations/community/entities/community.meta");
 const community_repository_1 = require("../../../foundations/community/repositories/community.repository");
+const tokenusage_type_1 = require("../../../foundations/tokenusage/enums/tokenusage.type");
 exports.prompt = `
 You are an expert knowledge analyst tasked with summarizing a community of related entities from a knowledge graph.
 
@@ -120,10 +122,20 @@ let CommunitySummariserService = class CommunitySummariserService {
             outputSchema,
             systemPrompts: [this.systemPrompt],
             temperature: 0.3,
+            tokenUsageType: tokenusage_type_1.TokenUsageType.CommunitySummariser,
+            relationshipId: community.id,
+            relationshipType: community_meta_1.communityMeta.labelName,
         });
-        // Generate embedding for the summary
+        // Generate embedding for the summary. Same ledger category as the call above so one
+        // community's summary reads as one cost; billed against the community itself — this
+        // agent is cron-driven with no calling agent to inherit attribution from.
         const embedding = await this.embedderService.vectoriseText({
             text: `${llmResponse.title}\n\n${llmResponse.summary}`,
+            attribution: {
+                relationshipId: community.id,
+                relationshipType: community_meta_1.communityMeta.labelName,
+                tokenUsageType: tokenusage_type_1.TokenUsageType.CommunitySummariser,
+            },
         });
         // Update the community with summary and embedding
         await this.communityRepository.updateSummary({

package/dist/agents/community.summariser/services/community.summariser.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"community.summariser.service.js","sourceRoot":"","sources":["../../../../src/agents/community.summariser/services/community.summariser.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"community.summariser.service.js","sourceRoot":"","sources":["../../../../src/agents/community.summariser/services/community.summariser.service.ts"],"names":[],"mappings":"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"}

package/dist/agents/contextualiser/contexts/contextualiser.context.d.ts

@@ -1,6 +1,17 @@
 import { DataLimits } from "../../../common/types/data.limits";
+import { CallerAttributionState } from "../../common/usage-attribution";
 export declare const ContextualiserContext: import("@langchain/langgraph").AnnotationRoot<{
     companyId: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    /** Ledger category of the CALLING agent, e.g. `TokenUsageType.Responder`. */
+    tokenUsageType: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    /** Id of the caller's scope-root node. Absent = the caller ran unscoped. */
+    scopeId: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    /** JSON:API type of the caller's scope root, e.g. "campaigns". */
+    scopeType: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    /** Neo4j label of the caller's scope root, e.g. "Campaign". */
+    scopeLabel: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    /** Id of the caller's `Assistant` (thread) node — the unscoped fallback. */
+    assistantId: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
     contentId: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
     contentType: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
     hops: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
@@ -271,5 +282,17 @@ export declare const ContextualiserContext: import("@langchain/langgraph").Annot
         };
     }>>, unknown>;
 }>;
-export type ContextualiserContextState = typeof ContextualiserContext.State;
+/**
+ * LangGraph's `StateType` makes EVERY channel a required property, so adding a
+ * channel to the root above would add a required key to this published type and
+ * break any consumer that builds a state literal. The attribution channels are
+ * therefore re-declared through {@link CallerAttributionState}, where they are
+ * optional — the state still carries them, existing literals still compile.
+ *
+ * {@link ContextualiserGraphState} is the un-widened shape LangGraph itself
+ * hands to a node callback; the graph wiring uses it so the callback signatures
+ * still match `StateGraph`'s required-property view.
+ */
+export type ContextualiserGraphState = typeof ContextualiserContext.State;
+export type ContextualiserContextState = Omit<ContextualiserGraphState, keyof CallerAttributionState> & CallerAttributionState;
 //# sourceMappingURL=contextualiser.context.d.ts.map

package/dist/agents/contextualiser/contexts/contextualiser.context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contextualiser.context.d.ts","sourceRoot":"","sources":["../../../../src/agents/contextualiser/contexts/contextualiser.context.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAE/D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0LhC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,OAAO,qBAAqB,CAAC,KAAK,CAAC"}
+{"version":3,"file":"contextualiser.context.d.ts","sourceRoot":"","sources":["../../../../src/agents/contextualiser/contexts/contextualiser.context.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,eAAO,MAAM,qBAAqB;;IAYhC,6EAA6E;;IAK7E,4EAA4E;;IAK5E,kEAAkE;;IAKlE,+DAA+D;;IAK/D,4EAA4E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0L5E,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,qBAAqB,CAAC,KAAK,CAAC;AAE1E,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,wBAAwB,EAAE,MAAM,sBAAsB,CAAC,GACnG,sBAAsB,CAAC"}

package/dist/agents/contextualiser/contexts/contextualiser.context.js

@@ -7,6 +7,38 @@ exports.ContextualiserContext = langgraph_1.Annotation.Root({
         default: () => undefined,
         reducer: (current) => current,
     }),
+    // ---------------------------------------------------------------------------
+    // Cost attribution INHERITED from the calling agent. The contextualiser is a
+    // sub-agent: it never bills on its own behalf, so it carries the caller's
+    // ledger category and the caller's entity and applies them at every LLM call
+    // it makes. All four are absent when a consumer drives the contextualiser
+    // directly without attribution — its spend is then simply not recorded.
+    // ---------------------------------------------------------------------------
+    /** Ledger category of the CALLING agent, e.g. `TokenUsageType.Responder`. */
+    tokenUsageType: (0, langgraph_1.Annotation)({
+        default: () => undefined,
+        reducer: (current, update) => update ?? current,
+    }),
+    /** Id of the caller's scope-root node. Absent = the caller ran unscoped. */
+    scopeId: (0, langgraph_1.Annotation)({
+        default: () => undefined,
+        reducer: (current, update) => update ?? current,
+    }),
+    /** JSON:API type of the caller's scope root, e.g. "campaigns". */
+    scopeType: (0, langgraph_1.Annotation)({
+        default: () => undefined,
+        reducer: (current, update) => update ?? current,
+    }),
+    /** Neo4j label of the caller's scope root, e.g. "Campaign". */
+    scopeLabel: (0, langgraph_1.Annotation)({
+        default: () => undefined,
+        reducer: (current, update) => update ?? current,
+    }),
+    /** Id of the caller's `Assistant` (thread) node — the unscoped fallback. */
+    assistantId: (0, langgraph_1.Annotation)({
+        default: () => undefined,
+        reducer: (current, update) => update ?? current,
+    }),
     contentId: (0, langgraph_1.Annotation)({
         default: () => undefined,
         reducer: (current) => current,