@opengeni/core 3.0.1 → 3.1.2

package/src/editable-artifact-live/server.ts

@@ -1,5 +1,6 @@
 import type { EditableArtifactAuthorizationPort } from "../domain/editable-artifacts/ports";
 import type { EditableArtifactService } from "../domain/editable-artifacts/service";
+import type { Database } from "@opengeni/db";
 import {
   EDITABLE_ARTIFACT_COMMAND_MAX_BYTES,
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
@@ -54,9 +55,13 @@ import {
   type EditableArtifactLiveSnapshot,
   type EditableArtifactLiveTicket,
   type EditableArtifactLiveTicketRecord,
+  type EditableArtifactLiveSourceSessionAuthority,
 } from "./types";
 
 const textEncoder = new TextEncoder();
+// Source-bound sockets must renew through the product proxy's live host check.
+// Unbound native console sockets retain their existing artifact-only lifecycle.
+const SOURCE_SESSION_LIVE_LEASE_MS = 15_000;
 const strictDecoder = new TextDecoder("utf-8", { fatal: true });
 
 // Shared OGATX is bounded at 5 MiB and whole OGACO at 8 MiB. Transport
@@ -112,6 +117,13 @@ export type OpenEditableArtifactLiveInput = Readonly<{
   resume: EditableArtifactLiveResume;
   sink: EditableArtifactLiveSinkPort;
   signal?: AbortSignal;
+  /** API-owned canonical source session authorization, including live revocation. */
+  authorizeSourceSession?: (
+    ticket: EditableArtifactLiveTicketRecord,
+    permission: "read" | "edit",
+    transaction?: Database,
+    signal?: AbortSignal,
+  ) => Promise<boolean>;
 }>;
 
 export interface EditableArtifactLiveSession {
@@ -160,6 +172,7 @@ export class EditableArtifactLiveServer {
       modality: EditableArtifactModality;
       actor: EditableArtifactActor;
       allowEdit: boolean;
+      sourceSessionAuthority?: EditableArtifactLiveSourceSessionAuthority;
     }>,
   ): Promise<EditableArtifactLiveTicket> {
     return this.ticketAuthority.mint(input);
@@ -183,6 +196,9 @@ export class EditableArtifactLiveServer {
       resume: input.resume,
       sink: input.sink,
       ...(input.signal === undefined ? {} : { parentSignal: input.signal }),
+      ...(input.authorizeSourceSession
+        ? { authorizeSourceSession: input.authorizeSourceSession }
+        : {}),
     });
     await session.start();
     return session;
@@ -197,6 +213,7 @@ type SessionConstructor = Readonly<{
   resume: EditableArtifactLiveResume;
   sink: EditableArtifactLiveSinkPort;
   parentSignal?: AbortSignal;
+  authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"];
 }>;
 
 type InFlight = Readonly<{
@@ -214,6 +231,8 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
   private readonly dependencies: EditableArtifactLiveServerDependencies;
   private readonly options: NormalizedOptions;
   private readonly ticket: EditableArtifactLiveTicketRecord;
+  private readonly authorizeSourceSession: OpenEditableArtifactLiveInput["authorizeSourceSession"];
+  private readonly sourceSessionLeaseExpiresAt: number | null;
   private readonly resume: EditableArtifactLiveResume;
   private readonly sink: EditableArtifactLiveSinkPort;
   private readonly abort = new AbortController();
@@ -247,6 +266,10 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
     this.dependencies = input.dependencies;
     this.options = input.options;
     this.ticket = input.ticket;
+    this.authorizeSourceSession = input.authorizeSourceSession;
+    this.sourceSessionLeaseExpiresAt = input.ticket.sourceSessionAuthority
+      ? Date.parse(input.ticket.issuedAt) + SOURCE_SESSION_LIVE_LEASE_MS
+      : null;
     this.artifactId = input.ticket.artifactId;
     this.modality = input.ticket.modality;
     this.streamEpoch = input.streamEpoch;
@@ -268,6 +291,13 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
   async start(): Promise<void> {
     try {
       this.assertOpen();
+      // Deadline enforcement owns no work-queue slot and starts before any
+      // bootstrap/authorization await. A hung callback cannot retain a socket.
+      if (this.sourceSessionLeaseExpiresAt !== null) {
+        void this.runSourceSessionLease().catch((error: unknown) => {
+          if (!this.abort.signal.aborted) void this.fail(error);
+        });
+      }
       this.authorizationRevision = await this.requireRead();
       this.assertOpen();
 
@@ -527,6 +557,7 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
   }
 
   private assertOpen(): void {
+    this.assertSourceSessionLease();
     if (this.closedValue) {
       throw new EditableArtifactLiveError("closed", "Live session is closed");
     }
@@ -925,6 +956,25 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
         scope: this.ticket.scope,
         artifactId: this.artifactId,
         actor: this.ticket.actor,
+        ...(this.ticket.sourceSessionAuthority
+          ? {
+              authorizeCommit: async (transaction) => {
+                this.assertOpen();
+                if (
+                  !this.authorizeSourceSession ||
+                  !(await this.withBoundedAuthorization((signal) =>
+                    this.authorizeSourceSession!(this.ticket, "edit", transaction, signal),
+                  ))
+                ) {
+                  throw new EditableArtifactLiveError(
+                    "permission_changed",
+                    "Editable artifact source session permission changed",
+                  );
+                }
+                this.assertOpen();
+              },
+            }
+          : {}),
         request: {
           intentBytes: frame.intentBytes.slice(),
           requestHash: frame.requestHash,
@@ -1035,11 +1085,22 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
   private async checkPermission(
     permission: "read" | "edit",
   ): Promise<Awaited<ReturnType<EditableArtifactAuthorizationPort["authorize"]>>> {
-    const decision = await this.dependencies.authorization.authorize({
-      scope: this.ticket.scope,
-      artifactId: this.artifactId,
-      actor: this.ticket.actor,
-      permission,
+    const decision = await this.withBoundedAuthorization(async (signal) => {
+      if (this.ticket.sourceSessionAuthority) {
+        if (
+          !this.authorizeSourceSession ||
+          !(await this.authorizeSourceSession(this.ticket, permission, undefined, signal))
+        ) {
+          return Object.freeze({ allowed: false, revision: this.authorizationRevision });
+        }
+      }
+      signal.throwIfAborted();
+      return await this.dependencies.authorization.authorize({
+        scope: this.ticket.scope,
+        artifactId: this.artifactId,
+        actor: this.ticket.actor,
+        permission,
+      });
     });
     if (permission === "edit" && !this.ticket.allowEdit) {
       return Object.freeze({ ...decision, allowed: false });
@@ -1047,6 +1108,57 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
     return decision;
   }
 
+  private async withBoundedAuthorization<T>(
+    operation: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    this.assertSourceSessionLease();
+    const timeout = new AbortController();
+    const signal = AbortSignal.any([this.abort.signal, timeout.signal]);
+    // Native artifact-only sockets retain their authorization timing. Only
+    // source-bound sockets have a renewable product-session lease.
+    if (this.sourceSessionLeaseExpiresAt !== null) {
+      const budget = this.sourceSessionLeaseExpiresAt - this.dependencies.clock.now().getTime();
+      void this.dependencies.scheduler.sleep(budget, signal).then(
+        () =>
+          timeout.abort(
+            new EditableArtifactLiveError("ticket_expired", "Live authorization lease expired", {
+              retryable: true,
+            }),
+          ),
+        () => undefined,
+      );
+    }
+    try {
+      const result = await awaitLiveAuthorization(operation(signal), signal);
+      this.assertOpen();
+      return result;
+    } finally {
+      timeout.abort();
+    }
+  }
+
+  private async runSourceSessionLease(): Promise<void> {
+    while (!this.abort.signal.aborted && this.sourceSessionLeaseExpiresAt !== null) {
+      const remaining = this.sourceSessionLeaseExpiresAt - this.dependencies.clock.now().getTime();
+      if (remaining <= 0) {
+        await this.close("ticket_expired");
+        return;
+      }
+      await this.dependencies.scheduler.sleep(remaining, this.abort.signal);
+    }
+  }
+  private assertSourceSessionLease(): void {
+    if (
+      this.sourceSessionLeaseExpiresAt !== null &&
+      this.dependencies.clock.now().getTime() >= this.sourceSessionLeaseExpiresAt
+    ) {
+      void this.close("ticket_expired");
+      throw new EditableArtifactLiveError("ticket_expired", "Source session lease expired", {
+        retryable: true,
+      });
+    }
+  }
+
   private async sendBarrier(): Promise<void> {
     if (!this.sentStateHash)
       throw new EditableArtifactLiveError("durable_gap", "Bootstrap has no state boundary");
@@ -1062,6 +1174,7 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
 
   private async send(frame: EditableArtifactLiveServerFrame): Promise<void> {
     if (this.closedValue) return;
+    this.assertSourceSessionLease();
     const bytes = estimateFrameBytes(frame);
     if (bytes > this.options.maxOutboundFrameBytes) {
       throw new EditableArtifactLiveError(
@@ -1131,9 +1244,21 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
       ),
     );
     while (!this.abort.signal.aborted) {
-      await this.dependencies.scheduler.sleep(tick, this.abort.signal);
+      const leaseRemaining =
+        this.sourceSessionLeaseExpiresAt === null
+          ? tick
+          : this.sourceSessionLeaseExpiresAt - this.dependencies.clock.now().getTime();
+      if (leaseRemaining <= 0) {
+        await this.close("ticket_expired");
+        return;
+      }
+      await this.dependencies.scheduler.sleep(Math.min(tick, leaseRemaining), this.abort.signal);
       if (this.abort.signal.aborted || this.closedValue) return;
       const now = this.dependencies.clock.now().getTime();
+      if (this.sourceSessionLeaseExpiresAt !== null && now >= this.sourceSessionLeaseExpiresAt) {
+        await this.close("ticket_expired");
+        return;
+      }
       if (this.oldestInFlightAt !== 0 && now - this.oldestInFlightAt >= this.options.ackTimeoutMs) {
         await this.enqueue(() => this.requireResync("slow_client", this.targetHead));
         return;
@@ -1177,6 +1302,29 @@ class EditableArtifactLiveSessionImpl implements EditableArtifactLiveSession {
   }
 }
 
+/** Settle callers on cancellation even when an embedding callback ignores it. */
+function awaitLiveAuthorization<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason);
+    };
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", abort);
+        if (signal.aborted) reject(signal.reason);
+        else resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      },
+    );
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
 function decodeClientFrame(
   bytes: Uint8Array,
   artifactId: EditableArtifactId,

package/src/editable-artifact-live/ticket.ts

@@ -1,3 +1,7 @@
+import { AccessGrant } from "@opengeni/contracts";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { z } from "zod";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
 import type { EditableArtifactAuthorizationPort } from "../domain/editable-artifacts/ports";
 import {
   assertIsoTimestamp,
@@ -19,11 +23,22 @@ import {
   EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION,
   type EditableArtifactLiveTicket,
   type EditableArtifactLiveTicketRecord,
+  type EditableArtifactLiveSourceSessionAuthority,
 } from "./types";
 
 const DEFAULT_TTL_MS = 30_000;
 const MAX_TTL_MS = 60_000;
 const MAX_TOKEN_BYTES = 4_096;
+const SOURCE_AUTHORITY_MARKER = ".ogs1.";
+const COMPRESSED_SOURCE_AUTHORITY_MARKER = ".ogs2.";
+const MAX_SOURCE_AUTHORITY_BYTES = 16 * 1024;
+const SourceSessionAuthority = z
+  .object({
+    sessionId: z.string().uuid(),
+    grant: AccessGrant,
+    externalContinuation: ExternalActorContinuation.optional(),
+  })
+  .strict();
 
 export type EditableArtifactLiveTicketAuthorityDependencies = Readonly<{
   authorization: EditableArtifactAuthorizationPort;
@@ -52,6 +67,7 @@ export class EditableArtifactLiveTicketAuthority {
       modality: EditableArtifactModality;
       actor: EditableArtifactActor;
       allowEdit: boolean;
+      sourceSessionAuthority?: EditableArtifactLiveSourceSessionAuthority;
     }>,
   ): Promise<EditableArtifactLiveTicket> {
     const scope = editableArtifactScope(input.scope);
@@ -74,7 +90,28 @@ export class EditableArtifactLiveTicketAuthority {
         "Editable artifact read permission denied",
       );
     }
-    const token = this.dependencies.tokens.randomOpaqueToken();
+    const sourceSessionAuthority = input.sourceSessionAuthority
+      ? SourceSessionAuthority.parse(input.sourceSessionAuthority)
+      : undefined;
+    if (sourceSessionAuthority) {
+      assertSourceSessionAuthority(sourceSessionAuthority, scope, actor);
+    }
+    const sourceBytes = sourceSessionAuthority
+      ? Buffer.from(JSON.stringify(sourceSessionAuthority))
+      : null;
+    if (sourceBytes && sourceBytes.byteLength > MAX_SOURCE_AUTHORITY_BYTES) {
+      throw new EditableArtifactLiveError(
+        "invalid_ticket",
+        "Live ticket source authority is too large",
+      );
+    }
+    const nonce = this.dependencies.tokens.randomOpaqueToken();
+    // The execute-only PG store persists the digest of this COMPLETE token.
+    // Changing/removing the suffix cannot consume its record. Decode only after
+    // atomic consume authenticates it, keeping the existing fixed SQL DTO intact.
+    const token = sourceBytes
+      ? `${nonce}${COMPRESSED_SOURCE_AUTHORITY_MARKER}${deflateRawSync(sourceBytes).toString("base64url")}`
+      : nonce;
     assertToken(token);
     const tokenDigest = await this.dependencies.tokens.digestOpaqueToken(token);
     assertDigest(tokenDigest);
@@ -124,6 +161,10 @@ export class EditableArtifactLiveTicketAuthority {
       );
     }
     validateTicketRecord(record);
+    const sourceSessionAuthority = decodeSourceSessionAuthority(input.token);
+    if (sourceSessionAuthority) {
+      assertSourceSessionAuthority(sourceSessionAuthority, record.scope, record.actor);
+    }
     if (Date.parse(record.expiresAt) <= this.dependencies.clock.now().getTime()) {
       throw new EditableArtifactLiveError("ticket_expired", "Live ticket has expired", {
         retryable: true,
@@ -145,6 +186,7 @@ export class EditableArtifactLiveTicketAuthority {
       ...record,
       scope: editableArtifactScope(record.scope),
       actor: Object.freeze({ ...record.actor }) as EditableArtifactActor,
+      ...(sourceSessionAuthority ? { sourceSessionAuthority } : {}),
     });
   }
 }
@@ -194,6 +236,49 @@ function validateTicketRecord(record: EditableArtifactLiveTicketRecord): void {
   assertIsoTimestamp(record.expiresAt, "ticket expiresAt");
 }
 
+function decodeSourceSessionAuthority(
+  token: string,
+): EditableArtifactLiveSourceSessionAuthority | undefined {
+  const compressed = token.includes(COMPRESSED_SOURCE_AUTHORITY_MARKER);
+  const marker = compressed ? COMPRESSED_SOURCE_AUTHORITY_MARKER : SOURCE_AUTHORITY_MARKER;
+  const separator = token.lastIndexOf(marker);
+  if (separator === -1) return undefined;
+  try {
+    return SourceSessionAuthority.parse(
+      JSON.parse(
+        (compressed
+          ? inflateRawSync(Buffer.from(token.slice(separator + marker.length), "base64url"), {
+              maxOutputLength: MAX_SOURCE_AUTHORITY_BYTES,
+            })
+          : Buffer.from(token.slice(separator + marker.length), "base64url")
+        ).toString("utf8"),
+      ),
+    );
+  } catch {
+    throw new EditableArtifactLiveError(
+      "invalid_ticket",
+      "Live ticket source authority is invalid",
+    );
+  }
+}
+
+function assertSourceSessionAuthority(
+  authority: EditableArtifactLiveSourceSessionAuthority,
+  scope: EditableArtifactScope,
+  actor: EditableArtifactActor,
+): void {
+  if (
+    authority.grant.accountId !== scope.accountId ||
+    authority.grant.workspaceId !== scope.workspaceId ||
+    authority.grant.subjectId !== actor.subjectId
+  ) {
+    throw new EditableArtifactLiveError(
+      "invalid_ticket",
+      "Live ticket source scope does not match",
+    );
+  }
+}
+
 function assertModality(value: EditableArtifactModality): EditableArtifactModality {
   if (value !== "document" && value !== "spreadsheet" && value !== "presentation") {
     throw new TypeError("ticket modality is invalid");

package/src/editable-artifact-live/types.ts

@@ -1,4 +1,6 @@
 import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "@opengeni/contracts/editable-artifact-live";
+import type { AccessGrant } from "@opengeni/contracts";
+import type { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type {
   EditableArtifactActor,
   EditableArtifactCausalFrontier,
@@ -14,6 +16,13 @@ import type {
 
 export const EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION = EDITABLE_ARTIFACT_LIVE_WIRE_VERSION;
 
+/** Authenticated by the digest of the complete one-use token, never client claims. */
+export type EditableArtifactLiveSourceSessionAuthority = Readonly<{
+  sessionId: string;
+  grant: AccessGrant;
+  externalContinuation?: ExternalActorContinuation | undefined;
+}>;
+
 export type EditableArtifactLiveTicket = Readonly<{
   artifactId: EditableArtifactId;
   modality: EditableArtifactModality;
@@ -30,6 +39,7 @@ export type EditableArtifactLiveTicketRecord = Readonly<{
   artifactId: EditableArtifactId;
   modality: EditableArtifactModality;
   actor: EditableArtifactActor;
+  sourceSessionAuthority?: EditableArtifactLiveSourceSessionAuthority;
   /** Delegated ceiling captured by the authenticated ticket-minting request. */
   allowEdit: boolean;
   protocolVersion: number;

package/src/goal-admission.ts

@@ -0,0 +1,220 @@
+import {
+  isModelAvailableForNewSelection,
+  policyChargesCreditsForModel,
+  policyProviderIdForModel,
+  resolveModelProvider,
+  runnableLatencyModesForModel,
+  withCodexCatalogProvider,
+  withXaiSubscriptionCatalogProvider,
+  type Settings,
+} from "@opengeni/config";
+import {
+  evaluateWorkspaceModelPolicy,
+  type GoalAdmissionPausedReason,
+  type Session,
+} from "@opengeni/contracts";
+import { isCodexBilledModel } from "@opengeni/codex";
+import {
+  checkSessionUsageLimitAdmission,
+  getWorkspaceModelPolicy,
+  type Database,
+} from "@opengeni/db";
+import { resolveWorkspaceCatalogSettings } from "./model-catalog";
+import { agentRunAdmissionDenial } from "./billing/agent-run-admission";
+
+export type GoalAdmissionBlock = { pausedReason: GoalAdmissionPausedReason; message: string };
+
+/** Catalog membership never grants access to a connection or changes the selected model. */
+export function goalContinuationModelDecision(input: {
+  settings: Settings;
+  workspaceModelPolicy: Awaited<ReturnType<typeof getWorkspaceModelPolicy>>;
+  inheritedModel: string;
+  codexCompactionMode?: Session["codexCompactionMode"];
+  latencyMode?: Session["latencyMode"];
+}): { model: string; blocked: string | null; pausedReason?: GoalAdmissionPausedReason } {
+  const catalogSettings = input.settings.supergrokSubscriptionEnabled
+    ? withXaiSubscriptionCatalogProvider(
+        input.settings.codexSubscriptionEnabled
+          ? withCodexCatalogProvider(input.settings)
+          : input.settings,
+      )
+    : input.settings.codexSubscriptionEnabled
+      ? withCodexCatalogProvider(input.settings)
+      : input.settings;
+  const model = input.inheritedModel;
+  if (!resolveModelProvider(catalogSettings, model)) {
+    return {
+      model,
+      blocked: "The selected model is unavailable. Choose an available model before resuming.",
+      pausedReason: "model_unavailable",
+    };
+  }
+  if (!isModelAvailableForNewSelection(catalogSettings, model)) {
+    return {
+      model,
+      blocked: "The selected model has been retired. Choose an available model before resuming.",
+      pausedReason: "model_unavailable",
+    };
+  }
+  const policyVerdict =
+    input.workspaceModelPolicy === null
+      ? null
+      : evaluateWorkspaceModelPolicy(input.workspaceModelPolicy, {
+          providerId: policyProviderIdForModel(catalogSettings, model),
+          modelId: model,
+          chargesCredits: policyChargesCreditsForModel(catalogSettings, model),
+        });
+  if (policyVerdict && !policyVerdict.allowed) {
+    return {
+      model,
+      blocked:
+        policyVerdict.reason === "credits"
+          ? "Opengeni credits are turned off in this workspace. Choose a model paid by a subscription or API key before resuming."
+          : "Workspace policy blocks the selected model. Choose an allowed model before resuming.",
+      pausedReason: "model_policy",
+    };
+  }
+  if (input.codexCompactionMode === "remote_v2" && !isCodexBilledModel(model)) {
+    return {
+      model,
+      blocked: "This conversation requires a Codex model. Choose a Codex model before resuming.",
+      pausedReason: "model_policy",
+    };
+  }
+  if (
+    !runnableLatencyModesForModel(catalogSettings, model).includes(input.latencyMode ?? "standard")
+  ) {
+    return {
+      model,
+      blocked:
+        "The selected model does not support this conversation's latency mode. Choose a supported mode or model before resuming.",
+      pausedReason: "model_policy",
+    };
+  }
+  return { model, blocked: null };
+}
+
+/** The same scoped, secret-free catalog used at ordinary turn admission. */
+export async function resolveGoalModelAdmission(
+  db: Database,
+  settings: Settings,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    model: string;
+    codexCompactionMode?: Session["codexCompactionMode"];
+    latencyMode?: Session["latencyMode"];
+  },
+) {
+  const catalog = await resolveWorkspaceCatalogSettings(db, settings, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    retainedProductModelId: input.model,
+  });
+  const workspaceModelPolicy = await getWorkspaceModelPolicy(db, input.workspaceId);
+  return {
+    settings: catalog.settings,
+    ...goalContinuationModelDecision({
+      settings: catalog.settings,
+      workspaceModelPolicy,
+      inheritedModel: input.model,
+      ...(input.codexCompactionMode ? { codexCompactionMode: input.codexCompactionMode } : {}),
+      ...(input.latencyMode ? { latencyMode: input.latencyMode } : {}),
+    }),
+  };
+}
+
+/** Shared with scheduled work; reasons describe the actual admission gate. */
+export async function goalRunBudgetBlocked(
+  services: Parameters<typeof agentRunAdmissionDenial>[0],
+  input: Omit<Parameters<typeof agentRunAdmissionDenial>[1], "requestedAgentRuns">,
+): Promise<GoalAdmissionBlock | null> {
+  const denial = await agentRunAdmissionDenial(services, { ...input, requestedAgentRuns: 1 });
+  if (denial === null) return null;
+  const blocks: Record<NonNullable<typeof denial>, GoalAdmissionBlock> = {
+    insufficient_credits: services.entitlements
+      ? {
+          pausedReason: "usage_policy",
+          message: "The application's usage policy blocks another run. Resume when it allows.",
+        }
+      : {
+          pausedReason: "credits",
+          message: "Insufficient Opengeni credits. Add credits before resuming.",
+        },
+    allowance_exhausted: {
+      pausedReason: "allowance",
+      message: "Opengeni usage allowance exhausted. Resume when your allowance is available.",
+    },
+    monthly_model_cost_limit: {
+      pausedReason: "budget",
+      message: "Monthly model spending limit reached. Resume when the spending limit allows.",
+    },
+    monthly_agent_run_limit: {
+      pausedReason: "usage_limit",
+      message: "Monthly agent run limit reached. Resume when the run limit allows.",
+    },
+  };
+  return blocks[denial];
+}
+
+/**
+ * Per-task usage limit gate for goal continuation and resume. A
+ * reached root limit blocks with its own reason; raising or clearing the limit
+ * never resumes a goal by itself. A read failure throws (never unlimited).
+ */
+export async function goalSessionUsageLimitBlocked(
+  db: Database,
+  input: { accountId: string; workspaceId: string; sessionId: string },
+): Promise<GoalAdmissionBlock | null> {
+  // Server-internal: the goal's session is already authorized, so a private
+  // root is enforced rather than read as missing; a missing tree fails closed.
+  const admission = await checkSessionUsageLimitAdmission(db, { ...input, runtime: true });
+  if (admission.allowed) return null;
+  return { pausedReason: "session_usage_limit", message: admission.refusal.message };
+}
+
+export class GoalResumeBlockedError extends Error {
+  constructor(
+    readonly pausedReason: GoalAdmissionPausedReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "GoalResumeBlockedError";
+  }
+}
+
+/** Called under the goal transition's locks, before counters, events or wakes change. */
+export async function assertGoalResumeAllowed(
+  services: Parameters<typeof agentRunAdmissionDenial>[0] & { catalogSourceSettings?: Settings },
+  session: Pick<Session, "accountId" | "workspaceId" | "model" | "codexCompactionMode"> &
+    Partial<Pick<Session, "latencyMode" | "id">>,
+  causalTurn: { initiatingHumanSubjectId: string | null } | null,
+): Promise<void> {
+  if (session.id) {
+    const limit = await goalSessionUsageLimitBlocked(services.db, {
+      accountId: session.accountId,
+      workspaceId: session.workspaceId,
+      sessionId: session.id,
+    });
+    if (limit) throw new GoalResumeBlockedError(limit.pausedReason, limit.message);
+  }
+  const decision = await resolveGoalModelAdmission(
+    services.db,
+    services.catalogSourceSettings ?? services.settings,
+    session,
+  );
+  if (decision.blocked) {
+    throw new GoalResumeBlockedError(decision.pausedReason!, decision.blocked);
+  }
+  const block = await goalRunBudgetBlocked(
+    { ...services, settings: decision.settings },
+    {
+      accountId: session.accountId,
+      workspaceId: session.workspaceId,
+      model: decision.model,
+      // Resuming does not lend the clicking user's allowance or credentials.
+      initiatingHumanSubjectId: causalTurn?.initiatingHumanSubjectId ?? null,
+    },
+  );
+  if (block) throw new GoalResumeBlockedError(block.pausedReason, block.message);
+}

package/src/host-session-usage-limit.ts

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * A task usage limit the trusted server applies to a root session it creates
+ * in this process, as the host actor `subjectId`. Published Site agents use
+ * it: site-runtime creates each conversation as `site:<siteId>` through an
+ * in-process dispatch, and the per-conversation budget must be in place in the
+ * create transaction, before the first model call. Only code in this process
+ * can set it; a request cannot.
+ */
+export type HostSessionUsageLimit = {
+  /** The service principal the session is created as; other callers are ignored. */
+  subjectId: string;
+  limitMicros: number;
+};
+
+const limits = new AsyncLocalStorage<HostSessionUsageLimit>();
+
+export function withHostSessionUsageLimit<T>(limit: HostSessionUsageLimit, run: () => T): T {
+  return limits.run(limit, run);
+}
+
+export function currentHostSessionUsageLimit(): HostSessionUsageLimit | undefined {
+  return limits.getStore();
+}