@opengeni/worker-bundle 0.2.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.
@@ -0,0 +1,232 @@
1
+ // apps/worker/src/sandbox-routing.ts — wire the agent-loop-free routing proxy
2
+ // (`@opengeni/runtime` RoutingSandboxSession + makeActiveBackendResolver) to the
3
+ // real DB pointer + the live NATS control plane for the WORKER TURN path (M7).
4
+ //
5
+ // The turn resumes its group box by id (resumeBoxForTurn) and injects it
6
+ // NON-OWNED into the run. With hot-swap, the injected `session` must be the
7
+ // STABLE routing proxy (dossier §10.3): the SDK binds to it ONCE and calls its
8
+ // methods per tool call; the proxy re-reads `(active_sandbox_id, active_epoch)`
9
+ // per op and dispatches to the currently-active backend (the group Modal box by
10
+ // default, or a swap target — a sibling Modal box or a selfhosted machine).
11
+ //
12
+ // The glue here is the DB-coupled half the leaf cannot own (the leaf must stay
13
+ // agent-loop-free + db-free): readActiveSandbox (the pointer), getSandbox (the
14
+ // target lookup), and the selfhosted ControlRpc built over the events bus's NATS
15
+ // request/reply connection.
16
+
17
+ import type { Settings } from "@opengeni/config";
18
+ import { getSandbox, readActiveSandbox, type Database } from "@opengeni/db";
19
+ import type { EventBus } from "@opengeni/events";
20
+ import {
21
+ buildSelfhostedBackendSession,
22
+ makeActiveBackendResolver,
23
+ NatsControlRpc,
24
+ RoutingSandboxSession,
25
+ type ControlRpc,
26
+ type EstablishedSandboxSession,
27
+ type NatsRequestConnection,
28
+ type RoutableBackendSession,
29
+ type RoutableSandbox,
30
+ type SelfhostedRelayConfig,
31
+ } from "@opengeni/runtime";
32
+
33
+ export type RoutingWiringServices = {
34
+ db: Database;
35
+ settings: Settings;
36
+ /** The events bus, for the selfhosted control-plane request/reply connection.
37
+ * Optional: when absent (or NATS unconfigured) a selfhosted swap target
38
+ * surfaces agent_offline on its first op rather than failing to build. */
39
+ bus?: EventBus;
40
+ };
41
+
42
+ export type RoutingWiringIds = {
43
+ workspaceId: string;
44
+ sessionId: string;
45
+ /**
46
+ * The run's declared sandbox environment — the SAME object the turn passes to
47
+ * `runtime.buildAgent`'s `sandboxEnvironment` and to `resumeBoxForTurn` (so the
48
+ * group box's manifest carries it too). Threaded into a selfhosted swap target's
49
+ * manifest so its `environment` EQUALS the turn's, making the SDK's per-turn
50
+ * provided-session manifest-env delta empty (validateNoEnvironmentDelta).
51
+ * WITHOUT this a pin-to-vm turn throws "Live sandbox sessions cannot change
52
+ * manifest environment variables." Optional → the resolver defaults to `{}`.
53
+ */
54
+ environment?: Record<string, string>;
55
+ /**
56
+ * Stage D machine-primary: PIN the already-established turn SelfhostedSession
57
+ * (the `established` arg's session) for THIS machine pointer `(sandboxId, epoch)`
58
+ * so the per-op resolver returns that SAME instance instead of building a fresh
59
+ * one — the turn-start manifest write + per-op reads then hit ONE
60
+ * SelfhostedSession/manifest. Set ONLY by the machine-primary establish branch
61
+ * (where `established.session` is the SelfhostedSession bound to this pointer);
62
+ * the group-box/swap path omits it (the default is the modal group box, and a
63
+ * swap target is built fresh).
64
+ */
65
+ pinnedSelfhosted?: { sandboxId: string; epoch: number };
66
+ };
67
+
68
+ /** Map the deployment relay URL to the leaf's `SelfhostedRelayConfig` shape
69
+ * (host/port/tls). M8 wires the real relay; until then a configured/placeholder
70
+ * host yields a well-formed stream-URL shape behind `resolveExposedPort`. */
71
+ export function relayConfigFromSettings(settings: Settings): SelfhostedRelayConfig {
72
+ const raw = settings.selfhostedRelayUrl?.trim();
73
+ if (!raw) {
74
+ return { host: "relay.opengeni.local", port: 443, tls: true };
75
+ }
76
+ try {
77
+ const url = new URL(raw.includes("://") ? raw : `wss://${raw}`);
78
+ const tls = url.protocol === "wss:" || url.protocol === "https:";
79
+ const port = url.port ? Number(url.port) : tls ? 443 : 80;
80
+ return { host: url.hostname, port, tls };
81
+ } catch {
82
+ return { host: raw, port: 443, tls: true };
83
+ }
84
+ }
85
+
86
+ /** Build the selfhosted `ControlRpc` over the events bus's request/reply
87
+ * connection. A null bus / unconfigured NATS yields a NatsControlRpc whose
88
+ * connection factory returns null → agent_offline on every op (never a throw). */
89
+ function controlRpcFactory(bus: EventBus | undefined): () => ControlRpc {
90
+ return () =>
91
+ new NatsControlRpc(async (): Promise<NatsRequestConnection | null> => {
92
+ if (!bus) {
93
+ return null;
94
+ }
95
+ return bus.getRequestConnection();
96
+ });
97
+ }
98
+
99
+ /**
100
+ * Wrap an established group-box session in a `RoutingSandboxSession` so a mid-turn
101
+ * swap routes the NEXT tool call to the new active sandbox. Returns the SAME
102
+ * established handle with its `session` replaced by the stable proxy; the
103
+ * client/sessionState/instanceId/backendId are preserved (the lease still owns
104
+ * the group box's lifecycle — the proxy is a routing veneer, not an owner).
105
+ *
106
+ * The DEFAULT pointer (active_sandbox_id == null) routes to the established group
107
+ * session unchanged (backward-compat). A swap to a selfhosted machine routes to a
108
+ * SelfhostedSession bound to the target's enrollment agentId, fenced under the
109
+ * swap's active_epoch.
110
+ */
111
+ export function wrapTurnBoxWithRouting(
112
+ services: RoutingWiringServices,
113
+ ids: RoutingWiringIds,
114
+ established: EstablishedSandboxSession,
115
+ ): EstablishedSandboxSession {
116
+ const { db, settings, bus } = services;
117
+ const resolver = makeActiveBackendResolver({
118
+ workspaceId: ids.workspaceId,
119
+ defaultBackend: established.session as RoutableBackendSession,
120
+ defaultKind: established.backendId,
121
+ getSandbox: async (sandboxId): Promise<RoutableSandbox | null> => {
122
+ const sandbox = await getSandbox(db, ids.workspaceId, sandboxId);
123
+ return sandbox
124
+ ? { id: sandbox.id, kind: sandbox.kind, name: sandbox.name, enrollmentId: sandbox.enrollmentId }
125
+ : null;
126
+ },
127
+ controlRpcFactory: controlRpcFactory(bus),
128
+ relay: relayConfigFromSettings(settings),
129
+ // The turn's declared environment → a selfhosted swap target's manifest, so the
130
+ // SDK's per-turn manifest-env delta is empty (no "cannot change manifest
131
+ // environment variables" throw when the turn pins to a vm). Mirrors the group
132
+ // box, which is created WITH this same environment (resumeBoxForTurn).
133
+ ...(ids.environment !== undefined ? { environment: ids.environment } : {}),
134
+ // Stage D machine-primary: pin THIS established SelfhostedSession for the machine
135
+ // pointer so the resolver returns the SAME instance (no two-instance manifest
136
+ // divergence). `established.session` is the SelfhostedSession the establish branch
137
+ // bound to (sandboxId, epoch).
138
+ ...(ids.pinnedSelfhosted
139
+ ? {
140
+ pinnedSelfhosted: {
141
+ sandboxId: ids.pinnedSelfhosted.sandboxId,
142
+ epoch: ids.pinnedSelfhosted.epoch,
143
+ session: established.session as RoutableBackendSession,
144
+ },
145
+ }
146
+ : {}),
147
+ // A modal swap target in the turn path would need its own lease resume-by-id;
148
+ // that is a future cross-group-box concern. Until then a modal swap target is
149
+ // unresolvable (the swap tool validates liveness, so this only triggers if a
150
+ // session points at a sibling modal box the turn cannot resume here) and the
151
+ // op surfaces unresolvable — never a silent wrong-box landing.
152
+ });
153
+
154
+ const proxy = new RoutingSandboxSession({
155
+ // Seed the DEFAULT backend (the established group box) at construction so
156
+ // `session.state` is the real backend's state object BEFORE the first op. The
157
+ // SDK reads `session.state.manifest` at turn START (and writes it back); an
158
+ // empty `{}` there crashes serializeManifestEnvironment /
159
+ // validateProvidedSessionManifestUpdate. This is byte-identical to what the
160
+ // resolver returns for the default pointer (`activeSandboxId === null`).
161
+ defaultResolved: {
162
+ session: established.session as RoutableBackendSession,
163
+ sandboxId: null,
164
+ kind: established.backendId,
165
+ },
166
+ readPointer: async () => {
167
+ const pointer = await readActiveSandbox(db, ids.workspaceId, ids.sessionId);
168
+ return pointer ?? { activeSandboxId: null, activeEpoch: 0 };
169
+ },
170
+ resolveActiveBackend: resolver,
171
+ });
172
+
173
+ return { ...established, session: proxy };
174
+ }
175
+
176
+ /**
177
+ * Stage D machine-primary establish: bind the live SelfhostedSession for a turn
178
+ * whose ACTIVE sandbox is a connected machine — WITHOUT establishing or leasing a
179
+ * phantom Modal home box. Reuses the SAME relay + ControlRpc wiring `wrapTurnBoxWithRouting`
180
+ * builds (so the turn session and a later swap target dial the machine identically),
181
+ * and the SAME `buildSelfhostedBackendSession` factory the routing resolver uses
182
+ * (one build shape). Returns an `EstablishedSandboxSession` whose:
183
+ * - `client` is the SelfhostedSandboxClient (the OWNED-sandbox client the turn
184
+ * injects; its `serializeSessionState` round-trips `{agentId}`);
185
+ * - `session` is the live SelfhostedSession (the routing default + pin instance);
186
+ * - `backendId` is "selfhosted" (drives recording's desktopCapableBackend gate +
187
+ * the warm-rate keying) and `instanceId` is the enrollment/agent id.
188
+ * No NATS round-trip happens here — `resume()` just re-addresses the subject — so a
189
+ * headless/offline machine binds fine; its ops surface agent_offline lazily.
190
+ */
191
+ export async function establishSelfhostedTurnSession(
192
+ services: RoutingWiringServices,
193
+ args: {
194
+ workspaceId: string;
195
+ /** The target machine's enrollment id == the agent subject id. */
196
+ agentId: string;
197
+ /** The active pointer's epoch — the control-op fence echoed to the agent. */
198
+ epoch: number;
199
+ /** The run's declared sandbox environment (the SAME object fed to buildAgent +
200
+ * the manifest), threaded so the SDK's per-turn provided-session env delta is
201
+ * empty. */
202
+ environment: Record<string, string>;
203
+ /** The session working directory (per-session pointer). Null ⇒ workspace_root. */
204
+ workingDir: string | null;
205
+ },
206
+ ): Promise<EstablishedSandboxSession> {
207
+ const { settings, bus } = services;
208
+ const { client, session } = await buildSelfhostedBackendSession({
209
+ workspaceId: args.workspaceId,
210
+ agentId: args.agentId,
211
+ relay: relayConfigFromSettings(settings),
212
+ controlRpcFactory: controlRpcFactory(bus),
213
+ epoch: args.epoch,
214
+ environment: args.environment,
215
+ workingDir: args.workingDir,
216
+ });
217
+ return {
218
+ client,
219
+ session,
220
+ sessionState: { agentId: args.agentId },
221
+ instanceId: args.agentId,
222
+ backendId: "selfhosted",
223
+ };
224
+ }
225
+
226
+ /** Whether the routing proxy should wrap the turn box: the hot-swap feature is
227
+ * gated by the selfhosted flag (the active pointer + swap tools are only
228
+ * meaningful when selfhosted is enabled). With the flag off the established
229
+ * group box is injected unchanged — byte-for-byte today. */
230
+ export function routingEnabled(settings: Settings): boolean {
231
+ return settings.sandboxSelfhostedEnabled === true;
232
+ }
@@ -0,0 +1,23 @@
1
+ import { proxyActivities } from "@temporalio/workflow";
2
+ import type * as activities from "../activities";
3
+
4
+ export const activity = proxyActivities<typeof activities>({
5
+ // Agent segments legitimately run for days (goal-bearing infrastructure
6
+ // sessions). Dead workers are detected by the heartbeat, not this timeout,
7
+ // so it is deliberately generous rather than a pacing bound.
8
+ startToCloseTimeout: "30 days",
9
+ heartbeatTimeout: "30 seconds",
10
+ retry: { maximumAttempts: 1 },
11
+ });
12
+
13
+ export const documentActivity = proxyActivities<Pick<typeof activities, "indexDocument">>({
14
+ startToCloseTimeout: "30 minutes",
15
+ retry: { maximumAttempts: 1 },
16
+ });
17
+
18
+ export function workflowFailureMessage(error: unknown): string {
19
+ if (error instanceof Error) {
20
+ return error.message;
21
+ }
22
+ return String(error);
23
+ }
@@ -0,0 +1,11 @@
1
+ import { documentActivity } from "./activities";
2
+
3
+ export type DocumentIndexWorkflowInput = {
4
+ accountId: string;
5
+ workspaceId: string;
6
+ documentId: string;
7
+ };
8
+
9
+ export async function documentIndexWorkflow(input: DocumentIndexWorkflowInput) {
10
+ return await documentActivity.indexDocument(input);
11
+ }
@@ -0,0 +1,28 @@
1
+ // apps/worker/src/workflows/sandbox-reaper.ts — the ONE global reaper workflow.
2
+ //
3
+ // This is the action the single global reaper Temporal Schedule starts
4
+ // (registered in apps/worker/src/index.ts, gated on sandboxOwnershipEnabled). It
5
+ // runs on the global task queue — the SAME queue the worker pool listens on,
6
+ // because the worker carries the runtime needed to resume-by-id and terminate a
7
+ // provider box. There is NO per-session worker, NO per-session/per-group queue.
8
+ //
9
+ // The workflow is intentionally trivial: it delegates the whole sweep to the
10
+ // stateless `reapSandboxLeases` activity (the sweep is DB + provider IO that
11
+ // must run in an activity, not in workflow-deterministic code). The Schedule's
12
+ // SKIP overlap policy means a slow sweep never overlaps itself; the activity is
13
+ // idempotent regardless.
14
+
15
+ import { proxyActivities } from "@temporalio/workflow";
16
+ import type * as activities from "../activities";
17
+
18
+ // A short, bounded reaper activity. Unlike the 30-day agent turn, the sweep is a
19
+ // fast DB pass + a handful of provider terminates; cap it well under the reaper
20
+ // period so a wedged sweep is abandoned rather than blocking the next fire.
21
+ const reaperActivity = proxyActivities<Pick<typeof activities, "reapSandboxLeases">>({
22
+ startToCloseTimeout: "5 minutes",
23
+ retry: { maximumAttempts: 1 },
24
+ });
25
+
26
+ export async function sandboxReaperWorkflow(): Promise<void> {
27
+ await reaperActivity.reapSandboxLeases();
28
+ }
@@ -0,0 +1,38 @@
1
+ import { getExternalWorkflowHandle, ParentClosePolicy, startChild } from "@temporalio/workflow";
2
+ import { activity } from "./activities";
3
+ import { queueChanged } from "./session";
4
+
5
+ export type ScheduledTaskFireWorkflowInput = {
6
+ accountId: string;
7
+ workspaceId: string;
8
+ taskId: string;
9
+ triggerType: "scheduled" | "manual";
10
+ agentRunUsageIdempotencyKey?: string;
11
+ };
12
+
13
+ export async function scheduledTaskFireWorkflow(input: ScheduledTaskFireWorkflowInput): Promise<void> {
14
+ const dispatched = await activity.dispatchScheduledTaskRun({
15
+ workspaceId: input.workspaceId,
16
+ taskId: input.taskId,
17
+ triggerType: input.triggerType,
18
+ ...(input.agentRunUsageIdempotencyKey ? { agentRunUsageIdempotencyKey: input.agentRunUsageIdempotencyKey } : {}),
19
+ });
20
+ if (dispatched.action === "start") {
21
+ await startSessionChild(dispatched.accountId, dispatched.workspaceId, dispatched.sessionId, dispatched.workflowId);
22
+ return;
23
+ }
24
+ try {
25
+ await getExternalWorkflowHandle(dispatched.workflowId).signal(queueChanged);
26
+ } catch {
27
+ await startSessionChild(dispatched.accountId, dispatched.workspaceId, dispatched.sessionId, dispatched.workflowId);
28
+ }
29
+ }
30
+
31
+ async function startSessionChild(accountId: string, workspaceId: string, sessionId: string, workflowId: string): Promise<void> {
32
+ await startChild("sessionWorkflow", {
33
+ workflowId,
34
+ parentClosePolicy: ParentClosePolicy.ABANDON,
35
+ workflowIdReusePolicy: "ALLOW_DUPLICATE",
36
+ args: [{ accountId, workspaceId, sessionId }],
37
+ });
38
+ }