@opengeni/worker-bundle 0.20.1 → 0.22.0-canary.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/dist/activities/agent-turn/admission.d.ts +52 -0
  2. package/dist/activities/agent-turn/agent-build.d.ts +89 -0
  3. package/dist/activities/agent-turn/claim.d.ts +67 -0
  4. package/dist/activities/agent-turn/codex-capacity.d.ts +40 -0
  5. package/dist/activities/agent-turn/codex.d.ts +32 -0
  6. package/dist/activities/agent-turn/compaction-prep.d.ts +88 -0
  7. package/dist/activities/agent-turn/credential-leases.d.ts +56 -0
  8. package/dist/activities/agent-turn/errors.d.ts +253 -0
  9. package/dist/activities/agent-turn/failure-settlement.d.ts +33 -0
  10. package/dist/activities/agent-turn/file-resources.d.ts +37 -0
  11. package/dist/activities/agent-turn/finalization.d.ts +42 -0
  12. package/dist/activities/agent-turn/github-repository-bindings.d.ts +105 -0
  13. package/dist/activities/agent-turn/governance-model.d.ts +66 -0
  14. package/dist/activities/agent-turn/history-sink.d.ts +52 -0
  15. package/dist/activities/agent-turn/history.d.ts +63 -0
  16. package/dist/activities/agent-turn/media-artifacts.d.ts +145 -0
  17. package/dist/activities/agent-turn/model-usage.d.ts +218 -0
  18. package/dist/activities/agent-turn/quiescence.d.ts +135 -0
  19. package/dist/activities/agent-turn/run-credentials.d.ts +84 -0
  20. package/dist/activities/agent-turn/run.d.ts +3 -0
  21. package/dist/activities/agent-turn/sandbox-establish.d.ts +93 -0
  22. package/dist/activities/agent-turn/sandbox-provision.d.ts +89 -0
  23. package/dist/activities/agent-turn/sandbox-route.d.ts +151 -0
  24. package/dist/activities/agent-turn/sandbox-runtime.d.ts +44 -0
  25. package/dist/activities/agent-turn/stream-attempt.d.ts +107 -0
  26. package/dist/activities/agent-turn/tool-environment.d.ts +142 -0
  27. package/dist/activities/agent-turn/tool-policy.d.ts +127 -0
  28. package/dist/activities/agent-turn/tool-result-spill.d.ts +59 -0
  29. package/dist/activities/agent-turn/turn-context.d.ts +144 -0
  30. package/dist/activities/agent-turn/xai-capacity.d.ts +2 -0
  31. package/dist/activities/agent-turn.d.ts +12 -954
  32. package/dist/activities/automations.d.ts +16 -0
  33. package/dist/activities/common.d.ts +1 -1
  34. package/dist/activities/connector-attachments.d.ts +13 -0
  35. package/dist/activities/documents.d.ts +1 -0
  36. package/dist/activities/environment.d.ts +26 -15
  37. package/dist/activities/generated-images.d.ts +1 -1
  38. package/dist/activities/git-credential-renewal.d.ts +3 -1
  39. package/dist/activities/goals.d.ts +4 -1
  40. package/dist/activities/google-drive-provider.d.ts +29 -0
  41. package/dist/activities/google-drive-publication.d.ts +66 -0
  42. package/dist/activities/image-generation-references.d.ts +2 -0
  43. package/dist/activities/incident-telemetry-authority.d.ts +52 -0
  44. package/dist/activities/incident-telemetry-preflight.d.ts +71 -0
  45. package/dist/activities/knowledge-source-sync-driver.d.ts +21 -0
  46. package/dist/activities/knowledge-source-sync.d.ts +33 -1
  47. package/dist/activities/mcp-credentials.d.ts +9 -3
  48. package/dist/activities/open-suffix-resume.d.ts +77 -0
  49. package/dist/activities/packs.d.ts +3 -11
  50. package/dist/activities/parent-wake.d.ts +19 -0
  51. package/dist/activities/retained-screenshot-reaper.d.ts +1 -1
  52. package/dist/activities/retained-screenshots.d.ts +1 -1
  53. package/dist/activities/rig-verification.d.ts +1 -1
  54. package/dist/activities/run-input.d.ts +16 -7
  55. package/dist/activities/sandbox-images.d.ts +1 -14
  56. package/dist/activities/sandbox-lease.d.ts +21 -3
  57. package/dist/activities/scheduled-tasks.d.ts +47 -0
  58. package/dist/activities/types.d.ts +23 -2
  59. package/dist/activities/video-media-validation.d.ts +1 -1
  60. package/dist/activities/video-output-retention.d.ts +1 -2
  61. package/dist/activities/xai-auth.d.ts +3 -0
  62. package/dist/{activities-control-SMKF2OBE.js → activities-control-DKG22ONJ.js} +2946 -549
  63. package/dist/activities-control-DKG22ONJ.js.map +1 -0
  64. package/dist/activities-control.d.ts +6 -2
  65. package/dist/activities-turn-4IMC3MAA.js +21326 -0
  66. package/dist/activities-turn-4IMC3MAA.js.map +1 -0
  67. package/dist/activities.d.ts +7 -3
  68. package/dist/artifact-materializer-entry.js +41 -22
  69. package/dist/artifact-materializer-entry.js.map +1 -1
  70. package/dist/{chunk-N5TJIFCE.js → chunk-CE7TPKBS.js} +468 -1
  71. package/dist/chunk-CE7TPKBS.js.map +1 -0
  72. package/dist/chunk-CNYGVRKF.js +4698 -0
  73. package/dist/chunk-CNYGVRKF.js.map +1 -0
  74. package/dist/connection-provider-use.d.ts +18 -0
  75. package/dist/editable-artifact-materializer.d.ts +4 -3
  76. package/dist/github-rest-mcp.d.ts +26 -0
  77. package/dist/index.d.ts +10 -2
  78. package/dist/index.js +58 -14
  79. package/dist/index.js.map +1 -1
  80. package/dist/knowledge-source-sync-activity-policy.d.ts +2 -0
  81. package/dist/model-context-contributions.d.ts +8 -4
  82. package/dist/observability-metrics.d.ts +63 -4
  83. package/dist/opensandbox-kubernetes-inventory.d.ts +21 -0
  84. package/dist/personal-github-git-credentials.d.ts +9 -0
  85. package/dist/pr-review-credentials.d.ts +6 -0
  86. package/dist/sandbox-archive-storage.d.ts +45 -0
  87. package/dist/sandbox-resume.d.ts +65 -6
  88. package/dist/sandbox-routing.d.ts +38 -2
  89. package/dist/scheduled-alert-occurrence.d.ts +33 -0
  90. package/dist/workflow-bundle.js +87 -28
  91. package/dist/workflows/activities.d.ts +1 -0
  92. package/dist/workflows/automations.d.ts +6 -0
  93. package/dist/workflows/document-index.d.ts +1 -0
  94. package/dist/workflows.d.ts +1 -0
  95. package/package.json +17 -17
  96. package/src/activities/agent-turn/admission.ts +292 -0
  97. package/src/activities/agent-turn/agent-build.ts +802 -0
  98. package/src/activities/agent-turn/claim.ts +590 -0
  99. package/src/activities/agent-turn/codex-capacity.ts +720 -0
  100. package/src/activities/agent-turn/codex.ts +94 -0
  101. package/src/activities/agent-turn/compaction-prep.ts +722 -0
  102. package/src/activities/agent-turn/credential-leases.ts +240 -0
  103. package/src/activities/agent-turn/errors.ts +1068 -0
  104. package/src/activities/agent-turn/failure-settlement.ts +1436 -0
  105. package/src/activities/agent-turn/file-resources.ts +227 -0
  106. package/src/activities/agent-turn/finalization.ts +754 -0
  107. package/src/activities/agent-turn/github-repository-bindings.ts +300 -0
  108. package/src/activities/agent-turn/governance-model.ts +465 -0
  109. package/src/activities/agent-turn/history-sink.ts +139 -0
  110. package/src/activities/agent-turn/history.ts +200 -0
  111. package/src/activities/agent-turn/media-artifacts.ts +359 -0
  112. package/src/activities/agent-turn/model-usage.ts +823 -0
  113. package/src/activities/agent-turn/quiescence.ts +353 -0
  114. package/src/activities/agent-turn/run-credentials.ts +761 -0
  115. package/src/activities/agent-turn/run.ts +1530 -0
  116. package/src/activities/agent-turn/sandbox-establish.ts +1207 -0
  117. package/src/activities/agent-turn/sandbox-provision.ts +569 -0
  118. package/src/activities/agent-turn/sandbox-route.ts +358 -0
  119. package/src/activities/agent-turn/sandbox-runtime.ts +731 -0
  120. package/src/activities/agent-turn/stream-attempt.ts +1670 -0
  121. package/src/activities/agent-turn/tool-environment.ts +729 -0
  122. package/src/activities/agent-turn/tool-policy.ts +216 -0
  123. package/src/activities/agent-turn/tool-result-spill.ts +265 -0
  124. package/src/activities/agent-turn/turn-context.ts +281 -0
  125. package/src/activities/agent-turn/xai-capacity.ts +229 -0
  126. package/src/activities/agent-turn.ts +12 -12575
  127. package/src/activities/api-integrations.ts +3 -0
  128. package/src/activities/automations.ts +214 -0
  129. package/src/activities/codemode-dispatcher.ts +12 -1
  130. package/src/activities/common.ts +1 -5
  131. package/src/activities/connector-attachments.ts +168 -0
  132. package/src/activities/context-compaction.ts +18 -0
  133. package/src/activities/documents.ts +6 -4
  134. package/src/activities/environment.ts +151 -55
  135. package/src/activities/generated-images.ts +26 -11
  136. package/src/activities/git-credential-renewal.ts +13 -3
  137. package/src/activities/goals.ts +85 -19
  138. package/src/activities/google-drive-provider.ts +178 -0
  139. package/src/activities/google-drive-publication.ts +938 -0
  140. package/src/activities/image-generation-references.ts +11 -2
  141. package/src/activities/incident-telemetry-authority.ts +327 -0
  142. package/src/activities/incident-telemetry-preflight.ts +317 -0
  143. package/src/activities/knowledge-source-sync-driver.ts +23 -0
  144. package/src/activities/knowledge-source-sync.ts +556 -40
  145. package/src/activities/mcp-credentials.ts +191 -17
  146. package/src/activities/open-suffix-resume.ts +422 -0
  147. package/src/activities/packs.ts +12 -60
  148. package/src/activities/parent-wake.ts +64 -14
  149. package/src/activities/retained-screenshot-reaper.ts +6 -3
  150. package/src/activities/retained-screenshots.ts +15 -47
  151. package/src/activities/rig-verification.ts +1 -1
  152. package/src/activities/run-input.ts +128 -136
  153. package/src/activities/sandbox-images.ts +7 -166
  154. package/src/activities/sandbox-lease.ts +406 -15
  155. package/src/activities/scheduled-tasks.ts +2103 -411
  156. package/src/activities/session-state.ts +10 -2
  157. package/src/activities/types.ts +32 -2
  158. package/src/activities/video-media-validation.ts +3 -3
  159. package/src/activities/video-output-retention.ts +2 -57
  160. package/src/activities/xai-auth.ts +8 -0
  161. package/src/activities-control.ts +2 -0
  162. package/src/activities.ts +3 -0
  163. package/src/activity-services.ts +13 -4
  164. package/src/connection-provider-use.ts +36 -0
  165. package/src/editable-artifact-materializer-subprocess.ts +25 -14
  166. package/src/editable-artifact-materializer.ts +29 -18
  167. package/src/github-rest-mcp.ts +713 -0
  168. package/src/http.ts +16 -6
  169. package/src/index.ts +40 -5
  170. package/src/knowledge-source-sync-activity-policy.ts +2 -0
  171. package/src/model-context-contributions.ts +33 -10
  172. package/src/observability-metrics.ts +357 -0
  173. package/src/opensandbox-kubernetes-inventory.ts +292 -0
  174. package/src/personal-github-git-credentials.ts +331 -0
  175. package/src/pr-review-credentials.ts +163 -0
  176. package/src/sandbox-archive-storage.ts +159 -0
  177. package/src/sandbox-resume.ts +449 -63
  178. package/src/sandbox-routing.ts +314 -16
  179. package/src/scheduled-alert-occurrence.ts +176 -0
  180. package/src/workflows/activities.ts +18 -2
  181. package/src/workflows/automations.ts +11 -0
  182. package/src/workflows/session.ts +13 -3
  183. package/src/workflows.ts +1 -0
  184. package/dist/activities-control-SMKF2OBE.js.map +0 -1
  185. package/dist/activities-turn-IDS3WEHA.js +0 -16532
  186. package/dist/activities-turn-IDS3WEHA.js.map +0 -1
  187. package/dist/chunk-N5TJIFCE.js.map +0 -1
  188. package/dist/chunk-P6Z2SLAA.js +0 -3092
  189. package/dist/chunk-P6Z2SLAA.js.map +0 -1
