@nettee/beacon 0.5.0 → 0.6.0

package/dist/daemon/runtime/pi-worker-lifecycle.js

@@ -0,0 +1,208 @@
+import { spawn } from "node:child_process";
+import { access, chmod, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_ORPHAN_AFTER_MS, isSupervisorLeaseFresh, } from "./supervisor-lease.js";
+const REQUEST_FILE = "request.json";
+const COMPLETION_FILE = "completion.json";
+const HEARTBEAT_FILE = "worker.heartbeat";
+const PID_FILE = "worker.pid";
+export function lifecyclePaths(lifecycleDirectory) {
+    return {
+        request: join(lifecycleDirectory, REQUEST_FILE),
+        completion: join(lifecycleDirectory, COMPLETION_FILE),
+        heartbeat: join(lifecycleDirectory, HEARTBEAT_FILE),
+        pid: join(lifecycleDirectory, PID_FILE),
+        outcomeSocket: join(lifecycleDirectory, "outcomes.sock"),
+    };
+}
+export async function prepareLifecycleDirectory(lifecycleDirectory) {
+    if (!isAbsolute(lifecycleDirectory)) {
+        throw new Error("Pi worker lifecycle directory must be absolute");
+    }
+    await mkdir(lifecycleDirectory, { recursive: true, mode: 0o700 });
+    await chmod(lifecycleDirectory, 0o700);
+    const paths = lifecyclePaths(lifecycleDirectory);
+    await rm(paths.completion, { force: true });
+    await rm(paths.heartbeat, { force: true });
+    await rm(paths.pid, { force: true });
+    await rm(paths.outcomeSocket, { force: true });
+}
+export async function writeWorkerRequest(lifecycleDirectory, request) {
+    await prepareLifecycleDirectory(lifecycleDirectory);
+    const temporary = `${lifecyclePaths(lifecycleDirectory).request}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(request, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(temporary, lifecyclePaths(lifecycleDirectory).request);
+}
+export async function readWorkerRequest(lifecycleDirectory) {
+    const raw = JSON.parse(await readFile(lifecyclePaths(lifecycleDirectory).request, "utf8"));
+    if (!raw.beaconCliPath || !raw.runToken || !raw.supervisorLeasePath) {
+        throw new Error("Pi worker request is missing required fields");
+    }
+    return raw;
+}
+export async function writeWorkerHeartbeat(lifecycleDirectory) {
+    const temporary = `${lifecyclePaths(lifecycleDirectory).heartbeat}.tmp`;
+    await writeFile(temporary, `${JSON.stringify({ pid: process.pid, updatedAt: new Date().toISOString() })}\n`, { mode: 0o600 });
+    await rename(temporary, lifecyclePaths(lifecycleDirectory).heartbeat);
+}
+export async function writeWorkerPid(lifecycleDirectory, pid) {
+    await writeFile(lifecyclePaths(lifecycleDirectory).pid, `${pid}\n`, {
+        mode: 0o600,
+    });
+}
+export async function writeWorkerCompletion(lifecycleDirectory, completion) {
+    const temporary = `${lifecyclePaths(lifecycleDirectory).completion}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(completion, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(temporary, lifecyclePaths(lifecycleDirectory).completion);
+}
+export async function readWorkerCompletion(lifecycleDirectory) {
+    try {
+        return JSON.parse(await readFile(lifecyclePaths(lifecycleDirectory).completion, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readWorkerHeartbeat(lifecycleDirectory) {
+    try {
+        const raw = JSON.parse(await readFile(lifecyclePaths(lifecycleDirectory).heartbeat, "utf8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            !("pid" in raw) ||
+            !("updatedAt" in raw) ||
+            typeof raw.pid !== "number" ||
+            typeof raw.updatedAt !== "string") {
+            return undefined;
+        }
+        return { pid: raw.pid, updatedAt: raw.updatedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readWorkerPid(lifecycleDirectory) {
+    try {
+        const raw = (await readFile(lifecyclePaths(lifecycleDirectory).pid, "utf8")).trim();
+        const pid = Number(raw);
+        return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isWorkerAdoptable(handle, nowMs = Date.now(), heartbeatMaxAgeMs = 60_000) {
+    if (!isProcessAlive(handle.workerPid))
+        return false;
+    const completion = await readWorkerCompletion(handle.lifecycleDirectory);
+    if (completion)
+        return true;
+    const heartbeat = await readWorkerHeartbeat(handle.lifecycleDirectory);
+    if (!heartbeat)
+        return false;
+    const updatedAt = Date.parse(heartbeat.updatedAt);
+    if (!Number.isFinite(updatedAt))
+        return false;
+    return nowMs - updatedAt <= heartbeatMaxAgeMs;
+}
+export async function waitForWorkerCompletion(lifecycleDirectory, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    for (;;) {
+        if (options.abortSignal?.aborted) {
+            throw new Error("Waiting for Pi worker completion was aborted");
+        }
+        const completion = await readWorkerCompletion(lifecycleDirectory);
+        if (completion)
+            return completion;
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, pollIntervalMs);
+            options.abortSignal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+    }
+}
+export function resolvePiWorkerMainPath() {
+    return fileURLToPath(new URL(import.meta.url.endsWith(".ts")
+        ? "../../dist/runtime/pi-worker-main.js"
+        : "./pi-worker-main.js", import.meta.url));
+}
+export async function spawnDetachedPiWorker(lifecycleDirectory, request, options) {
+    const orphanAfterMs = options.orphanAfterMs ?? DEFAULT_ORPHAN_AFTER_MS;
+    const workerRequest = {
+        ...request,
+        beaconCliPath: options.beaconCliPath,
+        runToken: options.runToken,
+        supervisorLeasePath: options.supervisorLeasePath,
+        orphanAfterMs,
+        executable: options.executable,
+        timeoutMs: options.timeoutMs,
+        terminateGraceMs: options.terminateGraceMs,
+        maxFrameBytes: options.maxFrameBytes,
+        environment: options.environment,
+        runtimeEnvironment: options.runtimeEnvironment,
+    };
+    await writeWorkerRequest(lifecycleDirectory, workerRequest);
+    const workerMainPath = options.workerMainPath ?? resolvePiWorkerMainPath();
+    try {
+        await access(workerMainPath);
+    }
+    catch (error) {
+        throw new Error(`Pi worker entry is missing (build the daemon first): ${workerMainPath}`, { cause: error });
+    }
+    const child = spawn(process.execPath, [workerMainPath, lifecycleDirectory], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            PATH: process.env.PATH,
+            HOME: process.env.HOME,
+            USER: process.env.USER,
+            TMPDIR: process.env.TMPDIR,
+            LANG: process.env.LANG,
+        },
+    });
+    if (child.pid === undefined) {
+        throw new Error("Failed to spawn detached Pi worker (no pid)");
+    }
+    child.unref();
+    await writeWorkerPid(lifecycleDirectory, child.pid);
+    return {
+        workerPid: child.pid,
+        lifecycleDirectory,
+        runToken: options.runToken,
+        supervisorLeasePath: options.supervisorLeasePath,
+        orphanAfterMs,
+    };
+}
+/** Stop a still-living worker (orphan / abandon). Best-effort. */
+export function signalWorker(pid, signal = "SIGTERM") {
+    if (!isProcessAlive(pid))
+        return;
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // already gone
+    }
+}
+export async function assertSupervisorOrThrow(supervisorLeasePath, orphanAfterMs) {
+    if (!(await isSupervisorLeaseFresh(supervisorLeasePath, orphanAfterMs))) {
+        throw new Error(`No Beacon supervisor lease for ${orphanAfterMs}ms; abandoning orphan Pi worker`);
+    }
+}

package/dist/daemon/runtime/pi-worker-main.d.ts

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

package/dist/daemon/runtime/pi-worker-main.js

@@ -0,0 +1,223 @@
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { completeOutcome, mergeOutcome, parseOutcomePatch, } from "../outcome/content.js";
+import { PiRuntimeError, runPiAgent } from "./pi-rpc.js";
+import { assertSupervisorOrThrow, lifecyclePaths, readWorkerRequest, writeWorkerCompletion, writeWorkerHeartbeat, } from "./pi-worker-lifecycle.js";
+import { DEFAULT_ORPHAN_AFTER_MS } from "./supervisor-lease.js";
+function respond(socket, response) {
+    socket.end(`${JSON.stringify(response)}\n`);
+}
+async function startWorkerOutcomeServer(socketPath, runToken, maxRequestBytes = 1024 * 1024) {
+    await rm(socketPath, { force: true });
+    const record = {};
+    const server = createServer((socket) => {
+        socket.setEncoding("utf8");
+        let buffer = "";
+        let finished = false;
+        socket.on("data", (chunk) => {
+            if (finished)
+                return;
+            buffer += chunk;
+            if (Buffer.byteLength(buffer, "utf8") > maxRequestBytes) {
+                finished = true;
+                respond(socket, {
+                    ok: false,
+                    error: "Outcome submission request is too large",
+                });
+                return;
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            finished = true;
+            let request;
+            try {
+                request = JSON.parse(buffer.slice(0, newline));
+            }
+            catch {
+                respond(socket, { ok: false, error: "invalid JSON request" });
+                return;
+            }
+            if (typeof request !== "object" ||
+                request === null ||
+                !("runToken" in request) ||
+                !("outcome" in request) ||
+                typeof request.runToken !== "string") {
+                respond(socket, {
+                    ok: false,
+                    error: "runToken and outcome are required",
+                });
+                return;
+            }
+            if (request.runToken !== runToken) {
+                respond(socket, { ok: false, error: "unknown Run Capability" });
+                return;
+            }
+            let patch;
+            try {
+                patch = parseOutcomePatch(request.outcome);
+            }
+            catch (error) {
+                respond(socket, {
+                    ok: false,
+                    error: `invalid Final Outcome: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                return;
+            }
+            try {
+                const previous = record.outcome;
+                record.outcome = mergeOutcome(record.outcome, patch);
+                if (patch.feedback && !previous?.feedback) {
+                    record.feedbackSubmittedAt = new Date().toISOString();
+                }
+                if (patch.observabilityFeedback && !previous?.observabilityFeedback) {
+                    record.observabilityFeedbackSubmittedAt = new Date().toISOString();
+                }
+            }
+            catch (error) {
+                respond(socket, {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return;
+            }
+            respond(socket, { ok: true });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socketPath, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    await chmod(socketPath, 0o600);
+    return {
+        take() {
+            return completeOutcome(record.outcome ?? {});
+        },
+        takeFeedback() {
+            const items = record.outcome?.feedback?.items;
+            if (!items || record.feedbackSubmittedAt === undefined)
+                return undefined;
+            return { items, submittedAt: record.feedbackSubmittedAt };
+        },
+        takeObservabilityFeedback() {
+            const items = record.outcome?.observabilityFeedback?.items;
+            if (!items || record.observabilityFeedbackSubmittedAt === undefined) {
+                return undefined;
+            }
+            return { items, submittedAt: record.observabilityFeedbackSubmittedAt };
+        },
+        hasReply() {
+            return record.outcome?.reply !== undefined;
+        },
+        async close() {
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+            await rm(socketPath, { force: true });
+        },
+    };
+}
+async function runWorker(lifecycleDirectory) {
+    const request = await readWorkerRequest(lifecycleDirectory);
+    const orphanAfterMs = request.orphanAfterMs ?? DEFAULT_ORPHAN_AFTER_MS;
+    const paths = lifecyclePaths(lifecycleDirectory);
+    await mkdir(lifecycleDirectory, { recursive: true, mode: 0o700 });
+    const abort = new AbortController();
+    const heartbeat = setInterval(() => {
+        void writeWorkerHeartbeat(lifecycleDirectory).catch(() => undefined);
+        void assertSupervisorOrThrow(request.supervisorLeasePath, orphanAfterMs)
+            .then(() => undefined)
+            .catch(() => {
+            if (!abort.signal.aborted)
+                abort.abort();
+        });
+    }, 5_000);
+    heartbeat.unref?.();
+    await writeWorkerHeartbeat(lifecycleDirectory);
+    const outcomes = await startWorkerOutcomeServer(paths.outcomeSocket, request.runToken);
+    const finish = async (completion) => {
+        clearInterval(heartbeat);
+        await writeWorkerCompletion(lifecycleDirectory, completion);
+        await outcomes.close().catch(() => undefined);
+    };
+    try {
+        await assertSupervisorOrThrow(request.supervisorLeasePath, orphanAfterMs);
+        const result = await runPiAgent({
+            prompt: request.prompt,
+            playbook: request.playbook,
+            provider: request.provider,
+            model: request.model,
+            systemPrompt: request.systemPrompt,
+            session: request.session,
+            skills: request.skills,
+            outcome: {
+                socketPath: paths.outcomeSocket,
+                runToken: request.runToken,
+                cliPath: request.beaconCliPath,
+            },
+        }, {
+            executable: request.executable,
+            timeoutMs: request.timeoutMs,
+            terminateGraceMs: request.terminateGraceMs,
+            maxFrameBytes: request.maxFrameBytes,
+            environment: request.environment,
+            runtimeEnvironment: request.runtimeEnvironment,
+            signal: abort.signal,
+        });
+        await finish({
+            ok: true,
+            result,
+            outcome: outcomes.take(),
+            feedback: outcomes.takeFeedback(),
+            observabilityFeedback: outcomes.takeObservabilityFeedback(),
+            hasReply: outcomes.hasReply(),
+            finishedAt: new Date().toISOString(),
+        });
+    }
+    catch (error) {
+        const orphaned = abort.signal.aborted;
+        const code = orphaned
+            ? "orphan_abandoned"
+            : error instanceof PiRuntimeError
+                ? error.code
+                : "worker_failed";
+        const message = orphaned
+            ? "Pi worker stopped after Beacon supervisor lease expired (orphan safety)"
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        await finish({
+            ok: false,
+            error: { code, message },
+            hasReply: outcomes.hasReply(),
+            feedback: outcomes.takeFeedback(),
+            observabilityFeedback: outcomes.takeObservabilityFeedback(),
+            finishedAt: new Date().toISOString(),
+        });
+    }
+}
+const lifecycleDirectory = process.argv[2];
+if (!lifecycleDirectory) {
+    console.error("Usage: node pi-worker-main.js <lifecycle-directory>");
+    process.exitCode = 1;
+}
+else {
+    runWorker(lifecycleDirectory).catch(async (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            await writeWorkerCompletion(lifecycleDirectory, {
+                ok: false,
+                error: { code: "worker_failed", message },
+                hasReply: false,
+                finishedAt: new Date().toISOString(),
+            });
+        }
+        catch {
+            console.error(`[beacon-pi-worker] fatal: ${message}`);
+        }
+        process.exitCode = 1;
+    });
+}

package/dist/daemon/runtime/supervisor-lease.d.ts

@@ -0,0 +1,15 @@
+export type SupervisorLease = {
+    pid: number;
+    updatedAt: string;
+};
+export declare const DEFAULT_ORPHAN_AFTER_MS = 120000;
+export declare const DEFAULT_LEASE_INTERVAL_MS = 10000;
+export declare function writeSupervisorLease(path: string): Promise<void>;
+export declare function readSupervisorLease(path: string): Promise<SupervisorLease | undefined>;
+/** True when a supervisor has refreshed the lease within orphanAfterMs. */
+export declare function isSupervisorLeaseFresh(path: string, orphanAfterMs: number, nowMs?: number): Promise<boolean>;
+export type SupervisorLeaseHandle = {
+    stop(): void;
+};
+/** Refresh the lease until stop(). Writes once immediately. */
+export declare function startSupervisorLeaseWriter(path: string, intervalMs?: number): SupervisorLeaseHandle;

package/dist/daemon/runtime/supervisor-lease.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export const DEFAULT_ORPHAN_AFTER_MS = 120_000;
+export const DEFAULT_LEASE_INTERVAL_MS = 10_000;
+export async function writeSupervisorLease(path) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const lease = {
+        pid: process.pid,
+        updatedAt: new Date().toISOString(),
+    };
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(lease)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+export async function readSupervisorLease(path) {
+    try {
+        const raw = JSON.parse(await readFile(path, "utf8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            !("pid" in raw) ||
+            !("updatedAt" in raw) ||
+            typeof raw.pid !== "number" ||
+            typeof raw.updatedAt !== "string") {
+            return undefined;
+        }
+        return { pid: raw.pid, updatedAt: raw.updatedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when a supervisor has refreshed the lease within orphanAfterMs. */
+export async function isSupervisorLeaseFresh(path, orphanAfterMs, nowMs = Date.now()) {
+    const lease = await readSupervisorLease(path);
+    if (!lease)
+        return false;
+    const updatedAt = Date.parse(lease.updatedAt);
+    if (!Number.isFinite(updatedAt))
+        return false;
+    return nowMs - updatedAt <= orphanAfterMs;
+}
+/** Refresh the lease until stop(). Writes once immediately. */
+export function startSupervisorLeaseWriter(path, intervalMs = DEFAULT_LEASE_INTERVAL_MS) {
+    let stopped = false;
+    let timer;
+    const tick = () => {
+        void writeSupervisorLease(path).catch((error) => {
+            console.error(`[beacon] failed to refresh supervisor lease: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    };
+    tick();
+    timer = setInterval(tick, intervalMs);
+    timer.unref?.();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+        },
+    };
+}

package/dist/daemon/service.js

@@ -14,6 +14,7 @@ import { createFeishuMessagePipeline } from "./feishu/message-pipeline.js";
 import { startOutcomeServer } from "./outcome/server.js";
 import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
 import { createRunQueue } from "./run/queue.js";
+import { startSupervisorLeaseWriter } from "./runtime/supervisor-lease.js";
 import { ScheduleCursorStore } from "./schedule/cursor-store.js";
 import { ScheduleLoop } from "./schedule/loop.js";
 import { ScheduleReconciler } from "./schedule/reconciler.js";
@@ -44,7 +45,11 @@ export async function runBeacon(configPath, options) {
     const eventProducers = global.events
         ? await loadEventCredentials(global.events.credentialsPath)
         : [];
-    const outcomes = await startOutcomeServer();
+    const supervisorLeasePath = join(global.homeDirectory, "state", "supervisor.lease");
+    const supervisorLease = startSupervisorLeaseWriter(supervisorLeasePath);
+    const outcomes = await startOutcomeServer({
+        directory: join(global.homeDirectory, "state", "outcomes"),
+    });
     const queue = createRunQueue(global.runs, profiles);
     let dashboard;
     try {
@@ -165,6 +170,7 @@ export async function runBeacon(configPath, options) {
             dashboard?.close() ?? Promise.resolve(),
             outcomes.close(),
         ]);
+        supervisorLease.stop();
         for (const result of [...stoppedEvents, ...drained, ...closed]) {
             if (result.status === "rejected" && !failures.includes(result.reason))
                 failures.push(result.reason);

package/dist/daemon/state/trigger-store.js

@@ -44,6 +44,21 @@ const inputSchema = z.discriminatedUnion("kind", [
         .strict(),
     z.object({ kind: z.literal("manual"), text: z.string().min(1) }).strict(),
 ]);
+const agentRuntimeSchema = z
+    .object({
+    workerPid: z.number().int().positive(),
+    lifecycleDirectory: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "Pi worker lifecycle directory must be absolute"),
+    runToken: z.string().min(1),
+    supervisorLeasePath: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "Supervisor lease path must be absolute"),
+    orphanAfterMs: z.number().int().positive(),
+})
+    .strict();
 const runSchema = z
     .object({
     runId: z.string().min(1),
@@ -65,6 +80,7 @@ const runSchema = z
     playbook: z.string().min(1),
     promptDigest: z.string().regex(/^[a-f0-9]{64}$/),
     systemPrompt: z.string().min(1).optional(),
+    agent: agentRuntimeSchema.optional(),
     failure: failureSchema.optional(),
 })
     .strict();