dev3000 0.0.188 → 0.0.191

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 (159) hide show
  1. package/README.md +84 -12
  2. package/dist/cdp-monitor.d.ts +10 -0
  3. package/dist/cdp-monitor.d.ts.map +1 -1
  4. package/dist/cdp-monitor.js +28 -4
  5. package/dist/cdp-monitor.js.map +1 -1
  6. package/dist/runtime/bridge.d.ts +2 -0
  7. package/dist/runtime/bridge.d.ts.map +1 -1
  8. package/dist/runtime/bridge.js +74 -0
  9. package/dist/runtime/bridge.js.map +1 -1
  10. package/dist/runtime/browser-events.d.ts +3 -2
  11. package/dist/runtime/browser-events.d.ts.map +1 -1
  12. package/dist/runtime/browser-events.js +11 -53
  13. package/dist/runtime/browser-events.js.map +1 -1
  14. package/dist/runtime/browser-metrics.d.ts +147 -0
  15. package/dist/runtime/browser-metrics.d.ts.map +1 -0
  16. package/dist/runtime/browser-metrics.js +243 -0
  17. package/dist/runtime/browser-metrics.js.map +1 -0
  18. package/dist/runtime/chrome-isolation.d.ts +3 -2
  19. package/dist/runtime/chrome-isolation.d.ts.map +1 -1
  20. package/dist/runtime/chrome-isolation.js +23 -35
  21. package/dist/runtime/chrome-isolation.js.map +1 -1
  22. package/dist/runtime/cli.js +63 -2
  23. package/dist/runtime/cli.js.map +1 -1
  24. package/dist/runtime/desktop-mcp.d.ts +216 -0
  25. package/dist/runtime/desktop-mcp.d.ts.map +1 -0
  26. package/dist/runtime/desktop-mcp.js +258 -0
  27. package/dist/runtime/desktop-mcp.js.map +1 -0
  28. package/dist/runtime/git-identity.d.ts +17 -0
  29. package/dist/runtime/git-identity.d.ts.map +1 -0
  30. package/dist/runtime/git-identity.js +41 -0
  31. package/dist/runtime/git-identity.js.map +1 -0
  32. package/dist/runtime/github-publish.d.ts +31 -0
  33. package/dist/runtime/github-publish.d.ts.map +1 -0
  34. package/dist/runtime/github-publish.js +237 -0
  35. package/dist/runtime/github-publish.js.map +1 -0
  36. package/dist/runtime/harness.d.ts +14 -3
  37. package/dist/runtime/harness.d.ts.map +1 -1
  38. package/dist/runtime/harness.js +55 -7
  39. package/dist/runtime/harness.js.map +1 -1
  40. package/dist/runtime/mcp-stdio.d.ts +17 -0
  41. package/dist/runtime/mcp-stdio.d.ts.map +1 -0
  42. package/dist/runtime/mcp-stdio.js +99 -0
  43. package/dist/runtime/mcp-stdio.js.map +1 -0
  44. package/dist/runtime/network-evidence.d.ts +28 -0
  45. package/dist/runtime/network-evidence.d.ts.map +1 -0
  46. package/dist/runtime/network-evidence.js +291 -0
  47. package/dist/runtime/network-evidence.js.map +1 -0
  48. package/dist/runtime/runtime.d.ts +4 -0
  49. package/dist/runtime/runtime.d.ts.map +1 -1
  50. package/dist/runtime/runtime.js +48 -17
  51. package/dist/runtime/runtime.js.map +1 -1
  52. package/dist/runtime/sandbox-agent.d.ts +5 -0
  53. package/dist/runtime/sandbox-agent.d.ts.map +1 -1
  54. package/dist/runtime/sandbox-agent.js +32 -0
  55. package/dist/runtime/sandbox-agent.js.map +1 -1
  56. package/dist/runtime/sandbox-cleanup.d.ts +14 -0
  57. package/dist/runtime/sandbox-cleanup.d.ts.map +1 -0
  58. package/dist/runtime/sandbox-cleanup.js +49 -0
  59. package/dist/runtime/sandbox-cleanup.js.map +1 -0
  60. package/dist/runtime/sandbox-command.d.ts +1 -0
  61. package/dist/runtime/sandbox-command.d.ts.map +1 -1
  62. package/dist/runtime/sandbox-command.js +38 -8
  63. package/dist/runtime/sandbox-command.js.map +1 -1
  64. package/dist/runtime/sandbox-context.d.ts +5 -0
  65. package/dist/runtime/sandbox-context.d.ts.map +1 -0
  66. package/dist/runtime/sandbox-context.js +42 -0
  67. package/dist/runtime/sandbox-context.js.map +1 -0
  68. package/dist/runtime/sandbox-fx-resume.d.ts +11 -0
  69. package/dist/runtime/sandbox-fx-resume.d.ts.map +1 -0
  70. package/dist/runtime/sandbox-fx-resume.js +45 -0
  71. package/dist/runtime/sandbox-fx-resume.js.map +1 -0
  72. package/dist/runtime/sandbox-gateway.d.ts +17 -0
  73. package/dist/runtime/sandbox-gateway.d.ts.map +1 -0
  74. package/dist/runtime/sandbox-gateway.js +34 -0
  75. package/dist/runtime/sandbox-gateway.js.map +1 -0
  76. package/dist/runtime/sandbox-github.d.ts +10 -0
  77. package/dist/runtime/sandbox-github.d.ts.map +1 -0
  78. package/dist/runtime/sandbox-github.js +35 -0
  79. package/dist/runtime/sandbox-github.js.map +1 -0
  80. package/dist/runtime/sandbox-local-harness.d.ts +34 -0
  81. package/dist/runtime/sandbox-local-harness.d.ts.map +1 -0
  82. package/dist/runtime/sandbox-local-harness.js +138 -0
  83. package/dist/runtime/sandbox-local-harness.js.map +1 -0
  84. package/dist/runtime/sandbox-preview.d.ts +14 -0
  85. package/dist/runtime/sandbox-preview.d.ts.map +1 -0
  86. package/dist/runtime/sandbox-preview.js +96 -0
  87. package/dist/runtime/sandbox-preview.js.map +1 -0
  88. package/dist/runtime/sandbox-process.d.ts +11 -0
  89. package/dist/runtime/sandbox-process.d.ts.map +1 -0
  90. package/dist/runtime/sandbox-process.js +77 -0
  91. package/dist/runtime/sandbox-process.js.map +1 -0
  92. package/dist/runtime/sandbox-proxy.d.ts +2 -0
  93. package/dist/runtime/sandbox-proxy.d.ts.map +1 -1
  94. package/dist/runtime/sandbox-proxy.js +75 -20
  95. package/dist/runtime/sandbox-proxy.js.map +1 -1
  96. package/dist/runtime/sandbox-recovery.d.ts +4 -0
  97. package/dist/runtime/sandbox-recovery.d.ts.map +1 -0
  98. package/dist/runtime/sandbox-recovery.js +36 -0
  99. package/dist/runtime/sandbox-recovery.js.map +1 -0
  100. package/dist/runtime/sandbox-sessions.d.ts +8 -1
  101. package/dist/runtime/sandbox-sessions.d.ts.map +1 -1
  102. package/dist/runtime/sandbox-sessions.js +20 -2
  103. package/dist/runtime/sandbox-sessions.js.map +1 -1
  104. package/dist/runtime/sandbox-setup.d.ts +4 -0
  105. package/dist/runtime/sandbox-setup.d.ts.map +1 -0
  106. package/dist/runtime/sandbox-setup.js +56 -0
  107. package/dist/runtime/sandbox-setup.js.map +1 -0
  108. package/dist/runtime/sandbox-shell.d.ts +27 -0
  109. package/dist/runtime/sandbox-shell.d.ts.map +1 -0
  110. package/dist/runtime/sandbox-shell.js +169 -0
  111. package/dist/runtime/sandbox-shell.js.map +1 -0
  112. package/dist/runtime/sandbox-watch.d.ts +11 -0
  113. package/dist/runtime/sandbox-watch.d.ts.map +1 -0
  114. package/dist/runtime/sandbox-watch.js +30 -0
  115. package/dist/runtime/sandbox-watch.js.map +1 -0
  116. package/dist/runtime/sandbox-workspace.d.ts +125 -0
  117. package/dist/runtime/sandbox-workspace.d.ts.map +1 -0
  118. package/dist/runtime/sandbox-workspace.js +205 -0
  119. package/dist/runtime/sandbox-workspace.js.map +1 -0
  120. package/dist/runtime/sandbox.d.ts +21 -2
  121. package/dist/runtime/sandbox.d.ts.map +1 -1
  122. package/dist/runtime/sandbox.js +435 -198
  123. package/dist/runtime/sandbox.js.map +1 -1
  124. package/dist/runtime/session.d.ts +1 -1
  125. package/dist/runtime/session.d.ts.map +1 -1
  126. package/dist/runtime/session.js +3 -3
  127. package/dist/runtime/session.js.map +1 -1
  128. package/dist/runtime/terminal.d.ts +19 -0
  129. package/dist/runtime/terminal.d.ts.map +1 -0
  130. package/dist/runtime/terminal.js +60 -0
  131. package/dist/runtime/terminal.js.map +1 -0
  132. package/dist/runtime/workspace-client.d.ts +2 -0
  133. package/dist/runtime/workspace-client.d.ts.map +1 -0
  134. package/dist/runtime/workspace-client.js +42 -0
  135. package/dist/runtime/workspace-client.js.map +1 -0
  136. package/package.json +2 -1
  137. package/scripts/eve/README.md +341 -0
  138. package/scripts/eve/agent/agent.ts +12 -0
  139. package/scripts/eve/agent/channels/eve.ts +23 -0
  140. package/scripts/eve/agent/instructions.md +53 -0
  141. package/scripts/eve/agent/sandbox.ts +34 -0
  142. package/scripts/eve/build-cache.mjs +18 -0
  143. package/scripts/eve/build-cache.test.mjs +32 -0
  144. package/scripts/eve/client.mjs +229 -0
  145. package/scripts/eve/connection.mjs +89 -0
  146. package/scripts/eve/conversation.mjs +91 -0
  147. package/scripts/eve/conversation.test.mjs +113 -0
  148. package/scripts/eve/fixture-agent.ts +101 -0
  149. package/scripts/eve/images.mjs +84 -0
  150. package/scripts/eve/launch.mjs +277 -0
  151. package/scripts/eve/model-command.mjs +21 -0
  152. package/scripts/eve/reconnect.mjs +22 -0
  153. package/scripts/eve/reconnect.test.mjs +41 -0
  154. package/scripts/eve/settings.mjs +33 -0
  155. package/scripts/eve/supervisor.mjs +41 -0
  156. package/scripts/eve/tui-client.mjs +234 -0
  157. package/scripts/eve/tui-input.mjs +114 -0
  158. package/scripts/eve/verify.mjs +575 -0
  159. package/skills/d3k/SKILL.md +48 -5
