@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
@@ -0,0 +1,90 @@
1
+ import assert from 'node:assert/strict'
2
+ import { test } from 'node:test'
3
+ import { resolveLaunch } from '../launch.ts'
4
+
5
+ /** A Windows machine: the files that exist, with their text. */
6
+ const machine = (files: Record<string, string>, path = 'C:\\tools;C:\\Users\\a b\\node22') => ({
7
+ platform: 'win32' as const,
8
+ env: { PATH: path },
9
+ exists: (file: string) => file in files,
10
+ read: (file: string) => files[file] ?? '',
11
+ execPath: 'C:\\node\\node.exe',
12
+ })
13
+
14
+ /** What npm's cmd-shim writes for a global install (the part that matters; the rest is boilerplate). */
15
+ const npmShim = (script: string) =>
16
+ `@ECHO off\r\nGOTO start\r\n:find_dp0\r\nSET dp0=%~dp0\r\nEXIT /b\r\n:start\r\nSETLOCAL\r\nCALL :find_dp0\r\n\r\nIF EXIST "%dp0%\\node.exe" (\r\n SET "_prog=%dp0%\\node.exe"\r\n) ELSE (\r\n SET "_prog=node"\r\n)\r\n\r\nendLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%" "%dp0%\\${script}" %*\r\n`
17
+
18
+ test('off Windows the program is started by name', () => {
19
+ assert.deepEqual(resolveLaunch('pi', ['-p', 'hi'], { platform: 'linux' }), {
20
+ file: 'pi',
21
+ args: ['-p', 'hi'],
22
+ })
23
+ })
24
+
25
+ test('an npm .cmd shim becomes node and the script it runs, with the message untouched (no shell, no cmd.exe quoting)', () => {
26
+ const message = 'make it "red" & show 100% | done > file ^ <x>'
27
+ const launch = resolveLaunch(
28
+ 'pi',
29
+ ['-p', message],
30
+ machine({
31
+ 'C:\\Users\\a b\\node22\\pi.cmd': npmShim(
32
+ 'node_modules\\@earendil-works\\pi-coding-agent\\dist\\cli.js',
33
+ ),
34
+ }),
35
+ )
36
+ assert.deepEqual(launch, {
37
+ file: 'C:\\node\\node.exe',
38
+ args: [
39
+ 'C:\\Users\\a b\\node22\\node_modules\\@earendil-works\\pi-coding-agent\\dist\\cli.js',
40
+ '-p',
41
+ message,
42
+ ],
43
+ })
44
+ })
45
+
46
+ test('a node.exe beside the shim is the Node that runs its script', () => {
47
+ const launch = resolveLaunch(
48
+ 'codex',
49
+ ['exec'],
50
+ machine({
51
+ 'C:\\tools\\codex.cmd': npmShim('node_modules\\@openai\\codex\\bin\\codex.js'),
52
+ 'C:\\tools\\node.exe': '',
53
+ }),
54
+ )
55
+ assert.deepEqual(launch, {
56
+ file: 'C:\\tools\\node.exe',
57
+ args: ['C:\\tools\\node_modules\\@openai\\codex\\bin\\codex.js', 'exec'],
58
+ })
59
+ })
60
+
61
+ test('a native .exe is started as it is, and is preferred to a shim beside it', () => {
62
+ const launch = resolveLaunch(
63
+ 'claude',
64
+ ['-p', 'hi'],
65
+ machine({ 'C:\\tools\\claude.exe': '', 'C:\\tools\\claude.cmd': npmShim('x.js') }),
66
+ )
67
+ assert.deepEqual(launch, { file: 'C:\\tools\\claude.exe', args: ['-p', 'hi'] })
68
+ })
69
+
70
+ test('a batch file that is not an npm shim, and a program that is not there, are sentences and not a spawn', () => {
71
+ const batch = resolveLaunch(
72
+ 'pi',
73
+ [],
74
+ machine({ 'C:\\tools\\pi.cmd': '@echo off\r\nsomething else %*\r\n' }),
75
+ )
76
+ assert.ok('error' in batch)
77
+ assert.match(
78
+ batch.error,
79
+ /pi is installed as C:\\tools\\pi\.cmd, a batch file the panel cannot start without a shell/,
80
+ )
81
+ const missing = resolveLaunch('pi', [], machine({}))
82
+ assert.deepEqual(missing, { error: 'pi was not found on the PATH' })
83
+ const unreadable = resolveLaunch('pi', [], {
84
+ ...machine({ 'C:\\tools\\pi.cmd': '' }),
85
+ read: () => {
86
+ throw new Error('EACCES')
87
+ },
88
+ })
89
+ assert.ok('error' in unreadable)
90
+ })
@@ -0,0 +1,79 @@
1
+ import assert from 'node:assert/strict'
2
+ import { test } from 'node:test'
3
+ import { parseInline, parseMarkdown, safeHref } from '../client/markdown.ts'
4
+
5
+ test('headings, paragraphs, lists, fences and quotes become blocks', () => {
6
+ const blocks = parseMarkdown(
7
+ '## Plan\nFirst line\nsecond line\n\n- one\n- two **bold**\n\n1. a\n2. b\n\n```ts\nconst x = 1\n```\n> quoted\n> more',
8
+ )
9
+ assert.deepEqual(
10
+ blocks.map((block) => block.type),
11
+ ['heading', 'paragraph', 'list', 'list', 'code', 'quote'],
12
+ )
13
+ const [heading, paragraph, bullets, numbers, code, quote] = blocks
14
+ assert.deepEqual(heading, {
15
+ type: 'heading',
16
+ level: 2,
17
+ children: [{ type: 'text', text: 'Plan' }],
18
+ })
19
+ assert.deepEqual(paragraph, {
20
+ type: 'paragraph',
21
+ children: [{ type: 'text', text: 'First line\nsecond line' }],
22
+ })
23
+ assert.equal(bullets?.type === 'list' && bullets.ordered, false)
24
+ assert.equal(bullets?.type === 'list' && bullets.items.length, 2)
25
+ assert.equal(numbers?.type === 'list' && numbers.ordered, true)
26
+ assert.deepEqual(code, { type: 'code', language: 'ts', text: 'const x = 1' })
27
+ assert.deepEqual(quote, { type: 'quote', children: [{ type: 'text', text: 'quoted\nmore' }] })
28
+ })
29
+
30
+ test('inline code, bold, italic and links; an opener with no closer is text', () => {
31
+ assert.deepEqual(
32
+ parseInline('use `npm test` and **be careful** with *this* [docs](https://example.com/a)'),
33
+ [
34
+ { type: 'text', text: 'use ' },
35
+ { type: 'code', text: 'npm test' },
36
+ { type: 'text', text: ' and ' },
37
+ { type: 'strong', children: [{ type: 'text', text: 'be careful' }] },
38
+ { type: 'text', text: ' with ' },
39
+ { type: 'em', children: [{ type: 'text', text: 'this' }] },
40
+ { type: 'text', text: ' ' },
41
+ { type: 'link', href: 'https://example.com/a', children: [{ type: 'text', text: 'docs' }] },
42
+ ],
43
+ )
44
+ assert.deepEqual(parseInline('2 * 3 and **open and `tick'), [
45
+ { type: 'text', text: '2 * 3 and **open and `tick' },
46
+ ])
47
+ assert.deepEqual(parseInline('snake_case_name stays'), [
48
+ { type: 'text', text: 'snake_case_name stays' },
49
+ ])
50
+ })
51
+
52
+ test('an open fence (the answer is still streaming) shows what it has', () => {
53
+ assert.deepEqual(parseMarkdown('Here:\n```\nline 1\nline 2'), [
54
+ { type: 'paragraph', children: [{ type: 'text', text: 'Here:' }] },
55
+ { type: 'code', language: '', text: 'line 1\nline 2' },
56
+ ])
57
+ })
58
+
59
+ test('HTML in an answer is text, and a link keeps its address only for http, https and mailto', () => {
60
+ const hostile = parseMarkdown(
61
+ '<img src=x onerror=alert(1)> <script>alert(2)</script>\n\n[x](javascript:alert(3)) [y](data:text/html,hi) [z]( https://ok.example/p ) [m](mailto:a@b.c)',
62
+ )
63
+ assert.deepEqual(hostile[0], {
64
+ type: 'paragraph',
65
+ children: [{ type: 'text', text: '<img src=x onerror=alert(1)> <script>alert(2)</script>' }],
66
+ })
67
+ const second = hostile[1]
68
+ assert.ok(second?.type === 'paragraph')
69
+ const links = second.children.filter((node) => node.type === 'link')
70
+ assert.deepEqual(
71
+ links.map((node) => (node.type === 'link' ? node.href : 'x')),
72
+ [undefined, undefined, 'https://ok.example/p', 'mailto:a@b.c'],
73
+ )
74
+ assert.equal(safeHref('HTTPS://EXAMPLE.COM'), 'HTTPS://EXAMPLE.COM')
75
+ assert.equal(safeHref('https://a b'), undefined)
76
+ assert.equal(safeHref('//evil.example'), undefined)
77
+ assert.equal(safeHref('/relative'), undefined)
78
+ assert.equal(safeHref('JaVaScRiPt:alert(1)'), undefined)
79
+ })
@@ -0,0 +1,150 @@
1
+ // The panel in a page that is replaced (a run that changes files reloads the page, and a mount replaces the panel): a submit is prevented before anything
2
+ // else and says why, a remount leaves one host and keeps the draft, and a page reloaded mid-run shows the run it lost. The frame gate caught the opposite
3
+ // once - an empty log with no refusal and no run (2026-11-02) - so these are the promises the panel makes to a person on a slow machine.
4
+ import assert from 'node:assert/strict'
5
+ import { afterEach, test } from 'node:test'
6
+ import { JSDOM } from 'jsdom'
7
+ import { RELOAD_MARKER, reloadDecision, start } from '../client/main.ts'
8
+
9
+ const SESSION = { token: 'gate-token', drivers: [{ name: 'agent', kind: 'chat' }] }
10
+ let dom: JSDOM | undefined
11
+
12
+ /** One server-sent answer: the frames, then the stream closes. */
13
+ function runStream(frames: readonly string[]): Response {
14
+ const body = new ReadableStream<Uint8Array>({
15
+ start(controller) {
16
+ const encoder = new TextEncoder()
17
+ for (const frame of frames) controller.enqueue(encoder.encode(frame))
18
+ setTimeout(() => {
19
+ controller.close()
20
+ }, 100)
21
+ },
22
+ })
23
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
24
+ }
25
+
26
+ /** A page with the globals the panel reads and a fetch that answers the session and the follow request; no WebSocket, so the panel streams over fetch. */
27
+ function mountPage(follow: () => Response): void {
28
+ dom = new JSDOM('<!doctype html><html><body></body></html>', {
29
+ url: 'http://127.0.0.1:4444/app',
30
+ })
31
+ const globals = globalThis as unknown as Record<string, unknown>
32
+ globals.window = dom.window
33
+ globals.document = dom.window.document
34
+ globals.sessionStorage = dom.window.sessionStorage
35
+ globals.location = dom.window.location
36
+ globals.Event = dom.window.Event
37
+ delete globals.WebSocket
38
+ globals.fetch = async (input: string | URL | Request) => {
39
+ const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
40
+ if (url.endsWith('/session'))
41
+ return new Response(JSON.stringify(SESSION), {
42
+ status: 200,
43
+ headers: { 'content-type': 'application/json' },
44
+ })
45
+ if (url.endsWith('/run')) return follow()
46
+ return new Response('{}', { status: 200 })
47
+ }
48
+ }
49
+
50
+ afterEach(() => {
51
+ dom?.window.close()
52
+ dom = undefined
53
+ })
54
+
55
+ const documentOf = (): Document => dom!.window.document
56
+
57
+ /** The one panel host and its shadow root. */
58
+ function panel(): { host: HTMLElement; root: ShadowRoot } {
59
+ const host = documentOf().getElementById('agent-panel')
60
+ assert.ok(host !== null, 'the panel mounted')
61
+ return { host, root: host.shadowRoot! }
62
+ }
63
+
64
+ /** Poll until the check passes (the panel's stream is asynchronous). */
65
+ async function waitFor(check: () => boolean, ms = 3_000): Promise<void> {
66
+ const end = Date.now() + ms
67
+ while (!check() && Date.now() < end) await new Promise((done) => setTimeout(done, 25))
68
+ assert.ok(check(), 'the expected panel state arrived')
69
+ }
70
+
71
+ test('a submit is prevented before anything else and says why when nothing is typed', async () => {
72
+ mountPage(() => runStream([]))
73
+ await start('/api/agent-panel')
74
+ const { root } = panel()
75
+ const event = new dom!.window.Event('submit', { bubbles: true, cancelable: true })
76
+ root.querySelector('form')!.dispatchEvent(event)
77
+ assert.equal(event.defaultPrevented, true, 'the form default never runs')
78
+ assert.match(root.querySelector('#log')!.textContent ?? '', /Type a message first\./)
79
+ // The form names no action either: a missed preventDefault could only submit to this page, never navigate it.
80
+ assert.equal(root.querySelector('form')!.getAttribute('action'), null)
81
+ })
82
+
83
+ test('a remount replaces the one host and keeps the draft', async () => {
84
+ mountPage(() => runStream([]))
85
+ await start('/api/agent-panel')
86
+ const input = panel().root.querySelector('textarea') as HTMLTextAreaElement
87
+ input.value = 'half a thought'
88
+ input.dispatchEvent(new dom!.window.Event('input', { bubbles: true }))
89
+ await start('/api/agent-panel')
90
+ const panels = documentOf().querySelectorAll('#agent-panel')
91
+ assert.equal(panels.length, 1, 'one live panel after a remount')
92
+ assert.equal(
93
+ (panels[0]!.shadowRoot!.querySelector('textarea') as HTMLTextAreaElement).value,
94
+ 'half a thought',
95
+ )
96
+ })
97
+
98
+ test('a page replaced mid-run shows the run it lost', async () => {
99
+ // The server records a run before it answers the ask that started it, so the follow after a reload finds it in one question (no client poll).
100
+ mountPage(() =>
101
+ runStream([
102
+ 'event: run\ndata: {"message":"add 2 3","startedAt":1,"ended":false}\n\n',
103
+ 'event: text\ndata: {"text":"The answer is 5."}\n\n',
104
+ ]),
105
+ )
106
+ await start('/api/agent-panel')
107
+ const { root } = panel()
108
+ await waitFor(() => (root.querySelector('#log')!.textContent ?? '').includes('The answer is 5.'))
109
+ const log = root.querySelector('#log')!.textContent ?? ''
110
+ assert.match(log, /add 2 3/, 'the question the run lost is shown again')
111
+ assert.match(log, /The answer is 5\./, 'the answer is shown again')
112
+ })
113
+
114
+ test('the decision to reload the page is made at the moment of reloading, never earlier', () => {
115
+ assert.equal(reloadDecision({ value: '', focused: false, following: false }), true)
116
+ // A person typing, or with the caret in the composer, keeps their page: a check made a second earlier must not replace it.
117
+ assert.equal(reloadDecision({ value: 'half typed', focused: false, following: false }), false)
118
+ assert.equal(reloadDecision({ value: '', focused: true, following: false }), false)
119
+ assert.equal(reloadDecision({ value: '', focused: false, following: true }), false)
120
+ })
121
+
122
+ /** The frames of a run that changes a plugin and then ends. */
123
+ const CHANGE_FRAMES = [
124
+ 'event: run\ndata: {"message":"add 2 3","startedAt":1,"ended":false}\n\n',
125
+ 'event: change\ndata: {"extension":"hello","action":"installed"}\n\n',
126
+ 'event: done\ndata: {"changed":true}\n\n',
127
+ ]
128
+
129
+ test('a change event while the person is typing never replaces the page or loses the text', async () => {
130
+ mountPage(() => runStream(CHANGE_FRAMES))
131
+ await start('/api/agent-panel')
132
+ const input = panel().root.querySelector('textarea') as HTMLTextAreaElement
133
+ input.value = 'half typed'
134
+ input.dispatchEvent(new dom!.window.Event('input', { bubbles: true }))
135
+ await new Promise((done) => setTimeout(done, 1_200))
136
+ assert.equal(dom!.window.sessionStorage.getItem(RELOAD_MARKER), null, 'no reload was started')
137
+ assert.equal((panel().root.querySelector('textarea') as HTMLTextAreaElement).value, 'half typed')
138
+ })
139
+
140
+ test('a change event with an idle, empty composer reloads the page and leaves the reason behind', async () => {
141
+ mountPage(() => runStream(CHANGE_FRAMES))
142
+ await start('/api/agent-panel')
143
+ // The run's first event opens the panel and focuses the composer; a person who has moved on (blurred it) with nothing typed lets the page refresh.
144
+ await waitFor(() => (panel().root.querySelector('#log')?.textContent ?? '').includes('add 2 3'))
145
+ ;(panel().root.querySelector('textarea') as HTMLTextAreaElement).blur()
146
+ await new Promise((done) => setTimeout(done, 1_200))
147
+ const marker = dom!.window.sessionStorage.getItem(RELOAD_MARKER)
148
+ assert.ok(marker !== null, 'the reload was recorded before it happened')
149
+ assert.match(marker!, /a plugin changed/)
150
+ })