@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/session-service.d.ts

@@ -1,12 +1,18 @@
-import { type DB } from "@intx/db";
-import type { CryptoProvider, HarnessConfig, InferenceSource, MessageAttachment } from "@intx/types/runtime";
+import { type DB, type SidecarAllocation } from "@intx/db";
+import type { CredentialDelivery } from "@intx/types/sidecar";
+import type { CredentialCipher } from "@intx/types";
+import type { HarnessConfig, InferenceSource } from "@intx/types/runtime";
 import { type RegistryConfig, type ScopeRoute } from "@intx/tool-packaging";
 import { type ToolPackagePin } from "@intx/types/tool-packages";
-import { type WorkflowDefinition } from "@intx/workflow/definition";
-import { type DeployContent as OrchestratorDeployContent, type DeploySingleStepFn } from "@intx/workflow-deploy";
+import type { SourceRefPin, WorkflowProjectionWithSources, WorkflowSourceAssetMount } from "@intx/types/sidecar";
+import type { WorkflowDefinitionAssetSource, WorkflowDefinitionRegistrySource, WorkflowDefinitionSource } from "@intx/types/workflow-sources";
+import { type DeployContent as OrchestratorDeployContent } from "@intx/workflow-deploy";
 import type { AgentRepoStore, DeployContent } from "./agent-repo.js";
 import { type AssetService } from "./asset-service.js";
