@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/keepers/acp/memoryStream.js

@@ -0,0 +1,121 @@
+export class MemoryStream {
+    options;
+    records = [];
+    sizes = [];
+    bytes = 0;
+    firstOffset;
+    nextOffset;
+    committedOffset;
+    tail;
+    checkpoints = [];
+    checkpointSeq = 0;
+    closed = false;
+    notifyPending = false;
+    watchers = new Set();
+    constructor(options) {
+        this.options = options;
+        const base = options.baseOffset ?? 0;
+        if (!Number.isSafeInteger(base) || base < 0)
+            throw new RangeError(`Invalid baseOffset ${base}`);
+        this.firstOffset = base;
+        this.nextOffset = base;
+        this.committedOffset = base - 1;
+    }
+    append(input) {
+        this.assertOpen();
+        if (typeof input.k !== 'string' || input.k === '')
+            throw new TypeError('A stream record needs a non-empty kind `k`');
+        if ('o' in input || 't' in input)
+            throw new TypeError('`o` and `t` are stamped by the stream log');
+        const { k, ...rest } = input;
+        const record = { o: this.nextOffset, t: this.options.now(), k, ...rest };
+        const size = Buffer.byteLength(JSON.stringify(record)) + 1;
+        this.records.push(record);
+        this.sizes.push(size);
+        this.bytes += size;
+        this.nextOffset += 1;
+        this.scheduleNotify();
+        return record;
+    }
+    readFrom(from, limit, options = {}) {
+        this.assertOpen();
+        const first = this.firstOffset;
+        const truncated = from < first;
+        const out = [];
+        const maxBytes = options.maxBytes ?? Number.POSITIVE_INFINITY;
+        let used = 0;
+        for (let i = Math.max(from, first) - first; i < this.records.length && out.length < limit; i++) {
+            if (out.length > 0 && used + this.sizes[i] > maxBytes)
+                break; // as the kit log: never cross the budget, always the first record
+            out.push(this.records[i]);
+            used += this.sizes[i];
+        }
+        return { records: out, first, truncated };
+    }
+    read(from, limit, options = {}) { return this.readFrom(from, limit, options).records; }
+    /** As the kit log: marks `o <= through` consumed and forgets them; `tail` is kept as the watermark. */
+    commit(through, tail) {
+        this.assertOpen();
+        if (!Number.isSafeInteger(through) || through < -1)
+            throw new RangeError(`Invalid commit offset ${through}`);
+        if (through > this.nextOffset - 1)
+            throw new RangeError(`Commit offset ${through} is beyond the head ${this.nextOffset - 1}`);
+        if (tail !== undefined)
+            this.tail = tail;
+        if (through <= this.committedOffset)
+            return;
+        this.committedOffset = through;
+        const drop = Math.min(this.records.length, through + 1 - this.firstOffset);
+        if (drop > 0) {
+            for (let i = 0; i < drop; i++)
+                this.bytes -= this.sizes[i];
+            this.records = this.records.slice(drop);
+            this.sizes = this.sizes.slice(drop);
+            this.firstOffset += drop;
+        }
+    }
+    writeCheckpoint(offset, blob) {
+        this.assertOpen();
+        if (!Number.isSafeInteger(offset) || offset < -1)
+            throw new RangeError(`Invalid checkpoint offset ${offset}`);
+        const checkpoint = { seq: ++this.checkpointSeq, offset, t: this.options.now(), blob: typeof blob === 'string' ? Buffer.from(blob, 'utf8') : Buffer.from(blob) };
+        this.checkpoints = [...this.checkpoints, checkpoint].slice(-2);
+        return checkpoint;
+    }
+    latestCheckpoint() { return this.checkpoints[this.checkpoints.length - 1]; }
+    state() {
+        return {
+            head: this.nextOffset - 1, committed: this.committedOffset, committedTail: this.tail, overQuota: false,
+            checkpointOffset: this.latestCheckpoint()?.offset ?? -1, first: this.firstOffset, next: this.nextOffset, bytes: this.bytes, segments: 0,
+        };
+    }
+    watch(notify) { this.watchers.add(notify); return () => { this.watchers.delete(notify); }; }
+    asEventSource(options = {}) {
+        return {
+            read: (from, limit, perRead) => {
+                const caps = [options.maxBytes, perRead?.maxBytes].filter((cap) => cap !== undefined);
+                return this.readFrom(from, limit, { maxBytes: caps.length > 0 ? Math.min(...caps) : undefined }).records;
+            },
+            watch: (notify) => this.watch(notify),
+        };
+    }
+    close() { this.closed = true; this.watchers.clear(); }
+    scheduleNotify() {
+        if (this.notifyPending || this.watchers.size === 0)
+            return;
+        this.notifyPending = true;
+        queueMicrotask(() => {
+            this.notifyPending = false;
+            if (this.closed)
+                return;
+            for (const watcher of [...this.watchers]) {
+                try {
+                    watcher();
+                }
+                catch { /* a watcher's failure is its own */ }
+            }
+        });
+    }
+    assertOpen() { if (this.closed)
+        throw new Error('Stream is closed'); }
+}

