@nettee/beacon 0.1.3 → 0.1.5

package/README.md

@@ -31,10 +31,11 @@ Upgrade to the current stable release with the same `latest` command. Run
 service. Beacon does not manage launchd installation, restart, or rollback in
 this release.
 
-Beacon only accepts an absolute path for the global configuration:
+Operator commands find the standard Beacon home automatically; a service
+deployment names its configuration explicitly:
 
 ```sh
-beacon doctor --config /Users/USERNAME/.beacon/config.yaml
+beacon doctor
 beacon serve --config /Users/USERNAME/.beacon/config.yaml
 ```
 
@@ -83,18 +84,69 @@ Each Schedule uses a five-field cron expression and an IANA timezone. Its `deliv
 
 ```text
 beacon serve --config <absolute-path>
-beacon doctor --config <absolute-path>
-beacon trigger --config <absolute-path> --profile <id> --input -
+beacon doctor [--config <absolute-path>]
+beacon trigger [--config <absolute-path>] --profile <id> --input -
+beacon schedule trigger [--config <absolute-path>] --profile <id> --schedule <id>
 beacon version
 ```
 
+Operator commands use `~/.beacon/config.yaml` when `--config` is omitted.
+An explicit override must still be an absolute path. `serve` keeps requiring an
+explicit absolute config path so service definitions identify their deployment
+configuration unambiguously.
+
 An operator can run one Profile without Feishu delivery by piping input to `trigger`; the Final Outcome is printed to stdout:
 
 ```sh
 printf '%s\n' 'Summarize the workspace status.' | \
-  beacon trigger --config /Users/USERNAME/.beacon/config.yaml --profile example --input -
+  beacon trigger --profile example --input -
+```
+
+An operator can also immediately run a configured Schedule through the real
+Schedule input and Feishu chat Delivery path:
+
+```sh
+beacon schedule trigger --profile example --schedule daily-report
 ```
 
+This creates a distinct durable Run on every invocation and prints its
+`run_id`. It uses the Schedule's configured `input` and `delivery.chat_id`, but
+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.
@@ -143,6 +195,12 @@ launchctl print gui/$(id -u)/io.nettee.beacon
 
 The example uses a restrictive umask and asks launchd to restart only after abnormal exit. `SIGTERM` initiates an orderly shutdown: timers and Gateways stop, accepted intake work drains, and the local Outcome server closes.
 
+The repository also contains Chinese operator runbooks based on the verified
+`macmini.liuyi` deployment:
+
+- [Deploy or update Beacon on macmini](docs/macmini-deploy-and-update.md)
+- [Add a Beacon Profile on macmini](docs/macmini-add-profile.md)
+
 ## Development checks
 
 Development requires pnpm 10.33.2. Install dependencies before running checks

package/dist/cli-app.js

@@ -1,18 +1,40 @@
-import { isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+export const defaultConfigPath = join(homedir(), ".beacon", "config.yaml");
 function usage() {
     throw new Error(`Usage:
   beacon serve --config <absolute-path>
