@x-tech-laboratories/x-libs 0.2.0 → 0.4.0

package/README.md

@@ -12,16 +12,18 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 | `agent/keys`                             | Reads and makes OpenSSH ed25519 agent keys; signs and checks the login challenge. |
 | `agent/protocol`                         | The messages between the server and an agent.                                 |
 | `agent/session`, `agent/client`          | The agent's side: `start_agent` dials the server and answers it.              |
+| `agent/tasks`                            | `TaskRunner`, and `shell_runner` for apps whose tasks are command lines.      |
 | `server/agents/hub`                      | `AgentHub`: the agents that have dialled in, and the server's built-in one.   |
 | `server/agents/connection`, `agent`, `local`, `route` | One connected agent, the `Agent` interface, `LocalAgent`, and the Fastify route. |
 | `server/passwords`                       | scrypt hashes and the `name:hash` accounts file.                              |
 | `server/hash_password`                   | The `hash-password` command.                                                  |
 | `web/dom`, `web/format`, `web/router`, `web/theme` | The page's element builder, formatters, hash router and theme choice. |
-| `web/layout`, `web/badges`, `web/states` | Panels, facts, tiles, cards, tabs, crumbs, toolbars, steppers; badges and chips; loading, empty and failed states. |
-| `web/controls`, `web/tables`             | Search boxes, selects, segmented choices, switches, button groups; sortable tables that turn into cards on phones, and a pager. |
-| `web/toasts`, `web/dialogs`, `web/menus` | Toasts with a link or Undo, modal and confirm dialogs, right-click menus and popovers kept on screen. |
-| `web/split`, `web/shell`                 | Pane sizing and resize handles; the sidebar menu, the section it lights up, and the theme button. |
-| `web/preact/*`                           | The same widgets as Preact components: menus, split, controls, layout, dialog, table. |
+| `web/states`, `web/tables`, `web/menus`, `web/split` | `LoginNeeded`; table sorting; menu items and on-screen placement; pane sizing. |
+| `web/preact/shell`                       | `Shell`: top bar, sidebar, theme button, toasts and dialogs; `use_route`.       |
+| `web/preact/layout`, `badges`, `states`  | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows; badges and chips; `use_resource` and its loading states. |
+| `web/preact/time`                        | `Age`: a time as how long ago, with the full stamp on hover. |
+| `web/preact/controls`, `table`           | Segmented choices, button groups, switches, search boxes, selects; sortable tables that turn into cards on phones, and a pager. |
+| `web/preact/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo; modal, confirm and text dialogs openable from anywhere; context menus and popovers; resize handles and splits. |
 
 ```ts
 import { AgentHub } from "@x-tech-laboratories/x-libs/server/agents/hub";
@@ -36,17 +38,25 @@ which an app imports once:
 ```ts
 import "@x-tech-laboratories/halon/halon-tokens.css";
 import "@x-tech-laboratories/halon/halon.css";
-import { data_table } from "@x-tech-laboratories/x-libs/web/tables";
-import { ContextMenu } from "@x-tech-laboratories/x-libs/web/preact/menus";
+import { DataTable } from "@x-tech-laboratories/x-libs/web/preact/table";
+import { toast } from "@x-tech-laboratories/x-libs/web/preact/toasts";
 ```
 
-A request whose session has lapsed throws `LoginNeeded` from `web/states`; `load` and `attempt` pass it on so the page can ask for a login.
+The widgets are Preact components, so a page renders with Preact; `Shell` holds the toasts and dialogs that `toast` and
+`confirm_dialog` open from anywhere. A request whose session has lapsed throws `LoginNeeded` from `web/states`, and
+`use_resource` passes it on as an unhandled rejection, which the page's login listens for.
 
-## The app's name
+## The app and its tasks
 
