vantage-peers-mcp 2.3.4 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## [2.4.0] — 2026-05-28 — M3 iframeEmbedSessions + __VP_TOOL_RESULT__ stream marker + ack-checklist
+
+**Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+**Pi sign-off** : PI_AUTHORIZED_TASK_ID=`k1793m1qgn0zaay6r87dhvsh7187kwya` (PROD-DEPLOY-AUTHORIZED).
+**Eta sign-off** : ETA_APPROVED_TASK_ID=`k171ep964sxabbrgmb21fk9axd87ka1n` at commit `338a7b9e6130ce69dc5fe7f3e2e9ecc4648b4f6a` (Day 79 SHA-pinned).
+**Merge** : PR #545 squash `f509c8d92f0b142bc063a0e9dd070e1993cc729b`.
+
+M3 delivers the session registry and stream-marker protocol that connects the VP MCP server
+to the Gen UI iframe bridge. All marker emission is gated behind `VP_EMIT_UI_MARKERS=1`
+so production behaviour is unchanged until the bridge is deployed.
+
+### Convex schema — `iframeEmbedSessions` table
+
+NEW table `iframeEmbedSessions` in `convex/schema.ts` :
+- Fields : `sessionId` (string), `tenantId` (optional string), `origin` (string),
+  `userId` (optional string), `createdAt` (number), `lastSeenAt` (number),
+  `expiresAt` (number), `revoked` (boolean).
+- Indexes : `by_session_id` on `["sessionId"]`, `by_origin_expires` on `["origin", "expiresAt"]`.
+
+NEW `convex/iframeEmbedSessions.ts` — 4 operations :
+- `createSession` mutation — inserts a new session row.
+- `getSession` query — returns session or null (null for expired / revoked).
+- `touchSession` mutation — bumps `lastSeenAt` to now; returns bool.
+- `revokeSession` mutation — sets `revoked=true`; returns bool.
+
+### Stream marker — `mcp-server/src/ui-resources/stream-marker.ts`
+
+NEW `MARKER_START = "__VP_TOOL_RESULT__"`, `MARKER_END = "__END__"`.
+
+NEW `wrapToolResult(payload: VpToolResult): string` :
+- Validates via `VpToolResultSchema`, throws `TypeError` on schema failure.
+- Returns `__VP_TOOL_RESULT__<json>__END__`.
+
+NEW `parseToolResult(text: string): VpToolResult | null` :
+- Extracts marker substring (handles bare, embedded, surrounding text).
+- Returns validated `VpToolResult` or null on any failure (no-throw contract).
+
+### MCP tools — marker emission gated by `VP_EMIT_UI_MARKERS=1`
+
+`mcp-server/src/tools.ts` — 6 tools now append `wrapToolResult(...)` after the JSON payload
+when `VP_EMIT_UI_MARKERS=1` (default OFF) :
+
+| Tool                  | kind               |
+|-----------------------|--------------------|
+| `list_tasks`          | `tasks-table`      |
+| `list_messages`       | `messages-feed`    |
+| `get_diary`           | `diary-entry`      |
+| `list_missions`       | `mission-timeline` |
+| `list_briefing_notes` | `briefing-note`    |
+| `list_memories`       | `memory-quote`     |
+
+Change is surgical — existing return shape is preserved; marker is appended as a new line.
+
+### Ack checklist
+
+NEW `docs/M3-ACK-CHECKLIST.md` — bilingual FR/EN post-deploy verification checklist
+for Marie + Ismaël. Covers: package install, primitive reads, Shadow DOM scoping,
+stream marker emit + parse, bilingual spot check, WCAG AA (contrast + role attrs),
+default-OFF guard.
+
+### Tests
+
+15+ new vitest cases (≥264 total after M3, baseline 253 after M2) :
+- `mcp-server/src/__tests__/m3-stream-marker.test.ts` — 14 cases:
+  `wrapToolResult` ×6 valid kinds, ×2 throws on invalid, `parseToolResult` roundtrip,
+  non-marker text ×2, embedded text, malformed JSON ×2, schema rejects unknown kind ×2.
+- `convex/iframeEmbedSessions.test.ts` — 7 cases:
+  create+get, optional fields, getSession unknown, expired session null,
+  touchSession updates lastSeenAt, touchSession unknown false,
+  revokeSession marks revoked (getSession null), revokeSession unknown false.
+
+0 regression on M1+M2 suites (253/253 baseline).
+
+---
+
+## [Unreleased] — M1 SEP-1865 ui:// resources backend + M2 primitives + Zod schemas
+
+**Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+**Template VR consumed** : `gui-iframe-embed-v1` v1.0.0 (jx7bzk0x1086tgwgj2zrssk2pn87k1ga).
+
+M1 Foundation (adapted MCP-pure paradigm per Pi arbitrage Day 84) :
+- NEW `mcp-server/src/ui-resources/index.ts` : URI parser `ui://vp/v1/<primitive>?<query>` + primitive registry + handler factory.
+- NEW `mcp-server/src/ui-resources/primitives/tasks-table.ts` : M1 MVP primitive returning HTML inline (Shadow DOM scoped CSS) — WCAG AA + bilingual FR+EN.
+- `mcp-server/server-http.ts` : wired `ListResourcesRequestSchema` + `ReadResourceRequestSchema` MCP handlers on the existing McpServer instance.
+
+Tests : 14 new vitest cases (`src/__tests__/ui-resources-sep-1865.test.ts`) — URI parsing, primitive registry, render variants (empty, populated, FR), backend arg forwarding, XSS escape, error fallback, limit clamping, unknown primitive rejection. 0 regression on existing suites.
+
+### M2 — Resolve 5 Gaps + Bearer sha256 hardening (adapted MCP-pure paradigm)
+
+5 new ui:// primitives :
+- `messages-feed` (`messages:listMessages` backend — channel filter applied client-side)
+- `diary-entry` (`diary:get` single-entry + `diary:list` multi-entry backend)
+- `mission-timeline` (`missions:list` backend with fields=lite)
+- `briefing-note` (`briefingNotes:get` by noteId OR `briefingNotes:list` by topic backend)
+- `memory-quote` (`memories:listMemories` backend — supports both plain-array and paginated result shapes)
+
+Zod discriminated union schemas : `mcp-server/src/ui-resources/schemas.ts` exports `VpTaskPayloadSchema` + `VpMessagePayloadSchema` + `VpDiaryEntryPayloadSchema` + `VpMissionPayloadSchema` + `VpBriefingNotePayloadSchema` + `VpMemoryPayloadSchema` + `VpToolResultSchema` (discriminated union by `kind`). Cross-fleet ready for Mu vantage-bridge sidepanel S3 consumer.
+
+Bearer sha256 validation : Already in place since v2.3.4 DCR security fix. `mcp-server/src/auth.ts` line 275 calls `sha256Hex(token)` before every Convex lookup (layers 2 and 4). Raw token never reaches Convex. No further hardening needed in M2.
+
+Tests : 42 new vitest cases in `src/__tests__/ui-resources-m2-primitives.test.ts` (target was ≥22). Covers : PRIMITIVES registry (6 entries), each of 5 new primitives (empty + populated + FR labels + XSS escape + error fallback = 5 cases each), Zod schema roundtrip (VpToolResultSchema all 6 variants accepted, malformed rejected, individual payload schema validations). 0 regression on M1 17 cases + 194 other MCP tests (253/253 total).
+
+M3 next : Registry json-render + `__VP_TOOL_RESULT__<json>` stream marker + smoke E2E + ack-checklist + PI-SIGNED Convex prod deploy + visual ack Marie/Ismaël.
+
+## v2.3.5 — 2026-05-28
+
+**Critical hotfix** — v2.3.3 (PR #539) shipped the backend filters `createdBy` + `updatedSince` and the Zod schema exports but did NOT wire those params into the 4 list MCP tool args blocks. Pi pull-cycle quickstart `list_tasks createdBy="pi" status="review" fields="lite"` was silently dropping `createdBy` at the MCP boundary and returning all visible tasks. Auto-clamp safeguard (Day 83) also could not trigger because Zod `.default(50)` / `.default(20)` on `limit` overrode the absent-value signal before it reached the backend.
+
+Fixes:
+- `mcp-server/src/tools.ts` : 4 list tools now expose `createdBy` (`list_tasks` + `list_tasks_by_mission` only — `list_missions` + `list_briefing_notes` do not accept it backend-side) and `updatedSince` (all 4).
+- Removed `.default(50)` (3 tools) and `.default(20)` (1 tool) on `limit` so absent value reaches the backend, enabling the v2.3.3 auto-clamp safeguard.
+
+Tests : 8 new boundary-forwarding cases (`src/__tests__/list-queries-v2.3.5-wire-createdby-updatedsince.test.ts`) — verify MCP layer actually forwards new params to `convex.query` instead of dropping them. 0 regression on existing suites.
+
+Detection : Vantage-Bridge architecture review Sigma scope Day 84 — direct `grep`/`sed` inspection of `tools.ts` confirmed the gap. Backend already correct since v2.3.3 (`convex/tasks.ts:354-357`).
+
+Fix-pattern (Day 84 capitalize) : when adding a new param across backend + MCP wrapper, the test suite MUST cover not only schema validation but also the tool-handler→convex.query forwarding boundary. Schema-only tests passed cleanly in v2.3.3 while the actual feature was broken in prod.
+
+VP task : `k177tsvdxzase5sjy2qm9fdvp187kbwr`. Predecessor v2.3.3 PR #539 (`k1796s5j6jfkvkx0tn5n926ftd87jx9p`).
+
 ## v2.3.4 — 2026-05-28
 
 **Security fix** — DCR (Dynamic Client Registration) self-registration now defaults to tenant-scope only. Master scope requires explicit admin authorization (`ADMIN_DCR_TOKEN` / `BEARER_SECRET_MASTER` env var). Closes beta blocker for Marie/Iris RH onboarding identified in VP Cloud audit Day 84.
@@ -13,6 +133,28 @@ Tests: 5 new Convex security tests (`convex/oauth-dcr-security.test.ts`) + 5 new
 
 VP task: k17218rvqyncs1v6rwj3qdzfsn87jj4n. Beta unblock chain: DCR fix → 5 quick wins onboarding (seed-profiles + marie-iris-rh client + README VP Cloud + runbook + email).
 
+## v2.3.3 — 2026-05-28
+
+**Follow-up to v2.3.2 (Day 84 scope élargi)** — Extend list queries with `createdBy` + `updatedSince` filters + auto-clamp safeguard.
+
+Backend (Convex) :
+- `tasks.list` + `tasks.listByMission` : + `createdBy` (filter by task creator) + `updatedSince` (Unix ms window) + auto-clamp limit=30 when `fields="full"` and no explicit limit
+- `missions.list` : + `updatedSince` + auto-clamp (30)
+- `briefingNotes.list` : + `updatedSince` + auto-clamp (15 when fields=full)
+
+MCP wrapper :
+- 4 list tools forward the new params
+- New export `updatedSinceSchema` (positive integer ms)
+- `limit` `.default()` removed on the 4 list tools so absent limit flows to backend → enables auto-clamp
+
+Tests : 15 new MCP schema cases (`src/__tests__/list-queries-v2.3.3-createdby-updatedsince.test.ts`) + 6 new Convex round-trip cases.
+
+Pi pull cycle unblocked : `list_tasks createdBy="pi" status="review" fields="lite"` returns only Pi-dispatched tasks recently moved to review, payload 5-10× smaller.
+
+Cap fleet : 0 overflow tolérance future (auto-clamp).
+
+VP task: `k1796s5j6jfkvkx0tn5n926ftd87jx9p`. Successor of `k17e09ng1tf217n93z9m4tr0mx87hfe0` (v2.3.2 PR #537).
+
 ## v2.3.2 — 2026-05-28
 
 **Hotfix** — Expose `fields="lite"` + `status` array/aliases in MCP tool schemas (Day 82 sprint gap).

package/dist/server-http.js

@@ -25,13 +25,14 @@
  *   NODE_ENV              — set to "production" on Railway
  */
 import { readFileSync } from "node:fs";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { ConvexHttpClient } from "convex/browser";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { bearerAuthMiddleware, internalClient, masterOnlyMiddleware, sha256Base64Url, sha256Hex, } from "./src/auth.js";
 import { registerTools } from "./src/tools.js";
+import { listUiResources, readUiResource } from "./src/ui-resources/index.js";
 let pkg;
 try {
     // Source mode: server-http.ts → ./package.json = mcp-server/package.json
@@ -563,6 +564,31 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
         version: pkg.version,
     });
     registerTools(server, convex, oauthCtx);
+    // SEP-1865 ui:// resources for Generative UI primitives
+    // Uses McpServer.resource() high-level API with a ResourceTemplate so that
+    // resources/list (via listCallback) and resources/read both work.
+    // URI pattern: ui://vp/v1/{primitive}  — query params read from the URL object.
+    const uiResourceTemplate = new ResourceTemplate("ui://vp/v1/{primitive}", {
+        list: async () => ({ resources: listUiResources() }),
+    });
+    server.resource("vp-ui", uiResourceTemplate, {
+        description: "SEP-1865 VantagePeers Generative UI primitives (HTML inline, Shadow DOM scoped)",
+    }, async (uri) => {
+        const fetchConvex = async (functionName, args) => {
+            // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+            return convex.query(functionName, args);
+        };
+        const resource = await readUiResource(uri.toString(), fetchConvex);
+        return {
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: resource.mimeType,
+                    text: resource.text,
+                },
+            ],
+        };
+    });
     const transport = new WebStandardStreamableHTTPServerTransport();
     await server.connect(transport);
     return transport.handleRequest(c.req.raw);

