@nettee/beacon 0.1.4 → 0.1.5

package/README.md

@@ -115,6 +115,38 @@ 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.
 
+## Feishu Final Outcome cards
+
+An Agent explicitly calls one of two Final Outcome tools:
+
+- `submit_final_outcome_text` sends a normal Feishu text message.
+- `submit_final_outcome_card` sends an interactive card.
+
+The card tool accepts 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:
+
+```json
+{ "text": "The task completed successfully." }
+```
+
+```json
+{
+  "title": "AMR 生产发布影响报告",
+  "content": "- XXL | CMS 活动生命周期、实时 Test 与生产 Campaign\n- XL | Astra 272K+ 长上下文费率",
+  "buttons": [
+    { "label": "查看 HTML 报告", "url": "https://example.com/report" },
+    { "label": "查看 GitHub Compare", "url": "https://github.com/example/compare" }
+  ]
+}
+```
+
+The selected form is stored durably as part of the Final Outcome. Both quoted
+message replies and scheduled chat messages preserve that choice: text remains
+text, while cards are sent with Feishu's `interactive` message type and include
+the card generation time. Manual local triggers render card outcomes as
+readable Markdown on stdout.
+
 ## State and failure behavior
 
 Per-Profile state lives below `profiles/<profile-id>/state/`. Trigger claims, normalized inputs, Run state, Final Outcomes, Delivery state, and Schedule cursors use durable JSON snapshots. Records do not expire, and Beacon has no automatic cleanup task. Manually deleting state also deletes its deduplication memory.

package/dist/feishu/final-outcome-card.js

@@ -0,0 +1,53 @@
+function formatTimestamp(date, timeZone) {
+    if (Number.isNaN(date.getTime())) {
+        throw new Error("Final Outcome card timestamp must be a valid Date");
+    }
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        ...(timeZone ? { timeZone } : {}),
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+    }).formatToParts(date);
+    const value = (type) => {
+        const part = parts.find((candidate) => candidate.type === type)?.value;
+        if (!part)
+            throw new Error(`Missing ${type} in formatted card timestamp`);
+        return part;
+    };
+    return `${value("year")}-${value("month")}-${value("day")} ${value("hour")}:${value("minute")}:${value("second")}`;
+}
+export function buildFeishuFinalOutcomeCard(outcome, options = {}) {
+    const elements = [{ tag: "markdown", content: outcome.content }];
+    if (outcome.buttons.length > 0) {
+        elements.push({ tag: "hr" }, {
+            tag: "action",
+            actions: outcome.buttons.map((button, index) => ({
+                tag: "button",
+                text: { tag: "plain_text", content: button.label },
+                url: button.url,
+                type: index === 0 ? "primary" : "default",
+            })),
+        });
+    }
+    elements.push({
+        tag: "note",
+        elements: [
+            {
+                tag: "plain_text",
+                content: `卡片生成时间：${formatTimestamp(options.generatedAt ?? new Date(), options.timeZone)}`,
+            },
+        ],
+    });
+    return {
+        config: { wide_screen_mode: true },
+        header: {
+            template: "blue",
+            title: { tag: "plain_text", content: outcome.title },
+        },
+        elements,
+    };
+}

package/dist/feishu/gateway.js

@@ -1,4 +1,5 @@
 import * as Lark from "@larksuiteoapi/node-sdk";
