@intx/hub-sessions 0.2.2 → 0.3.0

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

@@ -5,13 +5,131 @@ export type HubSessionLookupsDeps = {
     db: DB["db"];
     agentRepoStore: AgentRepoStore;
 };
-export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<SidecarLookups>;
+export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<Omit<SidecarLookups, "materializeMailTriggeredRunGrants">>;
 /**
- * Extract the instance id from an `<instanceId>@<domain>` agent address.
- * Throws on any input the `@intx/types`-owned `parseAgentAddress`
- * rejects: missing or leading `@`, empty domain, or an instance id
- * without the canonical `ins_` prefix.
+ * Extract the run id from an `<runId>@<domain>` run address.
+ * Throws on any input the `@intx/types`-owned `parseRunAddress`
+ * rejects: missing or leading `@`, empty domain, or a run id
+ * without the canonical `run_` prefix.
  */
 export declare function parseAgentId(agentAddress: string): string;
-export declare function findInstance(db: DB["db"], agentAddress: string): Promise<Awaited<ReturnType<typeof db.query.agentInstance.findFirst>>>;
-export declare function requireInstance(db: DB["db"], agentAddress: string): Promise<NonNullable<Awaited<ReturnType<typeof db.query.agentInstance.findFirst>>>>;
+/**
+ * A live routing endpoint backing a run address. Each address names one
+ * self-anchored `workflow_run`, so the endpoint is always that run.
+ */
+export interface RoutableEndpoint {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly address: string;
+    readonly publicKey: string | null;
+    /**
+     * The endpoint's raw run status. Resolution is `endedAt`-filtered, so a
+     * resolved endpoint is not necessarily live: a leaked run is deliberately
+     * kept routable (terminal status, null `endedAt`) to stay reachable, and the
+     * reconnect reaction reads this to keep such an endpoint routable without
+     * restoring a collector.
+     */
+    readonly status: string;
+    /**
+     * The live session backing this endpoint. A folded run has no session column,
+     * so this is the run's not-yet-ended `agent_session`, keyed by the run's
+     * principal. Transitional -- it retires when mail record-keeping moves off
+     * `agent_session`.
+     */
+    readonly sessionId: string | null;
+}
+/**
+ * Resolve a run address to the `workflow_run` endpoint backing it, keyed by
+ * the run's `address`. Every routable address names one self-anchored run --
+ * the deployment's anchor -- so this resolves the run's own address (the
+ * source `persistMail` depends on to record a triggered deployment's mail).
+ */
+export declare function resolveRoutableAddress(db: DB["db"], address: string): Promise<RoutableEndpoint | undefined>;
+/**
+ * A folded run has no session column; its session is the `agent_session` keyed
+ * by the run's principal. By default this is the live (not-yet-ended) session,
+ * matching routing semantics; `includeEnded` also resolves a stopped run's
+ * ended session, which mail history needs. Returns null when the run has no
+ * principal or no matching session. Transitional, alongside
+ * `RoutableEndpoint.sessionId`.
+ */
+export declare function resolveRunSessionId(db: DB["db"], principalId: string | null, opts?: {
+    includeEnded?: boolean;
+}): Promise<string | null>;
+/**
+ * The folded run that owns a session, or null when the session belongs to no
+ * run. This is the inverse of `resolveRunSessionId`: a mail-read path holds a
+ * `sessionMail.sessionId` and no address, so it recovers the owning run by
+ * joining `workflow_run` to `agent_session` on their shared principal (a folded
+ * run, its session, and its launch all key on the same `instancePrincipalId`).
+ * Scoped to the tenant and routed through `workflow_run` so the returned id is
+ * proven to name a real run of this tenant -- callers key an authorization
+ * subject on it, so a session held by a non-run principal must fail closed to
+ * null rather than resolve to a fabricated subject.
+ */
+export declare function resolveRunIdForSession(db: DB["db"], sessionId: string, tenantId: string): Promise<string | null>;
+/**
+ * A folded run resolved BY ID for the instance read/interact surface, shaped
+ * into one instance-shaped record. Unlike `resolveRoutableAddress` (keyed by
+ * address, live-only), this is keyed by the path id and does NOT filter
+ * terminated rows -- a stopped run's detail, mail history, and turns are still
+ * served. Keep the two separate: routing must never reach a dead endpoint,
+ * while the read surface must still render one.
+ */
+export interface RoutableRecord {
+    readonly id: string;
+    readonly tenantId: string;
+    /** The routing address. Non-null: a run resolves here only when it owns an
+     * address. */
+    readonly address: string;
+    readonly publicKey: string | null;
+    /** Raw run status. The wire mapping onto the instance status enum is a
+     * hub-api concern, done by the response shaper. */
+    readonly status: string;
+    readonly createdAt: Date;
+    /** A run has no `updatedAt` column, so it reports `endedAt ?? createdAt`. */
+    readonly updatedAt: Date;
+    readonly endedAt: Date | null;
+    /** The folded definition this run belongs to (`workflow_definition.id`). */
+    readonly definitionId: string;
+    readonly principalId: string | null;
+    readonly kernelId: string | null;
+    readonly sidecarId: string | null;
+}
+/**
+ * Shape a run row and its already-resolved routing address into the run
+ * record. Callers decide whether the run resolves at all -- only a top-level
+ * run (`isTopLevelRun`) does -- and pass the address they have narrowed; this
+ * only maps the columns, including the run's `endedAt ?? createdAt` stand-in
+ * for the absent `updatedAt`.
+ */
+export declare function runRowToRoutableRecord(run: {
+    id: string;
+    tenantId: string;
+    publicKey: string | null;
+    status: string;
+    createdAt: Date;
+    endedAt: Date | null;
+    definitionId: string;
+    principalId: string | null;
+    kernelId: string | null;
+    sidecarId: string | null;
+}, address: string): RoutableRecord;
+/**
+ * A run is a top-level run -- the addressable head of a deployment -- when it
+ * owns a routing address AND self-anchors (`anchorRunId === id`). A lazy child
+ * park row anchors on its parent (`anchorRunId !== id`) and carries no address;
+ * either condition excludes it. This is the single predicate the run read
+ * surface classifies on, so the resolver and the run list cannot drift.
+ */
+export declare function isTopLevelRun(row: {
+    id: string;
+    address: string | null;
+    anchorRunId: string | null;
+}): boolean;
+/**
+ * Resolve a run id to its record. A run resolves only when it is a top-level
+ * run (`isTopLevelRun`): it owns a routing address and self-anchors. A child
+ * park row (address-null, anchored on its parent) is not served here.
+ */
+export declare function findRoutableById(db: DB["db"], id: string, tenantId: string): Promise<RoutableRecord | undefined>;