@opengeni/runtime 4.3.0 → 4.4.0-canary.36927100590001

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 (117) hide show
  1. package/dist/agent-instructions/base-behavior.d.ts +8 -0
  2. package/dist/agent-instructions/compose.d.ts +59 -0
  3. package/dist/agent-instructions/identity.d.ts +21 -0
  4. package/dist/agent-instructions/index.d.ts +6 -0
  5. package/dist/agent-instructions/modules/admin.d.ts +3 -0
  6. package/dist/agent-instructions/modules/artifacts.d.ts +7 -0
  7. package/dist/agent-instructions/modules/attachments.d.ts +3 -0
  8. package/dist/agent-instructions/modules/environment.d.ts +11 -0
  9. package/dist/agent-instructions/modules/goals.d.ts +3 -0
  10. package/dist/agent-instructions/modules/knowledge.d.ts +6 -0
  11. package/dist/agent-instructions/modules/machines.d.ts +3 -0
  12. package/dist/agent-instructions/modules/renderer-markdown.d.ts +6 -0
  13. package/dist/agent-instructions/modules/repositories.d.ts +7 -0
  14. package/dist/agent-instructions/modules/sandbox.d.ts +3 -0
  15. package/dist/agent-instructions/modules/skills.d.ts +3 -0
  16. package/dist/agent-instructions/modules/subagents.d.ts +3 -0
  17. package/dist/agent-instructions/runtime-mechanics.d.ts +7 -0
  18. package/dist/agent-instructions/types.d.ts +55 -0
  19. package/dist/assets/codemode-client.json +1 -1
  20. package/dist/{chunk-JUFVYQCY.js → chunk-VDXKKMMD.js} +457 -165
  21. package/dist/chunk-VDXKKMMD.js.map +1 -0
  22. package/dist/{chunk-22M75RJF.js → chunk-ZY655LYR.js} +1636 -709
  23. package/dist/chunk-ZY655LYR.js.map +1 -0
  24. package/dist/claude-subscription-usage.d.ts +3 -1
  25. package/dist/first-party-client.d.ts +1 -0
  26. package/dist/index.d.ts +37 -28
  27. package/dist/index.js +28 -2
  28. package/dist/input-wait-yield.d.ts +4 -0
  29. package/dist/interaction-tools.d.ts +1 -0
  30. package/dist/lazy-tool-transport.d.ts +6 -2
  31. package/dist/mcp-run-credentials.d.ts +3 -2
  32. package/dist/mcp-transport-logger.d.ts +10 -0
  33. package/dist/model-context-inspector.d.ts +17 -1
  34. package/dist/model-preparation-diagnostics.d.ts +9 -0
  35. package/dist/model-provider-routing.d.ts +4 -0
  36. package/dist/model-provider.d.ts +1 -0
  37. package/dist/model-request-capture.d.ts +9 -0
  38. package/dist/replayable-json-body.d.ts +2 -1
  39. package/dist/responses-terminal-error.d.ts +17 -0
  40. package/dist/sandbox/codemode-authority.d.ts +1 -0
  41. package/dist/sandbox/index.d.ts +3 -3
  42. package/dist/sandbox/index.js +5 -1
  43. package/dist/sandbox/provider-command-session.d.ts +6 -0
  44. package/dist/sandbox/providers/modal-command-control.d.ts +7 -0
  45. package/dist/sandbox/providers/modal-command-router-wire.d.ts +8 -0
  46. package/dist/sandbox/providers/modal-command-session.d.ts +2 -1
  47. package/dist/sandbox/providers/modal-command-start-errors.d.ts +9 -0
  48. package/dist/sandbox/providers/modal.d.ts +3 -0
  49. package/dist/sandbox/routing/routing-session.d.ts +5 -4
  50. package/dist/workspace-tool-gateway.js +2 -2
  51. package/package.json +12 -12
  52. package/src/agent-instructions/PROMPT_CHANGELOG.md +149 -0
  53. package/src/agent-instructions/base-behavior.ts +120 -0
  54. package/src/agent-instructions/compose.ts +153 -0
  55. package/src/agent-instructions/identity.ts +42 -0
  56. package/src/agent-instructions/index.ts +24 -0
  57. package/src/agent-instructions/modules/admin.ts +25 -0
  58. package/src/agent-instructions/modules/artifacts.ts +39 -0
  59. package/src/agent-instructions/modules/attachments.ts +12 -0
  60. package/src/agent-instructions/modules/environment.ts +60 -0
  61. package/src/agent-instructions/modules/goals.ts +15 -0
  62. package/src/agent-instructions/modules/knowledge.ts +21 -0
  63. package/src/agent-instructions/modules/machines.ts +17 -0
  64. package/src/agent-instructions/modules/renderer-markdown.ts +17 -0
  65. package/src/agent-instructions/modules/repositories.ts +28 -0
  66. package/src/agent-instructions/modules/sandbox.ts +63 -0
  67. package/src/agent-instructions/modules/skills.ts +19 -0
  68. package/src/agent-instructions/modules/subagents.ts +42 -0
  69. package/src/agent-instructions/runtime-mechanics.ts +55 -0
  70. package/src/agent-instructions/types.ts +83 -0
  71. package/src/bundled_default_skills/opengeni-client/SKILL.md +116 -37
  72. package/src/bundled_default_skills/opengeni-client/references/agent-recipes.md +18 -8
  73. package/src/bundled_default_skills/opengeni-client/references/api-workflows.md +24 -4
  74. package/src/bundled_default_skills/opengeni-client/references/chat-facade-fallback.md +23 -4
  75. package/src/bundled_default_skills/opengeni-client/references/compatibility-and-troubleshooting.md +34 -1
  76. package/src/bundled_default_skills/opengeni-client/references/configure-the-agent.md +248 -0
  77. package/src/bundled_default_skills/opengeni-client/references/customer-skill-template.md +2 -1
  78. package/src/bundled_default_skills/opengeni-client/references/data-tools-and-credentials.md +15 -4
  79. package/src/bundled_default_skills/opengeni-client/references/discovery-and-autonomy.md +2 -2
  80. package/src/bundled_default_skills/opengeni-client/references/isolation-and-authorization.md +5 -3
  81. package/src/bundled_default_skills/opengeni-client/references/product-integration-shapes.md +6 -5
  82. package/src/bundled_default_skills/opengeni-client/references/product-shapes-and-ui.md +36 -3
  83. package/src/bundled_default_skills/opengeni-client/references/proxy-from-any-backend.md +170 -0
  84. package/src/bundled_default_skills/opengeni-client/references/session-history-import.md +147 -0
  85. package/src/bundled_default_skills/opengeni-client/references/usage-allowances.md +189 -0
  86. package/src/bundled_default_skills/opengeni-help/SKILL.md +1 -1
  87. package/src/claude-subscription-usage.ts +23 -4
  88. package/src/first-party-client.ts +4 -0
  89. package/src/index.ts +260 -146
  90. package/src/input-wait-yield.ts +7 -0
  91. package/src/interaction-tools.ts +16 -2
  92. package/src/lazy-tool-transport.ts +46 -16
  93. package/src/mcp-run-credentials.ts +18 -3
  94. package/src/mcp-transport-logger.ts +46 -0
  95. package/src/model-context-inspector.ts +37 -3
  96. package/src/model-preparation-diagnostics.ts +48 -1
  97. package/src/model-provider-client.ts +5 -1
  98. package/src/model-provider-routing.ts +95 -1
  99. package/src/model-provider.ts +1 -0
  100. package/src/model-request-capture.ts +28 -1
  101. package/src/provider-history-adapter.ts +24 -3
  102. package/src/replayable-json-body.ts +19 -2
  103. package/src/responses-terminal-error.ts +136 -0
  104. package/src/sandbox/codemode-authority.ts +4 -0
  105. package/src/sandbox/codemode-client.ts +18 -16
  106. package/src/sandbox/index.ts +45 -9
  107. package/src/sandbox/provider-command-session.ts +12 -0
  108. package/src/sandbox/providers/modal-command-control.ts +118 -12
  109. package/src/sandbox/providers/modal-command-router-wire.ts +40 -4
  110. package/src/sandbox/providers/modal-command-session.ts +36 -1
  111. package/src/sandbox/providers/modal-command-start-errors.ts +27 -0
  112. package/src/sandbox/providers/modal-legacy-command-control.ts +60 -30
  113. package/src/sandbox/providers/modal.ts +43 -2
  114. package/src/sandbox/routing/routing-session.ts +61 -6
  115. package/src/sandbox/turn-tool-cancellation.ts +8 -1
  116. package/dist/chunk-22M75RJF.js.map +0 -1
  117. package/dist/chunk-JUFVYQCY.js.map +0 -1
