@exagone313/dsh-podman 1.4.0 → 1.5.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 (47) hide show
  1. package/dist/card-route.d.ts +2 -1
  2. package/dist/card-route.js +89 -6
  3. package/dist/client/ContainerCard.js +1 -1
  4. package/dist/client/card-protocol.d.ts +12 -1
  5. package/dist/client/card-protocol.js +20 -0
  6. package/dist/client/container-card-controller.d.ts +5 -1
  7. package/dist/client/container-card-controller.js +12 -1
  8. package/dist/client/container-card-create-modal.js +14 -12
  9. package/dist/client/container-card-images.d.ts +9 -0
  10. package/dist/client/container-card-images.js +25 -3
  11. package/dist/client/container-card-ptc-section.d.ts +11 -0
  12. package/dist/client/container-card-ptc-section.js +36 -0
  13. package/dist/client/container-card-ptc.d.ts +69 -0
  14. package/dist/client/container-card-ptc.js +148 -0
  15. package/dist/client/container-card-resources.d.ts +1 -0
  16. package/dist/client/container-card-resources.js +13 -8
  17. package/dist/client/container-card-row.js +4 -2
  18. package/dist/client/container-card-shared.d.ts +1 -0
  19. package/dist/client/container-card-shared.js +4 -3
  20. package/dist/client/container-card-status.d.ts +6 -0
  21. package/dist/client/container-card-status.js +18 -14
  22. package/dist/client/index.js +832 -511
  23. package/dist/client/locales.d.ts +1 -1
  24. package/dist/client/locales.js +20 -0
  25. package/dist/client/relative-time.d.ts +2 -2
  26. package/dist/client/relative-time.js +8 -7
  27. package/dist/container-kind.d.ts +10 -0
  28. package/dist/container-kind.js +38 -0
  29. package/dist/dsh-version.d.ts +2 -0
  30. package/dist/dsh-version.js +33 -0
  31. package/dist/generated/version.d.ts +2 -2
  32. package/dist/generated/version.js +2 -2
  33. package/dist/grpc/proto/dshctl/v1/control.proto +35 -7
  34. package/dist/grpc/proto/dshguest/v1/guest.proto +17 -1
  35. package/dist/index.d.ts +1 -1
  36. package/dist/index.js +1 -1
  37. package/dist/public.d.ts +2 -0
  38. package/dist/public.js +19 -0
  39. package/dist/subprocess.js +271 -105
  40. package/dist/tool-handlers.js +12 -13
  41. package/dist/workspace-binding.d.ts +2 -0
  42. package/dist/workspace-binding.js +54 -11
  43. package/docs/configuration.md +6 -5
  44. package/docs/configuration.zh.md +6 -5
  45. package/docs/usage.md +37 -1
  46. package/docs/usage.zh.md +31 -1
  47. package/package.json +1 -1
@@ -4,17 +4,69 @@
4
4
  import { discardUnneededSpill, outputReader, spillTargetFor, splitEnv, } from "./output-reader.js";
5
5
  import { openGuestTerminal } from "./guest-terminal.js";
6
6
  import { globCwd, remoteArgv, unaryGuest } from "./guest-rpc.js";
7
- import { metadata } from "./workspace-binding.js";
8
- import { PassThrough } from "node:stream";
7
+ import { metadata, PTC_CONTAINER, } from "./workspace-binding.js";
8
+ import { Duplex, PassThrough } from "node:stream";
9
9
  import { SubprocessExecutableNotFoundError } from "@deepseek-ai/dsh-subprocess";
