feat: initialize TJWater WebGIS frontend

src/features/agent/frontend-action/executor.ts

@@ -0,0 +1,55 @@
+import {
+  parseFrontendActionRequest,
+  readActionResults,
+  storeActionResult,
+  type FrontendActionRequest,
+  type FrontendActionResult
+} from ".";
+
+type ExecuteAction = (request: FrontendActionRequest, signal: AbortSignal) => Promise<unknown>;
+type SubmitResult = (sessionId: string, actionId: string, result: FrontendActionResult) => Promise<void>;
+const ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]+$/;
+
+export class FrontendActionExecutor {
+  private readonly controllers = new Map<string, AbortController>();
+
+  constructor(private readonly execute: ExecuteAction, private readonly submit: SubmitResult) {}
+
+  async handle(value: unknown, activeSessionId: string | null): Promise<void> {
+    const request = parseFrontendActionRequest(value);
+    if (!request || request.sessionId !== activeSessionId) return;
+    const saved = readActionResults(request.sessionId)[request.actionId];
+    if (saved) {
+      await this.submit(request.sessionId, request.actionId, saved);
+      return;
+    }
+    if (this.controllers.has(request.actionId)) return;
+    const result = await this.executeOnce(request);
+    storeActionResult(request.sessionId, result);
+    await this.submit(request.sessionId, request.actionId, result);
+  }
+
+  cancelAll(): void {
+    for (const controller of this.controllers.values()) controller.abort();
+    this.controllers.clear();
+  }
+
+  private async executeOnce(request: FrontendActionRequest): Promise<FrontendActionResult> {
+    if (Date.now() >= request.expiresAt) return this.failure(request, "expired", "ACTION_EXPIRED", "frontend action expired before execution");
+    const controller = new AbortController();
+    this.controllers.set(request.actionId, controller);
+    try {
+      return { version: "frontend-action-result@1", actionId: request.actionId, status: "succeeded", output: await this.execute(request, controller.signal), completedAt: Date.now() };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "frontend action failed";
+      const code = controller.signal.aborted ? "ACTION_CANCELLED" : ERROR_CODE_PATTERN.test(message) ? message : "ACTION_FAILED";
+      return this.failure(request, controller.signal.aborted ? "cancelled" : "failed", code, message);
+    } finally {
+      this.controllers.delete(request.actionId);
+    }
+  }
+
+  private failure(request: FrontendActionRequest, status: "failed" | "cancelled" | "expired", code: string, message: string): FrontendActionResult {
+    return { version: "frontend-action-result@1", actionId: request.actionId, status, error: { code, message }, completedAt: Date.now() };
+  }
+}

src/features/agent/frontend-action/index.test.ts

