@opengeni/api-router 4.1.0 → 4.1.2-canary.36079201993001

package/src/routes/knowledge.ts

@@ -18,6 +18,8 @@ import {
   prepareKnowledgeFile,
   prepareKnowledgeSave,
   searchKnowledgeEntries,
+  KnowledgeVectorFundingError,
+  KnowledgeVectorQueryRejectedError,
   hasPermission,
   knowledgeContextForAccess,
   requireAccessGrantAuthorization,
@@ -47,6 +49,7 @@ import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
 import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
+import { ApiHttpError } from "../http/api-error";
 
 const ReadSettings = z
   .object({
@@ -63,6 +66,18 @@ const WriteSettings = ReadSettings.extend({
 const Id = z.uuid();
 function knowledgeHttpError(error: unknown): never {
   if (error instanceof HTTPException) throw error;
+  if (error instanceof KnowledgeVectorFundingError)
+    throw new ApiHttpError(402, {
+      code: "payment_required",
+      message: error.message,
+      details: { code: error.code, keywordAvailable: true },
+    });
+  if (error instanceof KnowledgeVectorQueryRejectedError)
+    throw new ApiHttpError(error.code === "quota" ? 429 : 422, {
+      code: error.code === "quota" ? "limit_exceeded" : "validation_failed",
+      message: error.message,
+      details: { code: error.code, keywordAvailable: true },
+    });
   if (error instanceof z.ZodError)
     throw new HTTPException(422, {
       message: error.issues[0]?.message ?? "Invalid Knowledge request",
@@ -216,6 +231,8 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
           context,
           KnowledgeSavePreparationRequest.parse(await c.req.json()),
           () => deps.getDocumentServices().embedder,
+          undefined,
+          deps.settings,
         ),
       );
     }),
@@ -228,6 +245,7 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
           context,
           KnowledgeEntryListRequest.parse(await c.req.json()),
           () => deps.getDocumentServices().embedder,
+          deps.settings,
         ),
       ),
     ),
@@ -270,6 +288,7 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
             ...(query.limit ? { limit: Number(query.limit) } : {}),
           }),
           () => deps.getDocumentServices().embedder,
+          deps.settings,
         ),
       );
     }),

package/src/routes/managed-onboarding.ts

@@ -77,6 +77,9 @@ export function registerManagedOnboardingRoutes(
             organizationName,
             operationId: parsed.data.operationId,
             requestFingerprint,
+            trialCreditsEnabled:
+              deps.settings.productAccessMode === "managed" &&
+              deps.settings.verifiedSignupTrialCreditsEnabled,
           }),
         ),
       );

package/src/routes/organization-memberships.ts

@@ -237,6 +237,9 @@ export function registerOrganizationMembershipRoutes(app: Hono, deps: ApiRouteDe
             subjectId,
             subjectLabel: session.user.email || session.user.name,
             ...payload,
+            trialCreditsEnabled:
+              deps.settings.productAccessMode === "managed" &&
+              deps.settings.verifiedSignupTrialCreditsEnabled,
           }),
         ),
         201,

package/src/routes/sessions.ts

@@ -1,5 +1,8 @@
 import { getRetainedProviderCommand } from "@opengeni/db/retained-provider-commands";
 import { searchSessionMessagesForSubject, SessionMessageSearchCursorError } from "@opengeni/db";
+import { listSessionEventSlices } from "@opengeni/db/session-event-slices";
+import * as sessionPreviewSchema from "@opengeni/db/schema";
+import { and, eq, sql } from "drizzle-orm";
 import { SessionMessageSearchRequest } from "@opengeni/contracts";
 import { scheduledSessionIds } from "@opengeni/db";
 import { withSiteSessionOrigin } from "@opengeni/core";
@@ -2924,6 +2927,90 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(page.events);
   });
 
