@nettee/beacon 0.3.1 → 0.3.2

package/README.md

@@ -109,11 +109,46 @@ created by Beacon 0.1.2 and earlier; when omitted it defaults to `sessions/`
 beside `config.yaml`. When configured, it must be absolute. Beacon creates
 per-Run directories with mode `0700` when Pi starts.
 
-Configuration is strict: unknown YAML/JSON fields, YAML aliases or warnings, missing paths, duplicate Schedule IDs, invalid timezones/cron expressions, a missing complete `persona.md` + `task.md` pair, escaped Profile markdown, permissive secret or runtime-environment permissions, and missing Profile credentials all fail startup. Beacon validates all Profiles before opening a Feishu connection.
+Configuration is strict: unknown YAML/JSON fields, YAML aliases or warnings, missing paths, duplicate Schedule IDs, invalid timezones/cron expressions, a missing complete `persona.md` + `task.md` pair, escaped Profile markdown, permissive secret or runtime-environment permissions, missing Profile credentials, and unknown Feishu channel names all fail startup. Beacon validates all Profiles before opening a Feishu connection.
+
+Feishu delivery destinations are registered globally in `~/.beacon/channels.yaml`
+(beside `config.yaml`), then referenced by semantic `name` from each Profile:
+
+```yaml
+# ~/.beacon/channels.yaml
+version: 1
+channels:
+  - name: admin-dm
+    description: Example admin direct chat
+    chat_id: REPLACE_WITH_ADMIN_DIRECT_CHAT_ID
+  - name: weekday-brief-group
+    description: Example weekday brief notify group
+    chat_id: REPLACE_WITH_GROUP_CHAT_ID
+```
+
+```yaml
+# profile.yaml destinations
+admin:
+  name: admin-dm
+schedules:
+  - id: weekday-brief
+    cron: "0 9 * * 1-5"
+    timezone: Asia/Shanghai
+    input: Prepare the weekday brief.
+    notify:
+      name: weekday-brief-group
+```
+
+Each channel has `name` (stable slug), `description` (human-readable Chinese or
+English label), and `chat_id` (the real Feishu chat id). Profile destinations
+bind `name` and may optionally override `description` for local readability;
+Beacon resolves `name` → `chat_id` at load time. Unknown names fail startup.
+Legacy `chat_id` directly under `admin` / `notify` is still accepted so existing
+hosts can migrate one Profile at a time; new Profiles should use `name`.
 
 Each Schedule uses a five-field cron expression and an IANA timezone. Profile
-`admin.chat_id` is the private chat used for schedule `reply_text` /
-`reply_card` / `no_reply` and for failure notices. Optional `notify.chat_id` on a
+`admin` is the private chat used for schedule `reply_text` /
+`reply_card` / `no_reply` and for failure notices. Optional `notify` on a
 Schedule is the group that receives `notify_card`. Beacon deliberately does not
 infer or fall back to another destination. A newly discovered Schedule starts at
 the current time.
@@ -181,19 +216,19 @@ Subscribe in the desired `profile.yaml`:
 
 ```yaml
 admin:
-  chat_id: REPLACE_WITH_ADMIN_DIRECT_CHAT_ID
+  name: admin-dm
 listener:
   sources:
     - https://deploy.example.com/production
   types:
     - com.example.deployment.completed.v1
   notify:
-    chat_id: REPLACE_WITH_GROUP_CHAT_ID
+    name: weekday-brief-group
 ```
 
 Both lists are required and nonempty. Values match exactly: **OR within each
 list, AND between `sources` and `types`**. There are no wildcards, regular
-expressions, or filters inside `data`. A listener requires `admin.chat_id`;
+expressions, or filters inside `data`. A listener requires `admin`;
 `listener.notify` is optional. Matching Profiles each receive one Trigger with
 the complete event as input. Their `persona.md` and `task.md` define what to do.
 `reply_text` and `reply_card` go to the configured admin; `no_reply` is allowed;