@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { FrontendActionExecutor } from "./executor";
+import { parseFrontendActionRegistry, parseFrontendActionRequest, type FrontendActionResult } from ".";
+
+const storage = new Map<string, string>();
+
+beforeEach(() => {
+  storage.clear();
+  vi.stubGlobal("sessionStorage", {
+    getItem: (key: string) => storage.get(key) ?? null,
+    setItem: (key: string, value: string) => storage.set(key, value)
+  });
+});
+
+describe("SCADA frontend actions", () => {
+  it("accepts only the two registered SCADA action names", () => {
+    expect(parseFrontendActionRegistry({
+      schema_version: "frontend-action-registry@1",
+      actions: [
+        { id: "render_scada_analysis", version: "frontend-action@1" },
+        { id: "clear_scada_analysis", version: "frontend-action@1" },
+        { id: "zoom_to_map", version: "frontend-action@1" }
+      ]
+    })?.actions.map((action) => action.id)).toEqual([
+      "render_scada_analysis",
+      "clear_scada_analysis"
+    ]);
+    expect(parseFrontendActionRequest(createRequest("zoom_to_map"))).toBeNull();
+    expect(parseFrontendActionRequest(createRequest("render_scada_analysis"))).not.toBeNull();
+  });
+
+  it("submits the real browser output and replays the terminal receipt idempotently", async () => {
+    const execute = vi.fn(async () => ({
+      rendered_ids: ["MP01"],
+      missing_ids: [],
+      level_counts: { high: 1, medium: 0, low: 0, unrated: 0 },
+      fitted: true
+    }));
+    const submit = vi.fn(async (
+      _sessionId: string,
+      _actionId: string,
+      _result: FrontendActionResult
+    ) => undefined);
+    const executor = new FrontendActionExecutor(execute, submit);
+    const request = createRequest("render_scada_analysis");
+    await executor.handle(request, "session-1");
+    await executor.handle(request, "session-1");
+    expect(execute).toHaveBeenCalledTimes(1);
+    expect(submit).toHaveBeenCalledTimes(2);
+    expect(submit.mock.calls[0][2]).toMatchObject({
+      status: "succeeded",
+      output: { rendered_ids: ["MP01"], fitted: true }
+    });
+    expect(submit.mock.calls[1][2]).toEqual(submit.mock.calls[0][2]);
+  });
+});
+
+function createRequest(name: string) {
+  return {
+    version: "frontend-action@1",
+    actionId: "action-1",
+    toolCallId: "call-1",
+    sessionId: "session-1",
+    name,
+    params: { items: [{ sensor_id: "MP01", level: "high" }] },
+    issuedAt: Date.now(),
+    expiresAt: Date.now() + 15_000
+  };
+}

src/features/agent/frontend-action/index.ts

@@ -0,0 +1,11 @@
+export const FRONTEND_ACTION_NAMES = ["render_scada_analysis", "clear_scada_analysis"] as const;
+export type FrontendActionName = (typeof FRONTEND_ACTION_NAMES)[number];
+export type FrontendActionRegistry = { schema_version: "frontend-action-registry@1"; actions: Array<{ id: FrontendActionName; version: "frontend-action@1" }> };
+export type FrontendActionRequest = { version: "frontend-action@1"; actionId: string; toolCallId: string; sessionId: string; name: FrontendActionName; params: Record<string, unknown>; issuedAt: number; expiresAt: number };
+export type FrontendActionResult = { version: "frontend-action-result@1"; actionId: string; status: "succeeded" | "failed" | "cancelled" | "expired"; output?: unknown; error?: { code: string; message: string }; completedAt: number };
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+export function parseFrontendActionRegistry(value: unknown): FrontendActionRegistry | null { if (!isRecord(value) || value.schema_version !== "frontend-action-registry@1" || !Array.isArray(value.actions)) return null; const actions = value.actions.filter((item): item is { id: FrontendActionName; version: "frontend-action@1" } => isRecord(item) && FRONTEND_ACTION_NAMES.includes(item.id as FrontendActionName) && item.version === "frontend-action@1"); return { schema_version: "frontend-action-registry@1", actions }; }
+export function parseFrontendActionRequest(value: unknown): FrontendActionRequest | null { if (!isRecord(value) || value.version !== "frontend-action@1" || typeof value.actionId !== "string" || typeof value.toolCallId !== "string" || typeof value.sessionId !== "string" || !FRONTEND_ACTION_NAMES.includes(value.name as FrontendActionName) || !isRecord(value.params) || typeof value.issuedAt !== "number" || typeof value.expiresAt !== "number") return null; return value as FrontendActionRequest; }
+const storageKey = (sessionId: string) => `tjwater:frontend-actions:${sessionId}`;
+export function readActionResults(sessionId: string): Record<string, FrontendActionResult> { try { const value = JSON.parse(sessionStorage.getItem(storageKey(sessionId)) ?? "{}"); return isRecord(value) ? value as Record<string, FrontendActionResult> : {}; } catch { return {}; } }
+export function storeActionResult(sessionId: string, result: FrontendActionResult) { const values = { ...readActionResults(sessionId), [result.actionId]: result }; const bounded = Object.fromEntries(Object.entries(values).sort(([, a], [, b]) => b.completedAt - a.completedAt).slice(0, 100)); sessionStorage.setItem(storageKey(sessionId), JSON.stringify(bounded)); }