@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
@@ -2,6 +2,7 @@ import { type SessionEventType } from "@opengeni/contracts";
2
2
  import type { EventLogger } from "@opengeni/events";
3
3
  import type { Observability } from "@opengeni/observability";
4
4
  import type { CompanyBrainContributionReceipt } from "./model-context-contributions.js";
5
+ import { type OpenSandboxKubernetesInventory } from "./opensandbox-kubernetes-inventory.js";
5
6
  import { type RuntimeMetricsHooks, type SelfhostedOpObservation, type SelfhostedOpObserver } from "@opengeni/runtime";
6
7
  export type TurnOutcome = "completed" | "failed" | "cancelled" | "recovering";
7
8
  export type CreditMicrosKind = "usage" | "grant" | "topup" | "refund";
@@ -83,6 +84,26 @@ export declare class TurnLifecycleMetrics {
83
84
  private stopTimer;
84
85
  private now;
85
86
  }
87
+ export declare function modelRequestLifecycleMetricsFor(observability: Observability): ModelRequestLifecycleMetrics;
88
+ export declare class ModelRequestLifecycleMetrics {
89
+ private readonly observability;
90
+ private readonly options;
91
+ private readonly requests;
92
+ private readonly providers;
93
+ private timer;
94
+ constructor(observability: Observability, options?: {
95
+ now?: () => number;
96
+ refreshIntervalMs?: number;
97
+ });
98
+ start(key: string, provider: string): void;
99
+ event(key: string, interEventGapMs?: number): void;
100
+ finish(key: string): void;
101
+ refreshGauges(): void;
102
+ stop(): void;
103
+ private ensureTimer;
104
+ private stopTimer;
105
+ private now;
106
+ }
86
107
  export declare function recordTurnsQueuedGauge(observability: Observability, value: number): void;
