feat(agent): add typed server API tools

tests/serverApi/gateway.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import { ServerApiGateway } from "../../src/serverApi/gateway.js";
+
+const context = {
+  actorKey: "user",
+  clientSessionId: "session",
+  projectId: "1c60fd8c-89fb-47ca-84f1-66ec10f5bf73",
+  projectKey: "project",
+  sessionId: "runtime",
+  traceId: "trace",
+};
+
+describe("ServerApiGateway project context", () => {
+  test("uses the metadata path and accepts project_id responses", async () => {
+    let requestedPath = "";
+    const fetchImpl = (async (input: URL | RequestInfo) => {
+      requestedPath = new URL(input.toString()).pathname;
+      return Response.json({
+        project_id: context.projectId,
+        code: "lingang",
+        name: "临港排水",
+        description: null,
+        status: "active",
+        project_role: "owner",
+        gs_workspace: "lingang",
+        map_extent: { xmin: 120.0, ymin: 30.0, xmax: 122.0, ymax: 32.0 },
+      });
+    }) as typeof fetch;
+    const gateway = new ServerApiGateway({} as never, fetchImpl);
+
+    const result = await gateway.execute("get_project_context", {}, context);
+
+    expect(requestedPath).toBe("/api/v1/meta/project");
+    expect(result).toMatchObject({
+      ok: true,
+      data: { project_id: context.projectId, status: "active", project_role: "owner" },
+    });
+  });
+
+  test("rejects the removed id response shape", async () => {
+    const fetchImpl = (async () =>
+      Response.json({ id: context.projectId, code: "lingang", name: "临港排水" })) as unknown as typeof fetch;
+    const gateway = new ServerApiGateway({} as never, fetchImpl);
+
+    const result = await gateway.execute("get_project_context", {}, context);
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: "UPSTREAM_UNAVAILABLE" },
+    });
+  });
+});

tests/serverApi/schemas.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { domainToolSchemas } from "../../src/serverApi/schemas.js";
+import { createIdempotencyKey } from "../../src/serverApi/gateway.js";
+
+const context = {
+  actorKey: "user", clientSessionId: "session", projectId: "1c60fd8c-89fb-47ca-84f1-66ec10f5bf73",
+  projectKey: "project", sessionId: "runtime", traceId: "trace",
+};
+
+describe("domain tool validation", () => {
+  test("rejects unknown metrics and reversed time", () => {
+    const base = { device_ids: ["940468c1-87cc-478f-b9f5-537ffbdb9025"], observed_from: "2026-07-14T02:00:00Z", observed_to: "2026-07-14T01:00:00Z", granularity: "5m" };
+    expect(domainToolSchemas.query_monitoring_readings.safeParse({ ...base, metrics: ["pressure"] }).success).toBeFalse();
+    expect(domainToolSchemas.query_monitoring_readings.safeParse({ ...base, metrics: ["flow_mean"] }).success).toBeFalse();
+  });
+
+  test("rejects invalid UUID before dispatch", () => {
+    expect(domainToolSchemas.start_simulation.safeParse({ model_version_id: "bad", parameters: {} }).success).toBeFalse();
+  });
+
+  test("idempotency key ignores object key order", () => {
+    expect(createIdempotencyKey(context, "start_simulation", { b: 2, a: 1 })).toBe(createIdempotencyKey(context, "start_simulation", { a: 1, b: 2 }));
+  });
+});