package/dist/workstation/keepers/acp/params.js

@@ -0,0 +1,137 @@
+// Parameter checks for `acp.*` (the daemon decides everything; the keeper only refuses malformed input).
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { ACP_ANNOTATION_BYTES, ACP_ENV_BYTES, ACP_LABEL_BYTES, ACP_SESSION_KEY_CHARS, AcpErrorCode, } from './protocol.js';
+const MAX_PATH = 4096;
+const MAX_ARGS = 4096;
+const MAX_ENV_ENTRIES = 4096;
+const MAX_LIST = 256;
+export const bad = (message) => { throw new KeeperMethodError(AcpErrorCode.badRequest, message); };
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const jsonBytes = (value) => { try {
+    return Buffer.byteLength(JSON.stringify(value) ?? '');
+}
+catch {
+    return Number.POSITIVE_INFINITY;
+} };
+/** Only the listed keys: a typo in the daemon's parameters must fail loudly, not be ignored. */
+export function onlyKeys(params, allowed) {
+    for (const key of Object.keys(params))
+        if (!allowed.includes(key))
+            bad(`Unknown parameter ${key}`);
+}
+export function sessionKeyOf(value) {
+    if (typeof value !== 'string' || !value || value.length > ACP_SESSION_KEY_CHARS || value.includes('\0'))
+        bad('Invalid sessionKey');
+    return value;
+}
+export function offsetOf(value, name, min = 0) {
+    if (!Number.isSafeInteger(value) || value < min)
+        bad(`Invalid ${name}`);
+    return value;
+}
+export function causeOf(value, name = 'cause') {
+    if (!isRecord(value) || !Number.isSafeInteger(value.o) || value.o < 0 || !Number.isSafeInteger(value.i) || value.i < 0)
+        bad(`Invalid ${name}`);
+    return { o: value.o, i: value.i };
+}
+function absolutePath(value, name) {
+    if (typeof value !== 'string' || !value || value.length > MAX_PATH || value.includes('\0') || !path.isAbsolute(value))
+        bad(`Invalid ${name}`);
+    return path.normalize(value);
+}
+function stringList(value, name, max) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > max || value.some((v) => typeof v !== 'string' || v.includes('\0')))
+        bad(`Invalid ${name}`);
+    return [...value];
+}
+/** The environment exactly as the daemon sent it: string values only, no `=` or NUL in names, no NUL in values, bounded. */
+function environment(value) {
+    if (!isRecord(value))
+        return bad('Invalid env');
+    const entries = Object.entries(value);
+    if (entries.length > MAX_ENV_ENTRIES || jsonBytes(value) > ACP_ENV_BYTES)
+        bad('Invalid env');
+    const env = {};
+    for (const [name, entry] of entries) {
+        if (!name || name.includes('=') || name.includes('\0') || typeof entry !== 'string' || entry.includes('\0'))
+            bad('Invalid env');
+        env[name] = entry;
+    }
+    return env;
+}
+/**
+ * A path the keeper may delete when the process exits: absolute, normalised, at least two levels below the root, never a parent of
+ * the keeper's own data. Only paths handed over at spawn are ever deleted.
+ */
+export function removablePath(value, protectedDirs) {
+    const target = absolutePath(value, 'removeOnExit');
+    if (target.split(path.sep).filter(Boolean).length < 2)
+        bad('removeOnExit path is too shallow');
+    for (const dir of protectedDirs) {
+        const rel = path.relative(target, dir);
+        if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)))
+            bad('removeOnExit may not contain keeper data');
+    }
+    return target;
+}
+export function spawnSpecOf(value, protectedDirs) {
+    if (!isRecord(value))
+        return bad('Invalid spec');
+    onlyKeys(value, ['command', 'args', 'env', 'cwd', 'stderrSecrets', 'removeOnExit']);
+    const { command } = value;
+    if (typeof command !== 'string' || !command || command.length > MAX_PATH || command.includes('\0'))
+        bad('Invalid command');
+    const args = stringList(value.args, 'args', MAX_ARGS);
+    const cwd = absolutePath(value.cwd, 'cwd');
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(cwd).isDirectory();
+    }
+    catch { /* missing */ }
+    if (!isDirectory)
+        bad('Adapter working directory is not a directory');
+    const stderrSecrets = stringList(value.stderrSecrets, 'stderrSecrets', MAX_LIST);
+    const removeOnExit = stringList(value.removeOnExit, 'removeOnExit', MAX_LIST).map((p) => removablePath(p, protectedDirs));
+    return { command: command, args, env: environment(value.env), cwd, stderrSecrets, removeOnExit };
+}
+export function labelOf(value) {
+    if (!isRecord(value) || jsonBytes(value) > ACP_LABEL_BYTES)
+        return bad('Invalid label');
+    return JSON.parse(JSON.stringify(value));
+}
+export function annotationOf(value) {
+    if (!isRecord(value) || jsonBytes(value) > ACP_ANNOTATION_BYTES)
+        return bad('Invalid annotation');
+    causeOf(value.cause, 'annotation.cause');
+    return value;
+}
+export function redactionsOf(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_LIST)
+        return bad('Invalid redact');
+    return value.map((entry) => {
+        if (!isRecord(entry) || typeof entry.ref !== 'string' || !entry.ref || typeof entry.value !== 'string')
+            return bad('Invalid redact');
+        return { ref: entry.ref, value: entry.value };
+    });
+}
+export function noteOf(value) {
+    if (!isRecord(value) || typeof value.type !== 'string' || !value.type)
+        return bad('Invalid note');
+    return value;
+}
+export function outboxEntriesOf(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return bad('Invalid entries');
+    return value.map((entry) => {
+        if (!isRecord(entry) || !Number.isSafeInteger(entry.seq) || !isRecord(entry.frame))
+            return bad('Invalid outbox entry');
+        return { seq: entry.seq, src: causeOf(entry.src, 'outbox src'), frame: entry.frame };
+    });
+}