@@ -311,7 +346,7 @@ beacon schedule trigger --profile example --schedule daily-report
 
 This creates a distinct durable Run on every invocation and prints its
 `run_id`. It uses the Schedule's configured `input`, replies to
-`admin.chat_id`, and may notify `notify.chat_id`, but does not read, initialize,
+the Profile `admin` channel, and may notify the Schedule `notify` channel, but does not read, initialize,
 or advance the Schedule's cron cursor. Unknown
 Profiles or Schedules and failed Runs or Deliveries exit non-zero; failure
 messages include the `run_id` whenever a Run record was created.

package/dist/config/channels.js

@@ -0,0 +1,65 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { parseStrictYaml } from "./yaml.js";
+export const channelNamePattern = /^[a-z0-9](?:[a-z0-9_-]{0,62})$/;
+const channelEntrySchema = z
+    .object({
+    name: z
+        .string()
+        .regex(channelNamePattern, "Channel name must be a lowercase slug (a-z, 0-9, _, -)"),
+    description: z.string().trim().min(1),
+    chat_id: z.string().trim().min(1),
+})
+    .strict();
+const channelsDocumentSchema = z
+    .object({
+    version: z.literal(1),
+    channels: z.array(channelEntrySchema).default([]),
+})
+    .strict();
+export function defaultChannelsPath(homeDirectory = join(homedir(), ".beacon")) {
+    return join(homeDirectory, "channels.yaml");
+}
+export function emptyChannelRegistry() {
+    return new Map();
+}
+export async function loadChannelRegistry(path) {
+    const metadata = await stat(path).catch((error) => {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return undefined;
+        }
+        throw new Error(`Cannot inspect Beacon channels file at ${path}`, {
+            cause: error,
+        });
+    });
+    if (!metadata)
+        return emptyChannelRegistry();
+    if (!metadata.isFile()) {
+        throw new Error(`Beacon channels path is not a file: ${path}`);
+    }
+    const document = channelsDocumentSchema.parse(await parseStrictYaml(path));
+    const registry = new Map();
+    for (const entry of document.channels) {
+        if (registry.has(entry.name)) {
+            throw new Error(`Duplicate channel name in ${path}: ${entry.name}`);
+        }
+        registry.set(entry.name, {
+            name: entry.name,
+            description: entry.description,
+            chatId: entry.chat_id,
+        });
+    }
+    return registry;
+}
+export function resolveChannelName(name, channels, channelsPath) {
+    const channel = channels.get(name);
+    if (!channel) {
+        throw new Error(`Unknown Feishu channel name ${JSON.stringify(name)}; define it in ${channelsPath}`);
+    }
+    return channel;
+}

package/dist/config/global.js

@@ -100,6 +100,7 @@ export async function loadGlobalConfig(path) {
         homeDirectory,
         profilesDirectory,
         secretsPath: resolve(homeDirectory, "secrets.json"),
+        channelsPath: resolve(homeDirectory, "channels.yaml"),
         runtimeEnvironmentPath: resolve(homeDirectory, "runtime.env"),
         pi: {
             executable,

package/dist/config/profile.js

@@ -4,11 +4,27 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { z } from "zod";
 import { eventSourceSchema } from "../events/cloudevent.js";
 import { nextOccurrence } from "../schedule/cron.js";
+import { channelNamePattern, defaultChannelsPath, emptyChannelRegistry, resolveChannelName, } from "./channels.js";
 import { parseStrictYaml } from "./yaml.js";
 const profileIdPattern = /^[a-z0-9](?:[a-z0-9_-]{0,62})$/;
 export const profilePersonaFile = "persona.md";
 export const profileTaskFile = "task.md";
 export const workspaceProfileDirectoryName = ".beacon-profile";
+const namedDestinationSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(channelNamePattern, "Channel name must be a lowercase slug (a-z, 0-9, _, -)"),
+    description: z.string().trim().min(1).optional(),
+})
+    .strict();
+const legacyChatDestinationSchema = z
+    .object({ chat_id: z.string().trim().min(1) })
+    .strict();
+const destinationSchema = z.union([
+    namedDestinationSchema,
+    legacyChatDestinationSchema,
+]);
 const scheduleSchema = z
     .object({
     id: z.string().regex(profileIdPattern),
@@ -31,10 +47,7 @@ const scheduleSchema = z
         }
     }, "Schedule timezone must be a valid IANA timezone"),
     input: z.string().trim().min(1),