87
108
  /**
88
109
  * Record the authoritative turn activity queue rather than aggregate Postgres
@@ -102,7 +123,8 @@ export declare function startTurnCapacityMonitor(input: {
102
123
  close: () => Promise<void>;
103
124
  };
104
125
  export declare function recordSandboxLeaseGauges(observability: Observability, counts: Partial<Record<SandboxLeaseLiveness, number>>): void;
105
- export declare const SANDBOX_INVENTORY_PROJECTION_DOMAINS: readonly ["leases", "checkpoint_artifacts", "rotation_backlog", "retained_processes", "expired_drains"];
126
+ export declare function recordOpenSandboxKubernetesInventoryGauges(observability: Observability, inventory: OpenSandboxKubernetesInventory): void;
127
+ export declare const SANDBOX_INVENTORY_PROJECTION_DOMAINS: readonly ["leases", "checkpoint_artifacts", "rotation_backlog", "retained_processes", "expired_drains", "opensandbox_kubernetes"];
106
128
  export type SandboxInventoryProjectionDomain = (typeof SANDBOX_INVENTORY_PROJECTION_DOMAINS)[number];
107
129
  export declare function recordSandboxInventoryProjectionSuccess(observability: Observability, domain: SandboxInventoryProjectionDomain, timestampSeconds?: number): void;
108
130
  export declare function recordSandboxInventoryProjectionFailure(observability: Observability, domain: SandboxInventoryProjectionDomain): void;
@@ -125,7 +147,7 @@ export declare function recordRetainedProcessInventoryGauges(observability: Obse
125
147
  activeCount: number;
126
148
  terminalOwnerCount: number;
127
149
  }>): void;
128
- export declare const EXPIRED_DRAINING_BACKENDS: readonly [...("blaxel" | "cloudflare" | "daytona" | "docker" | "e2b" | "local" | "modal" | "none" | "runloop" | "selfhosted" | "vercel")[], "unknown"];
150
+ export declare const EXPIRED_DRAINING_BACKENDS: readonly [...("blaxel" | "cloudflare" | "daytona" | "docker" | "e2b" | "local" | "modal" | "none" | "opensandbox" | "runloop" | "selfhosted" | "vercel")[], "unknown"];
129
151
  export declare const EXPIRED_DRAINING_AGE_BUCKETS: readonly ["lt_5m", "5m_1h", "1h_1d", "gte_1d"];
130
152
  export declare function recordExpiredDrainingSandboxLeaseGauges(observability: Observability, counts: Array<{
131
153
  backend: string;
@@ -147,12 +169,17 @@ export declare function recordModelRequestPhase(observability: Observability, in
147
169
  outcome?: "completed" | "failed" | "timed_out";
148
170
  durationSeconds: number;
149
171
  }): void;
150
- export type TurnStartupPhase = "claim_and_policy" | "turn_start_settlement" | "credential_selection" | "runtime_preparation" | "sandbox_establish" | "file_resolution" | "tool_context_preparation" | "tool_preparation" | "tool_server_construction" | "tool_required_connect" | "tool_optional_connect" | "tool_attempt_catalog_build" | "tool_attempt_catalog_persist" | "post_tool_preparation" | "agent_construction" | "post_agent_preparation" | "file_materialization" | "history_preparation" | "history_system_update_load" | "history_current_attachment_resolution" | "history_durable_history_load" | "history_sandbox_envelope_load" | "history_canonical_projection" | "history_provider_projection" | "history_attachment_ref_projection" | "history_screenshot_materialization" | "history_model_attachment_projection" | "history_runtime_input_assembly" | "history_artifact_candidate_scan" | "history_generated_image_materialization" | "history_position_load" | "owned_sandbox_setup" | "provider_dispatch" | "model_request_preparation" | "model_sdk_serialization" | "model_prepare_sandbox_agent_preparation" | "model_prepare_sandbox_agent_manifest_inventory" | "model_prepare_sandbox_session_manifest_inventory" | "model_prepare_sandbox_manifest_apply" | "model_prepare_sandbox_entry_materialization" | "model_prepare_sandbox_running_check" | "model_prepare_sandbox_start" | "model_prepare_sandbox_client_create" | "model_prepare_sandbox_client_resume" | "model_prepare_sandbox_client_delete" | "model_prepare_sandbox_client_state_serialize" | "model_prepare_sandbox_client_reuse_check" | "model_prepare_runner_before_mcp_tools" | "model_prepare_mcp_tools_snapshot" | "model_prepare_mcp_tools_before_input_filter" | "model_prepare_input_filter_base" | "model_prepare_input_filter_genesis" | "model_prepare_input_filter_host" | "model_prepare_input_filter_tool_output" | "model_prepare_input_filter_modality" | "model_prepare_input_filter_context" | "model_prepare_responses_input_conversion" | "model_prepare_responses_request_build" | "model_credential_resolution" | "model_wire_normalization" | "model_request_audit" | "stream_bootstrap";
172
+ export type TurnStartupPhase = "claim_and_policy" | "turn_start_settlement" | "credential_selection" | "runtime_preparation" | "sandbox_establish" | "file_resolution" | "tool_context_preparation" | "tool_preparation" | "tool_server_construction" | "tool_required_connect" | "tool_optional_connect" | "tool_attempt_catalog_build" | "tool_attempt_catalog_persist" | "post_tool_preparation" | "agent_construction" | "post_agent_preparation" | "file_materialization" | "history_preparation" | "history_system_update_load" | "history_current_attachment_resolution" | "history_durable_history_load" | "history_sandbox_envelope_load" | "history_canonical_projection" | "history_provider_projection" | "history_attachment_ref_projection" | "history_screenshot_materialization" | "history_model_attachment_projection" | "history_runtime_input_assembly" | "history_artifact_candidate_scan" | "history_generated_image_materialization" | "history_position_load" | "owned_sandbox_setup" | "provider_dispatch" | "model_request_preparation" | "model_sdk_serialization" | "model_prepare_sandbox_agent_preparation" | "model_prepare_sandbox_agent_manifest_inventory" | "model_prepare_sandbox_session_manifest_inventory" | "model_prepare_sandbox_manifest_apply" | "model_prepare_sandbox_entry_materialization" | "model_prepare_sandbox_running_check" | "model_prepare_sandbox_start" | "model_prepare_sandbox_client_create" | "model_prepare_sandbox_client_resume" | "model_prepare_sandbox_client_delete" | "model_prepare_sandbox_client_state_serialize" | "model_prepare_sandbox_client_reuse_check" | "model_prepare_sandbox_workspace_mutation_admission" | "model_prepare_sandbox_workspace_mutation_provider" | "model_prepare_sandbox_workspace_mutation_settlement" | "model_prepare_sandbox_first_routed_resolution_other" | "model_prepare_sandbox_first_routed_mutation_admission" | "model_prepare_sandbox_first_routed_provider_operation" | "model_prepare_sandbox_first_routed_mutation_settlement" | "model_prepare_sandbox_first_routed_other" | "model_prepare_sandbox_snapshot_wait" | "model_prepare_runner_before_first_sandbox_operation" | "model_prepare_sdk_after_first_sandbox_operation" | "model_prepare_runner_before_mcp_tools" | "model_prepare_mcp_tools_snapshot" | "model_prepare_mcp_tools_before_input_filter" | "model_prepare_input_filter_base" | "model_prepare_input_filter_genesis" | "model_prepare_input_filter_host" | "model_prepare_input_filter_tool_output" | "model_prepare_input_filter_modality" | "model_prepare_input_filter_context" | "model_prepare_responses_input_conversion" | "model_prepare_responses_request_build" | "model_credential_resolution" | "model_wire_normalization" | "model_request_audit" | "stream_bootstrap";
151
173
  export type TurnStartupOutcome = "completed" | "failed";
174
+ export type TurnStartupMilestone = "queue" | "provider_dispatch" | "first_byte";
152
175
  export type TurnStartupCache = "hit" | "miss" | "disabled" | "none";
153
176
  export type TurnStartupCountBucket = "0" | "1" | "2-5" | "6-20" | "21+" | "unknown";
154
177
  export type TurnSandboxEstablishPolicy = "eager" | "on-demand";
155
- export type TurnSandboxEstablishReason = "eligible" | "lazy_disabled" | "machine_primary" | "backend_none" | "initial_run_credentials" | "generated_video_files" | "signed_file_resources";
178
+ export type TurnSandboxEstablishReason = "eligible" | "lazy_disabled" | "machine_primary" | "backend_none" | "initial_run_credentials" | "initial_run_credentials_deferred" | "generated_video_files" | "signed_file_resources";
179
+ export type SandboxLogicalProvisionCategory = "create" | "resume" | "exec_readiness" | "sibling_warming" | "lease_superseded" | "drain_capture_wait" | "archive_recovery" | "provider_transport" | "configuration" | "unknown";
180
+ export type SandboxLogicalProvisionStage = "create" | "resume" | "exec_readiness" | "sibling_warming" | "lease_admission" | "lifecycle_wait" | "archive_recovery" | "configuration" | "provider_transport" | "unknown";
181
+ export type SandboxLogicalProvisionOutcome = "completed" | "expected_transition" | "failed";
182
+ export type SandboxProvisionAttemptOutcome = "completed" | "retrying" | "failed";
156
183
  export declare function turnStartupCountBucket(count: number | null): TurnStartupCountBucket;
157
184
  /**
158
185
  * Measure the critical path from a durable turn start to provider dispatch.
@@ -178,12 +205,44 @@ export declare function recordTurnSandboxEstablishPolicy(observability: Observab
178
205
  reason: TurnSandboxEstablishReason;
179
206
  backend: string;
180
207
  }): void;
208
+ /** Physical establish/resume attempts inside one logical provision. Safe
209
+ * lifecycle retries are counted here, never as another user-visible failure. */
210
+ export declare function recordSandboxProvisionAttempt(observability: Observability, input: {
211
+ backend: string;
212
+ stage: SandboxLogicalProvisionStage;
213
+ category: SandboxLogicalProvisionCategory;
214
+ outcome: SandboxProvisionAttemptOutcome;
215
+ durationSeconds: number;
216
+ }): void;
217
+ /** One terminal observation for one correlation-qualified logical provision. */
218
+ export declare function recordSandboxLogicalProvision(observability: Observability, input: {
219
+ backend: string;
220
+ stage: SandboxLogicalProvisionStage;
221
+ category: SandboxLogicalProvisionCategory | "none";
222
+ outcome: SandboxLogicalProvisionOutcome;
223
+ expected: boolean;
224
+ internalAttempts: number;
225
+ durationSeconds: number;
226
+ }): void;
181
227
  export declare function recordTurnWorkerPreparationTotal(observability: Observability, input: {
182
228
  provider: string;
183
229
  backend: string;
184
230
  outcome: TurnStartupOutcome;
185
231
  durationSeconds: number;
186
232
  }): void;
