@haywoodmarx/agent-pager 0.1.0

package/dist/src/shared/guards.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Hand-rolled structural guards for reading an untrusted `unknown` value as a plain JSON-like object.
+ *
+ * Neutral: no domain owns this module, so it must not import from any domain module, and it raises
+ * failures through a caller-supplied `fail` rather than a domain error type. `Reflect.ownKeys` plus a
+ * property-descriptor read (rather than direct property access) defends against a value whose access
+ * throws — a hostile Proxy trap or a getter that runs arbitrary code — so a malformed field fails with
+ * a located diagnostic instead of an uncaught throw.
+ */
+/** Raises a caller's own error for one field path; never returns. */
+export type GuardFailure = (path: string, reason: string) => never;
+/**
+ * Report whether a value is a plain JSON-like object: not null, not an array.
+ * @param value - Untrusted candidate value.
+ * @returns - Whether the value narrows to a record of unknown fields.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Read every own enumerable string-keyed entry of an object, defensively.
+ * @param value - Object to enumerate.
+ * @param path - Field path named in a raised failure.
+ * @param fail - Raises the caller's own error for one field path.
+ * @returns - Enumerated key/value entries in `Reflect.ownKeys` order.
+ */
+export declare function readOwnEnumerableEntries(value: object, path: string, fail: GuardFailure): Array<[string, unknown]>;
+/**
+ * Narrow an untrusted value to a record of its own enumerable fields.
+ * @param value - Untrusted candidate value.
+ * @param path - Field path named in a raised failure.
+ * @param fail - Raises the caller's own error for one field path.
+ * @returns - The value's own enumerable fields as a plain record.
+ */
+export declare function readRecord(value: unknown, path: string, fail: GuardFailure): Record<string, unknown>;
+/**
+ * Narrow an untrusted value to an array, reading each index defensively.
+ * @param value - Untrusted candidate value.
+ * @param path - Field path named in a raised failure.
+ * @param fail - Raises the caller's own error for one field path.
+ * @returns - The array's elements, read defensively in order.
+ */
+export declare function readArray(value: unknown, path: string, fail: GuardFailure): unknown[];
+/** Options for {@link exactFields}. */
+export type ExactFieldsCheck = {
+    /** Record to check. */
+    record: Record<string, unknown>;
+    /** Field names that must be present. */
+    required: readonly string[];
+    /** Field names that may be present. */
+    optional: readonly string[];
+    /** Field path named in a raised failure. */
+    path: string;
+    /** Raises the caller's own error for one field path. */
+    fail: GuardFailure;
+};
+/**
+ * Assert a record carries only permitted fields and every required one.
+ * @param check - Record, its permitted field names, the failure path, and the failure callback.
+ */
+export declare function exactFields({ record, required, optional, path, fail }: ExactFieldsCheck): void;

package/dist/src/shared/guards.js