-    notify: z
-        .object({ chat_id: z.string().trim().min(1) })
-        .strict()
-        .optional(),
+    notify: destinationSchema.optional(),
 })
     .strict();
 const profileDocumentSchema = z
@@ -47,19 +60,13 @@ const profileDocumentSchema = z
         id: z.string().min(1),
     })
         .strict(),
-    admin: z
-        .object({ chat_id: z.string().trim().min(1) })
-        .strict()
-        .optional(),
+    admin: destinationSchema.optional(),
     schedules: z.array(scheduleSchema).default([]),
     listener: z
         .object({
         sources: z.array(eventSourceSchema).min(1),
         types: z.array(z.string().min(1)).min(1),
-        notify: z
-            .object({ chat_id: z.string().trim().min(1) })
-            .strict()
-            .optional(),
+        notify: destinationSchema.optional(),
     })
         .strict()
         .optional(),
@@ -156,10 +163,23 @@ async function loadPersonaAndTask(profileId, workspace, profileDirectory) {
     ];
     throw new Error(`Profile ${profileId} has no complete ${profilePersonaFile} + ${profileTaskFile} pair. Missing: ${missing.join(", ")}`);
 }
-export async function loadProfile(profileId, profilesDirectory = join(homedir(), ".beacon", "profiles")) {
+function resolveDestination(destination, channels, channelsPath) {
+    if ("chat_id" in destination) {
+        return { chatId: destination.chat_id };
+    }
+    const channel = resolveChannelName(destination.name, channels, channelsPath);
+    return {
+        name: channel.name,
+        description: destination.description ?? channel.description,
+        chatId: channel.chatId,
+    };
+}
+export async function loadProfile(profileId, profilesDirectory = join(homedir(), ".beacon", "profiles"), options = {}) {
     assertProfileId(profileId);
     const profileDirectory = join(profilesDirectory, profileId);
     const configPath = join(profileDirectory, "profile.yaml");
+    const channels = options.channels ?? emptyChannelRegistry();
+    const channelsPath = options.channelsPath ?? defaultChannelsPath(dirname(profilesDirectory));
     const config = profileDocumentSchema.parse(await parseStrictYaml(configPath));
     const scheduleIds = new Set();
     for (const schedule of config.schedules) {
@@ -177,11 +197,14 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
         }
     }
     if (config.schedules.length > 0 && !config.admin) {
-        throw new Error(`Profile ${profileId} with schedules must declare admin.chat_id`);
+        throw new Error(`Profile ${profileId} with schedules must declare admin`);
     }
     if (config.listener && !config.admin) {
-        throw new Error(`Profile ${profileId} with listener must declare admin.chat_id`);
+        throw new Error(`Profile ${profileId} with listener must declare admin`);
     }
+    const admin = config.admin
+        ? resolveDestination(config.admin, channels, channelsPath)
+        : undefined;
     const canonicalProfileDirectory = await realpath(profileDirectory);
     const workspace = isAbsolute(config.workspace)
         ? config.workspace
@@ -207,14 +230,16 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
         workspace,
         runtime: config.runtime,
         model: config.model,
-        ...(config.admin ? { admin: { chatId: config.admin.chat_id } } : {}),
+        ...(admin ? { admin } : {}),
         ...(config.listener
             ? {
                 listener: {
                     sources: config.listener.sources,
                     types: config.listener.types,
                     ...(config.listener.notify
-                        ? { notify: { chatId: config.listener.notify.chat_id } }
+                        ? {
+                            notify: resolveDestination(config.listener.notify, channels, channelsPath),
+                        }
                         : {}),
                 },
             }
@@ -225,14 +250,16 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
             timezone: schedule.timezone,
             input: schedule.input,
             ...(schedule.notify
-                ? { notify: { chatId: schedule.notify.chat_id } }
+                ? {
+                    notify: resolveDestination(schedule.notify, channels, channelsPath),
+                }
                 : {}),
         })),
     };
 }
 export function profileAdminChatId(profile) {
     if (!profile.admin?.chatId) {
-        throw new Error(`Profile ${profile.id} must declare admin.chat_id`);
+        throw new Error(`Profile ${profile.id} must declare admin`);
     }
     return profile.admin.chatId;
 }

