@opengeni/api-router 0.22.2 → 0.26.1

package/dist/routes/sessions.d.ts

@@ -1,7 +1,8 @@
-import { type SessionAuthorizationOperation } from "@opengeni/contracts";
+import { ClientSessionEvent, SteerSessionMessageRequest, type SessionAuthorizationOperation } from "@opengeni/contracts";
+import { type SessionDiscoveryCursor } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { type ViewerServices } from "../sandbox/viewer";
+import { type ViewerServices } from "../sandbox/viewer.js";
 type SessionRouteDeps = ApiRouteDeps & Pick<ViewerServices, "establishSandboxSession">;
 export declare function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void;
 /**
@@ -10,6 +11,20 @@ export declare function registerSessionRoutes(app: Hono, deps: SessionRouteDeps)
  * host-managed mode; standalone deployments never consult this classifier.
  */
 export declare function sessionAuthorizationOperationForHttp(method: string, pathname: string, sessionId: string): SessionAuthorizationOperation | null;
+export type AgentTopologyCursorEnvelope = {
+    cursor: SessionDiscoveryCursor;
+    parentSessionId: string | null;
+    search: string | null;
+};
+export declare function encodeAgentTopologyCursor(value: AgentTopologyCursorEnvelope): string;
+export declare function agentTopologyQuery(query: Record<string, string>): {
+    limit: number;
+    parentSessionId: string | null;
+    search: string | undefined;
+    cursor: SessionDiscoveryCursor | undefined;
+};
 /** Stable, value-free JSON errors for only the create-session boundary. */
 export declare function sessionCreateErrorResponse(c: Context, error: unknown): Response;
+export declare function parseSessionEventAdmission(raw: unknown): ClientSessionEvent;
+export declare function parseSteerSessionAdmission(raw: unknown): SteerSessionMessageRequest;
 export {};

package/dist/routes/skills.d.ts

@@ -0,0 +1,6 @@
+import { type ApiRouteDeps, type GitHubSkillSourceClient } from "@opengeni/core";
+import type { Hono } from "hono";
+export type SkillRouteOverrides = Readonly<{
+    github?: GitHubSkillSourceClient;
+}>;
+export declare function registerSkillRoutes(app: Hono, deps: ApiRouteDeps, overrides?: SkillRouteOverrides): void;

package/dist/routes/video-generation.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerVideoGenerationRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/sandbox/auth-callout.d.ts

@@ -4,6 +4,8 @@ import { type ResponderConnection } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
 /** The NATS subject nats-server publishes authorization requests on (ADR-26). */
 export declare const AUTH_CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH";