-import type { SidecarRouter } from "./ws/sidecar-handler.js";
+import type { AllocatedSidecarTarget, SidecarAllocationRouter, SidecarRouter, WorkflowProbeResult } from "./ws/sidecar-handler.js";
+import { type ResolveAssetAttachmentFn } from "./workflow-closure-resolution.js";
+import { type InstallAndApproveResult } from "./workflow-probe-gate.js";
+import type { SidecarReconciliationContext } from "./sidecar-allocation/operation.js";
 export declare class SessionLaunchError extends Error {
     /** Which phase failed: "write", "provision", "pack", or "start". */
     readonly phase: string;
@@ -27,128 +33,97 @@ export type SessionService = {
     stageWorkflowStep(params: {
         agentAddress: string;
         agentId: string;
-        instanceId: string;
+        runId: string;
         config: HarnessConfig;
         deployContent: DeployContent;
         toolPackagePins?: readonly ToolPackagePin[];
+        allocationTarget: AllocatedSidecarTarget;
     }): Promise<void>;
-    /**
-     * Deploy a single-agent instance through the single-step-at-head path,
-     * wrapping the harness as a one-step workflow and routing it through the
-     * deploy core with the instance's real identity. Replaces `launchSession`
-     * as the production instance-deploy entry point: the instance runs as a
-     * supervised workflow-process child. Writes no `workflow_deployment`
-     * row. Returns the head's agent-key ack (the key the head signs its
-     * reconnect challenges with).
-     */
-    deployInstanceAtHead(params: {
-        agentAddress: string;
-        agentId: string;
-        instanceId: string;
-        config: HarnessConfig;
-        deployContent: DeployContent;
-        toolPackagePins?: readonly ToolPackagePin[];
-    }): Promise<{
-        publicKey: string;
-    }>;
-    /**
-     * Deploy a one-step workflow once at the head through the deploy core,
-     * without the DB-backed `workflow_deployment` projection row. Stages the
-     * head's deploy tree (deploy-tree write, pack, asset fan-out), fires the
-     * deployment `agent.deploy` frame carrying the workflow definition +
-     * source pin (the sidecar initializes the head repo and spawns the
-     * workflow-process child), then delivers the pack to the head. Returns
-     * the sidecar supervisor's principal public key. See `DeploySingleStepFn`.
-     */
-    deploySingleStepAtHead: DeploySingleStepFn;
-    /**
-     * Deploy a multi-step `WorkflowDefinition` through the workflow-deploy
-     * orchestrator's multi-step branch. This is the general workflow
-     * deploy entry point: it is not coupled to a single agent's
-     * credential/session model the way `launchSession` is. The
-     * orchestrator derives every per-step address
-     * from `deploymentId` + `deploymentDomain`, provisions each step's
-     * agent-state repo via the shared per-agent deploy phases, writes the
-     * workflow repo, and fires the deployment-level `agent.deploy` frame.
-     *
-     * Persists one `workflow_deployment` projection row keyed by
-     * `deploymentId` so the deployment is listable per tenant; the
-     * RepoStore substrate has no by-kind listing API of its own.
-     *
-     * Returns the supervisor's principal public key surfaced by the
-     * sidecar's `agent.deploy.ack`.
-     */
-    deployWorkflowDefinition(params: DeployWorkflowDefinitionParams): Promise<DeployWorkflowDefinitionResult>;
-    /**
-     * Compose a signed RFC 2822 message from the user and deliver it to the
-     * agent via the mail transport. Throws if the agent is unreachable.
-     * Returns the raw MIME bytes of the assembled message.
-     */
-    sendUserMessage(params: UserMessageParams): Promise<Uint8Array>;
     /**
      * Undeploy an agent and wait for the sidecar to acknowledge.
      */
     endSession(agentAddress: string, reason: string): Promise<void>;
 };
-export type DeployWorkflowDefinitionParams = {
-    /** Owning tenant; recorded on the projection row. */
-    tenantId: string;
-    /**
-     * Stable deployment identifier. The orchestrator concatenates it into
-     * every derived per-step address and the deployment-level address, and
-     * it is the `workflow_deployment` row's primary key. The caller owns
-     * its generation.
-     */
-    deploymentId: string;
-    /**
-     * Mail domain the deployment's derived addresses live under. The
-     * orchestrator derives `ins_<deploymentId>-<stepId>@<deploymentDomain>`
-     * per step and `ins_<deploymentId>@<deploymentDomain>` for the
-     * deployment-level supervisor address.
-     */
-    deploymentDomain: string;
-    /** The hydrated workflow definition to deploy. */
-    definition: WorkflowDefinition;
-    /**
-     * The `workflow`-kind asset the definition was hydrated from. Recorded
-     * on the projection row so the listing surface can join back to the
-     * source asset.
-     */
-    definitionAssetId: string;
-    /**
-     * Harness configuration shared across every step's launch. The
-     * orchestrator overrides `agentAddress`, `agentId`, and `systemPrompt`
-     * per step.
-     */
-    config: HarnessConfig;
-    /** Deploy-tree content shared across every step's launch. */
-    deployContent: DeployContent;
-    /** Tool-package pins to ship with every step's deploy. */
-    toolPackagePins?: readonly ToolPackagePin[];
-};
 export type DeployWorkflowDefinitionResult = {
     /** Echoes the deployment id recorded on the projection row. */
-    deploymentId: string;
+    anchorRunId: string;
     /** Deployment-level mail address the supervisor registers on the bus. */
     deploymentAddress: string;
     /** Supervisor principal public key from the sidecar's deploy ack. */
     publicKey: string;
 };
-export type UserMessageParams = {
-    agentAddress: string;
-    from: string;
-    messageId: string;
-    date: Date;
-    content: string;
-    attachments?: MessageAttachment[];
-    inReplyTo?: string;
-    references?: string[];
-    sessionId: string;
+/**
+ * Install/probe/gate/freeze inputs for a code-sourced workflow, DECOUPLED from
+ * deploy. The provisioned prepare path calls this on probe-scoped capacity,
+ * persists the frozen bundle, and deploys it to the workflow allocation later
+ * with no re-probe.
+ */
+export type InstallAndApproveWorkflowSourceParams = {
+    /** Where the definition's bytes come from at probe time. */
+    source: WorkflowDefinitionSource;
+    /** The `interchange.workflow` entry-module path the sidecar evaluates. */
+    entry: string;
+    /**
+     * A `name@range` spec for the definition package. REQUIRED for the `registry`
+     * and asset-`tarball` variants; omitted for the asset-`source` variant.
+     */
+    pin?: string;
+    /** The `workflow`-kind asset the frozen definition projects a definition over. */
+    definitionAssetId: string;
+    /** The exact provisioned generation that executes the probe. */
+    allocationTarget: AllocatedSidecarTarget;
+    /** Optional durable handoff invoked with the raw probe answer. */
+    onProbeResult?: (result: WorkflowProbeResult) => Promise<void>;
+};
+/**
+ * Inputs to deploy a previously-frozen code-sourced approval bundle to a
+ * dedicated allocation. Mirrors `DeployPreparedWorkflowDefinitionParams` for the
+ * source-ref lineage: the anchor `workflow_run` row already exists from prepare
+ * time, so the deploy UPDATES it under the allocation-ownership lock rather than
+ * inserting a fresh one.
+ */
+export type DeployPreparedCodeSourcedWorkflowParams = {
+    /** Owning tenant; the definition's own tenant for credential resolution. */
     tenantId: string;
-    cryptoProvider: CryptoProvider;
+    /** The pre-inserted anchor run id, fixed at prepare time. */
+    anchorRunId: string;
+    /** Mail domain the deployment's derived addresses live under. */
+    deploymentDomain: string;
+    /** The deployment-level mail address; re-derived and asserted coherent. */
+    agentAddress: string;
+    /** Where the definition's bytes come from, rehydrated from the frozen bundle. */
+    source: WorkflowDefinitionSource;
+    /** The frozen approval bundle rehydrated from the launch spec. */
+    approved: InstallAndApproveResult;
+    /** Harness config carrying the re-resolved per-step inference chain. */
+    config: HarnessConfig;
+    /** The exact allocation generation to deploy onto. */
+    allocationTarget: AllocatedSidecarTarget;
+    /** Current owner and cancellation of this initialization attempt. */
+    reconciliation: SidecarReconciliationContext;
+    /** Cipher for the definition's tenant-owned credential bindings, if any. */
+    credentialCipher?: CredentialCipher;
+};
+export type PreparedWorkflowDeployer = {
+    /**
+     * Install + probe + gate + freeze a code-sourced definition, returning the
+     * frozen bundle WITHOUT deploying it. The provisioned
+     * prepare path persists the bundle and deploys it later via
+     * `deployPreparedCodeSourcedWorkflow`.
+     */
+    installAndApproveWorkflowSource(params: InstallAndApproveWorkflowSourceParams): Promise<InstallAndApproveResult>;
+    /**
+     * Deploy a previously-frozen code-sourced approval bundle to a dedicated
+     * allocation, updating the pre-existing anchor run under the
+     * allocation-ownership lock. No re-probe: the frozen projection/hash/closure
+     * ride verbatim.
+     */
+    deployPreparedCodeSourcedWorkflow(params: DeployPreparedCodeSourcedWorkflowParams): Promise<DeployWorkflowDefinitionResult>;
 };
 export type SessionServiceDeps = {
     sidecarRouter: SidecarRouter;
+    /** Present when this Hub can route deploy phases to provisioned allocations. */
+    sidecarAllocationRouter?: SidecarAllocationRouter;
     agentRepoStore: AgentRepoStore;
     /**
      * Optional asset attachment integration. When set, the deploy flow
@@ -209,27 +184,178 @@ export type SessionServiceDeps = {
  * production multi-step callback does, rather than casting `unknown`.
  */
 export declare function bridgeOrchestratorDeployContent(content: OrchestratorDeployContent): DeployContent;
-/**
- * Wire the workflow-deploy orchestrator's `sendMultiStepDeploy`
- * dependency against `SidecarRouter.sendAgentDeploy`. The router
- * accepts an optional `workflow` projection on the deploy frame; the
- * sidecar's deploy router uses field presence to route the frame to
- * the workflow deploy path. The supervisor public key returned by the
- * sidecar's `agent.deploy.ack` is threaded back as the
- * `MultiStepDeployResult.publicKey`.
- *
- * Exported so the co-located caller-site test can assert that the
- * closure constructed in `launchSession` reaches the wire surface via
- * `sendAgentDeploy` with a `workflow` field structurally matching the
- * `AgentDeployFrame.workflow` schema.
- */
-export declare function sendMultiStepDeployFrame(args: {
-    sidecarRouter: SidecarRouter;
+/** Fields the deploy frame carries onto `sendAgentDeploy`. */
+type DeployFrameCommonArgs = {
+    sidecarAllocationRouter: SidecarAllocationRouter;
+    allocationTarget: AllocatedSidecarTarget;
     agentAddress: string;
     config: HarnessConfig;
-    definition: WorkflowDefinition;
     sources: Record<string, InferenceSource[]>;
-}): Promise<{
+};
+/**
+ * For a code-sourced (npm) deploy the hub never holds the live
+ * `WorkflowDefinition` -- it lives only in the airlocked child. The gate/freeze
+ * layer hashed the inert projection; the deploy frame carries that hash and the
+ * source-ref pin, and the sidecar re-materializes and evaluates the pinned code
+ * from the pin, so no inline definition rides the frame. The content hash is
+ * owned by the gate, so this frame never recomputes it -- recomputing over a
+ * live wire lineage would diverge from the inert projection the child
+ * re-verifies against.
+ */
+export type SourceRefDeployFrameArgs = DeployFrameCommonArgs & {
+    lineage: "source-ref";
+    /**
+     * The gate-frozen wire hash of the approved projection -- stamped onto the
+     * frame VERBATIM. This arm does not recompute it: the freeze layer owns the
+     * content hash, and the child re-verifies its closure evaluation against this
+     * exact value.
+     */
+    approvedWireHash: string;
+    /**
+     * The source-ref pin: where the definition's bytes come from plus the frozen
+     * dependency closure the hub resolved for it. The two co-travel, so they are
+     * one required object on this arm (see `SourceRefPin`) -- the sidecar
+     * re-materializes the exact tree from the pin at apply time.
+     */
+    sourceRef: SourceRefPin;
+    /**
+     * Resolved credential material for the definition's credential bindings,
+     * delivered to the child on the frame. The hub resolves + decrypts here; the
+     * source-ref child decrypts nothing. The grant that AUTHORIZES a credential's
+     * use is minted per-run by run-grant materialization, not carried on this
+     * frame.
+     */
+    credentials?: CredentialDelivery;
+    /**
+     * The projection's inline onTrigger section bodies, each already in inert wire
+     * form with its per-step inference sources pinned and its own wire hash --
+     * built by `deployCodeSourcedWorkflow` from the frozen projection. The sidecar
+     * seals each body's sources into the run record and re-verifies against its
+     * wire hash. Absent when the projection has no inline onTrigger body.
+     */
+    referencedDefinitions?: readonly WorkflowProjectionWithSources[];
+    /**
+     * Source assets the pin's `kind:"asset"` closure entries read from, delivered
+     * inline on the frame so the sidecar checks them out into its durable
+     * per-deployment source store. Absent for a registry-sourced pin (its tarballs
+     * are fetched over HTTP).
+     */
+    assets?: readonly WorkflowSourceAssetMount[];
+};
+export type SendMultiStepDeployFrameArgs = SourceRefDeployFrameArgs;
+/**
+ * Emit the source-ref deploy frame onto `SidecarRouter.sendAgentDeploy`. The
+ * router accepts an optional `workflow` projection on the deploy frame; the
+ * sidecar's deploy router uses field presence to route the frame to the
+ * workflow deploy path, and returns the supervisor public key on the
+ * `agent.deploy.ack`.
+ *
+ * The gate/freeze layer already hashed the inert projection, so the frozen hash
+ * and the inert projection ride the frame verbatim -- this never recomputes the
+ * content hash. Recomputing over a live wire lineage would diverge from the
+ * inert projection the child re-verifies against.
+ *
+ * Exported so the co-located caller-site test can assert that the constructed
+ * closure reaches the wire surface via `sendAgentDeploy` with a `workflow`
+ * field structurally matching the `AgentDeployFrame.workflow` schema.
+ */
+export declare function sendMultiStepDeployFrame(args: SendMultiStepDeployFrameArgs, signal?: AbortSignal, beforeSend?: () => Promise<void>): Promise<{
+    publicKey: string;
+}>;
+/**
+ * Arguments for `deployCodeSourcedWorkflow`. The `approved` bundle is the
+ * `installAndApproveWorkflowDefinition` output verbatim -- the frozen hash,
+ * inert projection, and closure travel together inside it so no caller can pair
+ * a hash with a mismatched projection or closure. The remaining fields are the
+ * operator/asset config the approve step never sees: the per-step inference
+ * `sources`, the deploy `config`, the target `agentAddress`, and the `source`
+ * ref that names where the definition's bytes are published.
+ */
+type DeployCodeSourcedCommonArgs = DeployFrameCommonArgs & {
+    approved: InstallAndApproveResult;
+    /**
+     * The hub DB handle, the definition's OWN tenant, the deployment's anchor run
+     * id, and the mail domain its run address lives under. REQUIRED: this function
+     * writes the deployment's anchor `workflow_run` row, and run-grant
+     * materialization keys off it. `tenantId` is the definition's own tenant
+     * (tenant-owned credential resolution walks up from it); do not pass a
+     * request/config tenant that may differ. `anchorRunId` is caller-supplied: the
+     * deployment mail address is frozen into the approved package bytes at
+     * authoring time, so the run id it derives from is fixed before this runs and
+     * cannot be minted here. `deploymentDomain` pairs with `anchorRunId` to
+     * re-derive the run address and assert it matches `agentAddress`, failing
+     * closed on an incoherent pair.
+     */
+    db: DB["db"];
+    tenantId: string;
+    anchorRunId: string;
+    deploymentDomain: string;
+    /**
+     * Credential cipher, REQUIRED whenever the definition carries credential
+     * bindings OR any pinned inference source (top-level or inline body) references
+     * a credential; resolution fails closed without it. Omit only for a deploy with
+     * neither.
+     */
+    credentialCipher?: CredentialCipher;
+};
+/** Deploy a definition published to an npm registry: the sidecar fetches its
+ * tarballs over HTTP, so no source asset is delivered. */
+export type DeployCodeSourcedRegistryArgs = DeployCodeSourcedCommonArgs & {
+    source: WorkflowDefinitionRegistrySource;
+};
+/** Deploy a definition sourced from a hub `package-registry` asset: the caller
+ * mints `resolveAttachment` so this glue delivers the asset packs the sidecar
+ * checks out, without importing the asset service. */
+export type DeployCodeSourcedAssetArgs = DeployCodeSourcedCommonArgs & {
+    source: WorkflowDefinitionAssetSource;
+    resolveAttachment: ResolveAssetAttachmentFn;
+};
+export type DeployCodeSourcedWorkflowArgs = DeployCodeSourcedRegistryArgs | DeployCodeSourcedAssetArgs;
+/**
+ * A direct allocation-bound composition entrypoint for tests and low-level
+ * callers: prepare, INSERT the deployment's anchor `workflow_run` row, THEN emit
+ * the source-ref frame. The anchor row is the deployment's first-class record
+ * that owns its routing address and public key. Run-grant materialization keys
+ * off this row (address + live status), so WITHOUT it no per-run grants (tool,
+ * capability, OR credential) ever materialize for a source-ref deployment. Born
+ * "deployed" (live but pre-trigger) with a null public key: the first trigger's
+ * materialization flips it to "running" via `anchorWithPrincipal`'s guarded
+ * update, which a row born "running" would skip. Its `anchorRunId` equals its
+ * own id, so the anchor references itself. The deployer read grant is deferred
+ * to the production route, which carries the authenticated deployer principal.
+ *
+ * ORDERING IS LOAD-BEARING. The anchor row must be committed and visible to the
+ * pack-receipt connection BEFORE the frame reaches the wire: the frame spawns
+ * the child, whose first events pack races the ack back, and
+ * `receiveWorkflowRunPack` fails closed on a missing live anchor. Emitting first
+ * (the previous order) rejected that first pack and never bootstrapped the log.
+ * This works because `args.db` is the autocommit handle (`DB["db"]`, which the
+ * type forbids from being a transaction) and the INSERT is NOT wrapped in a
+ * transaction with the emit -- so the row is durably visible the instant the
+ * INSERT statement returns. Do NOT relax `db` to a transaction executor or wrap
+ * anchor+emit in one transaction to make them atomic: that reopens the race.
+ *
+ * On emit failure the anchor row is rolled back or fenced by the `frameSent`
+ * evidence from the transport. `leakedAgent: false` (safe to fully roll back) is
+ * the STRONG claim and is made only on positive proof the frame never reached
+ * the wire (`isDeployFrameFailure && frameSent === false`); every other failure
+ * -- a sent-but-unacked frame OR any untagged error -- is treated as
+ * possibly-live: the anchor is fenced `deployed` -> `failed` and the error is
+ * `leakedAgent: true`.
+ *
+ * The prepared provisioned path does NOT use this composition: its anchor row
+ * already exists from prepare time, so it drives `emitSourceRefDeployFrame` and
+ * an UPDATE-under-allocation-lock instead.
+ */
+export declare function deployCodeSourcedWorkflow(args: DeployCodeSourcedWorkflowArgs): Promise<{
     publicKey: string;
 }>;
-export declare function createSessionService(deps: SessionServiceDeps): SessionService;
+/** Resolve deferred sender mail after claiming the previous initializer's lease. */
+export declare function recoverSenderDeploy(args: {
+    db: DB["db"];
+    sidecarRouter: Pick<SidecarRouter, "noteSenderDeploySettled">;
+    allocation: SidecarAllocation;
+    reconciliation: SidecarReconciliationContext;
+}): Promise<void>;
+export declare function createSessionService(deps: SessionServiceDeps): SessionService & PreparedWorkflowDeployer;
+export {};