diff --git a/tools/ruview-mcp/src/schemas/common.ts b/tools/ruview-mcp/src/schemas/common.ts new file mode 100644 index 00000000..91b65551 --- /dev/null +++ b/tools/ruview-mcp/src/schemas/common.ts @@ -0,0 +1,79 @@ +/** + * Shared Zod sub-schemas reused across the ADR-124 §4.1 tool catalog. + * + * All constraints are sourced from the ADR-124 decision record; comments cite + * the specific table row or section that defines the constraint. + */ + +import { z } from "zod"; + +// ── Shared primitives ────────────────────────────────────────────────────── + +/** + * Optional node_id — present on almost every tool. Defaults to the single + * active node when only one is registered; required for multi-node fleets. + */ +export const NodeIdSchema = z + .string() + .min(1) + .optional() + .describe("Target node id. Omit to use the single active node."); + +/** + * Subscription duration in seconds. ADR-124 policy layer caps this at the + * value returned by ruview.policy.can_subscribe.max_duration_s; the schema + * enforces a hard ceiling of 3600 s (1 h) as a first-line guard. + */ +export const DurationSSchema = z + .number() + .positive() + .max(3600) + .describe("Subscription duration in seconds (max 3600)."); + +/** + * Optional window in seconds for vitals averaging. Positive, max 300 s. + * ADR-124 §4.1 rows vitals.get_breathing / vitals.get_heart_rate. + */ +export const WindowSSchema = z + .number() + .positive() + .max(300) + .optional() + .describe("Averaging window in seconds (max 300)."); + +/** + * The 10 semantic primitive kinds defined in ADR-115 and mirrored in + * python/wifi_densepose/client/primitives.py:36-45. + */ +export const SemanticPrimitiveKindSchema = z.enum([ + "presence", + "n_persons", + "fall_detected", + "breathing_rate", + "heart_rate", + "gesture", + "zone_entry", + "zone_exit", + "movement_intensity", + "sleep_quality", +]); + +export type SemanticPrimitiveKind = z.infer; + +/** + * A single 17-keypoint COCO pose result as stored and returned by the + * ruvector HNSW index (ADR-016). Used by ruview.vector.store_pose input. + */ +export const PosePersonResultSchema = z.object({ + keypoints: z + .array(z.tuple([z.number(), z.number()])) + .length(17) + .describe("17 COCO keypoints as [x,y] pairs in image-normalised coords."), + confidence: z.number().min(0).max(1).describe("Pose confidence score [0,1]."), + person_id: z + .string() + .optional() + .describe("AETHER re-ID token, if available."), +}); + +export type PosePersonResult = z.infer; diff --git a/tools/ruview-mcp/src/schemas/index.ts b/tools/ruview-mcp/src/schemas/index.ts new file mode 100644 index 00000000..8913b41f --- /dev/null +++ b/tools/ruview-mcp/src/schemas/index.ts @@ -0,0 +1,9 @@ +/** + * Barrel re-export for @ruvnet/rvagent schema layer. + * + * Import from this module to get all Zod input schemas, shared sub-schemas, + * the TOOL_NAMES catalog, and the TOOL_INPUT_SCHEMAS dispatch map. + */ + +export * from "./common.js"; +export * from "./tools.js"; diff --git a/tools/ruview-mcp/src/schemas/tools.ts b/tools/ruview-mcp/src/schemas/tools.ts new file mode 100644 index 00000000..0486bc01 --- /dev/null +++ b/tools/ruview-mcp/src/schemas/tools.ts @@ -0,0 +1,242 @@ +/** + * Zod input schemas for all 20 ADR-124 MCP tools. + * + * §4.1 — 15 sensing tools (presence, vitals, pose, primitives, bfld, node, vector) + * §4.1a — 5 policy / governance tools (RUVIEW-POLICY) + * + * Each exported schema is named `InputSchema` matching the tool + * name from the ADR-124 §4.1 catalog table. The parallel `TOOL_NAMES` array + * is the single source of truth asserted by the schema-coverage test. + */ + +import { z } from "zod"; +import { + NodeIdSchema, + DurationSSchema, + WindowSSchema, + SemanticPrimitiveKindSchema, + PosePersonResultSchema, +} from "./common.js"; + +// ── §4.1 Presence ────────────────────────────────────────────────────────── + +/** ruview.presence.now */ +export const PresenceNowInputSchema = z.object({ + node_id: NodeIdSchema, +}); + +// ── §4.1 Vitals ─────────────────────────────────────────────────────────── + +/** ruview.vitals.get_breathing */ +export const VitalsGetBreathingInputSchema = z.object({ + node_id: NodeIdSchema, + window_s: WindowSSchema, +}); + +/** ruview.vitals.get_heart_rate */ +export const VitalsGetHeartRateInputSchema = z.object({ + node_id: NodeIdSchema, + window_s: WindowSSchema, +}); + +/** ruview.vitals.get_all */ +export const VitalsGetAllInputSchema = z.object({ + node_id: NodeIdSchema, +}); + +// ── §4.1 Pose ───────────────────────────────────────────────────────────── + +/** ruview.pose.latest */ +export const PoseLatestInputSchema = z.object({ + node_id: NodeIdSchema, +}); + +/** ruview.pose.subscribe */ +export const PoseSubscribeInputSchema = z.object({ + node_id: NodeIdSchema, + duration_s: DurationSSchema, + callback_url: z + .string() + .url() + .optional() + .describe("Webhook URL to receive PoseDataMessage events (optional)."), +}); + +// ── §4.1 Primitives ─────────────────────────────────────────────────────── + +/** ruview.primitives.get */ +export const PrimitivesGetInputSchema = z.object({ + node_id: NodeIdSchema, + primitive: SemanticPrimitiveKindSchema, +}); + +/** ruview.primitives.list_active */ +export const PrimitivesListActiveInputSchema = z.object({ + node_id: NodeIdSchema, +}); + +/** ruview.primitives.subscribe */ +export const PrimitivesSubscribeInputSchema = z.object({ + node_id: NodeIdSchema, + primitive: SemanticPrimitiveKindSchema.optional().describe( + "Subscribe to a specific primitive. Omit to receive all active primitives." + ), + duration_s: DurationSSchema, +}); + +// ── §4.1 BFLD ──────────────────────────────────────────────────────────── + +/** ruview.bfld.last_scan */ +export const BfldLastScanInputSchema = z.object({ + node_id: NodeIdSchema, +}); + +/** ruview.bfld.subscribe */ +export const BfldSubscribeInputSchema = z.object({ + node_id: NodeIdSchema, + duration_s: DurationSSchema, +}); + +// ── §4.1 Node ──────────────────────────────────────────────────────────── + +/** ruview.node.list — empty input per ADR-124 §4.1 table */ +export const NodeListInputSchema = z.object({}); + +/** ruview.node.status */ +export const NodeStatusInputSchema = z.object({ + node_id: z.string().min(1).describe("Node id to query status for."), +}); + +// ── §4.1 Vector ────────────────────────────────────────────────────────── + +/** ruview.vector.search_pose */ +export const VectorSearchPoseInputSchema = z.object({ + query_embedding: z + .array(z.number()) + .min(1) + .describe("Dense embedding vector to query against the HNSW index."), + k: z + .number() + .int() + .positive() + .max(100) + .optional() + .default(10) + .describe("Number of nearest neighbours to return (default 10, max 100)."), + node_id: NodeIdSchema, +}); + +/** ruview.vector.store_pose */ +export const VectorStorePoseInputSchema = z.object({ + pose: PosePersonResultSchema, + node_id: z.string().min(1).describe("Node id that observed this pose."), +}); + +// ── §4.1a Policy / governance tools ────────────────────────────────────── + +/** ruview.policy.can_access_vitals */ +export const PolicyCanAccessVitalsInputSchema = z.object({ + agent_id: z.string().min(1).describe("Calling agent identifier."), + node_id: z.string().min(1).describe("Target sensing node."), + vital: z + .enum(["breathing", "heart_rate", "all"]) + .describe("Which vital the agent is requesting."), +}); + +/** ruview.policy.can_query_presence */ +export const PolicyCanQueryPresenceInputSchema = z.object({ + agent_id: z.string().min(1), + scope: z + .enum(["node", "fleet"]) + .describe("node = single node; fleet = all nodes / aggregated count."), + node_id: NodeIdSchema, + zone: z + .string() + .optional() + .describe("Named zone within a node (e.g. 'living_room')."), +}); + +/** ruview.policy.can_subscribe */ +export const PolicyCanSubscribeInputSchema = z.object({ + agent_id: z.string().min(1), + topic: z + .string() + .min(1) + .describe("MQTT topic or tool name the agent wishes to subscribe to."), + duration_s: DurationSSchema, +}); + +/** ruview.policy.redact_identity_fields */ +export const PolicyRedactIdentityFieldsInputSchema = z.object({ + payload: z.record(z.unknown()).describe("Tool return value to redact."), + agent_id: z.string().min(1), +}); + +/** ruview.policy.audit_log */ +export const PolicyAuditLogInputSchema = z.object({ + agent_id: z.string().optional().describe("Filter to a specific agent."), + since_ts: z + .number() + .optional() + .describe("Return events after this Unix timestamp (ms)."), +}); + +// ── Catalog ─────────────────────────────────────────────────────────────── + +/** + * Single source of truth: every tool name in the ADR-124 §4.1 + §4.1a catalog. + * The schema-coverage test asserts this list exactly matches the exported schemas. + */ +export const TOOL_NAMES = [ + // §4.1 — 15 sensing tools + "ruview.presence.now", + "ruview.vitals.get_breathing", + "ruview.vitals.get_heart_rate", + "ruview.vitals.get_all", + "ruview.pose.latest", + "ruview.pose.subscribe", + "ruview.primitives.get", + "ruview.primitives.list_active", + "ruview.primitives.subscribe", + "ruview.bfld.last_scan", + "ruview.bfld.subscribe", + "ruview.node.list", + "ruview.node.status", + "ruview.vector.search_pose", + "ruview.vector.store_pose", + // §4.1a — 5 policy tools + "ruview.policy.can_access_vitals", + "ruview.policy.can_query_presence", + "ruview.policy.can_subscribe", + "ruview.policy.redact_identity_fields", + "ruview.policy.audit_log", +] as const; + +export type ToolName = (typeof TOOL_NAMES)[number]; + +/** + * Map from tool name → its Zod input schema. Used by the MCP server's + * CallTool handler for uniform schema-validation before dispatch. + */ +export const TOOL_INPUT_SCHEMAS: Record = { + "ruview.presence.now": PresenceNowInputSchema, + "ruview.vitals.get_breathing": VitalsGetBreathingInputSchema, + "ruview.vitals.get_heart_rate": VitalsGetHeartRateInputSchema, + "ruview.vitals.get_all": VitalsGetAllInputSchema, + "ruview.pose.latest": PoseLatestInputSchema, + "ruview.pose.subscribe": PoseSubscribeInputSchema, + "ruview.primitives.get": PrimitivesGetInputSchema, + "ruview.primitives.list_active": PrimitivesListActiveInputSchema, + "ruview.primitives.subscribe": PrimitivesSubscribeInputSchema, + "ruview.bfld.last_scan": BfldLastScanInputSchema, + "ruview.bfld.subscribe": BfldSubscribeInputSchema, + "ruview.node.list": NodeListInputSchema, + "ruview.node.status": NodeStatusInputSchema, + "ruview.vector.search_pose": VectorSearchPoseInputSchema, + "ruview.vector.store_pose": VectorStorePoseInputSchema, + "ruview.policy.can_access_vitals": PolicyCanAccessVitalsInputSchema, + "ruview.policy.can_query_presence": PolicyCanQueryPresenceInputSchema, + "ruview.policy.can_subscribe": PolicyCanSubscribeInputSchema, + "ruview.policy.redact_identity_fields": PolicyRedactIdentityFieldsInputSchema, + "ruview.policy.audit_log": PolicyAuditLogInputSchema, +}; diff --git a/tools/ruview-mcp/tests/schemas.test.ts b/tools/ruview-mcp/tests/schemas.test.ts new file mode 100644 index 00000000..32c995bb --- /dev/null +++ b/tools/ruview-mcp/tests/schemas.test.ts @@ -0,0 +1,208 @@ +/** + * ADR-124 §4.1 / §4.1a schema coverage tests. + * + * Guards: + * 1. Every catalogued tool name appears in TOOL_NAMES and TOOL_INPUT_SCHEMAS. + * 2. TOOL_INPUT_SCHEMAS has no extra (undocumented) keys. + * 3. Each schema accepts its documented happy-path input without throwing. + * 4. Each schema rejects structurally invalid input (Zod parse failure). + * 5. Shared sub-schemas (NodeId, DurationS, SemanticPrimitiveKind) enforce + * their documented constraints. + */ + +import { + TOOL_NAMES, + TOOL_INPUT_SCHEMAS, + SemanticPrimitiveKindSchema, + DurationSSchema, + NodeIdSchema, + PosePersonResultSchema, + PresenceNowInputSchema, + VitalsGetBreathingInputSchema, + PrimitivesGetInputSchema, + BfldLastScanInputSchema, + NodeStatusInputSchema, + VectorSearchPoseInputSchema, + VectorStorePoseInputSchema, + PolicyCanAccessVitalsInputSchema, + PolicyCanSubscribeInputSchema, + PolicyRedactIdentityFieldsInputSchema, +} from "../src/schemas/index.js"; + +// ── 1. Catalog completeness ──────────────────────────────────────────────── + +describe("TOOL_NAMES catalog (ADR-124 §4.1 + §4.1a)", () => { + const EXPECTED_COUNT = 20; // 15 sensing + 5 policy + + it("contains exactly 20 tools", () => { + expect(TOOL_NAMES).toHaveLength(EXPECTED_COUNT); + }); + + it("contains all 15 §4.1 sensing tool names", () => { + const sensing = [ + "ruview.presence.now", + "ruview.vitals.get_breathing", + "ruview.vitals.get_heart_rate", + "ruview.vitals.get_all", + "ruview.pose.latest", + "ruview.pose.subscribe", + "ruview.primitives.get", + "ruview.primitives.list_active", + "ruview.primitives.subscribe", + "ruview.bfld.last_scan", + "ruview.bfld.subscribe", + "ruview.node.list", + "ruview.node.status", + "ruview.vector.search_pose", + "ruview.vector.store_pose", + ]; + for (const name of sensing) { + expect(TOOL_NAMES).toContain(name); + } + }); + + it("contains all 5 §4.1a policy tool names", () => { + const policy = [ + "ruview.policy.can_access_vitals", + "ruview.policy.can_query_presence", + "ruview.policy.can_subscribe", + "ruview.policy.redact_identity_fields", + "ruview.policy.audit_log", + ]; + for (const name of policy) { + expect(TOOL_NAMES).toContain(name); + } + }); + + it("TOOL_INPUT_SCHEMAS has a schema for every catalogued tool name", () => { + for (const name of TOOL_NAMES) { + // Use Object.prototype.hasOwnProperty to avoid Jest's dotted-path + // interpretation of toHaveProperty (dots = nested path in Jest). + expect(Object.prototype.hasOwnProperty.call(TOOL_INPUT_SCHEMAS, name)).toBe(true); + expect(TOOL_INPUT_SCHEMAS[name]).toBeDefined(); + } + }); + + it("TOOL_INPUT_SCHEMAS has no extra keys beyond the catalog", () => { + const schemaKeys = Object.keys(TOOL_INPUT_SCHEMAS).sort(); + const catalogKeys = [...TOOL_NAMES].sort(); + expect(schemaKeys).toEqual(catalogKeys); + }); +}); + +// ── 2. Happy-path parse ──────────────────────────────────────────────────── + +describe("Schema happy-path acceptance", () => { + it("PresenceNow — accepts empty object (node_id optional)", () => { + expect(() => PresenceNowInputSchema.parse({})).not.toThrow(); + }); + + it("PresenceNow — accepts object with node_id", () => { + const r = PresenceNowInputSchema.parse({ node_id: "node-abc" }); + expect(r.node_id).toBe("node-abc"); + }); + + it("VitalsGetBreathing — accepts window_s and node_id", () => { + const r = VitalsGetBreathingInputSchema.parse({ window_s: 30, node_id: "n1" }); + expect(r.window_s).toBe(30); + }); + + it("PrimitivesGet — accepts valid primitive kind", () => { + const r = PrimitivesGetInputSchema.parse({ primitive: "fall_detected" }); + expect(r.primitive).toBe("fall_detected"); + }); + + it("BfldLastScan — accepts empty object", () => { + expect(() => BfldLastScanInputSchema.parse({})).not.toThrow(); + }); + + it("NodeStatus — accepts node_id string", () => { + const r = NodeStatusInputSchema.parse({ node_id: "cognitum-seed-1" }); + expect(r.node_id).toBe("cognitum-seed-1"); + }); + + it("VectorSearchPose — applies default k=10", () => { + const r = VectorSearchPoseInputSchema.parse({ query_embedding: [0.1, 0.2, 0.3] }); + expect(r.k).toBe(10); + }); + + it("VectorStorePose — accepts a valid 17-keypoint pose", () => { + const kpts = Array.from({ length: 17 }, (_, i) => [i * 0.05, i * 0.03] as [number, number]); + const r = VectorStorePoseInputSchema.parse({ + pose: { keypoints: kpts, confidence: 0.92 }, + node_id: "node-x", + }); + expect(r.pose.keypoints).toHaveLength(17); + }); + + it("PolicyCanAccessVitals — accepts valid vital value", () => { + const r = PolicyCanAccessVitalsInputSchema.parse({ + agent_id: "agent-007", + node_id: "node-1", + vital: "heart_rate", + }); + expect(r.vital).toBe("heart_rate"); + }); + + it("PolicyCanSubscribe — accepts valid duration_s", () => { + const r = PolicyCanSubscribeInputSchema.parse({ + agent_id: "agent-007", + topic: "ruview.vitals.get_all", + duration_s: 300, + }); + expect(r.duration_s).toBe(300); + }); + + it("PolicyRedactIdentityFields — accepts arbitrary payload record", () => { + const r = PolicyRedactIdentityFieldsInputSchema.parse({ + payload: { sta_mac: "AA:BB:CC:DD:EE:FF", n_persons: 2 }, + agent_id: "agent-007", + }); + expect(r.payload).toHaveProperty("sta_mac"); + }); +}); + +// ── 3. Constraint rejection ──────────────────────────────────────────────── + +describe("Schema constraint enforcement", () => { + it("NodeIdSchema — rejects empty string", () => { + expect(() => NodeIdSchema.parse("")).toThrow(); + }); + + it("DurationSSchema — rejects zero", () => { + expect(() => DurationSSchema.parse(0)).toThrow(); + }); + + it("DurationSSchema — rejects value > 3600", () => { + expect(() => DurationSSchema.parse(3601)).toThrow(); + }); + + it("SemanticPrimitiveKind — rejects unknown primitive", () => { + expect(() => SemanticPrimitiveKindSchema.parse("unknown_primitive")).toThrow(); + }); + + it("PosePersonResult — rejects keypoints array with wrong length", () => { + const badKpts = Array.from({ length: 5 }, () => [0, 0] as [number, number]); + expect(() => PosePersonResultSchema.parse({ keypoints: badKpts, confidence: 0.9 })).toThrow(); + }); + + it("VectorSearchPose — rejects k > 100", () => { + expect(() => + VectorSearchPoseInputSchema.parse({ query_embedding: [0.1], k: 101 }) + ).toThrow(); + }); + + it("PolicyCanAccessVitals — rejects unknown vital value", () => { + expect(() => + PolicyCanAccessVitalsInputSchema.parse({ + agent_id: "a", + node_id: "n", + vital: "temperature", + }) + ).toThrow(); + }); + + it("NodeStatus — rejects missing node_id", () => { + expect(() => NodeStatusInputSchema.parse({})).toThrow(); + }); +});