feat: add SCADA frontend action bridge

.opencode/agents/instruction.md

@@ -15,9 +15,7 @@ Agent 负责：
 1. 理解用户意图。
 2. 调用受控工具获取有限上下文或表达展示意图。
 3. 输出文字摘要、结论、追问和建议。
-4. 在没有可用前端工具时，仅输出文字摘要、结论和建议。
-
-当前不向 Agent 暴露前端动作工具。
+4. 在分析结论完成后，可将 SCADA 等级结果作为受控地图动作发送到浏览器。
 
 ## 工具选择
 
@@ -26,12 +24,17 @@ Agent 负责：
 | 历史会话检索 | `session_search` |
 | 用户偏好和项目事实 | `memory_manager` |
 | 可复用流程沉淀 | `skill_manager` |
+| 渲染 SCADA 分析结果 | `render_scada_analysis` |
+| 清除 SCADA 分析结果 | `clear_scada_analysis` |
 
 ## UI 约束
 
-1. 不生成或调用前端动作。
+1. `render_scada_analysis` 只能在分析结论已经完成后调用，不得让前端计算、猜测或修改高中低等级。
 2. 每次普通工具调用必须填写具体 `reason`。
 3. 不生成 JS、JSX、HTML、CSS 或可执行前端代码。
+4. SCADA 地图结果只允许使用可信 `sensor_id` 和 `high | medium | low | unrated` 等级，不得传入自定义标签、颜色或 HTML。
+5. 同一批结果不得包含重复 `sensor_id`，每次最多 100 个点位。
+6. 只有 SCADA 地图工具返回浏览器的成功结果后，才能声称已渲染或已清除；工具报错、超时或无活跃浏览器连接时，必须明确告知用户动作失败，不得伪造已渲染的点位、编号或等级。
 
 ## 执行约束
 

.opencode/plugins/frontend-action-call-id.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+const FRONTEND_ACTION_TOOLS = new Set([
+  "render_scada_analysis",
+  "clear_scada_analysis",
+]);
+
+export const frontendActionCallIdPlugin: Plugin = async () => ({
+  "tool.execute.before": async (input, output) => {
+    if (!FRONTEND_ACTION_TOOLS.has(input.tool)) return;
+    output.args.__frontend_action_call_id = input.callID;
+  },
+});

.opencode/tools/clear_scada_analysis.ts

@@ -0,0 +1,17 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { executeFrontendAction } from "./frontend_action.js";
+
+export default tool({
+  description: "清除当前浏览器地图上的 Agent SCADA 分析结果覆盖层。",
+  args: {
+    reason: tool.schema
+      .string()
+      .trim()
+      .min(1)
+      .describe("Why the current SCADA analysis overlay should be cleared."),
+  },
+  async execute(args, context) {
+    return executeFrontendAction("clear_scada_analysis", args, context);
+  },
+});

.opencode/tools/frontend_action.ts

