@nettee/beacon 0.1.0

package/dist/runtime/pi-doctor.js

@@ -0,0 +1,14 @@
+import { runPiAgent } from "./pi-rpc.js";
+export async function runPiDoctor(provider, model) {
+    const result = await runPiAgent({
+        prompt: "Reply with exactly: BEACON_PI_RPC_OK",
+        workspace: process.cwd(),
+        provider,
+        model,
+        systemPrompt: "Follow the user's instruction exactly. Do not use tools.",
+    });
+    if (result.text !== "BEACON_PI_RPC_OK") {
+        throw new Error(`Pi RPC smoke test returned an unexpected response: ${JSON.stringify(result.text)}`);
+    }
+    console.log(`[beacon] Pi RPC ready provider=${result.provider} model=${result.model}`);
+}

package/dist/runtime/pi-outcome-extension.js

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+async function invokeBeaconCli(text, signal) {
+    const cliPath = process.env.BEACON_CLI_PATH;
+    if (!cliPath)
+        throw new Error("BEACON_CLI_PATH is missing from this Agent Run");
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliPath, "outcome", "submit"], {
+            env: process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+            signal,
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr = (stderr + chunk).slice(-64 * 1024);
+        });
+        child.once("error", reject);
+        child.once("exit", (code, exitSignal) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`beacon outcome submit failed (code=${String(code)} signal=${String(exitSignal)}): ${stderr.trim()}`));
+        });
+        child.stdin.end(text);
+    });
+}
+export default function registerOutcomeTool(pi) {
+    pi.registerTool({
+        name: "submit_final_outcome",
+        label: "Submit Final Outcome",
+        description: "Submit the exact final response that Beacon must deliver to the user. Call this once after completing the task.",
+        parameters: {
+            type: "object",
+            properties: {
+                text: {
+                    type: "string",
+                    minLength: 1,
+                    description: "The complete user-facing final response.",
+                },
+            },
+            required: ["text"],
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, params, signal) {
+            await invokeBeaconCli(params.text, signal);
+            return {
+                content: [{ type: "text", text: "Final Outcome accepted by Beacon." }],
+                details: { submitted: true },
+            };
+        },
+    });
+}

