@opengeni/worker-bundle 0.16.21 → 0.17.2

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 (180) hide show
  1. package/dist/activities/agent-turn.d.ts +145 -32
  2. package/dist/activities/api-integrations.d.ts +21 -0
  3. package/dist/activities/codemode-dispatcher.d.ts +35 -0
  4. package/dist/activities/codemode-token-renewal.d.ts +23 -0
  5. package/dist/activities/codex-capacity.d.ts +5 -5
  6. package/dist/activities/codex-image-generation.d.ts +21 -0
  7. package/dist/activities/context-compaction.d.ts +3 -0
  8. package/dist/activities/documents.d.ts +3 -2
  9. package/dist/activities/environment.d.ts +11 -7
  10. package/dist/activities/expiring-material-renewal.d.ts +5 -3
  11. package/dist/activities/file-upload-reaper.d.ts +7 -2
  12. package/dist/activities/gateway-image-generation.d.ts +39 -0
  13. package/dist/activities/gateway-video-generation.d.ts +53 -0
  14. package/dist/activities/generated-images.d.ts +112 -0
  15. package/dist/activities/git-credential-renewal.d.ts +2 -2
  16. package/dist/activities/goals.d.ts +2 -2
  17. package/dist/activities/google-drive-changes.d.ts +99 -0
  18. package/dist/activities/image-generation-operation.d.ts +74 -0
  19. package/dist/activities/image-generation-references.d.ts +25 -0
  20. package/dist/activities/knowledge-source-sync-driver.d.ts +23 -0
  21. package/dist/activities/knowledge-source-sync.d.ts +75 -0
  22. package/dist/activities/packs.d.ts +13 -26
  23. package/dist/activities/parent-wake.d.ts +1 -1
  24. package/dist/activities/retained-screenshot-reaper.d.ts +32 -0
  25. package/dist/activities/retained-screenshots.d.ts +129 -0
  26. package/dist/activities/rig-verification.d.ts +82 -5
  27. package/dist/activities/run-credential-renewal.d.ts +2 -2
  28. package/dist/activities/run-input.d.ts +5 -1
  29. package/dist/activities/sandbox-images.d.ts +14 -0
  30. package/dist/activities/sandbox-lease.d.ts +47 -9
  31. package/dist/activities/scheduled-tasks.d.ts +2 -2
  32. package/dist/activities/session-state.d.ts +4 -4
  33. package/dist/activities/streaming.d.ts +1 -1
  34. package/dist/activities/types.d.ts +71 -5
  35. package/dist/activities/video-generation-admission.d.ts +38 -0
  36. package/dist/activities/video-generation-credential.d.ts +7 -0
  37. package/dist/activities/video-generation-reconciliation.d.ts +13 -0
  38. package/dist/activities/video-media-validation.d.ts +34 -0
  39. package/dist/activities/video-output-retention.d.ts +36 -0
  40. package/dist/activities/video-reference-staging.d.ts +49 -0
  41. package/dist/activities/workflow-wake.d.ts +2 -2
  42. package/dist/activities/workspace-capture.d.ts +11 -1
  43. package/dist/activities-control-44KBWLSM.js +6885 -0
  44. package/dist/activities-control-44KBWLSM.js.map +1 -0
  45. package/dist/activities-control.d.ts +289 -0
  46. package/dist/activities-turn-K4CEDEGJ.js +14675 -0
  47. package/dist/activities-turn-K4CEDEGJ.js.map +1 -0
  48. package/dist/activities-turn.d.ts +17 -0
  49. package/dist/activities.d.ts +130 -147
  50. package/dist/activity-services.d.ts +10 -0
  51. package/dist/artifact-materializer-entry.d.ts +6 -0
  52. package/dist/artifact-materializer-entry.js +2662 -0
  53. package/dist/artifact-materializer-entry.js.map +1 -0
  54. package/dist/artifact-outbox-entry.d.ts +2 -0
  55. package/dist/artifact-outbox-entry.js +681 -0
  56. package/dist/artifact-outbox-entry.js.map +1 -0
  57. package/dist/chunk-E3RI3I33.js +828 -0
  58. package/dist/chunk-E3RI3I33.js.map +1 -0
  59. package/dist/chunk-GRFQTTSQ.js +448 -0
  60. package/dist/chunk-GRFQTTSQ.js.map +1 -0
  61. package/dist/chunk-KKCRGAGZ.js +3091 -0
  62. package/dist/chunk-KKCRGAGZ.js.map +1 -0
  63. package/dist/{chunk-BJUW5LCM.js → chunk-RAMNYSAW.js} +15 -12
  64. package/dist/chunk-RAMNYSAW.js.map +1 -0
  65. package/dist/concurrency.d.ts +108 -5
  66. package/dist/editable-artifact-hint-broker.d.ts +49 -0
  67. package/dist/editable-artifact-materializer-launcher.d.ts +49 -0
  68. package/dist/editable-artifact-materializer-service.d.ts +108 -0
  69. package/dist/editable-artifact-materializer-storage.d.ts +12 -0
  70. package/dist/editable-artifact-materializer-subprocess.d.ts +50 -0
  71. package/dist/editable-artifact-materializer.d.ts +262 -0
  72. package/dist/editable-artifact-outbox-dispatcher.d.ts +44 -0
  73. package/dist/editable-artifact-outbox-service.d.ts +70 -0
  74. package/dist/host-export.d.ts +1 -1
  75. package/dist/host-export.js +1 -1
  76. package/dist/index.d.ts +176 -10
  77. package/dist/index.js +675 -16460
  78. package/dist/index.js.map +1 -1
  79. package/dist/memory-pressure-guard.d.ts +57 -0
  80. package/dist/model-checkpoint-memory-collector.d.ts +22 -0
  81. package/dist/observability-metrics.d.ts +33 -0
  82. package/dist/sandbox-reaper-contract.d.ts +40 -0
  83. package/dist/sandbox-reaper-timeout.d.ts +14 -0
  84. package/dist/sandbox-resume.d.ts +40 -7
  85. package/dist/sandbox-routing.d.ts +13 -6
  86. package/dist/worker-service-lifecycle.d.ts +6 -2
  87. package/dist/workflow-bundle.js +1044 -363
  88. package/dist/workflows/activities.d.ts +7 -1
  89. package/dist/workflows/document-index.d.ts +1 -1
  90. package/dist/workflows/knowledge-source-sync.d.ts +13 -0
  91. package/dist/workflows/rig-verification.d.ts +1 -1
  92. package/dist/workflows/sandbox-reaper.d.ts +8 -0
  93. package/dist/workflows/scheduled-tasks.d.ts +1 -1
  94. package/dist/workflows/session.d.ts +2 -2
  95. package/dist/workflows/video-generation.d.ts +10 -0
  96. package/dist/workflows/workflow-wake.d.ts +1 -1
  97. package/dist/workflows.d.ts +9 -7
  98. package/package.json +34 -15
  99. package/src/activities/agent-turn.ts +1905 -559
  100. package/src/activities/api-integrations.ts +138 -0
  101. package/src/activities/codemode-dispatcher.ts +335 -0
  102. package/src/activities/codemode-token-renewal.ts +64 -0
  103. package/src/activities/codex-capacity.ts +16 -7
  104. package/src/activities/codex-image-generation.ts +56 -0
  105. package/src/activities/codex-rotation.ts +19 -5
  106. package/src/activities/context-compaction.ts +47 -6
  107. package/src/activities/documents.ts +14 -4
  108. package/src/activities/environment.ts +52 -60
  109. package/src/activities/expiring-material-renewal.ts +16 -7
  110. package/src/activities/file-upload-reaper.ts +34 -3
  111. package/src/activities/gateway-image-generation.ts +146 -0
  112. package/src/activities/gateway-video-generation.ts +298 -0
  113. package/src/activities/generated-images.ts +860 -0
  114. package/src/activities/git-credential-renewal.ts +3 -3
  115. package/src/activities/goals.ts +6 -2
  116. package/src/activities/google-drive-changes.ts +454 -0
  117. package/src/activities/image-generation-operation.ts +333 -0
  118. package/src/activities/image-generation-references.ts +118 -0
  119. package/src/activities/knowledge-source-sync-driver.ts +27 -0
  120. package/src/activities/knowledge-source-sync.ts +2840 -0
  121. package/src/activities/mcp-credentials.ts +1 -0
  122. package/src/activities/packs.ts +55 -55
  123. package/src/activities/recording.ts +4 -5
  124. package/src/activities/retained-screenshot-reaper.ts +202 -0
  125. package/src/activities/retained-screenshots.ts +1317 -0
  126. package/src/activities/rig-verification.ts +567 -77
  127. package/src/activities/run-credential-renewal.ts +9 -2
  128. package/src/activities/run-input.ts +40 -10
  129. package/src/activities/sandbox-images.ts +167 -0
  130. package/src/activities/sandbox-lease.ts +1065 -483
  131. package/src/activities/scheduled-tasks.ts +96 -7
  132. package/src/activities/session-state.ts +4 -4
  133. package/src/activities/streaming.ts +42 -3
  134. package/src/activities/types.ts +87 -5
  135. package/src/activities/video-generation-admission.ts +270 -0
  136. package/src/activities/video-generation-credential.ts +34 -0
  137. package/src/activities/video-generation-reconciliation.ts +578 -0
  138. package/src/activities/video-media-validation.ts +326 -0
  139. package/src/activities/video-output-retention.ts +314 -0
  140. package/src/activities/video-reference-staging.ts +263 -0
  141. package/src/activities/workflow-wake.ts +2 -2
  142. package/src/activities/workspace-capture.ts +77 -13
  143. package/src/activities-control.ts +54 -0
  144. package/src/activities-turn.ts +40 -0
  145. package/src/activities.ts +50 -118
  146. package/src/activity-services.ts +62 -0
  147. package/src/artifact-materializer-entry.ts +35 -0
  148. package/src/artifact-outbox-entry.ts +29 -0
  149. package/src/concurrency.ts +484 -6
  150. package/src/editable-artifact-hint-broker.ts +235 -0
  151. package/src/editable-artifact-materializer-launcher.ts +515 -0
  152. package/src/editable-artifact-materializer-service.ts +787 -0
  153. package/src/editable-artifact-materializer-storage.ts +413 -0
  154. package/src/editable-artifact-materializer-subprocess.ts +956 -0
  155. package/src/editable-artifact-materializer.ts +1289 -0
  156. package/src/editable-artifact-outbox-dispatcher.ts +244 -0
  157. package/src/editable-artifact-outbox-service.ts +438 -0
  158. package/src/host-export-pump.ts +28 -11
  159. package/src/http.ts +3 -6
  160. package/src/index.ts +277 -72
  161. package/src/memory-pressure-guard.ts +489 -0
  162. package/src/model-checkpoint-memory-collector.ts +116 -0
  163. package/src/observability-metrics.ts +202 -7
  164. package/src/sandbox-reaper-contract.ts +73 -0
  165. package/src/sandbox-reaper-timeout.ts +79 -0
  166. package/src/sandbox-resume.ts +331 -157
  167. package/src/sandbox-routing.ts +49 -39
  168. package/src/worker-service-lifecycle.ts +82 -12
  169. package/src/workflows/activities.ts +30 -0
  170. package/src/workflows/file-upload-reaper.ts +6 -1
  171. package/src/workflows/knowledge-source-sync.ts +83 -0
  172. package/src/workflows/sandbox-reaper.ts +183 -21
  173. package/src/workflows/scheduled-tasks.ts +42 -6
  174. package/src/workflows/video-generation.ts +36 -0
  175. package/src/workflows.ts +17 -1
  176. package/dist/activities/redaction.d.ts +0 -1
  177. package/dist/activities/toolspace-token-renewal.d.ts +0 -23
  178. package/dist/chunk-BJUW5LCM.js.map +0 -1
  179. package/src/activities/redaction.ts +0 -9
  180. package/src/activities/toolspace-token-renewal.ts +0 -57