-  beacon doctor --config <absolute-path>
-  beacon trigger --config <absolute-path> --profile <id> --input -
+  beacon doctor [--config <absolute-path>]
+  beacon trigger [--config <absolute-path>] --profile <id> --input -
+  beacon schedule trigger [--config <absolute-path>] --profile <id> --schedule <id>
   beacon version`);
 }
-function configOnly(args) {
+function requiredConfig(args) {
     if (args.length !== 2 || args[0] !== "--config" || !args[1])
         usage();
     if (!isAbsolute(args[1]))
         throw new Error("Config path must be absolute");
     return args[1];
 }
+function options(args) {
+    if (args.length % 2 !== 0)
+        usage();
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 2) {
+        const key = args[index];
+        const value = args[index + 1];
+        if (!key?.startsWith("--") || !value || values.has(key))
+            usage();
+        values.set(key, value);
+    }
+    return values;
+}
+function optionalConfig(values) {
+    const config = values.get("--config") ?? defaultConfigPath;
+    if (!isAbsolute(config))
+        throw new Error("Config path must be absolute");
+    return config;
+}
 export function parseCli(args) {
     const [command, ...rest] = args;
     if (command === "version") {
@@ -20,30 +42,38 @@ export function parseCli(args) {
             usage();
         return { command: "version" };
     }
-    if (command === "serve" || command === "doctor") {
-        return { command, config: configOnly(rest) };
+    if (command === "serve") {
+        return { command, config: requiredConfig(rest) };
     }
-    if (command === "trigger") {
-        if (rest.length !== 6)
+    if (command === "doctor") {
+        const values = options(rest);
+        if ([...values.keys()].some((key) => key !== "--config"))
             usage();
-        const values = new Map();
-        for (let index = 0; index < rest.length; index += 2) {
-            const key = rest[index];
-            const value = rest[index + 1];
-            if (!key?.startsWith("--") || !value || values.has(key))
-                usage();
-            values.set(key, value);
-        }
-        const config = values.get("--config");
+        return { command, config: optionalConfig(values) };
+    }
+    if (command === "trigger") {
+        const values = options(rest);
         const profile = values.get("--profile");
-        if (!config ||
-            !profile ||
+        if (!profile ||
             values.get("--input") !== "-" ||
-            values.size !== 3)
+            [...values.keys()].some((key) => !["--config", "--profile", "--input"].includes(key)))
+            usage();
+        return { command: "trigger", config: optionalConfig(values), profile };
+    }
+    if (command === "schedule" && rest[0] === "trigger") {
+        const values = options(rest.slice(1));
+        const profile = values.get("--profile");
+        const schedule = values.get("--schedule");
+        if (!profile ||
+            !schedule ||
+            [...values.keys()].some((key) => !["--config", "--profile", "--schedule"].includes(key)))
             usage();
-        if (!isAbsolute(config))
-            throw new Error("Config path must be absolute");
-        return { command: "trigger", config, profile };
+        return {
+            command: "schedule-trigger",
+            config: optionalConfig(values),
+            profile,
+            schedule,
+        };
     }
     if (command === "outcome" && rest.length === 1 && rest[0] === "submit") {
         return { command: "outcome-submit" };
@@ -65,6 +95,9 @@ export async function runCli(command, dependencies) {
     if (command.command === "trigger") {
         return dependencies.trigger(command.config, command.profile, await readStdin());
     }
+    if (command.command === "schedule-trigger") {
+        return dependencies.triggerSchedule(command.config, command.profile, command.schedule);
+    }
     if (command.command === "outcome-submit")
         return dependencies.submitOutcome();
     console.log(dependencies.version);

package/dist/cli.js

@@ -3,6 +3,7 @@ import { parseCli, runCli } from "./cli-app.js";
 import { runDoctor } from "./doctor.js";
 import { runManualTrigger } from "./manual-trigger.js";
 import { submitOutcomeFromCli } from "./outcome/submit.js";
+import { runScheduleTrigger } from "./schedule-trigger.js";
 import { runBeacon } from "./service.js";
 import { packageVersion } from "./version.js";
 async function main() {
@@ -10,6 +11,7 @@ async function main() {
         serve: runBeacon,
         doctor: runDoctor,
         trigger: runManualTrigger,
+        triggerSchedule: runScheduleTrigger,
         submitOutcome: submitOutcomeFromCli,
         version: packageVersion,
     });

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/schedule-trigger.js

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { loadGlobalConfig } from "./config/global.js";
+import { loadProfileRegistry } from "./config/registry.js";
+import { loadFeishuCredentials } from "./config/secrets.js";
+import { createFeishuGateway } from "./feishu/gateway.js";
+import { startOutcomeServer } from "./outcome/server.js";
+import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
+import { RunQueue } from "./run/queue.js";
+import { TriggerStore } from "./state/trigger-store.js";
+function findSchedule(profile, scheduleId) {
+    const schedule = profile.schedules.find((candidate) => candidate.id === scheduleId);
+    if (!schedule) {
+        throw new Error(`Unknown Schedule in Profile ${profile.id}: ${scheduleId}`);
+    }
+    return schedule;
+}
+export async function triggerScheduleOnce(options) {
+    const schedule = findSchedule(options.profile, options.scheduleId);
+    const scheduledFor = (options.now ?? (() => new Date()))().toISOString();
+    const invocationId = (options.id ?? randomUUID)();
+    const claim = await options.store.claim({
+        sourceKey: ["manual-schedule", schedule.id, invocationId],
+        target: { kind: "chat", chatId: schedule.delivery.chatId },
+        ingress: {
+            invocation: "manual",
+            scheduleId: schedule.id,
+            scheduledFor,
+            text: schedule.input,
+        },
+    });
+    if (!claim.created) {
+        throw new Error(`Duplicate manual Schedule invocation: ${invocationId}`);
+    }
+    await options.process(claim.record.triggerKey, async () => ({
+        kind: "schedule",
+        scheduleId: schedule.id,
+        scheduledFor,
+        text: schedule.input,
+    }));
+    const record = (await options.store.list()).find((candidate) => candidate.triggerKey === claim.record.triggerKey);
+    if (!record?.run) {
+        throw new Error(`Schedule Trigger produced no Run record: trigger_id=${claim.record.triggerId}`);
+    }
+    if (record.run.state !== "succeeded" ||
+        record.delivery?.state !== "delivered") {
+        const failure = record.run.failure?.code ?? record.delivery?.failure?.code ?? "unknown";
+        throw new Error(`Schedule Trigger failed (run_id=${record.run.runId}): ${failure}`);
+    }
+    return record;
+}
+export async function runScheduleTrigger(configPath, profileId, scheduleId) {
+    const global = await loadGlobalConfig(configPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const profile = profiles.find((candidate) => candidate.id === profileId);
+    if (!profile)
+        throw new Error(`Unknown Profile: ${profileId}`);
+    findSchedule(profile, scheduleId);
+    const credentials = await loadFeishuCredentials(profile.id, global.secretsPath);
+    const outcomes = await startOutcomeServer();
+    try {
+        const store = new TriggerStore(profile.directory, profile.id);
+        const orchestrator = createPiRunOrchestrator({
+            config: global,
+            profile,
+            store,
+            queue: new RunQueue(global.runs.maxConcurrent, global.runs.maxQueued),
+            outcomes,
+            delivery: createFeishuGateway(credentials),
+        });
+        const record = await triggerScheduleOnce({
+            profile,
+            scheduleId,
+            store,
+            process: (triggerKey, normalize) => orchestrator.process(triggerKey, normalize),
+        });
+        console.log(`[beacon] Schedule Trigger succeeded run_id=${record.run.runId}`);
+    }
+    finally {
+        await outcomes.close();
+    }
+}

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