10
+ // The scratch directory a PTC child runs from. The PTC container has no
11
+ // project mount, so the harness's cwd (a workspace path) does not exist there;
12
+ // its /tmp is the one writable place it can start in.
13
+ const PTC_SCRATCH_CWD = "/tmp";
14
+ // The bounded range of numeric uids a PTC child may run as. Each concurrent
15
+ // control spawn gets its own id because the guest creates a per-uid home under
16
+ // /tmp/dsh-podman-home/<uid>; the ids stay outside the container's usual
17
+ // service and dynamic ranges.
18
+ const PTC_UID_MIN = 1001;
19
+ const PTC_UID_MAX = 10000;
20
+ // PtcUidPool hands out one numeric identity per running control spawn. It is
21
+ // bounded on purpose: running out is an explicit failure, never a fallback to a
22
+ // shared or privileged identity.
23
+ class PtcUidPool {
24
+ inUse = new Set();
25
+ // allocate returns the lowest free id, so a released one is reused before a
26
+ // fresh one, which keeps the pool compact under normal churn.
27
+ allocate() {
28
+ for (let id = PTC_UID_MIN; id <= PTC_UID_MAX; id++) {
29
+ if (this.inUse.has(id))
30
+ continue;
31
+ this.inUse.add(id);
32
+ return id;
33
+ }
34
+ throw new Error(`cannot start a PTC child: no free uid in ${PTC_UID_MIN}-${PTC_UID_MAX}`);
35
+ }
36
+ release(id) {
37
+ this.inUse.delete(id);
38
+ }
39
+ }
10
40
  export function createSubprocessProvider(resolver) {
11
41
  // Live termination handles, so service disposal can stop every process this
12
42
  // provider started (the harness's disposal contract).
13
43
  const live = new Set();
44
+ // The numeric identities the running control spawns hold, one per child.
45
+ const ptcUids = new PtcUidPool();
46
+ // Whether a guest agent implements the ExecControl transport, probed once
47
+ // per agent. An older agent answers UNIMPLEMENTED (or has no such method),
48
+ // and the probe then reports no support so spawn falls back to the previous
49
+ // behaviour.
50
+ const controlSupport = new Map();
51
+ const supportsControl = (binding) => {
52
+ const key = String(binding.socket ?? binding.token ?? "");
53
+ let probe = controlSupport.get(key);
54
+ if (probe === undefined) {
55
+ probe = unaryGuest({ binding }, "getCapabilities", {}).then((result) => result?.execControl === true, () => {
56
+ // An older agent does not implement the probe. Do not cache the
57
+ // failure: a recreated agent may answer next time.
58
+ controlSupport.delete(key);
59
+ return false;
60
+ });
61
+ controlSupport.set(key, probe);
62
+ }
63
+ return probe;
64
+ };
14
65
  return {
15
66
  dispose: () => {
16
67
  for (const terminate of Array.from(live))
17
68
  terminate();
69
+ controlSupport.clear();
18
70
  },
19
71
  // The harness's resolveExecutable carries no cwd, and this provider's
20
72
  // execution world is per-workspace (each workspace is its own container),
@@ -60,6 +112,27 @@ export function createSubprocessProvider(resolver) {
60
112
  const stderrSpill = spillTargetFor(spec.stdio?.stderr, "stderr");
61
113
  const stdoutReader = outputReader(spec.stdio?.stdout, stdoutSpill.spec);
62
114
  const stderrReader = outputReader(spec.stdio?.stderr, stderrSpill.spec);
115
+ // The control duplex is created synchronously because the harness reads
116
+ // `handle.control` immediately after spawn, while the guest's capability
117
+ // is only known once the binding resolves. A guest without ExecControl
118
+ // clears it again before the exec starts, which leaves the runtime with
119
+ // its normal missing-control error.
120
+ const wantsControl = spec.stdio?.control === "pipe";
121
+ // A control spawn is a PTC child, so it is assigned a private numeric
122
+ // identity for its whole run. A non-control spawn keeps the caller's own
123
+ // identity and never touches the pool.
124
+ const ptcUid = wantsControl ? ptcUids.allocate() : undefined;
125
+ const controlIn = wantsControl ? new PassThrough() : undefined;
126
+ const controlOut = wantsControl ? new PassThrough() : undefined;
127
+ let control = controlIn !== undefined && controlOut !== undefined
128
+ // @types/node omits the documented { writable, readable } overload.
129
+ ? Duplex.from({ writable: controlOut, readable: controlIn })
130
+ : undefined;
131
+ // The provider destroys this duplex on fallback and on exec exit.
132
+ // Duplexify reports that teardown as an AbortError, which would crash
133
+ // the host when no caller listener is attached; the caller's own
134
+ // listeners still observe transport failures.
135
+ control?.on("error", () => { });
63
136
  const state = {
64
137
  pid: -1,
65
138
  stdin: undefined,
@@ -127,112 +200,196 @@ export function createSubprocessProvider(resolver) {
127
200
  // A ripgrep discovery listing runs from its search root, so a pattern
128
201
  // containing "/" anchors to the path the harness passed; the workspace
129
202
  // binding still resolves from the caller's cwd.
130
- const runCwd = globCwd(spec.argv, spec.cwd) ?? spec.cwd;
131
- const done = resolver.resolve(spec.cwd).then((binding) => new Promise((resolveDone, reject) => {
203
+ //
204
+ // A control spawn is a PTC child: the harness runs its programmatic
205
+ // tool-calling runtime there, with the fd-7 channel it requested. The PTC
206
+ // container is separate from the workspace container and has no project
207
+ // mount, so the child starts in its scratch /tmp rather than the caller's
208
+ // workspace cwd. Every other spawn keeps today's binding and cwd.
209
+ const runCwd = wantsControl
210
+ ? PTC_SCRATCH_CWD
211
+ : globCwd(spec.argv, spec.cwd) ?? spec.cwd;
212
+ const resolved = wantsControl
213
+ ? resolver.ptcBinding().catch((error) => {
214
+ const detail = error instanceof Error ? error.message : String(error);
215
+ // There is deliberately no fallback to the workspace container: a
216
+ // PTC child that cannot run in the PTC container must fail instead of
217
+ // executing with the wrong filesystem, mounts, and credentials.
218
+ throw new Error(`cannot obtain the shared PTC container ${JSON.stringify(PTC_CONTAINER)} for this control spawn: ${detail}`);
219
+ })
220
+ : resolver.resolve(spec.cwd);
221
+ const done = resolved.then(async (binding) => {
132
222
  processBinding = binding;
133
- const stream = binding.guest.exec(metadata(binding.token));
134
- // finish settles the handle exactly once and tears it down however
135
- // the process ends: an exit message, a stream error, or a stream
136
- // that ends without one. The output pipes and spill files are
137
- // resolved on every path, so a failed exec leaves no half-open
138
- // handle, no hung reader, and no orphaned spill.
139
- const finish = (error, exit) => {
140
- if (settled)
141
- return;
142
- settled = true;
143
- exited = true;
144
- if (killTimer !== undefined) {
145
- clearTimeout(killTimer);
146
- killTimer = undefined;
147
- }
148
- // A pause applied for backpressure must not outlive the process,
149
- // or the exit/error message could stay stuck behind it.
150
- if (pendingDrains > 0) {
151
- pendingDrains = 0;
152
- stream.resume?.();
153
- }
154
- state.stdout?.end();
155
- state.stderr?.end();
156
- discardUnneededSpill(binding, stdoutReader);
157
- discardUnneededSpill(binding, stderrReader);
158
- if (error === undefined)
159
- resolveDone(exit);
160
- else
161
- reject(error);
162
- };
163
- stream.on("data", (output) => {
164
- if (output.stdoutChunk) {
165
- const data = Buffer.from(output.stdoutChunk);
166
- stdoutReader?.append(data);
167
- writeChunk(stream, state.stdout, data);
168
- if (spec.stdio?.stdout === "inherit") {
169
- process.stdout.write(data);
223
+ const withControl = wantsControl &&
224
+ await supportsControl(binding);
225
+ if (wantsControl && !withControl) {
226
+ control?.destroy();
227
+ control = undefined;
228
+ }
229
+ return new Promise((resolveDone, reject) => {
230
+ // One control call per exec. It is opened only after the guest
231
+ // reports the process id, because its first frame names the exec.
232
+ let controlCall;
233
+ let controlClosed = false;
234
+ const closeControl = () => {
235
+ if (controlClosed)
236
+ return;
237
+ controlClosed = true;
238
+ try {
239
+ controlCall?.cancel?.();
170
240
  }
171
- }
172
- if (output.processId) {
173
- state.pid = Number(output.processId);
174
- if (terminated)
175
- terminate();
176
- }
177
- if (output.stderrChunk) {
178
- const data = Buffer.from(output.stderrChunk);
179
- stderrReader?.append(data);
180
- writeChunk(stream, state.stderr, data);
181
- if (spec.stdio?.stderr === "inherit") {
182
- process.stderr.write(data);
241
+ catch {
242
+ // A finished call cannot be cancelled again.
183
243
  }
184
- }
185
- if (output.exit) {
186
- stdoutReader?.setSpillValid(Boolean(output.exit.stdoutSpillValid));
187
- stderrReader?.setSpillValid(Boolean(output.exit.stderrSpillValid));
188
- finish(undefined, {
189
- exitCode: output.exit.exitCode,
190
- signal: output.exit.signaled ? output.exit.signal : null,
244
+ };
245
+ const openControl = (execId) => {
246
+ if (!withControl || controlCall !== undefined)
247
+ return;
248
+ controlCall = binding.guest.execControl(metadata(binding.token));
249
+ controlCall.on("data", (frame) => {
250
+ const data = frame?.data;
251
+ if (data !== undefined && data.length > 0) {
252
+ controlIn?.write(Buffer.from(data));
253
+ }
254
+ });
255
+ controlCall.on("error", (error) => {
256
+ // The transport is gone; fail the caller's channel rather than
257
+ // leaving it open with no way to deliver frames.
258
+ controlIn?.destroy(error instanceof Error ? error : new Error(String(error)));
259
+ });
260
+ controlCall.on("end", () => controlIn?.end());
261
+ controlOut?.on("data", (data) => {
262
+ if (controlClosed)
263
+ return;
264
+ try {
265
+ controlCall.write({ data });
266
+ }
267
+ catch {
268
+ closeControl();
269
+ }
191
270
  });
271
+ controlOut?.on("end", () => {
272
+ if (!controlClosed)
273
+ controlCall.end();
274
+ });
275
+ controlOut?.on("close", closeControl);
276
+ controlCall.write({ execId });
277
+ };
278
+ const stream = binding.guest.exec(metadata(binding.token));
279
+ // finish settles the handle exactly once and tears it down however
280
+ // the process ends: an exit message, a stream error, or a stream
281
+ // that ends without one. The output pipes and spill files are
282
+ // resolved on every path, so a failed exec leaves no half-open
283
+ // handle, no hung reader, and no orphaned spill.
284
+ const finish = (error, exit) => {
285
+ if (settled)
286
+ return;
287
+ settled = true;
288
+ exited = true;
289
+ if (killTimer !== undefined) {
290
+ clearTimeout(killTimer);
291
+ killTimer = undefined;
292
+ }
293
+ // A pause applied for backpressure must not outlive the process,
294
+ // or the exit/error message could stay stuck behind it.
295
+ if (pendingDrains > 0) {
296
+ pendingDrains = 0;
297
+ stream.resume?.();
298
+ }
299
+ control?.destroy();
300
+ closeControl();
301
+ state.stdout?.end();
302
+ state.stderr?.end();
303
+ discardUnneededSpill(binding, stdoutReader);
304
+ discardUnneededSpill(binding, stderrReader);
305
+ if (error === undefined)
306
+ resolveDone(exit);
307
+ else
308
+ reject(error);
309
+ };
310
+ stream.on("data", (output) => {
311
+ if (output.stdoutChunk) {
312
+ const data = Buffer.from(output.stdoutChunk);
313
+ stdoutReader?.append(data);
314
+ writeChunk(stream, state.stdout, data);
315
+ if (spec.stdio?.stdout === "inherit") {
316
+ process.stdout.write(data);
317
+ }
318
+ }
319
+ if (output.processId) {
320
+ state.pid = Number(output.processId);
321
+ openControl(String(output.processId));
322
+ if (terminated)
323
+ terminate();
324
+ }
325
+ if (output.stderrChunk) {
326
+ const data = Buffer.from(output.stderrChunk);
327
+ stderrReader?.append(data);
328
+ writeChunk(stream, state.stderr, data);
329
+ if (spec.stdio?.stderr === "inherit") {
330
+ process.stderr.write(data);
331
+ }
332
+ }
333
+ if (output.exit) {
334
+ stdoutReader?.setSpillValid(Boolean(output.exit.stdoutSpillValid));
335
+ stderrReader?.setSpillValid(Boolean(output.exit.stderrSpillValid));
336
+ finish(undefined, {
337
+ exitCode: output.exit.exitCode,
338
+ signal: output.exit.signaled ? output.exit.signal : null,
339
+ });
340
+ }
341
+ });
342
+ stream.on("error", (error) => {
343
+ // The guest connection failed: stop the process if it is still
344
+ // reachable, then release the caller instead of leaving it
345
+ // pending on a stream that will never carry an exit message.
346
+ terminate();
347
+ finish(error instanceof Error ? error : new Error(String(error)));
348
+ });
349
+ stream.on("end", () => {
350
+ // A stream that ends without an exit message (guest restart,
351
+ // dropped socket) must not leave the caller pending forever.
352
+ if (settled)
353
+ return;
354
+ terminate();
355
+ finish(new Error("exec stream ended before the process exited"));
356
+ });
357
+ const env = splitEnv(spec.env);
358
+ if (withControl)
359
+ env.env.DSH_SUBPROCESS_CONTROL = "pipe";
360
+ stream.write({
361
+ start: {
362
+ argv: remoteArgv(spec.argv),
363
+ cwd: runCwd,
364
+ env: env.env,
365
+ unsetEnv: env.unsetEnv,
366
+ // A caller that will not send stdin leaves the child on
367
+ // /dev/null: a pipe would be a non-TTY stdin, and tools like
368
+ // ripgrep then read stdin instead of the working directory.
369
+ stdinPipe: spec.stdio?.stdin === "pipe",
370
+ ...(withControl ? { control: true } : {}),
371
+ // The PTC child runs as its own numeric uid/gid; it inherits no
372
+ // supplementary groups from the agent.
373
+ ...(ptcUid !== undefined
374
+ ? { uid: { value: ptcUid }, gid: { value: ptcUid } }
375
+ : {}),
376
+ ...(stdoutSpill.target !== undefined
377
+ ? { spillStdout: stdoutSpill.target }
378
+ : {}),
379
+ ...(stderrSpill.target !== undefined
380
+ ? { spillStderr: stderrSpill.target }
381
+ : {}),
382
+ },
383
+ });
384
+ if (spec.stdio?.stdin !== "pipe")
385
+ stream.end();
386
+ else {
387
+ state.stdin = new PassThrough();
388
+ state.stdin.on("data", (data) => stream.write({ stdinChunk: data }));
389
+ state.stdin.on("end", () => stream.end());
192
390
  }
193
391
  });
194
- stream.on("error", (error) => {
195
- // The guest connection failed: stop the process if it is still
196
- // reachable, then release the caller instead of leaving it
197
- // pending on a stream that will never carry an exit message.
198
- terminate();
199
- finish(error instanceof Error ? error : new Error(String(error)));
200
- });
201
- stream.on("end", () => {
202
- // A stream that ends without an exit message (guest restart,
203
- // dropped socket) must not leave the caller pending forever.
204
- if (settled)
205
- return;
206
- terminate();
207
- finish(new Error("exec stream ended before the process exited"));
208
- });
209
- const env = splitEnv(spec.env);
210
- stream.write({
211
- start: {
212
- argv: remoteArgv(spec.argv),
213
- cwd: runCwd,
214
- env: env.env,
215
- unsetEnv: env.unsetEnv,
216
- // A caller that will not send stdin leaves the child on
217
- // /dev/null: a pipe would be a non-TTY stdin, and tools like
218
- // ripgrep then read stdin instead of the working directory.
219
- stdinPipe: spec.stdio?.stdin === "pipe",
220
- ...(stdoutSpill.target !== undefined
221
- ? { spillStdout: stdoutSpill.target }
222
- : {}),
223
- ...(stderrSpill.target !== undefined
224
- ? { spillStderr: stderrSpill.target }
225
- : {}),
226
- },
227
- });
228
- if (spec.stdio?.stdin !== "pipe")
229
- stream.end();
230
- else {
231
- state.stdin = new PassThrough();
232
- state.stdin.on("data", (data) => stream.write({ stdinChunk: data }));
233
- state.stdin.on("end", () => stream.end());
234
- }
235
- }));
392
+ });
236
393
  if (spec.signal !== undefined) {
237
394
  if (spec.signal.aborted)
238
395
  terminate();
@@ -240,12 +397,21 @@ export function createSubprocessProvider(resolver) {
240
397
  spec.signal.addEventListener("abort", terminate, { once: true });
241
398
  }
242
399
  live.add(terminate);
400
+ void done.catch(() => control?.destroy());
243
401
  void done.finally(() => live.delete(terminate)).catch(() => { });
402
+ // The child's identity is free again once its exec settles, however it
403
+ // ended (an exit, a stream failure, or a failed binding).
404
+ if (ptcUid !== undefined) {
405
+ void done.finally(() => ptcUids.release(ptcUid)).catch(() => { });
406
+ }
244
407
  return {
245
408
  ...state,
246
- // The harness's SubprocessHandle declares a control channel; this
247
- // provider runs every process over gRPC, so none exists.
248
- control: undefined,
409
+ // The control channel is present only when the caller requested it and
410
+ // the guest implements ExecControl; a guest without the feature clears
411
+ // it before the exec starts.
412
+ get control() {
413
+ return control;
414
+ },
249
415
  collected: {
250
416
  ...(stdoutReader === undefined ? {} : { stdout: stdoutReader }),
251
417
  ...(stderrReader === undefined ? {} : { stderr: stderrReader }),
@@ -4,7 +4,8 @@
4
4
  import { bytesText, currentCwd, fsError, guestCwd, outputLines, resolveToolBinding, runExec, sessionWorkspaceSlug, streamLines, unaryGuest, } from "./guest-rpc.js";
5
5
  import { inferMountKind, mountsFromInput, projectMountDestinationReason, } from "./mount-input.js";
6
6
  import { mergeDefaultEnv } from "./container-env.js";
7
- import { publicContainer, publicDaemon, publicImage, publicMount, publicPublishedPort, } from "./public.js";
7
+ import { isPtcContainer } from "./container-kind.js";
8
+ import { publicContainerResult, publicContainers, publicDaemon, publicImage, publicMount, publicPublishedPort, } from "./public.js";
8
9
  import { portProtocolToProto } from "./publish-port.js";
9
10
  import { grpc } from "./grpc/runtime-client.js";
10
11
  import { defaultMountMode, mountKindToProto, mountModeToProto, } from "./mount-enums.js";
@@ -152,12 +153,10 @@ export const toolHandlers = {
152
153
  const defaultRow = rows.find((row) => row.containerName === "default");
153
154
  const listed = defaultRow === undefined
154
155
  ? [{ containerName: "default", status: "not started" }]
155
- : [publicContainer(defaultRow)];
156
+ : publicContainers([defaultRow]);
156
157
  return [
157
158
  ...listed,
158
- ...rows
159
- .filter((row) => row.containerName !== "default")
160
- .map(publicContainer),
159
+ ...publicContainers(rows.filter((row) => row.containerName !== "default")),
161
160
  ];
162
161
  },
163
162
  container_start: async (resolver, input, exec) => {
@@ -173,7 +172,7 @@ export const toolHandlers = {
173
172
  ...(input.secretEnv !== undefined ? { secretEnv: input.secretEnv } : {}),
174
173
  ...(input.paths !== undefined ? { paths: input.paths } : {}),
175
174
  });
176
- return publicContainer(row);
175
+ return publicContainerResult(row);
177
176
  },
178
177
  container_recreate: async (resolver, input, exec) => {
179
178
  const mounts = mountsFromInput(input.mounts, resolver.getConfig().projectsRoot);
@@ -186,7 +185,7 @@ export const toolHandlers = {
186
185
  ...(input.secretEnv !== undefined ? { secretEnv: input.secretEnv } : {}),
187
186
  ...(input.paths !== undefined ? { paths: input.paths } : {}),
188
187
  });
189
- return publicContainer(row);
188
+ return publicContainerResult(row);
190
189
  },
191
190
  container_remove: async (resolver, input, exec) => {
192
191
  await resolver.control("removeContainer", {
@@ -309,7 +308,7 @@ export const toolHandlers = {
309
308
  const result = await resolver.control("listContainers", {});
310
309
  const row = (result.containers ?? []).find((candidate) => candidate.workspaceSlug === slug &&
311
310
  candidate.containerName === input.container);
312
- if (row === undefined) {
311
+ if (row === undefined || isPtcContainer(row)) {
313
312
  throw containerNotFound(input.container, slug);
314
313
  }
315
314
  const mounts = row.mounts ?? [];
@@ -349,7 +348,7 @@ export const toolHandlers = {
349
348
  request.mode = mode;
350
349
  }
351
350
  const row = await resolver.control("addContainerMount", request);
352
- return publicContainer(row);
351
+ return publicContainerResult(row);
353
352
  },
354
353
  container_mount_remove: async (resolver, input, exec) => {
355
354
  const kind = inferMountKind(input);
@@ -374,7 +373,7 @@ export const toolHandlers = {
374
373
  request.destination = input.destination;
375
374
  }
376
375
  const row = await resolver.control("removeContainerMount", request);
377
- return publicContainer(row);
376
+ return publicContainerResult(row);
378
377
  },
379
378
  container_mount_update: async (resolver, input, exec) => {
380
379
  const kind = inferMountKind(input);
@@ -402,7 +401,7 @@ export const toolHandlers = {
402
401
  }
403
402
  }
404
403
  const row = await resolver.control("updateContainerMount", request);
405
- return publicContainer(row);
404
+ return publicContainerResult(row);
406
405
  },
407
406
  container_publish_port: async (resolver, input, exec) => {
408
407
  const request = {
@@ -508,7 +507,7 @@ export const toolHandlers = {
508
507
  env: input.env,
509
508
  secret: input.secret,
510
509
  });
511
- return publicContainer(row);
510
+ return publicContainerResult(row);
512
511
  },
513
512
  container_secret_remove: async (resolver, input, exec) => {
514
513
  const row = await resolver.control("removeContainerSecret", {
@@ -516,7 +515,7 @@ export const toolHandlers = {
516
515
  container: input.container,
517
516
  env: input.env,
518
517
  });
519
- return publicContainer(row);
518
+ return publicContainerResult(row);
520
519
  },
521
520
  daemon_start: async (resolver, input, exec) => {
522
521
  const sessionCwd = currentCwd(exec);
@@ -14,6 +14,7 @@ export interface BindingConfig {
14
14
  readyTimeoutMs?: number;
15
15
  containerEnv?: Record<string, string>;
16
16
  }
17
+ export declare const PTC_CONTAINER = "ptc";
17
18
  export declare class WorkspaceResolver {
18
19
  private readonly config;
19
20
  private readonly registry;
@@ -30,6 +31,7 @@ export declare class WorkspaceResolver {
30
31
  private workspaceForCwd;
31
32
  resolveSlug(key: string, signal?: AbortSignal): Promise<WorkspaceBinding>;
32
33
  containerBinding(cwd: unknown, container: string, signal?: AbortSignal): Promise<WorkspaceBinding>;
34
+ ptcBinding(signal?: AbortSignal): Promise<WorkspaceBinding>;
33
35
  private resolveContainerBinding;
34
36
  private buildContainerBinding;
35
37
  private ready;
@@ -3,6 +3,7 @@
3
3
  // SPDX-License-Identifier: MIT
4
4
  import { closeClients, controlClient, grpc, guestClient, unary, } from "./grpc/runtime-client.js";
5
5
  import { mergeDefaultEnv } from "./container-env.js";
6
+ import { pinnedDshVersion } from "./dsh-version.js";
6
7
  import { isAbsolute, join } from "node:path";
7
8
  import { VERSION } from "./generated/version.js";
8
9
  // The control calls that change a container's mount set or recreate it. A
@@ -20,13 +21,23 @@ const CONTAINER_MUTATIONS = {
20
21
  removeContainerSecret: "container",
21
22
  removeWorkspace: "workspace",
22
23
  };
24
+ // PTC_CONTAINER is the reserved logical name of the orchestrator-managed PTC
25
+ // container. Its kind marks it as PTC in every snapshot, and the orchestrator
26
+ // refuses every user-addressed mutation on this name; only the resolver's own
27
+ // binding path may reach it.
28
+ export const PTC_CONTAINER = "ptc";
29
+ // PTC_BINDING_KEY is the fixed cache key of the one shared PTC binding. The PTC
30
+ // container belongs to no workspace, so its entry is neither namespaced by a
31
+ // slug nor dropped when a workspace is forgotten.
32
+ const PTC_BINDING_KEY = "ptc:shared";
23
33
  export class WorkspaceResolver {
24
34
  config;
25
35
  registry;
26
36
  bindings = new Map();
27
37
  // Named containers get their own cache, keyed by "<slug>:<logical name>", so
28
38
  // resolving one does not re-run ensureContainer, rebuild a gRPC channel, and
29
- // wait for readiness on every tool call.
39
+ // wait for readiness on every tool call. The shared PTC binding uses its own
40
+ // fixed key instead.
30
41
  containerBindings = new Map();
31
42
  constructor(
32
43
  // A reader rather than a snapshot: the plugin's preferences are volatile
@@ -144,6 +155,25 @@ export class WorkspaceResolver {
144
155
  }
145
156
  return entry.binding;
146
157
  }
158
+ // ptcBinding resolves the one shared PTC container. It needs no session
159
+ // working directory: the container belongs to no workspace, so its binding is
160
+ // cached under a fixed global key and ensured with an empty workspace slug.
161
+ // It never offers the session directory as a cwd (the PTC container has no
162
+ // project mount) and never asks for a user-addressed recreate when its agent
163
+ // is unreachable: the reserved container is orchestrator-owned, so only
164
+ // EnsureContainer may create or repair it. A retry therefore re-asks the
165
+ // orchestrator, which recreates it lazily when its record is unusable.
166
+ async ptcBinding(signal) {
167
+ let entry = await this.resolveContainerBinding("", PTC_CONTAINER, PTC_BINDING_KEY, signal);
168
+ try {
169
+ return await this.ensureAgentReady(entry.binding);
170
+ }
171
+ catch {
172
+ this.containerBindings.delete(PTC_BINDING_KEY);
173
+ entry = await this.resolveContainerBinding("", PTC_CONTAINER, PTC_BINDING_KEY, signal);
174
+ return await this.ensureAgentReady(entry.binding);
175
+ }
176
+ }
147
177
  // resolveContainerBinding returns the cached promise for a named container,
148
178
  // creating it once. It deliberately stops at an "ensureContainer + build a
149
179
  // binding" step: readiness is per-call, so a credential refresh can never
@@ -288,18 +318,25 @@ export class WorkspaceResolver {
288
318
  // ensureContainer asks the orchestrator for a usable container, recreating it
289
319
  // when it is missing, stopped, or runs a guest agent from an outdated image,
290
320
  // and returns its row. A container the orchestrator does not know is reported
291
- // as the caller's missing container.
321
+ // as the caller's missing container. The PTC request also carries the harness
322
+ // release the plugin targets, because its image is built on demand for it.
292
323
  async ensureContainer(slug, container, signal) {
324
+ const request = {
325
+ workspaceSlug: slug,
326
+ container,
327
+ };
328
+ if (container === PTC_CONTAINER) {
329
+ request.dshVersion = pinnedDshVersion();
330
+ }
293
331
  try {
294
- return await this.control("ensureContainer", {
295
- workspaceSlug: slug,
296
- container,
297
- }, signal);
332
+ return await this.control("ensureContainer", request, signal);
298
333
  }
299
334
  catch (error) {
300
335
  if (error.code !== grpc.status.NOT_FOUND)
301
336
  throw error;
302
- throw containerNotFound(container, slug);
337
+ // The PTC container has no workspace, so it is reported alone rather
338
+ // than as missing from an empty workspace.
339
+ throw containerNotFound(container, slug === "" ? undefined : slug);
303
340
  }
304
341
  }
305
342
  async control(method, request, signal) {
@@ -318,15 +355,21 @@ export class WorkspaceResolver {
318
355
  const slug = typeof fields.workspaceSlug === "string"
319
356
  ? fields.workspaceSlug
320
357
  : "";
321
- if (slug === "")
358
+ const container = typeof fields.container === "string"
359
+ ? fields.container
360
+ : "";
361
+ if (slug === "") {
362
+ // The explicit workspace-less PTC remove retires the shared container, so
363
+ // its cached binding must not outlive it.
364
+ if (method === "removeContainer" && container === PTC_CONTAINER) {
365
+ this.containerBindings.delete(PTC_BINDING_KEY);
366
+ }
322
367
  return;
368
+ }
323
369
  if (scope === "workspace") {
324
370
  this.forgetWorkspace(slug);
325
371
  return;
326
372
  }
327
- const container = typeof fields.container === "string"
328
- ? fields.container
329
- : "";
330
373
  if (container === "")
331
374
  return;
332
375
  this.forgetContainer(slug, container);