233
+ /**
234
+ * Measure cumulative user-visible startup latency from the durable turn queue
235
+ * timestamp to a bounded milestone. Unlike the per-phase histogram above,
236
+ * these samples are end-to-end and can therefore back real queue/dispatch/TTFB
237
+ * SLOs without adding turn or session identifiers to Prometheus.
238
+ */
239
+ export declare function recordTurnStartupMilestone(observability: Observability, input: {
240
+ milestone: TurnStartupMilestone;
241
+ provider: string;
242
+ backend: string;
243
+ outcome: TurnStartupOutcome;
244
+ durationSeconds: number;
245
+ }): void;
187
246
  export type StreamDeltaClass = "message" | "reasoning";
188
247
  /**
189
248
  * Per-turn stream-timing tracker fed every normalized runtime event in push order.
@@ -0,0 +1,21 @@
1
+ export declare const OPENSANDBOX_CLEANUP_STUCK_SECONDS = 300;
2
+ export declare const OPENSANDBOX_EXPIRATION_OVERDUE_SECONDS = 180;
3
+ export declare const OPENSANDBOX_BATCHSANDBOX_PHASES: readonly ["pending", "running", "pausing", "paused", "resuming", "failed", "unknown"];
4
+ export type OpenSandboxBatchSandboxPhase = (typeof OPENSANDBOX_BATCHSANDBOX_PHASES)[number];
5
+ export declare const OPENSANDBOX_WORKLOAD_POD_CONDITIONS: readonly ["pending", "image_pull", "unschedulable"];
6
+ export type OpenSandboxWorkloadPodCondition = (typeof OPENSANDBOX_WORKLOAD_POD_CONDITIONS)[number];
7
+ export type OpenSandboxKubernetesInventory = {
8
+ batchSandboxPhases: Record<OpenSandboxBatchSandboxPhase, number>;
9
+ workloadPodConditions: Record<OpenSandboxWorkloadPodCondition, number>;
10
+ cleanupStuck: number;
11
+ expirationOverdue: number;
12
+ };
13
+ export type KubernetesJsonRequest = (url: URL) => Promise<unknown>;
14
+ export declare function inspectOpenSandboxKubernetesInventory(input: {
15
+ namespace: string;
16
+ nowMs?: number;
17
+ requestJson?: KubernetesJsonRequest;
18
+ apiUrl?: string;
19
+ tokenFile?: string;
20
+ caFile?: string;
21
+ }): Promise<OpenSandboxKubernetesInventory>;
@@ -0,0 +1,9 @@
1
+ import type { Settings } from "@opengeni/config";
2
+ import { type ConnectionCredentialsPort } from "@opengeni/contracts";
3
+ import { type Database } from "@opengeni/db";
4
+ /**
5
+ * Build the standalone personal-GitHub credential consumer. It returns only an
6
+ * OpenGeni broker bearer: the broad provider OAuth token remains encrypted in
7
+ * the API/database process and never crosses into a sandbox or worker result.
8
+ */
9
+ export declare function buildPersonalGitHubGitCredentials(db: Database, settings: Settings): NonNullable<ConnectionCredentialsPort["gitCredentials"]> | null;
@@ -0,0 +1,6 @@
1
+ import { type Settings } from "@opengeni/config";
2
+ import type { ConnectionCredentialsPort } from "@opengeni/contracts";
3
+ import { type Database } from "@opengeni/db";
4
+ /** Standalone credential broker for PR Review plus the existing GitHub App path.
5
+ * Embedded hosts keep precedence by supplying their own connectionCredentials. */
6
+ export declare function createStandaloneConnectionCredentialsPort(settings: Settings, db: Database): ConnectionCredentialsPort;
@@ -0,0 +1,45 @@
1
+ import type { ObjectStorage } from "@opengeni/storage";
2
+ import { type WorkspaceArchiveDescriptor, type WorkspaceArchiveObjectRef } from "@opengeni/contracts";
3
+ export declare class WorkspaceArchiveObjectStorageRequiredError extends Error {
4
+ readonly code: "workspace_archive_object_storage_required";
5
+ constructor(backend: string);
6
+ }
7
+ export declare function collectWorkspaceArchiveObjectKeys(resumeState: Record<string, unknown> | null | undefined): Set<string>;
8
+ export declare function putTarWorkspaceArchiveObject(input: {
9
+ objectStorage: ObjectStorage;
10
+ accountId: string;
11
+ workspaceId: string;
12
+ sandboxGroupId: string;
13
+ archive: {
14
+ bytes: Uint8Array;
15
+ descriptor: WorkspaceArchiveDescriptor;
16
+ };
17
+ }): Promise<WorkspaceArchiveObjectRef>;
18
+ export declare function putVersion1TarArchiveOrInline(input: {
19
+ backend: string;
20
+ objectStorage?: ObjectStorage | null | undefined;
21
+ accountId: string;
22
+ workspaceId: string;
23
+ sandboxGroupId: string;
24
+ archive: {
25
+ bytes: Uint8Array;
26
+ descriptor: WorkspaceArchiveDescriptor;
27
+ base64: string;
28
+ };
29
+ metrics?: {
30
+ onWorkspaceArchiveObject?: (input: {
31
+ outcome: "put" | "put_failed" | "deleted_unpublished";
32
+ backend: string;
33
+ }) => void;
34
+ };
35
+ }): Promise<{
36
+ workspaceArchive?: string;
37
+ workspaceArchiveRef?: WorkspaceArchiveObjectRef;
38
+ }>;
39
+ export declare function deleteUnpublishedWorkspaceArchiveObject(objectStorage: ObjectStorage | null | undefined, ref: WorkspaceArchiveObjectRef | undefined, metrics?: {
40
+ onWorkspaceArchiveObject?: (input: {
41
+ outcome: "deleted_unpublished";
42
+ backend: string;
43
+ }) => void;
44
+ }): Promise<void>;
45
+ export declare function deleteWorkspaceArchiveObjectKeys(objectStorage: ObjectStorage, keys: Iterable<string>): Promise<void>;
@@ -1,6 +1,8 @@
1
1
  import { type Settings } from "@opengeni/config";
