@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,209 @@
1
+ // The panel's runs over a WebSocket: the Origin is the boundary, the first frame carries the token, the events are the stream's, and Stop works on the same socket.
2
+ import assert from 'node:assert/strict'
3
+ import { mkdtempSync, rmSync } from 'node:fs'
4
+ import { createRequire } from 'node:module'
5
+ import { tmpdir } from 'node:os'
6
+ import { join } from 'node:path'
7
+ import { afterEach, test } from 'node:test'
8
+ import { agent, memory, model, tools } from '@acryldev/agent'
9
+ import { builder } from '@acryldev/builder'
10
+ import { extensions } from '@acryldev/extensions'
11
+ import { instance, pinnedInstance } from '@acryldev/instance'
12
+ import * as nodeServer from '@acryldev/node-server'
13
+ import * as router from '@acryldev/router'
14
+ import * as state from '@acryldev/state'
15
+ import { Context } from '@deepseek-ai/cordis'
16
+ import * as panel from '../index.ts'
17
+
18
+ const require = createRequire(import.meta.url)
19
+ const WebSocket = require('ws') as typeof import('ws').WebSocket
20
+ type Socket = InstanceType<typeof WebSocket>
21
+
22
+ const cleanup: Array<() => Promise<void> | void> = []
23
+ afterEach(async () => {
24
+ for (const step of cleanup.splice(0)) await step()
25
+ })
26
+
27
+ /** The agent family and the panel on a real server. */
28
+ async function boot() {
29
+ const saved = { NODE_ENV: process.env.NODE_ENV, ACRYL_DOOR: process.env.ACRYL_DOOR }
30
+ process.env.NODE_ENV = 'test'
31
+ delete process.env.ACRYL_DOOR
32
+ const root = mkdtempSync(join(tmpdir(), 'panel-socket-'))
33
+ const app = new Context()
34
+ const fibers: Array<ReturnType<Context['plugin']>> = []
35
+ for (const start of [
36
+ () => app.plugin(instance, pinnedInstance(join(root, '.acrylblends'), { root })),
37
+ () => app.plugin(router),
38
+ () => app.plugin(state),
39
+ () => app.plugin(nodeServer, { hostname: '127.0.0.1', port: 0 }),
40
+ () => app.plugin(extensions, { sources: [{ dir: join(root, 'plugins'), trust: 'install' }] }),
41
+ () => app.plugin(model),
42
+ () => app.plugin(tools),
43
+ () => app.plugin(memory),
44
+ () => app.plugin(agent),
45
+ () => app.plugin(builder, {}),
46
+ () => app.plugin(panel, { drivers: [] }),
47
+ ]) {
48
+ const fiber = start()
49
+ fibers.push(fiber)
50
+ await fiber.await()
51
+ }
52
+ cleanup.push(async () => {
53
+ for (const fiber of [...fibers].reverse()) await fiber.dispose()
54
+ rmSync(root, { recursive: true, force: true })
55
+ for (const [key, value] of Object.entries(saved)) {
56
+ if (value === undefined) delete process.env[key]
57
+ else process.env[key] = value
58
+ }
59
+ })
60
+ const origin = (app as unknown as { nodeServer: { url: string } }).nodeServer.url.replace(
61
+ /\/$/u,
62
+ '',
63
+ )
64
+ const session = (await (
65
+ await fetch(`${origin}/api/agent-panel/session`, {
66
+ headers: { 'sec-fetch-site': 'same-origin' },
67
+ })
68
+ ).json()) as { token: string }
69
+ return { origin, token: session.token, app }
70
+ }
71
+
72
+ const wsUrl = (origin: string): string => `${origin.replace('http', 'ws')}/api/agent-panel/run/ws`
73
+ const refusal = (url: string, headers: Record<string, string>): Promise<string> =>
74
+ new Promise((resolve) => {
75
+ const socket = new WebSocket(url, { headers })
76
+ socket.once('open', () => {
77
+ socket.close()
78
+ resolve('opened')
79
+ })
80
+ socket.once('unexpected-response', (_request, response) =>
81
+ resolve(`refused ${String(response.statusCode)}`),
82
+ )
83
+ socket.once('error', () => resolve('error'))
84
+ })
85
+ const open = (origin: string): Promise<Socket> =>
86
+ new Promise((resolve, reject) => {
87
+ const socket = new WebSocket(wsUrl(origin), { headers: { origin } })
88
+ socket.once('open', () => resolve(socket))
89
+ socket.once('error', reject)
90
+ })
91
+ /** Every frame until the socket closes, and the close code. */
92
+ const drain = (
93
+ socket: Socket,
94
+ ): Promise<{
95
+ frames: Array<{ e: string; d: Record<string, unknown> }>
96
+ code: number
97
+ accepted: boolean
98
+ }> =>
99
+ new Promise((resolve) => {
100
+ const frames: Array<{ e: string; d: Record<string, unknown> }> = []
101
+ socket.on('message', (data) =>
102
+ frames.push(JSON.parse(data.toString()) as { e: string; d: Record<string, unknown> }),
103
+ )
104
+ socket.once('close', (code) => {
105
+ // The first frame of an accepted socket says so, before anything the run sends; it is not an event of the run.
106
+ const accepted = frames[0]?.e === 'accepted'
107
+ resolve({ frames: accepted ? frames.slice(1) : frames, code, accepted })
108
+ })
109
+ })
110
+
111
+ test("only this app's own Origin may open it: another port, a web site, no Origin, a cross-site request", async () => {
112
+ const { origin } = await boot()
113
+ const port = Number(new URL(origin).port)
114
+ assert.equal(
115
+ await refusal(wsUrl(origin), { origin: `http://127.0.0.1:${String(port + 1)}` }),
116
+ 'refused 403',
117
+ )
118
+ assert.equal(await refusal(wsUrl(origin), { origin: 'https://evil.example' }), 'refused 403')
119
+ assert.equal(await refusal(wsUrl(origin), {}), 'refused 403')
120
+ assert.equal(
121
+ await refusal(wsUrl(origin), { origin, 'sec-fetch-site': 'cross-site' }),
122
+ 'refused 403',
123
+ )
124
+ assert.equal(await refusal(wsUrl(origin), { origin }), 'opened')
125
+ })
126
+
127
+ test('the first frame must carry the token: a wrong one, a missing one and a frame of another kind close the socket with 4401 and run nothing', async () => {
128
+ const { origin } = await boot()
129
+ for (const first of [
130
+ { t: 'hello', token: 'wrong' },
131
+ { t: 'ask', message: 'add 2 3' },
132
+ { t: 'hello' },
133
+ ]) {
134
+ const socket = await open(origin)
135
+ const done = drain(socket)
136
+ socket.send(JSON.stringify(first))
137
+ const { frames, code, accepted } = await done
138
+ assert.equal(code, 4401)
139
+ assert.deepEqual(frames, [])
140
+ // A token this start of the app does not know is told apart from a socket that opened: the page asks for a new session and tries again.
141
+ assert.equal(accepted, false)
142
+ }
143
+ })
144
+
145
+ test('an ask over the socket runs the agent and sends the events the stream sends, ending with done, then closes', async () => {
146
+ const { origin, token } = await boot()
147
+ const socket = await open(origin)
148
+ const done = drain(socket)
149
+ socket.send(JSON.stringify({ t: 'hello', token }))
150
+ socket.send(JSON.stringify({ t: 'ask', message: 'create route hello /hello Hello' }))
151
+ const { frames, code, accepted } = await done
152
+ assert.equal(accepted, true)
153
+ const names = frames.map((frame) => frame.e)
154
+ assert.ok(names.includes('tool'), names.join())
155
+ assert.deepEqual(frames.find((frame) => frame.e === 'change')?.d, {
156
+ extension: 'hello',
157
+ action: 'installed',
158
+ })
159
+ assert.equal(names.at(-1), 'done')
160
+ assert.equal(code, 1000)
161
+ // The page that loads next follows the latest run: its question, then every event, over a socket too.
162
+ const again = await open(origin)
163
+ const replay = drain(again)
164
+ again.send(JSON.stringify({ t: 'hello', token }))
165
+ again.send(JSON.stringify({ t: 'follow' }))
166
+ const followed = await replay
167
+ assert.equal(followed.frames[0]?.e, 'run')
168
+ assert.equal(followed.frames[0]?.d.message, 'create route hello /hello Hello')
169
+ assert.equal(followed.frames[0]?.d.ended, true)
170
+ assert.equal(followed.frames.at(-1)?.e, 'done')
171
+ })
172
+
173
+ test('a refused ask says why in an error frame; with nothing to follow it says idle', async () => {
174
+ const { origin, token } = await boot()
175
+ const refused = await open(origin)
176
+ const closed = drain(refused)
177
+ refused.send(JSON.stringify({ t: 'hello', token }))
178
+ refused.send(JSON.stringify({ t: 'ask', message: 'hi', driver: 'claude' }))
179
+ const { frames } = await closed
180
+ assert.equal(frames[0]?.e, 'error')
181
+ assert.match(String(frames[0]?.d.message), /the driver "claude" is not available here/)
182
+ const idle = await open(origin)
183
+ const idleDone = drain(idle)
184
+ idle.send(JSON.stringify({ t: 'hello', token }))
185
+ idle.send(JSON.stringify({ t: 'follow' }))
186
+ assert.deepEqual(
187
+ (await idleDone).frames.map((frame) => frame.e),
188
+ ['idle'],
189
+ )
190
+ })
191
+
192
+ test('an ask that names the page it came from has the door drive that page while the run goes, and let go when it ends; a page name that is not an id is ignored', async () => {
193
+ const { origin, token, app } = await boot()
194
+ const seen: string[] = []
195
+ app.provide('door', {
196
+ driveFor(page: string) {
197
+ seen.push(`for ${page}`)
198
+ return () => seen.push(`end ${page}`)
199
+ },
200
+ })
201
+ for (const page of ['4f1c-window', 'not an id!', undefined]) {
202
+ const socket = await open(origin)
203
+ const done = drain(socket)
204
+ socket.send(JSON.stringify({ t: 'hello', token }))
205
+ socket.send(JSON.stringify({ t: 'ask', message: 'add 2 3', page }))
206
+ assert.equal((await done).frames.at(-1)?.e, 'done')
207
+ }
208
+ assert.deepEqual(seen, ['for 4f1c-window', 'end 4f1c-window'])
209
+ })
@@ -0,0 +1,112 @@
1
+ import assert from 'node:assert/strict'
2
+ import { test } from 'node:test'
3
+ import { cookieValue, sameSecret, VISITOR_COOKIE, Visitors } from '../visitors.ts'
4
+
5
+ interface Run {
6
+ ended: boolean
7
+ }
8
+
9
+ const cookieOf = (setCookie: string | undefined): string => {
10
+ assert.ok(setCookie)
11
+ return setCookie.split(';')[0] ?? ''
12
+ }
13
+
14
+ test('development has one visitor, the owner: every request is theirs, with no cookie and no limits but one run at a time', () => {
15
+ const visitors = new Visitors<Run>({ shared: true })
16
+ const owner = visitors.of(undefined)
17
+ assert.ok(owner)
18
+ assert.equal(visitors.of('acryl-visitor=someone-else'), owner)
19
+ assert.equal(visitors.session(undefined, false).setCookie, undefined)
20
+ for (let i = 0; i < 50; i++) assert.equal(visitors.admit(owner), undefined)
21
+ owner.current = { ended: false }
22
+ assert.equal(visitors.admit(owner)?.status, 409)
23
+ assert.equal(visitors.checkMessage('x'.repeat(8000)), undefined)
24
+ })
25
+
26
+ test('the Assistant knows each visitor by an HttpOnly cookie of their own, with a token of their own', () => {
27
+ const visitors = new Visitors<Run>({ shared: false })
28
+ assert.equal(visitors.of(undefined), undefined)
29
+ const a = visitors.session(undefined, true)
30
+ assert.match(
31
+ a.setCookie ?? '',
32
+ new RegExp(
33
+ `^${VISITOR_COOKIE}=[\\w-]+; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400; Secure$`,
34
+ 'u',
35
+ ),
36
+ )
37
+ const b = visitors.session('other=1', false)
38
+ assert.doesNotMatch(b.setCookie ?? '', /Secure/u)
39
+ assert.notEqual(a.visitor, b.visitor)
40
+ // A known cookie gets its visitor back, and no new cookie.
41
+ const again = visitors.session(`x=1; ${cookieOf(a.setCookie)}`, true)
42
+ assert.equal(again.visitor, a.visitor)
43
+ assert.equal(again.setCookie, undefined)
44
+ // A visitor's token is good only with that visitor's cookie.
45
+ assert.equal(visitors.knows(cookieOf(a.setCookie), a.visitor.token), true)
46
+ assert.equal(visitors.knows(cookieOf(b.setCookie), a.visitor.token), false)
47
+ assert.equal(visitors.knows('acryl-visitor=made-up', a.visitor.token), false)
48
+ // The audit names a visitor by a short hash, never the cookie.
49
+ assert.match(a.visitor.tag, /^[0-9a-f]{12}$/u)
50
+ assert.equal(cookieOf(a.setCookie).includes(a.visitor.tag), false)
51
+ })
52
+
53
+ test("the Assistant's limits: the question's length, the visitor's hour, runs at once, and the day", () => {
54
+ let now = 0
55
+ const visitors = new Visitors<Run>({
56
+ shared: false,
57
+ now: () => now,
58
+ limits: { perVisitorPerHour: 2, concurrent: 2, perDay: 5, messageLength: 10 },
59
+ })
60
+ assert.equal(visitors.checkMessage('x'.repeat(11))?.status, 400)
61
+ assert.equal(visitors.checkMessage('')?.status, 400)
62
+ const [a, b, c] = [1, 2, 3].map(() => visitors.session(undefined, false).visitor)
63
+ assert.ok(a && b && c)
64
+ assert.equal(visitors.admit(a), undefined)
65
+ a.current = { ended: true }
66
+ assert.equal(visitors.admit(a), undefined)
67
+ a.current = { ended: true }
68
+ const hour = visitors.admit(a)
69
+ assert.equal(hour?.status, 429)
70
+ assert.match(hour?.error ?? '', /2 questions this hour\. Ask again in 60 minutes\./u)
71
+ // Two runs going: a third visitor waits, whoever asks.
72
+ assert.equal(visitors.admit(b), undefined)
73
+ b.current = { ended: false }
74
+ a.current = { ended: false }
75
+ assert.equal(visitors.admit(c)?.status, 503)
76
+ a.current = { ended: true }
77
+ b.current = { ended: true }
78
+ // The hour passes for a; the day still counts every ask it took: 3 so far (the refused ones are not counted), two left.
79
+ now += 60 * 60 * 1000
80
+ assert.equal(visitors.admit(c), undefined)
81
+ c.current = { ended: true }
82
+ assert.equal(visitors.admit(a), undefined)
83
+ a.current = { ended: true }
84
+ const day = visitors.admit(b)
85
+ assert.equal(day?.status, 429)
86
+ assert.match(day?.error ?? '', /all the questions it can today/u)
87
+ // A refused ask is not counted: after the day, a may ask again.
88
+ now += 24 * 60 * 60 * 1000
89
+ assert.equal(visitors.admit(a), undefined)
90
+ })
91
+
92
+ test('past its capacity the Assistant lets go of the visitors seen longest ago, never one with a run going', () => {
93
+ let now = 0
94
+ const visitors = new Visitors<Run>({ shared: false, capacity: 2, now: () => ++now })
95
+ const first = visitors.session(undefined, false)
96
+ first.visitor.current = { ended: false }
97
+ const second = visitors.session(undefined, false)
98
+ visitors.session(undefined, false)
99
+ assert.equal(visitors.size, 2)
100
+ assert.equal(visitors.of(cookieOf(first.setCookie)), first.visitor)
101
+ assert.equal(visitors.of(cookieOf(second.setCookie)), undefined)
102
+ })
103
+
104
+ test('cookie values and secrets', () => {
105
+ assert.equal(cookieValue('a=1; acryl-visitor=xyz; b=2', 'acryl-visitor'), 'xyz')
106
+ assert.equal(cookieValue('a=1', 'acryl-visitor'), undefined)
107
+ assert.equal(cookieValue(null, 'a'), undefined)
108
+ assert.equal(sameSecret('abc', 'abc'), true)
109
+ assert.equal(sameSecret('abd', 'abc'), false)
110
+ assert.equal(sameSecret('ab', 'abc'), false)
111
+ assert.equal(sameSecret(undefined, 'abc'), false)
112
+ })
@@ -0,0 +1,61 @@
1
+ import assert from 'node:assert/strict'
2
+ import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
3
+ import { tmpdir } from 'node:os'
4
+ import { join } from 'node:path'
5
+ import { afterEach, test } from 'node:test'
6
+ import { whyNotChat } from '../headless.ts'
7
+
8
+ const undo: Array<() => void> = []
9
+ afterEach(() => {
10
+ for (const step of undo.splice(0).reverse()) step()
11
+ })
12
+ /** A machine: a folder of programs on the PATH, a home with or without pi's stored key, and the DeepSeek key variable. */
13
+ function machine(options: { programs?: string[]; key?: string }) {
14
+ const root = mkdtempSync(join(tmpdir(), 'why-'))
15
+ const bin = join(root, 'bin')
16
+ mkdirSync(bin)
17
+ for (const name of options.programs ?? []) {
18
+ writeFileSync(join(bin, name), '#!/bin/sh\nexit 0\n')
19
+ chmodSync(join(bin, name), 0o755)
20
+ }
21
+ const saved = {
22
+ PATH: process.env.PATH,
23
+ HOME: process.env.HOME,
24
+ DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY,
25
+ PI_CODING_AGENT_DIR: process.env.PI_CODING_AGENT_DIR,
26
+ }
27
+ process.env.PATH = `${bin}:/usr/bin:/bin`
28
+ process.env.HOME = root
29
+ process.env.PI_CODING_AGENT_DIR = join(root, 'pi')
30
+ if (options.key === undefined) delete process.env.DEEPSEEK_API_KEY
31
+ else process.env.DEEPSEEK_API_KEY = options.key
32
+ undo.push(() => {
33
+ for (const [name, value] of Object.entries(saved)) {
34
+ if (value === undefined) delete process.env[name]
35
+ else process.env[name] = value
36
+ }
37
+ rmSync(root, { recursive: true, force: true })
38
+ })
39
+ }
40
+ const posix = { skip: process.platform === 'win32' ? 'the fake programs are shell scripts' : false }
41
+
42
+ test('a terminal driver is not asked over /ask, and a name that is not an agent has no reason to give', () => {
43
+ assert.match(whyNotChat('pi', 'terminal') ?? '', /terminal driver: pick it in the panel/)
44
+ assert.equal(whyNotChat('nope', undefined), undefined)
45
+ })
46
+
47
+ test('an agent that is not installed is named as not on the PATH', posix, () => {
48
+ machine({ programs: [] })
49
+ assert.match(whyNotChat('codex', undefined) ?? '', /^codex was not found on the PATH/)
50
+ })
51
+
52
+ test(
53
+ 'pi installed without a key says what it needs, and with one has nothing to explain',
54
+ posix,
55
+ () => {
56
+ machine({ programs: ['pi'] })
57
+ assert.match(whyNotChat('pi', undefined) ?? '', /DEEPSEEK_API_KEY.*auth\.json/)
58
+ machine({ programs: ['pi'], key: 'sk-test' })
59
+ assert.equal(whyNotChat('pi', undefined), undefined)
60
+ },
61
+ )
package/tsconfig.json ADDED
@@ -0,0 +1,21 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2024",
4
+ "lib": ["ES2024", "DOM", "DOM.Iterable"],
5
+ "module": "NodeNext",
6
+ "moduleResolution": "NodeNext",
7
+ "allowImportingTsExtensions": true,
8
+ "erasableSyntaxOnly": true,
9
+ "rootDir": ".",
10
+ "outDir": "lib",
11
+ "declaration": true,
12
+ "declarationDir": "lib/types",
13
+ "esModuleInterop": true,
14
+ "strict": true,
15
+ "noImplicitOverride": true,
16
+ "verbatimModuleSyntax": true,
17
+ "skipLibCheck": true,
18
+ "types": ["node"]
19
+ },
20
+ "include": ["*.ts"]
21
+ }
@@ -0,0 +1,23 @@
1
+ import { readFileSync } from 'node:fs'
2
+ import { defineConfig } from 'tsdown'
3
+
4
+ /** The package's importable files, exactly as `plugin.json`'s `entries` names them (the copy path uses the same table). */
5
+ const { entries } = JSON.parse(readFileSync(new URL('./plugin.json', import.meta.url), 'utf8')) as {
6
+ entries: Record<string, string>
7
+ }
8
+ const entry = Object.fromEntries(
9
+ Object.entries(entries).map(([, file]) => [file.replace(/.ts$/, ''), file]),
10
+ )
11
+
12
+ export default defineConfig({
13
+ name: '@acryldev/agent-panel',
14
+ entry,
15
+ outDir: 'lib',
16
+ format: 'esm',
17
+ platform: 'node',
18
+ target: 'es2024',
19
+ fixedExtension: false,
20
+ dts: false,
21
+ clean: true,
22
+ sourcemap: true,
23
+ })
package/visitors.ts ADDED
@@ -0,0 +1,231 @@
1
+ /**
2
+ * Who uses the panel, and what each one may do.
3
+ *
4
+ * - In development one person does, the app's owner: every page of the app shares one token and one run, so a run asked in the frame is followed from any tab of the app.
5
+ * - As the Assistant every visitor of the app is their own: a visitor is known by an HttpOnly cookie that the panel's session sets, and has their own token, their own run and
6
+ * their own limits. A visitor never sees, follows or stops another visitor's run, and never waits for one.
7
+ *
8
+ * The Assistant spends the owner's model key for anyone who opens the app, so its asks are bounded: per visitor per hour, for all visitors per day, runs at once, and the length of
9
+ * a question. The agent's own step budget bounds each run.
10
+ */
11
+ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
12
+
13
+ /** The cookie that names a visitor of the Assistant. HttpOnly: the page's scripts never read it. */
14
+ export const VISITOR_COOKIE = 'acryl-visitor'
15
+
16
+ /** The Assistant's limits; each one has a default. */
17
+ export interface AssistantLimits {
18
+ /** Questions one visitor may ask in an hour. */
19
+ readonly perVisitorPerHour?: number
20
+ /** Questions all visitors together may ask in a day: every one of them spends the owner's model key. */
21
+ readonly perDay?: number
22
+ /** Runs going at once, across visitors. */
23
+ readonly concurrent?: number
24
+ /** Characters in one question. */
25
+ readonly messageLength?: number
26
+ }
27
+
28
+ export const DEFAULT_LIMITS: Required<AssistantLimits> = {
29
+ perVisitorPerHour: 20,
30
+ perDay: 300,
31
+ concurrent: 4,
32
+ messageLength: 1000,
33
+ }
34
+
35
+ /** The question length the development panel accepts (one person, who owns the key). */
36
+ const OWNER_MESSAGE_LENGTH = 8000
37
+ const HOUR_MS = 60 * 60 * 1000
38
+ const DAY_MS = 24 * HOUR_MS
39
+ /** Visitors kept at most; the one seen longest ago without a run going is let go first. */
40
+ const DEFAULT_CAPACITY = 5000
41
+
42
+ /** What a visitor's run must say about itself. */
43
+ export interface RunState {
44
+ readonly ended: boolean
45
+ }
46
+
47
+ export interface Visitor<R extends RunState> {
48
+ readonly id: string
49
+ readonly token: string
50
+ /** The visitor in the audit: a short hash, never the cookie itself. */
51
+ readonly tag: string
52
+ /** The visitor's latest run, going or ended (what a page that loads shows again). */
53
+ current: R | undefined
54
+ /** When this visitor's asks of the last hour started. */
55
+ readonly asks: number[]
56
+ lastSeen: number
57
+ }
58
+
59
+ /** Why an ask is refused, with the HTTP status to answer. */
60
+ export interface Refusal {
61
+ readonly error: string
62
+ readonly status: 400 | 409 | 429 | 503
63
+ }
64
+
65
+ export interface VisitorsOptions {
66
+ /** One visitor for every page (development); otherwise one per cookie (the Assistant). */
67
+ readonly shared: boolean
68
+ readonly limits?: AssistantLimits
69
+ readonly now?: () => number
70
+ readonly capacity?: number
71
+ }
72
+
73
+ const newSecret = (): string => randomBytes(24).toString('base64url')
74
+
75
+ /** The value of one cookie in a `Cookie` header. */
76
+ export function cookieValue(header: string | undefined | null, name: string): string | undefined {
77
+ if (header === undefined || header === null) return undefined
78
+ for (const part of header.split(';')) {
79
+ const at = part.indexOf('=')
80
+ if (at === -1) continue
81
+ if (part.slice(0, at).trim() === name) return part.slice(at + 1).trim()
82
+ }
83
+ return undefined
84
+ }
85
+
86
+ /** Whether two secrets are the same, in constant time. */
87
+ export function sameSecret(presented: unknown, expected: string): boolean {
88
+ if (typeof presented !== 'string') return false
89
+ const a = Buffer.from(presented)
90
+ const b = Buffer.from(expected)
91
+ return a.length === b.length && timingSafeEqual(a, b)
92
+ }
93
+
94
+ const minutes = (ms: number): string => {
95
+ const count = Math.max(1, Math.ceil(ms / 60_000))
96
+ return `${String(count)} minute${count === 1 ? '' : 's'}`
97
+ }
98
+
99
+ export class Visitors<R extends RunState> {
100
+ private readonly shared: boolean
101
+ private readonly limits: Required<AssistantLimits>
102
+ private readonly now: () => number
103
+ private readonly capacity: number
104
+ private readonly byId = new Map<string, Visitor<R>>()
105
+ /** When every ask of the last day started, across visitors. */
106
+ private readonly day: number[] = []
107
+ private readonly owner: Visitor<R> | undefined
108
+
109
+ constructor(options: VisitorsOptions) {
110
+ this.shared = options.shared
111
+ this.limits = { ...DEFAULT_LIMITS, ...options.limits }
112
+ this.now = options.now ?? Date.now
113
+ this.capacity = options.capacity ?? DEFAULT_CAPACITY
114
+ this.owner = this.shared ? this.make() : undefined
115
+ }
116
+
117
+ /** The visitor a request belongs to: the owner in development, else the one its cookie names; `undefined` when it names none this app knows. */
118
+ of(cookieHeader: string | undefined | null): Visitor<R> | undefined {
119
+ if (this.owner !== undefined) return this.owner
120
+ const id = cookieValue(cookieHeader, VISITOR_COOKIE)
121
+ const visitor = id === undefined ? undefined : this.byId.get(id)
122
+ if (visitor !== undefined) visitor.lastSeen = this.now()
123
+ return visitor
124
+ }
125
+
126
+ /**
127
+ * The visitor of a session request, made when the request names none. `setCookie` is the header to answer with, only for a new visitor: HttpOnly, SameSite=Strict, the whole
128
+ * app (`Path=/`), a day long, and Secure when the page came over https.
129
+ */
130
+ session(
131
+ cookieHeader: string | undefined | null,
132
+ secure: boolean,
133
+ ): { visitor: Visitor<R>; setCookie?: string } {
134
+ const known = this.of(cookieHeader)
135
+ if (known !== undefined) return { visitor: known }
136
+ const visitor = this.make()
137
+ this.keep(visitor)
138
+ const setCookie = `${VISITOR_COOKIE}=${visitor.id}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${String(DAY_MS / 1000)}${secure ? '; Secure' : ''}`
139
+ return { visitor, setCookie }
140
+ }
141
+
142
+ /** Whether `presented` is this visitor's token. */
143
+ accepts(visitor: Visitor<R> | undefined, presented: unknown): visitor is Visitor<R> {
144
+ return visitor !== undefined && sameSecret(presented, visitor.token)
145
+ }
146
+
147
+ /** Whether any visitor holds this token (a terminal driver checks a request with no other context). */
148
+ knows(cookieHeader: string | undefined | null, presented: unknown): boolean {
149
+ return this.accepts(this.of(cookieHeader), presented)
150
+ }
151
+
152
+ /** The question's length check, which comes before anything is counted. */
153
+ checkMessage(message: string): Refusal | undefined {
154
+ const most = this.shared ? OWNER_MESSAGE_LENGTH : this.limits.messageLength
155
+ if (message === '' || message.length > most)
156
+ return { error: `write a message of at most ${String(most)} characters`, status: 400 }
157
+ return undefined
158
+ }
159
+
160
+ /**
161
+ * Whether this visitor may start a run now. The visitor's own run going is refused first (409); then, for the Assistant, the visitor's hour, the runs going at once and the
162
+ * day. An admitted ask is counted.
163
+ */
164
+ admit(visitor: Visitor<R>): Refusal | undefined {
165
+ if (visitor.current !== undefined && !visitor.current.ended)
166
+ return { error: 'a run is already going; wait for it to end', status: 409 }
167
+ if (this.shared) return undefined
168
+ const now = this.now()
169
+ prune(visitor.asks, now - HOUR_MS)
170
+ prune(this.day, now - DAY_MS)
171
+ const hour = visitor.asks[0]
172
+ if (visitor.asks.length >= this.limits.perVisitorPerHour && hour !== undefined)
173
+ return {
174
+ error: `You have asked ${String(this.limits.perVisitorPerHour)} questions this hour. Ask again in ${minutes(hour + HOUR_MS - now)}.`,
175
+ status: 429,
176
+ }
177
+ let going = 0
178
+ for (const other of this.byId.values())
179
+ if (other.current !== undefined && !other.current.ended) going += 1
180
+ if (going >= this.limits.concurrent)
181
+ return {
182
+ error: 'The assistant is helping other people right now. Ask again in a moment.',
183
+ status: 503,
184
+ }
185
+ const first = this.day[0]
186
+ if (this.day.length >= this.limits.perDay && first !== undefined)
187
+ return {
188
+ error: `The assistant has answered all the questions it can today. It is back in ${minutes(first + DAY_MS - now)}.`,
189
+ status: 429,
190
+ }
191
+ visitor.asks.push(now)
192
+ this.day.push(now)
193
+ return undefined
194
+ }
195
+
196
+ /** How many visitors are kept (for tests and diagnostics). */
197
+ get size(): number {
198
+ return this.owner === undefined ? this.byId.size : 1
199
+ }
200
+
201
+ private make(): Visitor<R> {
202
+ const id = newSecret()
203
+ return {
204
+ id,
205
+ token: newSecret(),
206
+ tag: createHash('sha256').update(id).digest('hex').slice(0, 12),
207
+ current: undefined,
208
+ asks: [],
209
+ lastSeen: this.now(),
210
+ }
211
+ }
212
+
213
+ /** Keep a new visitor; past the capacity, let go of the visitors seen longest ago that have no run going. */
214
+ private keep(visitor: Visitor<R>): void {
215
+ if (this.byId.size >= this.capacity) {
216
+ const idle = [...this.byId.values()]
217
+ .filter((other) => other.current === undefined || other.current.ended)
218
+ .sort((a, b) => a.lastSeen - b.lastSeen)
219
+ for (const other of idle.slice(0, this.byId.size - this.capacity + 1))
220
+ this.byId.delete(other.id)
221
+ }
222
+ this.byId.set(visitor.id, visitor)
223
+ }
224
+ }
225
+
226
+ /** Drop the times up to `since` from the front of an ascending list: an ask exactly an hour (or a day) old is out of the window. */
227
+ function prune(times: number[], since: number): void {
228
+ let drop = 0
229
+ while (drop < times.length && (times[drop] ?? 0) <= since) drop += 1
230
+ if (drop > 0) times.splice(0, drop)
231
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.