@@ -0,0 +1,341 @@
1
+ # Eve with a local client and remote execution
2
+
3
+ Eve runs beside the project in the sandbox, with its terminal UI running locally.
4
+ New CLI sandbox sessions launch it by default; `--harness eve` also selects it
5
+ explicitly. Each saved d3k sandbox session retains its Eve conversation and workflow data
6
+ in a stable remote service directory. Resume reopens that conversation, including
7
+ after rebuilding the service. It does not change d3k's compute cleanup. The standalone launcher connects to an already running sandbox.
8
+
9
+ The viable design is a local client using Eve's HTTP API, with an Eve service
10
+ running beside the existing checkout and dev server. Mosh/UDP is unnecessary:
11
+ editing input and reading the clipboard happen locally; submitted messages,
12
+ attachments, approvals, and resumable output cross the network.
13
+
14
+ ```mermaid
15
+ flowchart LR
16
+ UI[Local terminal or future web client] <-->|Authenticated HTTPS| Eve[Eve service in Sandbox]
17
+ Eve --> State[Remote conversation and approval state]
18
+ Eve --> Tools[Tools in existing checkout]
19
+ Tools --> Runtime[d3k runtime and dev server]
20
+ Runtime <-->|Existing authenticated bridge| Companion[Local d3k companion]
21
+ Companion --> Chrome[Local isolated Chrome]
22
+ ```
23
+
24
+ Closing the laptop disconnects the client and browser companion. The remote
25
+ agent can keep editing and running commands. Browser work waits until a supported
26
+ companion reconnects. A user can answer a pending approval from another client
27
+ without creating a new conversation or repeating the original prompt.
28
+
29
+ ## Try the local terminal
30
+
31
+ With the local canary installed, start a new sandbox through the CLI:
32
+
33
+ ```sh
34
+ d3k --project my-team/my-project
35
+ # Explicit equivalent:
36
+ d3k --project my-team/my-project --harness eve
37
+ ```
38
+
39
+ This creates a fresh checkout of the linked remote repository; it does not upload
40
+ uncommitted files from your current local directory. Existing saved sessions keep
41
+ their selected harness. Use `--harness fx`, `--harness codex`, or `--harness claude`
42
+ to select another harness, or `--no-shell` for a retained companion without one.
43
+
44
+ Keep a d3k sandbox session running with its local browser connected. In a local
45
+ interactive terminal, from this checkout, run:
46
+
47
+ ```sh
48
+ bun scripts/eve/launch.mjs --resume <d3k-saved-session-id>
49
+ ```
50
+
51
+ The launcher uses your local Vercel login, uploads this source into a separate
52
+ temporary service directory in that existing sandbox, installs pinned Eve
53
+ dependencies, and opens the local client. No commit, release, global Eve install,
54
+ or website deployment is needed. Management credentials remain on the laptop.
55
+ Each Eve session uses a project-scoped key under your team’s AI Gateway, with no
56
+ session spending cap by default. `--gateway-budget <usd>` sets an optional cap;
57
+ `--gateway-budget none` removes a saved cap. Access expires within 30 minutes or before
58
+ the current sandbox expires. Credentials stay in process memory and are not
59
+ printed or saved in a launcher file. The remote supervisor also stops Eve at
60
+ the access expiration even if the launcher disappears.
61
+ At expiry, the local composer or reconnect menu closes and the launcher explains
62
+ that the session time limit was reached. It does not renew access or replay a
63
+ message. Resume d3k to reopen the same conversation with renewed access.
64
+
65
+ Try these interactions:
66
+
67
+ 1. Ask “Inspect the current browser and tell me its main heading.” Ordinary
68
+ sandbox tools run without per-command approval. Tools with their own explicit
69
+ approval policy still use Eve's keyboard panel; press **y** or **n**.
70
+ 2. Paste a local image path normally, including CleanShot's shell-escaped paths.
71
+ It becomes `[Image #1]` in the composer and its bytes upload with your message.
72
+ For a binary clipboard image, press **Ctrl+V**. Neither requires `/paste`.
73
+ Existing draft text stays in place. Cmd+V behavior depends on the terminal app;
74
+ a terminal must emit an image file path, otherwise use Ctrl+V.
75
+ 3. Ask “Run `sleep 20; echo finished` once.” Enter `/detach`,
76
+ wait, then press Enter at the reconnect menu. It resumes the same conversation
77
+ without submitting the prompt again.
78
+ 4. Enter `/detach`, then press **Ctrl-C** at the reconnect prompt to exit and remove its model
79
+ key and service route. The existing d3k app and browser remain running.
80
+
81
+ Interactive terminals use Eve's actual composer, transcript renderer, and approval
82
+ panels from pinned Eve 1.0.0-rc.6 internals. A d3k adapter supplies a fixed remote
83
+ session and local image uploads. This is not the full Eve CLI runner: its other
84
+ setup commands are unavailable; model switching uses Eve’s dynamic model API. Image attachments use numbered markers,
85
+ not inline pixel previews. Noninteractive IO retains the plain client fallback.
86
+ Native internal imports must be revalidated before upgrading Eve.
87
+ The launcher appends the shared connected-session d3k skill to Eve's instructions,
88
+ including the actual remote checkout and app URL. Its tools run in the sandbox;
89
+ the native terminal UI runs locally. UI edits should be checked against the
90
+ already-running dev server through the paired browser before reporting completion.
91
+ Temporary Bun installs exempt only `eve` from an inherited minimum-release-age
92
+ delay so the pinned RC can be installed immediately; global configuration stays unchanged.
93
+
94
+ For requested pushes and PRs, Eve can use the remote runtime's `github` command
95
+ through the paired companion. It reaches the same linked-repository Git Data/PR
96
+ APIs as desktop `sandbox_github`, using the laptop's existing `gh` authentication.
97
+ No GitHub credential enters the sandbox. This fallback requires the companion
98
+ to remain connected; it does not provision managed Git credentials in the VM.
99
+
100
+ Keep the Eve launcher and d3k open while trying it. Exiting the launcher normally
101
+ stops its Eve service; a later invocation starts a fresh Eve conversation. This
102
+ launcher does not implement phone handoff or d3k's eventual laptop-close lifecycle.
103
+
104
+ For a noninteractive live setup/model/cleanup check, add `--check`:
105
+
106
+ ```sh
107
+ bun scripts/eve/launch.mjs --resume <d3k-saved-session-id> --check
108
+ ```
109
+
110
+ ## Model
111
+
112
+ New sessions default to **Claude Haiku 5.5 with thinking off**. In a terminal,
113
+ `/model` opens the native picker. `/model haiku`, `/model mini`, `/model flash`,
114
+ and `/model sonnet` switch directly; `/model current` reports the selection.
115
+ The choices are Haiku 5.5, GPT 5.4 Mini, Gemini 3.8 Flash, and Sonnet 4.6.
116
+ All support image input and tool use according to AI Gateway's model catalogue.
117
+
118
+ The local selection travels as authenticated request metadata. Eve's dynamic
119
+ model callback selects it for subsequent model calls without clearing the
120
+ conversation or asking the model to interpret a slash command. Detaching and
121
+ reconnecting within the same launcher preserves the choice. `settings.mjs`
122
+ contains the validated choices and reasoning levels; the UI does not control
123
+ Gateway budgets, credentials, or approvals.
124
+
125
+ ## Run the verification
126
+
127
+ From the repository root, with Node 24+ and Bun:
128
+
129
+ ```sh
130
+ node scripts/eve/verify.mjs
131
+ ```
132
+
133
+ The verifier installs pinned `eve@1.0.0-rc.6`, `ai@7.0.159`, and `zod@4.6.7` in
134
+ a temporary directory. It builds and starts a real Eve service with a deterministic
135
+ test model. It uses no model credentials, Chrome, Portless, or Vercel resources,
136
+ and removes the service and temporary checkout afterward.
137
+
138
+ To reuse an existing installation of those versions:
139
+
140
+ ```sh
141
+ D3K_EVE_PACKAGE_ROOT=/absolute/path/to/node_modules/eve node scripts/eve/verify.mjs
142
+ ```
143
+
144
+ The verification checks:
145
+
146
+ - Unauthenticated creation, continuation, and conversation reads return 401.
147
+ - A client process exits during a shell command; the command finishes in the
148
+ existing checkout while no client is observing it.
149
+ - A new client replays that conversation, with exactly one original prompt.
150
+ - A new client recovers a pending approval; answering runs the waiting tool once.
151
+ - A local PNG reaches the model as inline image content.
152
+ - The local terminal client reattaches, uploads an image, and detaches without
153
+ creating another conversation.
154
+ - Cancellation terminates the command process group, including a TERM-resistant
155
+ child.
156
+
157
+ These are integration checks of Eve's actual service, provider, and public SDK.
158
+ The deterministic model does not establish coding quality or real-provider vision
159
+ quality. This deterministic verifier does not exercise macOS clipboard reading,
160
+ live Vercel routing, browser re-pairing, or a phone UI.
161
+
162
+ ## Live Sandbox validation — November 5, 2026
163
+
164
+ The uncommitted scaffold was uploaded directly into a separate service directory
165
+ in a fresh Vercel Sandbox for `vercel-labs/dev3000-www`. No main push, npm release,
166
+ or website deployment was needed. Eve ran beside the existing checkout and dev
167
+ server, using a project-scoped Gateway key with a $1 non-renewing limit and a
168
+ 20-minute expiration. The real model was `anthropic/claude-sonnet-4.6`.
169
+
170
+ The following live checks passed:
171
+
172
+ - Eve served HTTPS through an additional Sandbox route. Unauthenticated session
173
+ creation, history streaming, and continuation each returned 401.
174
+ - A separate local client recovered a pending approval, approved one exact shell
175
+ command, and exited. With no client observing that conversation, the command
176
+ slept for 20 seconds and appended one marker to a temporary file. Reconnecting
177
+ recovered the same conversation, one original user prompt, one tool call, and
178
+ the completed assistant reply. The marker appeared exactly once. The second
179
+ admitted delivery was the approval answer, not a repeated prompt.
180
+ - A synthetic 64×64 red PNG generated on the laptop reached the remote vision
181
+ model, which answered “Red”. The actual terminal client's `/attach` flow also
182
+ uploaded it, received “red”, and exited successfully with `/detach`.
183
+ - Eve's approved shell tool invoked the existing d3k runtime's `status` and
184
+ `browser snapshot -i`. It reached the paired local Chrome and correctly reported
185
+ the page heading: “Your coding agent should see what your app is doing.”
186
+
187
+ An initial d3k launch failed because the test's custom Next command hardcoded
188
+ port 3000, colliding with d3k's sandbox proxy. Resuming the same sandbox with a
189
+ command that honors the supplied `PORT` restored the app and local browser:
190
+
191
+ ```sh
192
+ --command 'bun x next dev --hostname 0.0.0.0 --port "$PORT"'
193
+ ```
194
+
195
+ After validation, the test Eve service was stopped, its public route removed,
196
+ and its Gateway key removed. The d3k app and local Chrome connection were left
197
+ running. The installed local Vercel CLI used `ai-gateway api-keys remove`; it did
198
+ not support the `revoke` spelling.
199
+
200
+ This validates client process exit/reconnect, real-provider image delivery, and
201
+ remote Eve controlling local Chrome. It does **not** validate actual laptop sleep,
202
+ network loss during a tool call, browser bridge re-pairing while Eve is active,
203
+ another physical device, clipboard `/paste`, or a phone UI. Normal d3k stop still
204
+ stops owned compute. The detach/resume integration below remains required before
205
+ advertising laptop-close background execution as a product feature. The rc.2
206
+ server restart limitation below remains unresolved.
207
+
208
+ ## Important finding: server restart recovery
209
+
210
+ Client disconnection and Eve server replacement are different operations.
211
+ Client reconnect and approval recovery pass while the Eve service stays alive.
212
+ Repeated tests of **restarting the Eve service itself immediately after a tool
213
+ approval pauses** are unreliable in this configuration on rc.2: the new service
214
+ can replay the approval and accept its answer, but execution sometimes does not
215
+ continue within 60 seconds. One run succeeded; several did not. The cause has
216
+ not been isolated to Eve, its local Workflow world, or shutdown timing.
217
+
218
+ The optional reproducer exercises this additional case and may fail:
219
+
220
+ ```sh
221
+ D3K_EVE_TEST_RESTART=1 D3K_EVE_KEEP_FIXTURE=1 node scripts/eve/verify.mjs
222
+ ```
223
+
224
+ Do not describe arbitrary process restart recovery as proven. Laptop sleep does
225
+ not require restarting Eve. The first integrated mode should retain the same
226
+ remote process on detach and reconnect. Also pin Eve for the lifetime of each
227
+ conversation: its documentation says changing Eve versions strands existing
228
+ self-hosted sessions.
229
+
230
+ ## Components
231
+
232
+ - `agent/` is a real-agent scaffold. It uses Eve's default shell/file tools,
233
+ runs ordinary tools without per-command approval and supplies d3k browser instructions.
234
+ - `connection.mjs` implements Eve's custom sandbox connection over an existing
235
+ host filesystem and process tree. It is **not** a security sandbox. It belongs
236
+ inside the Vercel Sandbox that already isolates execution. Ending a conversation
237
+ never deletes the checkout or stops the shared dev server.
238
+ - `client.mjs` is a small local terminal using public `eve/client` APIs. It can
239
+ attach to a fixed session ID, replay history, answer pending interactions, queue
240
+ images, cancel a turn, and detach. It writes no local conversation history.
241
+ - `fixture-agent.ts` replaces the real model only inside the verifier's temporary
242
+ service. It is not part of a real-agent deployment.
243
+
244
+ The custom provider deliberately rejects authored sandbox seed files rather than
245
+ copying them over an existing checkout. Adding Eve's code extension requires
246
+ handling its skill/template setup before mounting it; this integration uses the default
247
+ tools. All conversations intentionally share this one project checkout, so edits
248
+ from simultaneous sessions are not isolated from each other.
249
+
250
+ ## Run against a prepared service
251
+
252
+ Place `agent/`, `settings.mjs`, and `connection.mjs` together in a service directory **inside the
253
+ already isolated remote VM**, separate from the project checkout. Install the
254
+ pinned dependencies above there with Bun. Configure the following server env:
255
+
256
+ | Variable | Purpose |
257
+ | ------------------------- | --------------------------------------------------------------------------------------- |
258
+ | `D3K_EVE_WORKDIR` | Absolute existing project checkout |
259
+ | `D3K_EVE_ISOLATED_HOST=1` | Explicit acknowledgement that the host is already isolated; this flag adds no isolation |
260
+ | `D3K_EVE_TOKEN` | Random per-sandbox bearer token, at least 32 characters |
261
+ | `D3K_EVE_EXPIRES_AT` | Token expiration as a Unix timestamp in milliseconds |
262
+ | `AI_GATEWAY_API_KEY` | Project-scoped, expiring, budget-limited Gateway key |
263
+
264
+ Build with `node node_modules/eve/bin/eve.js build`, then supervise
265
+ `node node_modules/eve/bin/eve.js start --host 0.0.0.0 --port 3001 --no-schedules`.
266
+ Expose it through authenticated HTTPS. Forward `/eve/` and
267
+ `/.well-known/workflow/` without rewriting their paths. Preserve the service's
268
+ `.eve/.workflow-data` on the sandbox disk. Do not send Vercel management tokens
269
+ or laptop harness credentials to the service.
270
+
271
+ The **local** client needs an existing Eve installation. Set
272
+ `D3K_EVE_PACKAGE_ROOT` to that package directory, `D3K_EVE_URL` to the HTTPS service
273
+ origin, and `D3K_EVE_TOKEN` through the environment; then run:
274
+
275
+ ```sh
276
+ node scripts/eve/client.mjs
277
+ node scripts/eve/client.mjs --session <printed-session-id>
278
+ ```
279
+
280
+ `/attach /absolute/path.png` queues a local image. On macOS, **Ctrl+V** reads and
281
+ attaches a PNG from the local clipboard; `/paste` remains a command alternative.
282
+ Neither captures a screenshot. Send a
283
+ message to upload the queued image. `/answer <interaction-id> <option-id or text>`
284
+ answers a pending request. `/cancel` cancels execution; `/detach` or Ctrl+C leaves
285
+ it running remotely. Interactive terminals use Eve’s native renderer.
286
+
287
+ ## Conversation resume and remaining lifecycle work
288
+
289
+ `d3k --resume <id>` reads the saved Eve conversation ID from the sandbox, restarts
290
+ Eve with fresh temporary credentials, verifies that the saved history is readable,
291
+ and attaches the local native UI to that exact conversation. History and discovery
292
+ metadata stay remote. The service directory is stable per d3k session rather than
293
+ per build hash, so rebuilding does not switch conversation storage. Existing older
294
+ sessions adopt their most recent remote conversation; separate older conversations
295
+ are retained on disk and are not merged. A missing saved conversation produces an
296
+ error instead of silently creating a replacement or replaying a prompt.
297
+
298
+ Stopping the launcher still stops its service and owned compute. Continuing an
299
+ active agent turn while the laptop is closed needs separate detach/stop lifecycle
300
+ work, bounded Gateway access, and authenticated connection recovery from another
301
+ device. The current resume support preserves history; it does not promise that an
302
+ interrupted command completed or automatically replay it. Inspect remote state
303
+ before retrying an uncertain mutation.
304
+
305
+ The verification fixture checks saved conversation replay and model history after
306
+ service stop/rebuild/restart, plus pending approval recovery and exactly-once tool
307
+ execution. Full laptop network-loss and cross-device browser handoff remain future
308
+ work.
309
+
310
+ A phone can use the same Eve API through a future web client. This terminal
311
+ client does not provide a phone UI. The macOS d3k companion cannot automatically turn
312
+ iPhone Safari into an automated Chrome/CDP endpoint. Another supported desktop
313
+ can attach its own companion and browser profile; transferring authenticated
314
+ Chrome profiles to the remote sandbox is a separate problem and is not required
315
+ for continued coding.
316
+
317
+ Sandbox timeout and Gateway expiry bound background work. Persisted history on a
318
+ sandbox filesystem is not a promise of unlimited compute or permanent storage.
319
+
320
+ ## Browser and security implications
321
+
322
+ This approach needs no public raw CDP endpoint and no UDP ingress. Retain d3k's
323
+ authenticated bridge, isolated browser profile, and scoped Gateway credentials.
324
+ The Eve API grants project command execution: use a distinct expiring token for
325
+ each sandbox, HTTPS, and owner authorization when obtaining it on another device.
326
+ The service strips service credentials from shell-command environments, but
327
+ the agent and service share the VM/Unix identity; that is not a credential
328
+ isolation boundary.
329
+
330
+ The laptop companion uses the installed standard Google Chrome executable with
331
+ its existing per-project automation profile. The macOS confinement policy still
332
+ blocks unrelated files, system clipboard access, and the normal keychain.
333
+ Chrome updates remain managed by the user's installation or IT. The everyday
334
+ browser profile is separate and is not exposed to remote automation.
335
+
336
+ References: [Eve self-hosting](https://eve.dev/docs/guides/deployment/self-hosting),
337
+ [custom providers](https://eve.dev/docs/sandbox/custom-providers),
338
+ [sessions and streaming](https://eve.dev/docs/concepts/sessions-runs-and-streaming),
339
+ [terminal UI](https://eve.dev/docs/guides/dev-tui),
340
+ [self-hosted operations](https://eve.dev/docs/guides/deployment/self-hosted-operations),
341
+ and [Mosh](https://mosh.org).
@@ -0,0 +1,12 @@
1
+ import { defineAgent } from "eve"
2
+ import { defineDynamic } from "eve/models"
3
+ import { resolveModel } from "../settings.mjs"
4
+
5
+ export default defineAgent({
6
+ // The authenticated client selects the model; ordinary tools have no extra approval gate.
7
+ model: defineDynamic((ctx) => {
8
+ const requested = ctx.session.auth.current?.attributes.d3kModel
9
+ const selected = resolveModel(typeof requested === "string" ? requested : undefined)
10
+ return { model: selected.id, reasoning: selected.reasoning, modelContextWindowTokens: selected.context }
11
+ })
12
+ })
@@ -0,0 +1,23 @@
1
+ import { timingSafeEqual } from "node:crypto"
2
+ import { eveChannel } from "eve/channels/eve"
3
+ import { EVE_MODEL, EVE_MODELS, MODEL_HEADER } from "../../settings.mjs"
4
+
5
+ export default eveChannel({
6
+ auth(request) {
7
+ const token = process.env.D3K_EVE_TOKEN
8
+ if (!token || token.length < 32) throw new Error("Configure a random per-sandbox D3K_EVE_TOKEN")
9
+ const expiresAt = Number(process.env.D3K_EVE_EXPIRES_AT)
10
+ if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) return null
11
+ const expected = Buffer.from(`Bearer ${token}`)
12
+ const supplied = Buffer.from(request.headers.get("authorization") || "")
13
+ if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) return null
14
+ const model = request.headers.get(MODEL_HEADER) || EVE_MODEL
15
+ if (!EVE_MODELS.some((candidate) => candidate.id === model)) return null
16
+ return {
17
+ authenticator: "d3k-sandbox",
18
+ principalId: "owner",
19
+ principalType: "user",
20
+ attributes: { d3kModel: model }
21
+ }
22
+ }
23
+ })
@@ -0,0 +1,53 @@
1
+ You are a coding agent running beside the user's code in an existing d3k sandbox.
2
+ Use the existing checkout and dev server. Do not provision another sandbox.
3
+ Only the terminal UI is local; your shell and file tools execute in the sandbox.
4
+ Your shell starts in the project checkout. Run pwd to find its actual path;
5
+ never guess /workspace. Read that checkout's AGENTS.md before editing.
6
+
7
+ For a small code change, minimize serial tool calls. Search the relevant source
8
+ with rg when available; avoid dependencies, generated output, and unrelated files.
9
+ Combine locating a match and reading its surrounding context when practical.
10
+ Read the necessary file range once and prefer a narrow edit over returning the
11
+ whole unchanged file. Check the resulting diff and run project-required checks.
12
+ After a user-visible UI change, verify the changed page in the paired browser
13
+ before reporting completion. d3k already started the dev server in the sandbox;
14
+ you do not need to start it yourself to check the page. Use the connected-session
15
+ d3k skill below to inspect status, view the page and read events. State what you
16
+ actually checked. If verification fails, report the command and actual error;
17
+ do not infer that the dev server is absent because you did not launch it.
18
+
19
+ Images attached by the user arrive as image content alongside [Image #n] markers.
20
+ Inspect that content directly. A laptop file path is not a sandbox file path;
21
+ do not try to read /Users/... in the sandbox.
22
+
23
+ The user's local Chrome is paired through d3k. Use
24
+ `/tmp/d3k-tools/node_modules/.bin/d3k-runtime status` and
25
+ `/tmp/d3k-tools/node_modules/.bin/d3k-runtime browser snapshot -i` to inspect it.
26
+ When the companion disconnects, browser testing is unavailable. Continue work
27
+ that does not require that browser. Leave browser-dependent checks pending until
28
+ the companion reconnects. Do not launch another browser as a fallback.
29
+
30
+ A user request for a PR authorizes committing the intended changes, publishing
31
+ a feature branch and opening a draft PR without another confirmation. Follow the
32
+ shared d3k Pull requests workflow below. Commit in this checkout. d3k supplies
33
+ and persists the user's configured Git identity in this repository. Check
34
+ `git var GIT_AUTHOR_IDENT` and `git var GIT_COMMITTER_IDENT` before reporting a
35
+ missing identity: Git also accepts environment-supplied author/committer values,
36
+ so empty `git config user.name` or `user.email` alone is not a blocker. If the
37
+ effective identities are available, commit without asking the user to repeat them.
38
+ After committing the intended files on a feature branch, publish from the project root:
39
+ `/tmp/d3k-tools/node_modules/.bin/d3k-runtime publish --base main --title "Describe the change" --body-file /tmp/pr-body.md`
40
+ Use the actual base branch and write the PR description file remotely first.
41
+ This command uploads the committed objects, preserves exact message newlines and
42
+ timestamps, verifies SHAs before updating the branch, and creates a draft PR or
43
+ returns the existing open PR. Do not construct Git Data API requests manually or
44
+ try an unauthenticated push first. Untracked files and unstaged changes stay out.
45
+ GitHub credentials stay on the laptop; publishing requires its connected companion.
46
+ On a timeout, rerun the same publisher: it checks GitHub state before writing and
47
+ recovers successful ref/PR writes whose responses were lost. Never force-push,
48
+ ask for tokens or run gh auth login in the sandbox. Report a concrete unsupported
49
+ object or authentication error instead of guessing at commit metadata.
50
+
51
+ Read the checkout's AGENTS.md before changing project code. Perform external
52
+ side effects when the user requests them; ask if authorization is missing.
53
+ Do not claim browser validation succeeded while disconnected.
@@ -0,0 +1,34 @@
1
+ import { stat } from "node:fs/promises"
2
+ import { defineSandbox } from "eve/sandbox"
3
+ import { defineSandboxProvider } from "eve/sandbox/provider"
4
+ import { connect } from "../connection.mjs"
5
+
6
+ const ExistingCheckout = defineSandboxProvider({
7
+ name: "d3k-existing-checkout",
8
+ environment() {
9
+ const root = process.env.D3K_EVE_WORKDIR
10
+ if (!root) throw new Error("Set D3K_EVE_WORKDIR to the existing sandbox checkout")
11
+ if (process.env.D3K_EVE_ISOLATED_HOST !== "1")
12
+ throw new Error("This provider must run inside an already isolated host")
13
+ return {
14
+ async prepare(ctx) {
15
+ // This provider intentionally has no template. Do not populate over the user's checkout.
16
+ if (!ctx.isEmpty) throw new Error("Use the existing checkout; authored sandbox seed files are unsupported")
17
+ return { version: 1 }
18
+ },
19
+ async start() {
20
+ if (!(await stat(root)).isDirectory()) throw new Error("The checkout is missing")
21
+ return { connection: connect(root), state: { root } }
22
+ },
23
+ async resume(_ctx, _artifact, state) {
24
+ if (state.root !== root) throw new Error("Refusing to move a conversation to another checkout")
25
+ if (!(await stat(root)).isDirectory()) throw new Error("The original checkout is missing")
26
+ return connect(root)
27
+ },
28
+ async onSessionEnd() {}
29
+ }
30
+ }
31
+ })
32
+
33
+ export const environment = ExistingCheckout.environment()
34
+ export default defineSandbox(() => environment.open())
@@ -0,0 +1,18 @@
1
+ import { createHash } from "node:crypto"
2
+
3
+ export function eveBuildFingerprint(files) {
4
+ const hash = createHash("sha256")
5
+ for (const { path, content } of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
6
+ const bytes = Buffer.from(content)
7
+ hash.update(JSON.stringify([path, bytes.length])).update(bytes)
8
+ }
9
+ return hash.digest("hex")
10
+ }
11
+
12
+ // The marker is written only after install and build both succeed.
13
+ export const eveBuildCacheProbe = `
14
+ const fs = require('node:fs');
15
+ const expected = process.argv[1];
16
+ process.exit(fs.existsSync('node_modules/eve/bin/eve.js') && fs.existsSync('.eve') &&
17
+ fs.existsSync('.d3k-build.sha256') && fs.readFileSync('.d3k-build.sha256', 'utf8') === expected ? 0 : 10);
18
+ `
@@ -0,0 +1,32 @@
1
+ import { spawnSync } from "node:child_process"
2
+ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
3
+ import { tmpdir } from "node:os"
4
+ import { join } from "node:path"
5
+ import { expect, it } from "vitest"
6
+ import { eveBuildCacheProbe, eveBuildFingerprint } from "./build-cache.mjs"
7
+
8
+ it("reuses completed Eve builds and invalidates changed sources, versions and missing artifacts", () => {
9
+ const root = mkdtempSync(join(tmpdir(), "d3k-eve-cache-"))
10
+ try {
11
+ const files = [
12
+ { path: "agent/agent.ts", content: Buffer.from("agent source") },
13
+ { path: "package.json", content: Buffer.from('{"eve":"1"}') }
14
+ ]
15
+ const fingerprint = eveBuildFingerprint(files)
16
+ expect(eveBuildFingerprint([...files].reverse())).toBe(fingerprint)
17
+ const probe = (hash = fingerprint) =>
18
+ spawnSync(process.execPath, ["-e", eveBuildCacheProbe, hash], { cwd: root }).status
19
+ mkdirSync(join(root, "node_modules/eve/bin"), { recursive: true })
20
+ mkdirSync(join(root, ".eve"))
21
+ writeFileSync(join(root, "node_modules/eve/bin/eve.js"), "")
22
+ expect(probe()).toBe(10)
23
+ writeFileSync(join(root, ".d3k-build.sha256"), fingerprint)
24
+ expect(probe()).toBe(0)
25
+ expect(probe(eveBuildFingerprint([{ ...files[0], content: Buffer.from("updated agent") }, files[1]]))).toBe(10)
26
+ expect(probe(eveBuildFingerprint([files[0], { ...files[1], content: Buffer.from('{"eve":"2"}') }]))).toBe(10)
27
+ rmSync(join(root, ".eve"), { recursive: true })
28
+ expect(probe()).toBe(10)
29
+ } finally {
30
+ rmSync(root, { recursive: true, force: true })
31
+ }
32
+ })