@nettee/beacon 0.2.2 → 0.2.4

package/README.md

@@ -50,12 +50,26 @@ Copy the files under [`examples`](examples) into a private Beacon home and repla
 ├── config.yaml
 ├── runtime.env
 ├── secrets.json
-└── profiles/
-    └── example/
-        ├── profile.yaml
-        └── prompt.md
+├── profiles/
+│   └── example/
+│       └── profile.yaml
+└── workspace/
+    └── .beacon-profile/
+        ├── persona.md
+        └── task.md
 ```
 
+yaml names the workspace directory only. Beacon then loads `persona.md`
+(identity) and `task.md` (process) as a pair: `{workspace}/.beacon-profile/`
+first; if that pair is missing, `{profileDir}/`. It never mixes the two
+places, never reads yaml `prompt:` / persona / task paths, and never falls
+back to `prompt.md`. If neither place has a complete pair, Profile load fails
+and lists the missing paths. Both pairs may exist; the workspace pair wins.
+
+Beacon prepends an English platform template for this Run: workspace limit,
+inbound vs Schedule vs manual capabilities, and the `reply` / `no_reply` /
+`notify_card` contract.
+
 Protect the home and secret file before running Beacon:
 
 ```sh
@@ -95,7 +109,7 @@ 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, unsafe Prompt paths, 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, and missing Profile credentials all fail startup. Beacon validates all Profiles before opening a Feishu connection.
 
 Each Schedule uses a five-field cron expression and an IANA timezone. Profile
 `admin.chat_id` is the private chat used for schedule `reply` / `no_reply` and
@@ -237,7 +251,7 @@ The repository also contains Chinese operator runbooks based on the verified
 
 - [Deploy or update Beacon on macmini](docs/macmini-deploy-and-update.md)
 - [Add a Beacon Profile on macmini](docs/macmini-add-profile.md)
-- [Write a role-bounded Profile Prompt](docs/profile-prompt-writing.md)
+- [Write a role-bounded Profile (`persona.md` / `task.md`)](docs/profile-prompt-writing.md)
 
 ## Development checks
 

package/dist/config/profile.js

