mtech-ai-local-runner 0.1.46 → 0.1.48

package/dist/src/asks/hook-client.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { connect } from "node:net";
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HUB_SOCKET, HUB_TIMEOUT_MS, MAX_HOOK_INPUT_BYTES, MAX_LINE_BYTES, WATCH_LIMIT_MS, encodeLine, parseEventResponse, parseWatchMessage, } from "./hub-protocol.js";
+import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
+const STDIN_TIMEOUT_MS = 1000;
+const STATE_ROOT_FLAG = "--state-root=";
+/**
+ * Values of CLAUDE_CODE_ENTRYPOINT under which a person types the prompts: a terminal, the Claude desktop app and
+ * the VS Code extension. Claude Code exports the variable itself (sdk-cli for claude -p, sdk-ts and sdk-py for the
+ * Agent SDK, mcp, local-agent, remote and the GitHub action for the rest), so any other value is not a person.
+ */
+const INTERACTIVE_ENTRYPOINTS = new Set(["cli", "claude-desktop", "claude-vscode"]);
+/** Where the Claude adapter puts each job's HOME: <stateRoot>/claude-jobs/<id>/home (src/adapters/claude-code/runtime-options.ts). */
+const CLAUDE_JOBS_DIR = "claude-jobs";
+/** True when HOME resolves inside <stateRoot>/claude-jobs/: a Claude job this runner started, never a person's session. */
+function isRunnerJobHome(env, stateRoot) {
+    const home = env.HOME;
+    if (!home || !isAbsolute(home))
+        return false;
+    const roots = new Set([resolve(stateRoot)]);
+    // The adapter builds job homes from the real state root; the shim may name it through a symlink.
+    try {
+        roots.add(realpathSync(stateRoot));
+    }
+    catch { /* A state root that does not exist holds no jobs. */ }
+    const resolved = resolve(home);
+    return [...roots].some(root => resolved.startsWith(join(root, CLAUDE_JOBS_DIR) + sep));
+}
+/**
+ * True when a person is attending the session that runs this hook (owner decision 2026-10-23). The one place that
+ * decides it, so it can be adjusted after the pilot.
+ *
+ * The runner's own jobs never count. A Claude job runs with its HOME under <stateRoot>/claude-jobs/, so a hook that
+ * sees such a HOME is refused whatever else the environment says. Codex jobs run with features.hooks=false (the Codex
+ * adapter's isolation overrides), so they never run a hook at all.
+ *
+ * Claude Code: CLAUDE_CODE_SESSION_ATTENDED, where the Claude Code version exports it, is the answer: "1" is a
+ * person, any other value is not, whatever the entrypoint says (a scheduled desktop task has the desktop entrypoint
+ * and nobody at the keyboard). A version that does not export it is judged by CLAUDE_CODE_ENTRYPOINT, and an unset
+ * or unknown entrypoint is not a person.
+ *
+ * Codex: no headless marker is exported to its hooks or present in its hook input that has been verified, so every
+ * Codex hook session counts as a person's. Claude's variables say nothing about Codex and are not read for it.
+ * `input` is the parsed hook input, passed for the day Codex exposes such a marker.
+ */
+export function isHumanSession(app, env, _input, stateRoot) {
+    if (isRunnerJobHome(env, stateRoot))
+        return false;
+    if (app !== "claude")
+        return true;
+    const attended = env.CLAUDE_CODE_SESSION_ATTENDED;
+    if (attended !== undefined && attended !== "")
+        return attended === "1";
+    return INTERACTIVE_ENTRYPOINTS.has(env.CLAUDE_CODE_ENTRYPOINT ?? "");
+}
+/** Same rule as defaultStateRootFromEnv in src/config.ts, repeated so this client loads nothing else. */
+function stateRootFrom(env) {
+    return env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "mtec-ai-local-runner") : join(env.HOME ?? "", ".local", "state", "mtec-ai-local-runner");
+}
+function parseArguments(argv, env) {
+    const rest = [...argv];
+    let stateRoot = stateRootFrom(env);
+    if (rest[0]?.startsWith(STATE_ROOT_FLAG)) {
+        stateRoot = rest.shift().slice(STATE_ROOT_FLAG.length);
+        if (!isAbsolute(stateRoot))
+            return null;
+    }
+    const [app, event, ...extra] = rest;
+    if (extra.length > 0 || !isApp(app) || !isHookEvent(event))
+        return null;
+    return { stateRoot, app, event };
+}
+/** The hook's JSON from stdin, at most 64 KiB, within a second; null otherwise. */
+async function readInput(stdin, timeoutMs) {
+    let timer;
+    const timeout = new Promise(resolve => { timer = setTimeout(() => resolve(null), timeoutMs); });
+    const read = (async () => {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of stdin) {
+            const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            size += bytes.length;
+            if (size > MAX_HOOK_INPUT_BYTES)
+                return null;
+            chunks.push(bytes);
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    })().catch(() => null);
+    try {
+        return await Promise.race([read, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The hook input as an object, or null when it is not one. */
+function parseRecord(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/** Takes the session id, the cwd and Codex's stop_hook_active. Every other field, the prompt included, is ignored. */
+function hookFields(input) {
+    const { session_id: sessionId, cwd, stop_hook_active: stopHookActive } = input;
+    if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId))
+        return null;
+    return { sessionId, cwd: typeof cwd === "string" && isAbsolute(cwd) && cwd.length <= MAX_CWD_LENGTH ? cwd : "", stopHookActive: stopHookActive === true };
+}
+/**
+ * Writes one line to the hub and calls onLine for each line it answers. The first line must arrive within
+ * firstMs; after that the connection may stay open until limitMs. Resolves with what onLine settled on, or null.
+ * A connection the hub closes without a message (a refused or late watch ends that way) resolves null.
+ */
+function converse(socketPath, line, firstMs, limitMs, onLine) {
+    return new Promise(resolve => {
+        const socket = connect(socketPath);
+        let buffer = "";
+        let first = true;
+        let settled = false;
+        let timer = setTimeout(() => finish(null), firstMs);
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setEncoding("utf8");
+        socket.on("error", () => finish(null));
+        socket.on("close", () => finish(null));
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > MAX_LINE_BYTES * 4) {
+                finish(null);
+                return;
+            }
+            let newline;
+            while (!settled && (newline = buffer.indexOf("\n")) >= 0) {
+                const text = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                const step = onLine(text, first);
+                if (first) {
+                    first = false;
+                    clearTimeout(timer);
+                    timer = setTimeout(() => finish(null), limitMs);
+                }
+                if (step.done)
+                    finish(step.value);
+            }
+        });
+        socket.write(line);
+    });
+}
+function contextOutput(event, text) {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } });
+}
+/** Returns the exit code: 2 only when a Claude Stop watcher wakes its session, else 0. Never throws. */
+export async function runHookClient(argv, io) {
+    try {
+        const args = parseArguments(argv, io.env);
+        if (args === null)
+            return 0;
+        const raw = await readInput(io.stdin, io.stdinTimeoutMs ?? STDIN_TIMEOUT_MS);
+        const record = raw === null ? null : parseRecord(raw);
+        const input = record === null ? null : hookFields(record);
+        if (record === null || input === null)
+            return 0;
+        // Before the first byte goes to the hub: a session nobody attends is not registered, shown an ask or counted as seen.
+        if (!isHumanSession(args.app, io.env, record, args.stateRoot))
+            return 0;
+        const socketPath = join(args.stateRoot, HUB_SOCKET);
+        const hubTimeoutMs = io.hubTimeoutMs ?? HUB_TIMEOUT_MS;
+        if (args.app === "claude" && args.event === "stop") {
+            // The asyncRewake watcher: exit 2 with the text on stderr wakes Claude, even when the session is idle.
+            const text = await converse(socketPath, encodeLine({ v: 1, op: "watch", app: "claude", session_id: input.sessionId, cwd: input.cwd }), hubTimeoutMs, io.watchLimitMs ?? WATCH_LIMIT_MS, (line, first) => {
+                const message = parseWatchMessage(line);
+                if (message?.type === "wake")
+                    return { done: true, value: message.text };
+                if (message?.type === "watching" && first)
+                    return { done: false };
+                return { done: true, value: null };
+            });
+            if (text === null)
+                return 0;
+            io.stderr(text);
+            return 2;
+        }
+        const request = args.event === "stop"
+            ? { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd, stop_hook_active: input.stopHookActive }
+            : { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd };
+        const text = await converse(socketPath, encodeLine(request), hubTimeoutMs, hubTimeoutMs, line => ({ done: true, value: parseEventResponse(line)?.text ?? null }));
+        if (text === null || text === "")
+            return 0;
+        if (args.event === "session-start")
+            io.stdout(contextOutput("SessionStart", text));
+        else if (args.event === "prompt")
+            io.stdout(contextOutput("UserPromptSubmit", text));
+        else if (args.event === "stop")
+            io.stdout(JSON.stringify({ decision: "block", reason: text }));
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** True when Node runs this file as its entry point, directly or through a symlink. */
+function isDirectInvocation(moduleUrl, argvPath) {
+    if (!argvPath)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectInvocation(import.meta.url, process.argv[1])) {
+    void runHookClient(process.argv.slice(2), {
+        stdin: process.stdin,
+        stdout: text => { process.stdout.write(`${text}\n`); },
+        stderr: text => { process.stderr.write(`${text}\n`); },
+        env: process.env,
+    }).then(code => {
+        process.exitCode = code;
+        process.stdin.destroy();
+    });
+}

package/dist/src/asks/hub-protocol.js

@@ -0,0 +1,97 @@
+import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
+/*
+ * The line protocol between the hook client and the daemon's local hub (Work Item e1c08b33, spec section 8.2):
+ * one JSON object per line over the Unix socket <stateRoot>/hub.sock. The hook client imports this module, so it
+ * may import nothing but ./types.js.
+ *
+ * Client to hub, one line, then the client waits without closing its side:
+ *   {"v":1,"op":"event","app":"claude"|"codex","event":"session-start"|"prompt"|"session-end","session_id":…,"cwd":…}
+ *   {"v":1,"op":"event","app":"codex","event":"stop","session_id":…,"cwd":…,"stop_hook_active":false}
+ *   {"v":1,"op":"watch","app":"claude","session_id":…,"cwd":…}        (the Claude Stop watcher)
+ *   {"v":1,"op":"status"}                                             (doctor)
+ * Hub to client:
+ *   event:  {"v":1,"ok":true,"text":"…"|null}, then the hub closes the connection
+ *   status: {"v":1,"ok":true,"status":{"deliveries":n,"live_sessions":n,"watchers":n}}
+ *   error:  {"v":1,"ok":false,"code":"invalid_request"|"unavailable"}
+ *   watch:  {"v":1,"type":"wake","text":"…"} at once, or {"v":1,"type":"watching"} and later at most one of
+ *           {"v":1,"type":"wake","text":"…"} or {"v":1,"type":"release","reason":"replaced"|"session_ended"|"shutdown"}
+ *           A watch the hub refuses, or answers too late, ends with a bare close and no message; the client exits 0 on that too.
+ */
+export const HUB_SOCKET = "hub.sock";
+/** The hook client prints nothing and exits 0 when the hub has not answered within 300 ms. */
+export const HUB_TIMEOUT_MS = 300;
+/** A Claude Stop watcher exits 0 after 3500 s; its hook timeout is 3600 s. */
+export const WATCH_LIMIT_MS = 3_500_000;
+/** The most hook input the client reads from stdin. */
+export const MAX_HOOK_INPUT_BYTES = 64 * 1024;
+/** The longest request or response line. */
+export const MAX_LINE_BYTES = 16 * 1024;
+/** macOS keeps 104 bytes for a Unix socket path, including the terminating NUL; Node silently truncates longer ones. */
+export const MAX_SOCKET_PATH_BYTES = 103;
+export function encodeLine(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+function record(line) {
+    try {
+        const value = JSON.parse(line);
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A request from the hook client, or null when anything is missing, unknown or out of range. The session id and the
+ * cwd are held to the limits the ask store applies on a load (SESSION_ID, MAX_CWD_LENGTH): a session the store would
+ * drop at the next start must never be registered, because it would orphan every delivery pinned to it.
+ */
+export function parseHubRequest(line) {
+    const value = record(line);
+    if (value === null || value.v !== 1)
+        return null;
+    if (value.op === "status")
+        return Object.keys(value).length === 2 ? { v: 1, op: "status" } : null;
+    if (typeof value.session_id !== "string" || !SESSION_ID.test(value.session_id))
+        return null;
+    if (typeof value.cwd !== "string" || value.cwd.length > MAX_CWD_LENGTH)
+        return null;
+    if (value.op === "watch") {
+        if (value.app !== "claude" || Object.keys(value).length !== 5)
+            return null;
+        return { v: 1, op: "watch", app: "claude", session_id: value.session_id, cwd: value.cwd };
+    }
+    if (value.op !== "event" || !isApp(value.app) || !isHookEvent(value.event))
+        return null;
+    // A Claude turn end is always a watch; only Codex sends a plain stop, with its loop guard.
+    if (value.event === "stop") {
+        if (value.app !== "codex" || typeof value.stop_hook_active !== "boolean" || Object.keys(value).length !== 7)
+            return null;
+        return { v: 1, op: "event", app: "codex", event: "stop", session_id: value.session_id, cwd: value.cwd, stop_hook_active: value.stop_hook_active };
+    }
+    if (Object.keys(value).length !== 6)
+        return null;
+    return { v: 1, op: "event", app: value.app, event: value.event, session_id: value.session_id, cwd: value.cwd };
+}
+/** The hub's answer to an event request, or null when it is not one. */
+export function parseEventResponse(line) {
+    const value = record(line);
+    if (value === null || value.v !== 1 || value.ok !== true)
+        return null;
+    if (value.text === null)
+        return { text: null };
+    return typeof value.text === "string" ? { text: value.text } : null;
+}
+/** One message on a watch connection, or null when it is not one. */
+export function parseWatchMessage(line) {
+    const value = record(line);
+    if (value === null || value.v !== 1)
+        return null;
+    if (value.type === "watching")
+        return { v: 1, type: "watching" };
+    if (value.type === "wake" && typeof value.text === "string" && value.text !== "")
+        return { v: 1, type: "wake", text: value.text };
+    if (value.type === "release" && (value.reason === "replaced" || value.reason === "session_ended" || value.reason === "shutdown")) {
+        return { v: 1, type: "release", reason: value.reason };
+    }
+    return null;
+}

package/dist/src/asks/hub.js

@@ -0,0 +1,202 @@
+import { createServer } from "node:net";
+import { chmod, lstat, mkdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { HUB_SOCKET, HUB_TIMEOUT_MS, MAX_LINE_BYTES, MAX_SOCKET_PATH_BYTES, encodeLine, parseHubRequest, } from "./hub-protocol.js";
+/*
+ * The daemon's local hub (Work Item e1c08b33, spec section 8.2). A Unix socket, mode 0600 in the 0700 state
+ * root, so only this user can reach it. It answers one request per connection and keeps a Claude Stop watcher's
+ * connection open until the handler wakes or releases it. It holds no ask state itself: the handler does.
+ */
+/**
+ * The hook client gives up after HUB_TIMEOUT_MS and prints nothing. A request that has waited this long, a little less
+ * to leave room for the write, can no longer be answered in time: the hub changes nothing for it.
+ */
+export const HUB_ANSWER_WINDOW_MS = HUB_TIMEOUT_MS - 100;
+export function hubSocketPath(stateRoot) {
+    return join(stateRoot, HUB_SOCKET);
+}
+/**
+ * True when nothing more can be sent to, or read from, the client. The client never half-closes its side, so an
+ * ended read side means it left. The socket's own state is read because its 'close' event can come several turns of
+ * the event loop later.
+ */
+function hasLeft(socket) {
+    return socket.destroyed || !socket.writable || socket.readableEnded;
+}
+function waitedTooLong(arrivedAt) {
+    return performance.now() - arrivedAt > HUB_ANSWER_WINDOW_MS;
+}
+/** The client of an event request whose line arrived at `arrivedAt` (performance.now()). */
+export function clientFor(socket, arrivedAt) {
+    return { get gone() { return hasLeft(socket) || waitedTooLong(arrivedAt); } };
+}
+/** The watcher for one watch connection. `answered` is true once anything was sent on it. */
+export function watcherFor(socket, arrivedAt = performance.now()) {
+    let closeEvent = false;
+    let answered = false;
+    const listeners = [];
+    socket.once("close", () => {
+        closeEvent = true;
+        for (const listener of listeners.splice(0))
+            listener();
+    });
+    const closed = () => closeEvent || hasLeft(socket);
+    const send = (message, last) => {
+        if (closed())
+            return false;
+        socket.write(encodeLine(message));
+        answered = true;
+        if (last)
+            socket.end();
+        return true;
+    };
+    return {
+        get closed() { return closed(); },
+        // Once something was sent the client has its answer; only a watch that is still unanswered can be too late.
+        get gone() { return closed() || (!answered && waitedTooLong(arrivedAt)); },
+        get answered() { return answered; },
+        hold: () => send({ v: 1, type: "watching" }, false),
+        wake: text => send({ v: 1, type: "wake", text }, true),
+        release: reason => { send({ v: 1, type: "release", reason }, true); },
+        onClose: listener => { if (closeEvent)
+            listener();
+        else
+            listeners.push(listener); },
+    };
+}
+/** A socket left behind by a daemon that died is removed; anything else at that path is never touched. */
+async function removeStaleSocket(path) {
+    try {
+        if (!(await lstat(path)).isSocket())
+            throw new Error("ASK_HUB_PATH_NOT_A_SOCKET");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    await rm(path, { force: true });
+}
+export class AskHub {
+    options;
+    server = null;
+    sockets = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get listening() {
+        return this.server !== null;
+    }
+    async start() {
+        // A second listener would remove the live socket as if it were stale.
+        if (this.server !== null)
+            throw new Error("ASK_HUB_ALREADY_LISTENING");
+        const path = this.options.socketPath;
+        if (Buffer.byteLength(path) > MAX_SOCKET_PATH_BYTES)
+            throw new Error("ASK_HUB_SOCKET_PATH_TOO_LONG");
+        const directory = dirname(path);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await chmod(directory, 0o700);
+        await removeStaleSocket(path);
+        const server = createServer(socket => this.connection(socket));
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(path, () => { server.off("error", reject); resolve(); });
+        });
+        // A listening server can still emit an error (accepting with no file descriptors left, say); without a listener Node
+        // would throw it and take the daemon down. Only its code is logged.
+        server.on("error", error => this.logServerError(error));
+        try {
+            // listen() creates the socket with the umask's mode (0755); only this user may connect.
+            await chmod(path, 0o600);
+        }
+        catch (error) {
+            // Never leave a socket listening that is not private, nor a connection that was accepted on it.
+            for (const socket of this.sockets)
+                socket.destroy();
+            await new Promise(resolve => server.close(() => resolve()));
+            await rm(path, { force: true });
+            throw error;
+        }
+        this.server = server;
+    }
+    async stop() {
+        const server = this.server;
+        this.server = null;
+        if (server === null)
+            return;
+        for (const socket of this.sockets)
+            socket.destroy();
+        await new Promise(resolve => server.close(() => resolve()));
+        await rm(this.options.socketPath, { force: true });
+    }
+    connection(socket) {
+        this.sockets.add(socket);
+        socket.once("close", () => this.sockets.delete(socket));
+        socket.on("error", () => undefined);
+        socket.setEncoding("utf8");
+        // A client that never sends a full line is dropped; a watch request clears the timer and stays open.
+        socket.setTimeout(this.options.requestTimeoutMs ?? 2000, () => socket.destroy());
+        let buffer = "";
+        const onData = (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            // A line over the limit is dropped without an answer, whether or not its end has arrived yet.
+            if (Buffer.byteLength(newline < 0 ? buffer : buffer.slice(0, newline)) > MAX_LINE_BYTES) {
+                socket.destroy();
+                return;
+            }
+            if (newline < 0)
+                return;
+            const arrivedAt = performance.now();
+            socket.off("data", onData);
+            // Keep reading, so the client leaving is seen while its request waits.
+            socket.resume();
+            socket.setTimeout(0);
+            void this.dispatch(buffer.slice(0, newline), socket, arrivedAt);
+        };
+        socket.on("data", onData);
+    }
+    async dispatch(line, socket, arrivedAt) {
+        const reply = (response) => { if (!hasLeft(socket))
+            socket.end(encodeLine(response)); };
+        const request = parseHubRequest(line);
+        if (request === null) {
+            reply({ v: 1, ok: false, code: "invalid_request" });
+            return;
+        }
+        try {
+            if (request.op === "status") {
+                reply({ v: 1, ok: true, status: this.options.handler.status() });
+            }
+            else if (request.op === "event") {
+                reply({ v: 1, ok: true, text: await this.options.handler.event(request, clientFor(socket, arrivedAt)) });
+            }
+            else {
+                const watcher = watcherFor(socket, arrivedAt);
+                await this.options.handler.watch(request, watcher);
+                // The handler sent nothing: it refused a client that had gone. Do not leave a connection open that nobody answers.
+                if (!watcher.answered)
+                    socket.destroy();
+            }
+        }
+        catch (error) {
+            this.logFailure(request.op, error);
+            reply({ v: 1, ok: false, code: "unavailable" });
+        }
+    }
+    logServerError(error) {
+        const code = error?.code;
+        try {
+            this.options.log?.({ event: "ask_hub_server_error", code: typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : "UNKNOWN" });
+        }
+        catch { /* Logging never stops the hub. */ }
+    }
+    logFailure(op, error) {
+        const code = error?.code;
+        try {
+            this.options.log?.({ event: "ask_hub_handler_failed", op, error: typeof code === "string" ? code : error instanceof Error ? error.name : "UNKNOWN" });
+        }
+        catch { /* Logging never stops the hub. */ }
+    }
+}