@@ -1,954 +1,12 @@
1
- import { type AppendEventInput, type ActiveSandboxPointer, type SandboxRecord, type SessionAttemptQuiescenceCommit } from "@opengeni/db";
2
- import { modelResponseServiceTierFromSdkEvent, modelTerminalResponseFromSdkEvent, type SandboxFileDownload, type SandboxFileDownloadFailure, type ComputerToolMode, type ModelResponseUsage, type ModelCallUsageInput, type ModelCallUsageNormalization, type TurnToolCancellationFence, type BackendUnresolvableCode, type LazyToolTransport } from "@opengeni/runtime";
3
- import { resolveTurnExecutionPolicyV1, type ModelUsageInput, type ModelProviderApi, type RegistryProviderKind, type Settings } from "@opengeni/config";
4
- import { ApplicationFailure, CancelledFailure } from "@temporalio/activity";
5
- import type { CodexAccountStatus } from "@opengeni/db";
6
- import { type GitCredentialRenewalController } from "./git-credential-renewal.js";
7
- import { type RunCredentialRenewalController } from "./run-credential-renewal.js";
8
- import { type CodemodeTokenRenewalController } from "./codemode-token-renewal.js";
9
- import { type ModelAttachmentInputPolicy } from "./run-input.js";
10
- import type { TurnActivityServices as ActivityServices, EscapedMcpTimeoutRecoveryDetail, RunAgentTurnInput, RunAgentTurnResult, SessionAttemptQuiescenceProof } from "./types.js";
11
- import { type ResumedTurnSandbox, type TurnSandboxLeaseHolderId } from "../sandbox-resume.js";
12
- import { type TurnSandboxEstablishReason } from "../observability-metrics.js";
13
- import { type LatencyMode, type SessionEvent, type SessionEventType, type SessionTurn, type ToolAuthNeededPayload, type TurnExecutionPolicyV1 } from "@opengeni/contracts";
14
- export declare const PROVIDER_BACKPRESSURE_DELAY_MS = 60000;
15
- export declare class WorkspaceHumanInputDisabledError extends Error {
16
- constructor(kind: "resume" | "interruption");
17
- }
18
- export declare function assertWorkspaceHumanInputAllowed(enabled: boolean, kind: "resume" | "interruption", attempted: boolean): void;
19
- /** Broad personal lookup is allowed only for a direct human/API command. */
20
- export declare function credentialSubjectIdForTurnInitiator(turn: Pick<SessionTurn, "source" | "initiator" | "initiatorContext">): string | undefined;
21
- /**
22
- * Direct authenticated-human work is the persisted human source with subject
23
- * authority and no inherited agent or legacy provenance. Use this complete
24
- * immutable turn authority instead of inferring causality from a
25
- * `user.message` event shape or the root initiator alone.
26
- */
27
- export declare function isDirectHumanTurnInitiation(turn: Pick<SessionTurn, "source" | "initiator" | "initiatorContext">): boolean;
28
- /**
29
- * A disconnected personal Slack server is prepared best-effort before the model
30
- * runs. Its initialize/tools-list credential miss is setup state, not evidence
31
- * that an unrelated turn wants Slack. Keep concrete tool-call failures
32
- * actionable, but gate setup-time Slack prompts to a human message that names
33
- * Slack explicitly. Other providers retain the existing generic behavior.
34
- */
35
- export declare function shouldPublishToolAuthNeededForTurn(payload: Pick<ToolAuthNeededPayload, "providerDomain" | "toolName">, trigger: Pick<SessionEvent, "type" | "payload">, turn: Pick<SessionTurn, "source" | "initiator" | "initiatorContext">): boolean;
36
- export declare function turnExecutionPolicyBillingIdentity(policy: TurnExecutionPolicyV1): {
37
- externallyBilled: boolean;
38
- codexSubscription: boolean;
39
- xaiSubscription: boolean;
40
- };
41
- export declare function legacyTurnExecutionPolicyInput(turn: Pick<SessionTurn, "source" | "model" | "reasoningEffort" | "latencyMode">): Parameters<typeof resolveTurnExecutionPolicyV1>[1];
42
- /** A retryable provider fault recovers the accepted turn itself. Goal state is
43
- * irrelevant: autonomous continuation and infrastructure recovery are separate
44
- * concerns. */
45
- export declare function providerRecoveryResult(input: {
46
- failureCode: string | undefined;
47
- attemptNumber: number;
48
- retryAfterMs?: number | null;
49
- }): {
50
- status: "recovering";
51
- continueDelayMs: number;
52
- };
53
- export declare function providerRecoveryCountFromMetadata(metadata: Record<string, unknown>): number;
54
- /** Read a provider Retry-After hint without retaining response headers/body. */
55
- export declare function providerRetryAfterMs(error: unknown, nowMs?: number): number | null;
56
- /**
57
- * Tell the model when durable MCP policy references are unavailable for this
58
- * exact turn. The policy projection already bounds and validates these ids;
59
- * this notice prevents a graceful runtime drop from becoming a silent source-
60
- * of-truth substitution or a false claim that the disconnected system was read.
61
- */
62
- export declare function unavailableMcpTurnInstructions(input: {
63
- droppedIds: readonly string[];
64
- droppedCount: number;
65
- }): string | undefined;
66
- /**
67
- * Preserve one precise recovery obligation across Temporal's activity boundary.
68
- * This is intentionally narrower than the ordinary retryable-provider path:
69
- * only a recovered turn (generation > 1) whose MCP timeout happened before a
70
- * model request may ask the workflow's DB-only control activity to finish the
71
- * same-turn checkpoint. The original transport/recovery errors are excluded
72
- * from details so raw MCP response data can never enter workflow history.
73
- */
74
- export declare function escapedMcpTimeoutRecoveryFailure(input: {
75
- failureCode: string | undefined;
76
- modelRequestStarted: boolean;
77
- detail: EscapedMcpTimeoutRecoveryDetail;
78
- }): ApplicationFailure | null;
79
- /**
80
- * Convert the atomic claim transaction's failure into a small, stable
81
- * Temporal wire contract. The original error remains in activity diagnostics,
82
- * but SQL text, parameters, and arbitrary invariant messages never enter
83
- * workflow history. Contention and operational database unavailability are
84
- * safe to re-read after backoff because the claim transaction contains no
85
- * model/tool effects; permanent database and state failures require terminal
86
- * settlement.
87
- */
88
- export declare function preClaimAdmissionFailure(error: unknown): ApplicationFailure;
89
- /**
90
- * Resolve which Codex account a turn runs on (multi-account P1): session-pin >
91
- * workspace-active. No rotation in P1. The selected id must still be in the
92
- * connected set — a disconnected pin was FK-nulled, so a stale id can't appear,
93
- * but we guard anyway. Returns null when there is no usable account (the turn
94
- * then fails with the existing relogin error path).
95
- */
96
- export declare function selectCodexCredentialForTurn(args: {
97
- sessionPinnedCredentialId: string | null;
98
- activeCredentialId: string | null;
99
- connectedIds: Set<string>;
100
- }): string | null;
101
- export declare function filterUnmaterializedSandboxFileDownloads(downloads: SandboxFileDownload[], materializedFileIds: Set<string>): SandboxFileDownload[];
102
- export declare function sandboxFileMaterializationOutcome(failures: readonly SandboxFileDownloadFailure[]): "completed" | "failed";
103
- /** Fixed-length one-way tenant correlation for metrics/alerts; never a raw id. */
104
- export declare function codexWorkspaceMetricKey(workspaceId: string): string;
105
- /** Stable public request identity across partial resumes and activity retries. */
106
- export declare function stableHumanInputRequestId(sessionId: string, turnId: string, toolCallId: string): string;
107
- export declare function stableInteractionInterventionId(sessionId: string, turnId: string, toolCallId: string): string;
108
- export declare function stableInteractionInterventionOperationId(sessionId: string, turnId: string, toolCallId: string): string;
109
- /**
110
- * True when this activity attempt was cancelled because its hosting worker is
111
- * shutting down gracefully (SIGTERM during a deploy), as opposed to a
112
- * workflow-requested Pause/Steer cancellation or a server-side timeout.
113
- */
114
- export declare function isWorkerShutdownCancellation(error: unknown): boolean;
115
- /**
116
- * Review captures and protective snapshots are cache/persistence housekeeping,
117
- * never part of cancellation correctness. A control-fenced or Temporal-cancelled
118
- * attempt must release its physical activity promptly so Steer/Pause can advance.
119
- */
120
- export declare function shouldRunTurnEndWorkspacePersistence(input: {
121
- activityStatus: RunAgentTurnResult["status"] | "unknown";
122
- cancellationRequested: boolean;
123
- }): boolean;
124
- /**
125
- * Temporal cancellation is delivery/transport state, never proof that the
126
- * dying activity crossed its mandatory sandbox-tool fence. If that fence
127
- * fails, surface the fence failure instead of retaining a misleading typed
128
- * cancellation; replacement admission remains closed because no durable
129
- * quiescence receipt was written.
130
- */
131
- export declare function assertPhysicalToolQuiescenceForCancellation(input: {
132
- acknowledgeQuiescence: boolean;
133
- physicalToolQuiescenceConfirmed: boolean;
134
- failure: unknown;
135
- }): void;
136
- /** A physically drained attempt must leave one durable recovery producer. The
137
- * direct Postgres receipt is preferred; after its bounded retries exhaust, an
138
- * exact Temporal proof signal is sufficient because the workflow persists it
139
- * through an independently retrying DB-only control activity. */
140
- export declare function assertSessionAttemptQuiescenceRecoveryDurable(input: {
141
- acknowledgeQuiescence: boolean;
142
- physicalToolQuiescenceConfirmed: boolean;
143
- receiptOrProofDurable: boolean;
144
- failure: unknown;
145
- }): void;
146
- /** Persist the authoritative receipt or durably hand the exact physical proof
147
- * to Temporal. This retries signal delivery, not DB eligibility or workflow
148
- * state. The proof object never changes between attempts. */
149
- export declare function persistOrSignalSessionAttemptQuiescence(input: {
150
- proof: SessionAttemptQuiescenceProof;
151
- persistReceipt: () => Promise<SessionAttemptQuiescenceCommit>;
152
- deliverWorkflowWake?: (wake: NonNullable<SessionAttemptQuiescenceCommit["workflowWake"]>) => Promise<unknown>;
153
- publishEvents: (events: SessionEvent[]) => Promise<unknown>;
154
- signalProof: ActivityServices["signalSessionAttemptQuiesced"];
155
- sleep?: (ms: number) => Promise<void>;
156
- heartbeat?: (attempt: number, delayMs: number) => void;
157
- onReceiptFailure?: (error: unknown) => void;
158
- onWakeFailure?: (error: unknown) => void;
159
- onPublishFailure?: (error: unknown) => void;
160
- onSignalFailure?: (error: unknown, attempt: number, delayMs: number) => void;
161
- }): Promise<"receipt" | "signal">;
162
- /**
163
- * Cross the non-detachable physical boundary for one dying attempt. Temporal's
164
- * cancellation signal is intentionally absent: cancellation is transport, not
165
- * proof that sandbox tools and attempt-owned credential writers have drained.
166
- * A replacement may be admitted only after this function resolves and the
167
- * caller durably persists or signals the exact quiescence receipt.
168
- */
169
- export declare function drainAttemptOwnedSandboxWriters(input: {
170
- toolCancellationFence: Pick<TurnToolCancellationFence, "cancel" | "waitForQuiescence"> | null;
171
- cancellationReason?: unknown;
172
- gitCredentialRenewals: readonly Pick<GitCredentialRenewalController, "stop">[];
173
- codemodeTokenRenewal: Pick<CodemodeTokenRenewalController, "stop"> | null;
174
- runCredentialRenewal: Pick<RunCredentialRenewalController, "stop"> | null;
175
- }): Promise<void>;
176
- /** Persist the exact turn's second-stage release only after the caller has
177
- * crossed the physical writer boundary. This wait is intentionally independent
178
- * of Temporal cancellation: it is a short idempotent DB transaction that closes
179
- * the durable archive-capture fence. Bounded retries cover a rollout connection
180
- * reset without turning ordinary finalizer housekeeping into lifecycle state. */
181
- export declare function releaseTurnSandboxAfterWriterDrain(sandbox: Pick<ResumedTurnSandbox, "release">, options?: {
182
- maxAttempts?: number;
183
- retryDelayMs?: number;
184
- wait?: (delayMs: number) => Promise<void>;
185
- }): Promise<void>;
186
- /**
187
- * Await a finalizer operation only while this Temporal activity still owns its
188
- * execution window. Once Pause/Steer cancellation arrives, the operation keeps
189
- * its own rejection handler and may finish its idempotent, attempt-scoped
190
- * cleanup in the background, but it cannot pin activity terminalization or
191
- * delay the separately receipt-gated replacement dispatch.
192
- */
193
- export declare function waitForTurnFinalizerStep<T>(operation: Promise<T>, signal: AbortSignal | undefined): Promise<T | undefined>;
194
- /**
195
- * Flush provider-facing stream state while the attempt still owns its activity
196
- * window. On Pause/Steer, both promises are detached with rejection handlers:
197
- * neither a runtime batcher nor an uncooperative provider completion promise
198
- * may pin the activity behind cancellation after durable writes are fenced.
199
- */
200
- export declare function waitForTurnStreamCleanup(batcherFlush: Promise<unknown>, providerCompleted: Promise<unknown>, signal: AbortSignal | undefined): Promise<void>;
201
- /**
202
- * Terminal settlement closes the active attempt before turn finalization. The
203
- * ordinary workspace admission therefore correctly returns `attempt_fenced`
204
- * for the final attempt-qualified credential deletion. Retry only that exact
205
- * settled-attempt case directly; every other fence/status and the direct
206
- * deletion itself remain fail-closed.
207
- */
208
- export declare function clearAttemptCredentialsWithSettledFence(input: {
209
- activityStatus: RunAgentTurnResult["status"] | "unknown";
210
- runWorkspaceFencedClear: () => Promise<void>;
211
- clearExactAttempt: () => Promise<void>;
212
- onSettledAttemptFence: () => void;
213
- }): Promise<void>;
214
- export type MandatoryHistoryPersistenceStage = "history_append" | "sandbox_envelope";
215
- /**
216
- * Preserve the exact storage failure for the permission-controlled turn event
217
- * while attaching only a stable, non-secret operation token to public worker
218
- * diagnostics. Mandatory history failures remain terminal and never inherit a
219
- * provider-retry classification from coincidental source text or status.
220
- */
221
- export declare class MandatoryHistoryPersistenceError extends Error {
222
- readonly stage: MandatoryHistoryPersistenceStage;
223
- readonly name = "MandatoryHistoryPersistenceError";
224
- readonly cause: unknown;
225
- constructor(stage: MandatoryHistoryPersistenceStage, cause: unknown);
226
- }
227
- export declare function runMandatoryHistoryPersistenceStep<T>(stage: MandatoryHistoryPersistenceStage, operation: () => Promise<T>): Promise<T>;
228
- export type SafeErrorDiagnostic = {
229
- errorClass: "WorkerOperationError";
230
- errorCode: "worker_operation_failed";
231
- status?: number;
232
- origin: "worker";
233
- historyPersistenceStage?: MandatoryHistoryPersistenceStage;
234
- };
235
- /**
236
- * Produce the only exception shape allowed in worker logs. It deliberately
237
- * excludes the arbitrary source message, stack, cause, response/request
238
- * bodies, and enumerable properties. Exact failure content belongs in the
239
- * permission-controlled session event, not stdout or telemetry.
240
- */
241
- export declare function safeErrorDiagnostic(error: unknown): SafeErrorDiagnostic;
242
- export declare function shouldRecoverCompactionProviderFailure(error: unknown): boolean;
243
- export declare function classifyContextWindowOverflowError(error: unknown): {
244
- message: string;
245
- code?: string;
246
- detail?: string;
247
- } | null;
248
- /**
249
- * Recognize an MCP transport/request timeout that escaped the SDK's per-tool
250
- * `mcpConfig.errorFunction` boundary. A thrown tool invocation is normally
251
- * converted to an `{isError:true}` tool output; however, connect/tools-list or
252
- * next-loop transport work can reject the stream iterator after a prior tool
253
- * output was already published. That is transient external backpressure, not a
254
- * terminal session error. Match MCP-qualified timeout text only: an unrelated
255
- * sandbox/model timeout and MCP's application-defined Authentication required signal must
256
- * retain their existing semantics.
257
- */
258
- export declare function classifyMcpTransportTimeoutError(error: unknown): {
259
- message: string;
260
- detail?: string;
261
- } | null;
262
- /**
263
- * Compute the conversation-truth rows a reconcile pass should append, given the
264
- * SDK's current `state.history` and the count already persisted.
265
- *
266
- * `state.history` is a computed getter that runs the SDK's orphan-tool-call
267
- * pruning on every access, so it is non-monotonic: a `function_call` with no
268
- * settling result yet is transiently absent and a later access yields a
269
- * different, possibly shorter/reordered list. The old code sliced this list by
270
- * a blind length watermark and appended at fixed positions with
271
- * onConflictDoNothing, which could freeze a position with one shape and later
272
- * persist a `function_call_result` whose `function_call` had been pruned away in
273
- * an earlier slice — the orphaned tool output that 400s the Responses API and
274
- * bricks the session on every replay.
275
- *
276
- * Defending: structurally repair the full current history into an API-valid sequence (the
277
- * same pure rules the read path uses), then append only the new tail beyond the
278
- * watermark. A trailing dangling call is dropped here and re-evaluated next
279
- * pass once its result lands, so a call and its result are written together at
280
- * consecutive positions and a result is never persisted without its call. The
281
- * watermark advances to the repaired length — never past anything unwritten —
282
- * so a non-monotonic history can never desync it. When previously-persisted
283
- * rows already exceed the repaired length (e.g. legacy orphans written before
284
- * this fix), nothing new is appended and the watermark holds steady.
285
- */
286
- /**
287
- * Stable+unique usage source key for one model call, used to build the per-call
288
- * idempotency key (`usage:model.tokens:${turnId}:${sourceKey}`). The turnId is
289
- * shared across a new attempt of the SAME turn (recovery, approval
290
- * rerun, activity retry), so the sourceKey alone must distinguish calls.
291
- *
292
- * - A provider responseId is globally stable+unique, so reuse it verbatim: a
293
- * true activity retry that re-emits the same responseId correctly DEDUPES
294
- * (one charge), while two distinct calls get distinct ids.
295
- * - Without a responseId the old synthesized key was only POSITIONAL ("response-1",
296
- * "aggregate"), which collides across a re-dispatch — dispatch B's first
297
- * call reuses dispatch A's "response-1" key and its charge is silently
298
- * dropped (undercharge). Qualifying the synthesized key with the
299
- * per-execution dispatch id (the Temporal activityId, unique per scheduled
300
- * execution) makes re-dispatched calls distinct while still deduping a
301
- * same-execution retry.
302
- */
303
- export declare function modelUsageSourceKey(input: {
304
- responseId?: string | null | undefined;
305
- dispatchId: string | null;
306
- positionalKey: string;
307
- }): string;
308
- export declare function providerContextTokens(usage: {
309
- inputTokens?: number;
310
- outputTokens?: number;
311
- totalTokens?: number;
312
- } | null | undefined): number | null;
313
- /**
314
- * A provider call has already consumed tokens by the time its usage frame is
315
- * available. Losing the Codex credential lease at the renewal checkpoint must
316
- * stop the result from becoming authoritative, but it must not erase accounting
317
- * truth for the call that already happened. Meter first, then surface the lost
318
- * lease, then write attempt-owned token/context signals. A replaced attempt can
319
- * reject those signals without erasing the provider usage already incurred.
320
- */
321
- export declare function recordCompletedModelCallBeforeOwnershipFences(input: {
322
- renewLease: () => Promise<void>;
323
- recordUsage: () => Promise<void>;
324
- leaseLost: () => boolean;
325
- leaseLostMessage: string;
326
- recordAttemptSignals?: () => Promise<void>;
327
- }): Promise<void>;
328
- type TurnEventPublisher = (events: Array<Omit<AppendEventInput, "producerId" | "producerSeq" | "turnId">>, immediate?: boolean) => Promise<{
329
- events: SessionEvent[];
330
- accepted: boolean;
331
- }>;
332
- export type ModelResponseEventState = {
333
- responseCount: number;
334
- contextSignal: {
335
- revision: number;
336
- totalTokens: number;
337
- } | null;
338
- claimedSourceKeys: Set<string>;
339
- };
340
- export type CompactionModelUsageEventState = {
341
- usageCount: number;
342
- claimedSourceKeys: Set<string>;
343
- };
344
- export declare function createModelResponseEventState(claimedSourceKeys?: Set<string>): ModelResponseEventState;
345
- export declare function createCompactionModelUsageEventState(claimedSourceKeys?: Set<string>): CompactionModelUsageEventState;
346
- export declare function modelResponseContextSignal(state: ModelResponseEventState): {
347
- revision: number;
348
- totalTokens: number;
349
- } | null;
350
- export declare function assertModelResponseLatencyMode(input: {
351
- event: Parameters<typeof modelResponseServiceTierFromSdkEvent>[0];
352
- requested: LatencyMode;
353
- model: string;
354
- /** When set to Codex ChatGPT auth, response `service_tier` is not an honor signal. */
355
- providerId?: string;
356
- }): void;
357
- /**
358
- * Process one SDK terminal-response event through the production authority path.
359
- *
360
- * The pinned Responses SDK mirrors one provider terminal response as both a
361
- * normalized `response_done` and a raw `model/response.completed` event. Claim
362
- * the stable response/source key before lease renewal or any side effect, and
363
- * use that one positional ordinal for both response identity and same-run
364
- * context binding. A response without usage still clears attempt-owned token
365
- * state. When usage exists, the durable `agent.model.usage` source-key fence
366
- * remains the cross-restart authority: a replay may retry the idempotent billing
367
- * write, but it cannot advance metrics, context, or attempt-owned signals.
368
- */
369
- export declare function processModelResponseTerminalEvent(input: {
370
- event: Parameters<typeof modelTerminalResponseFromSdkEvent>[0];
371
- state: ModelResponseEventState;
372
- dispatchId: string | null;
373
- settings: Settings;
374
- db: ActivityServices["db"];
375
- observability: ActivityServices["observability"];
376
- publish: TurnEventPublisher | null;
377
- accountId: string;
378
- workspaceId: string;
379
- sessionId: string;
380
- turnId: string;
381
- turnAttemptId: string;
382
- provider: string;
383
- providerApi: ModelProviderApi;
384
- model: string;
385
- latencyMode?: LatencyMode;
386
- metricProvider: string;
387
- externallyBilled: boolean;
388
- servingCredentialId: string | null;
389
- priorSessionCredentialId: string | null;
390
- emittedSourceKeys: Set<string>;
391
- renewLease: () => Promise<void>;
392
- leaseLost: () => boolean;
393
- leaseLostMessage: string;
394
- setLastInputTokens: (tokens: number | null) => Promise<void>;
395
- }): Promise<{
396
- status: "not_response";
397
- } | {
398
- status: "duplicate";
399
- sourceKey: string;
400
- } | {
401
- status: "processed";
402
- sourceKey: string;
403
- authoritative: boolean;
404
- usageReported: boolean;
405
- }>;
406
- /**
407
- * Apply the same source-key authority ordering to the compaction summarizer's
408
- * usage callback. The summarizer can retry or mirror a terminal response just
409
- * like the main stream, so claim before lease renewal, billing, durable usage,
410
- * logging, or cache metrics. Durable source-key idempotency remains the
411
- * cross-process authority after a worker restart.
412
- */
413
- export declare function processCompactionModelUsageEvent(input: {
414
- usage: ModelResponseUsage;
415
- state: CompactionModelUsageEventState;
416
- dispatchId: string | null;
417
- settings: Settings;
418
- db: ActivityServices["db"];
419
- observability: ActivityServices["observability"];
420
- publish: TurnEventPublisher | null;
421
- accountId: string;
422
- workspaceId: string;
423
- sessionId: string;
424
- turnId: string;
425
- turnAttemptId: string;
426
- provider: string;
427
- providerApi: ModelProviderApi;
428
- model: string;
429
- externallyBilled: boolean;
430
- servingCredentialId: string | null;
431
- priorSessionCredentialId: string | null;
432
- emittedSourceKeys: Set<string>;
433
- renewLease: () => Promise<void>;
434
- leaseLost: () => boolean;
435
- leaseLostMessage: string;
436
- }): Promise<{
437
- status: "duplicate";
438
- sourceKey: string;
439
- } | {
440
- status: "processed";
441
- sourceKey: string;
442
- authoritative: boolean;
443
- }>;
444
- export declare function emitModelCallUsage(input: {
445
- observability: ActivityServices["observability"];
446
- publish: TurnEventPublisher | null;
447
- accountId: string;
448
- workspaceId: string;
449
- sessionId: string;
450
- turnId: string;
451
- provider: string;
452
- providerApi: ModelProviderApi;
453
- model: string;
454
- sourceKey: string;
455
- usage: ModelResponseUsage | {
456
- usage?: unknown | null;
457
- } | null;
458
- normalizedUsage?: ModelCallUsageNormalization;
459
- servingAccountHash?: string;
460
- accountChangedFromPrevCall?: boolean;
461
- emittedSourceKeys?: Set<string>;
462
- }): Promise<boolean>;
463
- /**
464
- * Apply one authoritative, normalized model-call usage frame to the shared
465
- * prompt-cache metrics. The durable source-key fence in `emitModelCallUsage`
466
- * owns idempotency; this helper must never receive raw provider values.
467
- */
468
- export declare function applyCodexCacheTelemetry(observability: ActivityServices["observability"], provider: string, normalizedUsage: ModelCallUsageNormalization): void;
469
- export declare function historyRowsToAppend(rawHistory: Array<Record<string, unknown>>, persistedHistoryCount: number, nextPosition?: number, toolOutputTruncationTokens?: number): {
470
- rows: Array<{
471
- position: number;
472
- item: Record<string, unknown>;
473
- }>;
474
- nextWatermark: number;
475
- nextPosition: number;
476
- };
477
- /** Select only opaque rows that participated in the provider's rejected wire request. */
478
- export declare function selectRejectedProviderArtifactHistoryIds(activeHistory: ReadonlyArray<{
479
- id: string;
480
- item: Record<string, unknown>;
481
- providerArtifactInvalidatedAt: Date | null;
482
- }>, candidates: {
483
- knownHistoryItemIds: readonly string[];
484
- historyItemIds: readonly string[];
485
- }, wireFingerprints: readonly string[]): string[];
486
- /** Literal final per-call boundary for replayed and current-turn model input. */
487
- export declare function isModelOrToolProgressHistoryItem(item: Record<string, unknown>): boolean;
488
- /**
489
- * Resolve the EFFECTIVE/active compute backend a turn should gate
490
- * filesystem-touching agent lifecycle hooks on (today: the repository clone).
491
- *
492
- * WHY (Case B — clone-onto-real-disk hazard): a session keeps its CLOUD HOME
493
- * backend (`settings.sandboxBackend`, e.g. "modal") but its ACTIVE sandbox may
494
- * have been swapped to a connected machine (`active_sandbox_id` → a selfhosted
495
- * lease). `runtime.buildAgent`'s repository-clone hook keys off the backend it is
496
- * told; if the worker passes nothing it defaults to the HOME backend and the hook
497
- * would `git clone` a private GitHub-App repo onto the user's REAL disk — a
498
- * bring-your-own machine owns its own filesystem and must NEVER be cloned onto. So
499
- * we look at where the agent ACTUALLY runs, not where the session was created.
500
- *
501
- * Returns "selfhosted" ONLY when the selfhosted feature is on AND the session has
502
- * a non-null active pointer whose sandbox `kind` is "selfhosted". Otherwise
503
- * returns undefined so buildAgent falls back to the home backend — byte-for-byte
504
- * unchanged cloud behavior.
505
- *
506
- * Total + best-effort by contract: it NEVER throws (a lookup failure is logged and
507
- * falls back to the home default), so wiring it at turn start can't fail the turn.
508
- * The DB I/O is injected (the real call site passes readActiveSandbox + getSandbox,
509
- * the same helpers wrapTurnBoxWithRouting reuses) so the gate/decision/safety
510
- * contract is unit-testable without a live database.
511
- */
512
- export declare function resolveActiveSandboxBackend(routingOn: boolean, loadPointer: () => Promise<{
513
- activeSandboxId: string | null;
514
- } | null>, loadSandboxKind: (sandboxId: string) => Promise<string | null>): Promise<Settings["sandboxBackend"] | undefined>;
515
- /**
516
- * Managed-sandbox ownership exists only when this turn actually uses the
517
- * managed home. A Connected Machine is fenced by its active-route epoch and
518
- * must remain independent from cloud recovery state for the same session.
519
- */
520
- export declare function managedSandboxOwnershipForTurn(machinePrimary: boolean, attemptId: string, sandboxGroupId: string): {
521
- holderId: TurnSandboxLeaseHolderId;
522
- sandboxGroupId: string;
523
- } | null;
524
- /** A sandboxless home still establishes an explicitly attached Connected Machine. */
525
- export declare function shouldEstablishSandboxForTurn(sandboxOwnershipEnabled: boolean, homeBackend: Settings["sandboxBackend"], machinePrimary: boolean): boolean;
526
- export declare function sandboxEstablishPolicyDecision(input: {
527
- lazyEnabled: boolean;
528
- machinePrimary: boolean;
529
- sandboxBackend: Settings["sandboxBackend"];
530
- hasInitialRunCredentialMaterial: boolean;
531
- generatedVideoFileCount: number;
532
- hasSignedFileResources: boolean;
533
- }): {
534
- policy: "eager" | "on-demand";
535
- reason: TurnSandboxEstablishReason;
536
- };
537
- /**
538
- * Classify a persisted active-sandbox pointer for TURN-START RECONCILE (issue #341
539
- * invariant B). Returns the typed reason to RESET the pointer to the session HOME,
540
- * or null to leave it in place. STRUCTURAL unestablishability only:
541
- * - no record → the pointed-at sandbox row is gone (`stale_pointer`);
542
- * - an unestablishable kind (a non-group Modal sibling, or an unknown backend) per
543
- * the SHARED `swapTargetEstablishability` predicate (`unsupported_backend_context`);
544
- * - a selfhosted sandbox with no enrollment id to address (`offline_enrollment`).
545
- * A selfhosted sandbox WITH an enrollment is deliberately left in place even when it
546
- * is momentarily offline: the machine may recover mid-turn and its ops surface
547
- * agent_offline lazily, so the user's explicit machine target is never abandoned for
548
- * a transient control-plane blip (that is #339's concern, not this one).
549
- */
550
- export declare function pointerReconcileReason(record: {
551
- kind: string;
552
- enrollmentId: string | null;
553
- } | null): BackendUnresolvableCode | null;
554
- /** The active pointer + its sandbox row, loaded once at turn start and threaded
555
- * through the reconcile so the establish branch reads the SAME (possibly reset)
556
- * values with no second query. */
557
- export type LoadedActivePointer = {
558
- pointer: ActiveSandboxPointer | null;
559
- record: SandboxRecord | null;
560
- };
561
- /**
562
- * TURN-START RECONCILE (issue #341 invariant B / Shapes 1+2). If the persisted pointer's
563
- * target is STRUCTURALLY unestablishable ({@link pointerReconcileReason}) reset the pointer
564
- * to the session HOME (null) under the epoch fence, emit a VISIBLE `session.route.reconciled`
565
- * event, and return the reconciled pointer/record so the rest of the turn runs on home. NEVER
566
- * a silent downgrade. Bounded to ONE attempt: a lost CAS means a concurrent user swap won a
567
- * higher epoch, so re-read + honor it rather than clobber a newer, user-directed pointer. The
568
- * event publish is best-effort — a publish failure never fails the turn.
569
- *
570
- * FAIL-OPEN on a lookup failure (issue #341 review): the sandbox row is fetched HERE via the
571
- * caller's NON-swallowing `loadRecord`, so a null decision means the row is genuinely absent,
572
- * never a suppressed transient DB error. If `loadRecord` THROWS, reconciliation is skipped
573
- * entirely this turn — the pointer is left UNTOUCHED (record null → the turn runs
574
- * machinePrimary:false on the group box exactly as before reconcile existed), no CAS, no
575
- * event — and the next turn retries. A TRANSIENT LOOKUP FAILURE MUST NEVER MUTATE THE POINTER.
576
- */
577
- export declare function reconcileActiveSandboxPointer(db: ActivityServices["db"], ids: {
578
- accountId: string;
579
- workspaceId: string;
580
- sessionId: string;
581
- }, pointer: ActiveSandboxPointer | null, loadRecord: (sandboxId: string) => Promise<SandboxRecord | null>, publish?: (events: Array<{
582
- type: SessionEventType;
583
- payload: unknown;
584
- }>) => Promise<void> | void): Promise<LoadedActivePointer>;
585
- /**
586
- * Warm the Modal private-registry image for the image ref this turn actually
587
- * resolved, not only the deployment-global OPENGENI_MODAL_IMAGE_REF warmed at
588
- * worker boot. A provider-native modalImageId bypasses registry import and is
589
- * resolved by ModalImageSelector.fromId during create. Otherwise packs can
590
- * override `modalImageRef` per workspace/turn, so a private pack image must be
591
- * resolved before sandbox creation or Modal falls back to the unauthenticated
592
- * `fromTag` path.
593
- */
594
- export declare function ensureTurnModalRegistryImage(runSettings: Settings, sandboxCreationBackend: Settings["sandboxBackend"] | undefined, ensureRegistryImage?: (settings: Settings) => Promise<void>): Promise<void>;
595
- export type SandboxArtifactRuntimeAdmission = Readonly<{
596
- available: boolean;
597
- environment: Readonly<Record<string, string>>;
598
- }>;
599
- /**
600
- * Admit the optional native standalone-file runtime only for the deployment's
601
- * exact base sandbox image contract. A pack/rig image override is an
602
- * independent filesystem and therefore fails closed even when the deployment
603
- * base image is capable. Collaborative artifact skills are admitted separately
604
- * from the frozen canonical tool catalog.
605
- *
606
- * This keeps lazy provisioning intact: CI/release proves the image closure,
607
- * while a before-agent-start doctor verifies the actual box before any model
608
- * call. No speculative sandbox is created merely to populate the skill index.
609
- */
610
- export declare function sandboxArtifactRuntimeAdmission(deploymentSettings: Settings, runSettings: Settings, backend: Settings["sandboxBackend"] | undefined, options?: Readonly<{
611
- production?: boolean;
612
- }>): SandboxArtifactRuntimeAdmission;
613
- /**
614
- * Decide whether the first actual computer action may start a proof recording.
615
- *
616
- * On-turn recording runs ffmpeg/x11grab INSIDE the box and reads the .mp4 back
617
- * out of the box's /tmp — plumbing that exists only for OpenGeni-operated cloud
618
- * boxes (the Modal desktop backend). A turn whose EFFECTIVE backend is a connected
619
- * machine ("selfhosted") runs on the user's REAL computer, which has none of that
620
- * capture plumbing (and the platform must never shell ffmpeg onto a user's machine
621
- * — the same reason the runtime skips its setup hooks for selfhosted). Left ungated
622
- * it films nothing, finds no /tmp file, and emits recording.started followed by
623
- * recording.failed{box-death} on EVERY machine-primary turn — misleading timeline
624
- * noise + wasted work. So gate it off, exactly like a recording-disabled deployment:
625
- * skip silently, emit nothing (no new event shape).
626
- *
627
- * `effectiveBackend` is the resolved ACTIVE backend for the turn
628
- * (resolveActiveSandboxBackend) — NOT the session's home backend. A modal-home
629
- * session actively swapped onto a machine resolves to "selfhosted" here and
630
- * correctly skips; a machine-home turn that degraded back to its cloud group box
631
- * (swap-away / flag-off) resolves to undefined and records as before.
632
- *
633
- * EDGE — mid-turn swap: this is evaluated once when computer-use first runs. A swap
634
- * after recording starts is deliberately ignored; the partial recording already has
635
- * defined failure semantics, so there is no stop/restart machinery.
636
- */
637
- export declare function shouldStartOnTurnRecording(params: {
638
- recordingEnabled: boolean;
639
- desktopEnabled: boolean;
640
- establishedBackendId: string;
641
- effectiveBackend: Settings["sandboxBackend"] | undefined;
642
- }): boolean;
643
- /**
644
- * Decide the EXPLICIT computer-use tool transport for THIS turn.
645
- *
646
- * The runtime's SDK-mirrored capability would otherwise pick hosted-vs-function
647
- * tools by string-sniffing the bound model instance's constructor name for
648
- * "ChatCompletions" (supportsStructuredToolOutputTransport). That is fragile: a
649
- * wrapped / proxied / minified model instance defeats the sniff and a
650
- * chat-completions provider would silently get the HOSTED `computer_use_preview`
651
- * tool it 400s on every turn. So the mode is decided HERE — the worker's model
652
- * resolution is the ONE place a provider's true wire identity is authoritative —
653
- * and threaded to the runtime as an explicit flag (buildAgent → computerToolMode):
654
- * • codex-subscription → "function-image": the ChatGPT/Codex backend rejects
655
- * hosted tool types but SEES structured `input_image` tool results.
656
- * • a "chat" (OpenAIChatCompletionsModel wire) provider → "disabled": it cannot
657
- * receive a screenshot through a proven visual transport, so computer use fails
658
- * closed instead of serializing the image as text.
659
- * • Vercel Gateway providers → "disabled": their curated models support ordinary
660
- * function tools and vision input, not OpenAI's hosted computer tool.
661
- * • everything else — built-in Azure/OpenAI responses, registry "responses"
662
- * providers, AND the LEGACY global-client fallback (resolveTurnModel returned
663
- * null) — → "hosted": real Responses hosted-tool support.
664
- *
665
- * Pure + exported so the mapping is unit-testable without a live turn.
666
- */
667
- export declare function computerToolModeForTurn(resolvedModel: {
668
- provider: {
669
- kind: RegistryProviderKind;
670
- api: ModelProviderApi;
671
- };
672
- configured: {
673
- capabilities: {
674
- inputModalities: string[];
675
- };
676
- };
677
- } | null): ComputerToolMode;
678
- /** Gateway models do not advertise OpenAI's hosted apply_patch/view_image tool types. */
679
- export declare function structuredToolTransportForTurn(resolvedModel: {
680
- provider: {
681
- kind: RegistryProviderKind;
682
- };
683
- } | null): boolean;
684
- /**
685
- * Progressive tool disclosure is universal for supported OpenGeni turns; only
686
- * its contained transport differs. Codex keeps its native path, built-in direct
687
- * OpenAI/Azure Responses use native client tool search, and every other ordinary
688
- * function-calling provider uses OpenGeni's stable search/invoke dispatcher.
689
- */
690
- export declare function lazyToolTransportForTurn(resolvedModel: {
691
- provider: {
692
- id: string;
693
- kind: RegistryProviderKind;
694
- api: ModelProviderApi;
695
- builtin: boolean;
696
- baseUrl?: string | undefined;
697
- };
698
- } | null): LazyToolTransport;
699
- /**
700
- * Native web search is a runtime capability, not part of the session's MCP
701
- * allow-list. Attach it whenever the resolved provider advertises runnable
702
- * support. The null model is the legacy built-in Responses path, whose
703
- * deployment flag is its provider capability gate. There is deliberately no
704
- * cross-provider or sandbox/curl fallback.
705
- */
706
- export declare function hostedWebSearchForTurn(resolvedModel: {
707
- configured: {
708
- hostedWebSearch: boolean;
709
- };
710
- } | null, deploymentWebSearchEnabled: boolean): boolean;
711
- /**
712
- * Image generation is an optional connected-account capability. A delegated
713
- * subscription may still authorize the text model without carrying the local
714
- * credential identity required for paid image operations; that must narrow the
715
- * tool catalog, not reject an otherwise valid turn.
716
- */
717
- export declare function connectedSubscriptionImageGenerationAuthority<T>(credentialContext: T | null | undefined, credentialId: string | null | undefined): {
718
- credentialContext: T;
719
- credentialId: string;
720
- } | null;
721
- /** Direct OpenAI hosted image IDs are reusable only by the exact API credential. */
722
- export declare function openAiHostedImageProviderBindingForTurn(settings: Pick<Settings, "openaiProvider" | "openaiApiKey" | "openaiBaseUrl">, resolvedModel: {
723
- provider: {
724
- id: string;
725
- kind: RegistryProviderKind;
726
- builtin: boolean;
727
- baseUrl?: string | undefined;
728
- };
729
- configured: {
730
- capabilities: {
731
- hostedTools: {
732
- imageGeneration: {
733
- runnable: boolean;
734
- };
735
- };
736
- };
737
- };
738
- } | null): {
739
- providerId: string;
740
- providerBindingHash: string;
741
- } | null;
742
- /** Exact model-catalog modality gate; null preserves the legacy built-in path. */
743
- export declare function modelSupportsImageInputForTurn(resolvedModel: {
744
- configured: {
745
- capabilities?: {
746
- inputModalities: string[];
747
- };
748
- };
749
- } | null): boolean;
750
- /** Image and file input are independent catalogue capabilities. */
751
- export declare function modelAttachmentInputPolicyForTurn(resolvedModel: {
752
- provider: {
753
- api: ModelProviderApi;
754
- };
755
- configured: {
756
- capabilities?: {
757
- inputModalities: string[];
758
- inputFileMediaTypes?: string[];
759
- };
760
- };
761
- } | null): ModelAttachmentInputPolicy;
762
- export type TurnSandboxProvisioner<T> = {
763
- get(): Promise<T>;
764
- hasStarted(): boolean;
765
- waitForSettled(timeoutMs: number): Promise<T | null>;
766
- };
767
- export declare class TurnOperationCancelledError extends Error {
768
- readonly reason: unknown;
769
- readonly name = "TurnOperationCancelledError";
770
- constructor(reason: unknown);
771
- }
772
- export declare class SandboxDeadlineRotationError extends Error {
773
- readonly sandboxGroupId: string;
774
- readonly leaseEpoch: number;
775
- readonly name = "SandboxDeadlineRotationError";
776
- constructor(sandboxGroupId: string, leaseEpoch: number);
777
- }
778
- /**
779
- * Normalize a preparation/provisioning cancellation race back to the Temporal
780
- * cancellation that owns the activity. Several provider APIs expose no portable
781
- * abort primitive, so the worker stops awaiting them and disposes any late
782
- * resource. The wrapper error must never fall through as an ordinary turn
783
- * failure: doing so would omit the quiescence receipt and strand a committed
784
- * Steer/Pause behind `control-pending`.
785
- */
786
- export declare function turnOperationCancellationFailure(error: unknown): CancelledFailure | null;
787
- export declare function waitForTurnOperation<T>(operation: Promise<T>, signal: AbortSignal | undefined, disposeLateResult: ((result: T) => Promise<void> | void) | undefined): Promise<T>;
788
- export declare function isLazySandboxProvisionRetryable(error: unknown): boolean;
789
- /** Short workflow-visible anti-churn pacing after a lifecycle transition. The
790
- * next acquire waits on the exact durable claim itself, so this is deliberately
791
- * not a guessed snapshot-plus-schedules completion time. */
792
- export declare function sandboxDeadlineRotationRecoveryDelayMs(settings: Pick<Settings, "sandboxLeaseReaperPeriodMs">): number;
793
- export declare function createTurnSandboxProvisioner<T>(establish: () => Promise<T>, options?: {
794
- maxRetries?: number;
795
- backoffMs?: number;
796
- signal?: AbortSignal;
797
- onStarted?: () => Promise<void> | void;
798
- onCompleted?: (result: T) => Promise<void> | void;
799
- onFailed?: (error: unknown) => Promise<void> | void;
800
- disposeResult?: (result: T) => Promise<void> | void;
801
- }): TurnSandboxProvisioner<T>;
802
- /**
803
- * Decide whether THIS turn may send OpenAI's `prompt_cache_key` request field.
804
- *
805
- * Accepted transports:
806
- * - legacy/built-in OpenAI or Azure Responses fallback (resolvedModel null);
807
- * - resolved built-in OpenAI/Azure providers;
808
- * - ChatGPT/Codex subscription backend (its strict allowlist permits the field).
809
- *
810
- * Registry API-key providers are intentionally excluded. Fireworks' prompt-cache
811
- * docs prescribe `user` or `x-session-affinity`, not `prompt_cache_key`; Z.AI/GLM
812
- * documents automatic context caching plus `user_id`. Sending OpenAI-only fields
813
- * to unknown OpenAI-compatible providers risks unsupported-parameter 400s.
814
- */
815
- export declare function acceptsPromptCacheKeyForTurn(resolvedModel: {
816
- provider: {
817
- kind: RegistryProviderKind;
818
- builtin?: boolean;
819
- };
820
- } | null): boolean;
821
- /**
822
- * True once the lifetime last confirmed by Postgres is no longer trustworthy.
823
- * A missing or malformed deadline fails closed for a holder that claims to be
824
- * leased; callers check this before accepting an in-flight heartbeat promise.
825
- */
826
- export declare function codexCredentialLeaseDeadlineExpired(confirmedUntilMs: number | null, nowMs?: number): boolean;
827
- type OpStreamFinalizer = {
828
- finalizeOpStreamOps(): Promise<void>;
829
- };
830
- /** Release retained Connected Machine output only after the turn is durable. */
831
- export declare function finalizeDurableTurnOpStreams(sessions: readonly unknown[], fallback: OpStreamFinalizer | null): Promise<void>;
832
- export declare function createRunAgentTurnActivity(services: () => Promise<ActivityServices>): (input: RunAgentTurnInput) => Promise<RunAgentTurnResult>;
833
- export declare function isTransientProviderError(error: unknown): boolean;
834
- export type XaiCredentialFailure = {
835
- kind: "auth" | "forbidden" | "rate_limit";
836
- cooldownMs: number | null;
837
- };
838
- /**
839
- * Only definitive SuperGrok account refusals may move the same logical turn to
840
- * another credential. The marked transport response proves inference was
841
- * rejected before a stream began; refresh relogin is equally definitive.
842
- */
843
- export declare function classifyXaiCredentialFailure(error: unknown): XaiCredentialFailure | null;
844
- export declare function agentRunFailurePayload(error: unknown, options?: {
845
- isCodexTurn?: boolean;
846
- }): {
847
- error: string;
848
- code?: string;
849
- retryable?: boolean;
850
- detail?: string;
851
- timeoutClass?: string;
852
- responseObserved?: boolean;
853
- requestId?: string;
854
- correlationId?: string;
855
- stage?: string;
856
- sqlState?: string | null;
857
- attempts?: number;
858
- retryOutcome?: string;
859
- database?: Record<string, string>;
860
- historyPersistenceStage?: MandatoryHistoryPersistenceStage;
861
- };
862
- export type CodexCredentialFailure = {
863
- kind: "auth" | "forbidden" | "rate_limit" | "quota";
864
- cooldownSeconds: number | null;
865
- };
866
- export declare const CODEX_ALLOWANCE_FALLBACK_MS: number;
867
- /**
868
- * Resolve a deterministic quarantine end. Generic request throttling honors
869
- * provider retry-after (or one minute); allowance/quota refusal waits for the
870
- * LAST of provider reset and every still-binding cached window (five-hour and
871
- * weekly both bind), falling back to one complete five-hour window when no reset
872
- * metadata exists.
873
- */
874
- export declare function codexCredentialCooldownUntil(failure: CodexCredentialFailure, account: Pick<CodexAccountStatus, "primaryUsedPercent" | "primaryResetAt" | "secondaryUsedPercent" | "secondaryResetAt"> | null, now: Date): Date | null;
875
- /**
876
- * Only definitive credential/account refusals are safe rotation signals.
877
- * Ambiguous network failures, malformed/partial streams, invalid model content,
878
- * prompt 4xx, and provider 5xx may already have consumed tokens or persisted
879
- * progress and therefore MUST NOT walk the credential pool automatically.
880
- */
881
- export declare function classifyCodexCredentialFailure(error: unknown): CodexCredentialFailure | null;
882
- /** Humanize a seconds duration into a short "2h 5m" / "9m" / "in under a minute" string. */
883
- export declare function humanizeResetWindow(resetsInSeconds: number | null): string;
884
- /**
885
- * Build the turn.failed payload for a ChatGPT/Codex usage cap: a precise,
886
- * actionable message naming the reset window, the stable `codex_usage_limit_reached`
887
- * code, and retryable:false (an auto-retry would just re-hit the cap).
888
- */
889
- export declare function codexUsageLimitFailurePayload(info: {
890
- resetsInSeconds: number | null;
891
- }, detail: string, opts?: {
892
- allAccounts?: boolean;
893
- }): {
894
- error: string;
895
- code: string;
896
- retryable: boolean;
897
- detail?: string;
898
- };
899
- export declare function pendingToolCallFromSdkEvent(event: unknown): {
900
- callId: string;
901
- callType: string;
902
- callName: string | null;
903
- callItem: Record<string, unknown>;
904
- } | null;
905
- /** Tools whose intentional visual result must survive inline-media sanitization. */
906
- export declare function toolCallProducesRetainableSessionImage(name: string | null): boolean;
907
- export declare function completedToolCallFromSdkEvent(event: unknown): {
908
- callId: string;
909
- resultItem: Record<string, unknown>;
910
- } | null;
911
- export declare function ensureRunAllowed(settings: Settings, db: ActivityServices["db"], accountId: string, workspaceId: string, isExternallyBilledTurn: boolean, entitlements?: ActivityServices["entitlements"]): Promise<void>;
912
- export type ModelUsageBillingRecord = {
913
- billingPath: "opengeni_credits" | "external";
914
- /** Same quantity written to usage_events.model.cost when present; else 0. */
915
- pricedCostMicros: number;
916
- /** Hypothetical provider-rate USD micros; never an OpenGeni charge. */
917
- estimatedProviderCostMicros: number | null;
918
- pricingSource: "configured_list_price" | "gateway_reported" | null;
919
- normalizedUsage: ModelCallUsageNormalization;
920
- upstreamProvider?: string;
921
- };
922
- export declare function recordModelUsageAndDebitCredits(settings: Settings, db: ActivityServices["db"], input: {
923
- accountId: string;
924
- workspaceId: string;
925
- sessionId: string;
926
- turnId: string;
927
- turnAttemptId: string;
928
- model: string;
929
- externallyBilled: boolean;
930
- gatewayManaged?: boolean;
931
- gatewayBilling?: ModelResponseUsage["gatewayBilling"];
932
- usage?: ModelUsageInput | ModelCallUsageInput | null;
933
- normalizedUsage?: ModelCallUsageNormalization;
934
- sourceKey: string;
935
- latencyMode?: LatencyMode;
936
- observability?: ActivityServices["observability"];
937
- }): Promise<ModelUsageBillingRecord | null>;
938
- /** Soft-fail Insights fact write — never throws into the billing/emit path. */
939
- export declare function recordAuthoritativeModelCallFact(input: {
940
- db: ActivityServices["db"];
941
- observability: ActivityServices["observability"];
942
- accountId: string;
943
- workspaceId: string;
944
- sessionId: string;
945
- turnId: string;
946
- turnAttemptId: string;
947
- sourceKey: string;
948
- provider: string;
949
- providerApi: ModelProviderApi;
950
- model: string;
951
- billing: ModelUsageBillingRecord;
952
- }): Promise<void>;
953
- export declare function requiresSignedFileResourceDownloads(settings: Settings, activeSandboxBackend?: Settings["sandboxBackend"]): boolean;
954
- export {};
1
+ /** Public agent-turn surface. Implementation lives in `./agent-turn/*`. */
2
+ export { createRunAgentTurnActivity } from "./agent-turn/run.js";
3
+ export * from "./agent-turn/admission.js";
4
+ export * from "./agent-turn/codex.js";
5
+ export * from "./agent-turn/errors.js";
6
+ export * from "./agent-turn/file-resources.js";
7
+ export * from "./agent-turn/history.js";
8
+ export * from "./agent-turn/model-usage.js";
9
+ export * from "./agent-turn/quiescence.js";
10
+ export * from "./agent-turn/sandbox-provision.js";
11
+ export * from "./agent-turn/sandbox-route.js";
12
+ export * from "./agent-turn/tool-policy.js";