package/dist/runtime/pi-rpc.js

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+export class PiRuntimeError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "PiRuntimeError";
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function isRpcResponse(value) {
+    return (isObject(value) &&
+        value.type === "response" &&
+        typeof value.success === "boolean");
+}
+function isAssistantMessage(value) {
+    return (isObject(value) &&
+        value.role === "assistant" &&
+        Array.isArray(value.content) &&
+        typeof value.provider === "string" &&
+        typeof value.model === "string" &&
+        typeof value.stopReason === "string");
+}
+function isMessageEndEvent(value) {
+    return (isObject(value) &&
+        value.type === "message_end" &&
+        isAssistantMessage(value.message));
+}
+function isAgentSettledEvent(value) {
+    return isObject(value) && value.type === "agent_settled";
+}
+function collectText(message) {
+    return message.content
+        .filter((block) => isObject(block) &&
+        block.type === "text" &&
+        typeof block.text === "string")
+        .map((block) => block.text)
+        .join("")
+        .trim();
+}
+function buildArguments(request) {
+    const args = ["--mode", "rpc", "--no-session", "--no-approve"];
+    if (request.provider)
+        args.push("--provider", request.provider);
+    if (request.model)
+        args.push("--model", request.model);
+    if (request.systemPrompt)
+        args.push("--system-prompt", request.systemPrompt);
+    if (request.outcome) {
+        args.push("--extension", fileURLToPath(new URL("../../dist/runtime/pi-outcome-extension.js", import.meta.url)));
+    }
+    return args;
+}
+const inheritedEnvironmentKeys = [
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TMPDIR",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "COLORTERM",
+    "SSH_AUTH_SOCK",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "GH_CONFIG_DIR",
+    "PI_CODING_AGENT_DIR",
+    "PI_CODING_AGENT_SESSION_DIR",
+    "PI_PACKAGE_DIR",
+    "PI_OFFLINE",
+    "PI_TELEMETRY",
+];
+function buildPiEnvironment(outcome, configured = {}) {
+    const environment = {};
+    for (const key of inheritedEnvironmentKeys) {
+        const value = process.env[key];
+        if (value !== undefined)
+            environment[key] = value;
+    }
+    for (const [key, value] of Object.entries(configured)) {
+        if (!inheritedEnvironmentKeys.includes(key)) {
+            throw new Error(`Pi environment key is not allowlisted: ${key}`);
+        }
+        if (value !== undefined)
+            environment[key] = value;
+    }
+    if (outcome) {
+        environment.BEACON_OUTCOME_SOCKET = outcome.socketPath;
+        environment.BEACON_RUN_TOKEN = outcome.runToken;
+        environment.BEACON_CLI_PATH = outcome.cliPath;
+    }
+    return environment;
+}
+function describeExit(code, signal, stderr) {
+    const detail = stderr.trim();
+    return new PiRuntimeError("runtime_exit_failed", `Pi process exited before the Run settled (code=${String(code)} signal=${String(signal)})${detail ? `: ${detail}` : ""}`);
+}
+async function stopProcess(child, terminateGraceMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill("SIGTERM");
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            resolve();
+        }, terminateGraceMs);
+        child.once("exit", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+export async function runPiAgent(request, options = {}) {
+    if (!request.prompt.trim())
+        throw new Error("Pi Run prompt must not be empty");
+    if (!request.workspace.trim())
+        throw new Error("Pi Run workspace must not be empty");
+    if ((request.provider === undefined) !== (request.model === undefined)) {
+        throw new Error("Pi Run provider and model must either both be set or both be omitted");
+    }
+    const executable = options.executable ?? "pi";
+    const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+    const terminateGraceMs = options.terminateGraceMs ?? 1_000;
+    const maxFrameBytes = options.maxFrameBytes ?? 1024 * 1024;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("Pi Run timeout must be a positive integer");
+    }
+    if (!Number.isSafeInteger(terminateGraceMs) || terminateGraceMs <= 0) {
+        throw new Error("Pi termination grace must be a positive integer");
+    }
+    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+        throw new Error("Pi RPC frame limit must be a positive integer");
+    }
+    const child = spawn(executable, buildArguments(request), {
+        cwd: request.workspace,
+        env: buildPiEnvironment(request.outcome, options.environment),
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    let stderr = "";
+    let finalMessage;
+    let promptAccepted = false;
+    let finished = false;
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+        stderr = (stderr + chunk).slice(-64 * 1024);
+    });
+    try {
+        return await new Promise((resolve, reject) => {
+            const fail = (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                reject(error);
+            };
+            const timer = setTimeout(() => fail(new PiRuntimeError("runtime_timeout", `Pi Run timed out after ${timeoutMs}ms${stderr.trim() ? `: ${stderr.trim()}` : ""}`)), timeoutMs);
+            let frameBytes = 0;
+            child.stdout.on("data", (chunk) => {
+                for (const byte of chunk) {
+                    if (byte === 10)
+                        frameBytes = 0;
+                    else
+                        frameBytes += 1;
+                    if (frameBytes > maxFrameBytes) {
+                        fail(new PiRuntimeError("runtime_protocol_error", `Pi RPC frame exceeds ${maxFrameBytes} bytes`));
+                        return;
+                    }
+                }
+            });
+            child.once("error", (error) => fail(new PiRuntimeError("runtime_spawn_failed", `Failed to start Pi: ${error.message}`, {
+                cause: error,
+            })));
+            child.once("exit", (code, signal) => {
+                if (!finished)
+                    fail(describeExit(code, signal, stderr));
+            });
+            lines.on("line", (line) => {
+                if (finished)
+                    return;
+                let value;
+                try {
+                    value = JSON.parse(line);
+                }
+                catch {
+                    fail(new PiRuntimeError("runtime_protocol_error", `Pi emitted invalid RPC JSON: ${line}`));
+                    return;
+                }
+                if (isRpcResponse(value) && value.id === "run-prompt") {
+                    if (!value.success) {
+                        fail(new PiRuntimeError("runtime_protocol_error", `Pi rejected the prompt: ${value.error ?? "unknown RPC error"}`));
+                        return;
+                    }
+                    promptAccepted = true;
+                }
+                if (isMessageEndEvent(value)) {
+                    finalMessage = value.message;
+                    return;
+                }
+                if (!isAgentSettledEvent(value))
+                    return;
+                if (!promptAccepted) {
+                    fail(new PiRuntimeError("runtime_protocol_error", "Pi settled without accepting the prompt RPC command"));
+                    return;
+                }
+                if (!finalMessage) {
+                    fail(new PiRuntimeError("runtime_protocol_error", "Pi settled without an assistant message_end event"));
+                    return;
+                }
+                if (finalMessage.stopReason !== "stop") {
+                    fail(new PiRuntimeError("runtime_exit_failed", `Pi ended with stopReason=${finalMessage.stopReason}${finalMessage.errorMessage ? `: ${finalMessage.errorMessage}` : ""}`));
+                    return;
+                }
+                try {
+                    const text = collectText(finalMessage);
+                    if (!request.outcome && !text) {
+                        fail(new Error("Pi completed without a textual final response"));
+                        return;
+                    }
+                    const result = {
+                        text,
+                        provider: finalMessage.provider,
+                        model: finalMessage.model,
+                    };
+                    finished = true;
+                    clearTimeout(timer);
+                    resolve(result);
+                }
+                catch (error) {
+                    fail(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+            child.stdin.on("error", (error) => fail(new PiRuntimeError("runtime_protocol_error", `Failed to write Pi RPC command: ${error.message}`, { cause: error })));
+            child.stdin.write(`${JSON.stringify({ id: "run-prompt", type: "prompt", message: request.prompt })}\n`);
+        });
+    }
+    finally {
+        lines.close();
+        await stopProcess(child, terminateGraceMs);
+    }
+}

package/dist/schedule/cron.js

@@ -0,0 +1,48 @@
+import { CronExpressionParser } from "cron-parser";
+export function occurrencesBetween(cron, timezone, afterExclusive, throughInclusive, limit) {
+    if (cron.trim().split(/\s+/).length !== 5) {
+        throw new Error("Schedule cron must contain exactly five fields");
+    }
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        throw new Error("Occurrence limit must be a positive integer");
+    }
+    const expression = CronExpressionParser.parse(`0 ${cron}`, {
+        currentDate: afterExclusive,
+        endDate: throughInclusive,
+        tz: timezone,
+        strict: true,
+    });
+    const occurrences = [];
+    while (true) {
+        let next;
+        try {
+            next = expression.next().toDate();
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                /Out of the time span range|No more executions/.test(error.message)) {
+                break;
+            }
+            throw error;
+        }
+        if (next > throughInclusive)
+            break;
+        occurrences.push(next);
+        if (occurrences.length > limit) {
+            throw new Error(`Schedule occurrence enumeration exceeds limit ${limit}`);
+        }
+    }
+    return occurrences;
+}
+export function nextOccurrence(cron, timezone, afterExclusive) {
+    if (cron.trim().split(/\s+/).length !== 5) {
+        throw new Error("Schedule cron must contain exactly five fields");
+    }
+    return CronExpressionParser.parse(`0 ${cron}`, {
+        currentDate: afterExclusive,
+        tz: timezone,
+        strict: true,
+    })
+        .next()
+        .toDate();
+}

package/dist/schedule/cursor-store.js

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+const cursorSchema = z
+    .object({
+    version: z.literal(1),
+    scheduleId: z.string().min(1),
+    through: z.string().datetime({ offset: true }),
+})
+    .strict();
+export class ScheduleCursorStore {
+    root;
+    constructor(profileDirectory) {
+        this.root = join(profileDirectory, "state", "schedules");
+    }
+    path(scheduleId) {
+        return join(this.root, `${scheduleId}.json`);
+    }
+    async prepare() {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        await chmod(join(this.root, ".."), 0o700);
+        await chmod(this.root, 0o700);
+    }
+    async read(scheduleId) {
+        await this.prepare();
+        let raw;
+        try {
+            raw = await readFile(this.path(scheduleId), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw new Error(`Cannot read Schedule cursor ${scheduleId}`, {
+                cause: error,
+            });
+        }
+        try {
+            return cursorSchema.parse(JSON.parse(raw));
+        }
+        catch (error) {
+            throw new Error(`Invalid Schedule cursor ${scheduleId}`, {
+                cause: error,
+            });
+        }
+    }
+    async write(cursor, exclusive = false) {
+        await this.prepare();
+        const target = this.path(cursor.scheduleId);
+        const temporary = exclusive
+            ? target
+            : join(this.root, `.${cursor.scheduleId}-${randomUUID()}.tmp`);
+        const handle = await open(temporary, exclusive ? "wx" : "wx", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(cursor, null, 2)}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (!exclusive)
+            await rename(temporary, target);
+        const directory = await open(this.root, "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    async initialize(scheduleId, through) {
+        const cursor = cursorSchema.parse({
+            version: 1,
+            scheduleId,
+            through: through.toISOString(),
+        });
+        try {
+            await this.write(cursor, true);
+            return cursor;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = await this.read(scheduleId);
+            if (!existing)
+                throw new Error(`Schedule cursor disappeared: ${scheduleId}`);
+            return existing;
+        }
+    }
+    async advance(scheduleId, through) {
+        const current = await this.read(scheduleId);
+        if (!current)
+            throw new Error(`Cannot advance missing Schedule cursor ${scheduleId}`);
+        if (through.toISOString() < current.through) {
+            throw new Error(`Schedule cursor cannot move backwards: ${scheduleId}`);
+        }
+        const next = cursorSchema.parse({
+            version: 1,
+            scheduleId,
+            through: through.toISOString(),
+        });
+        await this.write(next);
+        return next;
+    }
+}

package/dist/schedule/loop.js

@@ -0,0 +1,45 @@
+import { nextOccurrence } from "./cron.js";
+const MAX_TIMER_MS = 2_147_000_000;
+export class ScheduleLoop {
+    profile;
+    reconciler;
+    onFatal;
+    timer;
+    stopped = false;
+    active;
+    constructor(profile, reconciler, onFatal) {
+        this.profile = profile;
+        this.reconciler = reconciler;
+        this.onFatal = onFatal;
+    }
+    start(after = new Date()) {
+        if (this.stopped || this.profile.schedules.length === 0)
+            return;
+        const next = this.profile.schedules
+            .map((schedule) => nextOccurrence(schedule.cron, schedule.timezone, after))
+            .sort((left, right) => left.getTime() - right.getTime())[0];
+        if (!next)
+            return;
+        const delay = Math.max(0, Math.min(MAX_TIMER_MS, next.getTime() - Date.now()));
+        this.timer = setTimeout(() => {
+            const now = new Date();
+            const active = this.reconciler
+                .reconcile(now)
+                .then(() => this.start(now))
+                .catch((error) => this.onFatal(error instanceof Error ? error : new Error(String(error))))
+                .finally(() => {
+                if (this.active === active)
+                    this.active = undefined;
+            });
+            this.active = active;
+        }, delay);
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+    }
+    async drain() {
+        await this.active;
+    }
+}

package/dist/schedule/reconciler.js

@@ -0,0 +1,41 @@
+import { occurrencesBetween } from "./cron.js";
+export class ScheduleReconciler {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async reconcile(now) {
+        for (const schedule of this.options.profile.schedules) {
+            let cursor = await this.options.cursors.read(schedule.id);
+            if (!cursor) {
+                await this.options.cursors.initialize(schedule.id, now);
+                continue;
+            }
+            const occurrences = occurrencesBetween(schedule.cron, schedule.timezone, new Date(cursor.through), now, this.options.maxOccurrences);
+            const latest = occurrences.at(-1);
+            if (!latest)
+                continue;
+            const scheduledFor = latest.toISOString();
+            const claim = await this.options.triggers.claim({
+                sourceKey: ["schedule", schedule.id, scheduledFor],
+                target: { kind: "chat", chatId: schedule.delivery.chatId },
+                ingress: {
+                    scheduleId: schedule.id,
+                    scheduledFor,
+                    text: schedule.input,
+                },
+            });
+            await this.options.cursors.advance(schedule.id, latest);
+            cursor = { version: 1, scheduleId: schedule.id, through: scheduledFor };
+            void cursor;
+            if (!claim.created)
+                continue;
+            await this.options.process(claim.record.triggerKey, async () => ({
+                kind: "schedule",
+                scheduleId: schedule.id,
+                scheduledFor,
+                text: schedule.input,
+            }));
+        }
+    }
+}

package/dist/service.js

@@ -0,0 +1,97 @@
+import { loadGlobalConfig } from "./config/global.js";
+import { loadProfileRegistry } from "./config/registry.js";
+import { loadFeishuCredentials } from "./config/secrets.js";
+import { createFeishuGateway } from "./feishu/gateway.js";
+import { createFeishuMessagePipeline } from "./feishu/message-pipeline.js";
+import { startOutcomeServer } from "./outcome/server.js";
+import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
+import { RunQueue } from "./run/queue.js";
+import { ScheduleCursorStore } from "./schedule/cursor-store.js";
+import { ScheduleLoop } from "./schedule/loop.js";
+import { ScheduleReconciler } from "./schedule/reconciler.js";
+import { TriggerStore } from "./state/trigger-store.js";
+function shutdownController() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    const stop = () => resolve();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    return {
+        promise,
+        resolve,
+        close() {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+        },
+    };
+}
+export async function runBeacon(configPath) {
+    const global = await loadGlobalConfig(configPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const credentials = await Promise.all(profiles.map((profile) => loadFeishuCredentials(profile.id, global.secretsPath)));
+    const outcomes = await startOutcomeServer();
+    const queue = new RunQueue(global.runs.maxConcurrent, global.runs.maxQueued);
+    const shutdown = shutdownController();
+    let rejectFatal;
+    const fatal = new Promise((_resolve, reject) => {
+        rejectFatal = reject;
+    });
+    const messagePipelines = [];
+    const loops = [];
+    const contexts = profiles.map((profile, index) => {
+        const profileCredentials = credentials[index];
+        const gateway = createFeishuGateway(profileCredentials);
+        const store = new TriggerStore(profile.directory, profile.id);
+        const orchestrator = createPiRunOrchestrator({
+            config: global,
+            profile,
+            store,
+            queue,
+            outcomes,
+            delivery: gateway,
+        });
+        const messagePipeline = createFeishuMessagePipeline({
+            gateway,
+            store,
+            process: (triggerKey, normalize) => orchestrator.process(triggerKey, normalize),
+            onFatal: rejectFatal,
+        });
+        messagePipelines.push(messagePipeline);
+        const reconciler = new ScheduleReconciler({
+            profile,
+            triggers: store,
+            cursors: new ScheduleCursorStore(profile.directory),
+            maxOccurrences: global.scheduler.maxOccurrencesPerReconciliation,
+            process: (triggerKey, normalize) => orchestrator.process(triggerKey, normalize),
+        });
+        const loop = new ScheduleLoop(profile, reconciler, rejectFatal);
+        loops.push(loop);
+        return { profile, messagePipeline, orchestrator, reconciler };
+    });
+    await Promise.all(contexts.map((context) => context.orchestrator.recover()));
+    const reconciliationTime = new Date();
+    await Promise.all(contexts.map((context) => context.reconciler.reconcile(reconciliationTime)));
+    for (const loop of loops)
+        loop.start(reconciliationTime);
+    const gateways = contexts.map(({ profile, messagePipeline }) => {
+        console.log(`[beacon] starting Profile id=${profile.id} runtime=${profile.runtime} provider=${profile.model.provider} model=${profile.model.id}`);
+        return messagePipeline.run(shutdown.promise);
+    });
+    try {
+        await Promise.race([shutdown.promise, fatal, ...gateways]);
+    }
+    finally {
+        shutdown.resolve();
+        for (const loop of loops)
+            loop.stop();
+        await Promise.allSettled(gateways);
+        await Promise.allSettled([
+            ...messagePipelines.map((pipeline) => pipeline.drain()),
+            ...loops.map((loop) => loop.drain()),
+        ]);
+        shutdown.close();
+        await outcomes.close();
+    }
+}