package/dist/config/registry.js

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import { loadProfile } from "./profile.js";
-export async function loadProfileRegistry(profilesDirectory) {
+export async function loadProfileRegistry(profilesDirectory, channels, channelsPath) {
     const entries = await readdir(profilesDirectory, { withFileTypes: true });
     const ids = entries
         .filter((entry) => entry.isDirectory())
@@ -8,5 +8,8 @@ export async function loadProfileRegistry(profilesDirectory) {
         .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)));
+    return Promise.all(ids.map((id) => loadProfile(id, profilesDirectory, {
+        ...(channels ? { channels } : {}),
+        ...(channelsPath ? { channelsPath } : {}),
+    })));
 }

package/dist/dashboard/server.js

@@ -1,6 +1,7 @@
 import { createServer, } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { defaultChannelsPath, loadChannelRegistry, } from "../config/channels.js";
 import { loadProfile } from "../config/profile.js";
 import { buildAgentSystemPrompt, } from "../runtime/system-prompt.js";
 import { exportSessionHtml } from "./export.js";
@@ -40,7 +41,12 @@ async function beaconOwnedSystemPrompt(summary, profilesDirectory) {
     if (summary.systemPrompt)
         return summary.systemPrompt;
     try {
-        return buildAgentSystemPrompt(await loadProfile(summary.profileId, profilesDirectory), triggerFromRunSummary(summary));
+        const channelsPath = defaultChannelsPath(dirname(profilesDirectory));
+        const channels = await loadChannelRegistry(channelsPath);
+        return buildAgentSystemPrompt(await loadProfile(summary.profileId, profilesDirectory, {
+            channels,
+            channelsPath,
+        }), triggerFromRunSummary(summary));
     }
     catch {
         // Old runs without a stored prompt: reconstruction needs a readable Profile.

package/dist/doctor.js

@@ -1,3 +1,4 @@
+import { loadChannelRegistry } from "./config/channels.js";
 import { loadEventCredentials } from "./config/event-credentials.js";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
@@ -8,7 +9,8 @@ import { runPiAgent } from "./runtime/pi-rpc.js";
 export async function runDoctor(configPath) {
     const global = await loadGlobalConfig(configPath);
     const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
-    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const channels = await loadChannelRegistry(global.channelsPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory, channels, global.channelsPath);
     if (global.events)
         await loadEventCredentials(global.events.credentialsPath);
     for (const profile of profiles) {

package/dist/manual-trigger.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { loadChannelRegistry } from "./config/channels.js";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
 import { loadRuntimeEnvironment } from "./config/runtime-environment.js";
@@ -17,7 +18,8 @@ export async function runManualTrigger(configPath, profileId, input, output = wr
         throw new Error("Manual Trigger input must not be empty");
     const global = await loadGlobalConfig(configPath);
     const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
-    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const channels = await loadChannelRegistry(global.channelsPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory, channels, global.channelsPath);
     const profile = profiles.find((candidate) => candidate.id === profileId);
     if (!profile)
         throw new Error(`Unknown Profile: ${profileId}`);

package/dist/outcome/doctor.js

@@ -1,4 +1,5 @@
 import { fileURLToPath } from "node:url";
+import { defaultChannelsPath, loadChannelRegistry, } from "../config/channels.js";
 import { loadProfile } from "../config/profile.js";
 import { createProfileRunner } from "../run/profile-runner.js";
 import { startOutcomeServer } from "./server.js";
@@ -13,7 +14,12 @@ const doctorTrigger = {
     },
 };
 export async function runOutcomeDoctor(profileId) {
-    const profile = await loadProfile(profileId);
+    const channelsPath = defaultChannelsPath();
+    const channels = await loadChannelRegistry(channelsPath);
+    const profile = await loadProfile(profileId, undefined, {
+        channels,
+        channelsPath,
+    });
     const outcomes = await startOutcomeServer();
     const beaconCliPath = fileURLToPath(new URL("../../dist/cli.js", import.meta.url));
     try {

package/dist/schedule-trigger.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { loadChannelRegistry } from "./config/channels.js";
 import { loadGlobalConfig } from "./config/global.js";
 import { profileAdminChatId } from "./config/profile.js";
 import { loadProfileRegistry } from "./config/registry.js";
@@ -57,7 +58,8 @@ export async function triggerScheduleOnce(options) {
 export async function runScheduleTrigger(configPath, profileId, scheduleId) {
     const global = await loadGlobalConfig(configPath);
     const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
-    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const channels = await loadChannelRegistry(global.channelsPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory, channels, global.channelsPath);
     const profile = profiles.find((candidate) => candidate.id === profileId);
     if (!profile)
         throw new Error(`Unknown Profile: ${profileId}`);

package/dist/service.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { loadChannelRegistry } from "./config/channels.js";
 import { loadEventCredentials } from "./config/event-credentials.js";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
@@ -37,7 +38,8 @@ function shutdownController() {
 export async function runBeacon(configPath) {
     const global = await loadGlobalConfig(configPath);
     const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
-    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const channels = await loadChannelRegistry(global.channelsPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory, channels, global.channelsPath);
     const credentials = await Promise.all(profiles.map((profile) => loadFeishuCredentials(profile.id, global.secretsPath)));
     const eventProducers = global.events
         ? await loadEventCredentials(global.events.credentialsPath)

package/examples/channels.yaml.example

@@ -0,0 +1,8 @@
+version: 1
+channels:
+  - name: admin-dm
+    description: Example admin direct chat
+    chat_id: REPLACE_WITH_ADMIN_DIRECT_CHAT_ID
+  - name: weekday-brief-group
+    description: Example weekday brief notify group
+    chat_id: REPLACE_WITH_GROUP_CHAT_ID

package/examples/profiles/example/profile.yaml

@@ -4,14 +4,14 @@ model:
   provider: REPLACE_WITH_PI_PROVIDER
   id: REPLACE_WITH_PI_MODEL
 admin:
-  chat_id: REPLACE_WITH_ADMIN_DIRECT_CHAT_ID
+  name: admin-dm
 schedules:
   - id: weekday-brief
     cron: "0 9 * * 1-5"
     timezone: Asia/Shanghai
     input: Prepare the weekday brief.
     notify:
-      chat_id: REPLACE_WITH_GROUP_CHAT_ID
+      name: weekday-brief-group
 # Optional external event subscription. Both lists use exact matches.
 # listener:
 #   sources:
@@ -19,4 +19,4 @@ schedules:
 #   types:
 #     - com.example.deployment.completed.v1
 #   notify:
-#     chat_id: REPLACE_WITH_GROUP_CHAT_ID
+#     name: weekday-brief-group

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nettee/beacon",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A single-host bridge from messaging and schedules to isolated agent runs",
   "license": "Apache-2.0",
   "repository": {