@nettee/beacon 0.2.8 → 0.2.9

package/README.md

@@ -1,6 +1,6 @@
 # Beacon
 
-Beacon is a single-host service that turns Feishu messages and configured schedules into isolated Pi agent runs. Each accepted Trigger is durably claimed, produces an explicit Final Outcome, and may `reply` to a person, `notify_card` a group, or stay silent on the admin channel.
+Beacon is a single-host service that turns Feishu messages and configured schedules into isolated Pi agent runs. Each accepted Trigger is durably claimed, produces an explicit Final Outcome, and may `reply_text` / `reply_card` to a person, `notify_card` a group, or stay silent on the admin channel.
 
 This repository currently implements the Feishu + Pi MVP described by the
 [Zest Dev Spec](https://github.com/nettee/beacon/blob/main/specs/change/20260913-beacon-feishu-pi-mvp/spec.md).
@@ -67,8 +67,8 @@ 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, the `reply` / `no_reply` /
-`notify_card` contract, and an optional `submit_feedback` tool.
+inbound vs Schedule vs manual capabilities, the `reply_text` / `reply_card` /
+`no_reply` / `notify_card` contract, and an optional `submit_feedback` tool.
 
 Protect the home and secret file before running Beacon:
 
@@ -112,10 +112,11 @@ 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.
 
 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
-for failure notices. Optional `notify.chat_id` 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.
+`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
+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.
 After sleep or restart, overdue occurrences are reconciled and coalesced to the
 most recent one.
 
@@ -157,18 +158,26 @@ messages include the `run_id` whenever a Run record was created.
 
 ## Final Outcomes
 
-An Agent closes the conversational channel with `reply` or `no_reply`, and may
-also call `notify_card` on the same Run:
-
-- `reply` sends plain text. Inbound Feishu messages quote-reply the user.
-  Schedules message the Profile admin. Inbound Runs must call `reply`, even
-  when the message is outside the Profile's role.
-- `no_reply` finishes a Schedule without messaging the admin. Its `reason` is
-  stored for audit and is never sent. Do not use it on inbound messages.
+An Agent closes the conversational channel with `reply_text`, `reply_card`, or
+`no_reply`, and may also call `notify_card` when the Run has a notify target:
+
+- `reply_text` sends plain text. Inbound Feishu messages quote-reply the user.
+  Schedules message the Profile admin.
+- `reply_card` sends an interactive card on the same conversational channel
+  (inbound quote-reply, or Schedule admin chat). It closes that channel by
+  itself.
+- `no_reply` finishes without messaging the conversational channel. Its
+  `reason` is stored for audit and is never sent. Do not use it on inbound
+  messages.
 - `notify_card` posts an interactive card to the Schedule's configured group.
-  Inbound messages cannot notify.
+  Only valid when the Run has a notify target.
+
+Which of `reply_text` / `reply_card` / `notify_card` / `no_reply` to use for a
+business result is decided by the Profile persona/task (or the situation), not
+hard-coded by Beacon beyond channel availability (`notify_card` needs a notify
+target; inbound cannot `no_reply`).
 
-The card tool accepts a title, Feishu-compatible Markdown body, and up to five
+The card tools accept a title, Feishu-compatible Markdown body, and up to five
 HTTP(S) link buttons. The first button is styled as primary. The tools accept
 these argument shapes:
 
@@ -194,9 +203,9 @@ these argument shapes:
 Beacon binds destinations; the Agent never supplies a `chat_id`. Text remains
 text. Cards are sent with Feishu's `interactive` message type and include the
 card generation time. A schedule `no_reply` without `notify_card` records a
-successful Run with no Delivery. Failures `reply` a short error and never
-notify a group. Manual local triggers print reply text and any notify card as
-Markdown on stdout.
+successful Run with no Delivery. Failures `reply_text` a short error and never
+notify a group. Manual local triggers print reply text/card and any notify card
+as Markdown on stdout.
 
 ## State and failure behavior
 

package/dist/outcome/content.js

@@ -16,10 +16,6 @@ const textReplySchema = z
 const noReplySchema = z
     .object({ kind: z.literal("no_reply"), reason: nonBlank })
     .strict();
-const replySchema = z.discriminatedUnion("kind", [
-    textReplySchema,
-    noReplySchema,
-]);
 const cardSchema = z
     .object({
     kind: z.literal("card"),
@@ -28,6 +24,11 @@ const cardSchema = z
     buttons: z.array(buttonSchema).max(5).default([]),
 })
     .strict();
+const replySchema = z.discriminatedUnion("kind", [
+    textReplySchema,
+    noReplySchema,
+    cardSchema,
+]);
 export const feedbackItemSchema = z
     .object({
     priority: z.enum(["high", "medium"]),
@@ -118,7 +119,7 @@ export function mergeOutcome(current, patch) {
     };
 }
 /** Stable English summary when the Agent settles without closing reply/no_reply. */
-export const MISSING_REPLY_OUTCOME_SUMMARY = "Expected exactly one of `reply` or `no_reply`, but the Agent Runtime settled without submitting either";
+export const MISSING_REPLY_OUTCOME_SUMMARY = "Expected exactly one of `reply_text`, `reply_card`, or `no_reply`, but the Agent Runtime settled without submitting any";
 export function isMissingReplyOutcomeError(error) {
     if (!(error instanceof Error))
         return false;
@@ -141,6 +142,8 @@ export function renderFinalOutcomeAsText(outcome) {
     const parts = [];
     if (outcome.reply.kind === "text")
         parts.push(outcome.reply.text);
+    if (outcome.reply.kind === "card")
+        parts.push(renderCard(outcome.reply));
     if (outcome.notify)
         parts.push(renderCard(outcome.notify));
     return parts.join("\n\n");

package/dist/outcome/instructions.js

@@ -1,8 +1,10 @@
 export const inboundOutOfRoleReply = "这条消息不在我的职责范围内。";
 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`.",
+    "`reply_text` 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`.",
+    "`reply_card` sends a titled Markdown card on the conversational channel (inbound quote-reply, or Schedule admin chat). It closes that channel by itself. Do not also call `reply_text` or `no_reply` on the same Run. Do not fill `chat_id`.",
+    "`no_reply` finishes a Run without messaging the conversational channel. Its reason is stored for audit and is never sent. Do not use it on inbound Feishu messages.",
+    "`notify_card` posts a titled Markdown card to the Schedule's configured notify group. Call it only when this Run has a notify target. Do not fill `chat_id`.",
+    "Which tool to use for a given business result is decided by the Profile persona/task (or the situation), not by these platform lines alone.",
     "Beacon ignores ordinary assistant final text for Delivery.",
 ];
 export const feedbackContractInstructions = [

package/dist/run/orchestrator.js

@@ -77,7 +77,7 @@ export function formatFailureReplyText(runId, failure) {
     if (failure?.code === "outcome_missing") {
         const parts = [
             `处理失败（run_id=${runId}，code=outcome_missing）：`,
-            "期望恰好调用一次 `reply` 或 `no_reply`，但 Agent 已结束且两者均未提交。",
+            "期望恰好调用一次 `reply_text`、`reply_card` 或 `no_reply`，但 Agent 已结束且均未提交。",
         ];
         const detail = failure.summary
             ? detailBeyondMissingSummary(failure.summary)
@@ -216,7 +216,7 @@ export class RunOrchestrator {
     async deliverOutcome(triggerKey, create = true) {
         const current = await this.record(triggerKey);
         const outcome = current.finalOutcome.content;
-        if (outcome.reply.kind === "text") {
+        if (outcome.reply.kind === "text" || outcome.reply.kind === "card") {
             await this.deliverField(triggerKey, "delivery", current.target, outcome.reply, create && current.delivery === undefined);
         }
         if (outcome.notify && current.notifyTarget) {
@@ -411,7 +411,8 @@ export class RunOrchestrator {
             if (latest.finalOutcome &&
                 (latest.run.state === "succeeded" || latest.run.state === "failed")) {
                 const outcome = latest.finalOutcome.content;
-                const missingReply = outcome.reply.kind === "text" && !latest.delivery;
+                const missingReply = (outcome.reply.kind === "text" || outcome.reply.kind === "card") &&
+                    !latest.delivery;
                 const missingNotify = Boolean(outcome.notify) &&
                     Boolean(latest.notifyTarget) &&
                     !latest.notifyDelivery;

package/dist/runtime/pi-outcome-extension.js

@@ -1,10 +1,20 @@
 import { spawn } from "node:child_process";
 import { parseOutcomePatch } from "../outcome/content.js";
-export function replyFromToolParams(params) {
+export function replyTextFromToolParams(params) {
     return parseOutcomePatch({
         reply: { kind: "text", text: params.text },
     });
 }
+export function replyCardFromToolParams(params) {
+    return parseOutcomePatch({
+        reply: {
+            kind: "card",
+            title: params.title,
+            content: params.content,
+            buttons: params.buttons ?? [],
+        },
+    });
+}
 export function noReplyFromToolParams(params) {
     return parseOutcomePatch({
         reply: { kind: "no_reply", reason: params.reason },
@@ -63,9 +73,9 @@ function acceptedResult() {
 }
 export default function registerOutcomeTools(pi) {
     pi.registerTool({
-        name: "reply",
-        label: "Reply",
-        description: "Send a plain-text reply. Inbound Feishu messages quote-reply the user. Schedules message the admin. Inbound Runs must use this tool, including out-of-role messages.",
+        name: "reply_text",
+        label: "Reply Text",
+        description: "Send a plain-text reply on the conversational channel. Inbound Feishu messages quote-reply the user. Schedules message the admin. Manual Runs print to the operator.",
         parameters: {
             type: "object",
             properties: {
@@ -83,6 +93,52 @@ export default function registerOutcomeTools(pi) {
             return acceptedResult();
         },
     });
+    pi.registerTool({
+        name: "reply_card",
+        label: "Reply Card",
+        description: "Send a structured interactive card on the conversational channel (inbound quote-reply, or Schedule admin chat). Closes that channel by itself. Do not also call reply_text or no_reply on the same Run.",
+        parameters: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    minLength: 1,
+                    description: "The card header title.",
+                },
+                content: {
+                    type: "string",
+                    minLength: 1,
+                    description: "The card body in Feishu-compatible Markdown.",
+                },
+                buttons: {
+                    type: "array",
+                    maxItems: 5,
+                    items: {
+                        type: "object",
+                        properties: {
+                            label: { type: "string", minLength: 1 },
+                            url: { type: "string", pattern: "^https?://" },
+                        },
+                        required: ["label", "url"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["title", "content"],
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, params, signal) {
+            await invokeBeaconCli({
+                reply: {
+                    kind: "card",
+                    title: params.title,
+                    content: params.content,
+                    buttons: params.buttons ?? [],
+                },
+            }, signal);
+            return acceptedResult();
+        },
+    });
     pi.registerTool({
         name: "no_reply",
         label: "No Reply",
@@ -107,7 +163,7 @@ export default function registerOutcomeTools(pi) {
     pi.registerTool({
         name: "notify_card",
         label: "Notify Card",
-        description: "Post a structured Feishu card to the Schedule's configured notify group. Inbound messages cannot notify. You must still call reply or no_reply on the same Run.",
+        description: "Post a structured Feishu card to the Schedule's configured notify group. Only valid when this Run has a notify target. You must still close the conversational channel with reply_text, reply_card, or no_reply on the same Run.",
         parameters: {
             type: "object",
             properties: {

package/dist/runtime/system-prompt.js

@@ -33,29 +33,30 @@ export function buildAgentSystemPrompt(profile, trigger) {
     ].join("\n");
 }
 function thisRunCapabilityInstructions(trigger) {
+    const notifyLine = trigger.notify
+        ? "You may also call `notify_card` at most once."
+        : "Do not call `notify_card`.";
     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`.",
+            "Close the conversational channel with exactly one of `reply_text` or `reply_card`.",
+            "Do not call `no_reply`.",
+            notifyLine,
         ];
     }
-    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`.",
+            "Close the conversational channel with exactly one of `reply_text`, `reply_card`, or `no_reply`.",
             notifyLine,
         ];
     }
     return [
         "This Run is a manual operator trigger.",
-        "Close the conversational channel with exactly one of `reply` or `no_reply`.",
+        "Close the conversational channel with exactly one of `reply_text`, `reply_card`, or `no_reply`.",
         notifyLine,
     ];
 }

package/package.json

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