@nettee/beacon 0.4.2 → 0.4.3

package/README.md

@@ -68,7 +68,8 @@ 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 event vs manual capabilities, the `reply_text` / `reply_card` /
-`no_reply` / `notify_card` contract, and an optional `submit_feedback` tool.
+`no_reply` / `notify_card` contract, optional `submit_feedback` (instruction gaps),
+and optional `submit_observability_feedback` (RCA observability gaps).
 
 Protect the home and secret file before running Beacon:
 

package/dist/daemon/dashboard/records.d.ts

@@ -1,5 +1,5 @@
 import type { RunRow } from "@nettee/beacon-shared";
-import type { FeedbackRecord } from "../domain/types.js";
+import type { FeedbackRecord, ObservabilityFeedbackRecord } from "../domain/types.js";
 export declare const runIdPattern: RegExp;
 export type RunSummary = {
     profileId: string;
@@ -18,6 +18,7 @@ export type RunSummary = {
     hasSessionFile: boolean;
     systemPrompt: string | undefined;
     feedback: FeedbackRecord | undefined;
+    observabilityFeedback: ObservabilityFeedbackRecord | undefined;
 };
 export declare function listRunSummaries(profilesDirectory: string): Promise<RunSummary[]>;
 export declare function kindLabel(row: Pick<RunSummary, "kind" | "scheduleId" | "eventSource" | "eventType">): string;

package/dist/daemon/dashboard/records.js

@@ -1,6 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { feedbackRecordSchema } from "../outcome/content.js";
+import { feedbackRecordSchema, observabilityFeedbackRecordSchema, } from "../outcome/content.js";
 export const runIdPattern = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 function asRecord(value) {
     return typeof value === "object" && value !== null
@@ -14,6 +14,10 @@ function asFeedback(value) {
     const parsed = feedbackRecordSchema.safeParse(value);
     return parsed.success ? parsed.data : undefined;
 }
+function asObservabilityFeedback(value) {
+    const parsed = observabilityFeedbackRecordSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
 async function readDirents(path) {
     try {
         return await readdir(path, { withFileTypes: true });
@@ -61,6 +65,7 @@ function summarize(value, hasSessionFile) {
         hasSessionFile,
         systemPrompt: asString(run?.systemPrompt),
         feedback: asFeedback(record.feedback),
+        observabilityFeedback: asObservabilityFeedback(record.observabilityFeedback),
     };
 }
 async function loadSummary(path) {
@@ -126,6 +131,12 @@ export function toRunListItem(row) {
                 summary: item.summary,
             }))
             : null,
+        observabilityFeedback: row.observabilityFeedback && row.observabilityFeedback.items.length > 0
+            ? row.observabilityFeedback.items.map((item) => ({
+                priority: item.priority,
+                summary: item.summary,
+            }))
+            : null,
     };
 }
 export async function findRunSummary(profilesDirectory, runId) {

package/dist/daemon/domain/types.d.ts

@@ -84,6 +84,20 @@ export type FeedbackRecord = {
     items: FeedbackItem[];
     submittedAt: string;
 };
+/** Observability-gap feedback may include low; instruction feedback may not. */
+export declare const observabilityFeedbackPriorities: readonly ["high", "medium", "low"];
+export type ObservabilityFeedbackPriority = (typeof observabilityFeedbackPriorities)[number];
+export type ObservabilityFeedbackItem = {
+    priority: ObservabilityFeedbackPriority;
+    summary: string;
+};
+export type ObservabilityFeedbackContent = {
+    items: ObservabilityFeedbackItem[];
+};
+export type ObservabilityFeedbackRecord = {
+    items: ObservabilityFeedbackItem[];
+    submittedAt: string;
+};
 export type DeliveryContent = TextReplyContent | CardContent;
 export type RunRecord = {
     runId: string;
@@ -132,6 +146,8 @@ export type TriggerRecord = {
     finalOutcome?: FinalOutcomeRecord | undefined;
     /** Present only when the Agent called `submit_feedback`. */
     feedback?: FeedbackRecord | undefined;
+    /** Present only when the Agent called `submit_observability_feedback`. */
+    observabilityFeedback?: ObservabilityFeedbackRecord | undefined;
     delivery?: DeliveryRecord | undefined;
     notifyDelivery?: DeliveryRecord | undefined;
 };

package/dist/daemon/domain/types.js

@@ -17,3 +17,9 @@ export const failureCodes = [
     "delivery_interrupted",
 ];
 export const feedbackPriorities = ["high", "medium"];
+/** Observability-gap feedback may include low; instruction feedback may not. */
+export const observabilityFeedbackPriorities = [
+    "high",
+    "medium",
+    "low",
+];

package/dist/daemon/outcome/content.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { CardContent, DeliveryContent, FeedbackContent, FinalOutcomeContent, ReplyContent } from "../domain/types.js";
+import type { CardContent, DeliveryContent, FeedbackContent, FinalOutcomeContent, ObservabilityFeedbackContent, ReplyContent } from "../domain/types.js";
 export declare const feedbackItemSchema: z.ZodObject<{
     priority: z.ZodEnum<{
         high: "high";
@@ -26,6 +26,35 @@ export declare const feedbackRecordSchema: z.ZodObject<{
     }, z.core.$strict>>;
     submittedAt: z.ZodString;
 }, z.core.$strict>;
+export declare const observabilityFeedbackItemSchema: z.ZodObject<{
+    priority: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    summary: z.ZodString;
+}, z.core.$strict>;
+export declare const observabilityFeedbackContentSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        priority: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        summary: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const observabilityFeedbackRecordSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        priority: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        summary: z.ZodString;
+    }, z.core.$strict>>;
+    submittedAt: z.ZodString;
+}, z.core.$strict>;
 export declare const finalOutcomeContentSchema: z.ZodObject<{
     reply: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"text">;
@@ -56,6 +85,7 @@ export type OutcomePatch = {
     reply?: ReplyContent | undefined;
     notify?: CardContent | undefined;
     feedback?: FeedbackContent | undefined;
+    observabilityFeedback?: ObservabilityFeedbackContent | undefined;
 };
 export declare function parseFinalOutcomeContent(value: unknown): FinalOutcomeContent;
 export declare function parseOutcomePatch(value: unknown): OutcomePatch;

package/dist/daemon/outcome/content.js

@@ -46,6 +46,23 @@ export const feedbackRecordSchema = z
     submittedAt: z.string().datetime({ offset: true }),
 })
     .strict();
+export const observabilityFeedbackItemSchema = z
+    .object({
+    priority: z.enum(["high", "medium", "low"]),
+    summary: nonBlank.max(1024),
+})
+    .strict();
+export const observabilityFeedbackContentSchema = z
+    .object({
+    items: z.array(observabilityFeedbackItemSchema).min(1).max(3),
+})
+    .strict();
+export const observabilityFeedbackRecordSchema = z
+    .object({
+    items: z.array(observabilityFeedbackItemSchema).min(1).max(3),
+    submittedAt: z.string().datetime({ offset: true }),
+})
+    .strict();
 export const finalOutcomeContentSchema = z
     .object({
     reply: replySchema,
@@ -57,12 +74,14 @@ const outcomePatchSchema = z
     reply: replySchema.optional(),
     notify: cardSchema.optional(),
     feedback: feedbackContentSchema.optional(),
+    observabilityFeedback: observabilityFeedbackContentSchema.optional(),
 })
     .strict()
     .refine((value) => value.reply !== undefined ||
     value.notify !== undefined ||
-    value.feedback !== undefined, {
-    message: "Outcome submission must include reply, notify, or feedback",
+    value.feedback !== undefined ||
+    value.observabilityFeedback !== undefined, {
+    message: "Outcome submission must include reply, notify, feedback, or observabilityFeedback",
 });
 const legacyOutcomeSchema = z.discriminatedUnion("kind", [
     textReplySchema,
@@ -106,6 +125,9 @@ export function mergeOutcome(current, patch) {
     if (patch.feedback && current?.feedback) {
         throw new Error("Feedback already submitted");
     }
+    if (patch.observabilityFeedback && current?.observabilityFeedback) {
+        throw new Error("Observability feedback already submitted");
+    }
     return {
         ...(current?.reply || patch.reply
             ? { reply: patch.reply ?? current?.reply }
@@ -116,6 +138,11 @@ export function mergeOutcome(current, patch) {
         ...(current?.feedback || patch.feedback
             ? { feedback: patch.feedback ?? current?.feedback }
             : {}),
+        ...(current?.observabilityFeedback || patch.observabilityFeedback
+            ? {
+                observabilityFeedback: patch.observabilityFeedback ?? current?.observabilityFeedback,
+            }
+            : {}),
     };
 }
 /** Stable English summary when the Agent settles without closing reply/no_reply. */

package/dist/daemon/outcome/instructions.d.ts

@@ -1,3 +1,4 @@
 export declare const inboundOutOfRoleReply = "\u8FD9\u6761\u6D88\u606F\u4E0D\u5728\u6211\u7684\u804C\u8D23\u8303\u56F4\u5185\u3002";
 export declare const finalOutcomeContractInstructions: readonly ["`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 this Run'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 declare const feedbackContractInstructions: readonly ["If this Run had a real high or medium problem with instructions, Skills, dependencies, or tools, you may call `submit_feedback` once with one to three items.", "If there are none, do not call it. Do not invent items. Do not report low-priority issues, taste, or problems you already worked around without needing a platform change."];
+export declare const feedbackContractInstructions: readonly ["If this Run had a real high or medium problem with instructions, Skills, dependencies, or tools, you may call `submit_feedback` once with one to three items.", "If there are none, do not call it. Do not invent items. Do not report low-priority issues, taste, or problems you already worked around without needing a platform change.", "Do not put observability gaps in `submit_feedback`. Use `submit_observability_feedback` for those."];
+export declare const observabilityFeedbackContractInstructions: readonly ["If root-cause analysis on this Run was held back by missing observability (logs, metrics, traces, event correlation, or similar signals), you may call `submit_observability_feedback` once with one to three items at high, medium, or low priority.", "Say what signal is missing and how adding it would make RCA more useful or more certain. If there are none, do not call it. Do not invent items.", "Do not put instruction, Skill, dependency, or tool problems in `submit_observability_feedback`. Use `submit_feedback` for those."];

package/dist/daemon/outcome/instructions.js

@@ -10,4 +10,10 @@ export const finalOutcomeContractInstructions = [
 export const feedbackContractInstructions = [
     "If this Run had a real high or medium problem with instructions, Skills, dependencies, or tools, you may call `submit_feedback` once with one to three items.",
     "If there are none, do not call it. Do not invent items. Do not report low-priority issues, taste, or problems you already worked around without needing a platform change.",
+    "Do not put observability gaps in `submit_feedback`. Use `submit_observability_feedback` for those.",
+];
+export const observabilityFeedbackContractInstructions = [
+    "If root-cause analysis on this Run was held back by missing observability (logs, metrics, traces, event correlation, or similar signals), you may call `submit_observability_feedback` once with one to three items at high, medium, or low priority.",
+    "Say what signal is missing and how adding it would make RCA more useful or more certain. If there are none, do not call it. Do not invent items.",
+    "Do not put instruction, Skill, dependency, or tool problems in `submit_observability_feedback`. Use `submit_feedback` for those.",
 ];

package/dist/daemon/outcome/server.d.ts

@@ -1,4 +1,4 @@
-import type { FeedbackRecord, FinalOutcomeContent } from "../domain/types.js";
+import type { FeedbackRecord, FinalOutcomeContent, ObservabilityFeedbackRecord } from "../domain/types.js";
 export type OutcomeBinding = {
     socketPath: string;
     runToken: string;
@@ -7,6 +7,7 @@ export type OutcomeSubmission = {
     binding: OutcomeBinding;
     take(): FinalOutcomeContent;
     takeFeedback(): FeedbackRecord | undefined;
+    takeObservabilityFeedback(): ObservabilityFeedbackRecord | undefined;
     cancel(): void;
 };
 export type OutcomeSink = {

package/dist/daemon/outcome/server.js

@@ -76,6 +76,10 @@ export async function startOutcomeServer(options = {}) {
                 if (patch.feedback && !previous?.feedback) {
                     submission.feedbackSubmittedAt = new Date().toISOString();
                 }
+                if (patch.observabilityFeedback && !previous?.observabilityFeedback) {
+                    submission.observabilityFeedbackSubmittedAt =
+                        new Date().toISOString();
+                }
             }
             catch (error) {
                 respond(socket, {
@@ -113,6 +117,16 @@ export async function startOutcomeServer(options = {}) {
                     }
                     return { items, submittedAt: record.feedbackSubmittedAt };
                 },
+                takeObservabilityFeedback() {
+                    const items = record.outcome?.observabilityFeedback?.items;
+                    if (!items || record.observabilityFeedbackSubmittedAt === undefined) {
+                        return undefined;
+                    }
+                    return {
+                        items,
+                        submittedAt: record.observabilityFeedbackSubmittedAt,
+                    };
+                },
                 cancel() {
                     submissions.delete(runToken);
                 },

package/dist/daemon/run/orchestrator.js

@@ -253,7 +253,7 @@ export class RunOrchestrator {
             await this.deliverField(triggerKey, "notifyDelivery", current.notifyTarget, outcome.notify, create && current.notifyDelivery === undefined);
         }
     }
-    async fail(triggerKey, runId, code, error, submitted, settle) {
+    async fail(triggerKey, runId, code, error, submitted, submittedObservability, settle) {
         let detail = isMissingReplyOutcomeError(error)
             ? MISSING_REPLY_OUTCOME_SUMMARY
             : summary(error);
@@ -278,6 +278,9 @@ export class RunOrchestrator {
                 submittedAt: this.timestamp(),
             },
             ...(submitted ? { feedback: submitted } : {}),
+            ...(submittedObservability
+                ? { observabilityFeedback: submittedObservability }
+                : {}),
         }));
         await this.deliverOutcome(triggerKey);
     }
@@ -336,6 +339,7 @@ export class RunOrchestrator {
                 text: completion.text,
             };
             const submitted = submission.takeFeedback();
+            const submittedObservability = submission.takeObservabilityFeedback();
             const outcome = normalizeAgentOutcome(input, submission.take(), record.notifyTarget);
             await this.options.store.update(triggerKey, (current) => ({
                 ...current,
@@ -352,18 +356,22 @@ export class RunOrchestrator {
                     submittedAt: this.timestamp(),
                 },
                 ...(submitted ? { feedback: submitted } : {}),
+                ...(submittedObservability
+                    ? { observabilityFeedback: submittedObservability }
+                    : {}),
             }));
             await this.deliverOutcome(triggerKey);
         }
         catch (error) {
             const submitted = submission.takeFeedback();
+            const submittedObservability = submission.takeObservabilityFeedback();
             submission.cancel();
             const code = error instanceof PiRuntimeError
                 ? error.code
                 : isMissingReplyOutcomeError(error)
                     ? "outcome_missing"
                     : "runtime_exit_failed";
-            await this.fail(triggerKey, runId, code, error, submitted, settle);
+            await this.fail(triggerKey, runId, code, error, submitted, submittedObservability, settle);
         }
     }
     async process(triggerKey, normalize) {

package/dist/daemon/runtime/pi-outcome-extension.d.ts

@@ -1,4 +1,4 @@
-import type { CardContent, FeedbackContent, FinalOutcomeContent } from "../domain/types.js";
+import type { CardContent, FeedbackContent, FinalOutcomeContent, ObservabilityFeedbackContent } from "../domain/types.js";
 type ToolResult = {
     content: Array<{
         type: "text";
@@ -25,6 +25,9 @@ export type CardOutcomeToolParams = {
 export type FeedbackToolParams = {
     items: FeedbackContent["items"];
 };
+export type ObservabilityFeedbackToolParams = {
+    items: ObservabilityFeedbackContent["items"];
+};
 type ExtensionApi = {
     registerTool<TParams>(tool: {
         name: string;
@@ -39,5 +42,6 @@ export declare function replyCardFromToolParams(params: CardOutcomeToolParams):
 export declare function noReplyFromToolParams(params: NoReplyOutcomeToolParams): FinalOutcomeContent;
 export declare function notifyCardFromToolParams(params: CardOutcomeToolParams): CardContent;
 export declare function feedbackFromToolParams(params: FeedbackToolParams): FeedbackContent;
+export declare function observabilityFeedbackFromToolParams(params: ObservabilityFeedbackToolParams): ObservabilityFeedbackContent;
 export default function registerOutcomeTools(pi: ExtensionApi): void;
 export {};

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

@@ -39,6 +39,15 @@ export function feedbackFromToolParams(params) {
         throw new Error("submit_feedback produced no items");
     return patch.feedback;
 }
+export function observabilityFeedbackFromToolParams(params) {
+    const patch = parseOutcomePatch({
+        observabilityFeedback: { items: params.items },
+    });
+    if (!patch.observabilityFeedback) {
+        throw new Error("submit_observability_feedback produced no items");
+    }
+    return patch.observabilityFeedback;
+}
 async function invokeBeaconCli(outcome, signal) {
     const cliPath = process.env.BEACON_CLI_PATH;
     if (!cliPath)
@@ -209,7 +218,7 @@ export default function registerOutcomeTools(pi) {
     pi.registerTool({
         name: "submit_feedback",
         label: "Submit Feedback",
-        description: "Optionally report one to three high or medium problems with instructions, Skills, dependencies, or tools on this Run. Call at most once, and only when such a problem actually existed. Do not call this tool when there is nothing to report.",
+        description: "Optionally report one to three high or medium problems with instructions, Skills, dependencies, or tools on this Run. Call at most once, and only when such a problem actually existed. Do not use this for missing observability — use submit_observability_feedback instead. Do not call this tool when there is nothing to report.",
         parameters: {
             type: "object",
             properties: {
@@ -249,4 +258,52 @@ export default function registerOutcomeTools(pi) {
             };
         },
     });
+    pi.registerTool({
+        name: "submit_observability_feedback",
+        label: "Submit Observability Feedback",
+        description: "Optionally report one to three observability gaps (missing logs, metrics, traces, or correlation signals) that held back root-cause analysis on this Run. Priority may be high, medium, or low. Call at most once, and only when such a gap actually existed. Do not use this for instruction/Skill/dependency/tool problems — use submit_feedback instead. Do not call this tool when there is nothing to report.",
+        parameters: {
+            type: "object",
+            properties: {
+                items: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 3,
+                    description: "One to three observability findings. Omit the tool call entirely when there are none.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            priority: {
+                                type: "string",
+                                enum: ["high", "medium", "low"],
+                                description: "high, medium, or low — how much the missing signal limited RCA confidence.",
+                            },
+                            summary: {
+                                type: "string",
+                                minLength: 1,
+                                maxLength: 1024,
+                                description: "One or two sentences naming the missing signal and how adding it would help RCA.",
+                            },
+                        },
+                        required: ["priority", "summary"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["items"],
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, params, signal) {
+            await invokeBeaconCli({ observabilityFeedback: { items: params.items } }, signal);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Observability feedback accepted by Beacon.",
+                    },
+                ],
+                details: { submitted: true },
+            };
+        },
+    });
 }

package/dist/daemon/runtime/system-prompt.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { feedbackContractInstructions, finalOutcomeContractInstructions, } from "../outcome/instructions.js";
+import { feedbackContractInstructions, finalOutcomeContractInstructions, observabilityFeedbackContractInstructions, } from "../outcome/instructions.js";
 export function agentSystemPromptTrigger(input, notifyTarget) {
     const notify = notifyTarget !== undefined;
     if (input?.kind === "event") {
@@ -30,6 +30,8 @@ export function buildAgentSystemPrompt(profile, trigger) {
         "",
         ...feedbackContractInstructions,
         "",
+        ...observabilityFeedbackContractInstructions,
+        "",
         profile.persona,
         "",
         profile.task,

package/dist/daemon/state/trigger-store.js

@@ -4,7 +4,7 @@ import { basename, dirname, isAbsolute, join } from "node:path";
 import { z } from "zod";
 import { failureCodes, } from "../domain/types.js";
 import { cloudEventSchema } from "../events/cloudevent.js";
-import { feedbackRecordSchema, finalOutcomeContentSchema, parseFinalOutcomeContent, } from "../outcome/content.js";
+import { feedbackRecordSchema, finalOutcomeContentSchema, observabilityFeedbackRecordSchema, parseFinalOutcomeContent, } 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) })
@@ -122,6 +122,7 @@ const triggerRecordSchema = z
     run: runSchema.optional(),
     finalOutcome: outcomeSchema.optional(),
     feedback: feedbackRecordSchema.optional(),
+    observabilityFeedback: observabilityFeedbackRecordSchema.optional(),
     delivery: deliverySchema.optional(),
     notifyDelivery: deliverySchema.optional(),
 })