@@ -1,5 +1,6 @@
1
1
  import { Client, Metadata, credentials, status, type ServiceError } from "@grpc/grpc-js";
2
2
  import protobuf from "protobufjs";
3
+ import { ModalCommandStartOutcomeUnknownError } from "./modal-command-start-errors";
3
4
  import { ProviderCommandStartRejectedError } from "../provider-command-session";
4
5
 
5
6
  // Narrow wire projection of Modal 0.9.0's task_command_router.proto. The public
@@ -61,6 +62,24 @@ export class ModalCommandStartPreDispatchUnavailableError extends Error {
61
62
  this.name = "ModalCommandStartPreDispatchUnavailableError";
62
63
  }
63
64
 
65
+ /** The supplied operation must contain only read-only preparation, never
66
+ * Start itself. Its transport failure therefore proves non-dispatch. */
67
+ static async beforeDispatch<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T> {
68
+ signal?.throwIfAborted();
69
+ try {
70
+ return await operation();
71
+ } catch (error) {
72
+ signal?.throwIfAborted();
73
+ const code = (error as Partial<ServiceError> | null)?.code;
74
+ if (
75
+ error instanceof Error &&
76
+ (code === status.UNAVAILABLE || code === status.DEADLINE_EXCEEDED)
77
+ )
78
+ throw new ModalCommandStartPreDispatchUnavailableError(error);
79
+ throw error;
80
+ }
81
+ }
82
+
64
83
  static async ensureReady(client: Client, signal?: AbortSignal): Promise<void> {
65
84
  signal?.throwIfAborted();
66
85
  await new Promise<void>((resolve, reject) => {
@@ -81,6 +100,17 @@ export class ModalCommandStartPreDispatchUnavailableError extends Error {
81
100
  }
82
101
  }
83
102
 
103
+ /** Local cancellation/closure before Start dispatch. This permits exact
104
+ * never-started reservation settlement, NOT another launch or turn recovery. */
105
+ export class ModalCommandStartNotDispatchedError extends Error {
106
+ constructor(cause: unknown) {
107
+ super(cause instanceof Error ? cause.message : "Modal command Start was never dispatched", {
108
+ cause,
109
+ });
110
+ this.name = "ModalCommandStartNotDispatchedError";
111
+ }
112
+ }
113
+
84
114
  export type ModalRouterIdentity = { taskId: string; execId: string };
85
115
  export type ModalRouterAccess = { url: string; jwt: string };
86
116
  export type ModalRouterStart = ModalRouterIdentity & {
@@ -170,12 +200,18 @@ export class ModalCommandRouterWire {
170
200
  }
171
201
 
172
202
  async start(request: ModalRouterStart, signal?: AbortSignal): Promise<void> {
173
- if (this.closed) throw new Error("Modal command router is closed");
174
203
  try {
204
+ if (this.closed) throw new Error("Modal command router is closed");
175
205
  await ModalCommandStartPreDispatchUnavailableError.ensureReady(this.client, signal);
206
+ signal?.throwIfAborted();
207
+ if (this.closed) throw new Error("Modal command router is closed");
176
208
  } catch (error) {
177
- if (this.closed) throw new Error("Modal command router is closed", { cause: error });
178
- throw error;
209
+ if (this.closed)
210
+ throw new ModalCommandStartNotDispatchedError(
211
+ new Error("Modal command router is closed", { cause: error }),
212
+ );
213
+ if (error instanceof ModalCommandStartPreDispatchUnavailableError) throw error;
214
+ throw new ModalCommandStartNotDispatchedError(error);
179
215
  }
180
216
  try {
181
217
  await this.unary(
@@ -202,7 +238,7 @@ export class ModalCommandRouterWire {
202
238
  ].includes(code)
203
239
  )
204
240
  throw new ModalCommandStartRejectedError(code, error);
205
- throw error;
241
+ throw new ModalCommandStartOutcomeUnknownError(request.taskId, request.execId, error);
206
242
  }
207
243
  }
208
244
 
@@ -10,6 +10,7 @@ import {
10
10
  type ProviderCommandPersistence,
11
11
  type ProviderCommandSession,
12
12
  admittedProviderCommandHandle,
13
+ ProviderCommandStartOutcomeUnknownError,
13
14
  } from "../provider-command-session";
14
15
  import type { ModalCommandControl, ModalProviderCommand } from "./modal-command-control";
15
16
  import { verifyModalMaterializedPath } from "./modal-materialization-verification";
@@ -41,15 +42,39 @@ export function installModalCommandSession(
41
42
  execCommand?: ChannelASession["execCommand"];
42
43
  writeStdin?: ChannelASession["writeStdin"];
43
44
  verifyMaterializedPath?: (path: string, workdir: string) => Promise<void>;
45
+ verifyExecReadiness?: (signal: AbortSignal) => Promise<number>;
44
46
  },
45
47
  control: Pick<ModalCommandControl, "start" | "read" | "readProbe" | "write"> &
46
- Partial<Pick<ModalCommandControl, "supervisionControl" | "verifySupervisionCapability">>,
48
+ Partial<
49
+ Pick<
50
+ ModalCommandControl,
51
+ "supervisionControl" | "verifySupervisionCapability" | "verifyExecReadiness"
52
+ >
53
+ >,
47
54
  ): void {
48
55
  markTypedExecHandleLoss(session);
49
56
  const originalExec = session.execCommand?.bind(session);
50
57
  const originalWrite = session.writeStdin?.bind(session);
51
58
  const cancelLegacyStart = session.cancelPendingExecCommand?.bind(session);
52
59
  const pendingStarts = new Set<AbortController>();
60
+ if (control.verifyExecReadiness) {
61
+ const verify = control.verifyExecReadiness.bind(control);
62
+ session.verifyExecReadiness = async (signal: AbortSignal) => {
63
+ const cancellation = new AbortController();
64
+ const abort = () => cancellation.abort(signal.reason);
65
+ signal.addEventListener("abort", abort, { once: true });
66
+ if (signal.aborted) abort();
67
+ pendingStarts.add(cancellation);
68
+ try {
69
+ const exit = await verify(cancellation.signal);
70
+ cancellation.signal.throwIfAborted();
71
+ return exit;
72
+ } finally {
73
+ signal.removeEventListener("abort", abort);
74
+ pendingStarts.delete(cancellation);
75
+ }
76
+ };
77
+ }
53
78
  session.verifyCommandSupervisionCapability = async () => {
54
79
  if (!control.verifySupervisionCapability)
55
80
  throw new Error("Modal instance lacks supervised command capability verification");
@@ -246,6 +271,16 @@ export function installModalCommandSession(
246
271
  exitCode: null,
247
272
  });
248
273
  }
274
+ } catch (error) {
275
+ if (error instanceof ProviderCommandStartOutcomeUnknownError) {
276
+ const entry = entries.get(handle);
277
+ if (entry && !sameExecution(entry.command, error.command))
278
+ throw new Error("Reserved Modal command changed during failed dispatch", {
279
+ cause: error,
280
+ });
281
+ entries.set(handle, entry ?? { command: error.command });
282
+ }
283
+ throw error;
249
284
  } finally {
250
285
  pendingStarts.delete(cancellation);
251
286
  }
@@ -0,0 +1,27 @@
1
+ // Shared with the repository's SDK patch without importing its optional exports.
2
+ // A remote RPC's name/code/details cannot create an own Symbol data property.
3
+ // Keep this non-enumerable marker local; never infer dispatch proof from text.
4
+ const boundaryBrand = Symbol.for("opengeni.modal.command-start.boundary.v1");
5
+ type BoundaryKind = "pre-dispatch-unavailable" | "outcome-unknown";
6
+
7
+ export function hasModalCommandStartBoundary(error: unknown, kind: BoundaryKind): boolean {
8
+ if (!error || typeof error !== "object") return false;
9
+ try {
10
+ return Object.getOwnPropertyDescriptor(error, boundaryBrand)?.value === kind;
11
+ } catch {
12
+ return false;
13
+ }
14
+ }
15
+
16
+ /** Owned by runtime so published consumers work with the unpatched Modal SDK. */
17
+ export class ModalCommandStartOutcomeUnknownError extends Error {
18
+ constructor(
19
+ readonly taskId: string,
20
+ readonly execId: string,
21
+ cause: unknown,
22
+ ) {
23
+ super("Modal command Start outcome unknown; do not replay this invocation", { cause });
24
+ this.name = "CommandStartOutcomeUnknownError";
25
+ Object.defineProperty(this, boundaryBrand, { value: "outcome-unknown" });
26
+ }
27
+ }
@@ -1,5 +1,9 @@
1
1
  import { posix } from "node:path";
2
2
  import { ModalClient } from "modal";
3
+ import { ModalCommandStartOutcomeUnknownError } from "./modal-command-start-errors";
4
+ import { status } from "@grpc/grpc-js";
5
+ import { ModalCommandStartPreDispatchUnavailableError } from "./modal-command-router-wire";
6
+ import { ProviderCommandStartRejectedError } from "../provider-command-session";
3
7
  import { ModalLegacyProviderCommand } from "@opengeni/contracts";
4
8
  import type { ChannelAExecArgs } from "../channel-a";
5
9
  import { shellQuote } from "@openai/agents-core/sandbox/internal";
@@ -151,7 +155,10 @@ export class ModalCommandControl {
151
155
  // Hydration replaces the SDK sandbox. Freeze its current identity for this
152
156
  // start so an asynchronous replacement cannot relabel the returned locator.
153
157
  const sandboxId = this.sandboxId;
154
- const task = await this.client.sandboxGetTaskId({ sandboxId }, signal ? { signal } : undefined);
158
+ const task = await ModalCommandStartPreDispatchUnavailableError.beforeDispatch(
159
+ () => this.client.sandboxGetTaskId({ sandboxId }, signal ? { signal } : undefined),
160
+ signal,
161
+ );
155
162
  if (!task.taskId || task.taskResult) throw new Error("Modal command task is unavailable");
156
163
  if (sandboxId !== this.sandboxId)
157
164
  throw new Error("Modal sandbox changed during command preparation");
@@ -175,35 +182,58 @@ export class ModalCommandControl {
175
182
  }
176
183
  // Do not retry this mutating start on an ambiguous transport error: this
177
184
  // provider API assigns the execution id in its response, not in our request.
178
- const result = await this.client.containerExec(
179
- {
180
- taskId: task.taskId,
181
- command,
182
- terminateContainerOnExit: false,
183
- runtimeDebug: false,
184
- stdoutOutput: 2,
185
- stderrOutput: 2,
186
- timeoutSecs: 0,
187
- workdir,
188
- secretIds: [],
189
- ...(args.tty
190
- ? {
191
- ptyInfo: {
192
- enabled: true,
193
- winszRows: 24,
194
- winszCols: 80,
195
- envTerm: "xterm",
196
- envColorterm: "",
197
- envTermProgram: "",
198
- ptyType: 1,
199
- noTerminateOnIdleStdin: true,
200
- },
201
- }
202
- : {}),
203
- },
204
- { retries: 0, ...(signal ? { signal } : {}) },
205
- );
206
- if (!result.execId) throw new Error("Modal command start returned no execution identity");
185
+ const result = await this.client
186
+ .containerExec(
187
+ {
188
+ taskId: task.taskId,
189
+ command,
190
+ terminateContainerOnExit: false,
191
+ runtimeDebug: false,
192
+ stdoutOutput: 2,
193
+ stderrOutput: 2,
194
+ timeoutSecs: 0,
195
+ workdir,
196
+ secretIds: [],
197
+ ...(args.tty
198
+ ? {
199
+ ptyInfo: {
200
+ enabled: true,
201
+ winszRows: 24,
202
+ winszCols: 80,
203
+ envTerm: "xterm",
204
+ envColorterm: "",
205
+ envTermProgram: "",
206
+ ptyType: 1,
207
+ noTerminateOnIdleStdin: true,
208
+ },
209
+ }
210
+ : {}),
211
+ },
212
+ { retries: 0, ...(signal ? { signal } : {}) },
213
+ )
214
+ .catch((error: unknown) => {
215
+ const code = (error as { code?: unknown } | null)?.code;
216
+ if (
217
+ typeof code === "number" &&
218
+ [
219
+ status.INVALID_ARGUMENT,
220
+ status.NOT_FOUND,
221
+ status.PERMISSION_DENIED,
222
+ status.UNAUTHENTICATED,
223
+ status.UNIMPLEMENTED,
224
+ ].includes(code)
225
+ )
226
+ throw new ProviderCommandStartRejectedError(error);
227
+ // Legacy ContainerExec assigns its id in the lost response. There is no
228
+ // safe invocation locator and no authority to issue another launch.
229
+ throw new ModalCommandStartOutcomeUnknownError(task.taskId!, "", error);
230
+ });
231
+ if (!result.execId)
232
+ throw new ModalCommandStartOutcomeUnknownError(
233
+ task.taskId,
234
+ "",
235
+ new Error("Modal command start returned no execution identity"),
236
+ );
207
237
  return {
208
238
  kind: "modal-control-v1",
209
239
  sandboxId,
@@ -15,10 +15,14 @@ import { CAPABILITY_DESCRIPTORS } from "../capabilities";
15
15
  import { SandboxChannelAService, type ChannelASession } from "../channel-a";
16
16
  import { installModalCommandSession } from "./modal-command-session";
17
17
  import { ModalCommandControl } from "./modal-command-control";
18
- import { ModalCommandStartPreDispatchUnavailableError } from "./modal-command-router-wire";
18
+ import {
19
+ ModalCommandStartPreDispatchUnavailableError,
20
+ ModalCommandStartNotDispatchedError,
21
+ } from "./modal-command-router-wire";
19
22
  import { createModalSessionWithLifecycle, type ModalCreateLifecycle } from "./modal-create-session";
20
23
  import { isRoutingMutationOutcomeUnknownError } from "../routing/routing-session";
21
24
  import type { ModalClient } from "modal";
25
+ import { hasModalCommandStartBoundary } from "./modal-command-start-errors";
22
26
  import { ModalProcessObservationUnavailableError, SandboxConfigError } from "../errors";
23
27
  export { ModalProcessObservationUnavailableError } from "../errors";
24
28
  import { markTypedExecHandleLoss } from "../exec-banner";
@@ -263,11 +267,16 @@ export function isModalTaskExecStartPreDispatchUnavailableError(error: unknown):
263
267
  try {
264
268
  const record = current.value as Record<string, unknown>;
265
269
  if (isRoutingMutationOutcomeUnknownError(current.value)) return false;
270
+ if (hasModalCommandStartBoundary(current.value, "outcome-unknown")) return false;
271
+ if (current.value instanceof ModalCommandStartNotDispatchedError) return false;
266
272
  if (hasContradictoryModalHttpStatus(record)) return false;
267
273
 
268
274
  // This instance is created only by the client's readiness gate before
269
275
  // Start dispatch; an RPC's own status or details never enters this path.
270
- if (current.value instanceof ModalCommandStartPreDispatchUnavailableError) {
276
+ if (
277
+ current.value instanceof ModalCommandStartPreDispatchUnavailableError ||
278
+ hasModalCommandStartBoundary(current.value, "pre-dispatch-unavailable")
279
+ ) {
271
280
  matchingLeaves += 1;
272
281
  continue;
273
282
  }
@@ -304,6 +313,38 @@ export function isModalTaskExecStartPreDispatchUnavailableError(error: unknown):
304
313
  return matchingLeaves > 0;
305
314
  }
306
315
 
316
+ /** Any typed ambiguous Start in a bounded wrapper graph vetoes generic provider
317
+ * retries. Setup/probe calls have no retained command handle to replay safely. */
318
+ export function isModalCommandStartOutcomeUnknownError(error: unknown): boolean {
319
+ const pending: Array<{ depth: number; value: unknown }> = [{ depth: 0, value: error }];
320
+ const seen = new WeakSet<object>();
321
+ for (
322
+ let inspected = 0;
323
+ pending.length && inspected < MODAL_TASK_EXEC_START_ERROR_MAX_NODES;
324
+ inspected++
325
+ ) {
326
+ const { depth, value } = pending.shift()!;
327
+ if (!value || typeof value !== "object" || seen.has(value)) continue;
328
+ seen.add(value);
329
+ if (hasModalCommandStartBoundary(value, "outcome-unknown")) return true;
330
+ if (depth >= MODAL_TASK_EXEC_START_ERROR_MAX_DEPTH) continue;
331
+ try {
332
+ const record = value as Record<string, unknown>;
333
+ for (const key of ["cause", "error"] as const)
334
+ if (record[key] !== undefined) pending.push({ depth: depth + 1, value: record[key] });
335
+ if (Array.isArray(record.errors))
336
+ for (const nested of record.errors.slice(
337
+ 0,
338
+ MODAL_TASK_EXEC_START_ERROR_MAX_AGGREGATE_ERRORS,
339
+ ))
340
+ pending.push({ depth: depth + 1, value: nested });
341
+ } catch {
342
+ // Unknown wrappers never establish dispatch proof.
343
+ }
344
+ }
345
+ return false;
346
+ }
347
+
307
348
  /**
308
349
  * Modal proves that the exact exec has already terminated with a typed
309
350
  * FAILED_PRECONDITION from its stdin-write RPC. Keep this deliberately
@@ -30,13 +30,17 @@
30
30
  import { SandboxWorkspaceReadNotFoundError } from "@openai/agents/sandbox";
31
31
  import { SandboxFilesystemNotFoundError } from "modal";
32
32
  import type { ExposedPortEndpoint } from "../stream-port";
33
- import { ModalCommandStartPreDispatchUnavailableError } from "../providers/modal-command-router-wire";
33
+ import {
34
+ ModalCommandStartPreDispatchUnavailableError,
35
+ ModalCommandStartNotDispatchedError,
36
+ } from "../providers/modal-command-router-wire";
34
37
  import { isDeepStrictEqual } from "node:util";
35
38
  import {
36
39
  withProviderCommandHandle,
37
40
  withCommandSupervisionReady,
38
41
  withSupervisedLaunchReservation,
39
42
  ProviderCommandStartRejectedError,
43
+ ProviderCommandStartOutcomeUnknownError,
40
44
  type ProviderCommandPersistence,
41
45
  type ProviderCommandSession,
42
46
  } from "../provider-command-session";
@@ -247,11 +251,11 @@ export interface RoutingSandboxSessionDeps {
247
251
  op: string;
248
252
  backend: ResolvedActiveBackend;
249
253
  admission: unknown;
250
- outcome: "resolved" | "rejected";
251
- /** Provider result for a resolved call. Never present for rejection. */
254
+ outcome: "resolved" | "rejected" | "outcome_unknown";
255
+ /** Provider result for a resolved call. Absent when Start is unknown. */
252
256
  result?: unknown;
253
- /** Stable candidate generated before durable promotion is attempted. It is
254
- * supplied only when the provider returned a positive yielded-session id. */
257
+ /** Exact candidate for a yielded process or a client-chosen unknown Start.
258
+ * Unknown Start settlement retains this writer; it does not prove exit. */
255
259
  retainedProcess?: RoutingRetainedProcess;
256
260
  }) => Promise<void | RoutingMutationSettlementResult>;
257
261
  /** Admit one model/user-visible stdin mutation under the already-durable
@@ -521,6 +525,15 @@ export class RoutingRetainedProcessNotFoundError extends Error {
521
525
  }
522
526
  }
523
527
 
528
+ export function renderRoutingMutationOutcomeUnknownToolResult(
529
+ error: RoutingMutationOutcomeUnknownError,
530
+ ): string {
531
+ const locator = error.retainedProcess
532
+ ? ` Inspect the exact invocation with write_stdin using session_id ${error.retainedProcess.providerSessionId} and empty chars.`
533
+ : " Inspect state before deciding how to proceed.";
534
+ return `Sandbox operation outcome unknown; the operation was not replayed. Do not blindly retry the command.${locator} Error: ${error}`;
535
+ }
536
+
524
537
  type PendingParentPromotion = Parameters<
525
538
  NonNullable<RoutingSandboxSessionDeps["afterMutation"]>
526
539
  >[0];
@@ -1070,7 +1083,8 @@ export class RoutingSandboxSession implements RoutableBackendSession {
1070
1083
  { cause: error },
1071
1084
  );
1072
1085
  }
1073
- await this.captureRetainedOutput(record, formatExecResult(pending.result));
1086
+ if (pending.result !== undefined)
1087
+ await this.captureRetainedOutput(record, formatExecResult(pending.result));
1074
1088
  }
1075
1089
 
1076
1090
  private confirmDurableRejectedPromotion(
@@ -1710,9 +1724,50 @@ export class RoutingSandboxSession implements RoutableBackendSession {
1710
1724
  );
1711
1725
  }
1712
1726
  } catch (error) {
1727
+ if (
1728
+ !reservedProcess &&
1729
+ error instanceof ProviderCommandStartOutcomeUnknownError &&
1730
+ mutatesWorkspace &&
1731
+ this.deps.afterMutation
1732
+ ) {
1733
+ const handle = this.deps.providerCommandHandle?.(admission);
1734
+ if (!handle) throw error;
1735
+ const process: RoutingRetainedProcess = {
1736
+ id: crypto.randomUUID(),
1737
+ providerSessionId: handle,
1738
+ providerCommand: error.command,
1739
+ };
1740
+ const record = this.registerRetainedProcess(process, backend);
1741
+ const settlement: PendingParentPromotion = {
1742
+ op,
1743
+ backend,
1744
+ admission,
1745
+ outcome: "outcome_unknown",
1746
+ retainedProcess: process,
1747
+ };
1748
+ record.pendingParentPromotion = settlement;
1749
+ try {
1750
+ const rejected = await this.deps.afterMutation(settlement);
1751
+ if (rejected) this.confirmDurableRejectedPromotion(record, rejected);
1752
+ else record.durable = true;
1753
+ record.pendingParentPromotion = null;
1754
+ } catch (cause) {
1755
+ throw new RoutingMutationOutcomeUnknownError(
1756
+ op,
1757
+ "Command Start outcome is unknown and exact invocation promotion remains unresolved; it was not replayed",
1758
+ { cause: new AggregateError([error, cause]), retainedProcess: process },
1759
+ );
1760
+ }
1761
+ throw new RoutingMutationOutcomeUnknownError(
1762
+ op,
1763
+ "Command Start outcome is unknown; its exact invocation is retained and was not replayed",
1764
+ { cause: error, retainedProcess: process },
1765
+ );
1766
+ }
1713
1767
  if (reservedProcess) {
1714
1768
  if (
1715
1769
  (error instanceof ProviderCommandStartRejectedError ||
1770
+ error instanceof ModalCommandStartNotDispatchedError ||
1716
1771
  error instanceof ModalCommandStartPreDispatchUnavailableError) &&
1717
1772
  reservedProcess.providerCommand?.kind === "modal-router-v1"
1718
1773
  ) {
@@ -5,7 +5,10 @@ import {
5
5
  parseExecBannerExitCode,
6
6
  parseExecBannerSessionId,
7
7
  } from "./exec-banner";
8
- import { RoutingMutationOutcomeUnknownError } from "./routing/routing-session";
8
+ import {
9
+ RoutingMutationOutcomeUnknownError,
10
+ renderRoutingMutationOutcomeUnknownToolResult,
11
+ } from "./routing/routing-session";
9
12
  import { sendCommandInput } from "./command-input";
10
13
  import {
11
14
  withPendingCommandSupervision,
@@ -633,6 +636,8 @@ export function renderDirectToolFault(error: unknown, retainedProcessSessionId?:
633
636
  } catch {
634
637
  // A hostile error Proxy must not replace the original safe fault renderer.
635
638
  }
639
+ if (error instanceof RoutingMutationOutcomeUnknownError)
640
+ return renderRoutingMutationOutcomeUnknownToolResult(error);
636
641
  const details = error instanceof Error ? error.toString() : String(error);
637
642
  return `An error occurred while running the tool. Please try again. Error: ${details}`;
638
643
  }
@@ -1226,6 +1231,8 @@ class TurnToolCancellationControllerImpl implements TurnToolCancellationControll
1226
1231
  });
1227
1232
  }
1228
1233
  pendingStart?.settle();
1234
+ if (error instanceof RoutingMutationOutcomeUnknownError)
1235
+ return renderRoutingMutationOutcomeUnknownToolResult(error);
1229
1236
  throw error;
1230
1237
  } finally {
1231
1238
  remoteExec?.settle();