@opengeni/worker-bundle 0.20.3 → 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 (184) 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 +17 -4
  42. package/dist/activities/incident-telemetry-authority.d.ts +52 -0
  43. package/dist/activities/incident-telemetry-preflight.d.ts +71 -0
  44. package/dist/activities/knowledge-source-sync.d.ts +4 -0
  45. package/dist/activities/mcp-credentials.d.ts +9 -3
  46. package/dist/activities/open-suffix-resume.d.ts +77 -0
  47. package/dist/activities/packs.d.ts +3 -11
  48. package/dist/activities/parent-wake.d.ts +19 -0
  49. package/dist/activities/retained-screenshot-reaper.d.ts +1 -1
  50. package/dist/activities/retained-screenshots.d.ts +1 -1
  51. package/dist/activities/rig-verification.d.ts +1 -1
  52. package/dist/activities/run-input.d.ts +9 -10
  53. package/dist/activities/sandbox-images.d.ts +1 -14
  54. package/dist/activities/sandbox-lease.d.ts +21 -3
  55. package/dist/activities/scheduled-tasks.d.ts +47 -0
  56. package/dist/activities/types.d.ts +23 -2
  57. package/dist/activities/video-media-validation.d.ts +1 -1
  58. package/dist/activities/video-output-retention.d.ts +1 -2
  59. package/dist/activities/xai-auth.d.ts +3 -0
  60. package/dist/{activities-control-BJSDRSIP.js → activities-control-DKG22ONJ.js} +2646 -551
  61. package/dist/activities-control-DKG22ONJ.js.map +1 -0
  62. package/dist/activities-control.d.ts +6 -2
  63. package/dist/activities-turn-4IMC3MAA.js +21326 -0
  64. package/dist/activities-turn-4IMC3MAA.js.map +1 -0
  65. package/dist/activities.d.ts +7 -3
  66. package/dist/artifact-materializer-entry.js +41 -22
  67. package/dist/artifact-materializer-entry.js.map +1 -1
  68. package/dist/{chunk-N5TJIFCE.js → chunk-CE7TPKBS.js} +468 -1
  69. package/dist/chunk-CE7TPKBS.js.map +1 -0
  70. package/dist/chunk-CNYGVRKF.js +4698 -0
  71. package/dist/chunk-CNYGVRKF.js.map +1 -0
  72. package/dist/connection-provider-use.d.ts +18 -0
  73. package/dist/editable-artifact-materializer.d.ts +4 -3
  74. package/dist/github-rest-mcp.d.ts +26 -0
  75. package/dist/index.d.ts +10 -2
  76. package/dist/index.js +58 -14
  77. package/dist/index.js.map +1 -1
  78. package/dist/knowledge-source-sync-activity-policy.d.ts +2 -0
  79. package/dist/model-context-contributions.d.ts +8 -4
  80. package/dist/observability-metrics.d.ts +63 -4
  81. package/dist/opensandbox-kubernetes-inventory.d.ts +21 -0
  82. package/dist/personal-github-git-credentials.d.ts +9 -0
  83. package/dist/pr-review-credentials.d.ts +6 -0
  84. package/dist/sandbox-archive-storage.d.ts +45 -0
  85. package/dist/sandbox-resume.d.ts +65 -6
  86. package/dist/sandbox-routing.d.ts +38 -2
  87. package/dist/scheduled-alert-occurrence.d.ts +33 -0
  88. package/dist/workflow-bundle.js +87 -28
  89. package/dist/workflows/activities.d.ts +1 -0
  90. package/dist/workflows/automations.d.ts +6 -0
  91. package/dist/workflows/document-index.d.ts +1 -0
  92. package/dist/workflows.d.ts +1 -0
  93. package/package.json +17 -17
  94. package/src/activities/agent-turn/admission.ts +292 -0
  95. package/src/activities/agent-turn/agent-build.ts +802 -0
  96. package/src/activities/agent-turn/claim.ts +590 -0
  97. package/src/activities/agent-turn/codex-capacity.ts +720 -0
  98. package/src/activities/agent-turn/codex.ts +94 -0
  99. package/src/activities/agent-turn/compaction-prep.ts +722 -0
  100. package/src/activities/agent-turn/credential-leases.ts +240 -0
  101. package/src/activities/agent-turn/errors.ts +1068 -0
  102. package/src/activities/agent-turn/failure-settlement.ts +1436 -0
  103. package/src/activities/agent-turn/file-resources.ts +227 -0
  104. package/src/activities/agent-turn/finalization.ts +754 -0
  105. package/src/activities/agent-turn/github-repository-bindings.ts +300 -0
  106. package/src/activities/agent-turn/governance-model.ts +465 -0
  107. package/src/activities/agent-turn/history-sink.ts +139 -0
  108. package/src/activities/agent-turn/history.ts +200 -0
  109. package/src/activities/agent-turn/media-artifacts.ts +359 -0
  110. package/src/activities/agent-turn/model-usage.ts +823 -0
  111. package/src/activities/agent-turn/quiescence.ts +353 -0
  112. package/src/activities/agent-turn/run-credentials.ts +761 -0
  113. package/src/activities/agent-turn/run.ts +1530 -0
  114. package/src/activities/agent-turn/sandbox-establish.ts +1207 -0
  115. package/src/activities/agent-turn/sandbox-provision.ts +569 -0
  116. package/src/activities/agent-turn/sandbox-route.ts +358 -0
  117. package/src/activities/agent-turn/sandbox-runtime.ts +731 -0
  118. package/src/activities/agent-turn/stream-attempt.ts +1670 -0
  119. package/src/activities/agent-turn/tool-environment.ts +729 -0
  120. package/src/activities/agent-turn/tool-policy.ts +216 -0
  121. package/src/activities/agent-turn/tool-result-spill.ts +265 -0
  122. package/src/activities/agent-turn/turn-context.ts +281 -0
  123. package/src/activities/agent-turn/xai-capacity.ts +229 -0
  124. package/src/activities/agent-turn.ts +12 -12701
  125. package/src/activities/api-integrations.ts +3 -0
  126. package/src/activities/automations.ts +214 -0
  127. package/src/activities/codemode-dispatcher.ts +12 -1
  128. package/src/activities/common.ts +1 -5
  129. package/src/activities/connector-attachments.ts +168 -0
  130. package/src/activities/context-compaction.ts +18 -0
  131. package/src/activities/environment.ts +151 -55
  132. package/src/activities/generated-images.ts +26 -11
  133. package/src/activities/git-credential-renewal.ts +13 -3
  134. package/src/activities/goals.ts +85 -19
  135. package/src/activities/google-drive-provider.ts +178 -0
  136. package/src/activities/google-drive-publication.ts +147 -49
  137. package/src/activities/incident-telemetry-authority.ts +327 -0
  138. package/src/activities/incident-telemetry-preflight.ts +317 -0
  139. package/src/activities/knowledge-source-sync.ts +178 -37
  140. package/src/activities/mcp-credentials.ts +191 -17
  141. package/src/activities/open-suffix-resume.ts +422 -0
  142. package/src/activities/packs.ts +12 -60
  143. package/src/activities/parent-wake.ts +64 -14
  144. package/src/activities/retained-screenshot-reaper.ts +6 -3
  145. package/src/activities/retained-screenshots.ts +15 -47
  146. package/src/activities/rig-verification.ts +1 -1
  147. package/src/activities/run-input.ts +102 -142
  148. package/src/activities/sandbox-images.ts +7 -166
  149. package/src/activities/sandbox-lease.ts +406 -15
  150. package/src/activities/scheduled-tasks.ts +2103 -411
  151. package/src/activities/session-state.ts +10 -2
  152. package/src/activities/types.ts +32 -2
  153. package/src/activities/video-media-validation.ts +3 -3
  154. package/src/activities/video-output-retention.ts +2 -57
  155. package/src/activities/xai-auth.ts +8 -0
  156. package/src/activities-control.ts +2 -0
  157. package/src/activities.ts +3 -0
  158. package/src/activity-services.ts +13 -4
  159. package/src/connection-provider-use.ts +36 -0
  160. package/src/editable-artifact-materializer-subprocess.ts +25 -14
  161. package/src/editable-artifact-materializer.ts +29 -18
  162. package/src/github-rest-mcp.ts +713 -0
  163. package/src/http.ts +16 -6
  164. package/src/index.ts +40 -5
  165. package/src/knowledge-source-sync-activity-policy.ts +2 -0
  166. package/src/model-context-contributions.ts +33 -10
  167. package/src/observability-metrics.ts +357 -0
  168. package/src/opensandbox-kubernetes-inventory.ts +292 -0
  169. package/src/personal-github-git-credentials.ts +331 -0
  170. package/src/pr-review-credentials.ts +163 -0
  171. package/src/sandbox-archive-storage.ts +159 -0
  172. package/src/sandbox-resume.ts +449 -63
  173. package/src/sandbox-routing.ts +314 -16
  174. package/src/scheduled-alert-occurrence.ts +176 -0
  175. package/src/workflows/activities.ts +18 -2
  176. package/src/workflows/automations.ts +11 -0
  177. package/src/workflows/session.ts +13 -3
  178. package/src/workflows.ts +1 -0
  179. package/dist/activities-control-BJSDRSIP.js.map +0 -1
  180. package/dist/activities-turn-J5YO7XXX.js +0 -17243
  181. package/dist/activities-turn-J5YO7XXX.js.map +0 -1
  182. package/dist/chunk-N5TJIFCE.js.map +0 -1
  183. package/dist/chunk-P6Z2SLAA.js +0 -3092
  184. package/dist/chunk-P6Z2SLAA.js.map +0 -1
