@acryldev/agent-panel 0.0.0-stage → 0.1.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 (50) hide show
  1. package/LICENSE +21 -0
  2. package/client/describe.ts +101 -0
  3. package/client/driver-pick.ts +22 -0
  4. package/client/frame.ts +51 -0
  5. package/client/main.ts +707 -0
  6. package/client/markdown.ts +219 -0
  7. package/headless.ts +220 -0
  8. package/index.ts +523 -0
  9. package/launch.ts +67 -0
  10. package/lib/client/describe.ts +101 -0
  11. package/lib/client/driver-pick.ts +22 -0
  12. package/lib/client/frame.ts +51 -0
  13. package/lib/client/main.ts +707 -0
  14. package/lib/client/markdown.ts +219 -0
  15. package/lib/headless-B_RGxZFU.js +252 -0
  16. package/lib/headless-B_RGxZFU.js.map +1 -0
  17. package/lib/headless.js +2 -0
  18. package/lib/index.js +562 -0
  19. package/lib/index.js.map +1 -0
  20. package/lib/mount.js +25 -0
  21. package/lib/mount.js.map +1 -0
  22. package/lib/registry.js +13 -0
  23. package/lib/registry.js.map +1 -0
  24. package/lib/types/headless.d.ts +22 -0
  25. package/lib/types/index.d.ts +22 -0
  26. package/lib/types/launch.d.ts +18 -0
  27. package/lib/types/mount.d.ts +12 -0
  28. package/lib/types/registry.d.ts +10 -0
  29. package/lib/types/tsdown.config.d.ts +2 -0
  30. package/lib/types/visitors.d.ts +82 -0
  31. package/mount.ts +27 -0
  32. package/package.json +62 -3
  33. package/plugin.json +28 -0
  34. package/registry.ts +17 -0
  35. package/scripts/copy-assets.mjs +5 -0
  36. package/test/client-guards.test.ts +13 -0
  37. package/test/describe.test.ts +105 -0
  38. package/test/driver-pick.test.ts +24 -0
  39. package/test/frame.test.ts +35 -0
  40. package/test/launch.test.ts +90 -0
  41. package/test/markdown.test.ts +79 -0
  42. package/test/panel-client.test.ts +150 -0
  43. package/test/panel.test.ts +534 -0
  44. package/test/socket.test.ts +209 -0
  45. package/test/visitors.test.ts +112 -0
  46. package/test/why.test.ts +61 -0
  47. package/tsconfig.json +21 -0
  48. package/tsdown.config.ts +23 -0
  49. package/visitors.ts +231 -0
  50. package/README.md +0 -3
