@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.
- package/LICENSE +21 -0
- package/client/describe.ts +101 -0
- package/client/driver-pick.ts +22 -0
- package/client/frame.ts +51 -0
- package/client/main.ts +707 -0
- package/client/markdown.ts +219 -0
- package/headless.ts +220 -0
- package/index.ts +523 -0
- package/launch.ts +67 -0
- package/lib/client/describe.ts +101 -0
- package/lib/client/driver-pick.ts +22 -0
- package/lib/client/frame.ts +51 -0
- package/lib/client/main.ts +707 -0
- package/lib/client/markdown.ts +219 -0
- package/lib/headless-B_RGxZFU.js +252 -0
- package/lib/headless-B_RGxZFU.js.map +1 -0
- package/lib/headless.js +2 -0
- package/lib/index.js +562 -0
- package/lib/index.js.map +1 -0
- package/lib/mount.js +25 -0
- package/lib/mount.js.map +1 -0
- package/lib/registry.js +13 -0
- package/lib/registry.js.map +1 -0
- package/lib/types/headless.d.ts +22 -0
- package/lib/types/index.d.ts +22 -0
- package/lib/types/launch.d.ts +18 -0
- package/lib/types/mount.d.ts +12 -0
- package/lib/types/registry.d.ts +10 -0
- package/lib/types/tsdown.config.d.ts +2 -0
- package/lib/types/visitors.d.ts +82 -0
- package/mount.ts +27 -0
- package/package.json +62 -3
- package/plugin.json +28 -0
- package/registry.ts +17 -0
- package/scripts/copy-assets.mjs +5 -0
- package/test/client-guards.test.ts +13 -0
- package/test/describe.test.ts +105 -0
- package/test/driver-pick.test.ts +24 -0
- package/test/frame.test.ts +35 -0
- package/test/launch.test.ts +90 -0
- package/test/markdown.test.ts +79 -0
- package/test/panel-client.test.ts +150 -0
- package/test/panel.test.ts +534 -0
- package/test/socket.test.ts +209 -0
- package/test/visitors.test.ts +112 -0
- package/test/why.test.ts +61 -0
- package/tsconfig.json +21 -0
- package/tsdown.config.ts +23 -0
- package/visitors.ts +231 -0
- 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
|
+
}
|