@chipschat/harness 0.0.0-stage → 1.0.0

package/dist/service.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A harness kept running (setup audit HS-15): a launch agent on a Mac, a systemd user unit on
+ * Linux, that runs the bridge again at login and whenever it stops, so closing the terminal it
+ * joined from, or restarting the machine, doesn't take it offline in Chips. The CLI keeps
+ * `chips serve` running the same way (`cli/src/service.ts`); this is that, for a harness on the
+ * SDK, which cannot depend on the CLI.
+ *
+ * A bridge writes it once it has joined, so the service carries the server's address (`CHIPS_URL`)
+ * and finds the key `join()` kept, and needs no link. Each file says it was written here; one
+ * without those words is somebody's own, a launch agent written by hand, and is left exactly as
+ * it is and said, since its label is the same and a second copy would answer everything twice.
+ *
+ * A bridge kept on the Node that Chips for Mac carries names the app in its launch agent, so macOS's
+ * background-item notice and Login Items say Chips rather than Node (ADR 0218's addendum).
+ *
+ * What the files say is worked out purely; `keepRunning` and `stopKeeping` write them and run the
+ * service manager's commands.
+ */
+import type { Environment } from "./keep.js";
+export type ServiceKind = "launchd" | "systemd";
+/** What to keep running, and how. */
+export interface KeepSpec {
+    /** Its label, `chat.chips.<name>`: `chat.chips.hermes`, `chat.chips.acp.codex`. */
+    readonly label: string;
+    /** The program and its words: `[process.execPath, "--import", "tsx", "src/main.ts"]`. */
+    readonly command: readonly [string, ...string[]];
+    /** Where it runs from: the bridge's own folder. */
+    readonly folder: string;
+    /** Its environment: the server it joined, a PATH that finds its agent (`keepEnvironment`). */
+    readonly environment: Readonly<Record<string, string>>;
+    /** What it says goes here; by default `~/Library/Logs/chips-<name>.log`, or under `~/.local/state/chips`. */
+    readonly logFile?: string | undefined;
+}
+/** Where the machine keeps things, and which machine it is. */
+export interface Machine {
+    readonly platform: string;
+    readonly home: string;
+    readonly env: Environment;
+}
+/** The service's file, worked out: which manager, where it goes, and what it says. */
+export interface ServiceFile {
+    readonly kind: ServiceKind;
+    readonly path: string;
+    readonly contents: string;
+    readonly logFile: string;
+}
+/** A command, as its words. */
+export type Command = readonly [string, ...string[]];
+/** What became of a keep, or a stop. */
+export interface Kept {
+    /**
+     * `kept` running; `theirs`, a file of somebody's own was there and left; `unsupported`, no
+     * manager here; `off`, `CHIPS_KEEP=off` said not to (a test running a card's line as written).
+     */
+    readonly state: "kept" | "theirs" | "unsupported" | "off";
+    readonly path?: string | undefined;
+    readonly logFile?: string | undefined;
+}
+export declare function serviceKind(platform: string): ServiceKind | undefined;
+/** The service's file for `spec` on `machine`, or nothing where there is no service manager. */
+export declare function serviceFile(spec: KeepSpec, given?: Partial<Machine>): ServiceFile | undefined;
+/**
+ * The Mac app whose bundle holds `program`, by its bundle identifier: the Node Chips for Mac
+ * carries, `Chips.app/Contents/Resources/chips/runtime/node`, is `chat.chips.desktop`'s. Nothing
+ * for a program outside an app, or an app whose `Info.plist` doesn't say. macOS names a launch
+ * agent after the app it names only when the program is signed by that app's team, which
+ * `pnpm desktop` does for the Node it carries.
+ */
+export declare function appHolding(program: string, read?: (path: string) => string): string | undefined;
+/**
+ * The launch agent: run from login, run again whenever it stops; credited to `app`, by its bundle
+ * identifier, where its program is inside one.
+ */
+export declare function launchdPlist(spec: KeepSpec, logFile: string, app?: string): string;
+/** The systemd user unit: run from login, run again whenever it stops. */
+export declare function systemdUnit(spec: KeepSpec, logFile: string): string;
+/** Run it now: load the agent (afresh, when it is loaded), or enable the unit and start it again. */
+export declare function startCommands(kind: ServiceKind, label: string, path: string, uid: number): readonly Command[];
+/** Stop it, and keep it from starting at the next login. */
+export declare function stopCommands(kind: ServiceKind, label: string, uid: number): readonly Command[];
+/**
+ * What a kept bridge needs from the shell it was joined from: the server's address, so `join()`
+ * finds the key it kept; the PATH, so its agent's command is found; Chips's own settings (never
+ * what was handed over for the run alone, the spent link among them); and the names a bridge asks
+ * for, where they are set. Given the `node` it is kept on, that node's folder comes first on the
+ * PATH: an agent run as `#!/usr/bin/env node` (an ACP adapter) finds it on a machine with no Node
+ * of its own.
+ */
+export declare function keepEnvironment(url: string, env?: Environment, names?: readonly string[], node?: string): Record<string, string>;
+/**
+ * The node a kept bridge runs on: the one `chips connect` hands over (`CHIPS_NODE`), named by a
+ * path an upgrade of Chips keeps (`~/.local/lib/chips/current/runtime/node`, or inside Chips.app);
+ * else the first on the PATH, as `npm start` runs it (`nodeOnPath`).
+ */
+export declare function keptNode(env?: Environment): string;
+/**
+ * The node a kept bridge runs on: the first on the PATH, as `npm start` runs it, which is the link
+ * a package manager keeps (Homebrew's `/opt/homebrew/bin/node`); `process.execPath` is the
+ * version's own folder, which the next upgrade removes, and the service with it. This process's
+ * own where none is on the PATH.
+ */
+export declare function nodeOnPath(env?: Environment): string;
+interface Running {
+    readonly machine?: Partial<Machine> | undefined;
+    /** Runs a command, throwing when it fails, and answers its output; the machine's own by default. */
+    readonly run?: ((command: Command) => unknown) | undefined;
+    readonly uid?: number | undefined;
+    /** How long to wait between tries to load it again while launchd lets the old copy go (250 ms). */
+    readonly retryMs?: number | undefined;
+    /** Where a word for the person who kept it goes: standard error by default. */
+    readonly say?: ((line: string) => void) | undefined;
+}
+/**
+ * Write the service and run it, replacing one written here before. A file of somebody's own at
+ * that place is left as it is: `theirs`.
+ */
+export declare function keepRunning(spec: KeepSpec, options?: Running): Kept;
+/** Stop a service written here, and remove its file. One of somebody's own is left: `theirs`. */
+export declare function stopKeeping(label: string, options?: Running): {
+    readonly state: "stopped" | "none" | "theirs" | "unsupported";
+    readonly path?: string;
+};
+export {};
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -0,0 +1,349 @@
+/**
+ * A harness kept running (setup audit HS-15): a launch agent on a Mac, a systemd user unit on
+ * Linux, that runs the bridge again at login and whenever it stops, so closing the terminal it
+ * joined from, or restarting the machine, doesn't take it offline in Chips. The CLI keeps
+ * `chips serve` running the same way (`cli/src/service.ts`); this is that, for a harness on the
+ * SDK, which cannot depend on the CLI.
+ *
+ * A bridge writes it once it has joined, so the service carries the server's address (`CHIPS_URL`)
+ * and finds the key `join()` kept, and needs no link. Each file says it was written here; one
+ * without those words is somebody's own, a launch agent written by hand, and is left exactly as
+ * it is and said, since its label is the same and a second copy would answer everything twice.
+ *
+ * A bridge kept on the Node that Chips for Mac carries names the app in its launch agent, so macOS's
+ * background-item notice and Login Items say Chips rather than Node (ADR 0218's addendum).
+ *
+ * What the files say is worked out purely; `keepRunning` and `stopKeeping` write them and run the
+ * service manager's commands.
+ */
+import { execFileSync } from "node:child_process";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { reportStep } from "./steps.js";
+const MARK = "Written by a Chips harness's keep";
+export function serviceKind(platform) {
+    if (platform === "darwin")
+        return "launchd";
+    if (platform === "linux")
+        return "systemd";
+    return undefined;
+}
+const machineOf = (given = {}) => ({
+    platform: given.platform ?? process.platform,
+    home: given.home ?? homedir(),
+    // biome-ignore lint/style/noProcessEnv: the environment is where the machine says where things go.
+    env: given.env ?? process.env,
+});
+/** `chat.chips.acp.codex` → `chips-acp-codex`: the name its log is kept under. */
+const logName = (label) => `${label.replace(/^chat\.chips\./, "chips-").replace(/\./g, "-")}.log`;
+/** The service's file for `spec` on `machine`, or nothing where there is no service manager. */
+export function serviceFile(spec, given = {}) {
+    const machine = machineOf(given);
+    const kind = serviceKind(machine.platform);
+    if (kind === undefined)
+        return undefined;
+    if (kind === "launchd") {
+        const logFile = spec.logFile ?? join(machine.home, "Library", "Logs", logName(spec.label));
+        const path = join(machine.home, "Library", "LaunchAgents", `${spec.label}.plist`);
+        return {
+            kind,
+            path,
+            logFile,
+            contents: launchdPlist(spec, logFile, appHolding(spec.command[0])),
+        };
+    }
+    const xdg = (name, fallback) => {
+        const set = machine.env[name];
+        return set !== undefined && set !== "" ? set : join(machine.home, fallback);
+    };
+    const logFile = spec.logFile ?? join(xdg("XDG_STATE_HOME", ".local/state"), "chips", logName(spec.label));
+    const path = join(xdg("XDG_CONFIG_HOME", ".config"), "systemd", "user", `${spec.label}.service`);
+    return { kind, path, logFile, contents: systemdUnit(spec, logFile) };
+}
+const xml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/**
+ * The Mac app whose bundle holds `program`, by its bundle identifier: the Node Chips for Mac
+ * carries, `Chips.app/Contents/Resources/chips/runtime/node`, is `chat.chips.desktop`'s. Nothing
+ * for a program outside an app, or an app whose `Info.plist` doesn't say. macOS names a launch
+ * agent after the app it names only when the program is signed by that app's team, which
+ * `pnpm desktop` does for the Node it carries.
+ */
+export function appHolding(program, read = (path) => readFileSync(path, "utf8")) {
+    const app = /^(.+?\.app)\/Contents\//.exec(program)?.[1];
+    if (app === undefined)
+        return undefined;
+    try {
+        const info = read(join(app, "Contents", "Info.plist"));
+        return /<key>CFBundleIdentifier<\/key>\s*<string>([^<]+)<\/string>/.exec(info)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `AssociatedBundleIdentifiers`, naming the app the agent is credited to, when there is one. */
+const associatedApp = (app) => app === undefined
+    ? ""
+    : `  <key>AssociatedBundleIdentifiers</key>\n  <array>\n    <string>${xml(app)}</string>\n  </array>\n`;
+/**
+ * The launch agent: run from login, run again whenever it stops; credited to `app`, by its bundle
+ * identifier, where its program is inside one.
+ */
+export function launchdPlist(spec, logFile, app) {
+    const args = spec.command.map((word) => `    <string>${xml(word)}</string>`).join("\n");
+    const env = Object.entries(spec.environment)
+        .map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- ${MARK}. Its bridge's \`npm run keep -- --stop\` stops it and removes this file. -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(spec.label)}</string>
+${associatedApp(app)}  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(spec.folder)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(logFile)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+/** The systemd user unit: run from login, run again whenever it stops. */
+export function systemdUnit(spec, logFile) {
+    const quote = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    const env = Object.entries(spec.environment)
+        .map(([key, value]) => `Environment=${quote(`${key}=${value}`)}`)
+        .join("\n");
+    return `# ${MARK}. Its bridge's \`npm run keep -- --stop\` stops it and removes this file.
+[Unit]
+Description=${spec.label}
+After=network-online.target
+
+[Service]
+ExecStart=${spec.command.map(quote).join(" ")}
+WorkingDirectory=${quote(spec.folder)}
+${env}
+Restart=always
+RestartSec=5
+StandardOutput=append:${logFile}
+StandardError=append:${logFile}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** Run it now: load the agent (afresh, when it is loaded), or enable the unit and start it again. */
+export function startCommands(kind, label, path, uid) {
+    if (kind === "launchd") {
+        return [
+            ["launchctl", "enable", `gui/${uid}/${label}`],
+            ["launchctl", "bootout", `gui/${uid}/${label}`],
+            ["launchctl", "bootstrap", `gui/${uid}`, path],
+        ];
+    }
+    return [
+        ["systemctl", "--user", "daemon-reload"],
+        ["systemctl", "--user", "enable", `${label}.service`],
+        ["systemctl", "--user", "restart", `${label}.service`],
+    ];
+}
+/** Stop it, and keep it from starting at the next login. */
+export function stopCommands(kind, label, uid) {
+    if (kind === "launchd")
+        return [["launchctl", "bootout", `gui/${uid}/${label}`]];
+    return [["systemctl", "--user", "disable", "--now", `${label}.service`]];
+}
+/** Unloading an agent that isn't loaded is how a first start begins, and how a second stop ends. */
+const mayFail = (command) => command[0] === "launchctl" && command[1] === "bootout";
+/**
+ * What `chips connect` hands a bridge for this run alone (ADR 0218): the link, which is spent once
+ * taken up; the Node to keep it on and the line that stops it, which keep has used by the time it
+ * writes the service; and the steps it reports, which only that `chips connect` reads.
+ */
+const HANDED_OVER = new Set([
+    "CHIPS_JOIN_LINK",
+    "CHIPS_NODE",
+    "CHIPS_STOP_COMMAND",
+    "CHIPS_STEPS",
+]);
+/**
+ * What a kept bridge needs from the shell it was joined from: the server's address, so `join()`
+ * finds the key it kept; the PATH, so its agent's command is found; Chips's own settings (never
+ * what was handed over for the run alone, the spent link among them); and the names a bridge asks
+ * for, where they are set. Given the `node` it is kept on, that node's folder comes first on the
+ * PATH: an agent run as `#!/usr/bin/env node` (an ACP adapter) finds it on a machine with no Node
+ * of its own.
+ */
+export function keepEnvironment(url, 
+// biome-ignore lint/style/noProcessEnv: the shell it joined from is what it takes with it.
+env = process.env, names = [], node) {
+    const kept = { CHIPS_URL: url };
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined || value === "")
+            continue;
+        if (name === "PATH" ||
+            names.includes(name) ||
+            (name.startsWith("CHIPS_") && !HANDED_OVER.has(name)))
+            kept[name] = value;
+    }
+    kept["CHIPS_URL"] = url;
+    if (node !== undefined)
+        kept["PATH"] = nodeFirst(dirname(node), kept["PATH"]);
+    return kept;
+}
+/** `folder` first on a PATH, and nowhere else on it. */
+function nodeFirst(folder, path) {
+    const rest = (path ?? "").split(delimiter).filter((each) => each !== "" && each !== folder);
+    return [folder, ...rest].join(delimiter);
+}
+/**
+ * The node a kept bridge runs on: the one `chips connect` hands over (`CHIPS_NODE`), named by a
+ * path an upgrade of Chips keeps (`~/.local/lib/chips/current/runtime/node`, or inside Chips.app);
+ * else the first on the PATH, as `npm start` runs it (`nodeOnPath`).
+ */
+export function keptNode(
+// biome-ignore lint/style/noProcessEnv: `chips connect` hands its Node over in the environment.
+env = process.env) {
+    const given = env["CHIPS_NODE"];
+    return given !== undefined && given !== "" ? given : nodeOnPath(env);
+}
+/**
+ * The node a kept bridge runs on: the first on the PATH, as `npm start` runs it, which is the link
+ * a package manager keeps (Homebrew's `/opt/homebrew/bin/node`); `process.execPath` is the
+ * version's own folder, which the next upgrade removes, and the service with it. This process's
+ * own where none is on the PATH.
+ */
+export function nodeOnPath(
+// biome-ignore lint/style/noProcessEnv: the shell it joined from is what it takes with it.
+env = process.env) {
+    for (const folder of (env["PATH"] ?? "").split(delimiter)) {
+        if (folder === "")
+            continue;
+        try {
+            accessSync(join(folder, "node"), constants.X_OK);
+            return join(folder, "node");
+        }
+        catch {
+            // Not here.
+        }
+    }
+    return process.execPath;
+}
+/** Wait here: the service's file and commands are all synchronous, and a bridge does nothing meanwhile. */
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** Tries at loading the launch agent: `bootout` returns before a running bridge has gone. */
+const LOAD_TRIES = 40;
+const runOf = (options) => options.run ??
+    ((command) => execFileSync(command[0], command.slice(1), {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }));
+const ours = (path) => !existsSync(path) || readFileSync(path, "utf8").includes(MARK);
+/** One command run, tried again while launchd lets a stopped copy go, and let fail where that's fine. */
+function runOne(command, run, retryMs) {
+    // `launchctl bootout` returns while the copy it stops is still going, and loading again before
+    // it has gone fails (status 5): try again, for about ten seconds.
+    const tries = command[0] === "launchctl" && command[1] === "bootstrap" ? LOAD_TRIES : 1;
+    for (let tried = 1;; tried += 1) {
+        try {
+            run(command);
+            return;
+        }
+        catch (error) {
+            if (mayFail(command))
+                return;
+            if (tried >= tries)
+                throw error;
+            pause(retryMs);
+        }
+    }
+}
+/** The commands, in order, on the machine's own manager unless `options.run` says otherwise. */
+function runAll(commands, options) {
+    const run = runOf(options);
+    for (const command of commands)
+        runOne(command, run, options.retryMs ?? 250);
+}
+const uidOf = (options) => options.uid ?? process.getuid?.() ?? 0;
+/**
+ * On Linux, a user's units run only while they are logged in, unless systemd keeps that user's
+ * manager running from boot ("lingering"), which `chips up` turns on for the server
+ * (`cli/src/service.ts`); this is that, for a harness on a machine that only runs one. Asked first,
+ * because turning it on over SSH is refused even when it is on; then turned on, which a local
+ * session may do without a password. False when it is off and stays off.
+ */
+function lingers(options) {
+    const run = runOf(options);
+    const uid = String(uidOf(options));
+    try {
+        const on = run(["loginctl", "show-user", uid, "--property=Linger", "--value"]);
+        if (typeof on === "string" && on.trim() === "yes")
+            return true;
+    }
+    catch {
+        // Not answered: turning it on may work all the same.
+    }
+    try {
+        run(["loginctl", "enable-linger", uid]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Where keep's word to the person goes: standard error, beside the bridge's own. */
+const sayOf = (options) => options.say ?? ((line) => void process.stderr.write(`${line}\n`));
+/**
+ * Write the service and run it, replacing one written here before. A file of somebody's own at
+ * that place is left as it is: `theirs`.
+ */
+export function keepRunning(spec, options = {}) {
+    // A test runs a card's line as a person does, and must never leave a real service behind.
+    if (machineOf(options.machine).env["CHIPS_KEEP"] === "off")
+        return { state: "off" };
+    const file = serviceFile(spec, options.machine);
+    if (file === undefined)
+        return { state: "unsupported" };
+    if (!ours(file.path))
+        return { state: "theirs", path: file.path, logFile: file.logFile };
+    reportStep("keeping", { label: spec.label }, machineOf(options.machine).env);
+    mkdirSync(dirname(file.path), { recursive: true });
+    mkdirSync(dirname(file.logFile), { recursive: true });
+    // Read by its user only: a bridge may carry a password its harness needs.
+    writeFileSync(file.path, file.contents, { mode: 0o600 });
+    chmodSync(file.path, 0o600);
+    runAll(startCommands(file.kind, spec.label, file.path, uidOf(options)), options);
+    if (file.kind === "systemd" && !lingers(options)) {
+        sayOf(options)("It stops when you log out. To keep it running on a machine nobody logs in to, run this once: sudo loginctl enable-linger $USER");
+    }
+    return { state: "kept", path: file.path, logFile: file.logFile };
+}
+/** Stop a service written here, and remove its file. One of somebody's own is left: `theirs`. */
+export function stopKeeping(label, options = {}) {
+    const file = serviceFile({ label, command: ["-"], folder: "/", environment: {} }, options.machine);
+    if (file === undefined)
+        return { state: "unsupported" };
+    if (!existsSync(file.path))
+        return { state: "none", path: file.path };
+    if (!ours(file.path))
+        return { state: "theirs", path: file.path };
+    runAll(stopCommands(file.kind, label, uidOf(options)), options);
+    rmSync(file.path);
+    return { state: "stopped", path: file.path };
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/settings.d.ts

@@ -0,0 +1,137 @@
+/**
+ * What a person changes about an agent from its page, kept by the harness (ADRs 0134, 0140, 0143,
+ * 0146): its context files, its model and effort, its heartbeat, its context window; and the jobs
+ * the harness runs on its own, from the harness's page (ADR 0252). One pattern five times. The harness sends its copy (`put…`) when it connects and whenever it changes on its
+ * own side; a person's change arrives as a frame, now or never; the harness makes it in its own way
+ * and answers with the copy as it is now. Here a handler does the making and returns the copy, and
+ * the answer — `answers`, or `refuses` when the handler throws — is sent for it.
+ */
+import { type AgentContextPut, type AgentContextWindowPut, type AgentHeartbeatPut, type AgentModelPut, type ContextEditFrame, type HarnessContextPut, type HarnessJobsPut, type HeartbeatChangeFrame, type JobChangeFrame, type JobRun, type ModelChangeFrame, type WindowChangeFrame, type WindowCompactFrame } from "@chipschat/protocol";
+type Answered = "answers" | "refuses";
+/** An agent's files, as `PUT /v1/agents/:id/context` takes them, without the answer. */
+export type AgentContextCopy = Omit<AgentContextPut, Answered>;
+/** The harness's own shared set, as `PUT /v1/harnesses/:id/context` takes it. */
+export type HarnessContextCopy = Omit<HarnessContextPut, Answered>;
+export type AgentModelCopy = Omit<AgentModelPut, Answered>;
+export type AgentHeartbeatCopy = Omit<AgentHeartbeatPut, Answered>;
+export type AgentContextWindowCopy = Omit<AgentContextWindowPut, Answered>;
+/** The jobs the harness runs on its own, as `PUT /v1/harnesses/:id/jobs` takes them. */
+export type HarnessJobsCopy = Omit<HarnessJobsPut, Answered>;
+/**
+ * A change the harness won't or can't make. Throw it from a handler with the copy as it is now:
+ * the person is told `message`, and sees the copy. Anything else thrown refuses the same way, with
+ * the copy last sent for that agent, and its message.
+ */
+export declare class Refuse extends Error {
+    /** The copy as it is now. Absent: the one last sent for that agent. */
+    readonly copy?: unknown | undefined;
+    /** For a context file only: `changed` when the file moved on since the person's version. */
+    readonly reason?: "changed" | "failed" | undefined;
+    readonly name = "Refuse";
+    constructor(message: string, 
+    /** The copy as it is now. Absent: the one last sent for that agent. */
+    copy?: unknown | undefined, 
+    /** For a context file only: `changed` when the file moved on since the person's version. */
+    reason?: "changed" | "failed" | undefined);
+}
+/**
+ * The handlers a harness gives `connect({ settings })`, each for a capability it declares. Giving
+ * one says the matching word in the socket's `hello` (`context`, `models`, `heartbeats`,
+ * `context_windows`), so Chips sends that frame here; leaving it out, Chips never does.
+ */
+export interface SettingsHandlers {
+    /**
+     * A person changed a context file (ADR 0134): an agent's, or the harness's own set when
+     * `agent_id` is absent. Save it, then return the copy it is in now: the agent's files, or the
+     * shared set. `base_hash: null` asks to give the agent its own copy of a shared file. When the
+     * file changed since `base_hash`, throw `new Refuse(words, copy, "changed")`.
+     */
+    readonly context?: ((edit: ContextEditFrame) => Promise<AgentContextCopy | HarnessContextCopy>) | undefined;
+    /** A person changed an agent's model or effort (ADR 0140); `model: null` is the default. */
+    readonly models?: ((change: ModelChangeFrame) => Promise<AgentModelCopy>) | undefined;
+    /** A person switched an agent's heartbeat or changed how often it beats (ADR 0143). */
+    readonly heartbeats?: ((change: HeartbeatChangeFrame) => Promise<AgentHeartbeatCopy>) | undefined;
+    /**
+     * A person asked an agent to compact now, or changed the limit it compacts itself at (ADR
+     * 0146). For a compaction, return the copy at once with `compacting` set, and `put` it again
+     * when it is done.
+     */
+    readonly contextWindows?: {
+        readonly compact: (ask: WindowCompactFrame) => Promise<AgentContextWindowCopy>;
+        readonly change: (ask: WindowChangeFrame) => Promise<AgentContextWindowCopy>;
+    } | undefined;
+    /**
+     * A person switched one of the jobs the harness runs on its own, or changed how often it runs
+     * (ADR 0252). Make it, then return the copy of all its jobs as they are now.
+     */
+    readonly jobs?: ((change: JobChangeFrame) => Promise<HarnessJobsCopy>) | undefined;
+}
+/** What `hello.accepts` says for these handlers, beside `restart` for a restart handler. */
+export declare function acceptsFor(handlers: SettingsHandlers | undefined): string[];
+/** A `PUT` to chipsd with the harness's token, as the connection makes it. */
+export type Put = (path: string, body: Readonly<Record<string, unknown>>) => Promise<unknown>;
+/**
+ * The harness's copies, sent and remembered: `chips.settings`. Each `put` sends the whole copy;
+ * the last one sent for each agent is what a refusal carries when a handler gives none. A copy
+ * the same as the last one Chips took for that agent is not sent again, unless it answers a
+ * person, so a harness may send its copies as often as it reads them; and one agent's copies of
+ * a kind go one after another, so a later one never lands before an earlier one.
+ */
+export declare class Settings {
+    private readonly put;
+    private readonly harnessId;
+    private readonly handlers;
+    /** A `POST` to chipsd with the harness's token, for its jobs' runs. */
+    private readonly post?;
+    /** The copy last given for each `kind:id`, for a refusal to carry. */
+    private readonly sent;
+    /** The copy Chips last took for each `kind:id`, as JSON. */
+    private readonly landed;
+    private readonly chains;
+    constructor(put: Put, harnessId: () => string, handlers: SettingsHandlers | undefined, 
+    /** A `POST` to chipsd with the harness's token, for its jobs' runs. */
+    post?: Put | undefined);
+    /** An agent's context files (`context_files`). */
+    context(agentId: string, copy: AgentContextCopy): Promise<unknown>;
+    /** The harness's own shared set, which its agents read or start from (`context_files`). */
+    harnessContext(copy: HarnessContextCopy): Promise<unknown>;
+    /** An agent's model and effort, what it may run on instead, and the words for each (`models`). */
+    model(agentId: string, copy: AgentModelCopy): Promise<unknown>;
+    /** An agent's heartbeat (`heartbeats`). */
+    heartbeat(agentId: string, copy: AgentHeartbeatCopy): Promise<unknown>;
+    /** An agent's context window: how full, its limit, its last compaction (`context_windows`). */
+    contextWindow(agentId: string, copy: AgentContextWindowCopy): Promise<unknown>;
+    /** The jobs the harness runs on its own, all of them (`jobs`). */
+    jobs(copy: HarnessJobsCopy): Promise<unknown>;
+    /**
+     * Runs of its jobs the harness finished (`jobs`), two hundred to a post. A run sent again says
+     * what it says over the one before, and what it leaves out stays, so send it once more when its
+     * cost is known, and again without one does no harm. Send the copy first:
+     * Chips refuses runs of a job its copy doesn't list.
+     */
+    jobRuns(runs: readonly JobRun[]): Promise<void>;
+    /** An agent deleted: nothing is remembered of it, so a copy for an agent made again is sent. */
+    forget(agentId: string): void;
+    /**
+     * A compaction taken (its handler returned) that then failed: the ask refused after all, with
+     * the harness's words, beside the copy as it is now, or the one last sent.
+     */
+    contextWindowFailed(agentId: string, changeId: string, message: string, copy?: AgentContextWindowCopy): Promise<unknown>;
+    /**
+     * A frame from Chips, if it is one of these: read by its schema (SEC-14), handed to its handler
+     * and answered. The answer's promise, which never rejects; nothing for any other frame, and
+     * nothing for a frame that is not what it says it is.
+     */
+    hear(frame: Readonly<Record<string, unknown>>): Promise<void> | undefined;
+    /** One of the frames read, handed to its handler and answered. */
+    private heard;
+    private send;
+    /**
+     * Make the change with its handler and answer with the copy: `answers` when it returns,
+     * `refuses` when it throws. With no handler and no copy ever sent there is nothing to answer
+     * with, and the person is told it was missed after a minute.
+     */
+    private answer;
+}
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"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"}