-The agent modules take the app's name, such as `x-nix`. It names the key login's header (`x-nix-agent-host`), is bound
-into the challenge the agent signs (`x-nix-agent-v1|<host>|<nonce>`), and names a long run's process (`x-nix-run`), so
-agents already deployed for an app keep logging in.
+The server and every agent are given the same `AgentApp`: the app's name, its protocol version, and its tasks.
+
+- The **name**, such as `x-nix`, names the key login's header (`x-nix-agent-host`) and is bound into the challenge the
+  agent signs (`x-nix-agent-v1|<host>|<nonce>`), so agents already deployed for an app keep logging in.
+- A **task** is what a run, a long run or a stream carries: a shell command line for one app, a typed operation for
+  another. The app names the wire field it travels in and checks it. `shell_app("x-backups")` sends a string in
+  `command`.
+- The agent and the server's `LocalAgent` carry tasks out through a `TaskRunner`: `run`, an optional `stream`, and
+  `launch`, the program a long run's process starts as. `shell_runner("x-backups-run")` runs each under `sh`.
 
 ## The app's own messages
 
@@ -67,7 +77,7 @@ npm test
 npm run lint
 ```
 
-`npm publish` builds first.
+`npm pack` and `npm publish` build first.
 
 ## License
 

package/dist/agent/client.d.ts

@@ -1,8 +1,11 @@
 import type { KeyObject } from "node:crypto";
 import { LongRuns, type LongRunOptions } from "./long_runs.ts";
+import { type AgentApp } from "./protocol.ts";
 import { AgentSession, type SessionHooks } from "./session.ts";
-export interface AgentConfig extends SessionHooks {
-    app: string;
+import type { TaskRunner } from "./tasks.ts";
+export interface AgentConfig<Task> extends SessionHooks<Task> {
+    app: AgentApp<Task>;
+    runner: TaskRunner<Task>;
     url: string;
     key_file?: string;
     token_file?: string;
@@ -20,10 +23,10 @@ export declare class AgentConfigError extends Error {
 }
 export declare function check_url(text: string): URL;
 export declare function read_key_file(file: string): KeyObject;
-export interface RunningAgent {
-    readonly runs: LongRuns;
+export interface RunningAgent<Task> {
+    readonly runs: LongRuns<Task>;
     connected(): boolean;
-    session(): AgentSession | null;
+    session(): AgentSession<Task> | null;
     stop(): Promise<void>;
 }
-export declare function start_agent(config: AgentConfig): RunningAgent;
+export declare function start_agent<Task>(config: AgentConfig<Task>): RunningAgent<Task>;

package/dist/agent/client.js

@@ -63,7 +63,7 @@ export function start_agent(config) {
                 throw error;
         }
     }
-    const runs = new LongRuns(config.state_directory, { process_name: `${config.app}-run`, ...config.long_runs });
+    const runs = new LongRuns(config.state_directory, config.runner, config.long_runs);
     const log = config.log ?? ((line) => console.log(line));
     const heartbeat = config.heartbeat_in_milliseconds ?? 15_000;
     const initial = config.backoff_initial_in_milliseconds ?? 1000;
@@ -90,7 +90,7 @@ export function start_agent(config) {
         try {
             if (login.kind === "key") {
                 key = read_key_file(login.file);
-                headers = { [key_host_header(config.app)]: config.host };
+                headers = { [key_host_header(config.app.name)]: config.host };
             }
             else {
                 headers = { authorization: `Bearer ${readFileSync(login.file, "utf8").trim()}` };
@@ -109,7 +109,7 @@ export function start_agent(config) {
             failures = 0;
             log(`Connected to ${url.origin}`);
             session = new AgentSession(current, runs, {
-                app: config.app, host: config.host, agent_version: config.agent_version, heartbeat_in_milliseconds: heartbeat, key,
+                app: config.app, runner: config.runner, host: config.host, agent_version: config.agent_version, heartbeat_in_milliseconds: heartbeat, key,
                 requests: config.requests, on_message: config.on_message, on_hello: config.on_hello,
             });
         });

package/dist/agent/keys.js

@@ -1,10 +1,9 @@
 // A host's agent key: an ed25519 key made by `ssh-keygen -t ed25519 -N ""`, whose private half the agent holds and
 // whose public line the server's config declares. The agent proves it holds the key by signing the server's nonce.
-//
-// Node's crypto reads neither OpenSSH format, so both are read here: the public line `ssh-ed25519 <base64> [comment]`,
-// and the unencrypted `openssh-key-v1` private key, whose 32-byte seed and public key become a JWK.
+// sshpk reads and writes the OpenSSH formats, which Node's crypto does not, and Node's crypto signs.
 // ── Imports ──────────────────────────────────────────────────────────────────
-import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign, verify } from "node:crypto";
+import { createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import sshpk from "sshpk";
 // ── Settings ─────────────────────────────────────────────────────────────────
 export class AgentKeyError extends Error {
     constructor(message) {
@@ -12,13 +11,6 @@ export class AgentKeyError extends Error {
         this.name = "AgentKeyError";
     }
 }
-const ed25519_name = "ssh-ed25519";
-const format_magic = "openssh-key-v1\0";
-// Spelled in parts so secret scanners do not take this file for a key.
-const armor_label = ["OPENSSH", "PRIVATE", "KEY"].join(" ");
-const armor = new RegExp(`-{5}BEGIN ${armor_label}-{5}([\\s\\S]*?)-{5}END ${armor_label}-{5}`);
-const ed25519_public_length = 32;
-const ed25519_private_length = 64;
 // ── Challenge ────────────────────────────────────────────────────────────────
 // What the agent signs: the app, the protocol, the host it logs in as and the server's nonce, so a signature fits one
 // login to one app only; `app` is the app's name, such as "x-nix".
@@ -42,128 +34,48 @@ export function parse_public_key(line) {
     const parts = line.trim().split(/\s+/);
     if (parts.length < 2 || parts[0] === "")
         throw new AgentKeyError('must be an OpenSSH public key line such as "ssh-ed25519 AAAA... comment".');
-    if (parts[0] !== ed25519_name)
+    if (parts[0] !== "ssh-ed25519")
         throw new AgentKeyError(`must be an ssh-ed25519 key, not ${parts[0]}; make one with ssh-keygen -t ed25519.`);
     if (!/^[A-Za-z0-9+/]+={0,2}$/.test(parts[1]))
         throw new AgentKeyError("holds a key that is not base64.");
-    const reader = new WireReader(Buffer.from(parts[1], "base64"), "public key");
-    const blob_type = reader.text();
-    if (blob_type !== ed25519_name)
-        throw new AgentKeyError(`says ssh-ed25519 but holds a ${blob_type} key.`);
-    const public_bytes = reader.bytes();
-    if (public_bytes.length !== ed25519_public_length || !reader.done())
-        throw new AgentKeyError("holds an ed25519 key of the wrong length.");
-    return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: public_bytes.toString("base64url") }, format: "jwk" });
+    let key;
+    try {
+        key = sshpk.parseKey(line.trim(), "ssh");
+    }
+    catch {
+        throw new AgentKeyError("is cut short or damaged.");
+    }
+    if (key.type !== "ed25519")
+        throw new AgentKeyError(`says ssh-ed25519 but holds a ${key.type} key.`);
+    return createPublicKey(key.toString("pkcs8"));
 }
 // The key's SHA256 fingerprint as ssh-keygen -l prints it.
 export function key_fingerprint(line) {
-    const blob = Buffer.from(line.trim().split(/\s+/)[1] ?? "", "base64");
-    return `SHA256:${createHash("sha256").update(blob).digest("base64").replace(/=+$/, "")}`;
+    return sshpk.parseKey(line.trim(), "ssh").fingerprint("sha256").toString();
 }
 // ── Private key ──────────────────────────────────────────────────────────────
 // Reads an unencrypted OpenSSH ed25519 private key; the messages never quote the key itself.
 export function parse_private_key(text) {
-    const armored = armor.exec(text);
-    if (armored === null)
+    if (!/-{5}BEGIN OPENSSH PRIVATE KEY-{5}/.test(text))
         throw new AgentKeyError('is not an OpenSSH private key; make one with ssh-keygen -t ed25519 -N "".');
-    const data = Buffer.from(armored[1].replace(/\s+/g, ""), "base64");
-    if (data.subarray(0, format_magic.length).toString("latin1") !== format_magic) {
-        throw new AgentKeyError("is not in the openssh-key-v1 format.");
-    }
-    const reader = new WireReader(data.subarray(format_magic.length), "private key");
-    const cipher = reader.text();
-    reader.bytes();
-    reader.bytes();
-    if (cipher !== "none") {
-        throw new AgentKeyError(`is encrypted with a passphrase (${cipher}), which the agent cannot type; make it with -N "" and keep it in a secret store instead.`);
+    let key;
+    try {
+        key = sshpk.parsePrivateKey(text, "ssh");
     }
-    if (reader.number() !== 1)
-        throw new AgentKeyError("must hold exactly one key.");
-    reader.bytes();
-    const section = new WireReader(reader.bytes(), "private key");
-    if (section.number() !== section.number())
-        throw new AgentKeyError("is damaged: its check numbers differ.");
-    const type = section.text();
-    if (type !== ed25519_name)
-        throw new AgentKeyError(`must be an ssh-ed25519 key, not ${type}; make one with ssh-keygen -t ed25519.`);
-    const public_bytes = section.bytes();
-    const private_bytes = section.bytes();
-    if (public_bytes.length !== ed25519_public_length || private_bytes.length !== ed25519_private_length) {
-        throw new AgentKeyError("holds an ed25519 key of the wrong length.");
+    catch (error) {
+        if (error.name === "KeyEncryptedError") {
+            throw new AgentKeyError('is encrypted with a passphrase, which the agent cannot type; make it with -N "" and keep it in a secret store instead.');
+        }
+        throw new AgentKeyError("is cut short or damaged.");
     }
-    // The private half is the seed followed by the public key again.
-    if (!private_bytes.subarray(ed25519_public_length).equals(public_bytes))
-        throw new AgentKeyError("is damaged: its two public keys differ.");
-    const x = public_bytes.toString("base64url");
-    const seed = private_bytes.subarray(0, ed25519_public_length).toString("base64url");
-    const private_key = createPrivateKey({ key: { kty: "OKP", crv: "Ed25519", d: seed, x }, format: "jwk" });
-    // A seed that does not give the stored public key would sign with a key the server does not know.
-    if (createPublicKey(private_key).export({ format: "jwk" }).x !== x)
-        throw new AgentKeyError("is damaged: its seed does not match its public key.");
-    return private_key;
+    if (key.type !== "ed25519")
+        throw new AgentKeyError(`must be an ssh-ed25519 key, not ${key.type}; make one with ssh-keygen -t ed25519.`);
+    return createPrivateKey(key.toString("pkcs8"));
 }
 // ── New keys ─────────────────────────────────────────────────────────────────
-// A new ed25519 key in the files ssh-keygen would write: the unencrypted openssh-key-v1 private key and its public line.
+// A new ed25519 key in the files ssh-keygen would write: the unencrypted OpenSSH private key and its public line.
 export function generate_agent_key(comment) {
-    const { privateKey } = generateKeyPairSync("ed25519");
-    const jwk = privateKey.export({ format: "jwk" });
-    const public_bytes = Buffer.from(jwk.x, "base64url");
-    const seed = Buffer.from(jwk.d, "base64url");
-    const public_blob = Buffer.concat([wire_text(ed25519_name), wire_bytes(public_bytes)]);
-    // Both check numbers are the same random number, which tells a reader the section decrypted correctly.
-    const check = randomBytes(4);
-    const section_parts = [check, check, wire_text(ed25519_name), wire_bytes(public_bytes), wire_bytes(Buffer.concat([seed, public_bytes])), wire_text(comment)];
-    let section = Buffer.concat(section_parts);
-    // The section is padded with the bytes 1, 2, 3 and on to a multiple of eight.
-    const padding = (8 - (section.length % 8)) % 8;
-    section = Buffer.concat([section, Buffer.from(Array.from({ length: padding }, (_, index) => index + 1))]);
-    const data = Buffer.concat([
-        Buffer.from(format_magic, "latin1"), wire_text("none"), wire_text("none"), wire_bytes(Buffer.alloc(0)), wire_number(1), wire_bytes(public_blob), wire_bytes(section),
-    ]);
-    const body = data.toString("base64").match(/.{1,70}/g).join("\n");
-    const private_text = `-----BEGIN ${armor_label}-----\n${body}\n-----END ${armor_label}-----\n`;
-    return { private_text, public_line: `${ed25519_name} ${public_blob.toString("base64")} ${comment}` };
-}
-function wire_number(value) {
-    const buffer = Buffer.alloc(4);
-    buffer.writeUInt32BE(value);
-    return buffer;
-}
-function wire_bytes(value) {
-    return Buffer.concat([wire_number(value.length), value]);
-}
-function wire_text(value) {
-    return wire_bytes(Buffer.from(value, "latin1"));
-}
-// ── Reader ───────────────────────────────────────────────────────────────────
-// Reads the SSH wire format: big-endian 32-bit numbers, and strings as a length then that many bytes.
-class WireReader {
-    data;
-    what;
-    offset = 0;
-    constructor(data, what) {
-        this.data = data;
-        this.what = what;
-    }
-    number() {
-        if (this.offset + 4 > this.data.length)
-            throw new AgentKeyError(`is cut short: the ${this.what} ends early.`);
-        const value = this.data.readUInt32BE(this.offset);
-        this.offset += 4;
-        return value;
-    }
-    bytes() {
-        const length = this.number();
-        if (this.offset + length > this.data.length)
-            throw new AgentKeyError(`is cut short: the ${this.what} ends early.`);
-        const value = this.data.subarray(this.offset, this.offset + length);
-        this.offset += length;
-        return value;
-    }
-    text() {
-        return this.bytes().toString("latin1");
-    }
-    done() {
-        return this.offset === this.data.length;
-    }
+    const key = sshpk.generatePrivateKey("ed25519");
+    key.comment = comment;
+    return { private_text: key.toString("ssh"), public_line: key.toPublic().toString("ssh") };
 }

package/dist/agent/long_runs.d.ts

@@ -1,22 +1,22 @@
 import { type CommandStream } from "./commands.ts";
 import { type LongRun, type LongRunPoll } from "./protocol.ts";
+import type { TaskRunner } from "./tasks.ts";
 export declare const poll_limit_in_bytes: number;
 export interface LongRunOptions {
-    process_name?: string;
     kill_grace_in_milliseconds?: number;
     tail_interval_in_milliseconds?: number;
 }
 export declare class LongRunError extends Error {
     constructor(message: string);
 }
-export declare class LongRuns {
+export declare class LongRuns<Task> {
     private readonly directory;
     private readonly grace;
     private readonly tail_interval;
-    private readonly process_name;
+    private readonly runner;
     private readonly children;
-    constructor(state_directory: string, options?: LongRunOptions);
-    start(run_id: string, command: string, stdin: string | null): LongRun;
+    constructor(state_directory: string, runner: TaskRunner<Task>, options?: LongRunOptions);
+    start(run_id: string, task: Task, stdin: string | null): LongRun;
     list(): LongRun[];
     get(run_id: string): LongRun;
     poll(run_id: string, offset: number, limit?: number): Promise<LongRunPoll>;

package/dist/agent/long_runs.js

@@ -1,4 +1,4 @@
-// Long runs: commands that keep going on their own, in their own process group, so they outlive the connection that
+// Long runs: tasks that keep going on their own, in their own process group, so they outlive the connection that
 // started them and the agent itself. Each writes its output and exit code into its own folder under the state
 // directory, which is all a later agent needs to report on it, follow it, or stop it.
 //
@@ -19,8 +19,6 @@ import { is_run_id } from "./protocol.js";
 export const poll_limit_in_bytes = 1024 * 1024;
 // A followed run is read in pieces of this size.
 const tail_chunk_in_bytes = 64 * 1024;
-// The outer shell runs the command with its output in the run's folder, then writes the exit code in one rename.
-const wrapper = 'sh -c "$2" > "$1/out" 2>&1; echo $? > "$1/exit.part"; mv -f "$1/exit.part" "$1/exit"';
 export class LongRunError extends Error {
     constructor(message) {
         super(message);
@@ -32,36 +30,37 @@ export class LongRuns {
     directory;
     grace;
     tail_interval;
-    process_name;
+    runner;
     // The runs this agent started, whose exit it hears of directly.
     children = new Map();
-    constructor(state_directory, options = {}) {
+    constructor(state_directory, runner, options = {}) {
         this.directory = join(state_directory, "runs");
         this.grace = options.kill_grace_in_milliseconds ?? kill_grace_in_milliseconds;
         this.tail_interval = options.tail_interval_in_milliseconds ?? 250;
-        this.process_name = options.process_name ?? "x-libs-run";
+        this.runner = runner;
         mkdirSync(this.directory, { recursive: true, mode: 0o700 });
     }
     // ── Starting ─────────────────────────────────────────────────────────────
-    start(run_id, command, stdin) {
+    start(run_id, task, stdin) {
         const folder = this.folder(run_id);
         if (existsSync(folder))
             throw new LongRunError(`A run named '${run_id}' already exists.`);
         mkdirSync(folder, { mode: 0o700 });
         writeFileSync(join(folder, "out"), "", { mode: 0o600 });
-        const child = spawn("sh", ["-c", wrapper, this.process_name, folder, command], {
+        const launch = this.runner.launch(task, folder, stdin !== null);
+        const child = spawn(launch.program, launch.args, {
             detached: true,
             stdio: [stdin === null ? "ignore" : "pipe", "ignore", "ignore"],
         });
         if (child.pid === undefined) {
             rmSync(folder, { recursive: true, force: true });
-            throw new LongRunError("Could not start sh.");
+            throw new LongRunError(`Could not start ${launch.program}.`);
         }
         if (stdin !== null) {
             child.stdin.on("error", () => { });
             child.stdin.end(stdin);
         }
-        // A wrapper killed before it could write its exit code is given the shell's code for that signal.
+        // A process killed before it could write its exit code is given the shell's code for that signal.
         child.on("exit", (code, signal) => {
             this.children.delete(run_id);
             const exit_file = join(folder, "exit");

package/dist/agent/protocol.d.ts

@@ -1,4 +1,10 @@
-export declare const protocol_version = 1;
+export interface AgentApp<Task> {
+    name: string;
+    protocol_version: number;
+    task_field: string;
+    is_task(value: unknown): value is Task;
+}
+export declare function shell_app(name: string, protocol_version?: number): AgentApp<string>;
 export interface RunResult {
     exit_code: number;
     stdout: string;
@@ -24,10 +30,10 @@ export interface AppMessage {
     type: string;
     [field: string]: unknown;
 }
-export interface Requests {
+export interface Requests<Task> {
     run: {
         body: {
-            command: string;
+            task: Task;
             stdin: string | null;
             timeout_in_seconds: number;
         };
@@ -36,7 +42,7 @@ export interface Requests {
     start: {
         body: {
             run_id: string;
-            command: string;
+            task: Task;
             stdin: string | null;
         };
         reply: LongRun;
@@ -65,17 +71,17 @@ export interface Requests {
         reply: LongRun[];
     };
 }
-export type RequestType = keyof Requests;
-export type RequestMessage = {
+export type RequestType = keyof Requests<unknown>;
+export type RequestMessage<Task> = {
     [K in RequestType]: {
         type: K;
         id: string;
-    } & Requests[K]["body"];
+    } & Requests<Task>[K]["body"];
 }[RequestType];
-export type ServerMessage = RequestMessage | {
+export type ServerMessage<Task> = RequestMessage<Task> | {
     type: "stream";
     id: string;
-    command: string;
+    task: Task;
     stdin: string | null;
     window: number;
 } | {
@@ -128,15 +134,15 @@ export type AgentMessage = {
     type: "pong";
     epoch_ms: number;
 };
-export declare function parse_server_message(text: string): ServerMessage | AppMessage | null;
-export declare function parse_agent_message(text: string): AgentMessage | AppMessage | null;
-export declare function is_server_message(message: ServerMessage | AppMessage): message is ServerMessage;
+export declare function parse_server_message<Task>(text: string, app: AgentApp<Task>): ServerMessage<Task> | AppMessage | null;
+export declare function parse_agent_message(text: string, app: AgentApp<unknown>): AgentMessage | AppMessage | null;
+export declare function is_server_message<Task>(message: ServerMessage<Task> | AppMessage): message is ServerMessage<Task>;
 export declare function is_agent_message(message: AgentMessage | AppMessage): message is AgentMessage;
-export declare function encode_message(message: ServerMessage | AgentMessage | AppMessage): string;
+export declare function encode_message<Task>(message: ServerMessage<Task> | AgentMessage | AppMessage, app: AgentApp<Task>): string;
 export declare function encode_chunk(id: string, data: Uint8Array): Buffer<ArrayBuffer>;
 export declare function decode_chunk(frame: Uint8Array): {
     id: string;
     data: Buffer;
 } | null;
-export declare function key_host_header(app: string): string;
+export declare function key_host_header(app_name: string): string;
 export declare function is_run_id(value: string): boolean;

package/dist/agent/protocol.js

@@ -5,23 +5,28 @@
 // frames tagged with its id, only as far as the credit the server has granted, then one `stream_end`. Either side
 // sends `ping` while idle and drops a connection that has been silent too long.
 //
+// A run, a long run and a stream each carry the app's task: a shell command for one app, a typed operation for another.
+// The app names the field its task travels in and checks it, so each app keeps its own wire format and version.
+//
 // An agent logging in with its host's key, rather than a token, names the host in the upgrade; the server's first
 // message is then a `challenge`, and the agent's hello carries its signature of that nonce (see keys.ts).
 //
 // An app adds its own messages beside these: any other `type` is handed to the app, and one carrying a string `id` is
 // a request the app's handler answers like any other.
-// ── Version ──────────────────────────────────────────────────────────────────
-export const protocol_version = 1;
+// An app whose tasks are shell command lines, sent in a `command` field.
+export function shell_app(name, protocol_version = 1) {
+    return { name, protocol_version, task_field: "command", is_task: (value) => typeof value === "string" };
+}
 const id_fields = { id: "string" };
 const run_fields = { ...id_fields, run_id: "string" };
 const server_fields = {
-    run: { ...id_fields, command: "string", stdin: "string_or_null", timeout_in_seconds: "number" },
-    start: { ...run_fields, command: "string", stdin: "string_or_null" },
+    run: { ...id_fields, task: "task", stdin: "string_or_null", timeout_in_seconds: "number" },
+    start: { ...run_fields, task: "task", stdin: "string_or_null" },
     poll: { ...run_fields, offset: "number" },
     stop: run_fields,
     forget: run_fields,
     runs: id_fields,
-    stream: { ...id_fields, command: "string", stdin: "string_or_null", window: "number" },
+    stream: { ...id_fields, task: "task", stdin: "string_or_null", window: "number" },
     attach: { ...run_fields, offset: "number", window: "number" },
     credit: { ...id_fields, bytes: "number" },
     cancel: id_fields,
@@ -37,9 +42,11 @@ const agent_fields = {
     ping: { epoch_ms: "number" },
     pong: { epoch_ms: "number" },
 };
-function has_kind(value, kind) {
+function has_kind(value, kind, app) {
     if (kind === "any")
         return value !== undefined;
+    if (kind === "task")
+        return app.is_task(value);
     if (kind === "array")
         return Array.isArray(value);
     if (kind === "string_or_null")
@@ -49,7 +56,7 @@ function has_kind(value, kind) {
     return typeof value === kind;
 }
 // A known message with every field it needs, an app's message for any other type, or null for one that is neither.
-function parse_with(text, fields) {
+function parse_with(text, fields, app) {
     let message;
     try {
         message = JSON.parse(text);
@@ -64,19 +71,25 @@ function parse_with(text, fields) {
         return null;
     if (!Object.hasOwn(fields, record.type))
         return record;
-    for (const [name, kind] of Object.entries(fields[record.type])) {
-        if (!has_kind(record[name], kind))
+    // The task arrives in the app's own field and is read as `task`.
+    const known_fields = fields[record.type];
+    if (Object.hasOwn(known_fields, "task") && app.task_field !== "task") {
+        record.task = record[app.task_field];
+        delete record[app.task_field];
+    }
+    for (const [name, kind] of Object.entries(known_fields)) {
+        if (!has_kind(record[name], kind, app))
             return null;
     }
     return message;
 }
 // A message from the server, or null for one that is not a message at all.
-export function parse_server_message(text) {
-    return parse_with(text, server_fields);
+export function parse_server_message(text, app) {
+    return parse_with(text, server_fields, app);
 }
 // A message from an agent, or null for one that is not a message at all.
-export function parse_agent_message(text) {
-    return parse_with(text, agent_fields);
+export function parse_agent_message(text, app) {
+    return parse_with(text, agent_fields, app);
 }
 // Whether a parsed message is one of this protocol's own rather than the app's.
 export function is_server_message(message) {
@@ -85,8 +98,12 @@ export function is_server_message(message) {
 export function is_agent_message(message) {
     return Object.hasOwn(agent_fields, message.type);
 }
-export function encode_message(message) {
-    return JSON.stringify(message);
+// The message as one text frame, with any task in the app's own field.
+export function encode_message(message, app) {
+    if (!Object.hasOwn(server_fields, message.type) || !("task" in message))
+        return JSON.stringify(message);
+    const { task, ...rest } = message;
+    return JSON.stringify({ ...rest, [app.task_field]: task });
 }
 // ── Output frames ────────────────────────────────────────────────────────────
 // A binary frame is one byte giving the id's length, the id, then the output bytes.
@@ -104,8 +121,8 @@ export function decode_chunk(frame) {
 }
 // ── Key login ────────────────────────────────────────────────────────────────
 // The upgrade header an agent logging in with its key names its host in, such as "x-nix-agent-host".
-export function key_host_header(app) {
-    return `${app}-agent-host`;
+export function key_host_header(app_name) {
+    return `${app_name}-agent-host`;
 }
 // ── Long run ids ─────────────────────────────────────────────────────────────
 // A long run's id names its folder on the agent, so it is kept to safe characters.

package/dist/agent/session.d.ts

@@ -1,14 +1,16 @@
 import type { KeyObject } from "node:crypto";
 import type { LongRuns } from "./long_runs.ts";
-import { type AgentMessage, type AppMessage } from "./protocol.ts";
+import { type AgentApp, type AgentMessage, type AppMessage } from "./protocol.ts";
+import type { TaskRunner } from "./tasks.ts";
 export type AppRequests = Record<string, (message: AppMessage) => unknown>;
-export interface SessionHooks {
+export interface SessionHooks<Task> {
     requests?: AppRequests;
-    on_message?: (message: AppMessage, session: AgentSession) => void;
-    on_hello?: (session: AgentSession) => void;
+    on_message?: (message: AppMessage, session: AgentSession<Task>) => void;
+    on_hello?: (session: AgentSession<Task>) => void;
 }
-export interface SessionOptions extends SessionHooks {
-    app: string;
+export interface SessionOptions<Task> extends SessionHooks<Task> {
+    app: AgentApp<Task>;
+    runner: TaskRunner<Task>;
     host: string;
     agent_version: string;
     heartbeat_in_milliseconds: number;
@@ -19,7 +21,7 @@ export interface MessageSocket {
     send(data: string | Uint8Array<ArrayBuffer>): void;
     close(code?: number, reason?: string): void;
 }
-export declare class AgentSession {
+export declare class AgentSession<Task> {
     private readonly socket;
     private readonly runs;
     private readonly options;
@@ -28,7 +30,7 @@ export declare class AgentSession {
     private readonly heartbeat;
     private closed;
     private greeted;
-    constructor(socket: MessageSocket, runs: LongRuns, options: SessionOptions);
+    constructor(socket: MessageSocket, runs: LongRuns<Task>, options: SessionOptions<Task>);
     private say_hello;
     receive(text: string): void;
     close(): void;
@@ -42,6 +44,7 @@ export declare class AgentSession {
     private handle_app;
     private start_pump;
     private answer;
+    private open_stream;
     private value_for;
     private beat;
 }