@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/credential-push.js

@@ -1,39 +1,63 @@
-// 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 on sidecar reconnect.
-import { eq, and, inArray } from "drizzle-orm";
+// 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 { agentInstance } from "@intx/db/schema";
-import { resolveInstanceModelSources, getDescendantTenants } from "@intx/db";
+import { workflowRun } from "@intx/db/schema";
+import { resolveInstanceModelSources, getDescendantTenants, reresolveCurrentMaterials, } from "@intx/db";
 const log = getLogger(["hub", "credentials"]);
 /**
  * Re-resolve a single running instance's inference sources from the catalog
- * (the agent's model requirements plus the invoker preferences persisted on
- * the instance) and push the ordered list to its sidecar. The head of the
+ * (the definition's model requirements plus the invoker preferences persisted
+ * on the instance) and push the ordered list to its sidecar. The head of the
  * catalog-priority-ordered list is the active default; the tail is the
  * failover chain.
  *
  * No-op when the instance resolves to no launchable source — the resolver's
  * own logger is the signal for why.
  */
-export async function pushInstanceSourceUpdate(db, sidecarRouter, instance) {
-    const resolution = await resolveInstanceModelSources(db, instance.tenantId, instance);
+export async function pushInstanceSourceUpdate(db, sidecarRouter, instance, credentialCipher) {
+    const resolution = await resolveInstanceModelSources(db, instance.tenantId, instance, credentialCipher);
     if (!resolution.ok)
         return;
     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);
 }
 /**
  * Re-resolve every running instance in the given tenants against the catalog
- * and push the updates to sidecars. Each instance re-resolves from its own
- * tenant's context (its ancestor chain), so the rotated/edited upstream entry
- * flows through. Errors are logged per-instance but do not propagate.
+ * and push the updates to sidecars. The running instances are the folded runs
+ * a launch produces: born running, with a routing address and no deployment.
+ * Deployment-anchor runs (which own a deployment id and a workflow-derived
+ * address) and address-less child runs route via the deployment, not this
+ * per-instance push, so they are excluded. Each instance re-resolves from its
+ * own tenant's context (its ancestor chain), so the rotated/edited upstream
+ * entry flows through. Errors are logged per-instance but do not propagate.
  */