2
- import { SandboxLeaseSupersededError, type Database, type LeaseHolderKind } from "@opengeni/db";
2
+ import { readLease, reinstateTurnLeaseHolder, SandboxLeaseSupersededError, type Database, type LeaseHolderKind } from "@opengeni/db";
3
3
  import { establishSandboxSessionFromEnvelope, type EstablishedSandboxSession, type RuntimeMetricsHooks } from "@opengeni/runtime";
4
+ import type { ObjectStorage } from "@opengeni/storage";
5
+ import type { Observability } from "@opengeni/observability";
4
6
  export type ResumeHolderKind = LeaseHolderKind;
5
7
  /**
6
8
  * The durable identity of a turn holding a shared sandbox lease.
@@ -19,11 +21,18 @@ export declare function isRetryableDegradedRestore(restore: {
19
21
  export type SandboxResumeServices = {
20
22
  db: Database;
21
23
  settings: Settings;
24
+ objectStorage?: ObjectStorage | null;
22
25
  /** Exact settings before a verified rig provider image overlaid the logical
23
26
  * pack/deployment image. Fresh-create NotFound fallback must preserve an
24
27
  * ID-only logical base instead of selecting the provider default. */
25
28
  logicalFallbackSettings?: Settings;
26
29
  sandboxMetrics?: RuntimeMetricsHooks;