+/** Keep live NATS credentials short-lived while never outliving the bearer. */
+export declare const NATS_USER_JWT_TTL_SECONDS: number;
 export interface AuthCalloutDeps {
     db: Database;
     settings: Settings;

package/dist/sandbox/channel-a.d.ts

@@ -3,27 +3,73 @@ import type { Session } from "@opengeni/contracts";
 import { type Database, type LeaseSnapshot } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
 import { type Observability } from "@opengeni/observability";
-import { SandboxChannelAService, type RoutingSandboxSession } from "@opengeni/runtime/sandbox";
+import { SandboxChannelAService, type ChannelASession, type EstablishedSandboxSession, type RoutingSandboxSession } from "@opengeni/runtime/sandbox";
 export type ChannelAServices = {
     db: Database;
     settings: Settings;
     bus: EventBus;
     observability?: Observability | undefined;
 };
+export type ChannelAOperation = "fs.list" | "fs.list-batch" | "fs.read" | "fs.write" | "fs.delete" | "fs.move" | "fs.mkdir" | "git.status" | "git.diff" | "git.read-batch" | "git.log" | "git.show" | "terminal.exec" | "terminal.pty.open" | "terminal.pty.write" | "terminal.pty.resize" | "terminal.pty.close" | "browser.create" | "browser.resume" | "browser.suspend" | "browser.end" | "browser.read" | "browser.control" | "browser.attach" | "computer.create" | "computer.end" | "computer.read" | "computer.control" | "computer.attach";
 export type ChannelAContext = {
     accountId: string;
     workspaceId: string;
     session: Session;
     subjectId: string;
+    /** Cancel lifecycle waiting when the originating HTTP request disconnects. */
+    waitSignal?: AbortSignal | undefined;
+    /** Bounded route identity for metrics and safe operator diagnostics. */
+    operation?: ChannelAOperation | undefined;
+};
+export type ChannelAOperationFailureReason = "request_cancelled" | "provider_read_busy" | "provider_unavailable" | "lifecycle_conflict" | "request_rejected" | "unexpected";
+export type ChannelAOperationFailureDiagnostic = {
+    reason: ChannelAOperationFailureReason;
+    status: number;
+    errorCode: "sandbox_channel_a_cancelled" | "sandbox_channel_a_provider_busy" | "sandbox_channel_a_provider_unavailable" | "sandbox_channel_a_lifecycle_conflict" | "sandbox_channel_a_operation_failed";
 };
 export type ChannelAHandle = {
     service: SandboxChannelAService;
     /** Connected Machine homes deliberately have no cloud lease. Durable PTYs
      * require a real home-provider lease and reject this null case. */
     lease: LeaseSnapshot | null;
+    /** Exact placement-home session established under this request's lease or
+     * Connected Machine fence. Unlike routingSession, this never follows a later
+     * active-sandbox pointer and is safe for placement-bound controllers. */
+    homeSession: ChannelASession;
     routingSession: RoutingSandboxSession;
     requestId: string;
 };
+export type EstablishedHandleCacheKind = "read" | "process" | "none";
+export declare function isChannelAHandleCacheEntryFresh(lastUsedAtMonotonicMs: number, nowMonotonicMs: number, idleTtlMs?: number): boolean;
+export declare function isChannelAProcessHandleCacheEntryFresh(lastUsedAtMonotonicMs: number, nowMonotonicMs: number, idleTtlMs?: number): boolean;
+/** Reuse the exact lease-fenced provider handle across API-direct surfaces.
+ * Stream capability negotiation and the first Files/Changes reads commonly run
+ * back-to-back; sharing this handle avoids paying the same Modal resume twice. */
+export declare function establishCachedChannelAHandle(workspaceId: string, sessionId: string, lease: LeaseSnapshot, establish: () => Promise<EstablishedSandboxSession>): Promise<EstablishedSandboxSession>;
+/**
+ * Run independent, side-effect-free Channel-A reads concurrently without
+ * releasing the direct-request holder while sibling provider commands are
+ * still settling. A typed temporary-unavailable failure is retried exactly
+ * once after every first attempt has settled; validation, conflict, not-found,
+ * and unknown failures are never replayed.
+ */
+export declare function runConcurrentChannelAReads<T>(operations: readonly (() => Promise<T>)[]): Promise<T[]>;
+type ChannelAReadRecoveryOptions = {
+    /** Modal may expose one more stale command-router route after the first
+     * successful handle rebuild. Keep this closed and statically bounded. */
+    maxFreshHandleRetries?: 1 | 2;
+    /** Never start another provider attempt after the originating request ends. */
+    waitSignal?: AbortSignal | undefined;
+};
+/** Retry a side-effect-free Channel-A read only after the caller has discarded
+ * and freshly re-established its provider handle. The ordinary provider-neutral
+ * contract allows one retry; Modal opts into one additional rebuild because a
+ * command-router rollover can outlive the first replacement handle. Provider
+ * commands are never replayed for validation/conflict/unknown errors, mutation
+ * routes never call this helper, and request cancellation stops recovery before
+ * another provider command begins. */
+export declare function runChannelAReadWithFreshHandleRetry<T>(run: () => Promise<T>, refreshHandle: (attempt: 1 | 2) => Promise<void>, options?: ChannelAReadRecoveryOptions): Promise<T>;
+export declare function shouldEvictChannelAHandleAfterError(error: unknown, cacheKind: EstablishedHandleCacheKind): boolean;
 /**
  * Run a Channel-A op against a live box, API-direct. Acquires an exact direct holder
  * (warming the box when cold), resumes by id, builds the service, runs `fn`, and
@@ -34,6 +80,17 @@ export type ChannelAHandle = {
  * otherwise). A `backend:none` session has no box -> 409 before touching it.
  */
 export declare function withChannelA<T>(services: ChannelAServices, ctx: ChannelAContext, fn: (handle: ChannelAHandle) => Promise<T>): Promise<T>;
+/** Read-only API-direct seam. Separate requests for the same exact live Modal
+ * instance are serialized across API replicas; each request's batched reads
+ * remain concurrent behind that one distributed boundary. A typed temporary
+ * provider-channel failure gets one retry only after rebuilding the exact
+ * lease-fenced handle. */
+export declare function withChannelARead<T>(services: ChannelAServices, ctx: ChannelAContext, fn: (handle: ChannelAHandle) => Promise<T>): Promise<T>;
 /** Map the service's typed errors to HTTP status (the §5.3 matrix). Re-throws an
  *  already-HTTPException unchanged. */
-export declare function mapChannelAError(error: unknown): unknown;
+export declare function mapChannelAError(error: unknown, waitSignal?: AbortSignal): unknown;
+export declare function isChannelARequestCancellation(error: unknown, waitSignal?: AbortSignal): boolean;
+/** Structural classification only: exact provider exception text, codes, URLs,
+ * and identifiers never cross the telemetry boundary. */
+export declare function channelAOperationFailureDiagnostic(error: unknown, waitSignal?: AbortSignal): ChannelAOperationFailureDiagnostic;
+export {};

package/dist/sandbox/metrics-ingestion.d.ts

@@ -1,7 +1,8 @@
 import { type Database, type MachineMetricsSample } from "@opengeni/db";
+import { type AttachedBrowserInventorySnapshot as AttachedBrowserInventoryContractValue } from "@opengeni/contracts";
 import { type EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
-import { Hello, type MetricsSample } from "@opengeni/agent-proto";
+import { Hello, type AttachedBrowserInventorySnapshot as WireAttachedBrowserInventorySnapshot, type MetricsSample } from "@opengeni/agent-proto";
 /** The wildcard subject the agent event plane publishes heartbeats on. */
 export declare const AGENT_EVENTS_SUBJECT = "agent.*.*.events";
 /** The wildcard subject the agent publishes its connect Hello on. */
@@ -27,6 +28,10 @@ export declare function parseAgentHelloSubject(subject: string): {
  * GPU plane; cpu/mem/disk 0 is a legitimate reading the dashboard shows as 0).
  */
 export declare function wireSampleToDbSample(wire: MetricsSample): MachineMetricsSample;
+/** Validate and project one wire inventory before it reaches durable browser
+ *  discovery. Unknown enum values and unsafe uint64 counters reject the whole
+ *  authoritative snapshot instead of partially disconnecting good endpoints. */
+export declare function wireAttachedBrowserInventoryToContract(wire: WireAttachedBrowserInventorySnapshot): AttachedBrowserInventoryContractValue;
 /**
  * Ingest ONE decoded heartbeat for an enrolled machine. Resolves the enrollment's
  * accountId (needed for the RLS-scoped writes) from the enrollment row; an

package/dist/sandbox/viewer.d.ts

@@ -65,6 +65,8 @@ export declare function attachViewer(services: ViewerServices, input: {
     workspaceId: string;
     session: Session;
     viewerId?: string;
+    /** Cancel lifecycle waiting when the originating HTTP request disconnects. */
+    waitSignal?: AbortSignal;
 }): Promise<ViewerAttachResult>;
 export type SessionGroupReadinessHold = {
     lease: LeaseSnapshot;
@@ -149,7 +151,7 @@ export type MintDesktopStreamInput = {
     session: Session;
     /** The viewer holder id the scoped token is minted for. */
     viewerId: string;
-    /** The live lease (must be warm/draining — the box is up). A selfhosted-active
+    /** The live lease (must be holder-confirmed warm). A selfhosted-active
      *  session may have no Modal group lease; omit and the selfhosted branch handles it. */
     lease?: LeaseSnapshot;
     /** The epoch the CALLER last observed the URL minted under. When the live
@@ -196,7 +198,7 @@ export type MintTerminalStreamInput = {
     session: Session;
     /** The viewer holder / principal id the scoped token is minted for. */
     viewerId: string;
-    /** The live lease (must be warm/draining — the box is up). A selfhosted-active
+    /** The live lease (must be holder-confirmed warm). A selfhosted-active
      *  session may have no Modal group lease; omit and the selfhosted branch handles it. */
     lease?: LeaseSnapshot;
     /** Test seam: override how the box is re-established by id (see

package/dist/temporal-schedule-cleanup.d.ts

@@ -0,0 +1,26 @@
+import { type Database, type TemporalScheduleCleanupClaim } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+type TemporalScheduleCleanupDependencies = {
+    db: Database;
+    deleteSchedule: (temporalScheduleId: string) => Promise<void>;
+    observability?: Pick<Observability, "info" | "warn" | "error">;
+};
+export type TemporalScheduleCleanupBatchResult = {
+    claimed: number;
+    deleted: number;
+    failed: number;
+    stale: number;
+};
+/** Settle exact claims concurrently; every external delete is idempotent. */
+export declare function processTemporalScheduleCleanupClaims(deps: TemporalScheduleCleanupDependencies, claims: readonly TemporalScheduleCleanupClaim[]): Promise<TemporalScheduleCleanupBatchResult>;
+/** Claim and process one globally bounded batch. */
+export declare function drainTemporalScheduleCleanupOutbox(deps: TemporalScheduleCleanupDependencies): Promise<TemporalScheduleCleanupBatchResult>;
+/**
+ * Start one non-overlapping reconciliation loop. PostgreSQL claims coordinate
+ * replicas; an API crash merely delays the exact row until its short claim
+ * expires.
+ */
+export declare function startTemporalScheduleCleanupPump(deps: TemporalScheduleCleanupDependencies, options?: {
+    intervalMs?: number;
+}): () => Promise<void>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.22.2",
+  "version": "0.26.1",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,25 +41,30 @@
     "@aws-sdk/client-s3": "^3.1044.0",
     "@aws-sdk/s3-request-presigner": "^3.1044.0",
     "@hono/zod-validator": "^0.7.6",
+    "@llamaindex/liteparse": "^1.5.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.3.0",
-    "@opengeni/codex": "^0.2.11",
-    "@opengeni/config": "^0.11.0",
-    "@opengeni/contracts": "^0.39.0",
-    "@opengeni/core": "^0.21.2",
-    "@opengeni/db": "^0.28.1",
-    "@opengeni/documents": "^0.5.10",
-    "@opengeni/events": "^0.3.80",
-    "@opengeni/github": "^0.4.31",
-    "@opengeni/network": "^0.2.0",
-    "@opengeni/observability": "^0.5.0",
-    "@opengeni/runtime": "^0.18.17",
-    "@opengeni/storage": "^0.2.68",
+    "@opengeni/agent-proto": "^0.4.0",
+    "@opengeni/artifact-tool": "^0.2.2",
+    "@opengeni/capabilities": "^0.1.1",
+    "@opengeni/codemode": "^0.2.2",
+    "@opengeni/codex": "^0.2.15",
+    "@opengeni/config": "^0.13.2",
+    "@opengeni/contracts": "^0.44.1",
+    "@opengeni/core": "^0.24.1",
+    "@opengeni/db": "^0.31.1",
+    "@opengeni/documents": "^0.5.32",
+    "@opengeni/events": "^0.3.103",
+    "@opengeni/github": "^0.4.50",
+    "@opengeni/network": "^0.2.2",
+    "@opengeni/observability": "^0.6.2",
+    "@opengeni/runtime": "^0.19.2",
+    "@opengeni/storage": "^0.2.87",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",
     "pg": "^8.21.0",
     "resend": "^6.12.4",
+    "sharp": "^0.34.5",
     "stripe": "^22.2.0",
     "zod": "^4.2.1"
   },