+  // Selected search hit only: never use the audit event projection here, even
+  // in summary mode (it can contain modelContext or truncate visible text).
+  app.get(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/events/:eventId/message-preview",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+      const sessionId = c.req.param("sessionId");
+      await assertSessionExists(db, workspaceId, sessionId);
+      const eventId = c.req.param("eventId");
+      const rawSequence = c.req.query("sequence");
+      const sequence = Number(rawSequence);
+      if (
+        !z.string().uuid().safeParse(eventId).success ||
+        rawSequence === undefined ||
+        !/^\d+$/.test(rawSequence) ||
+        !Number.isSafeInteger(sequence) ||
+        sequence < 1 ||
+        sequence > 2_147_483_647
+      )
+        throw new HTTPException(400, { message: "Invalid message preview reference" });
+
+      const notFound = () => new HTTPException(404, { message: "message not found" });
+      const maxUnits = 12_000;
+      const eventTable = sessionPreviewSchema.sessionEvents;
+      // The slice helper supports structured result views too. Check only the
+      // JSON scalar *kind* before calling it; never fetch a structured text value.
+      const candidates = await withWorkspaceRls(db, workspaceId, (tx) =>
+        tx
+          .select({ kind: sql<string | null>`jsonb_typeof(${eventTable.payload}->'text')` })
+          .from(eventTable)
+          .where(
+            and(
+              eq(eventTable.workspaceId, workspaceId),
+              eq(eventTable.sessionId, sessionId),
+              eq(eventTable.id, eventId),
+              eq(eventTable.sequence, sequence),
+              sql`${eventTable.type} in ('user.message', 'agent.message.completed')`,
+            ),
+          )
+          .limit(1),
+      );
+      if (candidates[0]?.kind !== "string") throw notFound();
+      const read = (offset: number) =>
+        listSessionEventSlices(db, workspaceId, sessionId, {
+          sourceSequence: sequence,
+          sourceOffset: offset,
+          after: sequence - 1,
+          before: sequence + 1,
+          includeTypes: ["user.message", "agent.message.completed"],
+          view: "conversation",
+        });
+      const first = await read(0);
+      const event = first.events[0];
+      const slice = first.slices?.[sequence];
+      // Includes the slice reader's duplicate, late and unclaimed-prompt gates.
+      if (!event || event.id !== eventId || event.sequence !== sequence || !slice || slice.omitted)
+        throw notFound();
+      if (slice.total > maxUnits) return c.json({ status: "unavailable" as const });
+
+      let text = slice.text;
+      let offset = slice.unit === "utf16" ? slice.text.length : Array.from(slice.text).length;
+      if (text.length > maxUnits) return c.json({ status: "unavailable" as const });
+      while (offset < slice.total) {
+        if (offset === 0) throw notFound();
+        const next = await read(offset);
+        const part = next.slices?.[sequence];
+        if (
+          next.events[0]?.id !== eventId ||
+          !part ||
+          part.omitted ||
+          part.unit !== slice.unit ||
+          part.total !== slice.total ||
+          part.offset !== offset
+        )
+          throw notFound();
+        text += part.text;
+        offset += slice.unit === "utf16" ? part.text.length : Array.from(part.text).length;
+        if (text.length > maxUnits) return c.json({ status: "unavailable" as const });
+      }
+      return c.json({ status: "available" as const, text });
+    },
+  );
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/events/stream", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -4817,6 +4904,8 @@ export function sessionAuthorizationOperationForHttp(
     return verb === "POST" ? "session.context.write" : null;
   }
   if (suffix === "/events/stream" && verb === "GET") return "session.stream.read";
