@nettee/beacon 0.1.0

package/dist/config/profile.js

@@ -0,0 +1,126 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { z } from "zod";
+import { nextOccurrence } from "../schedule/cron.js";
+import { parseStrictYaml } from "./yaml.js";
+const profileIdPattern = /^[a-z0-9](?:[a-z0-9_-]{0,62})$/;
+const scheduleSchema = z
+    .object({
+    id: z.string().regex(profileIdPattern),
+    cron: z
+        .string()
+        .trim()
+        .refine((value) => value.split(/\s+/).length === 5, {
+        message: "Schedule cron must contain exactly five fields",
+    }),
+    timezone: z
+        .string()
+        .min(1)
+        .refine((value) => {
+        try {
+            new Intl.DateTimeFormat("en", { timeZone: value }).format();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, "Schedule timezone must be a valid IANA timezone"),
+    input: z.string().trim().min(1),
+    delivery: z.object({ chat_id: z.string().trim().min(1) }).strict(),
+})
+    .strict();
+const profileDocumentSchema = z
+    .object({
+    prompt: z.string().min(1),
+    workspace: z.string().min(1),
+    runtime: z.literal("pi"),
+    model: z
+        .object({
+        provider: z.string().min(1),
+        id: z.string().min(1),
+    })
+        .strict(),
+    schedules: z.array(scheduleSchema).default([]),
+})
+    .strict();
+function assertProfileId(profileId) {
+    if (!profileIdPattern.test(profileId)) {
+        throw new Error(`Invalid Profile ID: ${JSON.stringify(profileId)}`);
+    }
+}
+function isWithin(parent, child) {
+    const path = relative(parent, child);
+    return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+}
+export async function loadProfile(profileId, profilesDirectory = join(homedir(), ".beacon", "profiles")) {
+    assertProfileId(profileId);
+    const profileDirectory = join(profilesDirectory, profileId);
+    const configPath = join(profileDirectory, "profile.yaml");
+    const config = profileDocumentSchema.parse(await parseStrictYaml(configPath));
+    const scheduleIds = new Set();
+    for (const schedule of config.schedules) {
+        if (scheduleIds.has(schedule.id)) {
+            throw new Error(`Duplicate Schedule ID in Profile ${profileId}: ${schedule.id}`);
+        }
+        scheduleIds.add(schedule.id);
+        try {
+            nextOccurrence(schedule.cron, schedule.timezone, new Date(0));
+        }
+        catch (error) {
+            throw new Error(`Invalid Schedule cron in Profile ${profileId}: ${schedule.id}`, {
+                cause: error,
+            });
+        }
+    }
+    if (isAbsolute(config.prompt)) {
+        throw new Error(`Profile prompt path must be relative to ${profileDirectory}`);
+    }
+    const promptPath = resolve(profileDirectory, config.prompt);
+    const canonicalProfileDirectory = await realpath(profileDirectory);
+    let canonicalPromptPath;
+    try {
+        canonicalPromptPath = await realpath(promptPath);
+    }
+    catch (error) {
+        throw new Error(`Cannot read Profile prompt at ${promptPath}`, {
+            cause: error,
+        });
+    }
+    if (!isWithin(canonicalProfileDirectory, canonicalPromptPath)) {
+        throw new Error(`Profile prompt must stay inside ${canonicalProfileDirectory}`);
+    }
+    const prompt = (await readFile(canonicalPromptPath, "utf8")).trim();
+    if (!prompt)
+        throw new Error(`Profile prompt must not be empty: ${canonicalPromptPath}`);
+    const workspace = isAbsolute(config.workspace)
+        ? config.workspace
+        : resolve(dirname(configPath), config.workspace);
+    let workspaceStat;
+    try {
+        workspaceStat = await stat(workspace);
+    }
+    catch (error) {
+        throw new Error(`Cannot access Profile workspace at ${workspace}`, {
+            cause: error,
+        });
+    }
+    if (!workspaceStat.isDirectory()) {
+        throw new Error(`Profile workspace is not a directory: ${workspace}`);
+    }
+    return {
+        id: profileId,
+        directory: canonicalProfileDirectory,
+        prompt,
+        workspace,
+        runtime: config.runtime,
+        model: config.model,
+        schedules: config.schedules.map((schedule) => ({
+            id: schedule.id,
+            cron: schedule.cron,
+            timezone: schedule.timezone,
+            input: schedule.input,
+            delivery: { chatId: schedule.delivery.chat_id },
+        })),
+    };
+}

package/dist/config/registry.js

@@ -0,0 +1,12 @@
+import { readdir } from "node:fs/promises";
+import { loadProfile } from "./profile.js";
+export async function loadProfileRegistry(profilesDirectory) {
+    const entries = await readdir(profilesDirectory, { withFileTypes: true });
+    const ids = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    if (ids.length === 0)
+        throw new Error(`No Profiles found in ${profilesDirectory}`);
+    return Promise.all(ids.map((id) => loadProfile(id, profilesDirectory)));
+}

package/dist/config/secrets.js

@@ -0,0 +1,68 @@
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+const secretsSchema = z
+    .object({
+    version: z.literal(1),
+    profiles: z.record(z.string(), z
+        .object({
+        feishu: z
+            .object({
+            app_id: z
+                .string()
+                .regex(/^cli_[0-9a-fA-F]{16}$/, "Invalid Feishu app_id"),
+            app_secret: z.string().min(1),
+        })
+            .strict(),
+    })
+        .strict()),
+})
+    .strict();
+export async function loadFeishuCredentials(profileId, path = join(homedir(), ".beacon", "secrets.json")) {
+    const metadata = await stat(path).catch((error) => {
+        throw new Error(`Cannot inspect Beacon secrets file at ${path}`, {
+            cause: error,
+        });
+    });
+    if (!metadata.isFile())
+        throw new Error(`Beacon secrets path is not a file: ${path}`);
+    if ((metadata.mode & 0o777) !== 0o600) {
+        throw new Error(`Beacon secrets file must have mode 0600: ${path}`);
+    }
+    if (typeof process.getuid === "function" &&
+        metadata.uid !== process.getuid()) {
+        throw new Error(`Beacon secrets file must be owned by the current user: ${path}`);
+    }
+    const parent = await stat(dirname(path));
+    if ((parent.mode & 0o077) !== 0) {
+        throw new Error(`Beacon secrets parent directory must not grant group/world access: ${dirname(path)}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Cannot read Beacon secrets file at ${path}`, {
+            cause: error,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Beacon secrets file is not valid JSON: ${path}`, {
+            cause: error,
+        });
+    }
+    const secrets = secretsSchema.parse(parsed);
+    const profile = secrets.profiles[profileId];
+    if (!profile) {
+        throw new Error(`No credentials configured for profile "${profileId}" in ${path}`);
+    }
+    return {
+        appId: profile.feishu.app_id,
+        appSecret: profile.feishu.app_secret,
+    };
+}

package/dist/config/yaml.js

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { parseDocument } from "yaml";
+export async function parseStrictYaml(path) {
+    let source;
+    try {
+        source = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Cannot read YAML configuration at ${path}`, {
+            cause: error,
+        });
+    }
+    const document = parseDocument(source, {
+        schema: "core",
+        strict: true,
+        uniqueKeys: true,
+        version: "1.2",
+    });
+    if (document.errors.length > 0) {
+        throw new Error(`Invalid YAML configuration at ${path}: ${document.errors[0]?.message}`);
+    }
+    if (document.warnings.length > 0) {
+        throw new Error(`YAML warning at ${path}: ${document.warnings[0]?.message}`);
+    }
+    try {
+        return document.toJS({ maxAliasCount: 0 });
+    }
+    catch (error) {
+        throw new Error(`YAML aliases are not allowed at ${path}`, {
+            cause: error,
+        });
+    }
+}

package/dist/doctor.js

@@ -0,0 +1,29 @@
+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 { runPiAgent } from "./runtime/pi-rpc.js";
+export async function runDoctor(configPath) {
+    const global = await loadGlobalConfig(configPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    for (const profile of profiles) {
+        const credentials = await loadFeishuCredentials(profile.id, global.secretsPath);
+        await createFeishuGateway(credentials).checkReady();
+        const result = await runPiAgent({
+            prompt: "Reply with exactly: BEACON_PI_RPC_OK",
+            workspace: profile.workspace,
+            provider: profile.model.provider,
+            model: profile.model.id,
+            systemPrompt: "Follow the user's instruction exactly. Do not use tools.",
+        }, {
+            executable: global.pi.executable,
+            timeoutMs: global.runs.timeoutSeconds * 1_000,
+            terminateGraceMs: global.runs.terminateGraceSeconds * 1_000,
+            environment: { PI_CODING_AGENT_DIR: global.pi.codingAgentDirectory },
+        });
+        if (result.text !== "BEACON_PI_RPC_OK") {
+            throw new Error(`Pi readiness returned unexpected text for Profile ${profile.id}: ${JSON.stringify(result.text)}`);
+        }
+        console.log(`[beacon] doctor Profile ready id=${profile.id}`);
+    }
+}

package/dist/domain/types.js

@@ -0,0 +1,18 @@
+export const failureCodes = [
+    "config_invalid",
+    "secret_invalid",
+    "gateway_terminal",
+    "trigger_persist_failed",
+    "trigger_normalization_failed",
+    "schedule_state_invalid",
+    "capacity_exceeded",
+    "runtime_spawn_failed",
+    "runtime_protocol_error",
+    "runtime_timeout",
+    "runtime_exit_failed",
+    "outcome_missing",
+    "outcome_invalid",
+    "service_interrupted",
+    "delivery_api_failed",
+    "delivery_interrupted",
+];

package/dist/feishu/doctor.js

@@ -0,0 +1,21 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+export async function runFeishuDoctor(credentials) {
+    const dispatcher = new Lark.EventDispatcher({
+        loggerLevel: Lark.LoggerLevel.info,
+    }).register({
+        "im.message.receive_v1": async (event) => {
+            const messageId = event.message.message_id;
+            const chatType = event.message.chat_type;
+            const content = JSON.parse(event.message.content);
+            console.log(`[beacon] received message event message_id=${messageId} chat_type=${chatType}`);
+            console.log(`[beacon] message content=${JSON.stringify(content)}`);
+        },
+    });
+    const client = new Lark.WSClient({
+        appId: credentials.appId,
+        appSecret: credentials.appSecret,
+        loggerLevel: Lark.LoggerLevel.info,
+    });
+    console.log("[beacon] starting Feishu long connection; press Ctrl-C to stop");
+    await client.start({ eventDispatcher: dispatcher });
+}

package/dist/feishu/gateway.js

@@ -0,0 +1,129 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+export function waitForShutdown(signals = process) {
+    return new Promise((resolve) => {
+        const shutdown = () => {
+            signals.off("SIGINT", shutdown);
+            signals.off("SIGTERM", shutdown);
+            resolve();
+        };
+        signals.once("SIGINT", shutdown);
+        signals.once("SIGTERM", shutdown);
+    });
+}
+export function shouldAcceptFeishuMessage(chatType, senderType, messageId, processedMessageIds) {
+    return ((chatType === "p2p" || chatType === "group") &&
+        senderType === "user" &&
+        !processedMessageIds.has(messageId));
+}
+function assertSucceeded(operation, result) {
+    if (result.code !== undefined && result.code !== 0) {
+        throw new Error(`${operation} failed: code=${result.code} msg=${result.msg ?? "unknown"}`);
+    }
+}
+function textContent(text) {
+    return JSON.stringify({ text });
+}
+export class FeishuGateway {
+    credentials;
+    client;
+    constructor(credentials) {
+        this.credentials = credentials;
+        this.client = new Lark.Client(credentials);
+    }
+    async checkReady() {
+        const result = (await this.client.auth.v3.tenantAccessToken.internal({
+            data: {
+                app_id: this.credentials.appId,
+                app_secret: this.credentials.appSecret,
+            },
+        }));
+        assertSucceeded("obtain tenant access token", result);
+        if (!result.tenant_access_token) {
+            throw new Error("Feishu readiness returned no tenant_access_token");
+        }
+    }
+    async run(handleEvent, shutdown = waitForShutdown()) {
+        const dispatcher = new Lark.EventDispatcher({
+            loggerLevel: Lark.LoggerLevel.info,
+        }).register({
+            "im.message.receive_v1": async (event) => {
+                await handleEvent(event);
+            },
+        });
+        let rejectTerminalFailure = () => undefined;
+        const terminalFailure = new Promise((_resolve, reject) => {
+            rejectTerminalFailure = reject;
+        });
+        const ws = new Lark.WSClient({
+            ...this.credentials,
+            loggerLevel: Lark.LoggerLevel.info,
+            onError: (error) => rejectTerminalFailure(error),
+        });
+        console.log("[beacon] Feishu Gateway ready");
+        try {
+            await ws.start({ eventDispatcher: dispatcher });
+            await Promise.race([shutdown, terminalFailure]);
+        }
+        finally {
+            ws.close({ force: true });
+        }
+    }
+    async acknowledge(messageId) {
+        const result = await this.client.im.v1.messageReaction.create({
+            path: { message_id: messageId },
+            data: { reaction_type: { emoji_type: "OnIt" } },
+        });
+        assertSucceeded("add OnIt reaction", result);
+    }
+    async fetchMessage(messageId) {
+        const result = await this.client.im.v1.message.get({
+            path: { message_id: messageId },
+        });
+        assertSucceeded("fetch quoted message", result);
+        const message = result.data?.items?.[0];
+        if (!message?.message_id ||
+            !message.msg_type ||
+            !message.sender?.sender_type ||
+            message.body?.content === undefined) {
+            throw new Error(`Feishu returned no readable quoted message for message_id=${messageId}`);
+        }
+        return {
+            messageId: message.message_id,
+            messageType: message.msg_type,
+            senderType: message.sender.sender_type,
+            senderId: message.sender.id,
+            content: message.body.content,
+            parentMessageId: message.parent_id,
+        };
+    }
+    async deliver(target, text) {
+        if (target.kind === "reply") {
+            const result = await this.client.im.v1.message.reply({
+                path: { message_id: target.messageId },
+                data: {
+                    msg_type: "text",
+                    content: textContent(text),
+                    reply_in_thread: false,
+                },
+            });
+            assertSucceeded("deliver quoted reply", result);
+            return {};
+        }
+        if (target.kind === "chat") {
+            const result = await this.client.im.v1.message.create({
+                params: { receive_id_type: "chat_id" },
+                data: {
+                    receive_id: target.chatId,
+                    msg_type: "text",
+                    content: textContent(text),
+                },
+            });
+            assertSucceeded("deliver chat message", result);
+            return {};
+        }
+        throw new Error("Feishu Gateway cannot deliver to local stdout");
+    }
+}
+export function createFeishuGateway(credentials) {
+    return new FeishuGateway(credentials);
+}

package/dist/feishu/intake.js

@@ -0,0 +1,67 @@
+import { buildFeishuTriggerInput, } from "./trigger-input.js";
+export class FeishuIntake {
+    options;
+    active = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async handle(event) {
+        if (event.sender.sender_type !== "user" ||
+            (event.message.chat_type !== "p2p" && event.message.chat_type !== "group")) {
+            return "ignored";
+        }
+        if (!event.event_id)
+            throw new Error("Feishu event_id is required");
+        const claim = await this.options.store.claim({
+            sourceKey: ["feishu", event.event_id],
+            target: { kind: "reply", messageId: event.message.message_id },
+            ingress: {
+                eventId: event.event_id,
+                messageId: event.message.message_id,
+                chatId: event.message.chat_id,
+                chatType: event.message.chat_type,
+                senderId: event.sender.sender_id?.open_id,
+                senderType: event.sender.sender_type,
+                messageType: event.message.message_type,
+                content: event.message.content,
+                ...(event.message.parent_id
+                    ? { parentMessageId: event.message.parent_id }
+                    : {}),
+            },
+        });
+        if (!claim.created)
+            return "duplicate";
+        void this.options
+            .acknowledge(event.message.message_id)
+            .catch((error) => {
+            console.error(`[beacon] non-critical acknowledgement failure message_id=${event.message.message_id}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        const task = this.options.process(claim.record.triggerKey, async () => {
+            const normalized = await buildFeishuTriggerInput({
+                messageId: event.message.message_id,
+                chatId: event.message.chat_id,
+                chatType: event.message.chat_type,
+                senderId: event.sender.sender_id?.open_id,
+                senderType: event.sender.sender_type,
+                messageType: event.message.message_type,
+                content: event.message.content,
+                parentMessageId: event.message.parent_id,
+            }, this.options.fetchMessage);
+            return {
+                kind: "feishu_message",
+                eventId: event.event_id,
+                chatType: normalized.source.chatType,
+                quotedMessages: normalized.quotedMessages,
+                currentMessage: normalized.message,
+            };
+        });
+        this.active.add(task);
+        void task
+            .catch((error) => this.options.onFatal(error instanceof Error ? error : new Error(String(error))))
+            .finally(() => this.active.delete(task));
+        return "accepted";
+    }
+    async drain() {
+        await Promise.all([...this.active]);
+    }
+}

package/dist/feishu/message-gateway.js

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

package/dist/feishu/message-pipeline.js

@@ -0,0 +1,14 @@
+import { FeishuIntake } from "./intake.js";
+export function createFeishuMessagePipeline(options) {
+    const intake = new FeishuIntake({
+        store: options.store,
+        process: options.process,
+        fetchMessage: (messageId) => options.gateway.fetchMessage(messageId),
+        acknowledge: (messageId) => options.gateway.acknowledge(messageId),
+        onFatal: options.onFatal,
+    });
+    return {
+        run: (shutdown) => options.gateway.run((event) => intake.handle(event), shutdown),
+        drain: () => intake.drain(),
+    };
+}

package/dist/feishu/reply-experiment.js

@@ -0,0 +1,111 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { buildFeishuTriggerInput, } from "./trigger-input.js";
+function assertSucceeded(operation, result) {
+    if (result.code !== undefined && result.code !== 0) {
+        throw new Error(`${operation} failed: code=${result.code} msg=${result.msg ?? "unknown"}`);
+    }
+}
+function textContent(text) {
+    return JSON.stringify({ text });
+}
+export function shouldExerciseReplyExperiment(chatType, messageId, processedMessageIds) {
+    return ((chatType === "p2p" || chatType === "group") &&
+        !processedMessageIds.has(messageId));
+}
+export async function runFeishuReplyExperiment(credentials) {
+    const api = new Lark.Client(credentials);
+    const processedMessageIds = new Set();
+    async function attempt(label, operation) {
+        try {
+            const result = await operation();
+            assertSucceeded(label, result);
+            console.log(`[beacon] succeeded: ${label}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[beacon] failed: ${label}: ${message}`);
+        }
+    }
+    async function fetchMessage(messageId) {
+        const result = await api.im.v1.message.get({
+            path: { message_id: messageId },
+        });
+        assertSucceeded("fetch quoted message", result);
+        const message = result.data?.items?.[0];
+        if (!message?.message_id ||
+            !message.msg_type ||
+            !message.sender?.sender_type ||
+            message.body?.content === undefined) {
+            throw new Error(`Feishu returned no readable message for quoted message_id=${messageId}`);
+        }
+        return {
+            messageId: message.message_id,
+            messageType: message.msg_type,
+            senderType: message.sender.sender_type,
+            senderId: message.sender.id,
+            content: message.body.content,
+            parentMessageId: message.parent_id,
+        };
+    }
+    async function exercise(event) {
+        const { message, sender } = event;
+        const messageId = message.message_id;
+        await attempt("add OnIt reaction", () => api.im.v1.messageReaction.create({
+            path: { message_id: messageId },
+            data: { reaction_type: { emoji_type: "OnIt" } },
+        }));
+        const triggerInput = await buildFeishuTriggerInput({
+            messageId,
+            chatId: message.chat_id,
+            chatType: message.chat_type,
+            senderId: sender.sender_id?.open_id,
+            senderType: sender.sender_type,
+            messageType: message.message_type,
+            content: message.content,
+            parentMessageId: message.parent_id,
+        }, fetchMessage);
+        console.log(`[beacon] trigger input=${JSON.stringify(triggerInput)}`);
+        await attempt("quoted final reply", () => api.im.v1.message.reply({
+            path: { message_id: messageId },
+            data: {
+                msg_type: "text",
+                content: textContent(triggerInput.quotedMessages.length > 0
+                    ? `已记录当前消息及完整引用链（${triggerInput.quotedMessages.length} 条）；后续会一起交给 Agent Runtime。`
+                    : "已记录当前消息；本条消息没有引用上下文。"),
+                reply_in_thread: false,
+            },
+        }));
+    }
+    const dispatcher = new Lark.EventDispatcher({
+        loggerLevel: Lark.LoggerLevel.info,
+    }).register({
+        "im.message.receive_v1": async (event) => {
+            const { chat_type: chatType, content, message_id: messageId, } = event.message;
+            const parsed = JSON.parse(content);
+            console.log(`[beacon] received message event message_id=${messageId} chat_type=${chatType} content=${JSON.stringify(parsed)}`);
+            if (!shouldExerciseReplyExperiment(chatType, messageId, processedMessageIds)) {
+                console.log(`[beacon] ignored duplicate or unsupported event message_id=${messageId}`);
+                return;
+            }
+            processedMessageIds.add(messageId);
+            void exercise(event).catch(async (error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`[beacon] reply experiment failed: ${message}`);
+                await attempt("quoted failure reply", () => api.im.v1.message.reply({
+                    path: { message_id: messageId },
+                    data: {
+                        msg_type: "text",
+                        content: textContent(`处理失败：${message}`),
+                        reply_in_thread: false,
+                    },
+                }));
+            });
+        },
+    });
+    const ws = new Lark.WSClient({
+        ...credentials,
+        loggerLevel: Lark.LoggerLevel.info,
+    });
+    console.log("[beacon] quoted-reply experiment ready; every new DM and group mention triggers one run");
+    await ws.start({ eventDispatcher: dispatcher });
+}