@nettee/beacon 0.2.7 → 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

@@ -40,13 +40,54 @@ function summary(error) {
     const value = error instanceof Error ? error.message : String(error);
     return value.slice(0, 4096) || "unknown failure";
 }
-/** User-visible (Feishu/admin) failure text. Keep codes stable; explain missing outcomes. */
+const FAILURE_DETAIL_LIMIT = 400;
+const THINKING_SNIPPET_LIMIT = 120;
+function clipForFeishu(value, max) {
+    const trimmed = value.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, Math.max(0, max - 1))}…`;
+}
+/** Compact settle-side hint for outcome_missing (Feishu / admin). */
+export function formatSettleFailureHint(parts) {
+    const bits = [];
+    if (parts.stopReason?.trim()) {
+        bits.push(`末轮 stopReason=${parts.stopReason.trim()}`);
+    }
+    const thought = parts.thinking?.trim() || parts.text?.trim();
+    if (thought) {
+        bits.push(`thinking：「${clipForFeishu(thought, THINKING_SNIPPET_LIMIT)}」`);
+    }
+    return bits.length > 0 ? bits.join("；") : undefined;
+}
+function detailBeyondMissingSummary(summaryText) {
+    if (summaryText === MISSING_REPLY_OUTCOME_SUMMARY)
+        return undefined;
+    if (summaryText.startsWith(MISSING_REPLY_OUTCOME_SUMMARY)) {
+        const rest = summaryText
+            .slice(MISSING_REPLY_OUTCOME_SUMMARY.length)
+            .replace(/^[\s.;]+/, "")
+            .trim();
+        return rest ? clipForFeishu(rest, FAILURE_DETAIL_LIMIT) : undefined;
+    }
+    return clipForFeishu(summaryText, FAILURE_DETAIL_LIMIT);
+}
+/** User-visible (Feishu/admin) failure text. Keep codes stable; prefer concrete reasons. */
 export function formatFailureReplyText(runId, failure) {
     if (failure?.code === "outcome_missing") {
-        return [
+        const parts = [
             `处理失败（run_id=${runId}，code=outcome_missing）：`,
-            "期望恰好调用一次 `reply` 或 `no_reply`，但 Agent 已结束且两者均未提交。",
-        ].join("");
+            "期望恰好调用一次 `reply_text`、`reply_card` 或 `no_reply`，但 Agent 已结束且均未提交。",
+        ];
+        const detail = failure.summary
+            ? detailBeyondMissingSummary(failure.summary)
+            : undefined;
+        if (detail)
+            parts.push(`详情：${detail}`);
+        return parts.join("");
+    }
+    if (failure?.summary?.trim()) {
+        return `处理失败（run_id=${runId}，code=${failure.code}）：${clipForFeishu(failure.summary, FAILURE_DETAIL_LIMIT)}`;
     }
     if (failure) {
         return `处理失败（run_id=${runId}，code=${failure.code}），请查看 Beacon 本地记录。`;
@@ -175,17 +216,22 @@ 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) {
             await this.deliverField(triggerKey, "notifyDelivery", current.notifyTarget, outcome.notify, create && current.notifyDelivery === undefined);
         }
     }
-    async fail(triggerKey, runId, code, error, submitted) {
-        const detail = isMissingReplyOutcomeError(error)
+    async fail(triggerKey, runId, code, error, submitted, settle) {
+        let detail = isMissingReplyOutcomeError(error)
             ? MISSING_REPLY_OUTCOME_SUMMARY
             : summary(error);
+        if (code === "outcome_missing") {
+            const hint = formatSettleFailureHint(settle ?? {});
+            if (hint)
+                detail = `${detail}. ${hint}`;
+        }
         const failure = { code, summary: detail };
         await this.options.store.update(triggerKey, (current) => ({
             ...current,
@@ -236,6 +282,7 @@ export class RunOrchestrator {
             run: { ...current.run, state: "running" },
         }));
         const submission = this.options.outcomes.openRun();
+        let settle;
         try {
             const completion = await this.options.runAgent({
                 prompt: promptFor(input),
@@ -250,6 +297,11 @@ export class RunOrchestrator {
                     name: `Beacon ${this.options.profile.id} ${runId}`,
                 },
             });
+            settle = {
+                stopReason: completion.stopReason,
+                thinking: completion.thinking,
+                text: completion.text,
+            };
             const submitted = submission.takeFeedback();
             const outcome = normalizeAgentOutcome(input, submission.take(), record.notifyTarget);
             await this.options.store.update(triggerKey, (current) => ({
@@ -278,7 +330,7 @@ export class RunOrchestrator {
                 : isMissingReplyOutcomeError(error)
                     ? "outcome_missing"
                     : "runtime_exit_failed";
-            await this.fail(triggerKey, runId, code, error, submitted);
+            await this.fail(triggerKey, runId, code, error, submitted, settle);
         }
     }
     async process(triggerKey, normalize) {
@@ -359,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/pi-rpc.js

@@ -45,6 +45,27 @@ function collectText(message) {
         .join("")
         .trim();
 }
+/** Collect thinking / reasoning blocks from an assistant message content array. */
+export function collectThinking(content) {
+    return content
+        .map((block) => {
+        if (!isObject(block))
+            return "";
+        if (block.type === "thinking") {
+            if (typeof block.thinking === "string")
+                return block.thinking;
+            if (typeof block.text === "string")
+                return block.text;
+        }
+        if (block.type === "reasoning" && typeof block.text === "string") {
+            return block.text;
+        }
+        return "";
+    })
+        .filter((part) => part.trim().length > 0)
+        .join("\n")
+        .trim();
+}
 function buildArguments(request) {
     const args = ["--mode", "rpc", "--no-approve"];
     if (request.session) {
@@ -257,10 +278,13 @@ export async function runPiAgent(request, options = {}) {
                         fail(new Error("Pi completed without a textual final response"));
                         return;
                     }
+                    const thinking = collectThinking(finalMessage.content);
                     const result = {
                         text,
                         provider: finalMessage.provider,
                         model: finalMessage.model,
+                        stopReason: finalMessage.stopReason,
+                        ...(thinking ? { thinking } : {}),
                     };
                     finished = true;
                     clearTimeout(timer);

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.7",
+  "version": "0.2.9",
   "description": "A single-host bridge from messaging and schedules to isolated agent runs",
   "license": "Apache-2.0",
   "repository": {