+  if (/^\/events\/[^/]+\/message-preview$/.test(suffix) && verb === "GET")
+    return "session.events.read";
   if (suffix === "/events") {
     if (verb === "GET") return "session.events.read";
     if (verb === "POST") return "session.append";

package/src/sandbox/channel-a.ts

@@ -22,6 +22,7 @@ import {
   hasGitCredentialRepositorySelection,
   hasGitHubRepositorySelection,
   sandboxLifecycleTransitionWaitMs,
+  sandboxWarmRateMicrosPerSecond,
   stableSandboxEnvironmentForRun,
   type Settings,
 } from "@opengeni/config";
@@ -42,6 +43,7 @@ import {
   SandboxImageConflictError,
   SandboxProviderReadLockUnavailableError,
   SandboxRigConflictError,
+  SandboxPaidComputeAdmissionError,
   withSandboxProviderReadLock,
   type Database,
   type LeaseSnapshot,
@@ -823,6 +825,10 @@ async function withChannelAOperation<T>(
       holderId,
       subjectId: session.id,
       backend: session.sandboxBackend,
+      warmBilling: {
+        mode: settings.sandboxWarmBillingMode,
+        rateMicrosPerSecond: sandboxWarmRateMicrosPerSecond(settings, session.sandboxBackend),
+      },
       os: session.sandboxOs,
       image: sandboxRuntime.image,
       rigVersionId: session.rigVersionId,
@@ -1210,6 +1216,8 @@ async function withChannelAOperation<T>(
  *  already-HTTPException unchanged. */
 export function mapChannelAError(error: unknown, waitSignal?: AbortSignal): unknown {
   if (error instanceof HTTPException) return error;
+  if (error instanceof SandboxPaidComputeAdmissionError)
+    return new HTTPException(402, { message: error.message, cause: error });
   if (isChannelARequestCancellation(error, waitSignal))
     return new HTTPException(499 as never, {
       message: "request cancelled",

package/src/sandbox/viewer.ts

@@ -26,6 +26,7 @@ import {
   hasGitHubRepositorySelection,
   resolveStreamTokenSecret,
   sandboxLifecycleTransitionWaitMs,
+  sandboxWarmRateMicrosPerSecond,
   stableSandboxEnvironmentForRun,
 } from "@opengeni/config";
 import type { Settings } from "@opengeni/config";
@@ -37,7 +38,7 @@ import {
   getSandbox,
   getScheduledScopedRigVersionMetadata,
   getSandboxSessionEnvelope,
-  heartbeatLeaseHolder,
+  heartbeatLeaseHolderStatus,
   loadWorkspaceEnvironmentForRun,
   markSandboxProviderReady,
   markWarmLeaseInstanceLost,
@@ -47,6 +48,7 @@ import {
   releaseLeaseHolder,
   SandboxLeaseSupersededError,
   SandboxViewerAdmissionBlockedError,
+  SandboxPaidComputeAdmissionError,
   type Database,
   type LeaseSnapshot,
   type SandboxRecord,
@@ -300,6 +302,10 @@ export async function attachViewer(
       ...(attachSubjectId ? { viewerSubjectId: attachSubjectId } : {}),
       ...(attachAuthorityEpoch !== null ? { viewerAuthorityEpoch: attachAuthorityEpoch } : {}),
       backend: session.sandboxBackend,
+      warmBilling: {
+        mode: settings.sandboxWarmBillingMode,
+        rateMicrosPerSecond: sandboxWarmRateMicrosPerSecond(settings, session.sandboxBackend),
+      },
       os: session.sandboxOs,
       image: sandboxRuntime.image,
       rigVersionId: session.rigVersionId,
@@ -309,6 +315,9 @@ export async function attachViewer(
       ...(input.waitSignal ? { waitSignal: input.waitSignal } : {}),
     });
   } catch (error) {
+    if (error instanceof SandboxPaidComputeAdmissionError) {
+      throw new HTTPException(402, { message: error.message, cause: error });
+    }
     if (error instanceof SandboxViewerAdmissionBlockedError) {
       throw new HTTPException(error.reason === "balance" ? 402 : 429, {
         message:
@@ -592,7 +601,7 @@ export async function heartbeatViewer(
     expectedEpoch: number;
   },
 ): Promise<boolean> {
-  const alive = await heartbeatLeaseHolder(services.db, {
+  const status = await heartbeatLeaseHolderStatus(services.db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     sandboxGroupId: input.sandboxGroupId,
@@ -600,8 +609,12 @@ export async function heartbeatViewer(
     holderId: input.viewerId,
     leaseTtlMs: services.settings.sandboxLeaseTtlMs,
     expectedEpoch: input.expectedEpoch,
+    billingMode: services.settings.sandboxWarmBillingMode,
   });
-  if (!alive) return false;
+  // A funding fence stops renewing paid provider time, but the holder is
+  // deliberately kept alive while the viewer winds down or adds funds. Other
+  // fences (epoch/rotation/drain) still require the client to re-attach.
+  if (!status.leaseExtended) return status.holderAlive && status.fence === "funding";
   const lease = await readLease(services.db, input.workspaceId, input.sandboxGroupId);
   if (lease?.liveness === "warm" && lease.leaseEpoch === input.expectedEpoch && lease.instanceId) {
     await renewSandboxProviderExpiration({

package/src/sandbox-file-artifacts.ts

@@ -27,6 +27,12 @@ import {
 } from "@opengeni/db";
 import { retryWhileMissing, type ObjectHead, type ObjectStorage } from "@opengeni/storage";
 import { HTTPException } from "hono/http-exception";
+import {
+  isConnectedMachineAbsolutePath,
+  relativeConnectedMachinePath,
+  resolveConnectedMachinePath,
+  type SandboxChannelAService,
+} from "@opengeni/runtime/sandbox";
 
 import { withChannelARead } from "./sandbox/channel-a";
 import { sanitizeFilename } from "./routes/files";
@@ -98,13 +104,12 @@ async function publishSandboxFileArtifactInScope(
     });
   }
 
-  const path = sandboxArtifactRelativePath(input.path);
   const maxArtifactBytes = Math.min(SANDBOX_FILE_ARTIFACT_MAX_BYTES, storage.maxSinglePutSizeBytes);
   if (maxArtifactBytes < 1) {
     throw new HTTPException(503, { message: "object storage cannot accept artifact files" });
   }
   const readLimit = Math.min(25 * 1024 * 1024, maxArtifactBytes + FILE_READ_SENTINEL_BYTES);
-  const read = await withChannelARead(
+  const { path, sandboxPath, read } = await withChannelARead(
     {
       db: deps.db,
       settings: deps.settings,
@@ -119,7 +124,7 @@ async function publishSandboxFileArtifactInScope(
       ...(input.signal ? { waitSignal: input.signal } : {}),
       operation: "artifact.publish",
     },
-    ({ service }) => service.fsRead({ path, encoding: "base64", maxBytes: readLimit }),
+    ({ service }) => readSandboxArtifactFile(service, input.path, readLimit),
   );
   if (read.truncated || read.sizeBytes > maxArtifactBytes) {
     throw new HTTPException(413, {
@@ -234,48 +239,54 @@ async function publishSandboxFileArtifactInScope(
   });
   return SandboxFileArtifactReceipt.parse({
     type: "sandbox_file",
-    sandboxPath: `/workspace/${path}`,
+    sandboxPath,
     filename,
     artifact,
   });
 }
 
-export function sandboxArtifactRelativePath(value: string): string {
+/** Use the root captured by the same fenced Channel-A service that reads bytes,
+ * not the session's placement-home label or a caller-supplied root. */
+export async function readSandboxArtifactFile(
+  service: Pick<SandboxChannelAService, "capabilities" | "fsRead">,
+  value: string,
+  maxBytes: number,
+) {
+  const root = service.capabilities().FileSystem.root;
+  const path = sandboxArtifactRelativePath(value, root);
+  const sandboxPath = resolveConnectedMachinePath(root, path);
+  const read = await service.fsRead({ path, encoding: "base64", maxBytes });
+  return { path, sandboxPath, read };
+}
+
+export function sandboxArtifactRelativePath(value: string, workspaceRoot = "/workspace"): string {
   let path = value.trim();
   if (path.startsWith("sandbox:")) {
     path = path.slice("sandbox:".length);
   }
-  if (path === "/workspace" || path === "/workspace/") {
+  if (!path || /[\\/]$/.test(path)) {
     throw new HTTPException(400, { message: "sandbox artifact path must name a file" });
   }
-  if (path.startsWith("/workspace/")) {
-    path = path.slice("/workspace/".length);
-  } else if (path.startsWith("/")) {
+  let absolute: string;
+  let relative: string | null;
+  try {
+    if (!isConnectedMachineAbsolutePath(workspaceRoot)) throw new Error("Missing workspace root");
+    absolute = resolveConnectedMachinePath(workspaceRoot, path);
+    relative = relativeConnectedMachinePath(workspaceRoot, absolute);
+  } catch {
     throw new HTTPException(400, {
-      message: "sandbox artifact path must be inside /workspace",
+      message: "sandbox artifact path is invalid for this workspace",
     });
   }
-  if (!path) {
-    throw new HTTPException(400, { message: "sandbox artifact path must name a file" });
-  }
-  if (path.includes("\0")) {
-    throw new HTTPException(400, { message: "sandbox artifact path is invalid" });
-  }
-  const normalized = posix.normalize(path);
-  if (
-    normalized === "." ||
-    normalized === ".." ||
-    normalized.startsWith("../") ||
-    normalized.endsWith("/")
-  ) {
+  if (!relative) {
     throw new HTTPException(400, {
-      message: "sandbox artifact path must canonically name a file inside /workspace",
+      message: "sandbox artifact path must name a file inside the active workspace root",
     });
   }
-  if (`/workspace/${normalized}`.length > SANDBOX_ARTIFACT_ABSOLUTE_PATH_MAX_CHARS) {
+  if (absolute.length > SANDBOX_ARTIFACT_ABSOLUTE_PATH_MAX_CHARS) {
     throw new HTTPException(400, { message: "sandbox artifact path is too long" });
   }
-  return normalized;
+  return relative;
 }
 
 export function sandboxArtifactSafeFilename(filename: string): string {

package/src/workspace-tool-gateway.ts

@@ -299,6 +299,7 @@ async function prepareWorkspaceToolGatewayForGrantInternal(
               routeDeps.getDocumentServices(),
               {
                 knowledge: await knowledgeContextForGateway(routeDeps, grant),
+                settings: gatewaySettings,
               },
             ),
           ),