30
+ /** Structured logger for lifecycle decisions (holder release reasons). Falls
31
+ * back to the console when a lean caller passes none. */
32
+ observability?: Pick<Observability, "info" | "warn">;
33
+ /** Test seam only: cadence of the private holder-liveness loop (default 10 s).
34
+ * Production keeps the default; the dead-worker reap horizon assumes it. */
35
+ holderLivenessIntervalMs?: number;
27
36
  /**
28
37
  * The logical turn-attempt lifetime, not merely the provider request lifetime.
29
38
  * Some provider SDK calls cannot be interrupted. Aborting this signal still
@@ -51,7 +60,7 @@ export type ResumeBoxIds = {
51
60
  * disclosure/attribution). For a singleton group this == sandboxGroupId. */
52
61
  sessionId: string;
53
62
  /** The backend the box runs on (sessions.sandbox_backend). */
54
- backend: string;
63
+ backend: Settings["sandboxBackend"];
55
64
  /** The OS axis (sessions.sandbox_os); default 'linux'. */
56
65
  os?: string;
57
66
  /**
@@ -100,6 +109,21 @@ export type ResumedTurnSandbox = {
100
109
  workspaceWritersQuiesced?: boolean;
101
110
  }) => Promise<void>;
102
111
  };
112
+ /**
113
+ * Structural ownership of the provider boundary that failed while establishing
114
+ * a logical sandbox provision. Object errors retain their identity and receive
115
+ * an out-of-band stage; primitive thrown values use a typed wrapper. In both
116
+ * cases the source diagnostic is unchanged and the stage is never guessed from
117
+ * prose.
118
+ */
119
+ export type SandboxProvisionFailureStage = "create" | "resume" | "archive_recovery";
120
+ export declare class SandboxProvisionStageError extends Error {
121
+ readonly stage: SandboxProvisionFailureStage;
122
+ readonly source: unknown;
123
+ readonly name = "SandboxProvisionStageError";
124
+ constructor(stage: SandboxProvisionFailureStage, source: unknown);
125
+ }
126
+ export declare function sandboxProvisionFailureStage(error: unknown): SandboxProvisionFailureStage | null;
103
127
  export declare abstract class SandboxWarmingTimeoutError extends Error {
104
128
  readonly backend: string;
105
129
  readonly timeoutMs: number;
@@ -131,10 +155,10 @@ export declare class SandboxLeaseInstanceLostError extends SandboxLeaseSupersede
131
155
  constructor(sandboxGroupId: string, leaseEpoch: number, lostInstanceId: string);
132
156
  }