@@ -0,0 +1,119 @@
+/**
+ * Hand-rolled structural guards for reading an untrusted `unknown` value as a plain JSON-like object.
+ *
+ * Neutral: no domain owns this module, so it must not import from any domain module, and it raises
+ * failures through a caller-supplied `fail` rather than a domain error type. `Reflect.ownKeys` plus a
+ * property-descriptor read (rather than direct property access) defends against a value whose access
+ * throws — a hostile Proxy trap or a getter that runs arbitrary code — so a malformed field fails with
+ * a located diagnostic instead of an uncaught throw.
+ */
+/**
+ * Report whether a value is a plain JSON-like object: not null, not an array.
+ * @param value - Untrusted candidate value.
+ * @returns - Whether the value narrows to a record of unknown fields.
+ */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Read every own enumerable string-keyed entry of an object, defensively.
+ * @param value - Object to enumerate.
+ * @param path - Field path named in a raised failure.
+ * @param fail - Raises the caller's own error for one field path.
+ * @returns - Enumerated key/value entries in `Reflect.ownKeys` order.
+ */
+export function readOwnEnumerableEntries(value, path, fail) {
+    let keys;
+    try {
+        keys = Reflect.ownKeys(value);
+    }
+    catch {
+        fail(path, "fields could not be enumerated");
+    }
+    const entries = [];
+    for (const key of Array.from(keys)) {
+        let descriptor;
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(value, key);
+        }
+        catch {
+            const fieldPath = typeof key === "string" ? `${path}.${key}` : path;
+            fail(fieldPath, "field descriptor could not be read");
+        }
+        if (!descriptor?.enumerable)
+            continue;
+        if (typeof key !== "string")
+            fail(path, "contains a non-string field");
+        let entry;
+        try {
+            entry = Reflect.get(value, key, value);
+        }
+        catch {
+            fail(`${path}.${key}`, "field could not be read");
+        }
+        entries.push([key, entry]);
+    }
+    return entries;
+}
+/**
+ * Narrow an untrusted value to a record of its own enumerable fields.
+ * @param value - Untrusted candidate value.
+ * @param path - Field path named in a raised failure.
+ * @param fail - Raises the caller's own error for one field path.
+ * @returns - The value's own enumerable fields as a plain record.
+ */
+export function readRecord(value, path, fail) {
+    if (!isPlainObject(value))
+        fail(path, "must be an object");
+    const record = {};
+    for (const [key, entry] of readOwnEnumerableEntries(value, path, fail)) {
+        Object.defineProperty(record, key, { value: entry, enumerable: true, configurable: true, writable: true });
+    }
+    return record;
+}
+/**
+ * Narrow an untrusted value to an array, reading each index defensively.
+ * @param value - Untrusted candidate value.
+ * @param path - Field path named in a raised failure.
+ * @param fail - Raises the caller's own error for one field path.
+ * @returns - The array's elements, read defensively in order.
+ */
+export function readArray(value, path, fail) {
+    if (!Array.isArray(value))
+        fail(path, "must be an array");
+    const output = [];
+    let length;
+    try {
+        length = value.length;
+    }
+    catch {
+        fail(`${path}.length`, "field could not be read");
+    }
+    if (!Number.isSafeInteger(length) || length < 0) {
+        fail(`${path}.length`, "must be a non-negative safe integer");
+    }
+    for (let index = 0; index < length; index += 1) {
+        try {
+            output.push(value[index]);
+        }
+        catch {
+            fail(`${path}[${String(index)}]`, "field could not be read");
+        }
+    }
+    return output;
+}
+/**
+ * Assert a record carries only permitted fields and every required one.
+ * @param check - Record, its permitted field names, the failure path, and the failure callback.
+ */
+export function exactFields({ record, required, optional, path, fail }) {
+    const permitted = new Set([...required, ...optional]);
+    for (const key of Object.keys(record)) {
+        if (!permitted.has(key))
+            fail(`${path}.${key}`, "unexpected field");
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(record, key))
+            fail(`${path}.${key}`, "required field is missing");
+    }
+}

package/dist/src/shared/http.d.ts

@@ -0,0 +1,30 @@
+import type { ServerResponse } from "node:http";
+import type { Server } from "node:net";
+/**
+ * Format a bound interface for use in a URL, bracketing an IPv6 literal.
+ * @param host - Interface address a server bound and reported back.
+ * @returns - The host as it belongs in a URL authority.
+ */
+export declare function urlHost(host: string): string;
+/**
+ * Write a JSON response body with the given status and headers.
+ * @param response - Server response to complete.
+ * @param status - HTTP status code.
+ * @param body - Value serialized as the JSON response body.
+ * @param headers - Additional response headers merged with the JSON content type.
+ */
+export declare function writeJson(response: ServerResponse, status: number, body: unknown, headers?: Record<string, string>): void;
+/**
+ * Bind a server, rejecting a bind failure instead of leaving the promise pending.
+ * @param server - Server to bind.
+ * @param port - Port to bind.
+ * @param host - Interface to bind.
+ * @returns - Resolves once the server is listening.
+ */
+export declare function listenServer(server: Server, port: number, host: string): Promise<void>;
+/**
+ * Close a server, rejecting a close failure instead of leaving the promise pending.
+ * @param server - Server to close.
+ * @returns - Resolves once the server has closed, or rejects with its close error.
+ */
+export declare function closeServer(server: Server): Promise<void>;

package/dist/src/shared/http.js

@@ -0,0 +1,50 @@
+/**
+ * Format a bound interface for use in a URL, bracketing an IPv6 literal.
+ * @param host - Interface address a server bound and reported back.
+ * @returns - The host as it belongs in a URL authority.
+ */
+export function urlHost(host) {
+    return host.includes(":") ? `[${host}]` : host;
+}
+/**
+ * Write a JSON response body with the given status and headers.
+ * @param response - Server response to complete.
+ * @param status - HTTP status code.
+ * @param body - Value serialized as the JSON response body.
+ * @param headers - Additional response headers merged with the JSON content type.
+ */
+export function writeJson(response, status, body, headers = {}) {
+    response.writeHead(status, { "content-type": "application/json", ...headers });
+    response.end(JSON.stringify(body));
+}
+/**
+ * Bind a server, rejecting a bind failure instead of leaving the promise pending.
+ * @param server - Server to bind.
+ * @param port - Port to bind.
+ * @param host - Interface to bind.
+ * @returns - Resolves once the server is listening.
+ */
+export function listenServer(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+}
+/**
+ * Close a server, rejecting a close failure instead of leaving the promise pending.
+ * @param server - Server to close.
+ * @returns - Resolves once the server has closed, or rejects with its close error.
+ */
+export function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}

