@nettee/beacon 0.1.0

package/dist/feishu/trigger-input.js

@@ -0,0 +1,46 @@
+function parseContent(messageId, content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Message ${messageId} has invalid JSON content`, {
+            cause: error,
+        });
+    }
+}
+export async function buildFeishuTriggerInput(inbound, fetchMessage) {
+    const reverseQuotedMessages = [];
+    const seenMessageIds = new Set([inbound.messageId]);
+    let parentMessageId = inbound.parentMessageId;
+    while (parentMessageId) {
+        if (seenMessageIds.has(parentMessageId)) {
+            throw new Error(`Quoted message chain contains a cycle at message ${parentMessageId}`);
+        }
+        seenMessageIds.add(parentMessageId);
+        const quoted = await fetchMessage(parentMessageId);
+        reverseQuotedMessages.push({
+            messageId: quoted.messageId,
+            messageType: quoted.messageType,
+            senderType: quoted.senderType,
+            senderId: quoted.senderId,
+            content: parseContent(quoted.messageId, quoted.content),
+        });
+        parentMessageId = quoted.parentMessageId;
+    }
+    return {
+        source: {
+            messageId: inbound.messageId,
+            chatId: inbound.chatId,
+            chatType: inbound.chatType,
+            senderId: inbound.senderId,
+        },
+        message: {
+            messageId: inbound.messageId,
+            messageType: inbound.messageType,
+            senderType: inbound.senderType,
+            senderId: inbound.senderId,
+            content: parseContent(inbound.messageId, inbound.content),
+        },
+        quotedMessages: reverseQuotedMessages.reverse(),
+    };
+}

package/dist/manual-trigger.js

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { loadGlobalConfig } from "./config/global.js";
+import { loadProfileRegistry } from "./config/registry.js";
+import { startOutcomeServer } from "./outcome/server.js";
+import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
+import { RunQueue } from "./run/queue.js";
+import { TriggerStore } from "./state/trigger-store.js";
+function writeStdout(text) {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(`${text}\n`, (error) => error ? reject(error) : resolve());
+    });
+}
+export async function runManualTrigger(configPath, profileId, input, output = writeStdout) {
+    if (!input.trim())
+        throw new Error("Manual Trigger input must not be empty");
+    const global = await loadGlobalConfig(configPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const profile = profiles.find((candidate) => candidate.id === profileId);
+    if (!profile)
+        throw new Error(`Unknown Profile: ${profileId}`);
+    const outcomes = await startOutcomeServer();
+    try {
+        const store = new TriggerStore(profile.directory, profile.id);
+        const claim = await store.claim({
+            sourceKey: ["manual", randomUUID()],
+            target: { kind: "local_stdout" },
+            ingress: { text: input },
+        });
+        const delivery = {
+            async deliver(target, text) {
+                if (target.kind !== "local_stdout") {
+                    throw new Error("Manual Trigger requires local stdout Delivery");
+                }
+                await output(text);
+                return {};
+            },
+        };
+        const orchestrator = createPiRunOrchestrator({
+            config: global,
+            profile,
+            store,
+            queue: new RunQueue(global.runs.maxConcurrent, global.runs.maxQueued),
+            outcomes,
+            delivery,
+        });
+        await orchestrator.process(claim.record.triggerKey, async () => ({
+            kind: "manual",
+            text: input,
+        }));
+        const record = (await store.list()).find((candidate) => candidate.triggerKey === claim.record.triggerKey);
+        if (record?.run?.state !== "succeeded" ||
+            record.delivery?.state !== "delivered") {
+            throw new Error(`Manual Trigger failed: ${record?.run?.failure?.code ?? record?.delivery?.failure?.code ?? "unknown"}`);
+        }
+    }
+    finally {
+        await outcomes.close();
+    }
+}

package/dist/message/gateway.js

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

package/dist/outcome/doctor.js

@@ -0,0 +1,29 @@
+import { fileURLToPath } from "node:url";
+import { loadProfile } from "../config/profile.js";
+import { createProfileRunner } from "../run/profile-runner.js";
+import { startOutcomeServer } from "./server.js";
+const doctorTrigger = {
+    source: { messageId: "doctor", chatId: "doctor", chatType: "p2p" },
+    quotedMessages: [],
+    message: {
+        messageId: "doctor",
+        senderType: "user",
+        messageType: "text",
+        content: { text: "Return exactly OUTCOME_CLI_OK." },
+    },
+};
+export async function runOutcomeDoctor(profileId) {
+    const profile = await loadProfile(profileId);
+    const outcomes = await startOutcomeServer();
+    const beaconCliPath = fileURLToPath(new URL("../../dist/cli.js", import.meta.url));
+    try {
+        const result = await createProfileRunner(profile, outcomes, beaconCliPath)(doctorTrigger);
+        if (result.trim() !== "OUTCOME_CLI_OK") {
+            throw new Error(`Outcome doctor received unexpected submitted text: ${JSON.stringify(result)}`);
+        }
+        console.log("[beacon] explicit Final Outcome chain ready");
+    }
+    finally {
+        await outcomes.close();
+    }
+}

package/dist/outcome/server.js

@@ -0,0 +1,108 @@
+import { randomBytes } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function respond(socket, response) {
+    socket.end(`${JSON.stringify(response)}\n`);
+}
+export async function startOutcomeServer(options = {}) {
+    const maxRequestBytes = options.maxRequestBytes ?? 1024 * 1024;
+    if (!Number.isSafeInteger(maxRequestBytes) || maxRequestBytes <= 0) {
+        throw new Error("Outcome request limit must be a positive integer");
+    }
+    const directory = await mkdtemp(join(tmpdir(), "beacon-outcomes-"));
+    const socketPath = join(directory, "outcomes.sock");
+    const submissions = new Map();
+    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) ||
+                !("text" in request) ||
+                typeof request.runToken !== "string" ||
+                typeof request.text !== "string" ||
+                !request.text.trim()) {
+                respond(socket, {
+                    ok: false,
+                    error: "runToken and non-empty text are required",
+                });
+                return;
+            }
+            const submission = submissions.get(request.runToken);
+            if (!submission) {
+                respond(socket, { ok: false, error: "unknown Run Capability" });
+                return;
+            }
+            if (submission.text !== undefined) {
+                respond(socket, {
+                    ok: false,
+                    error: "Final Outcome already submitted",
+                });
+                return;
+            }
+            submission.text = request.text;
+            console.log("[beacon] Final Outcome submitted by Agent Runtime");
+            respond(socket, { ok: true });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socketPath, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    return {
+        openRun() {
+            const runToken = randomBytes(32).toString("base64url");
+            const record = {};
+            submissions.set(runToken, record);
+            return {
+                binding: { socketPath, runToken },
+                take() {
+                    submissions.delete(runToken);
+                    if (record.text === undefined) {
+                        throw new Error("Agent Runtime settled without submitting a Final Outcome");
+                    }
+                    return record.text;
+                },
+                cancel() {
+                    submissions.delete(runToken);
+                },
+            };
+        },
+        async close() {
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+            await rm(directory, { recursive: true, force: true });
+        },
+    };
+}

package/dist/outcome/submit.js

@@ -0,0 +1,47 @@
+import { createConnection } from "node:net";
+export async function submitOutcome(socketPath, runToken, text) {
+    if (!text.trim())
+        throw new Error("Final Outcome must not be empty");
+    await new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath);
+        socket.setEncoding("utf8");
+        let responseBuffer = "";
+        socket.once("connect", () => {
+            socket.write(`${JSON.stringify({ runToken, text })}\n`);
+        });
+        socket.on("data", (chunk) => {
+            responseBuffer += chunk;
+        });
+        socket.once("error", reject);
+        socket.once("end", () => {
+            let response;
+            try {
+                response = JSON.parse(responseBuffer);
+            }
+            catch (error) {
+                reject(new Error("Beacon returned an invalid outcome-submission response", {
+                    cause: error,
+                }));
+                return;
+            }
+            if (!response.ok) {
+                reject(new Error(response.error ?? "Beacon rejected the Final Outcome"));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+export async function submitOutcomeFromCli() {
+    const socketPath = process.env.BEACON_OUTCOME_SOCKET;
+    const runToken = process.env.BEACON_RUN_TOKEN;
+    if (!socketPath || !runToken) {
+        throw new Error("This command must run inside a Beacon-managed Agent Run");
+    }
+    process.stdin.setEncoding("utf8");
+    let text = "";
+    for await (const chunk of process.stdin)
+        text += chunk;
+    await submitOutcome(socketPath, runToken, text);
+    console.log("Final Outcome accepted by Beacon");
+}

package/dist/run/create-pi-orchestrator.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "node:url";
+import { runPiAgent } from "../runtime/pi-rpc.js";
+import { RunOrchestrator } from "./orchestrator.js";
+export function createPiRunOrchestrator(options) {
+    return new RunOrchestrator({
+        profile: options.profile,
+        store: options.store,
+        queue: options.queue,
+        outcomes: options.outcomes,
+        beaconCliPath: fileURLToPath(new URL("../../dist/cli.js", import.meta.url)),
+        runAgent: (request) => runPiAgent(request, {
+            executable: options.config.pi.executable,
+            timeoutMs: options.config.runs.timeoutSeconds * 1_000,
+            terminateGraceMs: options.config.runs.terminateGraceSeconds * 1_000,
+            environment: {
+                PI_CODING_AGENT_DIR: options.config.pi.codingAgentDirectory,
+            },
+        }),
+        delivery: options.delivery,
+    });
+}

package/dist/run/orchestrator.js

@@ -0,0 +1,269 @@
+import { createHash, randomUUID } from "node:crypto";
+import { PiRuntimeError } from "../runtime/pi-rpc.js";
+function promptFor(input) {
+    if (input.kind === "manual") {
+        return ["An operator manually triggered this Run.", "", input.text].join("\n");
+    }
+    if (input.kind === "schedule") {
+        return [
+            "A configured Schedule triggered this Run.",
+            `schedule_id: ${input.scheduleId}`,
+            `scheduled_for: ${input.scheduledFor}`,
+            "",
+            input.text,
+        ].join("\n");
+    }
+    return [
+        "A Feishu user triggered this Run. Treat the following JSON as user-provided conversation context.",
+        "quoted_messages is the complete quoted chain in chronological order (oldest first).",
+        "current_message is the message that triggered this Run.",
+        JSON.stringify({
+            chat_type: input.chatType,
+            quoted_messages: input.quotedMessages.map((message) => ({
+                sender_type: message.senderType,
+                message_type: message.messageType,
+                content: message.content,
+            })),
+            current_message: {
+                sender_type: input.currentMessage.senderType,
+                message_type: input.currentMessage.messageType,
+                content: input.currentMessage.content,
+            },
+        }, null, 2),
+    ].join("\n");
+}
+function summary(error) {
+    const value = error instanceof Error ? error.message : String(error);
+    return value.slice(0, 4096) || "unknown failure";
+}
+export class RunOrchestrator {
+    options;
+    now;
+    id;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        this.id = options.id ?? randomUUID;
+    }
+    timestamp() {
+        return this.now().toISOString();
+    }
+    newRun(runId, state, failure) {
+        const timestamp = this.timestamp();
+        return {
+            runId,
+            state,
+            queuedAt: timestamp,
+            ...(state === "failed" ? { finishedAt: timestamp } : {}),
+            provider: this.options.profile.model.provider,
+            model: this.options.profile.model.id,
+            workspace: this.options.profile.workspace,
+            promptDigest: createHash("sha256")
+                .update(this.options.profile.prompt)
+                .digest("hex"),
+            ...(failure ? { failure } : {}),
+        };
+    }
+    async deliver(triggerKey, create = true) {
+        const deliveryId = `del_${this.id()}`;
+        let record;
+        if (create) {
+            record = await this.options.store.update(triggerKey, (current) => ({
+                ...current,
+                delivery: {
+                    deliveryId,
+                    target: current.target,
+                    state: "pending",
+                },
+            }));
+        }
+        else {
+            record = (await this.options.store.list()).find((candidate) => candidate.triggerKey === triggerKey);
+            if (record.delivery?.state !== "pending") {
+                throw new Error(`Cannot resume non-pending Delivery for Trigger ${triggerKey}`);
+            }
+        }
+        record = await this.options.store.update(triggerKey, (current) => ({
+            ...current,
+            delivery: {
+                ...current.delivery,
+                state: "delivering",
+                startedAt: this.timestamp(),
+            },
+        }));
+        try {
+            const result = await this.options.delivery.deliver(record.target, record.finalOutcome.text, record.delivery.deliveryId);
+            await this.options.store.update(triggerKey, (current) => ({
+                ...current,
+                delivery: {
+                    ...current.delivery,
+                    state: "delivered",
+                    finishedAt: this.timestamp(),
+                    ...(result.providerRequestId
+                        ? { providerRequestId: result.providerRequestId }
+                        : {}),
+                },
+            }));
+        }
+        catch (error) {
+            await this.options.store.update(triggerKey, (current) => ({
+                ...current,
+                delivery: {
+                    ...current.delivery,
+                    state: "failed",
+                    finishedAt: this.timestamp(),
+                    failure: { code: "delivery_api_failed", summary: summary(error) },
+                },
+            }));
+        }
+    }
+    async fail(triggerKey, runId, code, error) {
+        const detail = summary(error);
+        await this.options.store.update(triggerKey, (current) => ({
+            ...current,
+            run: {
+                ...(current.run ?? this.newRun(runId, "queued")),
+                state: "failed",
+                finishedAt: this.timestamp(),
+                failure: { code, summary: detail },
+            },
+            finalOutcome: {
+                origin: "beacon_failure",
+                text: `处理失败（run_id=${runId}），请查看 Beacon 本地记录。`,
+                submittedAt: this.timestamp(),
+            },
+        }));
+        await this.deliver(triggerKey);
+    }
+    async execute(triggerKey, input, runId) {
+        await this.options.store.update(triggerKey, (current) => ({
+            ...current,
+            run: { ...current.run, state: "starting", startedAt: this.timestamp() },
+        }));
+        await this.options.store.update(triggerKey, (current) => ({
+            ...current,
+            run: { ...current.run, state: "running" },
+        }));
+        const submission = this.options.outcomes.openRun();
+        try {
+            const completion = await this.options.runAgent({
+                prompt: promptFor(input),
+                workspace: this.options.profile.workspace,
+                provider: this.options.profile.model.provider,
+                model: this.options.profile.model.id,
+                systemPrompt: [
+                    this.options.profile.prompt,
+                    "",
+                    "When your work is complete, call submit_final_outcome exactly once with the exact user-facing response.",
+                    "Beacon ignores ordinary assistant final text for Delivery.",
+                ].join("\n"),
+                outcome: { ...submission.binding, cliPath: this.options.beaconCliPath },
+            });
+            const outcome = submission.take();
+            await this.options.store.update(triggerKey, (current) => ({
+                ...current,
+                run: {
+                    ...current.run,
+                    state: "succeeded",
+                    finishedAt: this.timestamp(),
+                    provider: completion.provider,
+                    model: completion.model,
+                },
+                finalOutcome: {
+                    origin: "agent",
+                    text: outcome,
+                    submittedAt: this.timestamp(),
+                },
+            }));
+            await this.deliver(triggerKey);
+        }
+        catch (error) {
+            submission.cancel();
+            const code = error instanceof PiRuntimeError
+                ? error.code
+                : error instanceof Error &&
+                    /submitting a Final Outcome/.test(error.message)
+                    ? "outcome_missing"
+                    : "runtime_exit_failed";
+            await this.fail(triggerKey, runId, code, error);
+        }
+    }
+    async process(triggerKey, normalize) {
+        const runId = `run_${this.id()}`;
+        let input;
+        try {
+            input = await normalize();
+        }
+        catch (error) {
+            await this.options.store.update(triggerKey, (current) => ({
+                ...current,
+                run: this.newRun(runId, "failed", {
+                    code: "trigger_normalization_failed",
+                    summary: summary(error),
+                }),
+                finalOutcome: {
+                    origin: "beacon_failure",
+                    text: `处理失败（run_id=${runId}），请查看 Beacon 本地记录。`,
+                    submittedAt: this.timestamp(),
+                },
+            }));
+            await this.deliver(triggerKey);
+            return;
+        }
+        await this.options.store.update(triggerKey, (current) => ({
+            ...current,
+            input,
+            run: this.newRun(runId, "queued"),
+        }));
+        const queued = this.options.queue.enqueue(() => this.execute(triggerKey, input, runId));
+        if (!queued.accepted) {
+            await this.fail(triggerKey, runId, "capacity_exceeded", "Run queue capacity exceeded");
+            return;
+        }
+        await queued.completion;
+    }
+    async recover() {
+        for (const record of await this.options.store.list()) {
+            if (record.delivery?.state === "delivering") {
+                await this.options.store.update(record.triggerKey, (current) => ({
+                    ...current,
+                    delivery: {
+                        ...current.delivery,
+                        state: "failed",
+                        finishedAt: this.timestamp(),
+                        failure: {
+                            code: "delivery_interrupted",
+                            summary: "Service restarted while Delivery result was unknown",
+                        },
+                    },
+                }));
+                continue;
+            }
+            if (record.delivery?.state === "pending") {
+                await this.deliver(record.triggerKey, false);
+                continue;
+            }
+            if (record.run?.state === "starting" || record.run?.state === "running") {
+                await this.fail(record.triggerKey, record.run.runId, "service_interrupted", "Service restarted while Run was active");
+                continue;
+            }
+            if (record.run?.state === "queued" && record.input) {
+                const queued = this.options.queue.enqueue(() => this.execute(record.triggerKey, record.input, record.run.runId));
+                if (!queued.accepted) {
+                    throw new Error("Persisted queued Runs exceed configured queue capacity");
+                }
+                await queued.completion;
+                continue;
+            }
+            if (!record.run) {
+                await this.fail(record.triggerKey, `run_${this.id()}`, "service_interrupted", "Service restarted before Trigger normalization completed");
+                continue;
+            }
+            if (record.finalOutcome &&
+                !record.delivery &&
+                (record.run.state === "succeeded" || record.run.state === "failed")) {
+                await this.deliver(record.triggerKey);
+            }
+        }
+    }
+}

package/dist/run/profile-runner.js

@@ -0,0 +1,39 @@
+import { runPiAgent, } from "../runtime/pi-rpc.js";
+function messageForPrompt(message) {
+    return {
+        sender_type: message.senderType,
+        message_type: message.messageType,
+        content: message.content,
+    };
+}
+export function formatFeishuTriggerPrompt(trigger) {
+    return [
+        "A Feishu user triggered this Run. Treat the following JSON as user-provided conversation context.",
+        "quoted_messages is the complete quoted chain in chronological order (oldest first).",
+        "current_message is the message that triggered this Run.",
+        JSON.stringify({
+            chat_type: trigger.source.chatType,
+            quoted_messages: trigger.quotedMessages.map(messageForPrompt),
+            current_message: messageForPrompt(trigger.message),
+        }, null, 2),
+    ].join("\n");
+}
+export function createProfileRunner(profile, outcomes, beaconCliPath, runAgent = runPiAgent) {
+    return async (trigger) => {
+        const submission = outcomes.openRun();
+        await runAgent({
+            prompt: formatFeishuTriggerPrompt(trigger),
+            workspace: profile.workspace,
+            provider: profile.model.provider,
+            model: profile.model.id,
+            systemPrompt: [
+                profile.prompt,
+                "",
+                "When your work is complete, you must call the submit_final_outcome tool exactly once with the exact user-facing response.",
+                "Beacon ignores your final assistant response for Delivery; only the submitted text is delivered.",
+            ].join("\n"),
+            outcome: { ...submission.binding, cliPath: beaconCliPath },
+        });
+        return submission.take();
+    };
+}

package/dist/run/queue.js

@@ -0,0 +1,46 @@
+export class RunQueue {
+    maxConcurrent;
+    maxQueued;
+    active = 0;
+    pending = [];
+    constructor(maxConcurrent, maxQueued) {
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueued = maxQueued;
+        if (!Number.isSafeInteger(maxConcurrent) || maxConcurrent <= 0) {
+            throw new Error("maxConcurrent must be a positive integer");
+        }
+        if (!Number.isSafeInteger(maxQueued) || maxQueued < 0) {
+            throw new Error("maxQueued must be a non-negative integer");
+        }
+    }
+    enqueue(task) {
+        if (this.active >= this.maxConcurrent &&
+            this.pending.length >= this.maxQueued) {
+            return { accepted: false };
+        }
+        let resolve;
+        let reject;
+        const completion = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        this.pending.push({ task, resolve, reject });
+        this.drain();
+        return { accepted: true, completion };
+    }
+    drain() {
+        while (this.active < this.maxConcurrent) {
+            const next = this.pending.shift();
+            if (!next)
+                return;
+            this.active += 1;
+            void next
+                .task()
+                .then(next.resolve, next.reject)
+                .finally(() => {
+                this.active -= 1;
+                this.drain();
+            });
+        }
+    }
+}