@intx/hub-sessions 0.1.2 → 0.2.2

package/dist/session-service.d.ts

@@ -0,0 +1,235 @@
+import { type DB } from "@intx/db";
+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 WorkflowDefinition } from "@intx/workflow/definition";
+import { type DeployContent as OrchestratorDeployContent, type DeploySingleStepFn } 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";
+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;
+        instanceId: string;
+        config: HarnessConfig;
+        deployContent: DeployContent;
+        toolPackagePins?: readonly ToolPackagePin[];
+    }): 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;
+    /** 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;
+    tenantId: string;
+    cryptoProvider: CryptoProvider;
+};
+export type SessionServiceDeps = {
+    sidecarRouter: SidecarRouter;
+    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;
+/**
+ * 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;
+    agentAddress: string;
+    config: HarnessConfig;
+    definition: WorkflowDefinition;
+    sources: Record<string, InferenceSource[]>;
+}): Promise<{
+    publicKey: string;
+}>;
+export declare function createSessionService(deps: SessionServiceDeps): SessionService;