@acryldev/drivers 0.0.0-stage → 0.1.1

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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 acrylblends
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ # @acryldev/drivers
2
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.
3
+ The driver contract the agent panel and the driver plugins are written against: chat and terminal drivers, their events, and the registry, with no dependency on Cordis.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ npm install @acryldev/drivers
9
+ ```
10
+
11
+ ## Source and license
12
+
13
+ Part of [ACRYL](https://github.com/acryldev/acryl): [`plugins/drivers`](https://github.com/acryldev/acryl/tree/main/plugins/drivers). MIT license.
package/index.ts ADDED
@@ -0,0 +1,75 @@
1
+ /**
2
+ * The drivers the agent panel can offer, in one registry (the `drivers` service the panel provides). A driver is one of two kinds of session:
3
+ *
4
+ * - `chat`: a message in, the panel's own events out (`text`, `tool`, `error`). The app's agent, the headless coding agents and a harness chat are chat drivers.
5
+ * - `terminal`: bytes in, bytes out, a real pseudo-terminal (the `driver-pty` plugin). Nothing is forced to speak bytes.
6
+ *
7
+ * This package is the contract a driver plugin writes against, with no dependency on Cordis: `acrylblends/drivers` when built, `@acryldev/drivers` in the
8
+ * repository and in an app's `plugins/`. It is a foundation package, so the framework and the panel both depend on it, never the other way round. The
9
+ * panel lists every registered driver and picks the view by `kind`. A plugin that provides drivers injects `drivers`: with no panel mounted it is
10
+ * pending, and a panel without such a plugin simply lists none of its drivers.
11
+ */
12
+ /** One event of a chat run. The panel adds `change` (a plugin was installed or removed) and `done` itself. */
13
+ export type ChatEvent =
14
+ | { readonly event: 'text'; readonly data: { readonly text: string } }
15
+ | { readonly event: 'tool'; readonly data: Record<string, unknown> }
16
+ | { readonly event: 'error'; readonly data: { readonly message: string } }
17
+
18
+ export interface ChatDriver {
19
+ readonly kind: 'chat'
20
+ readonly name: string
21
+ /** Runs one message. Aborting `signal` stops the run. `page` is the door's id of the page whose panel asked, when it sent one: a driver that uses the page drives that one. */
22
+ start(options: { message: string; signal: AbortSignal; page?: string }): AsyncIterable<ChatEvent>
23
+ }
24
+
25
+ /** A live pseudo-terminal session. */
26
+ export interface TerminalSession {
27
+ readonly id: string
28
+ onData(listener: (chunk: string) => void): () => void
29
+ onExit(listener: (code: number | null) => void): () => void
30
+ write(data: string): void
31
+ resize(cols: number, rows: number): void
32
+ /** Resolves when the process (group) is gone. */
33
+ kill(): Promise<void>
34
+ }
35
+
36
+ export interface TerminalDriver {
37
+ readonly kind: 'terminal'
38
+ readonly name: string
39
+ /**
40
+ * Where the panel loads the terminal view from: the browser module that draws it, and the URL prefix the view's endpoints live under. The driver
41
+ * plugin serves both, so the view follows wherever the app is mounted (the root of its own server, or the prefix the ACRYL frame serves it at).
42
+ */
43
+ readonly view: { readonly module: string; readonly prefix: string }
44
+ start(options: {
45
+ cwd: string
46
+ env: NodeJS.ProcessEnv
47
+ cols: number
48
+ rows: number
49
+ }): TerminalSession
50
+ }
51
+
52
+ export type Driver = ChatDriver | TerminalDriver
53
+
54
+ export interface Drivers {
55
+ /** Add a driver. Returns the function that removes it; a plugin registers inside `ctx.effect` so the driver leaves with it. */
56
+ register(driver: Driver): () => void
57
+ list(): Driver[]
58
+ get(name: string): Driver | undefined
59
+ /** Whether a request may use the drivers' endpoints: it comes from the app's own page and carries the panel's token. */
60
+ authorized(headers: Headers): boolean
61
+ }
62
+
63
+ export function createDrivers(authorized: (headers: Headers) => boolean = () => true): Drivers {
64
+ const table = new Map<string, Driver>()
65
+ return {
66
+ register(driver) {
67
+ if (table.has(driver.name)) throw new Error(`driver "${driver.name}" is already registered`)
68
+ table.set(driver.name, driver)
69
+ return () => void (table.get(driver.name) === driver && table.delete(driver.name))
70
+ },
71
+ list: () => [...table.values()],
72
+ get: (name) => table.get(name),
73
+ authorized,
74
+ }
75
+ }
package/lib/index.js ADDED
@@ -0,0 +1,18 @@
1
+ //#region index.ts
2
+ function createDrivers(authorized = () => true) {
3
+ const table = /* @__PURE__ */ new Map();
4
+ return {
5
+ register(driver) {
6
+ if (table.has(driver.name)) throw new Error(`driver "${driver.name}" is already registered`);
7
+ table.set(driver.name, driver);
8
+ return () => void (table.get(driver.name) === driver && table.delete(driver.name));
9
+ },
10
+ list: () => [...table.values()],
11
+ get: (name) => table.get(name),
12
+ authorized
13
+ };
14
+ }
15
+ //#endregion
16
+ export { createDrivers };
17
+
18
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","names":[],"sources":["../index.ts"],"sourcesContent":["/**\n * The drivers the agent panel can offer, in one registry (the `drivers` service the panel provides). A driver is one of two kinds of session:\n *\n * - `chat`: a message in, the panel's own events out (`text`, `tool`, `error`). The app's agent, the headless coding agents and a harness chat are chat drivers.\n * - `terminal`: bytes in, bytes out, a real pseudo-terminal (the `driver-pty` plugin). Nothing is forced to speak bytes.\n *\n * This package is the contract a driver plugin writes against, with no dependency on Cordis: `acrylblends/drivers` when built, `@acryldev/drivers` in the\n * repository and in an app's `plugins/`. It is a foundation package, so the framework and the panel both depend on it, never the other way round. The\n * panel lists every registered driver and picks the view by `kind`. A plugin that provides drivers injects `drivers`: with no panel mounted it is\n * pending, and a panel without such a plugin simply lists none of its drivers.\n */\n/** One event of a chat run. The panel adds `change` (a plugin was installed or removed) and `done` itself. */\nexport type ChatEvent =\n | { readonly event: 'text'; readonly data: { readonly text: string } }\n | { readonly event: 'tool'; readonly data: Record<string, unknown> }\n | { readonly event: 'error'; readonly data: { readonly message: string } }\n\nexport interface ChatDriver {\n readonly kind: 'chat'\n readonly name: string\n /** Runs one message. Aborting `signal` stops the run. `page` is the door's id of the page whose panel asked, when it sent one: a driver that uses the page drives that one. */\n start(options: { message: string; signal: AbortSignal; page?: string }): AsyncIterable<ChatEvent>\n}\n\n/** A live pseudo-terminal session. */\nexport interface TerminalSession {\n readonly id: string\n onData(listener: (chunk: string) => void): () => void\n onExit(listener: (code: number | null) => void): () => void\n write(data: string): void\n resize(cols: number, rows: number): void\n /** Resolves when the process (group) is gone. */\n kill(): Promise<void>\n}\n\nexport interface TerminalDriver {\n readonly kind: 'terminal'\n readonly name: string\n /**\n * Where the panel loads the terminal view from: the browser module that draws it, and the URL prefix the view's endpoints live under. The driver\n * plugin serves both, so the view follows wherever the app is mounted (the root of its own server, or the prefix the ACRYL frame serves it at).\n */\n readonly view: { readonly module: string; readonly prefix: string }\n start(options: {\n cwd: string\n env: NodeJS.ProcessEnv\n cols: number\n rows: number\n }): TerminalSession\n}\n\nexport type Driver = ChatDriver | TerminalDriver\n\nexport interface Drivers {\n /** Add a driver. Returns the function that removes it; a plugin registers inside `ctx.effect` so the driver leaves with it. */\n register(driver: Driver): () => void\n list(): Driver[]\n get(name: string): Driver | undefined\n /** Whether a request may use the drivers' endpoints: it comes from the app's own page and carries the panel's token. */\n authorized(headers: Headers): boolean\n}\n\nexport function createDrivers(authorized: (headers: Headers) => boolean = () => true): Drivers {\n const table = new Map<string, Driver>()\n return {\n register(driver) {\n if (table.has(driver.name)) throw new Error(`driver \"${driver.name}\" is already registered`)\n table.set(driver.name, driver)\n return () => void (table.get(driver.name) === driver && table.delete(driver.name))\n },\n list: () => [...table.values()],\n get: (name) => table.get(name),\n authorized,\n }\n}\n"],"mappings":";AA8DA,SAAgB,cAAc,mBAAkD,MAAe;CAC7F,MAAM,wBAAQ,IAAI,IAAoB;CACtC,OAAO;EACL,SAAS,QAAQ;GACf,IAAI,MAAM,IAAI,OAAO,IAAI,GAAG,MAAM,IAAI,MAAM,WAAW,OAAO,KAAK,wBAAwB;GAC3F,MAAM,IAAI,OAAO,MAAM,MAAM;GAC7B,aAAa,MAAM,MAAM,IAAI,OAAO,IAAI,MAAM,UAAU,MAAM,OAAO,OAAO,IAAI;EAClF;EACA,YAAY,CAAC,GAAG,MAAM,OAAO,CAAC;EAC9B,MAAM,SAAS,MAAM,IAAI,IAAI;EAC7B;CACF;AACF"}
@@ -0,0 +1,74 @@
1
+ /**
2
+ * The drivers the agent panel can offer, in one registry (the `drivers` service the panel provides). A driver is one of two kinds of session:
3
+ *
4
+ * - `chat`: a message in, the panel's own events out (`text`, `tool`, `error`). The app's agent, the headless coding agents and a harness chat are chat drivers.
5
+ * - `terminal`: bytes in, bytes out, a real pseudo-terminal (the `driver-pty` plugin). Nothing is forced to speak bytes.
6
+ *
7
+ * This package is the contract a driver plugin writes against, with no dependency on Cordis: `acrylblends/drivers` when built, `@acryldev/drivers` in the
8
+ * repository and in an app's `plugins/`. It is a foundation package, so the framework and the panel both depend on it, never the other way round. The
9
+ * panel lists every registered driver and picks the view by `kind`. A plugin that provides drivers injects `drivers`: with no panel mounted it is
10
+ * pending, and a panel without such a plugin simply lists none of its drivers.
11
+ */
12
+ /** One event of a chat run. The panel adds `change` (a plugin was installed or removed) and `done` itself. */
13
+ export type ChatEvent = {
14
+ readonly event: 'text';
15
+ readonly data: {
16
+ readonly text: string;
17
+ };
18
+ } | {
19
+ readonly event: 'tool';
20
+ readonly data: Record<string, unknown>;
21
+ } | {
22
+ readonly event: 'error';
23
+ readonly data: {
24
+ readonly message: string;
25
+ };
26
+ };
27
+ export interface ChatDriver {
28
+ readonly kind: 'chat';
29
+ readonly name: string;
30
+ /** Runs one message. Aborting `signal` stops the run. `page` is the door's id of the page whose panel asked, when it sent one: a driver that uses the page drives that one. */
31
+ start(options: {
32
+ message: string;
33
+ signal: AbortSignal;
34
+ page?: string;
35
+ }): AsyncIterable<ChatEvent>;
36
+ }
37
+ /** A live pseudo-terminal session. */
38
+ export interface TerminalSession {
39
+ readonly id: string;
40
+ onData(listener: (chunk: string) => void): () => void;
41
+ onExit(listener: (code: number | null) => void): () => void;
42
+ write(data: string): void;
43
+ resize(cols: number, rows: number): void;
44
+ /** Resolves when the process (group) is gone. */
45
+ kill(): Promise<void>;
46
+ }
47
+ export interface TerminalDriver {
48
+ readonly kind: 'terminal';
49
+ readonly name: string;
50
+ /**
51
+ * Where the panel loads the terminal view from: the browser module that draws it, and the URL prefix the view's endpoints live under. The driver
52
+ * plugin serves both, so the view follows wherever the app is mounted (the root of its own server, or the prefix the ACRYL frame serves it at).
53
+ */
54
+ readonly view: {
55
+ readonly module: string;
56
+ readonly prefix: string;
57
+ };
58
+ start(options: {
59
+ cwd: string;
60
+ env: NodeJS.ProcessEnv;
61
+ cols: number;
62
+ rows: number;
63
+ }): TerminalSession;
64
+ }
65
+ export type Driver = ChatDriver | TerminalDriver;
66
+ export interface Drivers {
67
+ /** Add a driver. Returns the function that removes it; a plugin registers inside `ctx.effect` so the driver leaves with it. */
68
+ register(driver: Driver): () => void;
69
+ list(): Driver[];
70
+ get(name: string): Driver | undefined;
71
+ /** Whether a request may use the drivers' endpoints: it comes from the app's own page and carries the panel's token. */
72
+ authorized(headers: Headers): boolean;
73
+ }
74
+ export declare function createDrivers(authorized?: (headers: Headers) => boolean): Drivers;
@@ -0,0 +1,2 @@
1
+ declare const _default: import("tsdown").UserConfig;
2
+ export default _default;
package/package.json CHANGED
@@ -1,6 +1,37 @@
1
1
  {
2
2
  "name": "@acryldev/drivers",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "description": "The driver contract the agent panel and the driver plugins are written against: chat and terminal drivers, their events, and the registry, with no dependency on Cordis.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/acryldev/acryl.git",
9
+ "directory": "plugins/drivers"
10
+ },
11
+ "homepage": "https://github.com/acryldev/acryl/tree/main/plugins/drivers#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/acryldev/acryl/issues"
14
+ },
15
+ "type": "module",
16
+ "engines": {
17
+ "node": "^22.19.0 || >=24.0.0"
18
+ },
19
+ "main": "./lib/index.js",
20
+ "types": "./lib/types/index.d.ts",
21
+ "exports": {
22
+ ".": {
23
+ "types": "./lib/types/index.d.ts",
24
+ "default": "./lib/index.js"
25
+ },
26
+ "./package.json": "./package.json"
27
+ },
28
+ "dependencies": {},
29
+ "devDependencies": {
30
+ "@types/node": "^22.20.0",
31
+ "tsdown": "0.22.2",
32
+ "typescript": "6.0.3"
33
+ },
34
+ "scripts": {
35
+ "build": "tsdown && tsc -p tsconfig.json --emitDeclarationOnly"
36
+ }
6
37
  }
package/plugin.json ADDED
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "drivers",
3
+ "description": "The driver contract the agent panel and the driver plugins are written against: chat and terminal drivers, their events, and the registry, with no dependency on Cordis. Built as acrylblends/drivers.",
4
+ "requires": [],
5
+ "inject": [],
6
+ "provides": [],
7
+ "dependencies": {},
8
+ "entries": {
9
+ "": "index.ts"
10
+ }
11
+ }
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,14 @@
1
+ import { defineConfig } from 'tsdown'
2
+
3
+ export default defineConfig({
4
+ name: '@acryldev/drivers',
5
+ entry: { index: 'index.ts' },
6
+ outDir: 'lib',
7
+ format: 'esm',
8
+ platform: 'node',
9
+ target: 'es2024',
10
+ fixedExtension: false,
11
+ dts: false,
12
+ clean: true,
13
+ sourcemap: true,
14
+ })