@opengeni/worker-bundle 1.0.1 → 1.0.2-canary.37202341988001

package/dist/activities/agent-run-admission.d.ts

@@ -1,6 +1,6 @@
 import { type Settings } from "@opengeni/config";
 import type { ControlActivityServices } from "./types.js";
-export type AgentRunAdmissionDenial = "insufficient_credits" | "monthly_model_cost_limit" | "monthly_agent_run_limit";
+export type AgentRunAdmissionDenial = "insufficient_credits" | "allowance_exhausted" | "monthly_model_cost_limit" | "monthly_agent_run_limit";
 /** One worker-side admission boundary for service-authored agent runs. */
 export declare function agentRunAdmissionDenial(services: Pick<ControlActivityServices, "db" | "entitlements"> & {
     settings: Settings;
@@ -9,4 +9,6 @@ export declare function agentRunAdmissionDenial(services: Pick<ControlActivitySe
     workspaceId: string;
     model: string;
     requestedAgentRuns: number;
+    /** The accepted work's causal human, not the scheduler/service caller. */
+    initiatingHumanSubjectId?: string | null;
 }): Promise<AgentRunAdmissionDenial | null>;

package/dist/activities/agent-turn/admission.d.ts

@@ -1,6 +1,6 @@
 import { resolveTurnExecutionPolicyV1, type Settings } from "@opengeni/config";
 import type { TurnActivityServices as ActivityServices } from "../types.js";
-import { type SessionEvent, type SessionTurn, type ToolAuthNeededPayload, type TurnExecutionPolicyV1, type XaiProviderAccountAuthoritySnapshotV1 } from "@opengeni/contracts";
+import { type AllowanceExhaustedRefusal, type SessionEvent, type SessionTurn, type ToolAuthNeededPayload, type TurnExecutionPolicyV1, type XaiProviderAccountAuthoritySnapshotV1 } from "@opengeni/contracts";
 export declare class WorkspaceHumanInputDisabledError extends Error {
     constructor(kind: "resume" | "interruption");
 }
@@ -62,6 +62,27 @@ export declare function stableInteractionInterventionUuid(namespace: string, ses
  */
 export declare class BudgetExhaustedError extends Error {
     readonly serializedRunState: string | null;
-    constructor(message: string, serializedRunState: string | null);
+    readonly allowance: AllowanceRefusal | null;
+    constructor(message: string, serializedRunState: string | null, allowance?: AllowanceRefusal | null);
 }
-export declare function ensureRunAllowed(settings: Settings, db: ActivityServices["db"], accountId: string, workspaceId: string, isExternallyBilledTurn: boolean, entitlements?: ActivityServices["entitlements"], chargesOpenGeniCredits?: boolean, countsTowardTokenCap?: boolean): Promise<void>;
+export type AllowanceRefusal = AllowanceExhaustedRefusal;
+/** Account allowance exhaustion is recoverable state, never a provider failure. */
+export declare class AllowanceExhaustedError extends Error {
+    readonly refusal: AllowanceRefusal;
+    readonly code = "allowance_exhausted";
+    constructor(refusal: AllowanceRefusal);
+}
+/** Revalidate between paid calls without replaying provider work or reserving credits. */
+export declare function ensureRunAllowedBetweenModelCalls(input: {
+    settings: Settings;
+    db: ActivityServices["db"];
+    accountId: string;
+    workspaceId: string;
+    isExternallyBilledTurn: boolean;
+    entitlements?: ActivityServices["entitlements"];
+    chargesOpenGeniCredits: boolean;
+    countsTowardTokenCap: boolean;
+    initiatingHumanSubjectId: string | null;
+    serializedRunState?: () => string | null;
+}): Promise<void>;
+export declare function ensureRunAllowed(settings: Settings, db: ActivityServices["db"], accountId: string, workspaceId: string, isExternallyBilledTurn: boolean, entitlements?: ActivityServices["entitlements"], chargesOpenGeniCredits?: boolean, countsTowardTokenCap?: boolean, initiatingHumanSubjectId?: string | null): Promise<void>;

package/dist/activities/agent-turn/agent-build.d.ts

@@ -13,6 +13,7 @@ import type { loadWorkspaceEnvironmentForRunWithCredentials, sandboxEnvironmentF
 import type { AttemptIdentityState, EventingState, ProviderTurnState, SandboxRuntimeState } from "./turn-context.js";
 export type BuildTurnAgentDeps = {
     skillCatalog: NonNullable<BuildAgentOptions["skillCatalog"]>;
+    mcpServers: Settings["mcpServers"];
     input: RunAgentTurnInput;
     db: ActivityServices["db"];
     runtime: ActivityServices["runtime"];
@@ -42,6 +43,7 @@ export type BuildTurnAgentDeps = {
     supportsImageInput: GovernanceModelOk["supportsImageInput"];
     agentHumanInputEnabled: GovernanceModelOk["agentHumanInputEnabled"];
     workspaceAgentInstructions: GovernanceModelOk["workspaceAgentInstructions"];
+    workspaceAgentIdentity: GovernanceModelOk["workspaceAgentIdentity"];
     workspaceGovernance: GovernanceModelOk["workspaceGovernance"];
     structuredWorkspacePolicyActive: GovernanceModelOk["structuredWorkspacePolicyActive"];
     workspaceMemory: GovernanceModelOk["workspaceMemory"];
@@ -62,6 +64,8 @@ export type BuildTurnAgentDeps = {
     connectorActionPolicy: ConnectorActionPolicyHooks;
     trigger: ClaimTurnOk["trigger"];
     preparationIndependentToolNames: readonly string[];
+    /** The attempt's tool catalog includes the Jev-backed code_search tool. */
+    codeSearchAvailable: boolean;
     videoGenerationAcceptancesByCallId: Map<string, {
         operationId: string;
         requestDigest: string;

package/dist/activities/agent-turn/claude-usage-observer.d.ts

@@ -0,0 +1,58 @@
+import { type parseModelProvidersJson, type ClaudeUsageObservation } from "@opengeni/config";
+type Scope = "workspace" | "organization";
+type ClaudeRequestCredential = {
+    token: string;
+    connectionId: string;
+    credentialVersion: number;
+};
+export declare class ClaudeSubscriptionConnectionUnavailable extends Error {
+    readonly status = 409;
+    readonly code = "claude_subscription_connection_changed";
+    constructor();
+}
+export type CapturedClaudeUsage = {
+    scope: Scope;
+    token: string;
+    expectedConnectionId: string;
+    expectedCredentialVersion: number;
+    observation?: ClaudeUsageObservation;
+    responseStatus?: number;
+    upstreamModelId?: string;
+    requestId?: string;
+    refresh?: {
+        status: "reconnect";
+        checkedAt: string;
+    };
+};
+/** Capture the exact credential before requests; replacement fences late responses. */
+export declare function createClaudeUsageObserver(providers: ReturnType<typeof parseModelProvidersJson>, latest: Map<string, CapturedClaudeUsage>, readCredential: (scope: Scope) => Promise<{
+    token: string;
+    connectionId: string;
+    credentialVersion: number;
+} | null>): Promise<((providerId: string, response: Response, upstreamModelId?: string, requestToken?: string | null) => void) & {
+    prepareRequestWithObserver: (providerId: string, headers: Headers, resolve: (binding: {
+        scope: Scope;
+        expectedConnectionId: string;
+        expectedCredentialVersion: number;
+    }) => Promise<ClaudeRequestCredential | null>) => Promise<{
+        headers: Headers;
+        observe: (providerId: string, response: Response, upstreamModelId?: string, requestToken?: string | null) => void;
+    }>;
+    prepareRequest(providerId: string, headers: Headers, resolve: (binding: {
+        scope: Scope;
+        expectedConnectionId: string;
+        expectedCredentialVersion: number;
+    }) => Promise<ClaudeRequestCredential | null>): Promise<Headers>;
+    binding(providerId: string): {
+        scope: Scope;
+        token: string;
+        expectedConnectionId: string;
+        expectedCredentialVersion: number;
+    } | undefined;
+    renew(providerId: string, credential: {
+        token: string;
+        connectionId: string;
+        credentialVersion: number;
+    }): void;
+}>;
+export {};

package/dist/activities/agent-turn/code-search.d.ts

@@ -0,0 +1,60 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import { type Settings } from "@opengeni/config";
+import { JevCircuitBreaker, type CodeSearchWorkspace } from "@opengeni/jev";
+import type { Observability } from "@opengeni/observability";
+import { type SandboxChannelAService } from "@opengeni/runtime/sandbox";
+/**
+ * One breaker per worker process. Repeated Jev outages (including an exhausted
+ * account) make `code_search` calls on this worker fail at once for a cooldown
+ * instead of each running a full retry cycle. The breaker never changes which
+ * tools a turn is offered: the tool list and instructions are the start of the
+ * model's cached prompt, and sessions move between workers whose breakers
+ * disagree.
+ */
+export declare const codeSearchCircuitBreaker: JevCircuitBreaker;
+type CodeSearchChannel = Pick<SandboxChannelAService, "codeSearchRipgrep" | "codeSearchPathKinds" | "fsRead">;
+/** Adapt the turn's sandbox or Connected Machine to the code search engine. */
+export declare function codeSearchWorkspaceFromChannel(channel: CodeSearchChannel): CodeSearchWorkspace;
+/** Jev work done by one completed `code_search` call, for per-workspace usage records. */
+export type CodeSearchUsage = {
+    operationId: string;
+    jevRequests: number;
+    jevInputTokens: number;
+    jevCostUsd: number;
+};
+/**
+ * The model-facing `code_search` tool. Jev scores candidates inside the worker;
+ * the sandbox only runs read-only ripgrep and file reads, so the Jev key never
+ * leaves this process. A Jev failure is reported to the model instead of
+ * degrading to keyword-only ranking, which lowered answer quality in testing.
+ */
+export declare function createCodeSearchAttemptToolDefinition(input: {
+    settings: Pick<Settings, "jevApiKey" | "jevBaseUrl" | "jevModel" | "jevRequestTimeoutMs">;
+    apiKey: string;
+    workspace: () => Promise<CodeSearchWorkspace>;
+    observability: Observability;
+    /** Records Jev usage against the workspace. Failures are logged, never surfaced. */
+    recordUsage?: (usage: CodeSearchUsage) => Promise<void>;
+    breaker?: JevCircuitBreaker;
+    fetch?: typeof fetch;
+}): AttemptToolDefinition;
+/**
+ * The `code_search` definition for one turn, or none. It is offered only when
+ * the session's frozen decision and the deployment enable it, a usable Jev key
+ * exists, and the turn has compute that can run its POSIX shell commands (not
+ * a Windows Connected Machine). Every input is durable, so the tool list stays
+ * the same from turn to turn and on every worker. Transient Jev health never
+ * hides the tool; the breaker only refuses calls.
+ */
+export declare function codeSearchToolDefinitions(input: {
+    enabled: boolean;
+    settings: Pick<Settings, "jevApiKey" | "jevBaseUrl" | "jevModel" | "jevRequestTimeoutMs">;
+    backend: Settings["sandboxBackend"];
+    /** The turn's Connected Machine workspace root, when a machine is primary. */
+    machineWorkspaceRoot?: string | null;
+    observability: Observability;
+    workspace: () => Promise<CodeSearchWorkspace>;
+    recordUsage?: (usage: CodeSearchUsage) => Promise<void>;
+    breaker?: JevCircuitBreaker;
+}): AttemptToolDefinition[];
+export {};

package/dist/activities/agent-turn/codex-capacity.d.ts

@@ -1,8 +1,21 @@
 import { type Settings } from "@opengeni/config";
 import type { TurnActivityServices as ActivityServices, RunAgentTurnInput, RunAgentTurnResult } from "../types.js";
 import { createTurnCredentialLeases } from "./credential-leases.js";
+import { type LogThrottle } from "@opengeni/observability";
 import type { ClaimTurnOk } from "./claim.js";
 import type { AttemptIdentityState, BillingState, ClaimedResult, EventingState, ProviderTurnState, TurnControlState } from "./turn-context.js";
+/** The eligible-pool gauge and `opengeni_codex_pool_low_total` stay per turn;
+ * the warning line is the first observation per workspace pool depth, then at
+ * most one per interval with the count it hid. The public log projection drops
+ * the identifiers and counts, so the closed `reason` keeps the depth visible. */
+export declare const CODEX_POOL_LOW_WARNING_INTERVAL_MS: number;
+export declare function warnCodexPoolLow(observability: Pick<ActivityServices["observability"], "warn">, input: {
+    workspaceKey: string;
+    workspaceId: string;
+    eligibleCount: number;
+    connectedCount: number;
+    depth: "zero" | "one";
+}, throttle?: LogThrottle): void;
 export type CapacityPhaseDeps = {
     input: RunAgentTurnInput;
     settings: Settings;

package/dist/activities/agent-turn/codex-plan-entitlement.d.ts

@@ -0,0 +1,105 @@
+import { type CodexEntitlementRejection } from "@opengeni/codex";
+import { type CodexCredentialPlanRecheck, type CodexPlanEntitlementExclusion } from "@opengeni/db";
+export declare const CODEX_PLAN_ENTITLEMENT_CODE = "codex_plan_entitlement";
+export declare const CODEX_REQUEST_REJECTED_CODE = "codex_request_rejected";
+export type CodexPlanEntitlementFailurePayload = {
+    error: string;
+    code: typeof CODEX_PLAN_ENTITLEMENT_CODE;
+    retryable: false;
+    planType: string | null;
+    model: string | null;
+    detail?: string;
+};
+export type CodexRequestRejectedFailurePayload = {
+    error: string;
+    code: typeof CODEX_REQUEST_REJECTED_CODE;
+    retryable: false;
+    planType: string | null;
+    detail?: string;
+};
+/**
+ * The user-set label of one connected ChatGPT account. The account email is
+ * deliberately never used: this text lands in the durable `turn.failed` event
+ * that every session reader (including embedding-host end users) can see, and
+ * an inherited organization credential's email may be a member's personal
+ * address. Without a label the copy says "The connected ChatGPT account".
+ */
+export declare function codexAccountDisplayLabel(account: {
+    label: string | null;
+} | null | undefined): string | null;
+/** Terminal copy when the serving account's plan does not include the model. */
+export declare function codexPlanEntitlementFailurePayload(input: {
+    accountLabel: string | null;
+    planType: string | null;
+    planChanged: boolean;
+    modelId: string | null;
+    rejection?: CodexEntitlementRejection | null;
+    /** The same turn waits for another connected account instead of failing. */
+    waiting?: boolean;
+}): CodexPlanEntitlementFailurePayload;
+/**
+ * Terminal copy for an empty Codex rejection. With `planChecked`, the account's
+ * plan was re-read and did not explain it, so OpenGeni kept the account.
+ */
+export declare function codexRequestRejectedFailurePayload(input: {
+    accountLabel: string | null;
+    planType: string | null;
+    rejection: CodexEntitlementRejection;
+    planChecked?: boolean;
+}): CodexRequestRejectedFailurePayload;
+/**
+ * Admission-time refusal: the only accounts that could serve this turn were
+ * already proven not to include its model on their current plan.
+ */
+export declare class CodexPlanEntitlementError extends Error {
+    readonly payload: CodexPlanEntitlementFailurePayload;
+    readonly code = "codex_plan_entitlement";
+    constructor(payload: CodexPlanEntitlementFailurePayload);
+}
+export type CodexPlanEntitlementAssessment = {
+    kind: "entitlement_lost";
+    /**
+     * Plan the exclusion binds to: the freshly observed plan, or the
+     * recorded plan when the provider reported none.
+     */
+    planType: string | null;
+    /** The provider reported the current plan during this re-check. */
+    planObserved: boolean;
+    /** The observed plan was reached by a recorded (non-upgrade) plan change. */
+    planChanged: boolean;
+    credentialVersion: number | null;
+} | {
+    kind: "unexplained";
+    planType: string | null;
+};
+/** Pure decision over one plan re-check (see `codexPlanEntitlementLost`). */
+export declare function assessCodexPlanEntitlement(rejection: CodexEntitlementRejection, recheck: CodexCredentialPlanRecheck, modelId: string | null): CodexPlanEntitlementAssessment;
+type AdmissionAccount = {
+    id: string;
+    label: string | null;
+    planType: string | null;
+    allocatorEnabled: boolean;
+    allowedModelIds?: string[] | null;
+    planEntitlementExclusion?: CodexPlanEntitlementExclusion | null;
+};
+/**
+ * Pure admission check after credential selection found no account. Returns
+ * the plan-excluded accounts that alone explain it, or null when capacity,
+ * health, or policy (not plan entitlement) is the reason:
+ *
+ * - a manual pin (user intent) whose account's plan excludes the model;
+ * - with rotation off, the active account's plan excludes the model;
+ * - with rotation on, every allocatable account permitted for the model is
+ *   plan-excluded.
+ */
+export declare function codexPlanEntitlementAdmissionBlock<T extends AdmissionAccount>(input: {
+    accounts: readonly T[];
+    modelId: string;
+    credentialId: string | null;
+    rotationEnabled: boolean;
+    activeCredentialId: string | null;
+    pinnedCredentialId: string | null;
+    pinSource: "manual" | "policy" | null;
+    now: Date;
+}): T[] | null;
+export {};

package/dist/activities/agent-turn/codex.d.ts

@@ -1,5 +1,5 @@
 import { type CodexAccountStatus } from "@opengeni/db";
-import { type ResolvedModelProvider, type Settings } from "@opengeni/config";
+import { type ModelProviderApi, type ResolvedModelProvider, type Settings } from "@opengeni/config";
 import type { TurnActivityServices as ActivityServices } from "../types.js";
 export declare function codexWorkspaceMetricKey(workspaceId: string): string;
 /** Stable public request identity across partial resumes and activity retries. */
@@ -7,6 +7,7 @@ export declare function acceptsPromptCacheKeyForTurn(resolvedModel: {
     provider: {
         kind: ResolvedModelProvider["kind"];
         builtin?: boolean;
+        api?: ModelProviderApi;
     };
 } | null): boolean;
 /**
@@ -24,7 +25,7 @@ export declare function acceptsPromptCacheKeyForTurn(resolvedModel: {
 export declare function refreshCappedCodexUsageRows(db: ActivityServices["db"], settings: Settings, workspaceId: string, accounts: Array<Pick<CodexAccountStatus, "id" | "status" | "primaryUsedPercent" | "secondaryUsedPercent" | "exhaustedUntil" | "exhaustedKind">>, capacitySignals: {
     signalCodexCapacityWorkflow?: ActivityServices["signalCodexCapacityWorkflow"] | undefined;
     wakeSessionWorkflow: ActivityServices["wakeSessionWorkflow"];
-}): Promise<Array<Pick<CodexAccountStatus, "id" | "status" | "primaryUsedPercent" | "secondaryUsedPercent" | "exhaustedUntil" | "exhaustedKind">>>;
+}, acceptedTurnId?: string): Promise<Array<Pick<CodexAccountStatus, "id" | "status" | "primaryUsedPercent" | "secondaryUsedPercent" | "exhaustedUntil" | "exhaustedKind">>>;
 /**
  * True once the lifetime last confirmed by Postgres is no longer trustworthy.
  * A missing or malformed deadline fails closed for a holder that claims to be

package/dist/activities/agent-turn/compaction-prep.d.ts

@@ -1,4 +1,3 @@
-import { serializedToolsForRemoteCompaction } from "@opengeni/runtime";
 import { type Settings } from "@opengeni/config";
 import { maybeCompactContext } from "../context-compaction.js";
 import type { CompactionSummarizer, RemoteCompactionV2Requester } from "../context-compaction.js";
@@ -10,10 +9,7 @@ import type { ClaimTurnOk } from "./claim.js";
 import type { GovernanceModelOk } from "./governance-model.js";
 import type { AttemptIdentityState, BillingState, ClaimedResult, EventingState, ProviderTurnState, TurnControlState } from "./turn-context.js";
 export type RemoteCompactionPrefix = {
-    tools: Awaited<ReturnType<typeof serializedToolsForRemoteCompaction>>;
-    instructions: string;
-    toolsReady: boolean;
-    agent: Parameters<typeof serializedToolsForRemoteCompaction>[0] | null;
+    agent: ReturnType<ActivityServices["runtime"]["buildAgent"]> | null;
 };
 export type CompactionPrepDeps = {
     input: RunAgentTurnInput;
@@ -41,6 +37,7 @@ export type CompactionPrepDeps = {
     turnExecutionPolicy: ClaimTurnOk["turnExecutionPolicy"];
     resolvedModel: GovernanceModelOk["resolvedModel"];
     workspaceAgentInstructions: GovernanceModelOk["workspaceAgentInstructions"];
+    workspaceAgentIdentity: GovernanceModelOk["workspaceAgentIdentity"];
     workspaceGovernance: GovernanceModelOk["workspaceGovernance"];
     structuredWorkspacePolicyActive: GovernanceModelOk["structuredWorkspacePolicyActive"];
     workspaceMemory: GovernanceModelOk["workspaceMemory"];
@@ -86,5 +83,24 @@ export type PostAgentCompactionOutcome = {
 } | {
     ok: PostAgentCompactionOk;
 };
+/**
+ * System instructions for the standalone (chat-provider) compaction request.
+ * A session with an agent configuration uses the same modular composer and
+ * module selection as its turns; a legacy session keeps the historical
+ * persona + CORE + governance + session + memory string byte-for-byte.
+ */
+export declare function standaloneCompactionInstructions(input: {
+    settings: Settings;
+    session: Pick<ClaimTurnOk["session"], "agent" | "instructions" | "resources">;
+    workspaceAgentInstructions: string | null | undefined;
+    workspaceAgentIdentity: string | null;
+    workspaceGovernance: string | null | undefined;
+    structuredWorkspacePolicyActive: boolean;
+    workspaceMemory: string | null | undefined;
+    rig: {
+        name: string;
+        version: number;
+    } | undefined;
+}): string;
 export declare function prepareCompaction(deps: CompactionPrepDeps): Promise<CompactionPrepOutcome>;
 export declare function runPostAgentCompaction(deps: PostAgentCompactionDeps): Promise<PostAgentCompactionOutcome>;

package/dist/activities/agent-turn/credential-leases.d.ts

@@ -1,6 +1,7 @@
+import { heartbeatXaiCredentialLeaseUntil } from "@opengeni/db";
 import type { SharedActivityServices } from "../types.js";
-export type LeaseRenewReason = "timer" | "runtime_event" | "model_usage";
-export type LeaseLossReason = "deadline" | "not_found";
+import { SubscriptionTurnLease, type LeaseRenewReason, type LeaseLossReason } from "./subscription-lease.js";
+export type { LeaseRenewReason, LeaseLossReason } from "./subscription-lease.js";
 export declare class CodexCredentialLeaseLostError extends Error {
     readonly reason: LeaseLossReason;
     readonly code = "codex_credential_lease_lost";
@@ -19,45 +20,30 @@ export type TurnCredentialLeaseDeps = {
  * cross-replica fairness primitive; the heartbeat here only extends its short
  * TTL. A killed worker stops heartbeating and the holder self-expires.
  */
-export declare class CodexTurnLease {
-    private readonly deps;
-    held: boolean;
-    lost: boolean;
-    lossReason: LeaseLossReason | null;
-    holderId: string | null;
-    generation: number | null;
-    confirmedUntilMs: number | null;
-    private heartbeatInFlight;
-    private heartbeatTimer;
+export declare class CodexTurnLease extends SubscriptionTurnLease {
     constructor(deps: TurnCredentialLeaseDeps);
-    markLost: (reason: LeaseLossReason) => void;
-    /** Fail closed at the last worker-confirmed lease deadline before dispatch. */
-    assertUsable: () => void;
-    renew: (reason: LeaseRenewReason) => Promise<void>;
-    startHeartbeat: () => void;
-    stopHeartbeat: () => void;
 }
-/** The xAI/SuperGrok credential holder for one running turn; same shape. */
-export declare class XaiTurnLease {
-    private readonly deps;
-    held: boolean;
-    lost: boolean;
+/** Scoped subscriptions share the existing holder and monotonic deadline implementation. */
+declare class ScopedSubscriptionTurnLease extends SubscriptionTurnLease {
     subjectId: string | null;
-    holderId: string | null;
-    generation: number | null;
-    confirmedUntilMs: number | null;
-    private heartbeatInFlight;
-    private heartbeatTimer;
+    constructor(deps: TurnCredentialLeaseDeps, provider: {
+        name: string;
+        code: string;
+        ttlMs: number;
+        heartbeat: typeof heartbeatXaiCredentialLeaseUntil;
+    });
+}
+export declare class XaiTurnLease extends ScopedSubscriptionTurnLease {
+    constructor(deps: TurnCredentialLeaseDeps);
+}
+export declare class ClaudeTurnLease extends ScopedSubscriptionTurnLease {
     constructor(deps: TurnCredentialLeaseDeps);
-    markLost: (reason: LeaseLossReason) => void;
-    renew: () => Promise<void>;
-    startHeartbeat: () => void;
-    stopHeartbeat: () => void;
 }
-/** Both serving-credential leases for one turn attempt plus their composite views. */
+/** Serving-credential leases for one turn attempt plus their composite views. */
 export type TurnCredentialLeases = {
     codex: CodexTurnLease;
     xai: XaiTurnLease;
+    claude: ClaudeTurnLease;
     renewServing: (reason: LeaseRenewReason) => Promise<void>;
     servingLost: () => boolean;
 };

package/dist/activities/agent-turn/credential-restriction.d.ts

@@ -0,0 +1,3 @@
+import { type TurnExecutionPolicyV1 } from "@opengeni/contracts";
+/** Only accepted policies establish the ceiling; ordinary metadata is not authority. */
+export declare function turnCredentialRestriction(acceptedPolicy: TurnExecutionPolicyV1, initialSessionMetadata: unknown): "developer_setup" | undefined;

package/dist/activities/agent-turn/errors.d.ts

@@ -1,3 +1,4 @@
+import { type CompactionProviderRejection, type MaterializationVerificationDiagnostic, type ProviderQuotaExhaustion, type ProviderQuotaScope } from "@opengeni/runtime";
 import { type McpTransportRequestFailureDiagnostic } from "@opengeni/runtime/mcp-network";
 import { ApplicationFailure } from "@temporalio/activity";
 import type { CodexAccountStatus } from "@opengeni/db";
@@ -6,6 +7,12 @@ import { type MandatoryHistoryPersistenceStage } from "./quiescence.js";
 export declare const PROVIDER_BACKPRESSURE_DELAY_MS = 60000;
 export declare const PROVIDER_CONNECTIVITY_BACKOFF_MS: readonly [2000, 5000, 15000, 30000, 60000];
 export declare const MAX_AUTOMATIC_PROVIDER_RECOVERIES: 5;
+/**
+ * Minimum wait per rate-limited recovery. Providers such as Azure OpenAI often
+ * answer a per-minute token limit with a `retry-after` of about a second, which
+ * alone would spend every automatic recovery before the window resets.
+ */
+export declare const PROVIDER_RATE_LIMIT_BACKOFF_MS: readonly [10000, 20000, 40000, 60000, 120000];
 export declare const POST_COMPACTION_CONTINUATION_EMPTY_CODE = "post_compaction_continuation_empty";
 export declare class PostCompactionContinuationEmptyError extends Error {
     readonly code = "post_compaction_continuation_empty";
@@ -67,23 +74,26 @@ export declare function escapedMcpTimeoutRecoveryFailure(input: {
  * Convert the atomic claim transaction's failure into a small, stable
  * Temporal wire contract. The original error remains in activity diagnostics,
  * but SQL text, parameters, and arbitrary invariant messages never enter
- * workflow history. Every database failure is safe to re-read after backoff
- * because the claim transaction contains no model/tool effects. Database
- * constraints and authorization guards can also be repaired by a deployment or
- * authority refresh, so they must preserve pending work. Only a non-database
- * claim invariant is terminal.
+ * workflow history. Operational failures retry; other persistence rejections
+ * retain accepted work behind a durable explicit-recheck fence. Repeating the
+ * same rejected transaction without changed conditions is not recovery.
  */
 export declare function preClaimAdmissionFailure(error: unknown): ApplicationFailure;
 /**
- * Carry one exact claimed-but-not-started attempt into the workflow's DB-only
- * recovery lane. Permanent database/state failures remain terminal; only the
- * same operational outage classes that are safe before claim are admitted.
+ * Carry one exact claimed attempt into the workflow's DB-only
+ * recovery lane. Permanent database/state failures remain terminal. The
+ * running-turn lane additionally requires a closed own-client outage class;
+ * existing pre-execution recovery classifications are unchanged.
  */
 export declare function postClaimDatabaseRecoveryFailure(input: {
     error: unknown;
     turnId: string;
     triggerEventId: string;
     executionGeneration: number;
+    /** Require an actual own-client boundary and the closed running-turn allowlist. */
+    requireDatabaseProvenance?: boolean;
+    sandboxSetupOutcomeUnknown?: true;
+    sandboxSetupRecoveryExhausted?: true;
     providerRecovery?: {
         failureCode: string;
         providerRecoveryCount: number;
@@ -109,8 +119,17 @@ export type SandboxLifecycleTransitionDiagnostic = {
  * cross-package error object is accepted.
  */
 export declare function sandboxLifecycleTransitionDiagnostic(error: unknown): SandboxLifecycleTransitionDiagnostic | null;
+export declare function modelPreparationFailureEventPayload(error: unknown, durationMs: number): {
+    phase: string;
+    durationMs: number;
+    expectedTransition: boolean;
+    failureCategory?: string;
+    failureStage?: string;
+    failureCode?: "capture_in_progress" | "provider_recovery_in_progress" | "rotation_in_progress";
+    retryable?: boolean;
+};
 /**
- * Recognize the one active-route transition that cannot finish inside its
+ * Recognize active-route transitions that cannot finish inside their
  * originating attempt. A Modal-home session may start on a Connected Machine
  * without creating or leasing its managed home box. When an explicit attach
  * clears the active pointer back to home, the pointer commit is authoritative,
@@ -121,7 +140,7 @@ export declare function sandboxLifecycleTransitionDiagnostic(error: unknown): Sa
  * only those structural error links with a strict bound; never classify from
  * message text, which could originate in model or tool content.
  */
-export declare function sandboxRouteTransitionCode(error: unknown): "home_unavailable_this_turn" | "workspace_root_changed_this_turn" | null;
+export declare function sandboxRouteTransitionCode(error: unknown): "home_unavailable_this_turn" | "workspace_root_changed_this_turn" | "native_capabilities_changed_this_attempt" | null;
 export declare function isSandboxRouteTransitionError(error: unknown): boolean;
 /** Backward-compatible name for callers/tests that only exercised the original
  * machine-to-home transition. */
@@ -147,7 +166,30 @@ export type SafeErrorDiagnostic = {
  */
 export declare function safeErrorDiagnostic(error: unknown): SafeErrorDiagnostic;
 export declare function safeErrorForTelemetry(error: unknown): Error;
+/**
+ * Guidance appended to a definitive provider rejection. Repeating the exact
+ * request cannot succeed, so the generic "send another message to retry"
+ * advice is wrong here: a new prompt re-sends the same rejected history.
+ */
+export declare const COMPACTION_PROVIDER_REJECTION_GUIDANCE = "The provider refused this exact request, so repeating it fails the same way until the conversation changes. If a new message fails again, start a new session.";
 export declare function compactionFailureReasonFromError(error: unknown): string;
+/**
+ * Exact `turn.failed` payload for a terminal compaction failure. A definitive
+ * provider rejection additionally carries its closed identifier record so the
+ * timeline, API consumers, and operators can name the rejected field without
+ * parsing the message.
+ */
+export declare function compactionFailureTurnEventPayload(error: unknown, overrides?: {
+    error?: string;
+}): {
+    error: string;
+    code: "context_compaction_failed";
+    retryable: false;
+    recovery: "user_message";
+    compacted: false;
+    providerRejection?: CompactionProviderRejection;
+    quotaScope?: ProviderQuotaScope;
+};
 export declare function isCompactionSummaryFailure(error: unknown): boolean;
 export declare function shouldRecoverCompactionProviderFailure(error: unknown): boolean;
 export declare function classifyContextWindowOverflowError(error: unknown): {
@@ -214,6 +256,15 @@ export declare function collectErrorStrings(value: unknown, seen?: WeakSet<objec
 export declare const STATUSLESS_UPSTREAM_CONNECTIVITY_MESSAGE = "unable to connect. is the computer able to access the url?";
 export declare function isExactStatuslessUpstreamConnectivityMessage(message: string): boolean;
 export declare function isTransientProviderError(error: unknown): boolean;
+/**
+ * Recognize an exhausted API-key provider quota (a daily or monthly allowance,
+ * a free-tier day cap, or an account out of credits) as distinct from an
+ * ordinary per-minute rate limit. Retrying within the bounded same-turn budget
+ * cannot succeed, so the turn fails promptly instead. Subscription transports
+ * own their quota semantics through credential rotation and durable capacity
+ * waits, so a Codex or SuperGrok transport error never classifies here.
+ */
+export declare function classifyProviderQuotaExhaustionError(error: unknown): ProviderQuotaExhaustion | null;
 export type XaiCredentialFailure = {
     kind: "auth" | "forbidden" | "rate_limit";
     cooldownMs: number | null;
@@ -227,6 +278,11 @@ export type XaiCredentialFailure = {
 export declare function classifyXaiCredentialFailure(error: unknown): XaiCredentialFailure | null;
 export declare function agentRunFailurePayload(error: unknown, options?: {
     isCodexTurn?: boolean;
+}): ReturnType<typeof baseAgentRunFailurePayload>;
+/** Keep Anthropic provider text on terminal failures, never recovery events. */
+export declare function agentRunRecoveryFailurePayload(error: unknown, failure: ReturnType<typeof agentRunFailurePayload>): ReturnType<typeof agentRunFailurePayload>;
+declare function baseAgentRunFailurePayload(error: unknown, options?: {
+    isCodexTurn?: boolean;
 }): {
     error: string;
     code?: string;
@@ -246,9 +302,19 @@ export declare function agentRunFailurePayload(error: unknown, options?: {
     database?: Record<string, string>;
     historyPersistenceStage?: MandatoryHistoryPersistenceStage;
     mcpTransportDiagnostic?: McpTransportRequestFailureDiagnostic;
+    materializationDiagnostic?: MaterializationVerificationDiagnostic;
+    quotaScope?: ProviderQuotaScope;
+    /** Closed Codex plan key on `codex_plan_entitlement` / `codex_request_rejected`. */
+    planType?: string | null;
+    /** Product model id a `codex_plan_entitlement` failure refers to. */
+    model?: string | null;
 };
 export type CodexCredentialFailure = {
-    kind: "auth" | "forbidden" | "rate_limit" | "quota";
+    /**
+     * `plan_entitlement` is produced only after a plan re-check proves the
+     * serving account's current plan does not include the requested model.
+     */
+    kind: "auth" | "forbidden" | "rate_limit" | "quota" | "plan_entitlement";
     cooldownSeconds: number | null;
 };
 export declare const CODEX_ALLOWANCE_FALLBACK_MS: number;
@@ -285,3 +351,8 @@ export declare function codexUsageLimitFailurePayload(info: {
     detail?: string;
 };
 export declare const CODEX_USAGE_LIMIT_MAX_RESUME_MS: number;
+/** Only typed provider backpressure or a verified reconnect requirement can rotate Claude. */
+export declare function classifyClaudeCredentialFailure(error: unknown): (XaiCredentialFailure & {
+    requestId?: string;
+}) | null;
+export {};