@intx/hub-sessions 0.3.0 → 0.4.0

package/dist/agent-repo.d.ts

@@ -66,8 +66,6 @@ export type AgentRepoStore = {
      * DB state without re-deriving terminal-ness.
      */
     receiveWorkflowRunPack(repoId: RepoId, pack: Uint8Array, ref: string, commitSha: string): Promise<NewlyTerminalRun[]>;
-    /** Resolve the current deploy ref SHA, or null if no deploy exists. */
-    getDeployRef(agentId: string): Promise<string | null>;
     /** Raw 32-byte Ed25519 public key used to sign deploy commits. */
     getSigningPublicKey(): Uint8Array;
     /**
@@ -78,6 +76,20 @@ export type AgentRepoStore = {
      */
     readonly repoStore: RepoStore;
 };
+/**
+ * Repo kinds eligible for write-path object GC. Deliberately EXCLUDES
+ * "workflow-run". The warm-agent mailbox physically expunges `<uid>.eml`
+ * blobs from the live tree; the raw bytes then persist only through the
+ * parent commit in git history, and they survive a push ONLY because a
+ * `workflow-run` repo's objects are never GC'd. Adding "workflow-run"
+ * here -- above all with a retention other than "keep-history" -- would
+ * make an expunged message's bytes prunable and silently destroy the
+ * mailbox audit trail. The mailbox subtree contract in `workflow-run-kind`
+ * documents this dependency; `agent-repo.test.ts` pins it. Do not add
+ * "workflow-run" without replacing physical expunge with a tip-reachable
+ * retain-bytes scheme first.
+ */
+export declare const DEFAULT_GC_KINDS: readonly ["agent-state"];
 export declare function createAgentRepoStore(config: {
     dataDir: string;
     signingKey: {

package/dist/agent-repo.js

@@ -5,6 +5,20 @@ import { skillKindHandler, skillAuthorize } from "./skill-kind.js";
 import { packageRegistryKindHandler, packageRegistryAuthorize, } from "./package-registry-kind.js";
 import { workflowKindHandler, workflowAuthorize } from "./workflow-kind.js";
 import { workflowRunKindHandler, workflowRunAuthorize, } from "./workflow-run-kind.js";
+/**
+ * Repo kinds eligible for write-path object GC. Deliberately EXCLUDES
+ * "workflow-run". The warm-agent mailbox physically expunges `<uid>.eml`
+ * blobs from the live tree; the raw bytes then persist only through the
+ * parent commit in git history, and they survive a push ONLY because a
+ * `workflow-run` repo's objects are never GC'd. Adding "workflow-run"
+ * here -- above all with a retention other than "keep-history" -- would
+ * make an expunged message's bytes prunable and silently destroy the
+ * mailbox audit trail. The mailbox subtree contract in `workflow-run-kind`
+ * documents this dependency; `agent-repo.test.ts` pins it. Do not add
+ * "workflow-run" without replacing physical expunge with a tip-reachable
+ * retain-bytes scheme first.
+ */
+export const DEFAULT_GC_KINDS = ["agent-state"];
 export function createAgentRepoStore(config) {
     const { dataDir, signingKey, gc } = config;
     const authorize = (principal, incomingRepoId, ref, action) => {
@@ -47,7 +61,9 @@ export function createAgentRepoStore(config) {
         },
         authorize,
         signingCallback: () => signer,
-        ...(gc === undefined ? {} : { gc: { kinds: ["agent-state"], ...gc } }),
+        ...(gc === undefined
+            ? {}
+            : { gc: { kinds: [...DEFAULT_GC_KINDS], ...gc } }),
     });
     const hub = { kind: "hub" };
     function repoId(agentId) {
@@ -98,9 +114,6 @@ export function createAgentRepoStore(config) {
             const expectedOldSha = await store.resolveRef(hub, incomingRepoId, ref);
             return store.receivePack(principal, incomingRepoId, ref, pack, commitSha, expectedOldSha);
         },
-        async getDeployRef(agentId) {
-            return store.resolveRef(hub, repoId(agentId), AGENT_STATE_DEPLOY_REF);
-        },
         getSigningPublicKey() {
             return signingKey.publicKey;
         },

package/dist/agent-state-kind.js

@@ -1,6 +1,5 @@
 import { type } from "arktype";
-import { glob, repoActionToGrantVerb } from "@intx/hub-common";
-import { UserPrincipal, } from "./repo-store/index.js";
+import { authorizeUserPrincipal, } from "./repo-store/index.js";
 const SidecarPrincipal = type({
     kind: "'sidecar'",
     agentId: "string",
@@ -62,10 +61,9 @@ export const agentStateKindHandler = {
 };
 export const agentStateAuthorize = (principal, repoId, ref, action) => {
     if (principal.kind === "hub") {
-        // Full access at this kind. Hub-side reads (getDeployRef,
-        // createDeployPack) and writes (writeDeployTree) all flow through
-        // here, so changing this branch tightens behavior in non-obvious
-        // places.
+        // Full access at this kind. Hub-side reads (createDeployPack) and writes
+        // (writeDeployTree) all flow through here, so changing this branch tightens
+        // behavior in non-obvious places.
         return { allowed: true };
     }
     if (principal.kind === "sidecar") {
@@ -114,69 +112,22 @@ export const agentStateAuthorize = (principal, repoId, ref, action) => {
         }
     }
     if (principal.kind === "user") {
-        // The route layer has already pre-resolved the grant verdict and
-        // attached it as `authz`. The substrate does NOT re-query the
-        // grant store here; it (a) checks the bearer-token's claims
-        // bound the requested (ref, action) and have not expired, and
-        // (b) sanity-checks that the pre-resolved verdict targets this
-        // exact resource and grant verb. Both gates must pass before the
-        // verdict's `effect` is honoured.
-        const parsed = UserPrincipal(principal);
-        if (parsed instanceof type.errors) {
-            return {
-                allowed: false,
-                reason: `user principal is malformed: ${parsed.summary}`,
-            };
-        }
+        // `agentStateAuthorize` has no top-level repoId.kind gate (the
+        // other kind handlers reject a mismatched kind up front), so the
+        // kind check lives here inside the user branch.
         if (repoId.kind !== "agent-state") {
             return {
                 allowed: false,
                 reason: `user authorize received non-agent-state repo ${repoId.kind}/${repoId.id}`,
             };
         }
-        if (!parsed.tokenClaims.actions.includes(action)) {
-            return {
-                allowed: false,
-                reason: `token does not grant action ${action}`,
-            };
-        }
-        // `ref === "*"` is the substrate's sentinel for the bulk read
-        // performed by `listRefs`. Per-ref filtering is the advertise-refs
-        // layer's responsibility, so the bulk read is gated on action and
-        // expiry alone.
-        if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
-            return {
-                allowed: false,
-                reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
-            };
-        }
-        if (Date.now() >= parsed.tokenClaims.expiresAt) {
-            return {
-                allowed: false,
-                reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
-            };
-        }
-        const expectedResource = `agent-state:${repoId.id}`;
-        if (parsed.authz.resource !== expectedResource) {
-            return {
-                allowed: false,
-                reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
-            };
-        }
-        const expectedGrantVerb = repoActionToGrantVerb(action);
-        if (parsed.authz.grantVerb !== expectedGrantVerb) {
-            return {
-                allowed: false,
-                reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
-            };
-        }
-        if (parsed.authz.effect === "allow") {
-            return { allowed: true };
-        }
-        return {
-            allowed: false,
-            reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
-        };
+        return authorizeUserPrincipal({
+            principal,
+            repoId,
+            ref,
+            action,
+            resourcePrefix: "agent-state",
+        });
     }
     // Fail closed on any kind not handled above. The tenant-level
     // `workflow` principal kind (`@intx/types` principalKinds) is a

package/dist/asset-service.js

@@ -26,16 +26,20 @@ const logger = getLogger(["hub-sessions", "asset-service"]);
  * push to this ref so it carries the published-asset HEAD.
  */
 export const DEFAULT_ASSET_REF = "refs/heads/main";
-// Asset names become the default workspace mountpath segment at
-// session start (`skills/<asset.name>/`). The mountpath segment
-// validator in applyAssetPack rejects anything outside a safe
-// character set; validate at the createAsset boundary so a bad name
-// fails at creation time rather than at materialization time. Names
-// must be lowercase-kebab: lowercase letters, digits, hyphens, with
-// no leading or trailing hyphen. Exported so a caller deriving a name
-// (the agent-fold materializer) asserts the shape at its own boundary
-// rather than discovering a violation three layers in as a generic
-// `invalid_name`.
+// An asset name becomes a workspace mountpath segment for the asset
+// kinds a session actually mounts: a tool-package registry mounts at
+// `package-registries/<asset.name>/`. A skill is an asset kind too,
+// and its `SKILL.md` frontmatter is validated on push and indexed
+// under the pushed ref, but nothing consumes that index and no
+// session path mounts a skill asset into an agent workspace. A skill
+// asset is therefore recorded and validated, not materialized and not
+// executed. The mountpath segment validator in applyAssetPack
+// rejects anything outside a safe character set; validate at the
+// createAsset boundary so a bad name fails at creation time rather
+// than at materialization time. Names must be lowercase-kebab:
+// lowercase letters, digits, hyphens, with no leading or trailing
+// hyphen. The sole enforcement site is the createAsset check below,
+// which rejects a bad name as `invalid_name`.
 export const ASSET_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export class AssetServiceError extends Error {
     reason;

package/dist/credential-push.d.ts

@@ -11,23 +11,67 @@ import type { SidecarRouter } from "./ws/sidecar-handler.js";
  * No-op when the instance resolves to no launchable source — the resolver's
  * own logger is the signal for why.
  */
-export declare function pushInstanceSourceUpdate(db: DB["db"], sidecarRouter: Pick<SidecarRouter, "sendSourcesUpdate">, instance: {
+export declare function pushInstanceSourceUpdate(db: DB["db"], sidecarRouter: Pick<SidecarRouter, "sendSourcesUpdate" | "sendCredentialsUpdate">, instance: {
     address: string;
     definitionId: string;
     tenantId: string;
     modelPreferences: unknown;
-}, credentialCipher?: CredentialCipher): Promise<void>;
+}, credentialCipher: CredentialCipher): Promise<void>;
 /**
  * After a credential secret is rotated, re-resolve every running instance in
  * the tenant against the catalog and push the updates. A rotated secret flows
  * through because resolution dereferences the provider's credential reference
  * to the current secret.
  */
-export declare function pushSourceUpdates(db: DB["db"], sidecarRouter: SidecarRouter, tenantId: string, credentialCipher?: CredentialCipher): Promise<void>;
+export declare function pushSourceUpdates(db: DB["db"], sidecarRouter: SidecarRouter, tenantId: string, credentialCipher: CredentialCipher): Promise<void>;
 /**
  * After a catalog edit in a tenant, re-resolve and push to every running
  * instance in that tenant AND its descendants. Descendants inherit the
  * edited tenant's catalog, so a change there (a disabled provider, a new
  * offering, a price update) alters their resolved sources too.
  */
-export declare function pushSourceUpdatesSubtree(db: DB["db"], sidecarRouter: SidecarRouter, tenantId: string, credentialCipher?: CredentialCipher): Promise<void>;
+export declare function pushSourceUpdatesSubtree(db: DB["db"], sidecarRouter: SidecarRouter, tenantId: string, credentialCipher: CredentialCipher): Promise<void>;
+/**
+ * After a credential is deleted or deliberately revoked, evict it from every
+ * running deployment in the tenant AND its descendants. A descendant resolves
+ * an ancestor's tenant-owned credential through the tenant walk-up, so a
+ * revoke in one tenant can affect a descendant's run. The push is a flat named
+ * revocation: the child drops the credentialId's material and any binding that
+ * references it, and a run that never held it no-ops. Because a flat revoke is
+ * safe to broadcast, this needs no per-instance ledger of what was delivered.
+ *
+ * Callers fire this without awaiting, so it must never reject: a failure to
+ * enumerate or push is logged and dropped. This closes the ONLINE revocation
+ * window (a running deployment stops holding the credential now); the offline
+ * window -- a run whose sidecar was disconnected when the revoke fired -- is
+ * closed by the reconnect resync, not here.
+ */
+export declare function pushCredentialRevoke(db: DB["db"], sidecarRouter: Pick<SidecarRouter, "sendCredentialsUpdate">, tenantId: string, credentialId: string): Promise<void>;
+/**
+ * Reconcile a reconnecting deployment's credentials against its deploy-time set.
+ * Re-resolve the CURRENT material for every credentialId the deployment
+ * persisted at deploy (`workflow_run.credentialRefs`), then push a MERGE that
+ * upserts the survivors (picking up a same-id secret rotation) and REVOKES the
+ * deploy-time ids that no longer resolve (deleted or revoked while the sidecar
+ * was disconnected). Closes the OFFLINE revocation window (the online window is
+ * closed by `pushCredentialRevoke`).
+ *
+ * Merge, not wholesale-replace: `credentialRefs` is only the deploy-time id set,
+ * not the child's complete live set (a catalog re-point can deliver a new
+ * credential online), so a replace would evict online-added credentials. The
+ * merge upserts survivors and names the dead ids in `revoke`, leaving online
+ * credentials untouched. It does NOT handle an id-CHANGING rotation of a
+ * deploy-time source (the new id is not in `credentialRefs`); a later source
+ * push delivers that.
+ *
+ * No-op when the run persisted no credential refs (a folded run, or a
+ * deployment with no credentials). Fire-and-forget from the reconnect handler:
+ * it never rejects. A live-but-unresolvable credential (its provider vanished
+ * or has no API base URL) makes `reresolveCurrentMaterials` throw, which aborts
+ * the WHOLE reconcile (logged, not sent) so a partial set with a spurious
+ * revoke never lands. This is deliberately all-or-nothing: one misconfigured
+ * credential blocks this reconnect's revocation of the others too, trading
+ * revocation timeliness for never falsely evicting a live credential. The next
+ * reconnect (or an online revoke) retries.
+ */
+export declare function pushCredentialReconcile(db: DB["db"], sidecarRouter: Pick<SidecarRouter, "sendCredentialsUpdate">, agentAddress: string, credentialCipher: CredentialCipher): Promise<void>;

package/dist/credential-push.js

@@ -1,13 +1,20 @@
-// Shared logic for re-resolving a running instance's inference sources from
-// the catalog and pushing the update to its sidecar.
+// Hub-side producers that push credential-material changes to running
+// deployments over `credentials.update`.
 //
-// Used after a credential secret rotation (a model provider's credential
-// changes the resolved source's apiKey) and after a catalog edit in a tenant
-// or its subtree.
+// Two shapes, one per removal semantic:
+//   - Source re-resolve (`pushSourceUpdates`, `pushSourceUpdatesSubtree`): after
+//     a credential secret rotation or a catalog edit, re-resolve each running
+//     instance's inference sources and push the refreshed material followed by
+//     the `sources.update` that references it. An inference source references
+//     its credential by id only, so the rotated secret rides the cell.
+//   - Flat named revoke (`pushCredentialRevoke`): after a credential is deleted
+//     or deliberately revoked, broadcast a `revoke` naming that credentialId so
+//     every running deployment drops it. The removed id is NAMED by the actor,
+//     so this needs no diff against a prior delivery.
 import { eq, and, inArray, isNull, isNotNull } from "drizzle-orm";
 import { getLogger } from "@intx/log";
 import { workflowRun } from "@intx/db/schema";
-import { resolveInstanceModelSources, getDescendantTenants } from "@intx/db";
+import { resolveInstanceModelSources, getDescendantTenants, reresolveCurrentMaterials, } from "@intx/db";
 const log = getLogger(["hub", "credentials"]);
 /**
  * Re-resolve a single running instance's inference sources from the catalog
@@ -26,6 +33,18 @@ export async function pushInstanceSourceUpdate(db, sidecarRouter, instance, cred
     const [head] = resolution.sources;
     if (head === undefined)
         return;
+    // Push the credential material before the source list. A source references
+    // its credential by id, so the cell must hold the (possibly rotated) secret
+    // before the source list that points at it lands. Inference sources carry no
+    // binding descriptor. A failure here propagates and aborts the source push --
+    // never a stale secret paired with a fresh source list.
+    if (resolution.materials.length > 0) {
+        const delivery = {
+            bindings: [],
+            materials: resolution.materials,
+        };
+        await sidecarRouter.sendCredentialsUpdate(instance.address, delivery);
+    }
     await sidecarRouter.sendSourcesUpdate(instance.address, resolution.sources, head.id);
 }
 /**
@@ -64,6 +83,9 @@ async function pushSourceUpdatesToTenants(db, sidecarRouter, tenantIds, credenti
             if (instance.address === null) {
                 throw new Error(`running run ${instance.id} matched the non-null-address filter but has a null address`);
             }
+            if (instance.definitionId === null) {
+                throw new Error(`running run ${instance.id} has no workflow definition`);
+            }
             return pushInstanceSourceUpdate(db, sidecarRouter, {
                 address: instance.address,
                 definitionId: instance.definitionId,
@@ -107,3 +129,113 @@ export async function pushSourceUpdatesSubtree(db, sidecarRouter, tenantId, cred
     }
     await pushSourceUpdatesToTenants(db, sidecarRouter, tenants, credentialCipher);
 }
+/**
+ * After a credential is deleted or deliberately revoked, evict it from every
+ * running deployment in the tenant AND its descendants. A descendant resolves
+ * an ancestor's tenant-owned credential through the tenant walk-up, so a
+ * revoke in one tenant can affect a descendant's run. The push is a flat named
+ * revocation: the child drops the credentialId's material and any binding that
+ * references it, and a run that never held it no-ops. Because a flat revoke is
+ * safe to broadcast, this needs no per-instance ledger of what was delivered.
+ *
+ * Callers fire this without awaiting, so it must never reject: a failure to
+ * enumerate or push is logged and dropped. This closes the ONLINE revocation
+ * window (a running deployment stops holding the credential now); the offline
+ * window -- a run whose sidecar was disconnected when the revoke fired -- is
+ * closed by the reconnect resync, not here.
+ */
+export async function pushCredentialRevoke(db, sidecarRouter, tenantId, credentialId) {
+    let tenants;
+    try {
+        tenants = await getDescendantTenants(db, tenantId);
+    }
+    catch (err) {
+        log.warn `Failed to enumerate descendants for credential revoke: ${String(err)}`;
+        return;
+    }
+    try {
+        // Every running, addressable run in the subtree. Unlike the source-update
+        // push this does NOT exclude deployment-anchor runs (`anchorRunId IS NULL`):
+        // a deployed workflow is the primary credential consumer, and a flat revoke
+        // is safe to deliver to any address -- a run that never held the credential
+        // no-ops on it.
+        const runs = await db.query.workflowRun.findMany({
+            where: and(inArray(workflowRun.tenantId, tenants), eq(workflowRun.status, "running"), isNotNull(workflowRun.address)),
+            columns: { id: true, address: true },
+        });
+        const addresses = new Set();
+        for (const run of runs) {
+            // The isNotNull(address) filter guarantees a value; a null here is a
+            // broken invariant, surfaced rather than silently skipped.
+            if (run.address === null) {
+                throw new Error(`running run ${run.id} matched the non-null-address filter but has a null address`);
+            }
+            addresses.add(run.address);
+        }
+        if (addresses.size === 0)
+            return;
+        const emptyDelivery = { bindings: [], materials: [] };
+        const results = await Promise.allSettled([...addresses].map((address) => sidecarRouter.sendCredentialsUpdate(address, emptyDelivery, [
+            credentialId,
+        ])));
+        for (const result of results) {
+            if (result.status === "rejected") {
+                log.warn `Failed to push credential revoke: ${String(result.reason)}`;
+            }
+        }
+    }
+    catch (err) {
+        log.warn `Failed to push credential revoke: ${String(err)}`;
+    }
+}
+/**
+ * Reconcile a reconnecting deployment's credentials against its deploy-time set.
+ * Re-resolve the CURRENT material for every credentialId the deployment
+ * persisted at deploy (`workflow_run.credentialRefs`), then push a MERGE that
+ * upserts the survivors (picking up a same-id secret rotation) and REVOKES the
+ * deploy-time ids that no longer resolve (deleted or revoked while the sidecar
+ * was disconnected). Closes the OFFLINE revocation window (the online window is
+ * closed by `pushCredentialRevoke`).
+ *
+ * Merge, not wholesale-replace: `credentialRefs` is only the deploy-time id set,
+ * not the child's complete live set (a catalog re-point can deliver a new
+ * credential online), so a replace would evict online-added credentials. The
+ * merge upserts survivors and names the dead ids in `revoke`, leaving online
+ * credentials untouched. It does NOT handle an id-CHANGING rotation of a
+ * deploy-time source (the new id is not in `credentialRefs`); a later source
+ * push delivers that.
+ *
+ * No-op when the run persisted no credential refs (a folded run, or a
+ * deployment with no credentials). Fire-and-forget from the reconnect handler:
+ * it never rejects. A live-but-unresolvable credential (its provider vanished
+ * or has no API base URL) makes `reresolveCurrentMaterials` throw, which aborts
+ * the WHOLE reconcile (logged, not sent) so a partial set with a spurious
+ * revoke never lands. This is deliberately all-or-nothing: one misconfigured
+ * credential blocks this reconnect's revocation of the others too, trading
+ * revocation timeliness for never falsely evicting a live credential. The next
+ * reconnect (or an online revoke) retries.
+ */
+export async function pushCredentialReconcile(db, sidecarRouter, agentAddress, credentialCipher) {
+    try {
+        const run = await db.query.workflowRun.findFirst({
+            where: eq(workflowRun.address, agentAddress),
+            columns: { credentialRefs: true },
+        });
+        if (run === undefined)
+            return;
+        const refs = run.credentialRefs;
+        if (refs === null)
+            return;
+        const materials = await reresolveCurrentMaterials(db, refs.credentialIds, credentialCipher);
+        const resolvedIds = new Set(materials.map((material) => material.credentialId));
+        // Deploy-time ids that no longer resolve: deleted or revoked while offline.
+        const revoke = refs.credentialIds.filter((id) => !resolvedIds.has(id));
+        // A binding whose credential dropped out of the re-resolution goes with it.
+        const bindings = refs.bindings.filter((binding) => resolvedIds.has(binding.credentialId));
+        const delivery = { bindings, materials };
+        await sidecarRouter.sendCredentialsUpdate(agentAddress, delivery, revoke.length > 0 ? revoke : undefined);
+    }
+    catch (err) {
+        log.warn `Failed to reconcile credentials for ${agentAddress}: ${String(err)}`;
+    }
+}

package/dist/event-collector-registry.d.ts

@@ -1,7 +1,7 @@
 import type { DB } from "@intx/db";
 import type { InferenceEvent } from "@intx/types/runtime";
 import type { SessionStatus } from "@intx/types";
-import { type TurnFinalized } from "./event-collector.js";
+import { type TurnFinalized, type TurnUsage } from "./event-collector.js";
 export type EventCollectorRegistry = {
     create(agentAddress: string, tenantId: string, sessionId: string, runId: string): void;
     dispatch(agentAddress: string, event: InferenceEvent): void;
@@ -15,6 +15,7 @@ export type EventCollectorRegistry = {
 export type EventCollectorRegistryConfig = {
     db: DB["db"];
     onTurnFinalized?: (agentAddress: string, turn: TurnFinalized) => void;
+    onUsage?: (agentAddress: string, usage: TurnUsage) => void;
 };
 export declare function deriveStatus(event: InferenceEvent): SessionStatus | null;
 export declare function createEventCollectorRegistry(config: EventCollectorRegistryConfig): EventCollectorRegistry;

package/dist/event-collector-registry.js

@@ -30,9 +30,12 @@ export function deriveStatus(event) {
     }
 }
 export function createEventCollectorRegistry(config) {
-    const { db, onTurnFinalized } = config;
+    const { db, onTurnFinalized, onUsage } = config;
     const collectors = new Map();
     const statuses = new Map();
+    // Per-address tail promise: serializes onEvent/abandon work for one run
+    // address so their DB writes cannot interleave. Reaped when it drains.
+    const tails = new Map();
     function create(agentAddress, tenantId, sessionId, runId) {
         if (collectors.has(agentAddress)) {
             log.warn `Collector already exists for ${agentAddress}, replacing`;
@@ -48,6 +51,11 @@ export function createEventCollectorRegistry(config) {
                     onTurnFinalized: (turn) => onTurnFinalized(agentAddress, turn),
                 }
                 : {}),
+            ...(onUsage
+                ? {
+                    onUsage: (usage) => onUsage(agentAddress, usage),
+                }
+                : {}),
         });
         collectors.set(agentAddress, collector);
         statuses.set(agentAddress, { status: "idle" });
@@ -56,6 +64,25 @@ export function createEventCollectorRegistry(config) {
         collectors.delete(agentAddress);
         statuses.delete(agentAddress);
     }
+    // Chain `work` onto the address's tail so per-address work runs in order and
+    // never interleaves, while the caller stays non-blocking. `onError` swallows
+    // a failure so one bad event cannot wedge the chain; `onSettled` runs after
+    // the work settles. The tail entry is reaped once no later work is queued.
+    function enqueue(agentAddress, work, onError, onSettled) {
+        const prev = tails.get(agentAddress) ?? Promise.resolve();
+        const next = prev
+            .then(work)
+            .catch(onError)
+            .finally(() => {
+            if (onSettled !== undefined) {
+                onSettled();
+            }
+            if (tails.get(agentAddress) === next) {
+                tails.delete(agentAddress);
+            }
+        });
+        tails.set(agentAddress, next);
+    }
     function dispatch(agentAddress, event) {
         const collector = collectors.get(agentAddress);
         if (collector === undefined) {
@@ -67,13 +94,10 @@ export function createEventCollectorRegistry(config) {
         }
         const isTerminal = event.type === "reactor.done" ||
             (event.type === "reactor.error" && event.data.fatal);
-        collector
-            .onEvent(event)
-            .catch((err) => {
+        enqueue(agentAddress, () => collector.onEvent(event), (err) => {
             log.warn `Failed to persist event ${event.type} seq=${String(event.seq)} for ${agentAddress}: ${err instanceof Error ? err.message : String(err)}`;
-        })
-            .finally(() => {
-            if (isTerminal) {
+        }, () => {
+            if (isTerminal && collectors.get(agentAddress) === collector) {
                 removeCollector(agentAddress);
             }
         });
@@ -82,10 +106,15 @@ export function createEventCollectorRegistry(config) {
         const collector = collectors.get(agentAddress);
         if (collector === undefined)
             return;
-        collector.abandon().catch((err) => {
+        // Stop NEW dispatches immediately; the queued closures keep their own
+        // reference so already-queued events still drain before the abandon runs.
+        removeCollector(agentAddress);
+        // Chain the abandon onto the tail so it runs AFTER any queued onEvents
+        // instead of racing them. Otherwise a queued beginTurn could create a
+        // fresh `running` turn row after the collector was finalized, orphaning it.
+        enqueue(agentAddress, () => collector.abandon(), (err) => {
             log.warn `Failed to abandon collector for ${agentAddress}: ${err instanceof Error ? err.message : String(err)}`;
         });
-        removeCollector(agentAddress);
     }
     function has(agentAddress) {
         return collectors.has(agentAddress);

package/dist/event-collector.d.ts

@@ -1,4 +1,4 @@
-import type { InferenceEvent } from "@intx/types/runtime";
+import type { InferenceEvent, TokenUsage } from "@intx/types/runtime";
 import { type DB } from "@intx/db";
 export type TurnToolCall = {
     name: string;
@@ -22,6 +22,15 @@ export type TurnFinalized = {
         content: string;
     }[];
 };
+export type TurnUsage = {
+    tenantId: string;
+    sessionId: string;
+    runId: string;
+    turnId: string;
+    provider: string;
+    model: string;
+    usage: TokenUsage;
+};
 export type EventCollector = {
     onEvent(event: InferenceEvent): Promise<void>;
     abandon(): Promise<void>;
@@ -35,5 +44,6 @@ export type EventCollectorConfig = {
     runId: string;
     tenantId: string;
     onTurnFinalized?: (turn: TurnFinalized) => void;
+    onUsage?: (usage: TurnUsage) => void;
 };
 export declare function createEventCollector(config: EventCollectorConfig): EventCollector;