@intx/hub-sessions 0.3.0 → 0.4.0

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, runId, 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,6 +184,8 @@ export function createEventCollector(config) {
         callArgs.clear();
         accumulatedToolCalls = [];
         accumulatedToolErrors = [];
+        turnUsage = null;
+        turnSource = null;
         await db.insert(inferenceTurn).values({
             id: currentTurnId,
             sessionId,
@@ -318,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,7 +5,7 @@ export type HubSessionLookupsDeps = {
     db: DB["db"];
     agentRepoStore: AgentRepoStore;
 };
-export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<Omit<SidecarLookups, "materializeMailTriggeredRunGrants">>;
+export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<Omit<SidecarLookups, "materializeMailTriggeredRunGrants" | "resyncCredentials" | "resolveSenderKey" | "resolveSenderKeyStrict">>;
 /**
  * Extract the run id from an `<runId>@<domain>` run address.
  * Throws on any input the `@intx/types`-owned `parseRunAddress`

package/dist/hub-session-lookups.js

@@ -5,7 +5,7 @@
 // Each lookup is a stateless DB or repo call. They are gathered into a
 // single struct that the hub app passes to `createSidecarRouter` as
 // `lookups`.
-import { eq, and, asc, inArray, isNull } from "drizzle-orm";
+import { eq, and, asc, inArray, isNotNull, isNull } from "drizzle-orm";
 import { createApprovalStore, createSignalCorrelationStore, createWorkflowRunDispatchStore, createWorkflowRunStore, } from "@intx/db";
 import { agentSession, liveWorkflowRunStatuses, principal, sessionMail, sidecarAllocation, workflowRun, } from "@intx/db/schema";
 import { getLogger } from "@intx/log";
@@ -23,25 +23,6 @@ export function createHubSessionLookups(deps) {
     const workflowRunStore = createWorkflowRunStore(db);
     const workflowRunDispatchStore = createWorkflowRunDispatchStore(db);
     return {
-        async lookupPublicKey(agentAddress) {
-            // Every routable address names one workflow run, whose key lives on its
-            // single self-anchored workflow_run row, keyed by address. Read the key
-            // off that row, gated on a live run (born "deployed", "running" after its
-            // first trigger) so a decommissioned deployment's key can no longer
-            // satisfy a challenge. The "deployed" arm is load-bearing: the reconnect
-            // ownership challenge fires in the deploy->first-trigger window, so a
-            // "running"-only gate would fail every such challenge closed. A missing
-            // row or a null publicKey (live but not yet acked) returns null so the
-            // reconnect challenge fails closed and the address stays unrouted rather
-            // than routing without ownership proof.
-            const row = await db
-                .select({ publicKey: workflowRun.publicKey })
-                .from(workflowRun)
-                .where(and(eq(workflowRun.address, agentAddress), inArray(workflowRun.status, [...liveWorkflowRunStatuses])))
-                .limit(1)
-                .then((rows) => rows[0]);
-            return row?.publicKey ?? null;
-        },
         async lookupDeployRef() {
             // A workflow run is a supervised workflow-process pinned forever like a
             // native deployment: it keeps its deploy-time definition and never
@@ -269,9 +250,11 @@ export function createHubSessionLookups(deps) {
                 id: workflowRun.id,
                 address: workflowRun.address,
                 anchorRunId: workflowRun.anchorRunId,
+                tenantId: workflowRun.tenantId,
+                definitionId: workflowRun.definitionId,
             })
                 .from(workflowRun)
-                .where(and(eq(workflowRun.address, source.agentAddress), inArray(workflowRun.status, [...liveWorkflowRunStatuses])))
+                .where(and(eq(workflowRun.address, source.agentAddress), inArray(workflowRun.status, [...liveWorkflowRunStatuses]), isNotNull(workflowRun.definitionId)))
                 .limit(1);
             if (anchor === undefined ||
                 anchor.anchorRunId !== anchor.id ||
@@ -282,43 +265,30 @@ export function createHubSessionLookups(deps) {
             const anchorAddress = anchor.address;
             let newlyTerminalRuns;
             try {
-                if (source.kind === "allocated") {
-                    newlyTerminalRuns = await db.transaction(async (tx) => {
-                        const [allocation] = await tx
-                            .select()
-                            .from(sidecarAllocation)
-                            .where(eq(sidecarAllocation.anchorRunId, anchor.id))
-                            .limit(1)
-                            .for("update");
-                        if (allocation === undefined ||
-                            allocation.id !== source.allocationId ||
-                            allocation.anchorRunId !== source.anchorRunId ||
-                            source.anchorRunId !== anchor.id ||
-                            allocation.status !== "allocated" ||
-                            allocation.generation !== source.generation ||
-                            allocation.ensureAcceptedGeneration !== source.generation) {
-                            return null;
-                        }
-                        // Replacement advances this same row. Keep its lock until the
-                        // repository ref has advanced so ownership cannot change after
-                        // validation but before the old worker's pack becomes
-                        // authoritative.
-                        return agentRepoStore.receiveWorkflowRunPack({ kind: "workflow-run", id: workflowRunRepoId }, pack, ref, commitSha);
-                    });
-                    if (newlyTerminalRuns === null) {
-                        logger.warn `Workflow-run pack rejected for ${workflowRunRepoId}: source connection does not own the deployment's current allocation`;
-                        return { accepted: false, reason: "path_violation" };
+                newlyTerminalRuns = await db.transaction(async (tx) => {
+                    const [allocation] = await tx
+                        .select()
+                        .from(sidecarAllocation)
+                        .where(eq(sidecarAllocation.anchorRunId, anchor.id))
+                        .limit(1)
+                        .for("update");
+                    if (allocation === undefined ||
+                        allocation.id !== source.allocationId ||
+                        allocation.anchorRunId !== source.anchorRunId ||
+                        source.anchorRunId !== anchor.id ||
+                        allocation.status !== "allocated" ||
+                        allocation.generation !== source.generation ||
+                        allocation.ensureAcceptedGeneration !== source.generation) {
+                        return null;
                     }
-                }
-                else {
-                    const allocation = await db.query.sidecarAllocation.findFirst({
-                        where: eq(sidecarAllocation.anchorRunId, anchor.id),
-                    });
-                    if (allocation !== undefined) {
-                        logger.warn `Workflow-run pack rejected for ${workflowRunRepoId}: source connection does not own the deployment's current allocation`;
-                        return { accepted: false, reason: "path_violation" };
-                    }
-                    newlyTerminalRuns = await agentRepoStore.receiveWorkflowRunPack({ kind: "workflow-run", id: workflowRunRepoId }, pack, ref, commitSha);
+                    // Replacement advances this same row. Keep its lock until the
+                    // repository ref has advanced so ownership cannot change after
+                    // validation but before the old worker's pack becomes authoritative.
+                    return agentRepoStore.receiveWorkflowRunPack({ kind: "workflow-run", id: workflowRunRepoId }, pack, ref, commitSha);
+                });
+                if (newlyTerminalRuns === null) {
+                    logger.warn `Workflow-run pack rejected for ${workflowRunRepoId}: source connection does not own the deployment's current allocation`;
+                    return { accepted: false, reason: "path_violation" };
                 }
             }
             catch (err) {
@@ -352,6 +322,39 @@ export function createHubSessionLookups(deps) {
             for (const { runId, status } of newlyTerminalRuns) {
                 try {
                     await db.transaction(async (tx) => {
+                        // Lazily anchor the run before settling it. An internal run that
+                        // parks only on a plain signal gate never reaches
+                        // `registerSignalCorrelation`, the sole other path that mints an
+                        // internal run row, so its terminal event can be the first the hub
+                        // sees of the run. A never-minted row is ordinary bookkeeping, not
+                        // a deployment-boundary violation, so mint it here against this
+                        // deployment's anchor rather than letting the ownership guard below
+                        // mistake absence for foreignness. The insert no-ops when any row
+                        // already exists, which keeps that guard authoritative for a row
+                        // that exists and anchors elsewhere. The principal is null: an
+                        // internal run inherits its deployment's grants and has none of its
+                        // own.
+                        //
+                        // The mint necessarily precedes the ownership guard, so an id the
+                        // hub has never seen is claimed under THIS anchor before anything
+                        // establishes it belongs here. That ordering is required -- the
+                        // guard reads the row the mint may have to create -- and it is
+                        // bounded rather than unbounded: internal run ids are supplied by
+                        // the sidecar and accepted verbatim, so the value is
+                        // caller-influenced, but it is a different population from the
+                        // anchor ids the hub mints itself, and nothing resolves an
+                        // internal id without also constraining the anchor or the tenant.
+                        // The insert cannot take a row away from another deployment; the
+                        // worst it does is create one for an id that deployment would
+                        // otherwise have created later.
+                        await workflowRunStore.createIfAbsent({
+                            id: runId,
+                            anchorRunId: anchor.id,
+                            definitionId: anchor.definitionId,
+                            tenantId: anchor.tenantId,
+                            principalId: null,
+                            status: "running",
+                        }, tx);
                         const [ownedRun] = await tx
                             .select({ anchorRunId: workflowRun.anchorRunId })
                             .from(workflowRun)
@@ -363,19 +366,11 @@ export function createHubSessionLookups(deps) {
                         }
                         const won = await workflowRunStore.markTerminal(runId, status, now, tx);
                         if (won === null) {
-                            // No running row matched. Either the run is already terminal (a
-                            // benign replay against an already-settled row) or no row exists
-                            // at all -- the run reached a terminal event before its anchor
-                            // committed, so its terminal state has nowhere to land. Only the
-                            // second case is a defect; distinguish them and log the missing
-                            // anchor loudly rather than silently treating both as done.
-                            const [existing] = await tx
-                                .select({ id: workflowRun.id })
-                                .from(workflowRun)
-                                .where(eq(workflowRun.id, runId));
-                            if (existing === undefined) {
-                                logger.error `Terminal event for run ${runId} (deployment ${anchor.id}, target status ${status}) has no workflow_run row; the run terminated before its anchor committed`;
-                            }
+                            // The row exists (the mint above guarantees it) and belongs to
+                            // this deployment (the guard above), so no running row matched
+                            // only because the run is already terminal -- a benign replay
+                            // against an already-settled row. Leave its settled status and
+                            // `endedAt` alone.
                             return;
                         }
                         // Deactivate the run's own principal, if it has one. Externally-
@@ -656,8 +651,9 @@ export async function findRoutableById(db, id, tenantId) {
     // return cannot do.
     if (runRow === undefined ||
         !isTopLevelRun(runRow) ||
-        runRow.address === null) {
+        runRow.address === null ||
+        runRow.definitionId === null) {
         return undefined;
     }
-    return runRowToRoutableRecord(runRow, runRow.address);
+    return runRowToRoutableRecord({ ...runRow, definitionId: runRow.definitionId }, runRow.address);
 }

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

@@ -1,20 +1,19 @@
 import type { DB } from "@intx/db";
-import type { AgentRepoStore } from "./agent-repo.js";
 import type { EventCollectorRegistry } from "./event-collector-registry.js";
 import type { SidecarEventEmitter } from "./ws/sidecar-events.js";
+import type { SenderDeploySettledOutcome } from "./ws/sidecar-handler.js";
 /** Subset of `SidecarRouter` the orchestrator drives outbound. The
  * narrow surface keeps tests honest and decouples the orchestrator
  * from the rest of the router API. */
 export type HubSessionRouterFacade = {
-    sendPack(agentAddress: string, pack: Uint8Array, ref: string, commitSha: string): Promise<void>;
     dispatchAgentEvent(agentAddress: string, event: unknown): void;
+    noteSenderDeploySettled(address: string, outcome: SenderDeploySettledOutcome): void;
 };
 export type HubSessionOrchestratorDeps = {
     events: SidecarEventEmitter;
     router: HubSessionRouterFacade;
     db: DB["db"];
     eventCollectors: EventCollectorRegistry;
-    agentRepoStore: AgentRepoStore;
 };
 export type HubSessionOrchestrator = {
     /** Unsubscribe all listeners. Tests use this between cases; the hub

package/dist/hub-session-orchestrator.js

@@ -15,10 +15,9 @@ import { workflowRun } from "@intx/db/schema";
 import { parseMailToEmail } from "@intx/mime";
 import { parseInferenceEvent } from "@intx/types/runtime";
 import { getLogger } from "@intx/log";
-import { parseAgentId } from "./hub-session-lookups.js";
 const log = getLogger(["hub", "orchestrator"]);
 export function createHubSessionOrchestrator(deps) {
-    const { events, router, db, eventCollectors, agentRepoStore } = deps;
+    const { events, router, db, eventCollectors } = deps;
     const unsubscribers = [];
     unsubscribers.push(events.on("agent.event", ({ agentAddress, event }) => {
         const validated = parseInferenceEvent(event);
@@ -46,25 +45,27 @@ export function createHubSessionOrchestrator(deps) {
     }));
     unsubscribers.push(events.on("agent.deploy.ack", async (event) => {
         const { agentAddress, publicKey, allocated } = event;
-        // Exclusive initialization publishes its key only after every deploy
+        // Provisioned initialization publishes its key only after every deploy
         // and asset pack succeeds under the allocation generation fence.
         if (allocated !== undefined)
             return;
         // Every deploy address names a workflow run whose public key lives on its
         // single self-anchored workflow_run row, keyed by address. Persist it
-        // there so the reconnect ownership challenge can verify the address off
-        // the same row `lookupPublicKey` reads. Only the deployment-level address
-        // owns a row, so a stray per-step ack updates nothing.
+        // there as the deployment's published identity. Reconnect routing is
+        // allocation-authenticated, so this projection is not connection
+        // authority. Only the deployment-level address owns a row, so a stray
+        // per-step ack updates nothing.
         await db
             .update(workflowRun)
             .set({ publicKey })
             .where(eq(workflowRun.address, agentAddress));
-    }));
-    unsubscribers.push(events.on("deploy.ref.stale", async ({ agentAddress }) => {
-        const agentId = parseAgentId(agentAddress);
-        const { pack, commitSha, ref } = await agentRepoStore.createDeployPack(agentId);
-        await router.sendPack(agentAddress, pack, ref, commitSha);
-        log.info("Re-deployed stale agent {agentAddress}", { agentAddress });
+        // The key is now durable. Wake any mail the run parked while pre-ack so it
+        // is delivered with the sender key co-delivered, closing the window where
+        // a run sends before its key is recorded. The write above happens-before
+        // this settle, so a re-drive resolves the recorded key. The address is the
+        // run's own deploy address, byte-identical to the sender address its mail
+        // was sent under.
+        router.noteSenderDeploySettled(agentAddress, { recorded: publicKey });
     }));
     unsubscribers.push(events.on("mail.persisted", (row) => {
         const parsed = parseMailToEmail(row.raw, row.id);

package/dist/index.d.ts

@@ -1,24 +1,25 @@
 export { createAgentRepoStore, type AgentRepoStore, type DeployContent, } from "./agent-repo.js";
-export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, type SessionService, type DeployWorkflowDefinitionResult, type DeployWorkflowFromSourceParams, type DeployPreparedCodeSourcedWorkflowParams, type InstallAndApproveWorkflowSourceParams, type PreparedWorkflowDeployer, type DeployCodeSourcedWorkflowArgs, } from "./session-service.js";
+export { createSessionService, recoverSenderDeploy, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, type SessionService, type DeployWorkflowDefinitionResult, type DeployPreparedCodeSourcedWorkflowParams, type InstallAndApproveWorkflowSourceParams, type PreparedWorkflowDeployer, type DeployCodeSourcedWorkflowArgs, } from "./session-service.js";
 export { installAndApproveWorkflowDefinition, createDbFrozenApprovalWriter, type InstallAndApproveArgs, type InstallAndApproveResult, type ProbeGateResult, type ProbeApprovalPolicy, type ApproveProbedGrants, } from "./workflow-probe-gate.js";
 export { committedReadsToSourceTree } from "./committed-source-tree.js";
 export type { SourceTreeReads } from "./workflow-source-closure.js";
 export type { WorkflowDefinition } from "@intx/workflow/definition";
 export { createEventCollectorRegistry, type EventCollectorRegistry, } from "./event-collector-registry.js";
-export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarAuthIdentity, type SidecarAuthenticator, type AllocatedSidecarTarget, type SidecarAllocationRouter, createSidecarCredentialResolver, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, type WsHandle, createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedPayload, type SidecarMailPersistedRow, type MailTriggeredRunGrantsResult, type WorkflowRunPackSource, } from "./ws/index.js";
+export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SenderDeploySettledOutcome, type AllocatedSenderDeployAttempt, type SidecarAuthIdentity, type SidecarAuthenticator, type AllocatedSidecarTarget, type SidecarAllocationRouter, SidecarIdentityValidationError, createSidecarCredentialResolver, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, type WsHandle, createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedPayload, type SidecarMailPersistedRow, type MailTriggeredRunGrantsResult, type WorkflowRunPackSource, } from "./ws/index.js";
 export { createHubSessionLookups, findRoutableById, parseAgentId, resolveRoutableAddress, resolveRunIdForSession, resolveRunSessionId, runRowToRoutableRecord, type HubSessionLookupsDeps, type RoutableEndpoint, type RoutableRecord, } from "./hub-session-lookups.js";
 export { createHubSessionOrchestrator, type HubSessionOrchestrator, type HubSessionOrchestratorDeps, type HubSessionRouterFacade, } from "./hub-session-orchestrator.js";
-export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.js";
-export { createSidecarPluginRegistry, createSidecarAllocationReconciler, resolveEffectiveSidecarPlacement, type CreateSidecarPluginRegistryOpts, type DestroySidecarRequest, type DestroySidecarResult, type EnsureSidecarRequest, type EnsureSidecarResult, type ResolveEffectiveSidecarPlacementOpts, type SidecarCredentialIdentity, type SidecarCredentialResolver, type SidecarOperationFailure, type SidecarPluginRegistry, type SidecarProvisioner, type SidecarAllocationReconciler, type SidecarAllocationReconcilerDeps, } from "./sidecar-allocation/index.js";
+export { pushSourceUpdates, pushSourceUpdatesSubtree, pushCredentialRevoke, pushCredentialReconcile, } from "./credential-push.js";
+export { chooseFirstSidecarProvisioner, createSidecarPluginRegistry, createSidecarAllocationReconciler, type CreateSidecarPluginRegistryOpts, type DestroySidecarRequest, type DestroySidecarResult, type EnsureSidecarRequest, type EnsureSidecarResult, type SidecarCredentialIdentity, type SidecarCredentialResolver, type SidecarOperationFailure, type SidecarPluginRegistry, type SidecarProvisioner, type SidecarProvisionerChooser, type SidecarAllocationReconciler, type SidecarAllocationReconcilerDeps, type SidecarReconciliationContext, } from "./sidecar-allocation/index.js";
 export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
 export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
-export { createWorkflowAllocationService, ExclusiveWorkflowPlacementError, resolveWorkflowSidecarPlacement, type PrepareExclusiveWorkflowDeploymentArgs, type PreparedExclusiveWorkflowDeployment, type WorkflowAllocationService, type WorkflowAllocationServiceDeps, } from "./workflow-allocation-service.js";
+export { createReconciliationScheduler, DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY, type ReconciliationSchedulerOptions, } from "./reconciliation-scheduler.js";
+export { createWorkflowAllocationService, WorkflowProvisioningError, type PrepareProvisionedWorkflowDeploymentArgs, type PreparedProvisionedWorkflowDeployment, type WorkflowAllocationService, type WorkflowAllocationServiceDeps, } from "./workflow-allocation-service.js";
 export { createWorkflowDispatchService, type WorkflowDispatchAcknowledgement, type WorkflowDispatchService, type WorkflowDispatchServiceDeps, } from "./workflow-dispatch-service.js";
 export { listAcceptedWorkflowDispatches, listConsumedWorkflowDispatches, listReceivedWorkflowSignals, type AcceptedWorkflowDispatch, type ConsumedWorkflowDispatch, type ReceivedWorkflowSignal, } from "./workflow-dispatch-settlement.js";
 export { skillKindHandler, skillAuthorize, skillFrontmatterSchema, getSkillIndex, type SkillIndexEntry, type SkillFrontmatter, type SkillPrincipal, type SkillHubPrincipal, type SkillSidecarPrincipal, } from "./skill-kind.js";
 export { packageRegistryKindHandler, packageRegistryAuthorize, asTarballEntry, validateTarballPackageJSON, TARBALLS_PREFIX, TARBALL_FILENAME_PATTERN, REGISTRY_INDEX_PATH, WORKSPACE_BUILTINS_REGISTRY, } from "./package-registry-kind.js";
 export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, type WorkflowPrincipal, type WorkflowHubPrincipal, type WorkflowSidecarPrincipal, } from "./workflow-kind.js";
-export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, type ClaimCheckEnvelope, type ConsumedEnvelope, type EnqueueAlreadyPresentReason, type EnqueueInboxArgs, type EnqueueInboxOutcome, type EnqueueInboxResult, type DequeueToProcessingResult, type ReadProcessingEntryResult, type MarkConsumedArgs, type MarkConsumedResult, type WorkflowRunLifecycle, type ReplayProcessingToInboxOpts, type ReplayProcessingToInboxResult, type WorkflowRunPrincipal, type WorkflowRunHubPrincipal, type WorkflowRunSidecarPrincipal, type WorkflowRunWorkflowProcessPrincipal, type WorkflowRunSupervisorPrincipal, } from "./workflow-run-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, classifyTerminalEvent, scanRunsForBoot, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, type ClaimCheckEnvelope, type ConsumedEnvelope, type EnqueueAlreadyPresentReason, type EnqueueInboxArgs, type EnqueueInboxOutcome, type EnqueueInboxResult, type DequeueToProcessingResult, type ReadProcessingEntryResult, type MarkConsumedArgs, type MarkConsumedResult, type WorkflowRunLifecycle, type ReplayProcessingToInboxOpts, type ReplayProcessingToInboxResult, type WorkflowRunPrincipal, type WorkflowRunHubPrincipal, type WorkflowRunSidecarPrincipal, type WorkflowRunWorkflowProcessPrincipal, type WorkflowRunSupervisorPrincipal, } from "./workflow-run-kind.js";
 export { restoreWorkflowRunToAllocation, WORKFLOW_RUN_RESTORE_REFS, } from "./workflow-run-restore.js";
 export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, type AssetService, type Asset, type CreateAssetParams, type PopulateAssetParams, type AssetServiceErrorReason, type ReadAssetBlobParams, type ListAssetBlobsParams, } from "./asset-service.js";
 export { createWorkflowRunReader, type WorkflowRunReader, type WorkflowRunEvent, } from "./workflow-run-reader.js";

package/dist/index.js

@@ -1,22 +1,23 @@
 export { createAgentRepoStore, } from "./agent-repo.js";
-export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, } from "./session-service.js";
+export { createSessionService, recoverSenderDeploy, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, } from "./session-service.js";
 export { installAndApproveWorkflowDefinition, createDbFrozenApprovalWriter, } from "./workflow-probe-gate.js";
 export { committedReadsToSourceTree } from "./committed-source-tree.js";
 export { createEventCollectorRegistry, } from "./event-collector-registry.js";
-export { createSidecarRouter, createSidecarCredentialResolver, createSidecarTokenAuthenticator, createSidecarEmitter, } from "./ws/index.js";
+export { createSidecarRouter, SidecarIdentityValidationError, createSidecarCredentialResolver, createSidecarTokenAuthenticator, createSidecarEmitter, } from "./ws/index.js";
 export { createHubSessionLookups, findRoutableById, parseAgentId, resolveRoutableAddress, resolveRunIdForSession, resolveRunSessionId, runRowToRoutableRecord, } from "./hub-session-lookups.js";
 export { createHubSessionOrchestrator, } from "./hub-session-orchestrator.js";
-export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.js";
-export { createSidecarPluginRegistry, createSidecarAllocationReconciler, resolveEffectiveSidecarPlacement, } from "./sidecar-allocation/index.js";
+export { pushSourceUpdates, pushSourceUpdatesSubtree, pushCredentialRevoke, pushCredentialReconcile, } from "./credential-push.js";
+export { chooseFirstSidecarProvisioner, createSidecarPluginRegistry, createSidecarAllocationReconciler, } from "./sidecar-allocation/index.js";
 export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
 export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
-export { createWorkflowAllocationService, ExclusiveWorkflowPlacementError, resolveWorkflowSidecarPlacement, } from "./workflow-allocation-service.js";
+export { createReconciliationScheduler, DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY, } from "./reconciliation-scheduler.js";
+export { createWorkflowAllocationService, WorkflowProvisioningError, } from "./workflow-allocation-service.js";
 export { createWorkflowDispatchService, } from "./workflow-dispatch-service.js";
 export { listAcceptedWorkflowDispatches, listConsumedWorkflowDispatches, listReceivedWorkflowSignals, } from "./workflow-dispatch-settlement.js";
 export { skillKindHandler, skillAuthorize, skillFrontmatterSchema, getSkillIndex, } from "./skill-kind.js";
 export { packageRegistryKindHandler, packageRegistryAuthorize, asTarballEntry, validateTarballPackageJSON, TARBALLS_PREFIX, TARBALL_FILENAME_PATTERN, REGISTRY_INDEX_PATH, WORKSPACE_BUILTINS_REGISTRY, } from "./package-registry-kind.js";
 export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, } from "./workflow-kind.js";
-export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, } from "./workflow-run-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, classifyTerminalEvent, scanRunsForBoot, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, } from "./workflow-run-kind.js";
 export { restoreWorkflowRunToAllocation, WORKFLOW_RUN_RESTORE_REFS, } from "./workflow-run-restore.js";
 export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, } from "./asset-service.js";
 export { createWorkflowRunReader, } from "./workflow-run-reader.js";

package/dist/reconciliation-scheduler.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY = 8;
+export type ReconciliationSchedulerOptions = {
+    readonly name: string;
+    /** Claim and process at most one item; false means no due work was found. */
+    readonly reconcileNext: () => Promise<boolean>;
+    readonly concurrency?: number;
+    readonly intervalMs?: number;
+};
+/** Polls for work without waiting for other occupied slots to finish. */
+export declare function createReconciliationScheduler({ name, reconcileNext, concurrency, intervalMs, }: ReconciliationSchedulerOptions): {
+    start(): void;
+    stop(): void;
+    wake: () => void;
+};

package/dist/reconciliation-scheduler.js

@@ -0,0 +1,55 @@
+import { getLogger } from "@intx/log";
+const logger = getLogger(["hub", "reconciliation"]);
+export const DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY = 8;
+/** Polls for work without waiting for other occupied slots to finish. */
+export function createReconciliationScheduler({ name, reconcileNext, concurrency = DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY, intervalMs = 1_000, }) {
+    if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {
+        throw new Error("Reconciliation concurrency must be a positive integer");
+    }
+    if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0) {
+        throw new Error("Reconciliation interval must be a positive integer");
+    }
+    let stopped = true;
+    let active = 0;
+    let timer;
+    function finish(worked) {
+        active -= 1;
+        if (worked)
+            wake();
+    }
+    function wake() {
+        if (stopped)
+            return;
+        while (active < concurrency) {
+            active += 1;
+            void Promise.resolve()
+                .then(() => (stopped ? false : reconcileNext()))
+                .then(finish, (error) => {
+                logger.error `${name} reconciliation failed: ${error instanceof Error ? error.message : String(error)}`;
+                finish(false);
+            });
+        }
+    }
+    function schedule(delayMs) {
+        timer = setTimeout(() => {
+            if (stopped)
+                return;
+            wake();
+            schedule(intervalMs);
+        }, delayMs);
+        timer.unref?.();
+    }
+    return {
+        start() {
+            if (!stopped)
+                return;
+            stopped = false;
+            schedule(0);
+        },
+        stop() {
+            stopped = true;
+            clearTimeout(timer);
+        },
+        wake,
+    };
+}

package/dist/repo-store/index.d.ts

@@ -1,4 +1,5 @@
 export type { AuthorizeFn, CommittedReads, CommittedTreeEntry, InitRepoOpts, KindHandler, NewlyTerminalRun, PriorDeltaReads, Principal, RefEntry, RepoAction, RepoId, RepoKind, RepoStore, RepoStoreSubscribeEvent, TreeContent, ValidatePushResult, WriteResult, WriteTreePreservingPrefixArgs, } from "./types.js";
 export { UserPrincipal } from "./types.js";
+export { authorizeUserPrincipal, type AuthorizeUserPrincipalArgs, } from "./user-principal-gate.js";
 export { createRepoStore, type CreateRepoStoreConfig } from "./store.js";
 export { subscribeKind, type SubscribeKindOpts, type SubscribeKindEntry, } from "./subscribe-kind.js";

package/dist/repo-store/index.js

@@ -1,3 +1,4 @@
 export { UserPrincipal } from "./types.js";
+export { authorizeUserPrincipal, } from "./user-principal-gate.js";
 export { createRepoStore } from "./store.js";
 export { subscribeKind, } from "./subscribe-kind.js";

package/dist/repo-store/user-principal-gate.d.ts

@@ -0,0 +1,26 @@
+import type { RepoAction, RepoId, Principal } from "./types.js";
+export type AuthorizeUserPrincipalArgs = {
+    principal: Principal;
+    repoId: RepoId;
+    ref: string;
+    action: RepoAction;
+    /**
+     * The resource-kind prefix the pre-resolved authz verdict must carry
+     * for this kind: the verdict's `resource` is compared against
+     * `<resourcePrefix>:<repoId.id>`.
+     */
+    resourcePrefix: string;
+};
+/**
+ * Verdict for a `user` principal performing `action` on `ref` of
+ * `repoId`, in the shape the substrate's `AuthorizeFn` contract
+ * expects. The caller dispatches on `principal.kind === "user"` first;
+ * this function narrows with `UserPrincipal` and applies the full
+ * claim/verdict cross-check.
+ */
+export declare function authorizeUserPrincipal({ principal, repoId, ref, action, resourcePrefix, }: AuthorizeUserPrincipalArgs): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};

package/dist/repo-store/user-principal-gate.js

@@ -0,0 +1,78 @@
+// Shared authorization gate for the `user` principal variant, used by
+// every kind handler that accepts user-token-authenticated requests
+// (workflow, skill, agent-state, workflow-run).
+//
+// The route layer has already pre-resolved the grant verdict and
+// attached it as `authz`; the kind handlers do NOT re-query the grant
+// store here. This gate (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.
+//
+// Funnelling every kind through this one gate keeps the security-
+// critical claim/verdict cross-check from drifting between kinds. The
+// only per-kind input is the `resourcePrefix` the verdict's `resource`
+// must carry (`asset:<id>` for the codebase kinds, `agent-state:<id>`,
+// `workflow-run:<id>`).
+import { type } from "arktype";
+import { glob, repoActionToGrantVerb } from "@intx/hub-common";
+import { UserPrincipal } from "./types.js";
+/**
+ * Verdict for a `user` principal performing `action` on `ref` of
+ * `repoId`, in the shape the substrate's `AuthorizeFn` contract
+ * expects. The caller dispatches on `principal.kind === "user"` first;
+ * this function narrows with `UserPrincipal` and applies the full
+ * claim/verdict cross-check.
+ */
+export function authorizeUserPrincipal({ principal, repoId, ref, action, resourcePrefix, }) {
+    const parsed = UserPrincipal(principal);
+    if (parsed instanceof type.errors) {
+        return {
+            allowed: false,
+            reason: `user principal is malformed: ${parsed.summary}`,
+        };
+    }
+    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 = `${resourcePrefix}:${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}`,
+    };
+}