package/index.ts ADDED
@@ -0,0 +1,523 @@
1
+ /**
2
+ * The built-in agent (spec 049 slice 14): a chat panel inside the running app. The person says what they want; the app's own agent (`driver: 'agent'`) or a coding
3
+ * agent started in the app folder (`'claude'`, `'codex'`, `'pi'`) builds it through the door, and when a plugin was installed or removed the page reloads, so the new feature
4
+ * shows with no restart. The drivers are entries of the `drivers` service this plugin provides (`@acryldev/drivers`): chat drivers here, and other plugins (`driver-pty`) add more.
5
+ *
6
+ * - A middleware appends one script tag (`/api/agent-panel/panel.js`) to every HTML response of the routes mounted after it, so no page is edited.
7
+ * - `GET /api/agent-panel/session` gives the page the drivers it may use and a token; `POST /api/agent-panel/ask` runs one message and answers server-sent events:
8
+ * `text`, `tool`, `change`, `done`, `error`.
9
+ * - Only the app's own page may ask (a same-origin request carrying the token), one run at a time, and every ask is written to `.acryl/audit/agent-panel.jsonl`.
10
+ * - Who asks (`visitors.ts`): in development one person, the owner, whose pages share one token and one run. As the Assistant each visitor has their own token, run and
11
+ * replay, named by an HttpOnly cookie: no visitor sees, follows or stops another's run, and the asks are bounded (per visitor per hour, per day, runs at once).
12
+ * - The routes live under the app's mount: the root of the app's own server, or the frame's prefix (`/app`) when the frame hosts it, where the host's own
13
+ * `/api` routes would otherwise answer first. The row's `mount` config names it.
14
+ * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`, except as the Assistant (`assistant: true`): then it runs in production too,
15
+ * docked open on the right, with the app's own agent only. The app gives that agent the page tools alone and a page-only door, so it uses the app for a visitor and
16
+ * cannot change it (src/app.ts, `ACRYL_ASSISTANT=on`). In the ACRYL frame's canvas the panel follows the frame's view: Build hides it, and Preview shows it only as
17
+ * the Assistant and only when the app's production environment names one (`assistantInProduction` in the session).
18
+ */
19
+ import { appendFileSync, mkdirSync } from 'node:fs'
20
+ import { dirname, join } from 'node:path'
21
+ import type {} from '@acryldev/agent'
22
+ import type { ChatDriver, Driver } from '@acryldev/drivers'
23
+ import type {} from '@acryldev/extensions'
24
+ import { clientModules } from '@acryldev/node-server/client-modules'
25
+ import { Acryl, type MiddlewareHandler } from '@acryldev/router'
26
+ import { streamSSE, type UpgradeWebSocket } from '@acryldev/router/helpers'
27
+ import { pageAuthority } from '@acryldev/router/middleware'
28
+ import type { Context } from '@deepseek-ai/cordis'
29
+ import {
30
+ agentDriver,
31
+ availableHeadless,
32
+ type HeadlessName,
33
+ headlessDriver,
34
+ whyNotChat,
35
+ } from './headless.ts'
36
+ import { mountedBase, mountedPrefix } from './mount.ts'
37
+ import { provideDrivers } from './registry.ts'
38
+ import { type AssistantLimits, type Visitor, Visitors } from './visitors.ts'
39
+
40
+ export type {
41
+ ChatDriver,
42
+ ChatEvent,
43
+ Driver,
44
+ Drivers,
45
+ TerminalDriver,
46
+ TerminalSession,
47
+ } from '@acryldev/drivers'
48
+
49
+ export const name = 'agent-panel'
50
+ export const inject = ['router', 'agent', 'extensions', 'appInstance']
51
+
52
+ /** The panel's own routes, fixed relative to the app's mount. */
53
+ const PANEL_PATH = '/api/agent-panel'
54
+
55
+ /** The one driver the Assistant offers its visitors: the app's own agent, held to the page tools. */
56
+ const ASSISTANT_DRIVER = 'agent'
57
+
58
+ /** The slice of the door the panel uses; the door is optional (it is a development plugin, and a different row). */
59
+ interface DoorPort {
60
+ driveFor(windowId: string): () => void
61
+ }
62
+ const CLIENT_DIR = join(import.meta.dirname, 'client')
63
+
64
+ export interface PanelConfig {
65
+ /** Headless coding agents to offer besides the app's own agent; default: the ones found on the machine. */
66
+ drivers?: readonly HeadlessName[]
67
+ /**
68
+ * The URL prefix the app is mounted at: empty on the app's own server, `/app` when the ACRYL frame hosts it (the same prefix `makeApp` and
69
+ * `routerHttp.mount` take). The panel's routes, script tag and client live under it, so they belong to the app and are served wherever it is.
70
+ */
71
+ mount?: string
72
+ /** The Assistant: a production panel for the app's visitors, with the app's own agent only (no coding agent, no terminal). Runs with `NODE_ENV=production`. */
73
+ assistant?: boolean
74
+ /** The Assistant's limits on what visitors may ask (`visitors.ts` has the defaults); the development panel has none but one run at a time. */
75
+ limits?: AssistantLimits
76
+ }
77
+
78
+ /** Whether the page came over https (directly, or through a proxy that says so): the visitor cookie is then Secure. */
79
+ const overHttps = (url: string, headers: Headers): boolean =>
80
+ url.startsWith('https:') || headers.get('x-forwarded-proto')?.split(',')[0]?.trim() === 'https'
81
+
82
+ /** The panel's routes under a checked mount: empty, or an absolute path such as `/app` with no trailing slash (the `routerHttp.mount` rule). */
83
+ const panelPrefix = (mount: string | undefined): string =>
84
+ mountedPrefix(mount, PANEL_PATH, 'agent-panel')
85
+
86
+ /** Whether a request comes from the app's own page: a browser says so itself (`Sec-Fetch-Site: same-origin`), or the Origin is the Host. */
87
+ export function fromOwnPage(headers: Headers): boolean {
88
+ const site = headers.get('sec-fetch-site')
89
+ if (site !== null) return site === 'same-origin'
90
+ const origin = headers.get('origin')
91
+ const host = headers.get('host')
92
+ return origin !== null && host !== null && new URL(origin).host === host
93
+ }
94
+
95
+ export function apply(ctx: Context, config: PanelConfig = {}): void {
96
+ const assistant = config.assistant === true
97
+ if (process.env.ACRYL_DOOR === 'off' || (process.env.NODE_ENV === 'production' && !assistant))
98
+ return
99
+ const PREFIX = panelPrefix(config.mount)
100
+ // The panel's routes mount at the app's own mount and keep the fixed path inside (`/app` + `/api/agent-panel/...`); the frame's router prefixes the
101
+ // mount path itself, so a prefix inside the routes too would become `/app/app/...`. PREFIX stays absolute for the page's script tag and client URLs.
102
+ const MOUNT = mountedBase(config.mount, 'agent-panel')
103
+ const root = ctx.appInstance.root
104
+ const visitors = new Visitors<Run>({
105
+ shared: !assistant,
106
+ ...(config.limits === undefined ? {} : { limits: config.limits }),
107
+ })
108
+ /** The visitor of a request that must carry its token, or `undefined` when it does not come from the app's own page with the right one. */
109
+ const caller = (headers: Headers, presented: unknown): Visitor<Run> | undefined => {
110
+ if (!fromOwnPage(headers)) return undefined
111
+ const visitor = visitors.of(headers.get('cookie'))
112
+ return visitors.accepts(visitor, presented) ? visitor : undefined
113
+ }
114
+ const auditFile = join(root, '.acryl', 'audit', 'agent-panel.jsonl')
115
+ const audit = (entry: Record<string, unknown>): void => {
116
+ try {
117
+ mkdirSync(dirname(auditFile), { recursive: true })
118
+ appendFileSync(auditFile, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`)
119
+ } catch {
120
+ // The audit never stops a run.
121
+ }
122
+ }
123
+ // The Assistant's visitors use the app's own agent and nothing else: no plugin's driver (a terminal, a coding agent) is open to them, whatever plugins the app mounts.
124
+ const registry = provideDrivers(
125
+ ctx,
126
+ (headers) => !assistant && caller(headers, headers.get('x-agent-panel-token')) !== undefined,
127
+ )
128
+ const offered = (): Driver[] =>
129
+ registry.list().filter((driver) => !assistant || driver.name === ASSISTANT_DRIVER)
130
+ ctx.effect(() => registry.register(agentDriver(ctx)))
131
+ if (!assistant)
132
+ for (const program of availableHeadless(config.drivers))
133
+ ctx.effect(() => registry.register(headlessDriver(program, root)))
134
+
135
+ const tag = `<script type="module" src="${PREFIX}/panel.js"></script>`
136
+ const addScript = async (c: { res: Response }, next: () => Promise<void>): Promise<void> => {
137
+ await next()
138
+ if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) return
139
+ const html = await c.res.text()
140
+ if (html.includes(`${PREFIX}/panel.js`)) {
141
+ c.res = new Response(html, c.res)
142
+ return
143
+ }
144
+ const headers = new Headers(c.res.headers)
145
+ headers.delete('content-length')
146
+ c.res = new Response(
147
+ html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag,
148
+ { status: c.res.status, headers },
149
+ )
150
+ }
151
+ // The script tag on every HTML page the app answers, whenever the plugin that serves the page was mounted (a plugin an agent built loads at boot, before this one, after a restart).
152
+ // An app whose router copy is older has no `wrap`: the tag is then added to the pages of the routes mounted after this plugin only.
153
+ const router = ctx.router as unknown as { wrap?: (middleware: typeof addScript) => unknown }
154
+ const wrapped = typeof router.wrap === 'function'
155
+ if (wrapped) router.wrap?.(addScript)
156
+ const app = new Acryl()
157
+ .use('*', async (c, next) => {
158
+ if (wrapped) return next()
159
+ await addScript(c, next)
160
+ })
161
+ .get(`${PANEL_PATH}/panel.js`, (c) =>
162
+ c.body(
163
+ `import { start } from '${PREFIX}/client/main.ts'\nstart(${JSON.stringify(PREFIX)})\n`,
164
+ 200,
165
+ {
166
+ 'content-type': 'text/javascript; charset=utf-8',
167
+ 'cache-control': 'no-cache',
168
+ },
169
+ ),
170
+ )
171
+ .route(`${PANEL_PATH}/client`, clientModules({ root: CLIENT_DIR, mount: `${PREFIX}/client` }))
172
+ .get(`${PANEL_PATH}/session`, (c) => {
173
+ if (!fromOwnPage(c.req.raw.headers))
174
+ return c.json({ error: "only the app's own page may use the panel" }, 403)
175
+ const { visitor, setCookie } = visitors.session(
176
+ c.req.header('cookie'),
177
+ overHttps(c.req.url, c.req.raw.headers),
178
+ )
179
+ if (setCookie !== undefined) c.header('set-cookie', setCookie)
180
+ return c.json({
181
+ token: visitor.token,
182
+ ...(assistant ? { assistant: true } : {}),
183
+ // The frame's Preview shows the app as production would. This is the fact that lets its page show the Assistant when the app's production
184
+ // environment names it (ACRYL_ASSISTANT=on), even though the frame host itself runs in development and never mounts the Assistant row.
185
+ ...(process.env.ACRYL_ASSISTANT === 'on' ? { assistantInProduction: true } : {}),
186
+ // A terminal driver names the browser module that draws its view and the prefix its endpoints live under: the plugin that owns the view
187
+ // also knows where the app is mounted, so the panel never guesses either.
188
+ drivers: offered().map((driver) => ({
189
+ name: driver.name,
190
+ kind: driver.kind,
191
+ ...(driver.kind === 'terminal' ? { view: driver.view } : {}),
192
+ })),
193
+ })
194
+ })
195
+ .post(`${PANEL_PATH}/ask`, async (c) => {
196
+ const visitor = caller(c.req.raw.headers, c.req.header('x-agent-panel-token'))
197
+ if (visitor === undefined) return c.json({ error: "only the app's own page may ask" }, 403)
198
+ const body = (await c.req.json().catch(() => ({}))) as {
199
+ message?: unknown
200
+ driver?: unknown
201
+ page?: unknown
202
+ }
203
+ const checked = checkAsk(visitor, body.message, body.driver)
204
+ if ('error' in checked) return c.json({ error: checked.error }, checked.status)
205
+ const run = startRun(
206
+ visitor,
207
+ checked.driverName,
208
+ checked.message,
209
+ checked.driver,
210
+ pageOf(body.page),
211
+ )
212
+ return follow(c, run, false)
213
+ })
214
+ // Stop: the only thing that cancels a run. A page that goes away (a reload, a move to another page, a closed tab) does not: the agent goes on, and the page picks it up again.
215
+ .post(`${PANEL_PATH}/stop`, (c) => {
216
+ const visitor = caller(c.req.raw.headers, c.req.header('x-agent-panel-token'))
217
+ if (visitor === undefined)
218
+ return c.json({ error: "only the app's own page may stop a run" }, 403)
219
+ // A visitor's own run, never another's.
220
+ visitor.current?.cancel.abort()
221
+ return c.json({ ok: true })
222
+ })
223
+ // The latest run, for a page that just loaded: what was asked, then every event so far, then the rest as it happens (until the run ends).
224
+ .get(`${PANEL_PATH}/run`, (c) => {
225
+ const visitor = caller(c.req.raw.headers, c.req.header('x-agent-panel-token'))
226
+ if (visitor === undefined)
227
+ return c.json({ error: "only the app's own page may read the run" }, 403)
228
+ return visitor.current === undefined
229
+ ? c.json({ run: null })
230
+ : follow(c, visitor.current, true)
231
+ })
232
+ /**
233
+ * What `/ask` and the socket's `ask` both check: a message of a sensible size, a chat driver that is here, and no run of this visitor going; for the Assistant also its
234
+ * limits (an admitted ask is counted).
235
+ */
236
+ const checkAsk = (
237
+ visitor: Visitor<Run>,
238
+ rawMessage: unknown,
239
+ rawDriver: unknown,
240
+ ):
241
+ | { message: string; driverName: string; driver: ChatDriver }
242
+ | { error: string; status: 400 | 409 | 429 | 503 } => {
243
+ const message = typeof rawMessage === 'string' ? rawMessage.trim() : ''
244
+ const driverName = typeof rawDriver === 'string' ? rawDriver : 'agent'
245
+ const tooLong = visitors.checkMessage(message)
246
+ if (tooLong !== undefined) return tooLong
247
+ const driver = offered().find((one) => one.name === driverName)
248
+ if (driver?.kind !== 'chat') {
249
+ const chat = offered()
250
+ .filter((d) => d.kind === 'chat')
251
+ .map((d) => d.name)
252
+ .join(', ')
253
+ const why = whyNotChat(driverName, driver?.kind)
254
+ return {
255
+ error: `the driver "${driverName}" is not available here${why === undefined ? '' : `: ${why}`} (chat drivers: ${chat})`,
256
+ status: 400,
257
+ }
258
+ }
259
+ const refused = visitors.admit(visitor)
260
+ if (refused !== undefined) {
261
+ if (assistant) audit({ ask: 'refused', visitor: visitor.tag, status: refused.status })
262
+ return refused
263
+ }
264
+ return { message, driverName, driver }
265
+ }
266
+ /** One run of an agent: its events as they came, and who is following. It lives in the app, not in a page. */
267
+ interface Run {
268
+ readonly id: number
269
+ readonly driver: string
270
+ readonly message: string
271
+ readonly startedAt: number
272
+ readonly events: Array<{ event: string; data: unknown }>
273
+ readonly followers: Set<(item: { event: string; data: unknown }) => void>
274
+ readonly cancel: AbortController
275
+ ended: boolean
276
+ endedAt?: number
277
+ }
278
+ let runs = 0
279
+ /** The door's id of the page that asked, when it sent one that looks like it. */
280
+ const pageOf = (raw: unknown): string | undefined =>
281
+ typeof raw === 'string' && /^[A-Za-z0-9-]{1,80}$/u.test(raw) ? raw : undefined
282
+ const startRun = (
283
+ visitor: Visitor<Run>,
284
+ driverName: string,
285
+ message: string,
286
+ driver: ChatDriver,
287
+ page?: string,
288
+ ): Run => {
289
+ runs += 1
290
+ const run: Run = {
291
+ id: runs,
292
+ driver: driverName,
293
+ message,
294
+ startedAt: Date.now(),
295
+ events: [],
296
+ followers: new Set(),
297
+ cancel: new AbortController(),
298
+ ended: false,
299
+ }
300
+ visitor.current = run
301
+ const who = assistant ? { visitor: visitor.tag } : {}
302
+ const emit = (event: string, data: unknown): void => {
303
+ const item = { event, data }
304
+ run.events.push(item)
305
+ for (const follower of [...run.followers]) follower(item)
306
+ }
307
+ let changed = false
308
+ const off = ctx.on('extensions/changed', (extension: string, action: string) => {
309
+ changed = true
310
+ emit('change', { extension, action })
311
+ })
312
+ // The run ends when the plugin unloads; the effect goes when the run ends, so runs do not pile up on the plugin.
313
+ const unloadStops = ctx.effect(() => () => run.cancel.abort(), `agent-panel: run ${runs}`)
314
+ audit({ ask: 'start', ...who, driver: driverName, characters: message.length })
315
+ // The agent's door calls name no window: while this run goes, they are for the page whose panel asked, not for another tab or window that happens to be open.
316
+ const door = page === undefined ? undefined : (ctx.get('door') as DoorPort | undefined)
317
+ const releasePage = door?.driveFor(page as string)
318
+ void (async () => {
319
+ try {
320
+ for await (const { event, data } of driver.start({
321
+ message,
322
+ signal: run.cancel.signal,
323
+ ...(page === undefined ? {} : { page }),
324
+ }))
325
+ emit(event, data)
326
+ emit('done', { changed })
327
+ } catch (error) {
328
+ emit('error', { message: error instanceof Error ? error.message : String(error) })
329
+ } finally {
330
+ off()
331
+ releasePage?.()
332
+ run.ended = true
333
+ run.endedAt = Date.now()
334
+ audit({ ask: 'end', ...who, driver: driverName, changed })
335
+ for (const follower of [...run.followers]) follower({ event: 'end', data: {} })
336
+ void unloadStops()
337
+ }
338
+ })()
339
+ return run
340
+ }
341
+ /**
342
+ * Follow a run into `write`: a `run` event (what it is, whether it already ended) when `announce`, the events so far, then the new ones until it ends. Following does not keep the
343
+ * run alive. `detach` stops following (the page went away); `done` settles when the run ended or the following was detached.
344
+ */
345
+ const pump = (
346
+ run: Run,
347
+ announce: boolean,
348
+ write: (event: string, data: unknown) => void | Promise<void>,
349
+ ): { done: Promise<void>; detach(): void } => {
350
+ const queue: Array<{ event: string; data: unknown }> = [...run.events]
351
+ if (announce)
352
+ queue.unshift({
353
+ event: 'run',
354
+ data: {
355
+ id: run.id,
356
+ driver: run.driver,
357
+ message: run.message,
358
+ startedAt: run.startedAt,
359
+ ended: run.ended,
360
+ endedAt: run.endedAt ?? null,
361
+ },
362
+ })
363
+ let wake: (() => void) | undefined
364
+ const follower = (item: { event: string; data: unknown }): void => {
365
+ queue.push(item)
366
+ wake?.()
367
+ }
368
+ if (!run.ended) run.followers.add(follower)
369
+ let open = true
370
+ const done = (async () => {
371
+ try {
372
+ while (open) {
373
+ const item = queue.shift()
374
+ if (item === undefined) {
375
+ if (run.ended) break
376
+ await new Promise<void>((resolve) => {
377
+ wake = resolve
378
+ })
379
+ wake = undefined
380
+ continue
381
+ }
382
+ if (item.event === 'end') break
383
+ await write(item.event, item.data)
384
+ }
385
+ } finally {
386
+ run.followers.delete(follower)
387
+ }
388
+ })()
389
+ return {
390
+ done,
391
+ detach: () => {
392
+ open = false
393
+ run.followers.delete(follower)
394
+ wake?.()
395
+ },
396
+ }
397
+ }
398
+ /** Follow a run as server-sent events. */
399
+ const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
400
+ streamSSE(c, async (stream) => {
401
+ const following = pump(run, announce, (event, data) =>
402
+ stream.writeSSE({ event, data: JSON.stringify(data) }),
403
+ )
404
+ stream.onAbort(following.detach)
405
+ await following.done
406
+ })
407
+ // The same runs over a WebSocket, which is not one of the browser's six connections per host: a page that streams its own state in two windows, with a run going, would otherwise
408
+ // queue the panel's Stop and the door's answers behind them. A WebSocket has no CORS and cannot set a header, so the Origin must be this app's own and the first frame carries the
409
+ // token. Frames: up `{ t: 'hello', token }`, then `{ t: 'ask', message, driver }`, `{ t: 'follow' }` or `{ t: 'stop' }`; down `{ e: <event>, d: <data> }`, as the stream's events.
410
+ // The server row comes after this plugin in a blend, so the WebSocket form is mounted when the server appears (and not at all without one that upgrades or without the `ws` package).
411
+ ctx.inject(['nodeServer'], (inner) => {
412
+ let upgrade: UpgradeWebSocket
413
+ try {
414
+ upgrade = (
415
+ inner as unknown as { nodeServer: { upgrades(): UpgradeWebSocket } }
416
+ ).nodeServer.upgrades()
417
+ } catch {
418
+ return
419
+ }
420
+ const ws = new Acryl()
421
+ const own: MiddlewareHandler = async (c, next) => {
422
+ const authority = pageAuthority(c)
423
+ const origin = c.req.header('origin')
424
+ const site = c.req.header('sec-fetch-site')
425
+ if (
426
+ authority === undefined ||
427
+ origin === undefined ||
428
+ origin !== authority.origin ||
429
+ (site !== undefined && site !== 'same-origin')
430
+ )
431
+ return c.json({ error: "only the app's own page may use the panel" }, 403)
432
+ await next()
433
+ }
434
+ ws.get(
435
+ `${PREFIX}/run/ws`,
436
+ own,
437
+ upgrade(
438
+ (c) => {
439
+ // The visitor the socket's cookie names (the owner in development): its hello must carry that visitor's token, and it reaches that visitor's runs only.
440
+ const visitor = visitors.of(c.req.header('cookie'))
441
+ let authed = false
442
+ let following: { detach(): void } | undefined
443
+ let hello: NodeJS.Timeout | undefined
444
+ return {
445
+ onOpen(_event, ws) {
446
+ hello = setTimeout(() => ws.close(4401, 'no token'), 5000)
447
+ },
448
+ onMessage(event, ws) {
449
+ if (typeof event.data !== 'string') return
450
+ let message: {
451
+ t?: unknown
452
+ token?: unknown
453
+ message?: unknown
454
+ driver?: unknown
455
+ page?: unknown
456
+ }
457
+ try {
458
+ message = JSON.parse(event.data) as typeof message
459
+ } catch {
460
+ return
461
+ }
462
+ if (!authed) {
463
+ if (message.t !== 'hello' || !visitors.accepts(visitor, message.token)) {
464
+ ws.close(4401, 'token')
465
+ return
466
+ }
467
+ authed = true
468
+ if (hello !== undefined) clearTimeout(hello)
469
+ // The page waits for this before it counts the socket as open: a token it was given by an earlier start of the app is refused (4401) and it asks for a new one.
470
+ ws.send(JSON.stringify({ e: 'accepted', d: {} }))
471
+ return
472
+ }
473
+ const send = (e: string, d: unknown): void => {
474
+ ws.send(JSON.stringify({ e, d }))
475
+ }
476
+ if (visitor === undefined) return
477
+ if (message.t === 'stop') {
478
+ visitor.current?.cancel.abort()
479
+ return
480
+ }
481
+ if (following !== undefined) return
482
+ const watch = (run: Run, announce: boolean): void => {
483
+ const pumped = pump(run, announce, send)
484
+ following = pumped
485
+ void pumped.done.then(() => ws.close(1000, 'run ended'))
486
+ }
487
+ if (message.t === 'ask') {
488
+ const checked = checkAsk(visitor, message.message, message.driver)
489
+ if ('error' in checked) {
490
+ send('error', { message: checked.error })
491
+ ws.close(1000, 'refused')
492
+ return
493
+ }
494
+ watch(
495
+ startRun(
496
+ visitor,
497
+ checked.driverName,
498
+ checked.message,
499
+ checked.driver,
500
+ pageOf(message.page),
501
+ ),
502
+ false,
503
+ )
504
+ } else if (message.t === 'follow') {
505
+ if (visitor.current === undefined) {
506
+ send('idle', {})
507
+ ws.close(1000, 'no run')
508
+ } else watch(visitor.current, true)
509
+ }
510
+ },
511
+ onClose() {
512
+ if (hello !== undefined) clearTimeout(hello)
513
+ following?.detach()
514
+ },
515
+ }
516
+ },
517
+ { textOnly: true },
518
+ ),
519
+ )
520
+ inner.router.route('/', ws)
521
+ })
522
+ ctx.router.route(MOUNT === '' ? '/' : MOUNT, app)
523
+ }
package/launch.ts ADDED
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Starting a coding agent (`claude`, `codex`, `pi`) without a shell. Off Windows the program is spawned by name. On Windows an npm-installed CLI is a `.cmd` shim, which CreateProcess
3
+ * cannot start, and a shell would pass the person's message through cmd.exe quoting (`& | < > ^ "` would run or break). So the shim is read: npm writes the script it runs
4
+ * (`"%dp0%\node_modules\<package>\dist\cli.js"`), and that script is started with Node directly, as one process. A native `.exe` (the Windows installer of claude) is started as it is.
5
+ */
6
+ import { existsSync, readFileSync } from 'node:fs'
7
+ import { win32 } from 'node:path'
8
+
9
+ export interface Launch {
10
+ readonly file: string
11
+ readonly args: string[]
12
+ }
13
+
14
+ export interface LaunchDeps {
15
+ readonly platform?: NodeJS.Platform
16
+ readonly env?: NodeJS.ProcessEnv
17
+ readonly exists?: (path: string) => boolean
18
+ readonly read?: (path: string) => string
19
+ /** The Node that starts a shim's script (this process's). */
20
+ readonly execPath?: string
21
+ }
22
+
23
+ /** The script an npm `.cmd` shim runs: the quoted path after `%dp0%\`, ending in .js, .cjs or .mjs. */
24
+ const SHIM_SCRIPT = /"%dp0%[\\/]([^"\r\n]+?\.(?:mjs|cjs|js))"/iu
25
+
26
+ /**
27
+ * @returns how to start `program` with `args`, or a sentence saying why it cannot be started here. A program that is not found is also a sentence.
28
+ */
29
+ export function resolveLaunch(
30
+ program: string,
31
+ args: readonly string[],
32
+ deps: LaunchDeps = {},
33
+ ): Launch | { readonly error: string } {
34
+ const platform = deps.platform ?? process.platform
35
+ if (platform !== 'win32') return { file: program, args: [...args] }
36
+ const env = deps.env ?? process.env
37
+ const exists = deps.exists ?? existsSync
38
+ const read = deps.read ?? ((path: string) => readFileSync(path, 'utf8'))
39
+ const execPath = deps.execPath ?? process.execPath
40
+ const folders = (env.PATH ?? env.Path ?? '').split(';').filter(Boolean)
41
+ for (const folder of folders) {
42
+ for (const extension of ['.exe', '.com', '.cmd', '.bat']) {
43
+ const found = win32.join(folder, `${program}${extension}`)
44
+ if (!exists(found)) continue
45
+ if (extension === '.exe' || extension === '.com') return { file: found, args: [...args] }
46
+ let text: string
47
+ try {
48
+ text = read(found)
49
+ } catch {
50
+ return { error: `${program} is installed as ${found} but that file cannot be read` }
51
+ }
52
+ const script = SHIM_SCRIPT.exec(text)?.[1]
53
+ if (script === undefined) {
54
+ return {
55
+ error: `${program} is installed as ${found}, a batch file the panel cannot start without a shell (a shell would pass the message through cmd.exe quoting). Install the native program, or an npm package that creates an npm shim`,
56
+ }
57
+ }
58
+ const directory = win32.dirname(found)
59
+ const node = win32.join(directory, 'node.exe')
60
+ return {
61
+ file: exists(node) ? node : execPath,
62
+ args: [win32.join(directory, script), ...args],
63
+ }
64
+ }
65
+ }
66
+ return { error: `${program} was not found on the PATH` }
67
+ }