package/dist/workstation/keepers/acp/protocol.js

@@ -0,0 +1,66 @@
+// keeper-acp's wire vocabulary, shared by the keeper (`main.ts`, `host.ts`) and the daemon (`client.ts`, the processor transports).
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it). Spec §5.3, §3.3, §13, §14.
+//
+// keeper-acp is ACP-agnostic: it hosts adapter processes, keeps one ordered raw stream and one outbox stream per session and
+// never interprets JSON-RPC beyond sniffing `id`/`method` for diagnostics. Everything that has meaning lives in the daemon.
+/** The keeper protocol this code speaks. `main.ts` declares the same number for the bundler (a test keeps them equal). */
+export const ACP_PROTOCOL_VERSION = 1;
+/** `keeper.hello` capability: `acp.*` is served. */
+export const ACP_CAPABILITY = 'acp';
+export const ACP_METHODS = [
+    'acp.spawn', 'acp.list', 'acp.attach', 'acp.write', 'acp.note', 'acp.read', 'acp.downs',
+    'acp.outbox.append', 'acp.commit', 'acp.terminate', 'acp.release',
+];
+export const acpStream = (stream, sessionKey) => `${stream}/${sessionKey}`;
+export function parseAcpStream(name) {
+    for (const stream of ['raw', 'outbox'])
+        if (name.startsWith(`${stream}/`) && name.length > stream.length + 1)
+            return { stream, sessionKey: name.slice(stream.length + 1) };
+    return undefined;
+}
+// ---- constants (spec §14 and this task) --------------------------------------------------------------------------------
+/** SIGTERM to the adapter's process group, then SIGKILL after this long, then pipes are closed after this long again. */
+export const ACP_TERMINATE_GRACE_MS = 2000;
+export const ACP_KILL_GRACE_MS = 2000;
+/** After the adapter exits by itself, its stdio is drained for at most this long before the pipes are closed and `exit` is written. */
+export const ACP_EXIT_DRAIN_MS = 2000;
+/** The redacted stderr tail carried by `proc exit` (today's `AgentSpawnError` text is built from it). */
+export const ACP_STDERR_TAIL_BYTES = 8 * 1024;
+/** A stderr line longer than this is never written anywhere (only a placeholder): a cut line could split a secret. */
+export const ACP_STDERR_LINE_BYTES = 16 * 1024;
+/** Per-session stderr file: rotated to `stderr.log.1` at this size, so at most twice this is kept. */
+export const ACP_STDERR_FILE_BYTES = 1024 * 1024;
+/**
+ * Largest serialised record (one stream line). Keeps every record readable through one 32 MiB frame (spec §3.3: an image prompt
+ * line is about 10.7 MB). A larger `down` is refused; a larger stdout line is dropped and a `gap` record says so.
+ */
+export const ACP_MAX_RECORD_BYTES = 30 * 1024 * 1024;
+/** Byte budget of one `acp.read` answer or one pushed batch (at least one record is always returned). */
+export const ACP_READ_MAX_BYTES = 16 * 1024 * 1024;
+export const ACP_READ_MAX_RECORDS = 4096;
+/** The hard limit of spec §3.4: below this much free disk the keeper stops reading adapter stdout until space returns. */
+export const ACP_MIN_FREE_DISK_BYTES = 1024 * 1024 * 1024;
+export const ACP_DISK_CHECK_MS = 5000;
+/** Sessions one keeper holds (live and exited, until released). */
+export const ACP_SESSION_LIMIT = 256;
+export const ACP_SESSION_KEY_CHARS = 256;
+export const ACP_LABEL_BYTES = 4096;
+export const ACP_ANNOTATION_BYTES = 64 * 1024;
+export const ACP_ENV_BYTES = 1024 * 1024;
+/** Unpaired requests the envelope sniffer remembers per direction (diagnostics only; the oldest are forgotten). */
+export const ACP_ENVELOPE_PENDING = 256;
+/** Lines longer than this are not parsed by the envelope sniffer (counted instead): sniffing must stay cheap. */
+export const ACP_ENVELOPE_SNIFF_BYTES = 256 * 1024;
+export const AcpErrorCode = {
+    badRequest: 'bad_request',
+    notFound: 'acp_session_not_found',
+    /** A process is starting or running in this session (spawn, release). */
+    busy: 'acp_session_busy',
+    limit: 'acp_limit',
+    /** The command could not be started (ENOENT, EACCES, …): nothing was appended to the session. */
+    spawnFailed: 'acp_spawn_failed',
+    /** The session belongs to another live keeper-acp generation. */
+    foreign: 'acp_session_foreign',
+    /** The session's directory has a session.json this keeper cannot read (corrupt, another schema): left alone, never reused. */
+    unreadable: 'acp_session_unreadable',
+};