-async function pushSourceUpdatesToTenants(db, sidecarRouter, tenantIds) {
+async function pushSourceUpdatesToTenants(db, sidecarRouter, tenantIds, credentialCipher) {
     if (tenantIds.length === 0)
         return;
     // Callers fire this without awaiting, so it must never reject: a failure to
@@ -41,12 +65,34 @@ async function pushSourceUpdatesToTenants(db, sidecarRouter, tenantIds) {
     // rejection. The push is best effort — the next mutation or a sidecar
     // reconnect re-resolves sources.
     try {
-        const instances = await db.query.agentInstance.findMany({
-            where: and(inArray(agentInstance.tenantId, tenantIds), eq(agentInstance.status, "running")),
+        // The instance-shaped runs: running, addressable, and not anchored on a
+        // deployment. `anchorRunId IS NULL` excludes the deployment-anchor runs
+        // (which set it to their own id), so no deployment-anchor run address can
+        // reach the address-targeted push below. Mirrors the /me/workflows/runs and
+        // tenant run-list predicate.
+        const instances = await db.query.workflowRun.findMany({
+            where: and(inArray(workflowRun.tenantId, tenantIds), eq(workflowRun.status, "running"), isNull(workflowRun.anchorRunId), isNotNull(workflowRun.address)),
         });
         if (instances.length === 0)
             return;
-        const results = await Promise.allSettled(instances.map((instance) => pushInstanceSourceUpdate(db, sidecarRouter, instance)));
+        const results = await Promise.allSettled(instances.map(async (instance) => {
+            // The isNotNull(address) filter guarantees a value; a null here is a
+            // broken invariant. The callback is async, so this throw becomes a
+            // rejected promise captured per-instance by allSettled and logged
+            // below -- one bad row is surfaced, not fatal to the whole batch.
+            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,
+                tenantId: instance.tenantId,
+                modelPreferences: instance.modelPreferences,
+            }, credentialCipher);
+        }));
         for (const result of results) {
             if (result.status === "rejected") {
                 log.warn `Failed to push source update: ${String(result.reason)}`;
@@ -63,8 +109,8 @@ async function pushSourceUpdatesToTenants(db, sidecarRouter, tenantIds) {
  * through because resolution dereferences the provider's credential reference
  * to the current secret.
  */
-export async function pushSourceUpdates(db, sidecarRouter, tenantId) {
-    await pushSourceUpdatesToTenants(db, sidecarRouter, [tenantId]);
+export async function pushSourceUpdates(db, sidecarRouter, tenantId, credentialCipher) {
+    await pushSourceUpdatesToTenants(db, sidecarRouter, [tenantId], credentialCipher);
 }
 /**
  * After a catalog edit in a tenant, re-resolve and push to every running
@@ -72,7 +118,7 @@ export async function pushSourceUpdates(db, sidecarRouter, tenantId) {
  * edited tenant's catalog, so a change there (a disabled provider, a new
  * offering, a price update) alters their resolved sources too.
  */
-export async function pushSourceUpdatesSubtree(db, sidecarRouter, tenantId) {
+export async function pushSourceUpdatesSubtree(db, sidecarRouter, tenantId, credentialCipher) {
     let tenants;
     try {
         tenants = await getDescendantTenants(db, tenantId);
@@ -81,5 +127,115 @@ export async function pushSourceUpdatesSubtree(db, sidecarRouter, tenantId) {
         log.warn `Failed to enumerate descendants for source push: ${String(err)}`;
         return;
     }
-    await pushSourceUpdatesToTenants(db, sidecarRouter, tenants);
+    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,9 +1,9 @@
 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, instanceId: string): void;
+    create(agentAddress: string, tenantId: string, sessionId: string, runId: string): void;
     dispatch(agentAddress: string, event: InferenceEvent): void;
     abandon(agentAddress: string): void;
     has(agentAddress: string): boolean;
@@ -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

@@ -1,8 +1,8 @@
-// Registry of active event collectors, keyed by agent address.
+// Registry of active event collectors, keyed by run address.
 //
 // The hub creates a collector when an instance starts and removes it when the
 // instance ends or the sidecar disconnects. The hub session orchestrator's
-// `agent.event` listener looks up the collector by agent address and
+// `agent.event` listener looks up the collector by run address and
 // dispatches the event.
 import { getLogger } from "@intx/log";
 import { createEventCollector, } from "./event-collector.js";
@@ -30,10 +30,13 @@ 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();
-    function create(agentAddress, tenantId, sessionId, instanceId) {
+    // 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`;
             abandon(agentAddress);
@@ -41,13 +44,18 @@ export function createEventCollectorRegistry(config) {
         const collector = createEventCollector({
             db,
             sessionId,
-            instanceId,
+            runId,
             tenantId,
             ...(onTurnFinalized
                 ? {
                     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>;
@@ -32,8 +41,9 @@ export type EventCollector = {
 export type EventCollectorConfig = {
     db: DB["db"];
     sessionId: string;
-    instanceId: string;
+    runId: string;
     tenantId: string;
     onTurnFinalized?: (turn: TurnFinalized) => void;
+    onUsage?: (usage: TurnUsage) => void;
 };
 export declare function createEventCollector(config: EventCollectorConfig): EventCollector;

package/dist/event-collector.js

@@ -10,7 +10,7 @@ import { parseTurnPartType } from "@intx/db";
 import { generateId } from "@intx/hub-common";
 const log = getLogger(["hub", "event-collector"]);
 export function createEventCollector(config) {
-    const { db, sessionId, instanceId, tenantId, onTurnFinalized } = config;
+    const { db, sessionId, runId, tenantId, onTurnFinalized, onUsage } = config;
     // Current inference turn being accumulated. A new turn is created on each
     // inference.start. Finalized on connector.reply, reactor.done,
     // reactor.error (fatal), or abandon. Null when no turn is active.
@@ -47,6 +47,12 @@ export function createEventCollector(config) {
     let accumulatedToolCalls = [];
     // Tool results that reported isError, accumulated for TurnFinalized.
     let accumulatedToolErrors = [];
+    // Final cumulative token usage for the current turn. `inference.usage` events
+    // carry a running cumulative total and fire multiple times per step, so these
+    // are OVERWRITTEN (not summed); the last value before finalize is the
+    // authoritative per-turn total. Both reset on each new turn.
+    let turnUsage = null;
+    let turnSource = null;
     async function onEvent(event) {
         switch (event.type) {
             case "inference.start":
@@ -59,6 +65,8 @@ export function createEventCollector(config) {
             case "inference.done":
                 await handleInferenceDone(event.data.turn.content);
                 streamingText = "";
+                turnUsage = event.data.usage;
+                turnSource = event.data.source;
                 break;
             case "tool.done": {
                 const callId = event.data.result.callId;
@@ -145,9 +153,15 @@ export function createEventCollector(config) {
                     });
                 }
                 break;
+            case "inference.usage":
+                // Cumulative running total that fires several times per step; overwrite
+                // so the last value before finalize is the authoritative per-turn
+                // usage, emitted once via onUsage from finalizeTurn.
+                turnUsage = event.data.usage;
+                turnSource = event.data.source;
+                break;
             default:
-                // reactor.start, streaming deltas, usage, and other events are
-                // not persisted.
+                // reactor.start, streaming deltas, and other events are not persisted.
                 break;
         }
     }
@@ -170,10 +184,12 @@ export function createEventCollector(config) {
         callArgs.clear();
         accumulatedToolCalls = [];
         accumulatedToolErrors = [];
+        turnUsage = null;
+        turnSource = null;
         await db.insert(inferenceTurn).values({
             id: currentTurnId,
             sessionId,
-            instanceId,
+            runId,
             tenantId,
             model,
             status: "running",
@@ -208,6 +224,14 @@ export function createEventCollector(config) {
                     // declines differently from regular assistant output.
                     await insertPart("refusal", block.reason, null);
                     break;
+                case "safety_rating":
+                    // Structured safety signals (e.g. Gemini
+                    // promptFeedback.blockReason). Persist the reason under a
+                    // dedicated part kind so a blocked turn is not empty in
+                    // the audit trail. Content is the provider-native reason
+                    // string (observed: PROHIBITED_CONTENT).
+                    await insertPart("safety_rating", block.blockReason, null);
+                    break;
                 case "tool_call":
                     callNames.set(block.id, block.name);
                     callArgs.set(block.id, block.arguments);
@@ -310,6 +334,23 @@ export function createEventCollector(config) {
                 toolErrors: [...accumulatedToolErrors],
             });
         }
+        // Report per-turn usage once, alongside the finalize notify. Gated on
+        // turnUsage being present so a turn that ran no inference emits nothing.
+        // NOTE: abandon() finalizes with notify=false, so a turn abandoned
+        // mid-step (e.g. a sidecar disconnect) reports no usage even if the
+        // provider already billed input tokens -- an accepted gap until durable
+        // usage persistence lands on the turn row.
+        if (notify && onUsage && turnUsage !== null && turnSource !== null) {
+            onUsage({
+                tenantId,
+                sessionId,
+                runId,
+                turnId,
+                provider: turnSource.provider,
+                model: turnSource.model,
+                usage: turnUsage,
+            });
+        }
         currentTurnId = null;
     }
     async function abandon() {

package/dist/hub-session-lookups.d.ts

@@ -5,13 +5,131 @@ export type HubSessionLookupsDeps = {
     db: DB["db"];
     agentRepoStore: AgentRepoStore;
 };
-export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<SidecarLookups>;
+export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<Omit<SidecarLookups, "materializeMailTriggeredRunGrants" | "resyncCredentials" | "resolveSenderKey" | "resolveSenderKeyStrict">>;
 /**
- * Extract the instance id from an `<instanceId>@<domain>` agent address.
- * Throws on any input the `@intx/types`-owned `parseAgentAddress`
- * rejects: missing or leading `@`, empty domain, or an instance id
- * without the canonical `ins_` prefix.
+ * Extract the run id from an `<runId>@<domain>` run address.
+ * Throws on any input the `@intx/types`-owned `parseRunAddress`
+ * rejects: missing or leading `@`, empty domain, or a run id
+ * without the canonical `run_` prefix.
  */
 export declare function parseAgentId(agentAddress: string): string;
-export declare function findInstance(db: DB["db"], agentAddress: string): Promise<Awaited<ReturnType<typeof db.query.agentInstance.findFirst>>>;
-export declare function requireInstance(db: DB["db"], agentAddress: string): Promise<NonNullable<Awaited<ReturnType<typeof db.query.agentInstance.findFirst>>>>;
+/**
+ * A live routing endpoint backing a run address. Each address names one
+ * self-anchored `workflow_run`, so the endpoint is always that run.
+ */
+export interface RoutableEndpoint {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly address: string;
+    readonly publicKey: string | null;
+    /**
+     * The endpoint's raw run status. Resolution is `endedAt`-filtered, so a
+     * resolved endpoint is not necessarily live: a leaked run is deliberately
+     * kept routable (terminal status, null `endedAt`) to stay reachable, and the
+     * reconnect reaction reads this to keep such an endpoint routable without
+     * restoring a collector.
+     */
+    readonly status: string;
+    /**
+     * The live session backing this endpoint. A folded run has no session column,
+     * so this is the run's not-yet-ended `agent_session`, keyed by the run's
+     * principal. Transitional -- it retires when mail record-keeping moves off
+     * `agent_session`.
+     */
+    readonly sessionId: string | null;
+}
+/**
+ * Resolve a run address to the `workflow_run` endpoint backing it, keyed by
+ * the run's `address`. Every routable address names one self-anchored run --
+ * the deployment's anchor -- so this resolves the run's own address (the
+ * source `persistMail` depends on to record a triggered deployment's mail).
+ */
+export declare function resolveRoutableAddress(db: DB["db"], address: string): Promise<RoutableEndpoint | undefined>;
+/**
+ * A folded run has no session column; its session is the `agent_session` keyed
+ * by the run's principal. By default this is the live (not-yet-ended) session,
+ * matching routing semantics; `includeEnded` also resolves a stopped run's
+ * ended session, which mail history needs. Returns null when the run has no
+ * principal or no matching session. Transitional, alongside
+ * `RoutableEndpoint.sessionId`.
+ */
+export declare function resolveRunSessionId(db: DB["db"], principalId: string | null, opts?: {
+    includeEnded?: boolean;
+}): Promise<string | null>;
+/**
+ * The folded run that owns a session, or null when the session belongs to no
+ * run. This is the inverse of `resolveRunSessionId`: a mail-read path holds a
+ * `sessionMail.sessionId` and no address, so it recovers the owning run by
+ * joining `workflow_run` to `agent_session` on their shared principal (a folded
+ * run, its session, and its launch all key on the same `instancePrincipalId`).
+ * Scoped to the tenant and routed through `workflow_run` so the returned id is
+ * proven to name a real run of this tenant -- callers key an authorization
+ * subject on it, so a session held by a non-run principal must fail closed to
+ * null rather than resolve to a fabricated subject.
+ */
+export declare function resolveRunIdForSession(db: DB["db"], sessionId: string, tenantId: string): Promise<string | null>;
+/**
+ * A folded run resolved BY ID for the instance read/interact surface, shaped
+ * into one instance-shaped record. Unlike `resolveRoutableAddress` (keyed by
+ * address, live-only), this is keyed by the path id and does NOT filter
+ * terminated rows -- a stopped run's detail, mail history, and turns are still
+ * served. Keep the two separate: routing must never reach a dead endpoint,
+ * while the read surface must still render one.
+ */
+export interface RoutableRecord {
+    readonly id: string;
+    readonly tenantId: string;
+    /** The routing address. Non-null: a run resolves here only when it owns an
+     * address. */
+    readonly address: string;
+    readonly publicKey: string | null;
+    /** Raw run status. The wire mapping onto the instance status enum is a
+     * hub-api concern, done by the response shaper. */
+    readonly status: string;
+    readonly createdAt: Date;
+    /** A run has no `updatedAt` column, so it reports `endedAt ?? createdAt`. */
+    readonly updatedAt: Date;
+    readonly endedAt: Date | null;
+    /** The folded definition this run belongs to (`workflow_definition.id`). */
+    readonly definitionId: string;
+    readonly principalId: string | null;
+    readonly kernelId: string | null;
+    readonly sidecarId: string | null;
+}
+/**
+ * Shape a run row and its already-resolved routing address into the run
+ * record. Callers decide whether the run resolves at all -- only a top-level
+ * run (`isTopLevelRun`) does -- and pass the address they have narrowed; this
+ * only maps the columns, including the run's `endedAt ?? createdAt` stand-in
+ * for the absent `updatedAt`.
+ */
+export declare function runRowToRoutableRecord(run: {
+    id: string;
+    tenantId: string;
+    publicKey: string | null;
+    status: string;
+    createdAt: Date;
+    endedAt: Date | null;
+    definitionId: string;
+    principalId: string | null;
+    kernelId: string | null;
+    sidecarId: string | null;
+}, address: string): RoutableRecord;
+/**
+ * A run is a top-level run -- the addressable head of a deployment -- when it
+ * owns a routing address AND self-anchors (`anchorRunId === id`). A lazy child
+ * park row anchors on its parent (`anchorRunId !== id`) and carries no address;
+ * either condition excludes it. This is the single predicate the run read
+ * surface classifies on, so the resolver and the run list cannot drift.
+ */
+export declare function isTopLevelRun(row: {
+    id: string;
+    address: string | null;
+    anchorRunId: string | null;
+}): boolean;
+/**
+ * Resolve a run id to its record. A run resolves only when it is a top-level
+ * run (`isTopLevelRun`): it owns a routing address and self-anchors. A child
+ * park row (address-null, anchored on its parent) is not served here.
+ */
+export declare function findRoutableById(db: DB["db"], id: string, tenantId: string): Promise<RoutableRecord | undefined>;