@@ -0,0 +1,76 @@
+type FrontendActionArgs = Record<string, unknown> & {
+  __frontend_action_call_id?: string;
+  reason?: string;
+};
+
+type FrontendActionBridgeResult = {
+  version: "frontend-action-result@1";
+  status: "succeeded" | "failed" | "rejected" | "cancelled" | "expired";
+  output?: unknown;
+  error?: { code?: string; message?: string };
+};
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export const executeFrontendAction = async (
+  name: "render_scada_analysis" | "clear_scada_analysis",
+  args: FrontendActionArgs,
+  context: { sessionID: string },
+) => {
+  const callId = args.__frontend_action_call_id;
+  if (!callId) {
+    throw new Error("frontend action bridge did not inject the OpenCode call ID");
+  }
+  const { __frontend_action_call_id: _callId, reason, ...params } = args;
+  let response: Response;
+  try {
+    response = await fetch(`${internalBaseUrl}/internal/frontend-actions/request`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-agent-internal-token": internalToken,
+      },
+      body: JSON.stringify({
+        session_id: context.sessionID,
+        call_id: callId,
+        name,
+        params,
+        fallback_text: reason,
+      }),
+    });
+  } catch (error) {
+    throw new Error(
+      `frontend action bridge unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      `frontend action bridge rejected request (${response.status}): ${text}`,
+    );
+  }
+  return unwrapFrontendActionResult(text);
+};
+
+export const unwrapFrontendActionResult = (text: string) => {
+  let result: FrontendActionBridgeResult;
+  try {
+    result = JSON.parse(text) as FrontendActionBridgeResult;
+  } catch {
+    throw new Error("frontend action bridge returned invalid JSON");
+  }
+  if (result.version !== "frontend-action-result@1" || typeof result.status !== "string") {
+    throw new Error("frontend action bridge returned an invalid result");
+  }
+  if (result.status !== "succeeded") {
+    const code = result.error?.code?.trim() || `ACTION_${result.status.toUpperCase()}`;
+    const message = result.error?.message?.trim() || `browser action ${result.status}`;
+    throw new Error(`${code}: ${message}`);
+  }
+  if (result.output === undefined) {
+    throw new Error("frontend action bridge returned no output");
+  }
+  return JSON.stringify(result.output);
+};

.opencode/tools/render_scada_analysis.ts

@@ -0,0 +1,36 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { executeFrontendAction } from "./frontend_action.js";
+
+const sensorId = tool.schema.string().trim().min(1).max(128);
+
+export default tool({
+  description:
+    "将已经完成分析并确定等级的 SCADA 点位结果高亮、编号并定位到前端地图。等级只能来自已完成的分析结论。",
+  args: {
+    reason: tool.schema
+      .string()
+      .trim()
+      .min(1)
+      .describe("Why the completed SCADA analysis should be rendered on the map."),
+    items: tool.schema
+      .array(
+        tool.schema.object({
+          sensor_id: sensorId.describe("Trusted SCADA sensor identifier."),
+          level: tool.schema
+            .enum(["high", "medium", "low", "unrated"])
+            .describe("Completed analysis level; use unrated only when no level was concluded."),
+        }),
+      )
+      .min(1)
+      .max(100)
+      .refine(
+        (items) => new Set(items.map((item) => item.sensor_id)).size === items.length,
+        "sensor_id values must be unique",
+      )
+      .describe("One to one hundred unique SCADA analysis results."),
+  },
+  async execute(args, context) {
+    return executeFrontendAction("render_scada_analysis", args, context);
+  },
+});

src/frontendAction/coordinator.ts

@@ -48,7 +48,11 @@ export class FrontendActionCoordinator {
     this.sinks.set(sessionId, sink);
     const now = Date.now();
     for (const pending of this.pending.values()) {
-      if (pending.request.sessionId === sessionId && pending.request.expiresAt > now) sink(pending.request);
+      if (
+        pending.request.sessionId === sessionId &&
+        pending.request.replayPolicy === "explicit" &&
+        pending.request.expiresAt > now
+      ) sink(pending.request);
     }
     return () => {
       if (this.sinks.get(sessionId) === sink) this.sinks.delete(sessionId);

src/frontendAction/registry.ts

@@ -2,7 +2,58 @@ import { z } from "zod";
 import type { FrontendActionManifest } from "./types.js";
 
 type Definition = { manifest: FrontendActionManifest; inputSchema: z.ZodTypeAny; outputSchema: z.ZodTypeAny };
-const definitions: Definition[] = [];
+const sensorId = z.string().trim().min(1).max(128);
+const scadaLevel = z.enum(["high", "medium", "low", "unrated"]);
+const levelCounts = z.object({
+  high: z.number().int().nonnegative(),
+  medium: z.number().int().nonnegative(),
+  low: z.number().int().nonnegative(),
+  unrated: z.number().int().nonnegative(),
+}).strict();
+const renderScadaAnalysisInput = z.object({
+  items: z.array(z.object({ sensor_id: sensorId, level: scadaLevel }).strict()).min(1).max(100),
+}).strict().superRefine((value, context) => {
+  const seen = new Set<string>();
+  value.items.forEach((item, index) => {
+    if (seen.has(item.sensor_id)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "sensor_id values must be unique",
+        path: ["items", index, "sensor_id"],
+      });
+    }
+    seen.add(item.sensor_id);
+  });
+});
+const definitions: Definition[] = [
+  {
+    manifest: {
+      id: "render_scada_analysis",
+      version: "frontend-action@1",
+      risk: "view",
+      timeoutMs: 15_000,
+      supportedSurfaces: ["map_overlay"],
+    },
+    inputSchema: renderScadaAnalysisInput,
+    outputSchema: z.object({
+      rendered_ids: z.array(sensorId),
+      missing_ids: z.array(sensorId),
+      level_counts: levelCounts,
+      fitted: z.literal(true),
+    }).strict(),
+  },
+  {
+    manifest: {
+      id: "clear_scada_analysis",
+      version: "frontend-action@1",
+      risk: "view",
+      timeoutMs: 15_000,
+      supportedSurfaces: ["map_overlay"],
+    },
+    inputSchema: z.object({}).strict(),
+    outputSchema: z.object({ cleared: z.literal(true) }).strict(),
+  },
+];
 
 export const frontendActionRegistry = definitions.map((item) => item.manifest);
 export const getFrontendActionDefinition = (name: string) => definitions.find((item) => item.manifest.id === name);

src/routes/chatStreamEvents.ts

@@ -60,7 +60,9 @@ export type TodoUpdatePayload = {
 const isDevelopmentDebugLoggingEnabled = process.env.NODE_ENV === "development";
 
 const toolLabels: Record<string, string> = {
+  clear_scada_analysis: "清除 SCADA 地图分析",
   memory_manager: "记忆写入",
+  render_scada_analysis: "渲染 SCADA 地图分析",
   session_search: "历史会话检索",
   skill_manager: "流程沉淀",
 };

src/routes/chatUiState.ts

@@ -207,6 +207,9 @@ export const updateLastAssistantQuestion = (
   });
 
 const getToolArtifactKind = (tool: string): ToolArtifactKind => {
+  if (tool === "render_scada_analysis" || tool === "clear_scada_analysis") {
+    return "map";
+  }
   return "tool";
 };
 

src/server.ts

@@ -52,13 +52,7 @@ app.post("/internal/frontend-actions/request", async (req, res) => {
     return;
   }
   if (!context.capabilities?.includes("frontend-action@1")) {
-    // Legacy clients still execute the existing UIEnvelope emitted from the tool call.
-    res.json({
-      version: "frontend-action-result@1",
-      status: "succeeded",
-      output: { legacy: true },
-      detail: "legacy client executes the action from its UIEnvelope",
-    });
+    res.status(409).json({ message: "frontend-action@1 browser capability is required" });
     return;
   }
   try {

tests/frontendAction/callIdPlugin.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+
+import { frontendActionCallIdPlugin } from "../../.opencode/plugins/frontend-action-call-id.js";
+
+describe("frontend action call ID plugin", () => {
+  it("injects call IDs only for SCADA frontend actions", async () => {
+    const hooks = await frontendActionCallIdPlugin({} as never);
+    const before = hooks["tool.execute.before"];
+    if (!before) throw new Error("before hook missing");
+    const actionArgs: Record<string, unknown> = { items: [] };
+    const actionOutput: { args: Record<string, unknown> } = { args: actionArgs };
+    await before(
+      { tool: "render_scada_analysis", callID: "call-1", sessionID: "s" },
+      actionOutput,
+    );
+    expect(actionOutput.args).toBe(actionArgs);
+    expect(actionArgs).toEqual({
+      items: [],
+      __frontend_action_call_id: "call-1",
+    });
+    const regularArgs = { query: "SCADA" };
+    const regularOutput = { args: regularArgs };
+    await before(
+      { tool: "session_search", callID: "call-2", sessionID: "s" },
+      regularOutput,
+    );
+    expect(regularOutput.args).toBe(regularArgs);
+    expect(regularArgs).toEqual({ query: "SCADA" });
+  });
+
+  it("exports only plugin functions so OpenCode can load the module", async () => {
+    const pluginModule = await import("../../.opencode/plugins/frontend-action-call-id.js");
+    expect(Object.keys(pluginModule)).toEqual(["frontendActionCallIdPlugin"]);
+    expect(Object.values(pluginModule).every((value) => typeof value === "function")).toBeTrue();
+  });
+});

tests/frontendAction/coordinator.test.ts

@@ -1,12 +1,143 @@
 import { describe, expect, it } from "bun:test";
 
-import { FrontendActionCoordinator, FrontendActionError } from "../../src/frontendAction/coordinator.js";
+import {
+  FrontendActionCoordinator,
+  FrontendActionError,
+} from "../../src/frontendAction/coordinator.js";
+import { frontendActionRegistry } from "../../src/frontendAction/registry.js";
+import type { FrontendActionRequest } from "../../src/frontendAction/types.js";
+
+const items = [
+  { sensor_id: "MP01", level: "high" },
+  { sensor_id: "MP02", level: "medium" },
+] as const;
+
+const start = (
+  coordinator: FrontendActionCoordinator,
+  name = "render_scada_analysis",
+  params: unknown = { items },
+) => {
+  let emitted: FrontendActionRequest | undefined;
+  coordinator.registerSink("session-1", (request) => {
+    emitted = request;
+  });
+  const pending = coordinator.request({
+    sessionId: "session-1",
+    toolCallId: "call-1",
+    name,
+    params,
+  });
+  if (!emitted) throw new Error("request was not emitted");
+  return { emitted, pending };
+};
 
 describe("FrontendActionCoordinator", () => {
-  it("rejects frontend actions when the registry is empty", () => {
+  it("registers only the two view-risk SCADA actions with 15 second expiry", () => {
+    expect(frontendActionRegistry).toEqual([
+      expect.objectContaining({ id: "render_scada_analysis", risk: "view", timeoutMs: 15_000 }),
+      expect.objectContaining({ id: "clear_scada_analysis", risk: "view", timeoutMs: 15_000 }),
+    ]);
+  });
+
+  it("emits once and resolves with validated browser output", async () => {
+    const coordinator = new FrontendActionCoordinator();
+    const { emitted, pending } = start(coordinator);
+    expect(emitted).toMatchObject({
+      name: "render_scada_analysis",
+      risk: "view",
+      replayPolicy: "never",
+      params: { items },
+    });
+    expect(emitted.expiresAt - emitted.issuedAt).toBe(15_000);
+    const result = {
+      version: "frontend-action-result@1" as const,
+      actionId: emitted.actionId,
+      status: "succeeded" as const,
+      output: {
+        rendered_ids: ["MP01", "MP02"],
+        missing_ids: [],
+        level_counts: { high: 1, medium: 1, low: 0, unrated: 0 },
+        fitted: true as const,
+      },
+      completedAt: Date.now(),
+    };
+    expect(coordinator.submitResult("session-1", result).duplicate).toBe(false);
+    expect((await pending).output).toEqual(result.output);
+    expect(coordinator.submitResult("session-1", result).duplicate).toBe(true);
+  });
+
+  it("does not replay never-policy actions when the browser sink reconnects", async () => {
+    const coordinator = new FrontendActionCoordinator();
+    const emitted: FrontendActionRequest[] = [];
+    const unregister = coordinator.registerSink("session-1", (request) => emitted.push(request));
+    const pending = coordinator.request({
+      sessionId: "session-1",
+      toolCallId: "call-no-replay",
+      name: "clear_scada_analysis",
+      params: {},
+    });
+    unregister();
+    coordinator.registerSink("session-1", (request) => emitted.push(request));
+    expect(emitted).toHaveLength(1);
+    coordinator.submitResult("session-1", {
+      version: "frontend-action-result@1",
+      actionId: emitted[0].actionId,
+      status: "succeeded",
+      output: { cleared: true },
+      completedAt: Date.now(),
+    });
+    await pending;
+  });
+
+  it("accepts clear output and rejects invalid successful output", async () => {
+    const coordinator = new FrontendActionCoordinator();
+    const { emitted, pending } = start(coordinator, "clear_scada_analysis", {});
+    expect(() => coordinator.submitResult("session-1", {
+      version: "frontend-action-result@1",
+      actionId: emitted.actionId,
+      status: "succeeded",
+      output: { cleared: false },
+      completedAt: Date.now(),
+    })).toThrow("invalid frontend action output");
+    coordinator.submitResult("session-1", {
+      version: "frontend-action-result@1",
+      actionId: emitted.actionId,
+      status: "succeeded",
+      output: { cleared: true },
+      completedAt: Date.now(),
+    });
+    expect((await pending).output).toEqual({ cleared: true });
+  });
+
+  it("validates item count, unique IDs, ID length, and levels", () => {
     const coordinator = new FrontendActionCoordinator();
     coordinator.registerSink("s", () => undefined);
-    expect(() => coordinator.request({ sessionId: "s", toolCallId: "c", name: "zoom_to_map", params: {} })).toThrow(FrontendActionError);
-    expect(() => coordinator.request({ sessionId: "s", toolCallId: "c", name: "zoom_to_map", params: {} })).toThrow("unknown frontend action");
+    const request = (value: unknown) => coordinator.request({
+      sessionId: "s",
+      toolCallId: "call-validation",
+      name: "render_scada_analysis",
+      params: value,
+    });
+    expect(() => request({ items: [] })).toThrow(FrontendActionError);
+    expect(() => request({ items: Array.from({ length: 101 }, (_, index) => ({ sensor_id: `MP${index}`, level: "low" })) })).toThrow("invalid frontend action params");
+    expect(() => request({ items: [{ sensor_id: "MP01", level: "high" }, { sensor_id: "MP01", level: "low" }] })).toThrow("invalid frontend action params");
+    expect(() => request({ items: [{ sensor_id: "x".repeat(129), level: "low" }] })).toThrow("invalid frontend action params");
+    expect(() => request({ items: [{ sensor_id: "MP01", level: "critical" }] })).toThrow("invalid frontend action params");
+  });
+
+  it("keeps terminal results idempotent and rejects conflicts", async () => {
+    const coordinator = new FrontendActionCoordinator();
+    const { emitted, pending } = start(coordinator, "clear_scada_analysis", {});
+    const result = {
+      version: "frontend-action-result@1" as const,
+      actionId: emitted.actionId,
+      status: "succeeded" as const,
+      output: { cleared: true as const },
+      completedAt: Date.now(),
+    };
+    expect(() => coordinator.submitResult("other", result)).toThrow("session mismatch");
+    coordinator.submitResult("session-1", result);
+    await pending;
+    expect(() => coordinator.submitResult("session-1", { ...result, completedAt: result.completedAt + 1 })).toThrow("conflicts");
   });
 });

tests/frontendAction/toolBridge.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test";
+
+import { unwrapFrontendActionResult } from "../../.opencode/tools/frontend_action.js";
+
+describe("frontend action tool bridge", () => {
+  it("returns only validated browser output for successful actions", () => {
+    expect(unwrapFrontendActionResult(JSON.stringify({
+      version: "frontend-action-result@1",
+      actionId: "action-1",
+      status: "succeeded",
+      output: { cleared: true },
+      completedAt: Date.now(),
+    }))).toBe('{"cleared":true}');
+  });
+
+  it("throws the browser error for failed and expired actions", () => {
+    expect(() => unwrapFrontendActionResult(JSON.stringify({
+      version: "frontend-action-result@1",
+      actionId: "action-1",
+      status: "failed",
+      error: { code: "WFS_UNAVAILABLE", message: "SCADA geometry query failed" },
+      completedAt: Date.now(),
+    }))).toThrow("WFS_UNAVAILABLE: SCADA geometry query failed");
+    expect(() => unwrapFrontendActionResult(JSON.stringify({
+      version: "frontend-action-result@1",
+      actionId: "action-2",
+      status: "expired",
+      error: { code: "ACTION_TIMEOUT", message: "browser action timed out" },
+      completedAt: Date.now(),
+    }))).toThrow("ACTION_TIMEOUT: browser action timed out");
+  });
+});

tests/opencode/disabledTools.test.ts

@@ -10,13 +10,15 @@ const disabledServerTools = [
 ];
 
 describe("disabled opencode tools", () => {
-  it("does not expose Server-dependent or frontend-action tools", () => {
+  it("exposes only the two SCADA frontend-action tools", () => {
     for (const toolName of disabledServerTools) {
       expect(existsSync(`.opencode/tools/${toolName}.ts`)).toBeFalse();
     }
     expect(existsSync(".opencode/tools/server_api_shared.ts")).toBeFalse();
     expect(existsSync(".opencode/tools/zoom_to_map.ts")).toBeFalse();
-    expect(existsSync(".opencode/tools/frontend_action.ts")).toBeFalse();
-    expect(existsSync(".opencode/plugins/frontend-action-call-id.ts")).toBeFalse();
+    expect(existsSync(".opencode/tools/frontend_action.ts")).toBeTrue();
+    expect(existsSync(".opencode/tools/render_scada_analysis.ts")).toBeTrue();
+    expect(existsSync(".opencode/tools/clear_scada_analysis.ts")).toBeTrue();
+    expect(existsSync(".opencode/plugins/frontend-action-call-id.ts")).toBeTrue();
   });
 });

tests/routes/chatUiState.test.ts

@@ -8,6 +8,20 @@ import {
 } from "../../src/routes/chatUiState.js";
 
 describe("appendBackendToolArtifact", () => {
+  it("marks SCADA frontend actions as map artifacts", () => {
+    const artifacts = appendBackendToolArtifact([], {
+      tool: "render_scada_analysis",
+      reason: "显示已完成的分级结论",
+      params: { items: [{ sensor_id: "MP01", level: "high" }] },
+    }) as Array<Record<string, unknown>>;
+
+    expect(artifacts[0]).toMatchObject({
+      tool: "render_scada_analysis",
+      kind: "map",
+      description: "显示已完成的分级结论",
+    });
+  });
+
   it("persists removed visual tool calls as generic tool artifacts", () => {
     const artifacts = appendBackendToolArtifact([], {
       session_id: "session-1",

tests/uiEnvelope/fromToolCall.test.ts

@@ -8,4 +8,15 @@ describe("toUiEnvelopeFromToolCall", () => {
     expect(toUiEnvelopeFromToolCall({ tool: "show_chart", params: {} })).toBeNull();
     expect(toUiEnvelopeFromToolCall({ tool: "view_scada", params: { asset_ids: ["A-1"] } })).toBeNull();
   });
+
+  it("does not generate duplicate UIEnvelopes for SCADA frontend actions", () => {
+    expect(toUiEnvelopeFromToolCall({
+      tool: "render_scada_analysis",
+      params: { items: [{ sensor_id: "MP01", level: "high" }] },
+    })).toBeNull();
+    expect(toUiEnvelopeFromToolCall({
+      tool: "clear_scada_analysis",
+      params: {},
+    })).toBeNull();
+  });
 });