package/dist/workstation/keepers/acp/recover.js

@@ -0,0 +1,120 @@
+// keeper-acp start-up recovery (spec §5.3 "keeper-acp 自身重启"): every session directory whose owning keeper process is gone is
+// adopted. A session whose adapter was running when its keeper died is marked exited with `proc exit{reason:'keeper_lost'}`, and the
+// adapter's process group is killed — only after verifying the leader by pid + start time (`kit/orphanSweep.ts`, the same
+// PID-reuse-safe rule keeper-terminal applies to execs); a group that cannot be verified is never signalled. Its `removeOnExit`
+// paths are removed after the kill grace. The daemon then folds the tail (it may hold a real `turn_done`) and reopens the session
+// through `session/load`. Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import { closeSync, openSync, readFileSync, readSync, readdirSync, fstatSync } from 'node:fs';
+import path from 'node:path';
+import { settleOrphan } from '../kit/orphanSweep.js';
+import { ACP_KILL_GRACE_MS, ACP_STDERR_TAIL_BYTES } from './protocol.js';
+export const SESSION_FILE = 'session.json';
+export const STDERR_FILE = 'stderr.log';
+export function validMeta(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const m = value;
+    const spawn = m.spawn;
+    return m.v === 1 && typeof m.sessionKey === 'string' && typeof m.label === 'object' && m.label !== null && Number.isFinite(m.createdAtMs)
+        && typeof m.exited === 'boolean' && Array.isArray(m.removeOnExit) && m.removeOnExit.every((p) => typeof p === 'string')
+        && (spawn === null || (typeof spawn === 'object' && typeof spawn.spawnId === 'string' && Number.isSafeInteger(spawn.pid) && Number.isSafeInteger(spawn.pgid)
+            && (spawn.startTime === null || typeof spawn.startTime === 'string')));
+}
+/** Session directories under `sessionsDir` with a readable `session.json` (others are being created, or not sessions: left alone). */
+/**
+ * A session directory's metadata: `absent` only when `session.json` does not exist (a start killed between mkdir and the metadata
+ * rename); `unreadable` for anything else (corrupt, another schema version, unreadable) — such a directory is never deleted.
+ */
+export function readSessionMeta(dir) {
+    let text;
+    try {
+        text = readFileSync(path.join(dir, SESSION_FILE), 'utf8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? 'absent' : 'unreadable';
+    }
+    try {
+        const value = JSON.parse(text);
+        return validMeta(value) ? value : 'unreadable';
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+export function listSessionDirs(sessionsDir, report) {
+    let names;
+    try {
+        names = readdirSync(sessionsDir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names.sort()) {
+        const dir = path.join(sessionsDir, name);
+        let value;
+        try {
+            value = JSON.parse(readFileSync(path.join(dir, SESSION_FILE), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!validMeta(value)) {
+            report(`${name}: unreadable session metadata, left alone`);
+            continue;
+        }
+        found.push({ dir, meta: value });
+    }
+    return found;
+}
+/** The redacted stderr tail the session's file kept (the file only ever holds redacted lines). */
+export function stderrTailOf(dir) {
+    let fd;
+    try {
+        fd = openSync(path.join(dir, STDERR_FILE), 'r');
+        const size = fstatSync(fd).size;
+        const length = Math.min(size, ACP_STDERR_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, size - length);
+        let text = buffer.toString('utf8');
+        if (length < size)
+            text = text.replace(/^[^\n]*\n?/, ''); // never start mid-line (or mid-character)
+        return text;
+    }
+    catch {
+        return '';
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+    }
+}
+/**
+ * The adapter a lost keeper ran: verified by pid + start time, then SIGTERM to its group and SIGKILL after the grace
+ * (`settleOrphan`). `afterGrace` runs once the SIGKILL is due (or at once when nothing was signalled) — removeOnExit goes there,
+ * so a bearer file outlives no process that could still read it.
+ */
+export async function settleLostAdapter(meta, afterGrace, deps = {}) {
+    const spawn = meta.spawn;
+    if (!spawn) {
+        afterGrace();
+        return 'gone';
+    }
+    const later = deps.later ?? ((ms, run) => { setTimeout(run, ms).unref(); });
+    let killDue;
+    const outcome = await settleOrphan({ pid: spawn.pid, pgid: spawn.pgid, startTime: spawn.startTime }, 'kill', ACP_KILL_GRACE_MS, {
+        ...deps,
+        later: (ms, run) => { killDue = run; later(ms, () => { try {
+            run();
+        }
+        finally {
+            afterGrace();
+        } }); },
+    });
+    if (!killDue)
+        afterGrace();
+    return outcome;
+}