@@ -5,6 +5,9 @@ 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})$/;
+export const profilePersonaFile = "persona.md";
+export const profileTaskFile = "task.md";
+export const workspaceProfileDirectoryName = ".beacon-profile";
 const scheduleSchema = z
     .object({
     id: z.string().regex(profileIdPattern),
@@ -35,7 +38,6 @@ const scheduleSchema = z
     .strict();
 const profileDocumentSchema = z
     .object({
-    prompt: z.string().min(1),
     workspace: z.string().min(1),
     runtime: z.literal("pi"),
     model: z
@@ -60,6 +62,88 @@ function isWithin(parent, child) {
     const path = relative(parent, child);
     return path === "" || (!path.startsWith("..") && !isAbsolute(path));
 }
+export function workspaceProfileDirectory(workspace) {
+    return join(workspace, workspaceProfileDirectoryName);
+}
+async function isExistingFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function markdownPairPaths(directory) {
+    return {
+        persona: join(directory, profilePersonaFile),
+        task: join(directory, profileTaskFile),
+    };
+}
+async function missingMarkdownPaths(directory) {
+    const paths = markdownPairPaths(directory);
+    const missing = [];
+    if (!(await isExistingFile(paths.persona)))
+        missing.push(paths.persona);
+    if (!(await isExistingFile(paths.task)))
+        missing.push(paths.task);
+    return missing;
+}
+async function markdownPairExists(directory) {
+    return (await missingMarkdownPaths(directory)).length === 0;
+}
+async function loadRequiredMarkdown(canonicalDirectory, filename) {
+    const filePath = join(canonicalDirectory, filename);
+    let canonicalFilePath;
+    try {
+        canonicalFilePath = await realpath(filePath);
+    }
+    catch (error) {
+        throw new Error(`Cannot read Profile ${filename} at ${filePath}`, {
+            cause: error,
+        });
+    }
+    if (!isWithin(canonicalDirectory, canonicalFilePath)) {
+        throw new Error(`Profile ${filename} must stay inside ${canonicalDirectory}`);
+    }
+    const text = (await readFile(canonicalFilePath, "utf8")).trim();
+    if (!text) {
+        throw new Error(`Profile ${filename} must not be empty: ${canonicalFilePath}`);
+    }
+    return text;
+}
+async function loadMarkdownPair(directory, boundary) {
+    const canonicalBoundary = await realpath(boundary);
+    let canonicalDirectory;
+    try {
+        canonicalDirectory = await realpath(directory);
+    }
+    catch (error) {
+        throw new Error(`Cannot read Profile markdown at ${directory}`, {
+            cause: error,
+        });
+    }
+    if (!isWithin(canonicalBoundary, canonicalDirectory)) {
+        throw new Error(`Profile markdown must stay inside ${canonicalBoundary}`);
+    }
+    return {
+        persona: await loadRequiredMarkdown(canonicalDirectory, profilePersonaFile),
+        task: await loadRequiredMarkdown(canonicalDirectory, profileTaskFile),
+    };
+}
+async function loadPersonaAndTask(profileId, workspace, profileDirectory) {
+    const workspaceDirectory = workspaceProfileDirectory(workspace);
+    if (await markdownPairExists(workspaceDirectory)) {
+        return loadMarkdownPair(workspaceDirectory, workspace);
+    }
+    if (await markdownPairExists(profileDirectory)) {
+        return loadMarkdownPair(profileDirectory, profileDirectory);
+    }
+    const missing = [
+        ...(await missingMarkdownPaths(workspaceDirectory)),
+        ...(await missingMarkdownPaths(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")) {
     assertProfileId(profileId);
     const profileDirectory = join(profilesDirectory, profileId);
@@ -83,26 +167,7 @@ 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`);
     }
-    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);
@@ -118,10 +183,12 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
     if (!workspaceStat.isDirectory()) {
         throw new Error(`Profile workspace is not a directory: ${workspace}`);
     }
+    const { persona, task } = await loadPersonaAndTask(profileId, workspace, canonicalProfileDirectory);
     return {
         id: profileId,
         directory: canonicalProfileDirectory,
-        prompt,
+        persona,
+        task,
         workspace,
         runtime: config.runtime,
         model: config.model,

package/dist/dashboard/records.js

@@ -41,6 +41,7 @@ function summarize(value, hasSessionFile) {
         acceptedAt,
         kind: asString(input?.kind) ?? "unknown",
         scheduleId: asString(input?.scheduleId),
+        hasNotifyTarget: asRecord(record.notifyTarget) !== undefined,
         runId: asString(run?.runId),
         state: asString(run?.state),
         failureCode: asString(failure?.code),

package/dist/dashboard/server.js

@@ -2,7 +2,7 @@ import { createServer, } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadProfile } from "../config/profile.js";
-import { buildAgentSystemPrompt } from "../runtime/system-prompt.js";
+import { buildAgentSystemPrompt, } from "../runtime/system-prompt.js";
 import { exportSessionHtml } from "./export.js";
 import { findRunSummary, listRunSummaries, runIdPattern, toRunListItem, } from "./records.js";
 import { sendStaticFile } from "./static.js";
@@ -20,11 +20,24 @@ function sendText(response, status, body) {
 export function defaultUiDirectory() {
     return join(dirname(fileURLToPath(import.meta.url)), "ui");
 }
+function triggerFromRunSummary(summary) {
+    if (summary.kind === "schedule") {
+        return {
+            kind: "schedule",
+            ...(summary.scheduleId ? { scheduleId: summary.scheduleId } : {}),
+            notify: summary.hasNotifyTarget,
+        };
+    }
+    if (summary.kind === "feishu_message") {
+        return { kind: "feishu_message", notify: false };
+    }
+    return { kind: "manual", notify: summary.hasNotifyTarget };
+}
 async function beaconOwnedSystemPrompt(summary, profilesDirectory) {
     if (summary.systemPrompt)
         return summary.systemPrompt;
     try {
-        return buildAgentSystemPrompt(await loadProfile(summary.profileId, profilesDirectory));
+        return buildAgentSystemPrompt(await loadProfile(summary.profileId, profilesDirectory), triggerFromRunSummary(summary));
     }
     catch {
         // Old runs without a stored prompt: reconstruction needs a readable Profile.

package/dist/outcome/instructions.js

@@ -1,8 +1,7 @@
 export const inboundOutOfRoleReply = "这条消息不在我的职责范围内。";
-export const finalOutcomeSystemInstructions = [
-    "When your work is complete, close the conversational channel with exactly one of `reply` or `no_reply`. You may also call `notify_card` at most once on the same Run.",
-    "`reply` sends plain text. For an inbound Feishu message, quote-reply that message. For a Schedule, message the Profile admin. Inbound Runs must call `reply`, even when the message is outside this Profile's role: send a short text saying the request is out of scope. Do not call `no_reply` on inbound messages.",
-    "`no_reply` finishes a Schedule without messaging the admin. Its reason is stored for audit and is never sent. Do not use it for inbound Feishu messages.",
-    "`notify_card` posts a titled Markdown card to the Schedule's configured group. Call it only when this Run is a Schedule with a notify target. Inbound messages cannot notify.",
+export const finalOutcomeContractInstructions = [
+    "`reply` sends plain text. For an inbound Feishu message, quote-reply that message. For a Schedule, message the Profile admin. For a manual Run, print to the operator. Do not fill `chat_id`.",
+    "`no_reply` finishes a Run without messaging anyone. Its reason is stored for audit and is never sent.",
+    "`notify_card` posts a titled Markdown card to the Schedule's configured notify group. Do not fill `chat_id`.",
     "Beacon ignores ordinary assistant final text for Delivery.",
 ];

package/dist/run/orchestrator.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { isAbsolute, join } from "node:path";
 import { inboundOutOfRoleReply } from "../outcome/instructions.js";
 import { PiRuntimeError } from "../runtime/pi-rpc.js";
-import { buildAgentSystemPrompt } from "../runtime/system-prompt.js";
+import { agentSystemPromptTrigger, buildAgentSystemPrompt, profilePromptDigest, } from "../runtime/system-prompt.js";
 function promptFor(input) {
     if (input.kind === "manual") {
         return ["An operator manually triggered this Run.", "", input.text].join("\n");
@@ -80,12 +80,15 @@ export class RunOrchestrator {
             throw new Error(`Unknown Trigger ${triggerKey}`);
         return found;
     }
-    agentSystemPrompt(existing) {
+    agentSystemPrompt(trigger, existing) {
         return existing && existing.length > 0
             ? existing
-            : buildAgentSystemPrompt(this.options.profile);
+            : buildAgentSystemPrompt(this.options.profile, trigger);
     }
-    newRun(runId, state, failure) {
+    triggerFor(record, input) {
+        return agentSystemPromptTrigger(input ?? record.input, record.notifyTarget);
+    }
+    newRun(runId, state, trigger, failure) {
         const timestamp = this.timestamp();
         return {
             runId,
@@ -97,10 +100,8 @@ export class RunOrchestrator {
             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"),
-            systemPrompt: this.agentSystemPrompt(),
+            promptDigest: profilePromptDigest(this.options.profile),
+            systemPrompt: this.agentSystemPrompt(trigger),
             ...(failure ? { failure } : {}),
         };
     }
@@ -172,7 +173,8 @@ export class RunOrchestrator {
         await this.options.store.update(triggerKey, (current) => ({
             ...current,
             run: {
-                ...(current.run ?? this.newRun(runId, "queued")),
+                ...(current.run ??
+                    this.newRun(runId, "queued", this.triggerFor(current))),
                 state: "failed",
                 finishedAt: this.timestamp(),
                 failure: { code, summary: detail },
@@ -199,7 +201,7 @@ export class RunOrchestrator {
                     sessionId: current.run.runId,
                     sessionPath: join(this.options.sessionDirectory, this.options.profile.id, current.run.runId),
                 };
-            const systemPrompt = this.agentSystemPrompt(current.run.systemPrompt);
+            const systemPrompt = this.agentSystemPrompt(this.triggerFor(current, input), current.run.systemPrompt);
             return {
                 ...current,
                 run: {
@@ -268,7 +270,7 @@ export class RunOrchestrator {
         catch (error) {
             await this.options.store.update(triggerKey, (current) => ({
                 ...current,
-                run: this.newRun(runId, "failed", {
+                run: this.newRun(runId, "failed", this.triggerFor(current), {
                     code: "trigger_normalization_failed",
                     summary: summary(error),
                 }),
@@ -284,7 +286,7 @@ export class RunOrchestrator {
         await this.options.store.update(triggerKey, (current) => ({
             ...current,
             input,
-            run: this.newRun(runId, "queued"),
+            run: this.newRun(runId, "queued", this.triggerFor(current, input)),
         }));
         const queued = this.options.queue.enqueue(() => this.execute(triggerKey, input, runId));
         if (!queued.accepted) {

package/dist/run/profile-runner.js

@@ -27,7 +27,10 @@ export function createProfileRunner(profile, outcomes, beaconCliPath, runAgent =
             workspace: profile.workspace,
             provider: profile.model.provider,
             model: profile.model.id,
-            systemPrompt: buildAgentSystemPrompt(profile),
+            systemPrompt: buildAgentSystemPrompt(profile, {
+                kind: "feishu_message",
+                notify: false,
+            }),
             outcome: { ...submission.binding, cliPath: beaconCliPath },
         });
         return submission.take();

package/dist/runtime/system-prompt.js

@@ -1,10 +1,59 @@
-import { finalOutcomeSystemInstructions } from "../outcome/instructions.js";
-export function buildAgentSystemPrompt(profile) {
+import { createHash } from "node:crypto";
+import { finalOutcomeContractInstructions } from "../outcome/instructions.js";
+export function agentSystemPromptTrigger(input, notifyTarget) {
+    const notify = notifyTarget !== undefined;
+    if (input?.kind === "schedule") {
+        return { kind: "schedule", scheduleId: input.scheduleId, notify };
+    }
+    if (input?.kind === "feishu_message") {
+        return { kind: "feishu_message", notify: false };
+    }
+    return { kind: "manual", notify };
+}
+export function profilePromptDigest(profile) {
+    return createHash("sha256")
+        .update(profile.persona)
+        .update("\n")
+        .update(profile.task)
+        .digest("hex");
+}
+export function buildAgentSystemPrompt(profile, trigger) {
     return [
-        profile.prompt,
-        "",
         `All local file reads, searches, and modifications must stay within the workspace directory and its descendants: ${profile.workspace}`,
         "",
-        ...finalOutcomeSystemInstructions,
+        ...thisRunCapabilityInstructions(trigger),
+        "",
+        ...finalOutcomeContractInstructions,
+        "",
+        profile.persona,
+        "",
+        profile.task,
     ].join("\n");
 }
+function thisRunCapabilityInstructions(trigger) {
+    if (trigger.kind === "feishu_message") {
+        return [
+            "This Run is an inbound Feishu message.",
+            "Close the conversational channel with `reply`. Inbound Runs must call `reply` even when the message is outside this Profile's role: send a short text saying the request is out of scope.",
+            "Do not call `no_reply`. Do not call `notify_card`.",
+        ];
+    }
+    const notifyLine = trigger.notify
+        ? "You may also call `notify_card` at most once."
+        : "Do not call `notify_card`.";
+    if (trigger.kind === "schedule") {
+        const label = trigger.scheduleId
+            ? `This Run is Schedule ${trigger.scheduleId}.`
+            : "This Run is a Schedule.";
+        return [
+            label,
+            "Close the conversational channel with exactly one of `reply` or `no_reply`.",
+            notifyLine,
+        ];
+    }
+    return [
+        "This Run is a manual operator trigger.",
+        "Close the conversational channel with exactly one of `reply` or `no_reply`.",
+        notifyLine,
+    ];
+}

package/examples/profiles/example/profile.yaml

@@ -1,5 +1,4 @@
-prompt: prompt.md
-workspace: /ABSOLUTE/PATH/TO/WORKSPACE
+workspace: ../../workspace
 runtime: pi
 model:
   provider: REPLACE_WITH_PI_PROVIDER

package/examples/workspace/.beacon-profile/persona.md

@@ -0,0 +1,5 @@
+You are a workspace-status assistant. Your only role is to answer requests about the configured workspace's files, version-control state, and verification results.
+
+Before reading files or running commands, decide whether the input is within that role. A group `@ All` does not by itself address this bot, and a direct message is not automatically relevant. Use the quoted-message chain when the current message is a follow-up.
+
+If a Feishu message is outside this role, do not inspect the workspace. Explain in one or two sentences that the request is out of scope.

package/examples/workspace/.beacon-profile/task.md

@@ -0,0 +1,5 @@
+For in-role work, inspect the configured workspace and produce a concise user-facing result.
+
+Scheduled Runs that have nothing to report should stay silent on the admin channel. If there is a report for the notify group, send a card to that group and stay silent on the admin channel unless the admin also needs a text update.
+
+Inbound in-role work should report the result to the user. Required operations must fail visibly; do not fabricate fallback data or report success after incomplete work.

package/package.json

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

package/examples/profiles/example/prompt.md

@@ -1,9 +0,0 @@
-You are a workspace-status assistant. Your only role is to answer requests about the configured workspace's files, version-control state, and verification results.
-
-Before reading files or running commands, decide whether the input is within that role. A group `@ All` does not by itself address this bot, and a direct message is not automatically relevant. Use the quoted-message chain when the current message is a follow-up.
-
-If a Feishu message is outside this role, call `reply` with a short text saying the request is out of scope. Do not inspect the workspace. Do not call `no_reply` on inbound messages.
-
-Scheduled Runs that have nothing to report should call `no_reply`. If a Schedule has a notify group and there is a report for that group, call `notify_card` and then `no_reply` unless the admin also needs a text update.
-
-For in-role work, stay inside the configured workspace and call `reply` with a concise user-facing result. Required operations must fail visibly; do not fabricate fallback data or report success after incomplete work.