@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/services.js

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { connect } from "node:net";
+import { join } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { agentShell } from "./agent-shell.js";
+import { maskSecrets } from "./masking.js";
+import { modulesScratchDir } from "./paths.js";
+import { isRunning, startInBackground, stopGroup } from "./shell.js";
+/**
+ * What an agent starts and keeps running while it works - a server, a worker - to try the software as someone would,
+ * from outside: with curl, or what the stack's own client is. Whatever the stack: the agent gives the command that
+ * starts it, and how to tell it is up - a port that answers, or a line in its log. It runs on this machine behind the
+ * same walls as the agent's own shell - the command check, the module's environment, the OS sandbox, the audit while it
+ * starts - in a process group of its own, so it outlives the command that started it; it is stopped - it and everything
+ * it started - when the agent asks, when the agent's session ends, and in any case when its pulse ends.
+ */
+/** How many services one agent may have running at once. */
+export const MAX_SERVICES = 3;
+const DEFAULT_READY_SECONDS = 60;
+const MAX_READY_SECONDS = 300;
+const LOG_LINES = 80;
+/** Whether something on this machine answers on `port`. */
+function answers(port) {
+    return new Promise((done) => {
+        const socket = connect({ host: "127.0.0.1", port });
+        const end = (up) => {
+            socket.destroy();
+            done(up);
+        };
+        socket.once("connect", () => end(true));
+        socket.once("error", () => end(false));
+        socket.setTimeout(1000, () => end(false));
+    });
+}
+/** The last `lines` of a log, masked. */
+function tail(log, lines = LOG_LINES) {
+    if (!existsSync(log))
+        return "";
+    return maskSecrets(readFileSync(log, "utf8").trimEnd().split("\n").slice(-lines).join("\n"));
+}
+/**
+ * Start, read and stop services from `dir` - the folder the agent works in - fenced as its role is: what it may read and
+ * write (its workdir when not given), or the shell given.
+ */
+export function createServiceTools(options) {
+    let shell = options.shell;
+    const shellOf = () => (shell ??= agentShell({ workdir: options.dir, ...(options.read !== undefined ? { read: options.read } : {}), ...(options.write !== undefined ? { write: options.write } : {}) }));
+    const running = new Map();
+    const say = (text) => ({ content: [{ type: "text", text }], details: {} });
+    const logsDir = join(modulesScratchDir(options.dir), "services");
+    const stop = async (service) => {
+        running.delete(service.name);
+        await stopGroup(service.pid);
+    };
+    const start = defineTool({
+        name: "start_service",
+        label: "Start a service",
+        description: "Start something that keeps running - a server, a worker - in the background, behind the same walls as your shell, to " +
+            "try what is built from outside: then reach it with curl (or the stack's own client) in bash. Give the command that " +
+            "starts it, from the code folder, and how to tell it is up: the port it listens on, or a line its log prints once it is " +
+            `ready. It returns once it is up - or, if it exits or is not up in time, what it printed. ${MAX_SERVICES} at once at ` +
+            "most; each runs until you stop it with stop_service, and is stopped in any case when you finish. A port something " +
+            "else holds is not yours: choose another.",
+        promptSnippet: "start_service: run a server in the background, to try it from outside with curl",
+        parameters: Type.Object({
+            name: Type.String({ description: "A short name for it, to read its log and stop it by" }),
+            command: Type.String({ description: "The command that starts it, run from the code folder - e.g. `uvicorn src.main:app --port 8000`" }),
+            port: Type.Optional(Type.Number({ description: "The port it listens on: it is up once the port answers" })),
+            ready_log: Type.Optional(Type.String({ description: "Text its log prints once it is up - used when it has no port" })),
+            timeout_seconds: Type.Optional(Type.Number({ description: `How long it may take to come up. Default ${DEFAULT_READY_SECONDS}, at most ${MAX_READY_SECONDS}` })),
+        }),
+        async execute(_id, params) {
+            const { name, command, port, ready_log: readyLog, timeout_seconds: seconds } = params;
+            if (running.has(name))
+                return say(`A service called ${name} is running already: stop it first, or give this one another name.`);
+            if (running.size >= MAX_SERVICES)
+                return say(`${MAX_SERVICES} services are running already (${[...running.keys()].join(", ")}): stop one first.`);
+            const fenced = shellOf();
+            const checked = fenced.check(command);
+            if (!checked.ok)
+                return say(`Not started: ${checked.reason}`);
+            mkdirSync(logsDir, { recursive: true });
+            const log = join(logsDir, `${name.replace(/[^\w.-]+/g, "_")}-${randomUUID().slice(0, 8)}.log`);
+            const limit = Math.min(Math.max(seconds ?? DEFAULT_READY_SECONDS, 1), MAX_READY_SECONDS);
+            // Started and waited on under the audit: what it writes while it comes up, outside its role, is put back.
+            const { value: outcome, note } = await fenced.audited(async () => {
+                const { pid } = startInBackground(command, { cwd: options.dir, env: fenced.env, wrap: (argv) => fenced.wrap(argv), logFile: log });
+                running.set(name, { name, command, pid, log });
+                for (let i = 0; i < limit * 4; i += 1) {
+                    if (!isRunning(pid))
+                        return "EXITED";
+                    if (port !== undefined ? await answers(Math.trunc(port)) : readyLog !== undefined ? tail(log, 10_000).includes(readyLog) : i >= 8) {
+                        // Up - and still running a moment later: a port someone else holds answers too, while this one exits.
+                        await new Promise((done) => setTimeout(done, 100));
+                        return isRunning(pid) ? "READY" : "EXITED";
+                    }
+                    await new Promise((done) => setTimeout(done, 250));
+                }
+                return "TIMEOUT";
+            });
+            const service = running.get(name);
+            const printed = tail(log);
+            const audit = note !== undefined ? `\n\n${note}` : "";
+            if (outcome === "READY") {
+                const where = port !== undefined ? ` on port ${Math.trunc(port)} - reach it with curl http://127.0.0.1:${Math.trunc(port)}/...` : "";
+                return say(`${name} is up${where}. stop_service stops it; service_logs reads what it prints.\n\n<its log so far>\n${printed}\n</its log so far>${audit}`);
+            }
+            await stop(service);
+            const why = outcome === "EXITED" ? "It exited before it was up" : `It was not up after ${limit} seconds, and was stopped`;
+            return say(`${why}. What it printed:\n\n${printed || "(nothing)"}${audit}`);
+        },
+    });
+    const logs = defineTool({
+        name: "service_logs",
+        label: "Service logs",
+        description: "The last lines a service started with start_service has printed - its requests, its errors and their traces.",
+        promptSnippet: "service_logs: what a service you started has printed",
+        parameters: Type.Object({
+            name: Type.String({ description: "The service's name" }),
+            lines: Type.Optional(Type.Number({ description: `How many of the last lines. Default ${LOG_LINES}` })),
+        }),
+        async execute(_id, params) {
+            const { name, lines } = params;
+            const service = running.get(name);
+            if (service === undefined)
+                return say(`No service called ${name} is running.${running.size > 0 ? ` Running: ${[...running.keys()].join(", ")}.` : ""}`);
+            const printed = tail(service.log, Math.min(Math.max(Math.trunc(lines ?? LOG_LINES), 1), 1000));
+            return say(`${isRunning(service.pid) ? `${name} is running.` : `${name} has exited.`}\n\n${printed || "(nothing printed)"}`);
+        },
+    });
+    const stopTool = defineTool({
+        name: "stop_service",
+        label: "Stop a service",
+        description: "Stop a service started with start_service, and everything it started.",
+        promptSnippet: "stop_service: stop a service you started",
+        parameters: Type.Object({ name: Type.String({ description: "The service's name" }) }),
+        async execute(_id, params) {
+            const { name } = params;
+            const service = running.get(name);
+            if (service === undefined)
+                return say(`No service called ${name} is running.`);
+            await stop(service);
+            return say(`${name} is stopped.`);
+        },
+    });
+    return {
+        tools: [start, logs, stopTool],
+        names: ["start_service", "service_logs", "stop_service"],
+        async stopAll() {
+            await Promise.all([...running.values()].map((service) => stop(service)));
+        },
+    };
+}