@@ -93,7 +93,7 @@ function createHostExportPump(options) {
93
93
  maxBytes: batchMaxBytes
94
94
  };
95
95
  const settleFailure = async (error) => {
96
- const message = safeErrorMessage(error);
96
+ const message = exactHostExportErrorMessage(error);
97
97
  let failures = 0;
98
98
  try {
99
99
  failures = await failHostExportBatch(options.db, {
@@ -106,17 +106,15 @@ function createHostExportPump(options) {
106
106
  } catch (settlementError) {
107
107
  options.observability?.warn("host export failure settlement was stale", {
108
108
  kind,
109
- consumerId,
110
- error: safeErrorMessage(settlementError)
109
+ ...hostExportPublicErrorFields(settlementError, "host_export_failure_settlement_stale")
111
110
  });
112
111
  }
113
112
  const blocked = failures >= maxFailures;
114
113
  options.observability?.warn("host export batch failed", {
115
114
  kind,
116
- consumerId,
117
115
  failures,
118
116
  blocked,
119
- error: message
117
+ ...hostExportPublicErrorFields(error, "host_export_batch_delivery_failed")
120
118
  });
121
119
  const result2 = {
122
120
  kind,
@@ -143,8 +141,7 @@ function createHostExportPump(options) {
143
141
  } catch (error) {
144
142
  options.observability?.error("host export retention prune failed", {
145
143
  kind,
146
- consumerId,
147
- error: safeErrorMessage(error)
144
+ ...hostExportPublicErrorFields(error, "host_export_retention_prune_failed")
148
145
  });
149
146
  }
150
147
  const result2 = {
@@ -258,7 +255,7 @@ function createHostExportPump(options) {
258
255
  }
259
256
  } catch (error) {
260
257
  options.observability?.error("host export pump iteration failed", {
261
- error: safeErrorMessage(error)
258
+ ...hostExportPublicErrorFields(error, "host_export_pump_iteration_failed")
262
259
  });
263
260
  }
264
261
  if (running) await waitForPoll();
@@ -314,12 +311,18 @@ function validateInstanceId(value) {
314
311
  }
315
312
  return value;
316
313
  }
317
- function safeErrorMessage(error) {
318
- const message = error instanceof Error ? error.message : String(error);
319
- return message.trim().slice(0, 500) || "host sink failed";
314
+ function exactHostExportErrorMessage(error) {
315
+ return error instanceof Error ? error.message : String(error);
316
+ }
317
+ function hostExportPublicErrorFields(_error, errorCode) {
318
+ return {
319
+ errorClass: "HostExportOperationError",
320
+ errorCode,
321
+ origin: "host-export"
322
+ };
320
323
  }
321
324
 
322
325
  export {
323
326
  createHostExportPump
324
327
  };
325
- //# sourceMappingURL=chunk-BJUW5LCM.js.map
328
+ //# sourceMappingURL=chunk-RAMNYSAW.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/host-export-pump.ts"],"sourcesContent":["import type { HostEventSink, HostUsageSink } from \"@opengeni/contracts\";\nimport {\n acknowledgeHostExportBatch,\n claimHostExportBatch,\n disableHostExportConsumer,\n failHostExportBatch,\n getHostExportConsumerStatus,\n pruneHostExportOutbox,\n registerHostExportConsumer,\n retireHostExportConsumer,\n type Database,\n type HostExportConsumerStatus,\n type HostExportKind,\n} from \"@opengeni/db\";\nimport type { Observability } from \"@opengeni/observability\";\n\nexport type HostExportDrainResult =\n | { kind: HostExportKind; outcome: \"not_configured\" | \"idle\" }\n | { kind: HostExportKind; outcome: \"blocked\"; failures: number }\n | {\n kind: HostExportKind;\n outcome: \"delivered\";\n count: number;\n throughCursor: string;\n }\n | {\n kind: HostExportKind;\n outcome: \"failed\";\n failures: number;\n blocked: boolean;\n };\n\nexport type HostExportPumpOptions = {\n /** A handle authenticated as the separately provisioned host-export role. */\n db: Database;\n eventSink?: HostEventSink;\n usageSink?: HostUsageSink;\n observability?: Observability;\n instanceId?: string;\n pollIntervalMs?: number;\n leaseSeconds?: number;\n batchLimit?: number;\n batchMaxBytes?: number;\n maxFailures?: number;\n /** Maximum catch-up batches per poll tick; bounds one iteration's work. */\n maxBatchesPerPoll?: number;\n /** Acked rows younger than this remain available for replay. */\n pruneGraceSeconds?: number;\n /** Maximum rows pruned after one successful acknowledgement. */\n pruneLimit?: number;\n};\n\nexport type HostExportPump = {\n /** Register configured consumers and start the non-overlapping poll loop. */\n start: () => Promise<void>;\n /** Stop polling and wait for the currently executing sink call, if any. */\n stop: () => Promise<void>;\n /** Execute at most one bounded batch for each configured sink. */\n drainOnce: () => Promise<HostExportDrainResult[]>;\n /**\n * Disable this named consumer while retaining its replay checkpoint. If it is\n * the last enabled consumer of the kind, capture stops and that interval is\n * intentionally unrecoverable. Normal process shutdown must not call this.\n */\n disable: (kind: HostExportKind) => Promise<void>;\n /** Permanently remove a stopped consumer and release its retention floor. */\n retire: (kind: HostExportKind) => Promise<void>;\n status: (kind: HostExportKind) => Promise<HostExportConsumerStatus | null>;\n};\n\n/**\n * Build the durable delivery loop used by embedded hosts.\n *\n * The source transaction writes the outbox; this pump only leases, delivers,\n * and checkpoints it. Delivery is intentionally at least once: a process death\n * after sink success but before acknowledgement repeats the same idempotency\n * keys. Sink implementations must therefore deduplicate those keys.\n */\nexport function createHostExportPump(options: HostExportPumpOptions): HostExportPump {\n if (!options.eventSink && !options.usageSink) {\n throw new Error(\"createHostExportPump requires at least one host sink\");\n }\n const instanceId = validateInstanceId(\n options.instanceId ?? `worker-${process.pid}-${crypto.randomUUID()}`,\n );\n const pollIntervalMs = boundedInteger(options.pollIntervalMs, 1_000, 25, 60_000);\n const leaseSeconds = boundedInteger(options.leaseSeconds, 60, 5, 300);\n const batchLimit = boundedInteger(options.batchLimit, 100, 1, 256);\n const batchMaxBytes = boundedInteger(options.batchMaxBytes, 1_048_576, 98_304, 4_194_304);\n const maxFailures = boundedInteger(options.maxFailures, 20, 1, 1_000);\n const maxBatchesPerPoll = boundedInteger(options.maxBatchesPerPoll, 32, 1, 1_000);\n const pruneGraceSeconds = boundedInteger(options.pruneGraceSeconds, 3_600, 0, 604_800);\n const pruneLimit = boundedInteger(options.pruneLimit, 1_000, 1, 10_000);\n let running = false;\n let loopPromise: Promise<void> | null = null;\n let waitTimer: ReturnType<typeof setTimeout> | null = null;\n let wakeWait: (() => void) | null = null;\n let lifecycleTail: Promise<void> = Promise.resolve();\n let drainTail: Promise<void> = Promise.resolve();\n const retiringKinds = new Set<HostExportKind>();\n\n const configuredConsumer = (kind: HostExportKind): string | null =>\n kind === \"session_event\"\n ? (options.eventSink?.consumerId ?? null)\n : (options.usageSink?.consumerId ?? null);\n\n const recordResult = (result: HostExportDrainResult, durationSeconds: number) => {\n const labels = { kind: result.kind, outcome: result.outcome };\n options.observability?.incrementCounter({\n name: \"opengeni_host_export_batches_total\",\n help: \"Durable host export batch attempts by outcome.\",\n labels,\n });\n options.observability?.observeHistogram({\n name: \"opengeni_host_export_batch_duration_seconds\",\n help: \"Duration of durable host export batch attempts.\",\n labels: { kind: result.kind },\n value: durationSeconds,\n });\n if (result.outcome === \"delivered\") {\n options.observability?.incrementCounter({\n name: \"opengeni_host_export_records_total\",\n help: \"Durable host export records acknowledged by a host sink.\",\n labels: { kind: result.kind },\n amount: result.count,\n });\n options.observability?.setGauge({\n name: \"opengeni_host_export_consumer_blocked\",\n help: \"Whether the durable host export consumer is blocked.\",\n labels: { kind: result.kind },\n value: 0,\n });\n } else if (result.outcome === \"failed\") {\n options.observability?.setGauge({\n name: \"opengeni_host_export_consumer_blocked\",\n help: \"Whether the durable host export consumer is blocked.\",\n labels: { kind: result.kind },\n value: result.blocked ? 1 : 0,\n });\n } else if (result.outcome === \"blocked\") {\n options.observability?.setGauge({\n name: \"opengeni_host_export_consumer_blocked\",\n help: \"Whether the durable host export consumer is blocked.\",\n labels: { kind: result.kind },\n value: 1,\n });\n }\n };\n\n const drainKind = async (kind: HostExportKind): Promise<HostExportDrainResult> => {\n if (retiringKinds.has(kind)) return { kind, outcome: \"not_configured\" };\n const startedAt = performance.now();\n const consumerId = configuredConsumer(kind);\n if (!consumerId) {\n const result: HostExportDrainResult = { kind, outcome: \"not_configured\" };\n recordResult(result, (performance.now() - startedAt) / 1_000);\n return result;\n }\n const leaseToken = crypto.randomUUID();\n const common = {\n consumerId,\n leaseToken,\n leaseHolderId: instanceId,\n leaseSeconds,\n limit: batchLimit,\n maxBytes: batchMaxBytes,\n };\n const settleFailure = async (error: unknown): Promise<HostExportDrainResult> => {\n const message = exactHostExportErrorMessage(error);\n let failures = 0;\n try {\n failures = await failHostExportBatch(options.db, {\n kind,\n consumerId,\n leaseToken,\n error: message,\n maxFailures,\n });\n } catch (settlementError) {\n options.observability?.warn(\"host export failure settlement was stale\", {\n kind,\n ...hostExportPublicErrorFields(settlementError, \"host_export_failure_settlement_stale\"),\n });\n }\n const blocked = failures >= maxFailures;\n options.observability?.warn(\"host export batch failed\", {\n kind,\n failures,\n blocked,\n ...hostExportPublicErrorFields(error, \"host_export_batch_delivery_failed\"),\n });\n const result: HostExportDrainResult = {\n kind,\n outcome: \"failed\",\n failures,\n blocked,\n };\n recordResult(result, (performance.now() - startedAt) / 1_000);\n return result;\n };\n const deliverClaim = async (\n count: number,\n deliver: () => Promise<void>,\n ): Promise<HostExportDrainResult> => {\n await deliver();\n const throughCursor = await acknowledgeHostExportBatch(options.db, {\n kind,\n consumerId,\n leaseToken,\n });\n try {\n await pruneHostExportOutbox(options.db, {\n kind,\n graceSeconds: pruneGraceSeconds,\n limit: pruneLimit,\n });\n } catch (error) {\n // The sink and checkpoint are already committed. A retention failure\n // must be visible, but must never turn into a false delivery failure or\n // a duplicate settlement attempt for the now-stale lease.\n options.observability?.error(\"host export retention prune failed\", {\n kind,\n ...hostExportPublicErrorFields(error, \"host_export_retention_prune_failed\"),\n });\n }\n const result: HostExportDrainResult = {\n kind,\n outcome: \"delivered\",\n count,\n throughCursor,\n };\n recordResult(result, (performance.now() - startedAt) / 1_000);\n return result;\n };\n\n try {\n if (kind === \"session_event\") {\n const sink = options.eventSink;\n if (!sink) return { kind, outcome: \"not_configured\" };\n const batch = await claimHostExportBatch(options.db, {\n kind,\n ...common,\n });\n if (batch) return await deliverClaim(batch.events.length, () => sink.deliverEvents(batch));\n } else {\n const sink = options.usageSink;\n if (!sink) return { kind, outcome: \"not_configured\" };\n const batch = await claimHostExportBatch(options.db, {\n kind,\n ...common,\n });\n if (batch) return await deliverClaim(batch.events.length, () => sink.deliverUsage(batch));\n }\n } catch (error) {\n return await settleFailure(error);\n }\n const status = await getHostExportConsumerStatus(options.db, {\n kind,\n consumerId,\n });\n if (status?.blockedAt) {\n const result: HostExportDrainResult = {\n kind,\n outcome: \"blocked\",\n failures: status.consecutiveFailures,\n };\n recordResult(result, (performance.now() - startedAt) / 1_000);\n return result;\n }\n const result: HostExportDrainResult = { kind, outcome: \"idle\" };\n recordResult(result, (performance.now() - startedAt) / 1_000);\n return result;\n };\n\n const drainConfiguredOnce = async (): Promise<HostExportDrainResult[]> => {\n const results: HostExportDrainResult[] = [];\n if (options.eventSink) results.push(await drainKind(\"session_event\"));\n if (options.usageSink) results.push(await drainKind(\"usage_event\"));\n return results;\n };\n\n const drainOnce = (): Promise<HostExportDrainResult[]> => {\n const next = drainTail.then(drainConfiguredOnce);\n drainTail = next.then(\n () => undefined,\n () => undefined,\n );\n return next;\n };\n\n const serializeLifecycle = <T>(operation: () => Promise<T>): Promise<T> => {\n const next = lifecycleTail.then(operation);\n lifecycleTail = next.then(\n () => undefined,\n () => undefined,\n );\n return next;\n };\n\n const waitForPoll = async (): Promise<void> => {\n await new Promise<void>((resolve) => {\n wakeWait = resolve;\n waitTimer = setTimeout(resolve, pollIntervalMs);\n waitTimer.unref?.();\n });\n wakeWait = null;\n if (waitTimer) clearTimeout(waitTimer);\n waitTimer = null;\n };\n\n return {\n start: () =>\n serializeLifecycle(async () => {\n if (running) return;\n await options.db.transaction(async (tx) => {\n const scoped = tx as unknown as Database;\n if (options.eventSink) {\n await registerHostExportConsumer(scoped, {\n kind: \"session_event\",\n consumerId: options.eventSink.consumerId,\n });\n }\n if (options.usageSink) {\n await registerHostExportConsumer(scoped, {\n kind: \"usage_event\",\n consumerId: options.usageSink.consumerId,\n });\n }\n });\n if (options.eventSink) retiringKinds.delete(\"session_event\");\n if (options.usageSink) retiringKinds.delete(\"usage_event\");\n running = true;\n loopPromise = (async () => {\n while (true) {\n if (!running) break;\n try {\n for (let batch = 0; batch < maxBatchesPerPoll; batch += 1) {\n if (!running) break;\n const results = await drainOnce();\n if (!results.some((result) => result.outcome === \"delivered\")) break;\n }\n } catch (error) {\n options.observability?.error(\"host export pump iteration failed\", {\n ...hostExportPublicErrorFields(error, \"host_export_pump_iteration_failed\"),\n });\n }\n if (running) await waitForPoll();\n }\n })();\n }),\n stop: () =>\n serializeLifecycle(async () => {\n running = false;\n if (waitTimer) clearTimeout(waitTimer);\n wakeWait?.();\n await loopPromise;\n loopPromise = null;\n }),\n drainOnce,\n disable: async (kind) => {\n const consumerId = configuredConsumer(kind);\n if (!consumerId) throw new Error(`No ${kind} sink is configured`);\n await disableHostExportConsumer(options.db, { kind, consumerId });\n },\n retire: (kind) =>\n serializeLifecycle(async () => {\n if (running) throw new Error(\"Stop the host export pump before retiring a consumer\");\n const consumerId = configuredConsumer(kind);\n if (!consumerId) throw new Error(`No ${kind} sink is configured`);\n retiringKinds.add(kind);\n try {\n await drainTail;\n await retireHostExportConsumer(options.db, { kind, consumerId });\n } catch (error) {\n retiringKinds.delete(kind);\n throw error;\n }\n }),\n status: async (kind) => {\n const consumerId = configuredConsumer(kind);\n if (!consumerId) return null;\n return await getHostExportConsumerStatus(options.db, {\n kind,\n consumerId,\n });\n },\n };\n}\n\nfunction boundedInteger(\n value: number | undefined,\n fallback: number,\n minimum: number,\n maximum: number,\n): number {\n const candidate = value ?? fallback;\n if (!Number.isInteger(candidate) || candidate < minimum || candidate > maximum) {\n throw new Error(`Expected an integer between ${minimum} and ${maximum}`);\n }\n return candidate;\n}\n\nfunction validateInstanceId(value: string): string {\n if (value.length < 1 || value.length > 128) {\n throw new Error(\"Host export instanceId must contain 1 to 128 characters\");\n }\n return value;\n}\n\nfunction exactHostExportErrorMessage(error: unknown): string {\n return error instanceof Error ? error.message : String(error);\n}\n\ntype HostExportPublicFailureCode =\n | \"host_export_failure_settlement_stale\"\n | \"host_export_batch_delivery_failed\"\n | \"host_export_retention_prune_failed\"\n | \"host_export_pump_iteration_failed\";\n\nfunction hostExportPublicErrorFields(\n _error: unknown,\n errorCode: HostExportPublicFailureCode,\n): {\n errorClass: \"HostExportOperationError\";\n errorCode: HostExportPublicFailureCode;\n origin: \"host-export\";\n} {\n return {\n errorClass: \"HostExportOperationError\",\n errorCode,\n origin: \"host-export\",\n };\n}\n"],"mappings":"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","names":["result"]}
@@ -1,14 +1,36 @@
1
1
  import type { Settings } from "@opengeni/config";
2
- import type { WorkerOptions } from "@temporalio/worker";
2
+ import type { Observability } from "@opengeni/observability";
3
+ import type { ActivitySlotInfo, CustomSlotSupplier, SlotMarkUsedContext, SlotPermit, SlotReleaseContext, SlotReserveContext, WorkerOptions, WorkerTuner } from "@temporalio/worker";
4
+ /**
5
+ * Default fixed/HPA turn-worker admission contract. The configured fixed-mode
6
+ * ceiling may be lower, but every live Temporal permit reserves the complete
7
+ * hard budget until the runAgentTurn activity promise physically completes.
8
+ */
9
+ export declare const TURN_WORKER_MAX_CONCURRENT_TURNS = 16;
10
+ export declare const TURN_WORKER_HARD_MEMORY_BYTES_PER_TURN: number;
11
+ export declare const TURN_WORKER_NATIVE_HEADROOM_BYTES: number;
3
12
  export type TurnWorkerConcurrencySettings = Pick<Settings, "turnWorkerConcurrencyMode" | "turnWorkerMaxConcurrentTurns" | "turnWorkerTargetCpuUsage" | "turnWorkerTargetMemoryUsage">;
4
13
  export type TurnWorkerConcurrencyOptions = Pick<WorkerOptions, "maxConcurrentActivityTaskExecutions" | "tuner">;
5
14
  /**
6
- * Ordinary multi-worker deployments keep a fixed per-process ceiling so HPA or
7
- * an operator owns horizontal capacity. The single-machine profile selects the
8
- * resource tuner instead: Temporal admits activity slots while whole-system CPU
9
- * and memory remain below the configured targets, then stops polling more work.
15
+ * Fixed profiles keep a per-process ceiling. Resource-aware profiles retain a
16
+ * hard per-process maximum while Temporal meters new activity admission against
17
+ * cgroup/host CPU and memory. The ramp lets usage become visible before a burst
18
+ * can reserve the entire ceiling.
10
19
  */
11
20
  export declare function turnWorkerConcurrencyOptions(settings: TurnWorkerConcurrencySettings): TurnWorkerConcurrencyOptions;
21
+ export type TurnWorkerConcurrencyPlan = {
22
+ options: TurnWorkerConcurrencyOptions;
23
+ admission: MemoryAwareTurnSlotSupplier | null;
24
+ };
25
+ /**
26
+ * Build the runtime concurrency policy for a turn worker.
27
+ *
28
+ * Fixed/HPA deployments use the hard-reservation supplier below. The explicit
29
+ * non-HA single-machine profile keeps Temporal's native CPU/memory resource
30
+ * tuner because it controls whole-machine load rather than a pod cgroup; that
31
+ * profile documents that its configured maximum is not a per-turn reservation.
32
+ */
33
+ export declare function createTurnWorkerConcurrencyPlan(settings: TurnWorkerConcurrencySettings, options?: Omit<TurnAdmissionOptions, "maximumTurns">): TurnWorkerConcurrencyPlan;
12
34
  export declare function turnWorkerConcurrencyLogFields(settings: TurnWorkerConcurrencySettings): {
13
35
  concurrencyMode: "fixed" | "resource-based";
14
36
  maxConcurrentTurns: number;
@@ -17,3 +39,84 @@ export declare function turnWorkerConcurrencyLogFields(settings: TurnWorkerConcu
17
39
  };
18
40
  export declare const CONTROL_WORKER_MAX_CONCURRENT_ACTIVITIES = 32;
19
41
  export declare const CONTROL_WORKER_MAX_CONCURRENT_WORKFLOW_TASKS = 40;
42
+ export type CgroupMemorySnapshot = {
43
+ currentBytes: number;
44
+ limitBytes: number | null;
45
+ source: "cgroup-v1" | "cgroup-v2" | "process";
46
+ };
47
+ export type TurnAdmissionSnapshot = {
48
+ baselineBytes: number;
49
+ currentBytes: number;
50
+ limitBytes: number | null;
51
+ hardBytesPerTurn: number;
52
+ nativeHeadroomBytes: number;
53
+ maximumTurns: number;
54
+ memoryBoundCapacity: number;
55
+ reservedSlots: number;
56
+ usedSlots: number;
57
+ availableSlots: number;
58
+ };
59
+ export type TurnAdmissionOptions = {
60
+ maximumTurns?: number;
61
+ hardBytesPerTurn?: number;
62
+ nativeHeadroomBytes?: number;
63
+ memorySnapshot?: () => CgroupMemorySnapshot;
64
+ retryDelayMs?: number;
65
+ observability?: Observability;
66
+ };
67
+ /**
68
+ * Temporal custom activity-slot supplier for turn workers.
69
+ *
70
+ * A permit is required before Temporal polls a task. Reservation is allowed
71
+ * only when both independent safety checks pass:
72
+ *
73
+ * baseline + reserved-after × hard-turn-budget + native headroom <= limit
74
+ * current + reserved-after × hard-turn-budget + native headroom <= limit
75
+ *
76
+ * The first check enforces the release contract even when current RSS happens
77
+ * to be low. The second accounts for native/retained memory observed after
78
+ * startup and keeps the complete hard budget reserved for every live permit.
79
+ * A used permit is not evidence that its allocation is already visible in the
80
+ * cgroup, and unrelated native growth cannot safely be attributed to a turn.
81
+ * Kubernetes OOM is never an admission mechanism.
82
+ */
83
+ export declare class MemoryAwareTurnSlotSupplier implements CustomSlotSupplier<ActivitySlotInfo> {
84
+ readonly type: "custom";
85
+ private readonly owner;
86
+ private readonly permits;
87
+ private baselineBytes;
88
+ private readonly maximumTurns;
89
+ private readonly hardBytesPerTurn;
90
+ private readonly nativeHeadroomBytes;
91
+ private readonly memorySnapshot;
92
+ private readonly retryDelayMs;
93
+ private readonly observability;
94
+ constructor(options?: TurnAdmissionOptions);
95
+ reserveSlot(_ctx: SlotReserveContext, abortSignal: AbortSignal): Promise<SlotPermit>;
96
+ tryReserveSlot(_ctx: SlotReserveContext): SlotPermit | null;
97
+ markSlotUsed(ctx: SlotMarkUsedContext<ActivitySlotInfo>): void;
98
+ releaseSlot(ctx: SlotReleaseContext<ActivitySlotInfo>): void;
99
+ snapshot(memory?: CgroupMemorySnapshot): TurnAdmissionSnapshot;
100
+ /**
101
+ * Finalize the admission baseline after Temporal/native construction.
102
+ * Worker.create can retain memory after the constructor's provisional
103
+ * sample. That initialization delta must remain in the baseline for every
104
+ * later projection rather than competing with turn reservations.
105
+ */
106
+ finalizeStartupBaseline(): void;
107
+ private reserveIfSafe;
108
+ private memoryAllowsAnother;
109
+ private availableSlots;
110
+ private memoryBoundCapacity;
111
+ private usedSlots;
112
+ private ownedPermit;
113
+ private refreshMetrics;
114
+ }
115
+ export declare function createTurnWorkerTuner(options?: TurnAdmissionOptions): {
116
+ tuner: WorkerTuner;
117
+ admission: MemoryAwareTurnSlotSupplier;
118
+ };
119
+ export declare function readCgroupMemorySnapshot(): CgroupMemorySnapshot;
120
+ export declare function parseCgroupLimitValue(value: string): number | null;
121
+ export declare function parseCgroupCurrentValue(value: string): number;
122
+ export declare const CONTROL_WORKER_MAX_CACHED_WORKFLOWS = 64;
@@ -0,0 +1,49 @@
1
+ import { type EditableArtifactHintBrokerPort } from "@opengeni/core";
2
+ import { type NatsConnection } from "@opengeni/events";
3
+ export type EditableArtifactHintNatsAuth = Readonly<{
4
+ kind: "user-password";
5
+ user: string;
6
+ pass: string;
7
+ }> | Readonly<{
8
+ kind: "token";
9
+ token: string;
10
+ }> | Readonly<{
11
+ kind: "anonymous";
12
+ }>;
13
+ export type EditableArtifactHintNatsBrokerOptions = Readonly<{
14
+ maxHintBytes?: number;
15
+ }>;
16
+ export type EditableArtifactHintNatsConnection = Pick<NatsConnection, "publish" | "flush" | "drain" | "close" | "closed" | "isClosed" | "isDraining">;
17
+ /**
18
+ * Core-NATS adapter for the durable outbox. A publish resolves only after a
19
+ * server round-trip flush ACK. Reconnect buffering may create duplicates after
20
+ * a timeout; hints are intentionally idempotent wakeups for durable gap-fill.
21
+ */
22
+ export declare class ConfirmedNatsEditableArtifactHintBroker implements EditableArtifactHintBrokerPort {
23
+ private readonly connection;
24
+ private readonly maxHintBytes;
25
+ constructor(connection: EditableArtifactHintNatsConnection, options?: EditableArtifactHintNatsBrokerOptions);
26
+ publish(input: Readonly<{
27
+ subject: string;
28
+ payload: Uint8Array;
29
+ signal: AbortSignal;
30
+ }>): Promise<void>;
31
+ /**
32
+ * A readiness probe must prove the server is reachable, not merely that the
33
+ * client object has not observed closure yet. `flush()` is a bounded NATS
34
+ * round trip and has the same acknowledgement semantics as publication.
35
+ */
36
+ check(signal?: AbortSignal): Promise<void>;
37
+ close(drainTimeoutMs?: number): Promise<void>;
38
+ }
39
+ export declare class EditableArtifactNatsHintPublishError extends Error {
40
+ readonly code: "broker_unavailable" | "broker_backpressure";
41
+ constructor(code: "broker_unavailable" | "broker_backpressure", message: string, options?: ErrorOptions);
42
+ }
43
+ /** Opens one resilient dispatcher identity; callers own `broker.close()`. */
44
+ export declare function connectEditableArtifactHintBroker(input: Readonly<{
45
+ natsUrl: string;
46
+ auth: EditableArtifactHintNatsAuth;
47
+ name?: string;
48
+ maxHintBytes?: number;
49
+ }>): Promise<ConfirmedNatsEditableArtifactHintBroker>;
@@ -0,0 +1,49 @@
1
+ import type { VerifiedEditableArtifactProcessLauncher } from "./editable-artifact-materializer-subprocess.js";
2
+ export type LinuxEditableArtifactLauncherOptions = Readonly<{
3
+ materializerExecutable: string;
4
+ bubblewrapExecutable: string;
5
+ prlimitExecutable: string;
6
+ runtimeRoot: string;
7
+ memoryLimitBytes: number;
8
+ cpuTimeLimitMs: number;
9
+ fileDescriptorLimit: number;
10
+ processLimit: number;
11
+ fileSizeLimitBytes: number;
12
+ probeExecutable?: string;
13
+ }>;
14
+ export type DevelopmentEditableArtifactLauncherOptions = Readonly<{
15
+ materializerExecutable: string;
16
+ explicitlyEnabled: boolean;
17
+ nodeEnvironment: string | undefined;
18
+ }>;
19
+ /**
20
+ * Current-host local development only. This deliberately reports that no OS
21
+ * sandbox, network namespace, or process resource limit is enforced. The
22
+ * caller must surface that degraded capability and can never select this path
23
+ * in production.
24
+ */
25
+ export declare function createDevelopmentEditableArtifactProcessLauncher(options: DevelopmentEditableArtifactLauncherOptions): Promise<VerifiedEditableArtifactProcessLauncher>;
26
+ /**
27
+ * Concrete production launcher for Linux. Isolation facts are established by
28
+ * a parent-run behavioral probe of the actual bwrap+prlimit command, never by
29
+ * the untrusted codec child. macOS/Windows require their own native launcher
30
+ * implementation and therefore fail closed in production today.
31
+ */
32
+ export declare function createLinuxEditableArtifactProcessLauncher(options: LinuxEditableArtifactLauncherOptions): Promise<VerifiedEditableArtifactProcessLauncher>;
33
+ export declare function linuxEditableArtifactSandboxArguments(input: Readonly<{
34
+ executable: string;
35
+ args: readonly string[];
36
+ runtimeRoot: string;
37
+ scratchLimitBytes: number;
38
+ }>): readonly string[];
39
+ export declare function linuxEditableArtifactPrlimitArguments(input: Readonly<{
40
+ memoryLimitBytes: number;
41
+ cpuSeconds: number;
42
+ fileDescriptorLimit: number;
43
+ processLimit: number;
44
+ fileSizeLimitBytes: number;
45
+ }>): readonly string[];
46
+ export declare function linuxEditableArtifactSandboxRootEntries(input: Readonly<{
47
+ executable: string;
48
+ runtimeRoot: string;
49
+ }>): readonly string[];
@@ -0,0 +1,108 @@
1
+ import { type Settings } from "@opengeni/config";
2
+ import { type Database } from "@opengeni/db";
3
+ import { type Observability } from "@opengeni/observability";
4
+ import { type ObjectStorage } from "@opengeni/storage";
5
+ import { EditableArtifactMaterializer, type EditableArtifactMaterializerPassSummary } from "./editable-artifact-materializer.js";
6
+ export type EditableArtifactRuntimeAuthority = Readonly<{
7
+ mode: "production";
8
+ environmentVariable: "OPENGENI_ARTIFACT_RUNTIME_MANIFEST";
9
+ manifestPath: string;
10
+ }> | Readonly<{
11
+ mode: "development-current-host";
12
+ environmentVariable: "OPENGENI_ARTIFACT_DEVELOPMENT_RUNTIME_MANIFEST";
13
+ manifestPath: string;
14
+ }>;
15
+ export type EditableArtifactMaterializerServiceState = "starting" | "ready" | "draining" | "stopped" | "failed";
16
+ export type EditableArtifactMaterializerService = Readonly<{
17
+ state(): EditableArtifactMaterializerServiceState;
18
+ run(): Promise<void>;
19
+ drain(reason?: string): boolean;
20
+ close(): Promise<void>;
21
+ dispatchOnce(signal?: AbortSignal): Promise<EditableArtifactMaterializerPassSummary>;
22
+ fetch(request: Request): Promise<Response>;
23
+ }>;
24
+ export type CreateEditableArtifactMaterializerServiceInput = Readonly<{
25
+ materializer: EditableArtifactMaterializer;
26
+ db: Database;
27
+ closeDatabase: () => Promise<void>;
28
+ observability: Observability;
29
+ serviceName: string;
30
+ environment: string;
31
+ deploymentRevision?: string;
32
+ readinessTimeoutMs?: number;
33
+ runtimeCapability?: Readonly<{
34
+ mode: EditableArtifactRuntimeAuthority["mode"];
35
+ sandboxEnforced: boolean;
36
+ }>;
37
+ }>;
38
+ export type ProductionEditableArtifactMaterializerServiceOptions = Readonly<{
39
+ settings: Settings;
40
+ /** Dedicated DSN; never defaults to settings.databaseUrl. */
41
+ databaseUrl: string;
42
+ declaredDatabaseRole: string;
43
+ executable: string;
44
+ bubblewrapExecutable: string | null;
45
+ prlimitExecutable: string | null;
46
+ runtimeAuthority: EditableArtifactRuntimeAuthority;
47
+ /** Explicit exception selected only by the validated local-dev sidecar config. */
48
+ allowUnsandboxedLocalDevelopment?: boolean;
49
+ skillFacadeEntrypoint: string;
50
+ owner: string;
51
+ objectStorage?: ObjectStorage;
52
+ batchSize?: number;
53
+ concurrency?: number;
54
+ leaseDurationMs?: number;
55
+ leaseRenewIntervalMs?: number;
56
+ pollIntervalMs?: number;
57
+ maxAttempts?: number;
58
+ memoryLimitBytes: number;
59
+ cpuTimeLimitMs: number;
60
+ fileDescriptorLimit: number;
61
+ processLimit: number;
62
+ fileSizeLimitBytes: number;
63
+ wallTimeoutMs: number;
64
+ nodeEnvironment?: string;
65
+ maxSourceBytes?: number;
66
+ maxOutputBytes?: number;
67
+ }>;
68
+ /**
69
+ * Compose the distinct production sidecar. It creates its own connection pool
70
+ * from the dedicated DSN and never reuses a control/turn worker handle.
71
+ */
72
+ export declare function createProductionEditableArtifactMaterializerService(options: ProductionEditableArtifactMaterializerServiceOptions): Promise<EditableArtifactMaterializerService>;
73
+ export declare function createEditableArtifactMaterializerService(input: CreateEditableArtifactMaterializerServiceInput): EditableArtifactMaterializerService;
74
+ export declare function assertDedicatedMaterializerDatabaseRole(db: Database): Promise<void>;
75
+ export type EditableArtifactMaterializerSidecarEnvironment = Readonly<{
76
+ databaseUrl: string;
77
+ declaredDatabaseRole: string;
78
+ executable: string;
79
+ bubblewrapExecutable: string | null;
80
+ prlimitExecutable: string | null;
81
+ runtimeAuthority: EditableArtifactRuntimeAuthority;
82
+ skillFacadeEntrypoint: string;
83
+ owner: string;
84
+ httpHostname: string;
85
+ httpPort: number;
86
+ batchSize: number;
87
+ concurrency: number;
88
+ leaseDurationMs: number;
89
+ leaseRenewIntervalMs: number;
90
+ pollIntervalMs: number;
91
+ maxAttempts: number;
92
+ memoryLimitBytes: number;
93
+ cpuTimeLimitMs: number;
94
+ fileDescriptorLimit: number;
95
+ processLimit: number;
96
+ fileSizeLimitBytes: number;
97
+ wallTimeoutMs: number;
98
+ maxSourceBytes: number;
99
+ maxOutputBytes: number;
100
+ allowUnsandboxedLocalDevelopment: boolean;
101
+ nodeEnvironment?: string;
102
+ }>;
103
+ export declare function readEditableArtifactMaterializerSidecarEnvironment(environment?: NodeJS.ProcessEnv): EditableArtifactMaterializerSidecarEnvironment | null;
104
+ export declare function createMaterializerSidecarFromEnvironment(environment?: NodeJS.ProcessEnv): Promise<Readonly<{
105
+ service: EditableArtifactMaterializerService;
106
+ httpHostname: string;
107
+ httpPort: number;
108
+ }> | null>;
@@ -0,0 +1,12 @@
1
+ import { type BoundedImmutableObjectWritePort, type BoundedObjectReadPort, type ObjectStorage } from "@opengeni/storage";
2
+ import { type EditableArtifactMaterializationSemanticVerifierPort, type EditableArtifactMaterializationVerifierPort } from "./editable-artifact-materializer.js";
3
+ /** Provider-versioned, immutable range reader. No whole-object fallback. */
4
+ export declare function createEditableArtifactObjectStorageReader(storage: ObjectStorage): BoundedObjectReadPort;
5
+ /** Conditional-create digest writer with independent version-pinned readback. */
6
+ export declare function createEditableArtifactObjectStorageWriter(storage: ObjectStorage): BoundedImmutableObjectWritePort;
7
+ /**
8
+ * Independent immutable readback + structural parser. When the native source
9
+ * projection supplies a semantic digest, a second isolated codec process must
10
+ * re-import the published Office bytes and prove that digest before success.
11
+ */
12
+ export declare function createEditableArtifactObjectStorageVerifier(storage: ObjectStorage, semanticVerifier: EditableArtifactMaterializationSemanticVerifierPort): EditableArtifactMaterializationVerifierPort;
@@ -0,0 +1,50 @@
1
+ import type { ChildProcessWithoutNullStreams } from "node:child_process";
2
+ import { type NativeEditableArtifactMaterializerPort } from "./editable-artifact-materializer.js";
3
+ export type NativeEditableArtifactSubprocessOptions = Readonly<{
4
+ /** Absolute path to the exact codec executable. Isolation belongs to launcher. */
5
+ executable: string;
6
+ launcher: VerifiedEditableArtifactProcessLauncher;
7
+ childEnvironment?: Readonly<Record<string, string>>;
8
+ /** Explicitly permits the current-host local-dev launcher; never set in production. */
9
+ allowUnsandboxedDevelopment?: boolean;
10
+ wallTimeoutMs: number;
11
+ maxSourceBytes: number;
12
+ maxOutputBytes: number;
13
+ probeTimeoutMs?: number;
14
+ }>;
15
+ export type VerifiedEditableArtifactProcessLauncher = Readonly<{
16
+ identity: Readonly<{
17
+ platform: string;
18
+ isolation: "subprocess";
19
+ network: "denied" | "host";
20
+ officeAutomation: false;
21
+ sandboxEnforced: boolean;
22
+ memoryLimitBytes: number;
23
+ cpuTimeLimitMs: number;
24
+ fileDescriptorLimit: number;
25
+ processLimit: number;
26
+ fileSizeLimitBytes: number;
27
+ }>;
28
+ spawn(input: {
29
+ executable: string;
30
+ args: readonly string[];
31
+ environment: Readonly<Record<string, string>>;
32
+ }): ChildProcessWithoutNullStreams;
33
+ }>;
34
+ export type NativeEditableArtifactSubprocessPort = NativeEditableArtifactMaterializerPort & Readonly<{
35
+ verifyMaterialization(input: {
36
+ format: string;
37
+ codecId: string;
38
+ codecVersion: string;
39
+ expectedSemanticHash: string;
40
+ byteSize: number;
41
+ chunks: AsyncIterable<Uint8Array>;
42
+ signal: AbortSignal;
43
+ }): Promise<void>;
44
+ }>;
45
+ /**
46
+ * Probe exact codec/kernel capabilities and combine them with independently
47
+ * verified parent-launcher isolation. The child is never trusted to attest its
48
+ * own network namespace, resource limits, or platform sandbox.
49
+ */
50
+ export declare function createNativeEditableArtifactSubprocessPort(options: NativeEditableArtifactSubprocessOptions): Promise<NativeEditableArtifactSubprocessPort>;