package/dist/src/shared/row.d.ts

@@ -0,0 +1,2 @@
+/** Shape of one SQLite result row before its columns are read into a typed value. */
+export type Row = Record<string, unknown>;

package/dist/src/shared/row.js

@@ -0,0 +1 @@
+export {};

package/dist/src/shared/shell.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Single-quote a value so it reaches a POSIX shell as one word.
+ * @param value - Value to quote.
+ * @returns - The value as a single shell word.
+ */
+export declare function shellQuote(value: string): string;

package/dist/src/shared/shell.js

@@ -0,0 +1,8 @@
+/**
+ * Single-quote a value so it reaches a POSIX shell as one word.
+ * @param value - Value to quote.
+ * @returns - The value as a single shell word.
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/src/tui/actions.d.ts

@@ -0,0 +1,166 @@
+import { type PackagedSkill } from "../launch/skill.js";
+import { type TuiCopyFallbackPort } from "./message-views.js";
+import type { TuiLocalRun, TuiLocalRunSize, TuiOperatorModelState, TuiOperatorViewState } from "./model.js";
+import type { TuiTheme } from "./theme.js";
+/**
+ * Installs into the global scope, leaving every other choice to the operator.
+ *
+ * The child runs in a terminal it can prompt through, so nothing here answers on the operator's
+ * behalf.
+ */
+export declare const SKILL_INSTALL_FLAGS: readonly string[];
+/** Names every skill action in the menu. */
+export declare const SKILL_ACTION_LABEL = "Install skills";
+/** Footer keys of the actions menu. A constant, because JSX collapses runs of spaces in inline text. */
+export declare const ACTIONS_FOOTER_KEYS = "\u23CE select";
+/** The one thing a key asks the shell to do to the local run. */
+export type TuiActionRunRequest = {
+    readonly kind: "none";
+}
+/** Start the command. */
+ | {
+    readonly kind: "start";
+    readonly command: TuiActionCommand;
+}
+/** Discard a finished run's output. */
+ | {
+    readonly kind: "clear";
+}
+/** End the child the operator asked to abandon. */
+ | {
+    readonly kind: "cancel";
+};
+/** Reports the next view and the work the shell must perform on the model's behalf. */
+export type TuiOperatorActionsKeyResult = {
+    /** Next view state, identical to the current one when the key means nothing here. */
+    view: TuiOperatorViewState;
+    /** What the key asks of the local run; a key never asks for more than one. */
+    request: TuiActionRunRequest;
+};
+/** Names the child process one action runs. */
+export type TuiActionCommand = {
+    /** Executable to run. */
+    command: string;
+    /** Arguments passed to the executable. */
+    args: readonly string[];
+    /** The same command as an operator would type it, shown above the terminal and copied on request. */
+    display: string;
+};
+/** One operator action offered by the actions menu. */
+export type TuiOperatorAction = {
+    /** Identifies the action for selection and tests. */
+    id: string;
+    /** Names the action in the menu. */
+    label: string;
+    /** Titles the overlay the action runs in. */
+    title: string;
+    /** Command the action runs. */
+    command: TuiActionCommand;
+};
+/**
+ * Registration this build offers for one agent harness, supplied by the composition root.
+ *
+ * Injected rather than imported because the menu must not name an implementation.
+ */
+export type TuiHostRegistration = {
+    /** Identifies the harness, and the action that registers with it. */
+    id: string;
+    /** Names the harness as the operator knows it. */
+    label: string;
+    /** Command that performs the registration. */
+    command: TuiActionCommand;
+};
+/** Everything the actions menu can offer, resolved once by the composition root. */
+export type TuiActionCatalogue = {
+    /** Skills this build ships, in the order the menu lists them. */
+    readonly skills: readonly PackagedSkill[];
+    /** Harness registrations this build offers, listed after the skills. */
+    readonly registrations: readonly TuiHostRegistration[];
+};
+/**
+ * List the actions the operator may start from the menu, in display order.
+ *
+ * Declared as data so a further action is an entry here rather than a branch in the menu, which
+ * never names a specific action.
+ * @param catalogue - Skills and harness registrations this build offers.
+ * @returns - Every selectable action, in display order.
+ */
+export declare function operatorActions(catalogue: TuiActionCatalogue): readonly TuiOperatorAction[];
+/**
+ * Find the action an overlay was opened for.
+ * @param id - Action id recorded when the action was selected.
+ * @param catalogue - Skills and harness registrations this build offers.
+ * @returns - The action, or undefined when this build no longer offers one by that id.
+ */
+export declare function menuAction(id: string, catalogue: TuiActionCatalogue): TuiOperatorAction | undefined;
+/**
+ * Reduce one key pressed while an action overlay is open.
+ *
+ * Pure. `y`, which copies the command before a run, is the one action-overlay key `ActionRunOverlay`
+ * answers itself.
+ *
+ * Escape during a run ends the child at once, without asking again, so the operator can always leave a
+ * run that will not finish, including an Escape the operator meant for a prompt of the child's own.
+ * @param state - Current model state.
+ * @param key - Key name reported by the terminal.
+ * @param catalogue - Skills and harness registrations this build offers.
+ * @returns - Next view state, unchanged when the key means nothing here, and the run request the key makes.
+ */
+export declare function reduceOperatorActionsKey(state: TuiOperatorModelState, key: string, catalogue: TuiActionCatalogue): TuiOperatorActionsKeyResult;
+/**
+ * Render the operator actions menu.
+ * @param properties - Described on each property below.
+ * @returns Overlay centred over the shell, listing the packaged skills first and then each registration.
+ */
+export declare function ActionsOverlay({ actionIndex, catalogue, theme, onSelect, }: {
+    /** Row highlighted, as an index into the actions the menu lists. */
+    readonly actionIndex: number;
+    /** Skills and harness registrations the menu lists. */
+    readonly catalogue: TuiActionCatalogue;
+    /** Semantic palette the menu draws with. */
+    readonly theme: Readonly<TuiTheme>;
+    /** Called with the action a pointer press chose. */
+    readonly onSelect: (action: TuiOperatorAction) => void;
+}): import("react").ReactNode;
+/**
+ * Colour the outcome so a clean exit and a failure read as such without being read. No run yet, a run
+ * still going, and a cancelled run share the neutral colour; only the status text tells them apart.
+ *
+ * Green marks a zero exit, which says the command finished and nothing more; see `skillInstallStatus`.
+ * @param run - Current run, or null before one has started.
+ * @param theme - Semantic palette the surface draws from.
+ * @returns - Colour for the status shown beside the title.
+ */
+export declare function skillInstallStatusColor(run: TuiLocalRun | null, theme: Readonly<TuiTheme>): string;
+/**
+ * Report the terminal the install's child is given.
+ *
+ * The child lays its output out for this size, and the emulator that renders that output is built to
+ * match, so the two must be read from here rather than each deciding for itself.
+ * @param terminalRows - Rows the whole terminal has.
+ * @returns - Columns and rows of the run overlay's terminal.
+ */
+export declare function skillInstallTerminalSize(terminalRows: number): TuiLocalRunSize;
+/**
+ * Render one action's run: its command, its terminal, its outcome, and the keys it answers.
+ * @param properties - Described on each property below.
+ * @returns The run overlay, or nothing when this build no longer offers the action.
+ */
+export declare function ActionRunOverlay({ run, actionId, catalogue, terminalRows, copyFallback, onInput, onResize, theme, }: {
+    /** Run the model holds, or null before the operator has started one. */
+    readonly run: TuiLocalRun | null;
+    /** Action the overlay was opened for. */
+    readonly actionId: string;
+    /** Skills and harness registrations this build offers, among which the action is looked up. */
+    readonly catalogue: TuiActionCatalogue;
+    /** Rows the whole terminal has, from which the overlay and the child's terminal are sized. */
+    readonly terminalRows: number;
+    /** Native copy used when the terminal cannot take OSC52, or its OSC52 write fails. */
+    readonly copyFallback: TuiCopyFallbackPort;
+    /** Receives the operator's keys, encoded for the child's terminal. */
+    readonly onInput: (bytes: Uint8Array) => void;
+    /** Receives the child terminal's new size when the emulator resizes it. */
+    readonly onResize: (columns: number, rows: number) => void;
+    /** Semantic palette the overlay draws with. */
+    readonly theme: Readonly<TuiTheme>;
+}): import("react").ReactNode;