package/dist/regenerate/shell.js

@@ -0,0 +1,319 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { constants, tmpdir } from "node:os";
+import { join } from "node:path";
+import { currentStopSignal } from "./activity.js";
+import { maskingStream } from "./masking.js";
+/**
+ * How long a command may run before it is stopped - an agent's own, its tests, the harness's runs. Nothing an agent
+ * starts may hang a build: a server started in the foreground, a watcher, a prompt waiting for input would otherwise
+ * hold the agent's turn, and the job, forever. TURRI_COMMAND_TIMEOUT sets it, in seconds.
+ */
+export const COMMAND_TIMEOUT_MS = Number(process.env.TURRI_COMMAND_TIMEOUT ?? 120) * 1000;
+/** The longest an agent may ask one of its own commands to run for. */
+export const MAX_COMMAND_TIMEOUT_MS = Math.max(COMMAND_TIMEOUT_MS, 30 * 60_000);
+/** What a command that ran out of time leaves in its output, for the agent to act on. */
+export function timedOutNote(timeoutMs) {
+    return (`\n[stopped after ${Math.round(timeoutMs / 1000)}s, the time limit. A command that never ends on its own - a ` +
+        "server, a watcher, a prompt waiting for input - has to be started in the background (`cmd > app.log 2>&1 &`) " +
+        "or given its input; a slow one can be given a longer timeout.]");
+}
+/** How long a command's output is waited for once it has ended: past that, what holds it is a server it left behind. */
+const OUTPUT_GRACE_MS = 100;
+const WINDOWS = process.platform === "win32";
+/** Every group this turri started that may still be running: by its leader's process id, which is the group's id. */
+const groups = new Set();
+/** The current pulse. */
+const pulse = new AsyncLocalStorage();
+/** Every pulse running in this process. */
+const pulses = new Set();
+/**
+ * Whether a pulse other than the current one is at work in `moduleDir` - what changes there is that pulse's, and the
+ * audit leaves it.
+ */
+export function anotherPulseIn(moduleDir) {
+    const mine = pulse.getStore();
+    for (const other of pulses)
+        if (other !== mine && other.modules.has(moduleDir))
+            return true;
+    return false;
+}
+/** Where each running turri records its groups, a file named for its process id: for its watcher, and the sweep. */
+export function groupRecordsDir() {
+    return join(tmpdir(), "turri-groups");
+}
+function recordFile() {
+    return join(groupRecordsDir(), `${process.pid}`);
+}
+function writeRecord() {
+    try {
+        if (groups.size === 0) {
+            rmSync(recordFile(), { force: true });
+            return;
+        }
+        mkdirSync(groupRecordsDir(), { recursive: true });
+        writeFileSync(recordFile(), [...groups].map((group) => `${group}\n`).join(""));
+    }
+    catch {
+        // Only the watcher and the sweep read it; exit kills the groups all the same.
+    }
+}
+let watching = false;
+/**
+ * A small shell beside this turri that waits for it to end, then kills every group it recorded - for a turri killed
+ * outright, which runs no exit handler. It ends with the turri; it holds nothing open.
+ */
+function watch() {
+    if (watching || WINDOWS)
+        return;
+    watching = true;
+    const file = recordFile();
+    const script = [
+        `while kill -0 ${process.pid} 2>/dev/null; do sleep 2; done`,
+        `[ -f '${file}' ] || exit 0`,
+        `while read -r group; do kill -KILL -- "-$group" 2>/dev/null; done < '${file}'`,
+        `rm -f '${file}'`,
+    ].join("\n");
+    try {
+        spawn("/bin/sh", ["-c", script], { detached: true, stdio: "ignore" }).unref();
+    }
+    catch {
+        // The sweep at the next start is there still.
+    }
+}
+function track(group) {
+    groups.add(group);
+    pulse.getStore()?.groups.add(group);
+    writeRecord();
+    watch();
+}
+function forget(group) {
+    groups.delete(group);
+    writeRecord();
+}
+/** Whether anything in the group still runs. */
+function groupAlive(group) {
+    if (WINDOWS)
+        return false;
+    try {
+        process.kill(-group, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Kill a group, everything in it. */
+function killGroup(group) {
+    if (WINDOWS) {
+        spawnSync("taskkill", ["/T", "/F", "/PID", String(group)], { stdio: "ignore", windowsHide: true });
+        return;
+    }
+    try {
+        process.kill(-group, "SIGKILL");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Run `work` - a pulse - and kill every group it started when it ends, however it ends: what an agent left running in
+ * the background is the pulse's, and goes with it. Groups of a pulse running beside it are left alone. `modules`: the
+ * module folders it works in - its lanes - which the audit of another pulse's commands leaves to it.
+ */
+export async function withPulse(work, options = {}) {
+    const mine = { groups: new Set(), modules: new Set(options.modules ?? []) };
+    pulses.add(mine);
+    try {
+        return await pulse.run(mine, work);
+    }
+    finally {
+        pulses.delete(mine);
+        for (const group of mine.groups) {
+            killGroup(group);
+            forget(group);
+        }
+    }
+}
+/** Kill every group this turri started. Called as it exits; the tests call it between files. */
+export function killAllGroups() {
+    for (const group of groups)
+        killGroup(group);
+    groups.clear();
+    writeRecord();
+}
+/**
+ * Kill the groups turris that are gone left behind - killed outright, their watcher gone too - from their records in
+ * `dir`. A running turri's are its own. Returns how many groups were still there to kill.
+ */
+export function sweepOrphanedGroups(dir = groupRecordsDir()) {
+    if (WINDOWS || !existsSync(dir))
+        return 0;
+    let killed = 0;
+    for (const name of readdirSync(dir)) {
+        const owner = Number(name);
+        if (!Number.isInteger(owner) || owner === process.pid || processAlive(owner))
+            continue;
+        const file = join(dir, name);
+        try {
+            for (const line of readFileSync(file, "utf8").split("\n")) {
+                const group = Number(line.trim());
+                if (!Number.isInteger(group) || group <= 1 || !groupAlive(group))
+                    continue;
+                killGroup(group);
+                killed += 1;
+            }
+        }
+        finally {
+            rmSync(file, { force: true });
+        }
+    }
+    return killed;
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Alive, but not ours to signal.
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Run `command` with bash on this machine, from `cwd`, in a process group of its own.
+ *
+ * It has a time limit - COMMAND_TIMEOUT_MS unless given another - and ends at once when it is stopped, by the caller's
+ * signal or the job's; either way its whole group is killed. Ended on its own, what it left in the background runs on
+ * until its pulse ends.
+ */
+export async function runCommand(command, options) {
+    const timeoutMs = options.timeoutMs ?? COMMAND_TIMEOUT_MS;
+    const signals = [options.signal, currentStopSignal()].filter((signal) => signal !== undefined);
+    // An abort that has already happened fires no event: the command is not started at all.
+    if (signals.some((signal) => signal.aborted))
+        throw new Error("aborted");
+    const argv = options.wrap !== undefined ? options.wrap(["bash", "-c", command]) : ["bash", "-c", command];
+    const child = spawn(argv[0], argv.slice(1), {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        detached: !WINDOWS,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    const group = child.pid;
+    if (group !== undefined)
+        track(group);
+    // The credentials passed to agents are masked as the output streams, before anything sees it.
+    let output = "";
+    const masked = maskingStream((data) => {
+        output += data.toString("utf8");
+        options.onData?.(data);
+    });
+    const take = (data) => masked.write(data);
+    child.stdout.on("data", take);
+    child.stderr.on("data", take);
+    let timedOut = false;
+    let stopped = false;
+    const kill = () => {
+        if (group !== undefined)
+            killGroup(group);
+    };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        kill();
+    }, timeoutMs);
+    const onAbort = () => {
+        stopped = true;
+        kill();
+    };
+    for (const signal of signals)
+        signal.addEventListener("abort", onAbort, { once: true });
+    const exitCode = await new Promise((done) => {
+        child.on("error", (error) => {
+            take(Buffer.from(String(error.message)));
+            done(1);
+        });
+        child.on("exit", (code, signal) => {
+            // The rest of its output, unless a server it left behind holds the pipe: that is not waited for.
+            const grace = setTimeout(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+            }, OUTPUT_GRACE_MS);
+            child.on("close", () => clearTimeout(grace));
+            const ended = () => done(code ?? 128 + (signal !== null ? (constants.signals[signal] ?? 0) : 0));
+            const open = [child.stdout, child.stderr].filter((stream) => !stream.closed);
+            let left = open.length;
+            if (left === 0)
+                ended();
+            for (const stream of open)
+                stream.once("close", () => (--left === 0 ? ended() : undefined));
+        });
+    });
+    masked.end();
+    clearTimeout(timer);
+    for (const signal of signals)
+        signal.removeEventListener("abort", onAbort);
+    if (group !== undefined && !groupAlive(group))
+        forget(group);
+    if (stopped)
+        throw new Error("aborted");
+    if (timedOut) {
+        const note = (options.timeoutNote ?? timedOutNote)(timeoutMs);
+        options.onData?.(Buffer.from(note));
+        return { exitCode: 124, output: `${output}${note}`, timedOut: true };
+    }
+    return { exitCode, output };
+}
+/**
+ * Start `command` in the background, in a process group of its own, its output to `logFile` - a server an agent starts
+ * to try from outside. It is its pulse's: running until stopped (`stopGroup`), and killed when the pulse ends.
+ */
+export function startInBackground(command, options) {
+    const argv = options.wrap !== undefined ? options.wrap(["bash", "-c", command]) : ["bash", "-c", command];
+    const log = openSync(options.logFile, "a");
+    try {
+        const child = spawn(argv[0], argv.slice(1), { cwd: options.cwd, env: options.env ?? process.env, detached: !WINDOWS, stdio: ["ignore", log, log], windowsHide: true });
+        child.on("error", () => undefined);
+        child.unref();
+        if (child.pid === undefined)
+            throw new Error(`${argv[0]} could not be started`);
+        track(child.pid);
+        return { pid: child.pid };
+    }
+    finally {
+        closeSync(log);
+    }
+}
+/** Whether a process is still running. */
+export function isRunning(pid) {
+    if (WINDOWS)
+        return spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/NH"], { encoding: "utf8", windowsHide: true }).stdout.includes(String(pid));
+    return processAlive(pid);
+}
+/** Stop a group started in the background: asked to end, then - after `graceMs` - made to. */
+export async function stopGroup(group, graceMs = 1000) {
+    if (!WINDOWS) {
+        try {
+            process.kill(-group, "SIGTERM");
+        }
+        catch {
+            // Already gone.
+        }
+        const end = Date.now() + graceMs;
+        while (groupAlive(group) && Date.now() < end)
+            await new Promise((done) => setTimeout(done, 50));
+    }
+    killGroup(group);
+    forget(group);
+}
+process.on("exit", killAllGroups);
+// A process ended by a signal never exits in the sense that runs the handler above: where nothing else handles the
+// signal, exit properly on it.
+for (const [signal, code] of [["SIGTERM", 143], ["SIGHUP", 129], ["SIGINT", 130]]) {
+    process.once(signal, () => {
+        if (process.listenerCount(signal) === 0)
+            process.exit(code);
+    });
+}