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

package/dist/agent/session.js

@@ -1,9 +1,8 @@
 // One connection to the server: says hello, with its signature of the server's challenge when it logs in with a key,
 // answers each request, and sends streamed output only as far as the server's credit allows. Closing it stops the
 // streams it was sending; long runs carry on.
-import { run_command, stream_command } from "./commands.js";
 import { sign_challenge } from "./keys.js";
-import { encode_chunk, encode_message, is_server_message, parse_server_message, protocol_version, } from "./protocol.js";
+import { encode_chunk, encode_message, is_server_message, parse_server_message, } from "./protocol.js";
 const socket_open = 1;
 // ── Output ───────────────────────────────────────────────────────────────────
 // Sends a stream's stdout as binary frames within the credit granted, then its end once all of it has gone.
@@ -90,14 +89,14 @@ export class AgentSession {
     }
     say_hello(signature) {
         this.greeted = true;
-        const hello = { type: "hello", protocol: protocol_version, host: this.options.host, agent_version: this.options.agent_version, runs: this.runs.list() };
+        const hello = { type: "hello", protocol: this.options.app.protocol_version, host: this.options.host, agent_version: this.options.agent_version, runs: this.runs.list() };
         this.send(signature === undefined ? hello : { ...hello, signature });
         this.options.on_hello?.(this);
     }
     // Handles one text frame from the server; anything that is not a message is ignored.
     receive(text) {
         this.last_heard = Date.now();
-        const message = parse_server_message(text);
+        const message = parse_server_message(text, this.options.app);
         if (message === null)
             return;
         if (is_server_message(message))
@@ -118,7 +117,7 @@ export class AgentSession {
     // ── Sending ──────────────────────────────────────────────────────────────
     send(message) {
         if (!this.closed && this.socket.readyState === socket_open)
-            this.socket.send(encode_message(message));
+            this.socket.send(encode_message(message, this.options.app));
     }
     send_chunk(id, data) {
         if (!this.closed && this.socket.readyState === socket_open)
@@ -138,7 +137,7 @@ export class AgentSession {
                 return;
             case "challenge":
                 if (this.options.key && !this.greeted)
-                    this.say_hello(sign_challenge(this.options.key, this.options.app, this.options.host, message.nonce));
+                    this.say_hello(sign_challenge(this.options.key, this.options.app.name, this.options.host, message.nonce));
                 return;
             case "credit":
                 this.pumps.get(message.id)?.grant(message.bytes);
@@ -147,7 +146,7 @@ export class AgentSession {
                 this.pumps.get(message.id)?.cancel();
                 return;
             case "stream":
-                this.start_pump(message.id, () => stream_command(message.command, { stdin: message.stdin }), message.window);
+                this.start_pump(message.id, () => this.open_stream(message.task, message.stdin), message.window);
                 return;
             case "attach":
                 this.start_pump(message.id, () => this.runs.tail(message.run_id, message.offset), message.window);
@@ -192,12 +191,17 @@ export class AgentSession {
             this.send({ type: "failed", id, error: error.message });
         }
     }
+    open_stream(task, stdin) {
+        if (this.options.runner.stream === undefined)
+            throw new Error("This agent does not stream its tasks.");
+        return this.options.runner.stream(task, { stdin });
+    }
     async value_for(message) {
         switch (message.type) {
             case "run":
-                return run_command(message.command, { timeout_in_seconds: message.timeout_in_seconds, stdin: message.stdin });
+                return this.options.runner.run(message.task, { timeout_in_seconds: message.timeout_in_seconds, stdin: message.stdin });
             case "start":
-                return this.runs.start(message.run_id, message.command, message.stdin);
+                return this.runs.start(message.run_id, message.task, message.stdin);
             case "poll":
                 return this.runs.poll(message.run_id, message.offset);
             case "stop":

package/dist/agent/tasks.d.ts

@@ -0,0 +1,17 @@
+import { type CommandStream } from "./commands.ts";
+import type { RunResult } from "./protocol.ts";
+export interface LongRunLaunch {
+    program: string;
+    args: string[];
+}
+export interface TaskRunner<Task> {
+    run(task: Task, options: {
+        timeout_in_seconds: number;
+        stdin?: string | null;
+    }): Promise<RunResult>;
+    stream?(task: Task, options: {
+        stdin?: string | null;
+    }): CommandStream;
+    launch(task: Task, folder: string, has_stdin: boolean): LongRunLaunch;
+}
+export declare function shell_runner(process_name: string): TaskRunner<string>;

package/dist/agent/tasks.js

@@ -0,0 +1,15 @@
+// How an agent carries out the app's tasks: to their end, as a stream, or as a long run's own process. Shell tasks, a
+// command line run by sh, come built in; an app with typed operations gives its own.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { run_command, stream_command } from "./commands.js";
+// ── Shell ────────────────────────────────────────────────────────────────────
+// 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"';
+// Runs each task as a command line under sh; `process_name`, such as "x-backups-run", is what ps shows for a long run.
+export function shell_runner(process_name) {
+    return {
+        run: (command, options) => run_command(command, options),
+        stream: (command, options) => stream_command(command, options),
+        launch: (command, folder) => ({ program: "sh", args: ["-c", wrapper, process_name, folder, command] }),
+    };
+}

package/dist/durations.js

@@ -1,36 +1,34 @@
 // Reads durations such as "2h30m" from settings and writes them back in words, for the server and the agent alike.
-const unit_seconds = { w: 604800, d: 86400, h: 3600, m: 60, s: 1 };
-const unit_names = [
-    [604800, "week"], [86400, "day"], [3600, "hour"], [60, "minute"], [1, "second"],
-];
-// A duration in seconds; `key` names the setting in the error.
+import parse from "parse-duration";
+const unit_names = [["weeks", 604800], ["days", 86400], ["hours", 3600], ["minutes", 60], ["seconds", 1]];
+const words = new Intl.DurationFormat("en", { style: "long" });
+// A duration in whole seconds; `key` names the setting in the error.
 export function parse_duration(value, key) {
     if (typeof value === "number" && Number.isFinite(value) && value >= 0)
         return Math.floor(value);
-    const text = String(value).trim().toLowerCase();
-    if (/^\d+$/.test(text))
-        return Number(text);
-    if (!/^(\d+[wdhms])+$/.test(text))
+    const text = String(value).trim();
+    // A bare number is seconds, where parse-duration would read milliseconds.
+    const seconds = /^\d+$/.test(text) ? Number(text) : parse(text, "s");
+    if (seconds === null || seconds === undefined || !Number.isFinite(seconds) || seconds < 0) {
         throw new Error(`\`${key}\` must be a duration such as "1w", "7d", "2h30m" or "60s", not ${JSON.stringify(value)}`);
-    let seconds = 0;
-    for (const [, count, unit] of text.matchAll(/(\d+)([wdhms])/g))
-        seconds += Number(count) * unit_seconds[unit];
-    return seconds;
+    }
+    return Math.floor(seconds);
 }
-// The two largest whole units, such as "1 day 2 hours".
+// The two largest whole units, such as "1 day, 2 hours".
 export function format_duration(seconds) {
-    if (seconds <= 0)
+    if (seconds < 1)
         return "0 seconds";
-    const parts = [];
+    const parts = {};
     let remaining = Math.floor(seconds);
-    for (const [size, name] of unit_names) {
+    for (const [name, size] of unit_names) {
+        if (Object.keys(parts).length === 2)
+            break;
         if (remaining < size)
             continue;
-        const count = Math.floor(remaining / size);
+        parts[name] = Math.floor(remaining / size);
         remaining %= size;
-        parts.push(`${count} ${name}${count === 1 ? "" : "s"}`);
     }
-    return parts.slice(0, 2).join(" ");
+    return words.format(parts);
 }
 export function format_age(seconds) {
     return seconds < 0 ? "never" : `${format_duration(seconds)} ago`;

package/dist/server/agents/agent.d.ts

@@ -14,10 +14,10 @@ export declare class AgentError extends Error {
     constructor(message: string, unreachable?: boolean);
 }
 export declare function ended_stream(stderr: string): CommandStream;
-export interface Agent {
-    run(command: string, options: AgentRunOptions): Promise<RunResult>;
-    stream(command: string, options?: AgentStreamOptions): CommandStream;
-    start(run_id: string, command: string, options?: AgentStreamOptions): Promise<LongRun>;
+export interface Agent<Task> {
+    run(task: Task, options: AgentRunOptions): Promise<RunResult>;
+    stream(task: Task, options?: AgentStreamOptions): CommandStream;
+    start(run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
     poll(run_id: string, offset: number): Promise<LongRunPoll>;
     attach(run_id: string, offset: number): CommandStream;
     stop(run_id: string): Promise<LongRun>;

package/dist/server/agents/connection.d.ts

@@ -1,4 +1,4 @@
-import { type AgentMessage, type AppMessage, type LongRun, type LongRunPoll, type RunResult, type ServerMessage } from "../../agent/protocol.ts";
+import { type AgentApp, type AgentMessage, type AppMessage, type LongRun, type LongRunPoll, type RunResult, type ServerMessage } from "../../agent/protocol.ts";
 import { type Agent, type AgentRunOptions, type AgentStreamOptions, type CommandStream } from "./agent.ts";
 export interface ServerSocket {
     readonly readyState: number;
@@ -16,12 +16,13 @@ export interface ConnectionOptions {
 export type Hello = Omit<Extract<AgentMessage, {
     type: "hello";
 }>, "signature">;
-export declare class AgentConnection implements Agent {
+export declare class AgentConnection<Task> implements Agent<Task> {
     readonly host: string;
     readonly hello: Hello;
     readonly connected_epoch: number;
     on_message: ((message: AppMessage) => void) | null;
     private readonly socket;
+    private readonly app;
     private readonly options;
     private readonly pending;
     private readonly streams;
@@ -29,18 +30,18 @@ export declare class AgentConnection implements Agent {
     private last_heard;
     private readonly heartbeat;
     private closed_reason;
-    constructor(socket: ServerSocket, host: string, hello: Hello, options: ConnectionOptions);
+    constructor(socket: ServerSocket, app: AgentApp<Task>, host: string, hello: Hello, options: ConnectionOptions);
     get is_open(): boolean;
-    run(command: string, options: AgentRunOptions): Promise<RunResult>;
-    stream(command: string, options?: AgentStreamOptions): CommandStream;
-    start(run_id: string, command: string, options?: AgentStreamOptions): Promise<LongRun>;
+    run(task: Task, options: AgentRunOptions): Promise<RunResult>;
+    stream(task: Task, options?: AgentStreamOptions): CommandStream;
+    start(run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
     poll(run_id: string, offset: number): Promise<LongRunPoll>;
     attach(run_id: string, offset: number): CommandStream;
     stop(run_id: string): Promise<LongRun>;
     forget(run_id: string): Promise<void>;
     runs(): Promise<LongRun[]>;
     request(type: string, body?: Record<string, unknown>): Promise<unknown>;
-    send(message: ServerMessage | AppMessage): void;
+    send(message: ServerMessage<Task> | AppMessage): void;
     receive(data: Buffer, is_binary: boolean): void;
     closed(reason: string): void;
     close(code: number, reason: string): void;

package/dist/server/agents/connection.js

@@ -82,6 +82,7 @@ export class AgentConnection {
     // Takes the app's own messages from the agent that are not replies.
     on_message = null;
     socket;
+    app;
     options;
     pending = new Map();
     streams = new Map();
@@ -89,8 +90,9 @@ export class AgentConnection {
     last_heard = Date.now();
     heartbeat;
     closed_reason = null;
-    constructor(socket, host, hello, options) {
+    constructor(socket, app, host, hello, options) {
         this.socket = socket;
+        this.app = app;
         this.host = host;
         this.hello = hello;
         this.options = options;
@@ -101,20 +103,20 @@ export class AgentConnection {
         return this.closed_reason === null;
     }
     // ── Agent ────────────────────────────────────────────────────────────────
-    async run(command, options) {
+    async run(task, options) {
         try {
             const timeout = options.timeout_in_seconds * 1000 + run_reply_slack_in_milliseconds;
-            return await this.send_request("run", { command, stdin: options.stdin ?? null, timeout_in_seconds: options.timeout_in_seconds }, timeout);
+            return await this.send_request("run", { task, stdin: options.stdin ?? null, timeout_in_seconds: options.timeout_in_seconds }, timeout);
         }
         catch (error) {
             return { exit_code: -1, stdout: "", stderr: error.message };
         }
     }
-    stream(command, options = {}) {
-        return this.open_stream((id, window) => ({ type: "stream", id, command, stdin: options.stdin ?? null, window }));
+    stream(task, options = {}) {
+        return this.open_stream((id, window) => ({ type: "stream", id, task, stdin: options.stdin ?? null, window }));
     }
-    start(run_id, command, options = {}) {
-        return this.send_request("start", { run_id, command, stdin: options.stdin ?? null });
+    start(run_id, task, options = {}) {
+        return this.send_request("start", { run_id, task, stdin: options.stdin ?? null });
     }
     poll(run_id, offset) {
         return this.send_request("poll", { run_id, offset });
@@ -137,7 +139,7 @@ export class AgentConnection {
     // ── Socket ───────────────────────────────────────────────────────────────
     send(message) {
         if (this.is_open && this.socket.readyState === socket_open)
-            this.socket.send(encode_message(message));
+            this.socket.send(encode_message(message, this.app));
     }
     // Handles one frame from the agent after its hello.
     receive(data, is_binary) {
@@ -148,7 +150,7 @@ export class AgentConnection {
                 this.streams.get(chunk.id)?.receive(chunk.data);
             return;
         }
-        const message = parse_agent_message(data.toString("utf8"));
+        const message = parse_agent_message(data.toString("utf8"), this.app);
         if (message === null)
             return;
         if (!is_agent_message(message)) {

package/dist/server/agents/hub.d.ts

@@ -1,20 +1,20 @@
 import { EventEmitter } from "node:events";
 import type { IncomingHttpHeaders } from "node:http";
-import { type AppMessage, type LongRun, type LongRunPoll, type RunResult } from "../../agent/protocol.ts";
+import { type AgentApp, type AppMessage, type LongRun, type LongRunPoll, type RunResult } from "../../agent/protocol.ts";
 import { type Agent, type AgentRunOptions, type AgentStreamOptions, type CommandStream } from "./agent.ts";
 import { AgentConnection, type ConnectionOptions, type ServerSocket } from "./connection.ts";
 export interface AgentTokenLookup {
     host_for(token: string): string | null;
     seen?(host: string): void;
 }
-export interface HubOptions {
-    app: string;
+export interface HubOptions<Task> {
+    app: AgentApp<Task>;
     local?: {
         host: string;
-        agent: Agent;
+        agent: Agent<Task>;
     };
     tokens?: AgentTokenLookup;
-    on_message?: (host: string, message: AppMessage, connection: AgentConnection) => void;
+    on_message?: (host: string, message: AppMessage, connection: AgentConnection<Task>) => void;
     hello_timeout_in_milliseconds?: number;
     connection?: Partial<ConnectionOptions>;
 }
@@ -45,8 +45,8 @@ export declare const close_codes: {
     readonly no_hello: 4005;
     readonly bad_key: 4006;
 };
-export declare class AgentHub extends EventEmitter<HubEvents> {
-    readonly app: string;
+export declare class AgentHub<Task> extends EventEmitter<HubEvents> {
+    readonly app: AgentApp<Task>;
     private readonly local;
     private readonly tokens;
     private readonly on_message;
@@ -55,7 +55,7 @@ export declare class AgentHub extends EventEmitter<HubEvents> {
     private readonly connections;
     private readonly logins;
     private agent_keys;
-    constructor(options: HubOptions);
+    constructor(options: HubOptions<Task>);
     set_local_host(host: string): void;
     set_agent_keys(lines: Map<string, string>): void;
     has_agent_key(host: string): boolean;
@@ -70,10 +70,10 @@ export declare class AgentHub extends EventEmitter<HubEvents> {
     is_connected(host: string): boolean;
     status(host: string): AgentStatus | null;
     statuses(): AgentStatus[];
-    agent(host: string): Agent | null;
-    run(host: string, command: string, options: AgentRunOptions): Promise<RunResult>;
-    stream(host: string, command: string, options?: AgentStreamOptions): CommandStream;
-    start(host: string, run_id: string, command: string, options?: AgentStreamOptions): Promise<LongRun>;
+    agent(host: string): Agent<Task> | null;
+    run(host: string, task: Task, options: AgentRunOptions): Promise<RunResult>;
+    stream(host: string, task: Task, options?: AgentStreamOptions): CommandStream;
+    start(host: string, run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
     poll(host: string, run_id: string, offset: number): Promise<LongRunPoll>;
     attach(host: string, run_id: string, offset: number): CommandStream;
     stop(host: string, run_id: string): Promise<LongRun>;

package/dist/server/agents/hub.js

@@ -5,7 +5,7 @@
 import { randomBytes } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { parse_public_key, verify_challenge } from "../../agent/keys.js";
-import { encode_message, is_agent_message, key_host_header, parse_agent_message, protocol_version, } from "../../agent/protocol.js";
+import { encode_message, is_agent_message, key_host_header, parse_agent_message, } from "../../agent/protocol.js";
 import { AgentError, ended_stream } from "./agent.js";
 import { AgentConnection } from "./connection.js";
 // Close codes the hub hangs up with.
@@ -79,7 +79,7 @@ export class AgentHub extends EventEmitter {
     }
     // Who an agent's upgrade request says it is: the host it names to log in with that host's key, or a token's host.
     admit(headers) {
-        const header = key_host_header(this.app);
+        const header = key_host_header(this.app.name);
         const named = headers[header];
         if (typeof named === "string" && named !== "") {
             if (named === this.local?.host)
@@ -105,19 +105,19 @@ export class AgentHub extends EventEmitter {
         const hello_timer = setTimeout(() => socket.close(close_codes.no_hello, "No hello came."), this.hello_timeout);
         const nonce = login === "key" ? randomBytes(32).toString("base64url") : null;
         if (nonce !== null)
-            socket.send(encode_message({ type: "challenge", nonce }));
+            socket.send(encode_message({ type: "challenge", nonce }, this.app));
         socket.on("message", (raw, is_binary) => {
             const data = as_buffer(raw);
             if (connection !== null) {
                 connection.receive(data, is_binary);
                 return;
             }
-            const hello = is_binary ? null : parse_agent_message(data.toString("utf8"));
+            const hello = is_binary ? null : parse_agent_message(data.toString("utf8"), this.app);
             if (hello === null || !is_agent_message(hello) || hello.type !== "hello")
                 return;
             clearTimeout(hello_timer);
-            if (hello.protocol !== protocol_version) {
-                socket.close(close_codes.protocol, `This server speaks agent protocol ${protocol_version}, not ${hello.protocol}.`);
+            if (hello.protocol !== this.app.protocol_version) {
+                socket.close(close_codes.protocol, `This server speaks agent protocol ${this.app.protocol_version}, not ${hello.protocol}.`);
                 return;
             }
             const { signature, ...greeting } = hello;
@@ -126,7 +126,7 @@ export class AgentHub extends EventEmitter {
                 return;
             }
             this.connections.get(host)?.close(close_codes.replaced, "A newer connection from the same host replaced this one.");
-            const current = new AgentConnection(socket, host, greeting, this.connection_options);
+            const current = new AgentConnection(socket, this.app, host, greeting, this.connection_options);
             current.on_message = (message) => this.on_message?.(host, message, current);
             connection = current;
             this.connections.set(host, current);
@@ -149,7 +149,7 @@ export class AgentHub extends EventEmitter {
     }
     proves_key(host, nonce, signature) {
         const declared = this.agent_keys.get(host);
-        return declared !== undefined && typeof signature === "string" && verify_challenge(declared.key, this.app, host, nonce, signature);
+        return declared !== undefined && typeof signature === "string" && verify_challenge(declared.key, this.app.name, host, nonce, signature);
     }
     disconnect(host, code = 1000, reason = "The server hung up.") {
         this.connections.get(host)?.close(code, reason);
@@ -181,15 +181,15 @@ export class AgentHub extends EventEmitter {
     }
     // ── Commands ─────────────────────────────────────────────────────────────
     // A run on a host with no agent answers with exit code -1 rather than rejecting, as a command that failed does.
-    run(host, command, options) {
+    run(host, task, options) {
         const agent = this.agent(host);
-        return agent === null ? Promise.resolve({ exit_code: -1, stdout: "", stderr: not_connected(host) }) : agent.run(command, options);
+        return agent === null ? Promise.resolve({ exit_code: -1, stdout: "", stderr: not_connected(host) }) : agent.run(task, options);
     }
-    stream(host, command, options = {}) {
-        return this.agent(host)?.stream(command, options) ?? ended_stream(not_connected(host));
+    stream(host, task, options = {}) {
+        return this.agent(host)?.stream(task, options) ?? ended_stream(not_connected(host));
     }
-    start(host, run_id, command, options = {}) {
-        return this.require(host).then((agent) => agent.start(run_id, command, options));
+    start(host, run_id, task, options = {}) {
+        return this.require(host).then((agent) => agent.start(run_id, task, options));
     }
     poll(host, run_id, offset) {
         return this.require(host).then((agent) => agent.poll(run_id, offset));

package/dist/server/agents/local.d.ts

@@ -1,17 +1,20 @@
 import { LongRuns, type LongRunOptions } from "../../agent/long_runs.ts";
 import type { AppRequests } from "../../agent/session.ts";
+import type { TaskRunner } from "../../agent/tasks.ts";
 import { type Agent, type AgentRunOptions, type AgentStreamOptions, type CommandStream, type LongRun, type LongRunPoll, type RunResult } from "./agent.ts";
-export interface LocalAgentOptions {
+export interface LocalAgentOptions<Task> {
+    runner: TaskRunner<Task>;
     long_runs?: LongRunOptions;
     requests?: AppRequests;
 }
-export declare class LocalAgent implements Agent {
-    readonly long_runs: LongRuns;
+export declare class LocalAgent<Task> implements Agent<Task> {
+    readonly long_runs: LongRuns<Task>;
+    private readonly runner;
     private readonly requests;
-    constructor(state_directory: string, options?: LocalAgentOptions);
-    run(command: string, options: AgentRunOptions): Promise<RunResult>;
-    stream(command: string, options?: AgentStreamOptions): CommandStream;
-    start(run_id: string, command: string, options?: AgentStreamOptions): Promise<LongRun>;
+    constructor(state_directory: string, options: LocalAgentOptions<Task>);
+    run(task: Task, options: AgentRunOptions): Promise<RunResult>;
+    stream(task: Task, options?: AgentStreamOptions): CommandStream;
+    start(run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
     poll(run_id: string, offset: number): Promise<LongRunPoll>;
     attach(run_id: string, offset: number): CommandStream;
     stop(run_id: string): Promise<LongRun>;

package/dist/server/agents/local.js

@@ -1,26 +1,29 @@
 // The agent built into the server for its own machine. It runs commands itself with no socket between, through the
 // same code a remote agent uses, so a command behaves the same on every host.
 // ── Imports ──────────────────────────────────────────────────────────────────
-import { run_command, stream_command } from "../../agent/commands.js";
 import { LongRuns } from "../../agent/long_runs.js";
 import { AgentError, ended_stream, } from "./agent.js";
 // ── Local agent ──────────────────────────────────────────────────────────────
 export class LocalAgent {
     long_runs;
+    runner;
     requests;
     // Long runs keep their output under the state directory, so they outlive a restart of the server.
-    constructor(state_directory, options = {}) {
-        this.long_runs = new LongRuns(state_directory, options.long_runs);
+    constructor(state_directory, options) {
+        this.runner = options.runner;
+        this.long_runs = new LongRuns(state_directory, options.runner, options.long_runs);
         this.requests = options.requests ?? {};
     }
-    run(command, options) {
-        return run_command(command, options);
+    run(task, options) {
+        return this.runner.run(task, options);
     }
-    stream(command, options = {}) {
-        return stream_command(command, options);
+    stream(task, options = {}) {
+        if (this.runner.stream === undefined)
+            return ended_stream("This agent does not stream its tasks.");
+        return this.runner.stream(task, options);
     }
-    start(run_id, command, options = {}) {
-        return as_agent_error(() => this.long_runs.start(run_id, command, options.stdin ?? null));
+    start(run_id, task, options = {}) {
+        return as_agent_error(() => this.long_runs.start(run_id, task, options.stdin ?? null));
     }
     poll(run_id, offset) {
         return as_agent_error(() => this.long_runs.poll(run_id, offset));

package/dist/server/agents/route.d.ts

@@ -1,3 +1,3 @@
 import type { FastifyInstance } from "fastify";
 import type { AgentHub } from "./hub.ts";
-export declare function register_agent_route(app: FastifyInstance, hub: AgentHub, path?: string): Promise<void>;
+export declare function register_agent_route<Task>(app: FastifyInstance, hub: AgentHub<Task>, path?: string): Promise<void>;

package/dist/server/hash_password.js

@@ -3,46 +3,28 @@
 // ── Imports ──────────────────────────────────────────────────────────────────
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { text } from "node:stream/consumers";
+import password from "@inquirer/password";
 import { account_name_pattern, hash_password, set_account } from "./passwords.js";
 // ── Asking ───────────────────────────────────────────────────────────────────
-// Reads one line without echoing it.
-function ask_hidden(question) {
-    return new Promise((resolve) => {
-        process.stderr.write(question);
-        process.stdin.setRawMode(true);
-        process.stdin.setEncoding("utf8");
-        let answer = "";
-        const on_data = (chunk) => {
-            for (const character of chunk) {
-                if (character === "\r" || character === "\n") {
-                    process.stdin.setRawMode(false);
-                    process.stdin.pause();
-                    process.stdin.off("data", on_data);
-                    process.stderr.write("\n");
-                    resolve(answer);
-                    return;
-                }
-                if (character === "\u0003")
-                    process.exit(130);
-                if (character === "\u007f")
-                    answer = answer.slice(0, -1);
-                else
-                    answer += character;
-            }
-        };
-        process.stdin.on("data", on_data);
-        process.stdin.resume();
-    });
-}
+// Asks twice at a terminal without echoing, on stderr so stdout stays clean; reads one line from a pipe.
 async function read_password() {
     if (!process.stdin.isTTY)
         return (await text(process.stdin)).replace(/\r?\n$/, "");
-    const password = await ask_hidden("Password: ");
-    if (password !== (await ask_hidden("Again: "))) {
-        console.error("The passwords differ.");
-        process.exit(1);
+    const ask = (message) => password({ message, mask: false }, { output: process.stderr });
+    try {
+        const first = await ask("Password:");
+        if (first !== (await ask("Again:"))) {
+            console.error("The passwords differ.");
+            process.exit(1);
+        }
+        return first;
+    }
+    catch (error) {
+        // Ctrl-C at the prompt ends the command as a shell would.
+        if (error.name === "ExitPromptError")
+            process.exit(130);
+        throw error;
     }
-    return password;
 }
 // ── Command ──────────────────────────────────────────────────────────────────
 // Runs the command with `<name> [file]` from argv; `variable` is the environment variable the app reads the file from.