@@ -0,0 +1,353 @@
1
+ import { type SessionAttemptQuiescenceCommit } from "@opengeni/db";
2
+ import { type TurnToolCancellationFence } from "@opengeni/runtime";
3
+ import { type GitCredentialRenewalController } from "../git-credential-renewal";
4
+ import { type RunCredentialRenewalController } from "../run-credential-renewal";
5
+ import { type CodemodeTokenRenewalController } from "../codemode-token-renewal";
6
+ import type {
7
+ TurnActivityServices as ActivityServices,
8
+ RunAgentTurnResult,
9
+ SessionAttemptQuiescenceProof,
10
+ } from "../types";
11
+ import { type ResumedTurnSandbox } from "../../sandbox-resume";
12
+ import { type SessionEvent } from "@opengeni/contracts";
13
+ import { sleep } from "./sandbox-provision";
14
+
15
+ export function shouldRunTurnEndWorkspacePersistence(input: {
16
+ activityStatus: RunAgentTurnResult["status"] | "unknown";
17
+ cancellationRequested: boolean;
18
+ }): boolean {
19
+ return input.activityStatus !== "cancelled" && !input.cancellationRequested;
20
+ }
21
+
22
+ /**
23
+ * Periodic workspace snapshots protect work performed during a long-running
24
+ * turn. Before the first provider request reaches the wire there is no
25
+ * mid-turn agent work to protect; snapshotting platform setup at that point can
26
+ * instead make the request wait behind the snapshot's workspace-write fence.
27
+ */
28
+ export function shouldStartPeriodicWorkspaceSnapshot(input: {
29
+ firstProviderRequestStarted: boolean;
30
+ snapshotInFlight: boolean;
31
+ turnEndCaptureInProgress: boolean;
32
+ }): boolean {
33
+ return (
34
+ input.firstProviderRequestStarted && !input.snapshotInFlight && !input.turnEndCaptureInProgress
35
+ );
36
+ }
37
+
38
+ /**
39
+ * Temporal cancellation is delivery/transport state, never proof that the
40
+ * dying activity crossed its mandatory sandbox-tool fence. If that fence
41
+ * fails, surface the fence failure instead of retaining a misleading typed
42
+ * cancellation; replacement admission remains closed because no durable
43
+ * quiescence receipt was written.
44
+ */
45
+ export function assertPhysicalToolQuiescenceForCancellation(input: {
46
+ acknowledgeQuiescence: boolean;
47
+ physicalToolQuiescenceConfirmed: boolean;
48
+ failure: unknown;
49
+ }): void {
50
+ if (!input.acknowledgeQuiescence || input.physicalToolQuiescenceConfirmed) return;
51
+ if (input.failure instanceof Error) throw input.failure;
52
+ throw new Error("Physical sandbox-tool quiescence could not be confirmed", {
53
+ cause: input.failure,
54
+ });
55
+ }
56
+
57
+ /** A physically drained attempt must leave one durable recovery producer. The
58
+ * direct Postgres receipt is preferred; after its bounded retries exhaust, an
59
+ * exact Temporal proof signal is sufficient because the workflow persists it
60
+ * through an independently retrying DB-only control activity. */
61
+ export function assertSessionAttemptQuiescenceRecoveryDurable(input: {
62
+ acknowledgeQuiescence: boolean;
63
+ physicalToolQuiescenceConfirmed: boolean;
64
+ receiptOrProofDurable: boolean;
65
+ failure: unknown;
66
+ }): void {
67
+ if (
68
+ !input.acknowledgeQuiescence ||
69
+ !input.physicalToolQuiescenceConfirmed ||
70
+ input.receiptOrProofDurable
71
+ ) {
72
+ return;
73
+ }
74
+ if (input.failure instanceof Error) throw input.failure;
75
+ throw new Error("Physical quiescence had no durable receipt or recovery proof", {
76
+ cause: input.failure,
77
+ });
78
+ }
79
+
80
+ export const QUIESCENCE_PROOF_SIGNAL_INITIAL_RETRY_MS = 250;
81
+ export const QUIESCENCE_PROOF_SIGNAL_MAX_RETRY_MS = 5_000;
82
+
83
+ /** Persist the authoritative receipt or durably hand the exact physical proof
84
+ * to Temporal. This retries signal delivery, not DB eligibility or workflow
85
+ * state. The proof object never changes between attempts. */
86
+ export async function persistOrSignalSessionAttemptQuiescence(input: {
87
+ proof: SessionAttemptQuiescenceProof;
88
+ persistReceipt: () => Promise<SessionAttemptQuiescenceCommit>;
89
+ deliverWorkflowWake?: (
90
+ wake: NonNullable<SessionAttemptQuiescenceCommit["workflowWake"]>,
91
+ ) => Promise<unknown>;
92
+ publishEvents: (events: SessionEvent[]) => Promise<unknown>;
93
+ signalProof: ActivityServices["signalSessionAttemptQuiesced"];
94
+ sleep?: (ms: number) => Promise<void>;
95
+ heartbeat?: (attempt: number, delayMs: number) => void;
96
+ onReceiptFailure?: (error: unknown) => void;
97
+ onWakeFailure?: (error: unknown) => void;
98
+ onPublishFailure?: (error: unknown) => void;
99
+ onSignalFailure?: (error: unknown, attempt: number, delayMs: number) => void;
100
+ }): Promise<"receipt" | "signal"> {
101
+ let receipt: SessionAttemptQuiescenceCommit;
102
+ try {
103
+ receipt = await input.persistReceipt();
104
+ } catch (receiptError) {
105
+ input.onReceiptFailure?.(receiptError);
106
+ if (!input.signalProof) {
107
+ throw new Error("Session-attempt quiescence proof signaler is unavailable", {
108
+ cause: receiptError,
109
+ });
110
+ }
111
+ const delay = input.sleep ?? sleep;
112
+ let retryMs = QUIESCENCE_PROOF_SIGNAL_INITIAL_RETRY_MS;
113
+ let attempt = 1;
114
+ for (;;) {
115
+ try {
116
+ await input.signalProof(input.proof);
117
+ return "signal";
118
+ } catch (signalError) {
119
+ input.onSignalFailure?.(signalError, attempt, retryMs);
120
+ try {
121
+ input.heartbeat?.(attempt, retryMs);
122
+ } catch {
123
+ // Heartbeat telemetry is not proof delivery and cannot replace or
124
+ // interrupt the exact signal retry loop.
125
+ }
126
+ await delay(retryMs);
127
+ retryMs = Math.min(retryMs * 2, QUIESCENCE_PROOF_SIGNAL_MAX_RETRY_MS);
128
+ attempt += 1;
129
+ }
130
+ }
131
+ }
132
+
133
+ if (receipt.workflowWake && input.deliverWorkflowWake) {
134
+ try {
135
+ await input.deliverWorkflowWake(receipt.workflowWake);
136
+ } catch (wakeError) {
137
+ // The exact revision is already durable. Immediate delivery is latency
138
+ // optimization only; the outbox dispatcher remains the repair path.
139
+ input.onWakeFailure?.(wakeError);
140
+ }
141
+ }
142
+ try {
143
+ await input.publishEvents(receipt.events);
144
+ } catch (publishError) {
145
+ // Postgres already committed quiesced_at, the queue event, and the wake.
146
+ // NATS is live fanout only; never misclassify its failure as receipt loss.
147
+ input.onPublishFailure?.(publishError);
148
+ }
149
+ return "receipt";
150
+ }
151
+
152
+ /**
153
+ * Cross the non-detachable physical boundary for one dying attempt. Temporal's
154
+ * cancellation signal is intentionally absent: cancellation is transport, not
155
+ * proof that sandbox tools and attempt-owned credential writers have drained.
156
+ * A replacement may be admitted only after this function resolves and the
157
+ * caller durably persists or signals the exact quiescence receipt.
158
+ */
159
+ export async function drainAttemptOwnedSandboxWriters(input: {
160
+ toolCancellationFence: Pick<TurnToolCancellationFence, "cancel" | "waitForQuiescence"> | null;
161
+ cancellationReason?: unknown;
162
+ gitCredentialRenewals: readonly Pick<GitCredentialRenewalController, "stop">[];
163
+ codemodeTokenRenewal: Pick<CodemodeTokenRenewalController, "stop"> | null;
164
+ runCredentialRenewal: Pick<RunCredentialRenewalController, "stop"> | null;
165
+ }): Promise<void> {
166
+ if (input.toolCancellationFence) {
167
+ input.toolCancellationFence.cancel(
168
+ input.cancellationReason ?? new Error("TURN_ATTEMPT_FENCED"),
169
+ );
170
+ await input.toolCancellationFence.waitForQuiescence();
171
+ }
172
+ await Promise.all(input.gitCredentialRenewals.map(async (renewal) => await renewal.stop()));
173
+ await input.codemodeTokenRenewal?.stop();
174
+ await input.runCredentialRenewal?.stop();
175
+ }
176
+
177
+ /** Persist the exact turn's second-stage release only after the caller has
178
+ * crossed the physical writer boundary. This wait is intentionally independent
179
+ * of Temporal cancellation: it is a short idempotent DB transaction that closes
180
+ * the durable archive-capture fence. Bounded retries cover a rollout connection
181
+ * reset without turning ordinary finalizer housekeeping into lifecycle state. */
182
+ export async function releaseTurnSandboxAfterWriterDrain(
183
+ sandbox: Pick<ResumedTurnSandbox, "release">,
184
+ options: {
185
+ maxAttempts?: number;
186
+ retryDelayMs?: number;
187
+ wait?: (delayMs: number) => Promise<void>;
188
+ } = {},
189
+ ): Promise<void> {
190
+ const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
191
+ const retryDelayMs = Math.max(0, options.retryDelayMs ?? 50);
192
+ const wait = options.wait ?? sleep;
193
+ let lastError: unknown;
194
+ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
195
+ try {
196
+ await sandbox.release({ workspaceWritersQuiesced: true });
197
+ return;
198
+ } catch (error) {
199
+ lastError = error;
200
+ if (attempt < maxAttempts) {
201
+ await wait(retryDelayMs * attempt);
202
+ }
203
+ }
204
+ }
205
+ throw lastError;
206
+ }
207
+
208
+ /**
209
+ * Await a finalizer operation only while this Temporal activity still owns its
210
+ * execution window. Once Pause/Steer cancellation arrives, the operation keeps
211
+ * its own rejection handler and may finish its idempotent, attempt-scoped
212
+ * cleanup in the background, but it cannot pin activity terminalization or
213
+ * delay the separately receipt-gated replacement dispatch.
214
+ */
215
+ export async function waitForTurnFinalizerStep<T>(
216
+ operation: Promise<T>,
217
+ signal: AbortSignal | undefined,
218
+ ): Promise<T | undefined> {
219
+ if (!signal) return await operation;
220
+ if (signal.aborted) {
221
+ void operation.catch(() => undefined);
222
+ return undefined;
223
+ }
224
+
225
+ let resolveCancellation: (() => void) | undefined;
226
+ const cancelled = new Promise<undefined>((resolve) => {
227
+ resolveCancellation = () => resolve(undefined);
228
+ });
229
+ const cancel = (): void => {
230
+ void operation.catch(() => undefined);
231
+ resolveCancellation?.();
232
+ };
233
+ signal.addEventListener("abort", cancel, { once: true });
234
+ try {
235
+ return await Promise.race([operation, cancelled]);
236
+ } finally {
237
+ signal.removeEventListener("abort", cancel);
238
+ }
239
+ }
240
+
241
+ /**
242
+ * Flush provider-facing stream state while the attempt still owns its activity
243
+ * window. On Pause/Steer, both promises are detached with rejection handlers:
244
+ * neither a runtime batcher nor an uncooperative provider completion promise
245
+ * may pin the activity behind cancellation after durable writes are fenced.
246
+ */
247
+ export async function waitForTurnStreamCleanup(
248
+ batcherFlush: Promise<unknown>,
249
+ providerCompleted: Promise<unknown>,
250
+ signal: AbortSignal | undefined,
251
+ ): Promise<void> {
252
+ await waitForTurnFinalizerStep(batcherFlush, signal);
253
+ await waitForTurnFinalizerStep(providerCompleted, signal);
254
+ }
255
+
256
+ /**
257
+ * Terminal settlement closes the active attempt before turn finalization. The
258
+ * ordinary workspace admission therefore correctly returns `attempt_fenced`
259
+ * for the final attempt-qualified credential deletion. Retry only that exact
260
+ * settled-attempt case directly; every other fence/status and the direct
261
+ * deletion itself remain fail-closed.
262
+ */
263
+ export async function clearAttemptCredentialsWithSettledFence(input: {
264
+ activityStatus: RunAgentTurnResult["status"] | "unknown";
265
+ runWorkspaceFencedClear: () => Promise<void>;
266
+ clearExactAttempt: () => Promise<void>;
267
+ onSettledAttemptFence: () => void;
268
+ }): Promise<void> {
269
+ try {
270
+ await input.runWorkspaceFencedClear();
271
+ } catch (error) {
272
+ const settledAttemptFence =
273
+ error instanceof Error &&
274
+ error.name === "SandboxWorkspaceMutationFencedError" &&
275
+ (error as Error & { code?: unknown }).code === "attempt_fenced" &&
276
+ (input.activityStatus === "idle" ||
277
+ input.activityStatus === "failed" ||
278
+ input.activityStatus === "cancelled");
279
+ if (!settledAttemptFence) throw error;
280
+ input.onSettledAttemptFence();
281
+ await input.clearExactAttempt();
282
+ }
283
+ }
284
+
285
+ export function turnFinalizerCancellationSignal(
286
+ temporalSignal: AbortSignal | undefined,
287
+ activityStatus: RunAgentTurnResult["status"] | "unknown",
288
+ ): AbortSignal | undefined {
289
+ if (activityStatus !== "cancelled" || temporalSignal?.aborted) return temporalSignal;
290
+ const fenced = new AbortController();
291
+ fenced.abort(new Error("TURN_ATTEMPT_FENCED"));
292
+ return fenced.signal;
293
+ }
294
+
295
+ export type MandatoryHistoryPersistenceStage = "history_append" | "sandbox_envelope";
296
+
297
+ /**
298
+ * Preserve the exact storage failure for the permission-controlled turn event
299
+ * while attaching only a stable, non-secret operation token to public worker
300
+ * diagnostics. Mandatory history failures remain terminal and never inherit a
301
+ * provider-retry classification from coincidental source text or status.
302
+ */
303
+ export class MandatoryHistoryPersistenceError extends Error {
304
+ readonly name = "MandatoryHistoryPersistenceError";
305
+ readonly cause: unknown;
306
+
307
+ constructor(
308
+ readonly stage: MandatoryHistoryPersistenceStage,
309
+ cause: unknown,
310
+ ) {
311
+ super(cause instanceof Error ? cause.message : String(cause));
312
+ this.cause = cause;
313
+ }
314
+ }
315
+
316
+ export async function runMandatoryHistoryPersistenceStep<T>(
317
+ stage: MandatoryHistoryPersistenceStage,
318
+ operation: () => Promise<T>,
319
+ ): Promise<T> {
320
+ try {
321
+ return await operation();
322
+ } catch (cause) {
323
+ throw new MandatoryHistoryPersistenceError(stage, cause);
324
+ }
325
+ }
326
+
327
+ export type OpStreamFinalizer = {
328
+ finalizeOpStreamOps(): Promise<void>;
329
+ };
330
+
331
+ /** Release retained Connected Machine output only after the turn is durable. */
332
+ export async function finalizeDurableTurnOpStreams(
333
+ sessions: readonly unknown[],
334
+ fallback: OpStreamFinalizer | null,
335
+ ): Promise<void> {
336
+ const candidates = new Set<OpStreamFinalizer>();
337
+ for (const session of sessions) {
338
+ const candidate = session as Partial<OpStreamFinalizer> | null;
339
+ if (typeof candidate?.finalizeOpStreamOps === "function") {
340
+ candidates.add(candidate as OpStreamFinalizer);
341
+ }
342
+ }
343
+ if (candidates.size === 0 && fallback) {
344
+ candidates.add(fallback);
345
+ }
346
+ for (const candidate of candidates) {
347
+ try {
348
+ await candidate.finalizeOpStreamOps();
349
+ } catch {
350
+ // The runner's retention TTL owns the fallback.
351
+ }
352
+ }
353
+ }