@intx/hub-sessions 0.3.0 → 0.4.0

package/dist/session-service.d.ts

@@ -1,7 +1,7 @@
-import { type DB } from "@intx/db";
+import { type DB, type SidecarAllocation } from "@intx/db";
 import type { CredentialDelivery } from "@intx/types/sidecar";
 import type { CredentialCipher } from "@intx/types";
-import type { CryptoProvider, HarnessConfig, InferenceSource, MessageAttachment } from "@intx/types/runtime";
+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 { SourceRefPin, WorkflowProjectionWithSources, WorkflowSourceAssetMount } from "@intx/types/sidecar";
@@ -9,9 +9,10 @@ import type { WorkflowDefinitionAssetSource, WorkflowDefinitionRegistrySource, W
 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 { AllocatedSidecarTarget, SidecarAllocationRouter, 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;
@@ -36,35 +37,8 @@ export type SessionService = {
         config: HarnessConfig;
         deployContent: DeployContent;
         toolPackagePins?: readonly ToolPackagePin[];
-        allocationTarget?: AllocatedSidecarTarget;
+        allocationTarget: AllocatedSidecarTarget;
     }): Promise<void>;
-    /**
-     * Deploy a CODE-SOURCED workflow definition end to end: install + probe +
-     * gate + freeze (`approve-probed`), then deploy the frozen definition by
-     * source-ref. This is the general workflow deploy entry point the
-     * `POST /deployments` route drives; it never hydrates a live definition from a
-     * static `workflow.json`.
-     *
-     * The service owns the source-read wiring (`repoStore` committed reads and
-     * asset pack fan-out) and the registry configuration, so the caller passes
-     * only the deploy intent: where the definition's bytes come from
-     * (`source`/`entry`/`pin`), the `workflow`-kind asset the definition projects
-     * over (`definitionAssetId`), and the shared harness config. The method
-     * dispatches on `source.kind`/`source.package.format` to build the install
-     * args, pins every top-level step's inference source under the frozen
-     * approval, and persists the deployment's anchor run.
-     *
-     * Persists the deployment's anchor `workflow_run` (id = `anchorRunId`) via
-     * `deployCodeSourcedWorkflow`, so the deployment is listable per tenant.
-     * Returns the supervisor's principal public key from the sidecar deploy ack.
-     */
-    deployWorkflowFromSource(params: DeployWorkflowFromSourceParams): 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.
      */
@@ -78,50 +52,11 @@ export type DeployWorkflowDefinitionResult = {
     /** Supervisor principal public key from the sidecar's deploy ack. */
     publicKey: string;
 };
-export type DeployWorkflowFromSourceParams = {
-    /** Owning tenant; recorded on the deployment's anchor run. */
-    tenantId: string;
-    /**
-     * Stable deployment identifier and anchor-run id. The deployment-level
-     * address derives from it; the caller owns its generation.
-     */
-    anchorRunId: string;
-    /** Mail domain the deployment's derived addresses live under. */
-    deploymentDomain: string;
-    /**
-     * The deployment-level mail address, derived by the caller from `anchorRunId`
-     * + `deploymentDomain`. Re-derived and asserted coherent inside
-     * `deployCodeSourcedWorkflow`.
-     */
-    agentAddress: string;
-    /** Where the definition's bytes come from at apply 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 (the pin selects the member); omitted for the
-     * asset-`source` variant, whose member is selected by `package.packageName`.
-     */
-    pin?: string;
-    /**
-     * The `workflow`-kind asset the frozen definition projects a
-     * `workflow_definition` over. Distinct from a `source.kind === "asset"`
-     * source's `assetId`, which names where the bytes live.
-     */
-    definitionAssetId: string;
-    /**
-     * Harness config shared across the deployment. Its `sources`/`defaultSource`
-     * are the operator-supplied inference chain; the method pins each top-level
-     * step to one approved source from it.
-     */
-    config: HarnessConfig;
-};
 /**
  * Install/probe/gate/freeze inputs for a code-sourced workflow, DECOUPLED from
- * deploy. The exclusive prepare path calls this on shared capacity at request
- * time to freeze the approval, persists the frozen bundle, and deploys it to a
- * dedicated allocation later with no re-probe.
+ * 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. */
@@ -135,6 +70,10 @@ export type InstallAndApproveWorkflowSourceParams = {
     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
@@ -160,13 +99,15 @@ export type DeployPreparedCodeSourcedWorkflowParams = {
     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 on shared
-     * capacity, returning the frozen bundle WITHOUT deploying it. The exclusive
+     * 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`.
      */
@@ -179,22 +120,9 @@ export type PreparedWorkflowDeployer = {
      */
     deployPreparedCodeSourcedWorkflow(params: DeployPreparedCodeSourcedWorkflowParams): Promise<DeployWorkflowDefinitionResult>;
 };
-export type UserMessageParams = {
-    agentAddress: string;
-    from: string;
-    messageId: string;
-    date: Date;
-    content: string;
-    attachments?: MessageAttachment[];
-    inReplyTo?: string;
-    references?: string[];
-    sessionId: string;
-    tenantId: string;
-    cryptoProvider: CryptoProvider;
-};
 export type SessionServiceDeps = {
     sidecarRouter: SidecarRouter;
-    /** Present when this Hub can route deploy phases to exclusive allocations. */
+    /** Present when this Hub can route deploy phases to provisioned allocations. */
     sidecarAllocationRouter?: SidecarAllocationRouter;
     agentRepoStore: AgentRepoStore;
     /**
@@ -258,9 +186,8 @@ export type SessionServiceDeps = {
 export declare function bridgeOrchestratorDeployContent(content: OrchestratorDeployContent): DeployContent;
 /** Fields the deploy frame carries onto `sendAgentDeploy`. */
 type DeployFrameCommonArgs = {
-    sidecarRouter: SidecarRouter;
-    sidecarAllocationRouter?: SidecarAllocationRouter;
-    allocationTarget?: AllocatedSidecarTarget;
+    sidecarAllocationRouter: SidecarAllocationRouter;
+    allocationTarget: AllocatedSidecarTarget;
     agentAddress: string;
     config: HarnessConfig;
     sources: Record<string, InferenceSource[]>;
@@ -303,8 +230,8 @@ export type SourceRefDeployFrameArgs = DeployFrameCommonArgs & {
      * 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
-     * stages each body's `sources.json` (and re-verify hash). Absent when the
-     * projection has no inline onTrigger body.
+     * 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[];
     /**
@@ -332,7 +259,7 @@ export type SendMultiStepDeployFrameArgs = SourceRefDeployFrameArgs;
  * closure reaches the wire surface via `sendAgentDeploy` with a `workflow`
  * field structurally matching the `AgentDeployFrame.workflow` schema.
  */
-export declare function sendMultiStepDeployFrame(args: SendMultiStepDeployFrameArgs): Promise<{
+export declare function sendMultiStepDeployFrame(args: SendMultiStepDeployFrameArgs, signal?: AbortSignal, beforeSend?: () => Promise<void>): Promise<{
     publicKey: string;
 }>;
 /**
@@ -364,19 +291,12 @@ type DeployCodeSourcedCommonArgs = DeployFrameCommonArgs & {
     anchorRunId: string;
     deploymentDomain: string;
     /**
-     * Credential cipher, REQUIRED only when the definition carries credential
-     * bindings (resolution fails closed without it); omit for a binding-free
-     * deployment.
+     * 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;
-    /**
-     * Present only for a prepared exclusive deploy: route the source-ref frame to
-     * this dedicated allocation instead of the shared router. `sidecarAllocationRouter`
-     * carries the allocation transport and is REQUIRED whenever `allocationTarget`
-     * is set. A shared deploy omits both.
-     */
-    allocationTarget?: AllocatedSidecarTarget;
-    sidecarAllocationRouter?: SidecarAllocationRouter;
 };
 /** Deploy a definition published to an npm registry: the sidecar fetches its
  * tarballs over HTTP, so no source asset is delivered. */
@@ -392,25 +312,50 @@ export type DeployCodeSourcedAssetArgs = DeployCodeSourcedCommonArgs & {
 };
 export type DeployCodeSourcedWorkflowArgs = DeployCodeSourcedRegistryArgs | DeployCodeSourcedAssetArgs;
 /**
- * The single public composition entrypoint for a SHARED code-sourced (npm)
- * deploy: emit the source-ref frame, then INSERT the deployment's anchor
- * `workflow_run` row -- 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): 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; this stays a
- * single insert with no grant row to pair atomically.
+ * 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.
  *
- * The prepared exclusive path does NOT use this wrapper: its anchor row already
- * exists from prepare time, so it wraps `emitSourceRefDeployFrame` with an
- * UPDATE-under-allocation-lock instead of this INSERT.
+ * 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;
 }>;
+/** 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 {};