133
157
  /**
134
- * Modal may return a sandbox handle before its command router accepts the first
135
- * exec. The upstream session's yieldTimeMs starts only after sandbox.exec()
136
- * returns, so it cannot bound that initial RPC. Probe it before publishing the
137
- * lease as warm and enforce our own wall-clock deadline.
158
+ * A remote provider may return a sandbox handle before its command router
159
+ * accepts the first exec. The upstream session's yieldTimeMs starts only after
160
+ * sandbox.exec() returns, so it cannot bound that initial RPC. Probe it before
161
+ * publishing the lease as warm and enforce our own wall-clock deadline.
138
162
  */
139
163
  export declare function waitForSandboxExecReadiness(established: EstablishedSandboxSession, timeoutMs?: number, identity?: {
140
164
  sandboxGroupId?: string | null;
@@ -144,8 +168,43 @@ export declare function safeSnapshotError(error: unknown): {
144
168
  errorCode: "snapshot_operation_failed";
145
169
  status?: number;
146
170
  origin: "sandbox-resume";
171
+ causeName?: string;
172
+ integrityCode?: string;
147
173
  };
148
174
  export declare function waitForWarmSnapshot(snapshot: Promise<unknown>, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
175
+ export type SandboxDeadlineRotationCheckpointResult = {
176
+ /** The exact established epoch still carries a requested rotation and a
177
+ * complete current-generation archive: the turn may abort orderly. */
178
+ checkpointed: boolean;
179
+ /** What the defense-in-depth holder step observed before the capture. */
180
+ holder: Awaited<ReturnType<typeof reinstateTurnLeaseHolder>>["status"];
181
+ lease: Awaited<ReturnType<typeof readLease>>;
182
+ };
183
+ /**
184
+ * The orderly provider-deadline rotation checkpoint for one running turn. The
185
+ * turn-side lease heartbeat calls this once it observes a rotation-fenced lease
186
+ * at its established epoch/instance; `checkpointed: true` licenses the
187
+ * SandboxDeadlineRotationError abort that hands the same logical turn to the
188
+ * cold successor.
189
+ *
190
+ * Defense in depth: the warm capture claim requires exactly this turn's holder.
191
+ * If that holder was lost while the attempt is still the active writer (a stale
192
+ * release, a reap race), `reinstateTurnLeaseHolder` puts it back under the
193
+ * exact epoch/instance fence before the capture, so a lost holder cannot
194
+ * silently disable the orderly abort and leave the reaper to terminate the box
195
+ * under the running turn. Never captures when the epoch/instance changed.
196
+ */
197
+ export declare function persistSandboxDeadlineRotationCheckpoint(services: SandboxResumeServices, ids: {
198
+ accountId: string;
199
+ workspaceId: string;
200
+ sessionId: string;
201
+ turnId: string;
202
+ attemptId: string;
203
+ sandboxGroupId: string;
204
+ }, session: unknown, expected: {
205
+ leaseEpoch: number;
206
+ instanceId: string;
207
+ }, signal?: AbortSignal): Promise<SandboxDeadlineRotationCheckpointResult>;
149
208
  /**
150
209
  * MID-SESSION /workspace snapshot (sandbox-file-persistence). The reaper's
151
210
  * drain-persist only protects boxes the reaper itself kills; anything else —
@@ -1,7 +1,7 @@
1
1
  import { type Settings } from "@opengeni/config";
2
- import { type Database } from "@opengeni/db";
2
+ import { type Database, type EnrollmentRecord } from "@opengeni/db";
3
3
  import type { EventBus } from "@opengeni/events";
4
- import { type EstablishedSandboxSession, type RoutingSandboxOperationObserver, type SelfhostedOpObserver, type SelfhostedRelayConfig, type OpStreamJournal } from "@opengeni/runtime";
4
+ import { type EstablishedSandboxSession, type RoutingSandboxFirstOperationObserver, type RoutingSandboxOperationObserver, type SelfhostedOpObserver, type SelfhostedRelayConfig, type OpStreamJournal } from "@opengeni/runtime";
5
5
  export type RoutingWiringServices = {
6
6
  db: Database;
7
7
  settings: Settings;
@@ -43,6 +43,18 @@ type TurnRoutingWiringServices = RoutingWiringServices & {
43
43
  export type RoutingWiringIds = {
44
44
  workspaceId: string;
45
45
  sessionId: string;
46
+ resourceAccountId?: string;
47
+ resourceSubjectId?: string;
48
+ /** Frozen initiating-human authority for personal Connected Machine use.
49
+ * Every routed operation reasserts this exact accepted attempt before the
50
+ * control-plane connection is resolved. */
51
+ personalMachineAttempt?: {
52
+ accountId: string;
53
+ subjectId: string;
54
+ turnId: string;
55
+ attemptId: string;
56
+ executionGeneration: number;
57
+ };
46
58
  /** Canonical turn-attempt fence used to admit persistable-home mutations.
47
59
  * Omit outside a running worker attempt; mutation hooks then remain disabled. */
48
60
  workspaceMutationFence?: {
@@ -136,14 +148,31 @@ export declare function wrapLazyTurnBoxWithRouting(services: TurnRoutingWiringSe
136
148
  sandboxGroupId: string;
137
149
  backend: string;
138
150
  };
151
+ onFirstOperation?: RoutingSandboxFirstOperationObserver;
139
152
  }): EstablishedSandboxSession;
140
153
  export type SelfhostedTurnSessionArgs = {
154
+ accountId: string;
155
+ /** Authorization/session workspace. */
141
156
  workspaceId: string;
157
+ sessionId: string;
158
+ /** Physical machine-origin workspace used in control-plane routing. */
159
+ controlWorkspaceId?: string;
160
+ /** Exact launching attempt required before a live Connected Machine command
161
+ * can transfer into session ownership. Omitted by non-turn/test callers,
162
+ * which therefore cannot yield a durable background command. */
163
+ backgroundCommandAttempt?: Pick<NonNullable<RoutingWiringIds["workspaceMutationFence"]>, "turnId" | "executionGeneration" | "attemptId">;
142
164
  /** The target machine's enrollment id == the agent subject id. */
143
165
  agentId: string;
166
+ /** Exact daemon process currently leased for the enrollment. */
167
+ connectionInstanceId: string;
144
168
  /** Whether the target machine advertised Capabilities.op_stream in its latest
145
169
  * Hello. The runtime-side transport gate must still require the server flag. */
146
170
  opStream: boolean;
171
+ /** Desired per-enrollment command policy and capability from the same live
172
+ * enrollment snapshot as the process identity. */
173
+ operationResourcePolicy: EnrollmentRecord["operationPolicy"];
174
+ operationResourcePolicySupported: boolean;
175
+ operationCpuQuotaSupported: boolean;
147
176
  /** The active pointer's epoch — the control-op fence echoed to the agent. */
148
177
  epoch: number;
149
178
  /** The run's declared sandbox environment (the SAME object fed to buildAgent +
@@ -154,6 +183,13 @@ export type SelfhostedTurnSessionArgs = {
154
183
  transientExecEnvironment?: () => Readonly<Record<string, string>>;
155
184
  /** The session working directory (per-session pointer). Null ⇒ workspace_root. */
156
185
  workingDir: string | null;
186
+ /** Effective absolute host-native root frozen for this attempt. */
187
+ workspaceRoot: string;
188
+ /** Present only for a user-owned machine. Every provider operation rechecks
189
+ * this frozen accepted-attempt authority immediately before dispatch. */
190
+ personalMachineAttempt?: NonNullable<RoutingWiringIds["personalMachineAttempt"]> & {
191
+ sessionId: string;
192
+ };
157
193
  };
158
194
  export declare function establishSelfhostedTurnSession(services: RoutingWiringServices, args: SelfhostedTurnSessionArgs): Promise<EstablishedSandboxSession>;
159
195
  /** Whether the routing proxy should wrap the turn box: the hot-swap feature is
@@ -0,0 +1,33 @@
1
+ export type ScheduledAlertOccurrenceDeclaration = {
2
+ status: "firing" | "resolved";
3
+ startsAt: string;
4
+ fingerprint: string;
5
+ labels: Record<string, string>;
6
+ provider?: string;
7
+ };
8
+ export type ScheduledAlertOccurrenceIdentity = {
9
+ status: "firing" | "resolved";
10
+ sessionCreateIdempotencyKey: string;
11
+ /** Exact bounded labels from the validated structured occurrence. */
12
+ labels: Readonly<Record<string, string>>;
13
+ };
14
+ /**
15
+ * Bind the series-stable occurrence identity to one accepted task execution
16
+ * definition. A later task revision must not adopt the prior responder root,
17
+ * because that session has already frozen the old prompt/tool/authority policy.
18
+ */
19
+ export declare function scheduledAlertResponderSessionCreateIdempotencyKey(input: {
20
+ occurrence: ScheduledAlertOccurrenceIdentity;
21
+ taskAuthorityRevision: number;
22
+ taskExecutionDigest: string;
23
+ }): string;
24
+ /**
25
+ * Derive one content-free, workspace-bound identity for an Alertmanager-style
26
+ * alert occurrence. Missing or malformed metadata deliberately returns null so
27
+ * ordinary scheduled tasks retain their existing new-session-per-run behavior.
28
+ */
29
+ export declare function scheduledAlertOccurrenceIdentity(input: {
30
+ workspaceId: string;
31
+ scheduledTaskId: string;
32
+ metadata: Record<string, unknown>;
33
+ }): ScheduledAlertOccurrenceIdentity | null;