@nettee/beacon 0.2.1 → 0.2.3

package/README.md

@@ -53,9 +53,16 @@ Copy the files under [`examples`](examples) into a private Beacon home and repla
 └── profiles/
     └── example/
         ├── profile.yaml
-        └── prompt.md
+        ├── persona.md
+        └── task.md
 ```
 
+Each Profile directory must contain `persona.md` (identity) and `task.md`
+(process). 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. It does not read yaml `prompt:` or
+`prompt.md`. Missing either Markdown file fails Profile load.
+
 Protect the home and secret file before running Beacon:
 
 ```sh
@@ -95,7 +102,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, missing `persona.md` or `task.md`, 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 +244,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,8 @@ 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";
 const scheduleSchema = z
     .object({
     id: z.string().regex(profileIdPattern),
@@ -35,7 +37,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 +61,26 @@ function isWithin(parent, child) {
     const path = relative(parent, child);
     return path === "" || (!path.startsWith("..") && !isAbsolute(path));
 }
+async function loadRequiredMarkdown(canonicalProfileDirectory, filename) {
+    const filePath = join(canonicalProfileDirectory, filename);
+    let canonicalFilePath;
+    try {
+        canonicalFilePath = await realpath(filePath);
+    }
+    catch (error) {
+        throw new Error(`Cannot read Profile ${filename} at ${filePath}`, {
+            cause: error,
+        });
+    }
+    if (!isWithin(canonicalProfileDirectory, canonicalFilePath)) {
+        throw new Error(`Profile ${filename} must stay inside ${canonicalProfileDirectory}`);
+    }
+    const text = (await readFile(canonicalFilePath, "utf8")).trim();
+    if (!text) {
+        throw new Error(`Profile ${filename} must not be empty: ${canonicalFilePath}`);
+    }
+    return text;
+}
 export async function loadProfile(profileId, profilesDirectory = join(homedir(), ".beacon", "profiles")) {
     assertProfileId(profileId);
     const profileDirectory = join(profilesDirectory, profileId);
@@ -83,26 +104,9 @@ 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 persona = await loadRequiredMarkdown(canonicalProfileDirectory, profilePersonaFile);
+    const task = await loadRequiredMarkdown(canonicalProfileDirectory, profileTaskFile);
     const workspace = isAbsolute(config.workspace)
         ? config.workspace
         : resolve(dirname(configPath), config.workspace);
@@ -121,7 +125,8 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
     return {
         id: profileId,
         directory: canonicalProfileDirectory,
-        prompt,
+        persona,
+        task,
         workspace,
         runtime: config.runtime,
         model: config.model,

package/dist/dashboard/export.js

@@ -3,7 +3,7 @@ import { mkdtemp, readdir, readFile, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, sep } from "node:path";
 import { promisify } from "node:util";
-import { fillExportedHtmlSystemPrompt, systemPromptFromJsonl, } from "./session-prompt.js";
+import { fillExportedHtmlSystemPrompt, pickExportedSystemPrompt, } from "./session-prompt.js";
 const execFileAsync = promisify(execFile);
 function isInside(root, candidate) {
     return candidate === root || candidate.startsWith(`${root}${sep}`);
@@ -44,7 +44,7 @@ export async function exportSessionHtml(request) {
             windowsHide: true,
         });
         const html = await readFile(outputPath, "utf8");
-        const systemPrompt = systemPromptFromJsonl(await readFile(jsonlPath, "utf8"));
+        const systemPrompt = pickExportedSystemPrompt(await readFile(jsonlPath, "utf8"), request.systemPrompt);
         return systemPrompt
             ? fillExportedHtmlSystemPrompt(html, systemPrompt)
             : html;

package/dist/dashboard/records.js

@@ -41,12 +41,14 @@ 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),
         deliveryState: asString(delivery?.state),
         sessionPath: asString(run?.sessionPath),
         hasSessionFile,
+        systemPrompt: asString(run?.systemPrompt),
     };
 }
 async function loadSummary(path) {

package/dist/dashboard/server.js

@@ -1,6 +1,8 @@
 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 { exportSessionHtml } from "./export.js";
 import { findRunSummary, listRunSummaries, runIdPattern, toRunListItem, } from "./records.js";
 import { sendStaticFile } from "./static.js";
@@ -18,6 +20,30 @@ 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), triggerFromRunSummary(summary));
+    }
+    catch {
+        // Old runs without a stored prompt: reconstruction needs a readable Profile.
+        return undefined;
+    }
+}
 export async function startDashboard(options) {
     const cache = new Map();
     const inflight = new Map();
@@ -63,6 +89,7 @@ export async function startDashboard(options) {
                     sessionDirectory: options.sessionDirectory,
                     runId: summary.runId,
                     sessionPath: summary.sessionPath,
+                    systemPrompt: await beaconOwnedSystemPrompt(summary, options.profilesDirectory),
                     timeoutMs: options.exportTimeoutMs,
                 }).finally(() => {
                     inflight.delete(runId);

package/dist/dashboard/session-prompt.js

@@ -23,6 +23,13 @@ function systemMessageText(content, sections) {
         .filter((part) => part.length > 0)
         .join("\n\n");
 }
+function nonempty(value) {
+    return value && value.length > 0 ? value : undefined;
+}
+/** Prefer a JSONL system message; otherwise the Beacon-owned `--system-prompt` text. */
+export function pickExportedSystemPrompt(jsonl, beaconOwned) {
+    return systemPromptFromJsonl(jsonl) ?? nonempty(beaconOwned);
+}
 export function systemPromptFromJsonl(jsonl) {
     const contents = [];
     const sections = new Map();

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,7 +80,15 @@ export class RunOrchestrator {
             throw new Error(`Unknown Trigger ${triggerKey}`);
         return found;
     }
-    newRun(runId, state, failure) {
+    agentSystemPrompt(trigger, existing) {
+        return existing && existing.length > 0
+            ? existing
+            : buildAgentSystemPrompt(this.options.profile, trigger);
+    }
+    triggerFor(record, input) {
+        return agentSystemPromptTrigger(input ?? record.input, record.notifyTarget);
+    }
+    newRun(runId, state, trigger, failure) {
         const timestamp = this.timestamp();
         return {
             runId,
@@ -92,9 +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"),
+            promptDigest: profilePromptDigest(this.options.profile),
+            systemPrompt: this.agentSystemPrompt(trigger),
             ...(failure ? { failure } : {}),
         };
     }
@@ -166,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 },
@@ -193,6 +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(this.triggerFor(current, input), current.run.systemPrompt);
             return {
                 ...current,
                 run: {
@@ -200,6 +209,7 @@ export class RunOrchestrator {
                     ...session,
                     state: "starting",
                     startedAt: this.timestamp(),
+                    systemPrompt,
                 },
             };
         });
@@ -214,7 +224,7 @@ export class RunOrchestrator {
                 workspace: this.options.profile.workspace,
                 provider: this.options.profile.model.provider,
                 model: this.options.profile.model.id,
-                systemPrompt: buildAgentSystemPrompt(this.options.profile),
+                systemPrompt: record.run.systemPrompt,
                 outcome: { ...submission.binding, cliPath: this.options.beaconCliPath },
                 session: {
                     id: record.run.sessionId,
@@ -260,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),
                 }),
@@ -276,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/dist/state/trigger-store.js

@@ -62,6 +62,7 @@ const runSchema = z
     model: z.string().min(1),
     workspace: z.string().min(1),
     promptDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    systemPrompt: z.string().min(1).optional(),
     failure: failureSchema.optional(),
 })
     .strict();

package/examples/profiles/example/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/profiles/example/profile.yaml

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

package/examples/profiles/example/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.1",
+  "version": "0.2.3",
   "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.