package/dist/src/tools.d.ts

@@ -96,6 +96,7 @@ export declare const fieldsSchema: z.ZodEnum<{
     lite: "lite";
     full: "full";
 }>;
+export declare const updatedSinceSchema: z.ZodNumber;
 export interface ParsedConvexError {
     code: string;
     message: string;

package/dist/src/tools.js

@@ -10,6 +10,36 @@
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { checkFromAllowed, checkNamespaceRead, checkNamespaceWrite, isMasterScope, } from "./auth.js";
+import { wrapToolResult } from "./ui-resources/stream-marker.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// VP_EMIT_UI_MARKERS gate
+//
+// When VP_EMIT_UI_MARKERS=1 the 6 list/get tools that have a matching
+// ui:// primitive append a __VP_TOOL_RESULT__<json>__END__ marker after the
+// existing JSON payload. The Gen UI iframe bridge detects this marker and
+// renders the structured primitive inline. Default is OFF so prod behaviour
+// is unchanged.
+// ─────────────────────────────────────────────────────────────────────────────
+const UI_MARKERS_ENABLED = process.env.VP_EMIT_UI_MARKERS === "1" ||
+    process.env.VP_EMIT_UI_MARKERS === "true";
+/**
+ * Append a stream marker to a text response when UI markers are enabled.
+ * `buildPayload` is called only when the flag is ON to avoid any overhead.
+ */
+function appendMarkerIfEnabled(text, buildPayload) {
+    if (!UI_MARKERS_ENABLED)
+        return text;
+    try {
+        const payload = buildPayload();
+        if (payload === null)
+            return text;
+        return `${text}\n${wrapToolResult(payload)}`;
+    }
+    catch {
+        // Never break the primary response — marker emission is best-effort.
+        return text;
+    }
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Pre-flight content size guard
 //
@@ -162,6 +192,14 @@ export const fieldsSchema = z
     .describe('Field projection — "lite" returns compact fields only ' +
     '(typical 5-10× smaller payload for large list scans), ' +
     '"full" (default) returns the full document.');
+// v2.3.3 — Unix timestamp ms filter for "updated since".
+// Pass `Date.now() - 24*60*60*1000` for "last 24h" pattern.
+export const updatedSinceSchema = z
+    .number()
+    .int()
+    .positive()
+    .describe("Unix timestamp (ms) — return only rows whose updatedAt >= this value. " +
+    "Typical usage: Date.now() - 24*60*60*1000 for last-24h window.");
 const mandateStatusSchema = z
     .enum(["requested", "accepted", "in_progress", "delivered", "settled"])
     .describe("Mandate lifecycle status");
@@ -738,13 +776,24 @@ export function registerTools(server, convex, oauthCtx) {
                 type,
                 limit: limit ?? 20,
             });
+            const rawList = Array.isArray(memories)
+                ? memories
+                : Array.isArray(memories?.page)
+                    ? memories.page
+                    : [];
+            const baseText = JSON.stringify(memories, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "memory-quote",
+                items: rawList.map((m) => ({
+                    _id: m._id,
+                    namespace: m.namespace,
+                    type: m.type,
+                    content: m.content,
+                    score: m.score,
+                })),
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(memories, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1017,13 +1066,21 @@ export function registerTools(server, convex, oauthCtx) {
                 from,
                 limit: limit ?? 100,
             });
+            const baseText = JSON.stringify(messages, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "messages-feed",
+                items: Array.isArray(messages)
+                    ? messages.map((m) => ({
+                        _id: m._id,
+                        from: m.from,
+                        channel: m.channel,
+                        content: m.content,
+                        createdAt: m.createdAt,
+                    }))
+                    : [],
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(messages, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1141,28 +1198,42 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum number of tasks to return (default 50)"),
+            .describe("Maximum number of tasks to return. Default 50 with fields=lite, auto-clamped to 30 when fields=full and no explicit limit (overflow protection)."),
         fields: fieldsSchema
             .optional()
             .describe('Field projection ("lite"|"full")'),
-    }, async ({ assignedTo, assignedToInstance, status, project, limit, fields, }) => {
+        createdBy: assigneeSchema
+            .optional()
+            .describe("Filter by task creator (e.g. 'pi' to find Pi-dispatched tasks)"),
+        updatedSince: updatedSinceSchema.optional(),
+    }, async ({ assignedTo, assignedToInstance, status, project, limit, fields, createdBy, updatedSince, }) => {
         try {
             const tasks = await convex.query("tasks:list", {
                 assignedTo,
                 assignedToInstance,
                 status,
                 project,
-                limit: limit ?? 50,
+                limit,
                 fields,
-            });
+                createdBy,
+                updatedSince,
+            });
+            const baseText = JSON.stringify(tasks, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "tasks-table",
+                items: Array.isArray(tasks)
+                    ? tasks.map((t) => ({
+                        _id: t._id,
+                        title: t.title,
+                        status: t.status,
+                        priority: t.priority,
+                        assignedTo: t.assignedTo,
+                        _creationTime: t._creationTime,
+                    }))
+                    : [],
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(tasks, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1470,18 +1541,23 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum number of tasks to return (default 50)"),
+            .describe("Maximum number of tasks to return. Default 50 with fields=lite, auto-clamped to 30 when fields=full and no explicit limit."),
         fields: fieldsSchema
             .optional()
             .describe('Field projection ("lite"|"full")'),
-    }, async ({ missionId, status, limit, fields }) => {
+        createdBy: assigneeSchema
+            .optional()
+            .describe("Filter by task creator"),
+        updatedSince: updatedSinceSchema.optional(),
+    }, async ({ missionId, status, limit, fields, createdBy, updatedSince }) => {
         try {
             const tasks = await convex.query("tasks:listByMission", {
                 missionId: missionId,
                 status,
-                limit: limit ?? 50,
+                limit,
                 fields,
+                createdBy,
+                updatedSince,
             });
             return {
                 content: [
@@ -1565,27 +1641,38 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum number of missions to return (default 50)"),
+            .describe("Maximum number of missions to return. Default 50 with fields=lite, auto-clamped to 30 when fields=full and no explicit limit."),
         fields: fieldsSchema
             .optional()
             .describe('Field projection ("lite"|"full")'),
-    }, async ({ project, pilot, status, limit, fields }) => {
+        updatedSince: updatedSinceSchema.optional(),
+    }, async ({ project, pilot, status, limit, fields, updatedSince }) => {
         try {
             const missions = await convex.query("missions:list", {
                 project,
                 pilot,
                 status,
-                limit: limit ?? 50,
+                limit,
                 fields,
-            });
+                updatedSince,
+            });
+            const baseText = JSON.stringify(missions, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "mission-timeline",
+                items: Array.isArray(missions)
+                    ? missions.map((m) => ({
+                        _id: m._id,
+                        name: m.name,
+                        project: m.project,
+                        status: m.status,
+                        pilot: m.pilot,
+                        priority: m.priority,
+                        progress: m.progress,
+                    }))
+                    : [],
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(missions, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1740,13 +1827,24 @@ export function registerTools(server, convex, oauthCtx) {
                 date,
                 orchestrator,
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(entry, null, 2),
+            const baseText = JSON.stringify(entry, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => {
+                if (!entry)
+                    return null;
+                return {
+                    kind: "diary-entry",
+                    item: {
+                        _id: entry._id,
+                        date: entry.date,
+                        orchestrator: entry.orchestrator,
+                        content: entry.content,
+                        highlights: entry.highlights,
+                        blockers: entry.blockers,
                     },
-                ],
+                };
+            });
+            return {
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1899,25 +1997,40 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(100)
             .optional()
-            .default(20)
-            .describe("Maximum notes to return (default 20)"),
+            .describe("Maximum notes to return. Default 20 with fields=lite, auto-clamped to 15 when fields=full and no explicit limit."),
         fields: fieldsSchema
             .optional()
             .describe('Field projection ("lite"|"full")'),
-    }, async ({ topic, limit, fields }) => {
+        updatedSince: updatedSinceSchema.optional(),
+    }, async ({ topic, limit, fields, updatedSince }) => {
         try {
             const notes = await convex.query("briefingNotes:list", {
                 topic,
-                limit: limit ?? 20,
+                limit,
                 fields,
+                updatedSince,
+            });
+            const baseText = JSON.stringify(notes, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => {
+                const items = Array.isArray(notes) ? notes : [];
+                if (items.length === 0)
+                    return null;
+                // Emit the first note as a briefing-note item for the primitive renderer.
+                const first = items[0];
+                return {
+                    kind: "briefing-note",
+                    item: {
+                        _id: first._id,
+                        topic: first.topic,
+                        title: first.title,
+                        participants: first.participants,
+                        content: first.content,
+                        createdBy: first.createdBy,
+                    },
+                };
             });
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(notes, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {

package/dist/src/ui-resources/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SEP-1865 ui:// resources for VantagePeers Generative UI.
+ *
+ * URI pattern : ui://vp/v1/<primitive>?<query>
+ * Examples :
+ *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
+ *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
+ *
+ * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
+ * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
+ *
+ * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
+ * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
+ *
+ * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
+ * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+ */
+export type UiResourceParsed = {
+    primitive: string;
+    query: URLSearchParams;
+};
+export declare function parseUiUri(uri: string): UiResourceParsed | null;
+export declare const PRIMITIVES: readonly ["tasks-table", "messages-feed", "diary-entry", "mission-timeline", "briefing-note", "memory-quote"];
+export type Primitive = (typeof PRIMITIVES)[number];
+export declare const PRIMITIVE_DESCRIPTIONS: Record<Primitive, string>;
+export declare function listUiResources(): Array<{
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}>;
+export declare function readUiResource(uri: string, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<{
+    uri: string;
+    mimeType: string;
+    text: string;
+}>;

package/dist/src/ui-resources/index.js

@@ -0,0 +1,100 @@
+/**
+ * SEP-1865 ui:// resources for VantagePeers Generative UI.
+ *
+ * URI pattern : ui://vp/v1/<primitive>?<query>
+ * Examples :
+ *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
+ *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
+ *
+ * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
+ * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
+ *
+ * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
+ * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
+ *
+ * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
+ * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+ */
+import { renderBriefingNote } from "./primitives/briefing-note.js";
+import { renderDiaryEntry } from "./primitives/diary-entry.js";
+import { renderMemoryQuote } from "./primitives/memory-quote.js";
+import { renderMessagesFeed } from "./primitives/messages-feed.js";
+import { renderMissionTimeline } from "./primitives/mission-timeline.js";
+import { renderTasksTable } from "./primitives/tasks-table.js";
+// URI parser : ui://vp/v1/<primitive>?<query>
+const UI_URI_RE = /^ui:\/\/vp\/v1\/([a-z][a-z0-9-]*)(?:\?(.*))?$/;
+export function parseUiUri(uri) {
+    const match = UI_URI_RE.exec(uri);
+    if (!match)
+        return null;
+    const primitive = match[1];
+    const queryString = match[2] ?? "";
+    return {
+        primitive,
+        query: new URLSearchParams(queryString),
+    };
+}
+// Primitive registry — M1 ships 1 (tasks-table). M2 adds 5 more.
+export const PRIMITIVES = [
+    "tasks-table",
+    "messages-feed",
+    "diary-entry",
+    "mission-timeline",
+    "briefing-note",
+    "memory-quote",
+];
+export const PRIMITIVE_DESCRIPTIONS = {
+    "tasks-table": "Render a compact table of tasks. Query params: assignedTo, status, fields=lite|full, limit. Mirrors list_tasks tool semantics.",
+    "messages-feed": "Render a chronological feed of VantagePeers messages. Query params: from, channel, limit, lang.",
+    "diary-entry": "Render a single diary entry or list of recent entries. Query params: date (YYYY-MM-DD), orchestrator, limit, lang.",
+    "mission-timeline": "Render a missions timeline. Query params: pilot, project, status, limit, lang.",
+    "briefing-note": "Render briefing note details. Query params: noteId or (topic + limit), lang.",
+    "memory-quote": "Render memory quotes from a namespace. Query params: namespace, type, limit, lang.",
+};
+// Resource list — returned by resources/list MCP handler
+export function listUiResources() {
+    return PRIMITIVES.map((p) => ({
+        uri: `ui://vp/v1/${p}`,
+        name: p,
+        description: PRIMITIVE_DESCRIPTIONS[p],
+        mimeType: "text/html",
+    }));
+}
+// Resource read — dispatched by primitive name. Returns HTML inline.
+export async function readUiResource(uri, fetchConvex) {
+    const parsed = parseUiUri(uri);
+    if (!parsed) {
+        throw new Error(`[VP UI Resources] Invalid ui:// URI: ${uri}`);
+    }
+    if (!PRIMITIVES.includes(parsed.primitive)) {
+        throw new Error(`[VP UI Resources] Unknown primitive: ${parsed.primitive}. Available: ${PRIMITIVES.join(", ")}`);
+    }
+    let html;
+    switch (parsed.primitive) {
+        case "tasks-table":
+            html = await renderTasksTable(parsed.query, fetchConvex);
+            break;
+        case "messages-feed":
+            html = await renderMessagesFeed(parsed.query, fetchConvex);
+            break;
+        case "diary-entry":
+            html = await renderDiaryEntry(parsed.query, fetchConvex);
+            break;
+        case "mission-timeline":
+            html = await renderMissionTimeline(parsed.query, fetchConvex);
+            break;
+        case "briefing-note":
+            html = await renderBriefingNote(parsed.query, fetchConvex);
+            break;
+        case "memory-quote":
+            html = await renderMemoryQuote(parsed.query, fetchConvex);
+            break;
+        default:
+            throw new Error(`[VP UI Resources] Unimplemented primitive: ${parsed.primitive}`);
+    }
+    return {
+        uri,
+        mimeType: "text/html",
+        text: html,
+    };
+}