@intx/hub-sessions 0.1.2 → 0.3.0

package/dist/session-service.d.ts

@@ -0,0 +1,416 @@
+import { type DB } 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 RegistryConfig, type ScopeRoute } from "@intx/tool-packaging";
+import { type ToolPackagePin } from "@intx/types/tool-packages";
+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 { AllocatedSidecarTarget, SidecarAllocationRouter, SidecarRouter } from "./ws/sidecar-handler.js";
+import { type ResolveAssetAttachmentFn } from "./workflow-closure-resolution.js";
+import { type InstallAndApproveResult } from "./workflow-probe-gate.js";
+export declare class SessionLaunchError extends Error {
+    /** Which phase failed: "write", "provision", "pack", or "start". */
+    readonly phase: string;
+    /** True if the sidecar has a provisioned agent that could not be cleaned up. */
+    readonly leakedAgent: boolean;
+    constructor(phase: string, cause: unknown, leakedAgent: boolean);
+}
+export type SessionService = {
+    /**
+     * Stage one step of a multi-step workflow deploy: bind a transient route
+     * for the step address, fire a no-spawn provision frame (init the step's
+     * agent-state repo and record the hub key), deliver the deploy + asset
+     * packs, and unbind the route -- no warm harness. The multi-step branch
+     * stages every step this way before firing the deployment-level workflow
+     * frame that spawns the supervised child; the child reads each staged step
+     * tree from disk and runs the step itself.
+     */
+    stageWorkflowStep(params: {
+        agentAddress: string;
+        agentId: string;
+        runId: string;
+        config: HarnessConfig;
+        deployContent: DeployContent;
+        toolPackagePins?: readonly ToolPackagePin[];
+        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.
+     */
+    endSession(agentAddress: string, reason: string): Promise<void>;
+};
+export type DeployWorkflowDefinitionResult = {
+    /** Echoes the deployment id recorded on the projection row. */
+    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 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.
+ */
+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;
+};
+/**
+ * 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;
+    /** 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;
+    /** 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
+     * 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 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. */
+    sidecarAllocationRouter?: SidecarAllocationRouter;
+    agentRepoStore: AgentRepoStore;
+    /**
+     * Optional asset attachment integration. When set, the deploy flow
+     * fans out per-attachment packs after the deploy pack lands and
+     * inserts a `session_asset` row per attachment. When unset, only
+     * the deploy pack is sent — the single-pack path is preserved
+     * bit-for-bit.
+     */
+    assetService?: AssetService;
+    /** DB handle used for `session_asset` manifest inserts. Required
+     * iff `assetService` is set. */
+    db?: DB["db"];
+    /**
+     * Tool-package registry configuration. Required iff any agent the
+     * service launches has non-empty `toolPackagePins`. When set, the
+     * service builds a per-agent `ClosureResolver` at launch time: the
+     * registry map combines (a) every `package-registry` asset visible
+     * to the agent's tenant via the INTR-178 walker — keyed by
+     * `asset.name` — and (b) the statically-configured HTTP registries
+     * in `httpRegistries`.
+     *
+     * **Name-collision policy.** When an asset and an HTTP registry
+     * both claim the same registry name, the asset wins. This mirrors
+     * the inner-shadows-outer rule the tenancy walker already applies
+     * to asset resolution and gives operators a single mental model:
+     * closer-scope shadows wider-scope. The rule is a contract this
+     * service guarantees, not an iteration-order accident — consumers
+     * may rely on it to override a wider-scope HTTP registry by
+     * publishing an asset at a closer tenancy.
+     *
+     * `defaultRegistry` names the entry the resolver consults for any
+     * package whose scope does not match `scopeRouting`. The name must
+     * resolve in the combined map for the given agent — if no asset and
+     * no HTTP entry carries that name, launch fails at the
+     * registry-resolution step.
+     */
+    toolPackageRegistries?: {
+        /**
+         * Registry identifier → registry config. The key is the
+         * identifier `scopeRouting` entries and manifest `registry`
+         * references point at; the value carries url plus optional auth.
+         */
+        readonly httpRegistries: ReadonlyMap<string, RegistryConfig>;
+        readonly defaultRegistry: string;
+        readonly scopeRouting?: readonly ScopeRoute[];
+    };
+};
+/**
+ * Translate the orchestrator's structural `DeployContent` (which types
+ * `toolPackageManifest` as `unknown`) back into the hub-sessions
+ * `DeployContent` shape. The orchestrator round-trips whatever the
+ * caller supplied, but the surface type widens `toolPackageManifest` to
+ * `unknown`; the validator narrows it back to the canonical shape
+ * `agentRepoStore.writeDeployTree` consumes.
+ *
+ * Exported so a test fixture that forwards orchestrator-shaped deploy
+ * content into `launchSession` narrows it the same validated way the
+ * production multi-step callback does, rather than casting `unknown`.
+ */
+export declare function bridgeOrchestratorDeployContent(content: OrchestratorDeployContent): DeployContent;
+/** Fields the deploy frame carries onto `sendAgentDeploy`. */
+type DeployFrameCommonArgs = {
+    sidecarRouter: SidecarRouter;
+    sidecarAllocationRouter?: SidecarAllocationRouter;
+    allocationTarget?: AllocatedSidecarTarget;
+    agentAddress: string;
+    config: HarnessConfig;
+    sources: Record<string, InferenceSource[]>;
+};
+/**
+ * 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
+     * stages each body's `sources.json` (and re-verify 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): 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 only when the definition carries credential
+     * bindings (resolution fails closed without it); omit for a binding-free
+     * deployment.
+     */
+    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. */
+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;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function deployCodeSourcedWorkflow(args: DeployCodeSourcedWorkflowArgs): Promise<{
+    publicKey: string;
+}>;
+export declare function createSessionService(deps: SessionServiceDeps): SessionService & PreparedWorkflowDeployer;
+export {};