+import { buildFeishuFinalOutcomeCard } from "./final-outcome-card.js";
 export function waitForShutdown(signals = process) {
     return new Promise((resolve) => {
         const shutdown = () => {
@@ -20,8 +21,17 @@ function assertSucceeded(operation, result) {
         throw new Error(`${operation} failed: code=${result.code} msg=${result.msg ?? "unknown"}`);
     }
 }
-function textContent(text) {
-    return JSON.stringify({ text });
+export function encodeFeishuFinalOutcome(outcome) {
+    if (outcome.kind === "text") {
+        return {
+            msgType: "text",
+            content: JSON.stringify({ text: outcome.text }),
+        };
+    }
+    return {
+        msgType: "interactive",
+        content: JSON.stringify(buildFeishuFinalOutcomeCard(outcome)),
+    };
 }
 export class FeishuGateway {
     credentials;
@@ -96,13 +106,14 @@ export class FeishuGateway {
             parentMessageId: message.parent_id,
         };
     }
-    async deliver(target, text) {
+    async deliver(target, outcome) {
+        const message = encodeFeishuFinalOutcome(outcome);
         if (target.kind === "reply") {
             const result = await this.client.im.v1.message.reply({
                 path: { message_id: target.messageId },
                 data: {
-                    msg_type: "text",
-                    content: textContent(text),
+                    msg_type: message.msgType,
+                    content: message.content,
                     reply_in_thread: false,
                 },
             });
@@ -114,8 +125,8 @@ export class FeishuGateway {
                 params: { receive_id_type: "chat_id" },
                 data: {
                     receive_id: target.chatId,
-                    msg_type: "text",
-                    content: textContent(text),
+                    msg_type: message.msgType,
+                    content: message.content,
                 },
             });
             assertSucceeded("deliver chat message", result);

package/dist/manual-trigger.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
+import { renderFinalOutcomeAsText } from "./outcome/content.js";
 import { startOutcomeServer } from "./outcome/server.js";
 import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
 import { RunQueue } from "./run/queue.js";
@@ -27,11 +28,11 @@ export async function runManualTrigger(configPath, profileId, input, output = wr
             ingress: { text: input },
         });
         const delivery = {
-            async deliver(target, text) {
+            async deliver(target, outcome) {
                 if (target.kind !== "local_stdout") {
                     throw new Error("Manual Trigger requires local stdout Delivery");
                 }
-                await output(text);
+                await output(renderFinalOutcomeAsText(outcome));
                 return {};
             },
         };

package/dist/outcome/content.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+const nonBlank = z.string().refine((value) => value.trim().length > 0, {
+    message: "must not be blank",
+});
+const buttonSchema = z
+    .object({
+    label: nonBlank,
+    url: z
+        .url()
+        .refine((value) => value.startsWith("https://") || value.startsWith("http://"), "must use http or https"),
+})
+    .strict();
+export const finalOutcomeContentSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("text"), text: nonBlank }).strict(),
+    z
+        .object({
+        kind: z.literal("card"),
+        title: nonBlank,
+        content: nonBlank,
+        buttons: z.array(buttonSchema).max(5).default([]),
+    })
+        .strict(),
+]);
+export function parseFinalOutcomeContent(value) {
+    return finalOutcomeContentSchema.parse(value);
+}
+export function renderFinalOutcomeAsText(outcome) {
+    if (outcome.kind === "text")
+        return outcome.text;
+    return [
+        `# ${outcome.title}`,
+        "",
+        outcome.content,
+        ...outcome.buttons.map((button) => `\n[${button.label}](${button.url})`),
+    ].join("\n");
+}

package/dist/outcome/doctor.js

@@ -18,7 +18,7 @@ export async function runOutcomeDoctor(profileId) {
     const beaconCliPath = fileURLToPath(new URL("../../dist/cli.js", import.meta.url));
     try {
         const result = await createProfileRunner(profile, outcomes, beaconCliPath)(doctorTrigger);
-        if (result.trim() !== "OUTCOME_CLI_OK") {
+        if (result.kind !== "text" || result.text.trim() !== "OUTCOME_CLI_OK") {
             throw new Error(`Outcome doctor received unexpected submitted text: ${JSON.stringify(result)}`);
         }
         console.log("[beacon] explicit Final Outcome chain ready");

package/dist/outcome/instructions.js

@@ -0,0 +1,5 @@
+export const finalOutcomeSystemInstructions = [
+    "When your work is complete, call exactly one of submit_final_outcome_text or submit_final_outcome_card with the exact user-facing response.",
+    "Use submit_final_outcome_text for a normal response, or submit_final_outcome_card when a titled Markdown summary and link buttons materially improve the result.",
+    "Beacon ignores ordinary assistant final text for Delivery.",
+];

package/dist/outcome/server.js

@@ -3,6 +3,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { parseFinalOutcomeContent } from "./content.js";
 function respond(socket, response) {
     socket.end(`${JSON.stringify(response)}\n`);
 }
@@ -45,13 +46,22 @@ export async function startOutcomeServer(options = {}) {
             if (typeof request !== "object" ||
                 request === null ||
                 !("runToken" in request) ||
-                !("text" in request) ||
-                typeof request.runToken !== "string" ||
-                typeof request.text !== "string" ||
-                !request.text.trim()) {
+                !("outcome" in request) ||
+                typeof request.runToken !== "string") {
                 respond(socket, {
                     ok: false,
-                    error: "runToken and non-empty text are required",
+                    error: "runToken and outcome are required",
+                });
+                return;
+            }
+            let outcome;
+            try {
+                outcome = parseFinalOutcomeContent(request.outcome);
+            }
+            catch (error) {
+                respond(socket, {
+                    ok: false,
+                    error: `invalid Final Outcome: ${error instanceof Error ? error.message : String(error)}`,
                 });
                 return;
             }
@@ -60,14 +70,14 @@ export async function startOutcomeServer(options = {}) {
                 respond(socket, { ok: false, error: "unknown Run Capability" });
                 return;
             }
-            if (submission.text !== undefined) {
+            if (submission.outcome !== undefined) {
                 respond(socket, {
                     ok: false,
                     error: "Final Outcome already submitted",
                 });
                 return;
             }
-            submission.text = request.text;
+            submission.outcome = outcome;
             console.log("[beacon] Final Outcome submitted by Agent Runtime");
             respond(socket, { ok: true });
         });
@@ -88,10 +98,10 @@ export async function startOutcomeServer(options = {}) {
                 binding: { socketPath, runToken },
                 take() {
                     submissions.delete(runToken);
-                    if (record.text === undefined) {
+                    if (record.outcome === undefined) {
                         throw new Error("Agent Runtime settled without submitting a Final Outcome");
                     }
-                    return record.text;
+                    return record.outcome;
                 },
                 cancel() {
                     submissions.delete(runToken);

package/dist/outcome/submit.js

@@ -1,13 +1,13 @@
 import { createConnection } from "node:net";
-export async function submitOutcome(socketPath, runToken, text) {
-    if (!text.trim())
-        throw new Error("Final Outcome must not be empty");
+import { parseFinalOutcomeContent } from "./content.js";
+export async function submitOutcome(socketPath, runToken, outcome) {
+    const validatedOutcome = parseFinalOutcomeContent(outcome);
     await new Promise((resolve, reject) => {
         const socket = createConnection(socketPath);
         socket.setEncoding("utf8");
         let responseBuffer = "";
         socket.once("connect", () => {
-            socket.write(`${JSON.stringify({ runToken, text })}\n`);
+            socket.write(`${JSON.stringify({ runToken, outcome: validatedOutcome })}\n`);
         });
         socket.on("data", (chunk) => {
             responseBuffer += chunk;
@@ -39,9 +39,18 @@ export async function submitOutcomeFromCli() {
         throw new Error("This command must run inside a Beacon-managed Agent Run");
     }
     process.stdin.setEncoding("utf8");
-    let text = "";
+    let input = "";
     for await (const chunk of process.stdin)
-        text += chunk;
-    await submitOutcome(socketPath, runToken, text);
+        input += chunk;
+    let outcome;
+    try {
+        outcome = parseFinalOutcomeContent(JSON.parse(input));
+    }
+    catch (error) {
+        throw new Error("Final Outcome stdin must be valid outcome JSON", {
+            cause: error,
+        });
+    }
+    await submitOutcome(socketPath, runToken, outcome);
     console.log("Final Outcome accepted by Beacon");
 }

package/dist/run/orchestrator.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isAbsolute, join } from "node:path";
+import { finalOutcomeSystemInstructions } from "../outcome/instructions.js";
 import { PiRuntimeError } from "../runtime/pi-rpc.js";
 function promptFor(input) {
     if (input.kind === "manual") {
@@ -98,7 +99,7 @@ export class RunOrchestrator {
             },
         }));
         try {
-            const result = await this.options.delivery.deliver(record.target, record.finalOutcome.text, record.delivery.deliveryId);
+            const result = await this.options.delivery.deliver(record.target, record.finalOutcome.content, record.delivery.deliveryId);
             await this.options.store.update(triggerKey, (current) => ({
                 ...current,
                 delivery: {
@@ -135,7 +136,10 @@ export class RunOrchestrator {
             },
             finalOutcome: {
                 origin: "beacon_failure",
-                text: `处理失败（run_id=${runId}），请查看 Beacon 本地记录。`,
+                content: {
+                    kind: "text",
+                    text: `处理失败（run_id=${runId}），请查看 Beacon 本地记录。`,
+                },
                 submittedAt: this.timestamp(),
             },
         }));
@@ -180,8 +184,7 @@ export class RunOrchestrator {
                 systemPrompt: [
                     this.options.profile.prompt,
                     "",
-                    "When your work is complete, call submit_final_outcome exactly once with the exact user-facing response.",
-                    "Beacon ignores ordinary assistant final text for Delivery.",
+                    ...finalOutcomeSystemInstructions,
                 ].join("\n"),
                 outcome: { ...submission.binding, cliPath: this.options.beaconCliPath },
                 session: {
@@ -202,7 +205,7 @@ export class RunOrchestrator {
                 },
                 finalOutcome: {
                     origin: "agent",
-                    text: outcome,
+                    content: outcome,
                     submittedAt: this.timestamp(),
                 },
             }));
@@ -234,7 +237,10 @@ export class RunOrchestrator {
                 }),
                 finalOutcome: {
                     origin: "beacon_failure",
-                    text: `处理失败（run_id=${runId}），请查看 Beacon 本地记录。`,
+                    content: {
+                        kind: "text",
+                        text: `处理失败（run_id=${runId}），请查看 Beacon 本地记录。`,
+                    },
                     submittedAt: this.timestamp(),
                 },
             }));

package/dist/run/profile-runner.js

@@ -1,3 +1,4 @@
+import { finalOutcomeSystemInstructions } from "../outcome/instructions.js";
 import { runPiAgent, } from "../runtime/pi-rpc.js";
 function messageForPrompt(message) {
     return {
@@ -29,8 +30,7 @@ export function createProfileRunner(profile, outcomes, beaconCliPath, runAgent =
             systemPrompt: [
                 profile.prompt,
                 "",
-                "When your work is complete, you must call the submit_final_outcome tool exactly once with the exact user-facing response.",
-                "Beacon ignores your final assistant response for Delivery; only the submitted text is delivered.",
+                ...finalOutcomeSystemInstructions,
             ].join("\n"),
             outcome: { ...submission.binding, cliPath: beaconCliPath },
         });

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

@@ -1,5 +1,17 @@
 import { spawn } from "node:child_process";
-async function invokeBeaconCli(text, signal) {
+import { parseFinalOutcomeContent } from "../outcome/content.js";
+export function textOutcomeFromToolParams(params) {
+    return parseFinalOutcomeContent({ kind: "text", text: params.text });
+}
+export function cardOutcomeFromToolParams(params) {
+    return parseFinalOutcomeContent({
+        kind: "card",
+        title: params.title,
+        content: params.content,
+        buttons: params.buttons ?? [],
+    });
+}
+async function invokeBeaconCli(outcome, signal) {
     const cliPath = process.env.BEACON_CLI_PATH;
     if (!cliPath)
         throw new Error("BEACON_CLI_PATH is missing from this Agent Run");
@@ -22,32 +34,74 @@ async function invokeBeaconCli(text, signal) {
             }
             reject(new Error(`beacon outcome submit failed (code=${String(code)} signal=${String(exitSignal)}): ${stderr.trim()}`));
         });
-        child.stdin.end(text);
+        child.stdin.end(JSON.stringify(outcome));
     });
 }
-export default function registerOutcomeTool(pi) {
+function acceptedResult() {
+    return {
+        content: [{ type: "text", text: "Final Outcome accepted by Beacon." }],
+        details: { submitted: true },
+    };
+}
+export default function registerOutcomeTools(pi) {
     pi.registerTool({
-        name: "submit_final_outcome",
-        label: "Submit Final Outcome",
-        description: "Submit the exact final response that Beacon must deliver to the user. Call this once after completing the task.",
+        name: "submit_final_outcome_text",
+        label: "Submit Final Outcome Text",
+        description: "Submit the final response as a normal text message. Call either this tool or submit_final_outcome_card exactly once after completing the task.",
         parameters: {
             type: "object",
             properties: {
                 text: {
                     type: "string",
                     minLength: 1,
-                    description: "The complete user-facing final response.",
+                    description: "The complete user-facing plain-text response.",
                 },
             },
             required: ["text"],
             additionalProperties: false,
         },
         async execute(_toolCallId, params, signal) {
-            await invokeBeaconCli(params.text, signal);
-            return {
-                content: [{ type: "text", text: "Final Outcome accepted by Beacon." }],
-                details: { submitted: true },
-            };
+            await invokeBeaconCli(textOutcomeFromToolParams(params), signal);
+            return acceptedResult();
+        },
+    });
+    pi.registerTool({
+        name: "submit_final_outcome_card",
+        label: "Submit Final Outcome Card",
+        description: "Submit the final response as a structured Feishu card. Call either this tool or submit_final_outcome_text exactly once after completing the task.",
+        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(cardOutcomeFromToolParams(params), signal);
+            return acceptedResult();
         },
     });
 }

package/dist/state/trigger-store.js

@@ -3,6 +3,7 @@ import { chmod, mkdir, open, readdir, readFile, rename, } from "node:fs/promises
 import { basename, dirname, isAbsolute, join } from "node:path";
 import { z } from "zod";
 import { failureCodes, } from "../domain/types.js";
+import { finalOutcomeContentSchema } from "../outcome/content.js";
 const timestamp = z.string().datetime({ offset: true });
 const failureSchema = z
     .object({ code: z.enum(failureCodes), summary: z.string().min(1).max(4096) })
@@ -64,13 +65,27 @@ const runSchema = z
     failure: failureSchema.optional(),
 })
     .strict();
-const outcomeSchema = z
-    .object({
-    origin: z.enum(["agent", "beacon_failure"]),
-    text: z.string().min(1),
-    submittedAt: timestamp,
-})
-    .strict();
+const outcomeSchema = z.union([
+    z
+        .object({
+        origin: z.enum(["agent", "beacon_failure"]),
+        content: finalOutcomeContentSchema,
+        submittedAt: timestamp,
+    })
+        .strict(),
+    z
+        .object({
+        origin: z.enum(["agent", "beacon_failure"]),
+        text: z.string().min(1),
+        submittedAt: timestamp,
+    })
+        .strict()
+        .transform(({ origin, text, submittedAt }) => ({
+        origin,
+        content: { kind: "text", text },
+        submittedAt,
+    })),
+]);
 const deliverySchema = z
     .object({
     deliveryId: z.string().min(1),

package/package.json

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