@a-company/paradigm 3.34.0 → 3.44.0

package/dist/symphony-QWOEKZMC.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+import {
+  approveFileRequest,
+  buildMessage,
+  cleanStaleAgents,
+  createThread,
+  denyFileRequest,
+  discoverClaudeCodeSessions,
+  expireOldRequests,
+  getMyIdentity,
+  getThreadMessages,
+  isAgentAsleep,
+  listAgents,
+  listFileRequests,
+  listThreads,
+  loadThread,
+  readInbox,
+  resolveAgentIdentity,
+  resolveThread,
+  routeMessage
+} from "./chunk-SOBTKFSP.js";
+import "./chunk-ZXMDA7VB.js";
+
+// src/platform-server/routes/symphony.ts
+import { Router } from "express";
+function createSymphonyRouter(projectDir, broadcast) {
+  const router = Router();
+  router.get("/agents", (_req, res) => {
+    try {
+      cleanStaleAgents();
+      const agents = listAgents();
+      const discovered = discoverClaudeCodeSessions();
+      const agentIds = new Set(agents.map((a) => a.id));
+      for (const d of discovered) {
+        if (!agentIds.has(d.id)) agents.push(d);
+      }
+      const result = agents.map((a) => ({
+        id: a.id,
+        name: a.name,
+        project: a.project,
+        role: a.role,
+        status: isAgentAsleep(a) ? "asleep" : "awake",
+        lastPoll: a.lastPoll,
+        startedAt: a.startedAt,
+        statusBlurb: a.statusBlurb
+      }));
+      res.json({ agents: result });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to list agents", detail: String(err) });
+    }
+  });
+  router.get("/agents/me", (_req, res) => {
+    try {
+      const identity = getMyIdentity(projectDir);
+      res.json({ identity: identity || null });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to get identity", detail: String(err) });
+    }
+  });
+  router.get("/threads", (req, res) => {
+    try {
+      const statusParam = req.query.status;
+      let status;
+      if (statusParam === "active" || statusParam === "resolved") {
+        status = statusParam;
+      }
+      const threads = listThreads(status);
+      const result = threads.map((t) => ({
+        id: t.id,
+        topic: t.topic,
+        status: t.status,
+        participants: t.participants.map((p) => ({ id: p.id, name: p.name, type: p.type })),
+        messageCount: t.messageCount,
+        lastActivity: t.lastActivity,
+        decision: t.decision
+      }));
+      res.json({ threads: result });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to list threads", detail: String(err) });
+    }
+  });
+  router.get("/threads/:threadId", (req, res) => {
+    try {
+      const { threadId } = req.params;
+      const thread = loadThread(threadId);
+      if (!thread) {
+        res.status(404).json({ error: `Thread not found: ${threadId}` });
+        return;
+      }
+      const messages = getThreadMessages(threadId);
+      const symbolsDiscussed = /* @__PURE__ */ new Set();
+      for (const msg of messages) {
+        for (const sym of msg.symbols) symbolsDiscussed.add(sym);
+      }
+      res.json({
+        thread: {
+          id: thread.id,
+          topic: thread.topic,
+          status: thread.status,
+          participants: thread.participants.map((p) => ({ id: p.id, name: p.name, type: p.type })),
+          messageCount: thread.messageCount,
+          lastActivity: thread.lastActivity,
+          decision: thread.decision
+        },
+        messages: messages.map((m) => ({
+          id: m.id,
+          sender: { id: m.sender.id, name: m.sender.name, type: m.sender.type },
+          intent: m.intent,
+          text: m.content.text,
+          timestamp: m.timestamp,
+          symbols: m.symbols,
+          diff: m.content.diff,
+          decision: m.content.decision,
+          recipients: m.recipients?.map((r) => ({ id: r.id, name: r.name }))
+        })),
+        symbolsDiscussed: [...symbolsDiscussed]
+      });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to load thread", detail: String(err) });
+    }
+  });
+  router.post("/threads/:threadId/resolve", (req, res) => {
+    try {
+      const { threadId } = req.params;
+      const { decision } = req.body;
+      const success = resolveThread(threadId, decision);
+      if (!success) {
+        res.status(404).json({ error: `Thread not found: ${threadId}` });
+        return;
+      }
+      if (broadcast) {
+        broadcast({ type: "symphony:thread_resolved", threadId, decision });
+      }
+      res.json({ resolved: true, threadId, decision });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to resolve thread", detail: String(err) });
+    }
+  });
+  router.post("/messages", (req, res) => {
+    try {
+      const { intent, text, threadRoot, recipients, symbols, diff, decision } = req.body;
+      if (!intent || !text) {
+        res.status(400).json({ error: "intent and text are required" });
+        return;
+      }
+      const agentId = resolveAgentIdentity(projectDir);
+      const sender = {
+        id: `human/${agentId}`,
+        name: "Human (Platform UI)",
+        type: "human"
+      };
+      let effectiveThreadRoot = threadRoot;
+      let threadCreated = false;
+      if (!threadRoot) {
+        const topic = text.length > 60 ? text.slice(0, 60) + "..." : text;
+        const thread = createThread(topic, sender);
+        effectiveThreadRoot = thread.id;
+        threadCreated = true;
+      }
+      let resolvedRecipients;
+      if (recipients && recipients.length > 0) {
+        const allAgents = listAgents();
+        resolvedRecipients = recipients.map((id) => {
+          const agent = allAgents.find((a) => a.id === id);
+          if (agent) return { id: agent.id, name: agent.name, type: "agent" };
+          return { id, name: id, type: "agent" };
+        });
+      }
+      const message = buildMessage({
+        sender,
+        recipients: resolvedRecipients,
+        intent,
+        text,
+        threadRoot: effectiveThreadRoot,
+        symbols,
+        diff,
+        decision
+      });
+      const deliveryCount = routeMessage(message);
+      if (broadcast) {
+        broadcast({
+          type: "symphony:message",
+          message: {
+            id: message.id,
+            sender: { id: sender.id, name: sender.name, type: sender.type },
+            intent: message.intent,
+            text: message.content.text,
+            timestamp: message.timestamp,
+            symbols: message.symbols,
+            diff: message.content.diff,
+            decision: message.content.decision
+          },
+          threadId: effectiveThreadRoot
+        });
+      }
+      res.json({
+        sent: true,
+        messageId: message.id,
+        threadId: effectiveThreadRoot,
+        threadCreated,
+        deliveredTo: deliveryCount
+      });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to send message", detail: String(err) });
+    }
+  });
+  router.get("/inbox", (_req, res) => {
+    try {
+      const agentId = resolveAgentIdentity(projectDir);
+      const messages = readInbox(agentId);
+      res.json({
+        agentId,
+        messages: messages.map((m) => ({
+          id: m.id,
+          sender: { id: m.sender.id, name: m.sender.name, type: m.sender.type },
+          intent: m.intent,
+          text: m.content.text,
+          timestamp: m.timestamp,
+          threadRoot: m.threadRoot,
+          symbols: m.symbols
+        }))
+      });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to read inbox", detail: String(err) });
+    }
+  });
+  router.get("/file-requests", (req, res) => {
+    try {
+      expireOldRequests();
+      const statusParam = req.query.status;
+      let status;
+      if (statusParam === "pending" || statusParam === "approved" || statusParam === "denied" || statusParam === "expired") {
+        status = statusParam;
+      }
+      const requests = listFileRequests(status);
+      const result = requests.map((r) => ({
+        requestId: r.request.requestId,
+        filePath: r.request.filePath,
+        reason: r.request.reason,
+        requester: { id: r.request.requester.id, name: r.request.requester.name },
+        urgency: r.request.urgency,
+        snippet: r.request.snippet,
+        status: r.status,
+        createdAt: r.createdAt,
+        resolvedAt: r.resolvedAt,
+        denyReason: r.denyReason
+      }));
+      res.json({ fileRequests: result });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to list file requests", detail: String(err) });
+    }
+  });
+  router.post("/file-requests/:requestId/action", (req, res) => {
+    try {
+      const { requestId } = req.params;
+      const { action, reason } = req.body;
+      if (!action) {
+        res.status(400).json({ error: "action is required" });
+        return;
+      }
+      if (action === "deny") {
+        const success = denyFileRequest(requestId, reason);
+        res.json({ success, requestId, action: "denied", reason });
+        return;
+      }
+      const redact = action === "approve-redacted";
+      const result = approveFileRequest(requestId, projectDir, redact);
+      if (!result.success) {
+        res.status(400).json({ success: false, requestId, error: result.error });
+        return;
+      }
+      res.json({
+        success: true,
+        requestId,
+        action: redact ? "approved-redacted" : "approved",
+        filePath: result.delivery?.filePath,
+        size: result.delivery?.size
+      });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to handle file request", detail: String(err) });
+    }
+  });
+  router.get("/status", (_req, res) => {
+    try {
+      cleanStaleAgents();
+      const agents = listAgents();
+      const awake = agents.filter((a) => !isAgentAsleep(a)).length;
+      const threads = listThreads("active");
+      const agentId = resolveAgentIdentity(projectDir);
+      const unread = readInbox(agentId);
+      const pendingRequests = listFileRequests("pending");
+      res.json({
+        agentCount: agents.length,
+        awakeCount: awake,
+        asleepCount: agents.length - awake,
+        activeThreadCount: threads.length,
+        unreadCount: unread.length,
+        pendingFileRequests: pendingRequests.length
+      });
+    } catch (err) {
+      res.status(500).json({ error: "Failed to get status", detail: String(err) });
+    }
+  });
+  return router;
+}
+export {
+  createSymphonyRouter
+};

package/dist/{team-VH3HYABB.js → team-HGLJXWQG.js}

@@ -8,17 +8,17 @@ import {
   teamModelsCommand,
   teamResetCommand,
   teamStatusCommand
-} from "./chunk-UQNTJ5VB.js";
-import "./chunk-3BGSDKWD.js";
-import "./chunk-6QC3YGB6.js";
-import "./chunk-J26YQVAK.js";
+} from "./chunk-HIKKOCXY.js";
+import "./chunk-QWA26UNO.js";
+import "./chunk-J4E6K5MG.js";
 import "./chunk-PBHIFAL4.js";
-import "./chunk-5SXMV4SP.js";
+import "./chunk-FS3WTUHY.js";
+import "./chunk-6QC3YGB6.js";
 import "./chunk-PMXRGPRQ.js";
 import "./chunk-MW5DMGBB.js";
 import "./chunk-5JGJACDU.js";
-import "./chunk-CTF6RHKG.js";
-import "./chunk-VUSCJJ4A.js";
+import "./chunk-ZGUAAVMA.js";
+import "./chunk-EDOAWN7J.js";
 import "./chunk-IRKUEJVW.js";
 import "./chunk-ZXMDA7VB.js";
 export {

package/dist/{timeline-RKXNRMKF.js → timeline-ANC7LVDL.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   loadLoreEntries
-} from "./chunk-BRILIG7Z.js";
+} from "./chunk-QIOCFXDQ.js";
 import "./chunk-ZXMDA7VB.js";
 
 // src/commands/lore/timeline.ts

package/dist/{triage-GJ6GK647.js → triage-IZ4MDYNB.js}

@@ -6,10 +6,10 @@ import {
   StatsCalculator,
   TimelineBuilder,
   loadAllSeedPatterns
-} from "./chunk-3BAMPB6I.js";
+} from "./chunk-ZSYVKSY6.js";
 import {
   SentinelStorage
-} from "./chunk-R2SGQ22F.js";
+} from "./chunk-FKJUBQU3.js";
 import "./chunk-ZXMDA7VB.js";
 
 // src/commands/triage/index.ts

package/dist/university-content/courses/.purpose

@@ -1,5 +1,5 @@
 name: university-courses
-description: Course content for Paradigm University — 5 courses, 49 lessons. Each lesson is mapped to the Paradigm concepts it teaches so that ripple analysis can identify which lessons need updating when a concept changes.
+description: Course content for Paradigm University — 5 courses, 50 lessons. Each lesson is mapped to the Paradigm concepts it teaches so that ripple analysis can identify which lessons need updating when a concept changes.
 
 components:
   # PARA 101: Foundations (8 lessons)
@@ -305,3 +305,9 @@ components:
     file: para-501.json
     tags: [course-content, para-501]
     references: ["#lore-system"]
+
+  para-501-platform-agent-ui:
+    description: "Platform & Agent-Driven UI — paradigm serve, MCP→HTTP→WS→browser pipeline, 5 agent tools, conflict resolution, presence, visual treatment"
+    file: para-501.json
+    tags: [course-content, para-501]
+    references: ["#PlatformServer", "#PlatformWebSocket", "#AgentPresenceManager", "#UserStateTracker", "#AgentCommandRoute", "#PlatformTools", "#AgentStore", "#AgentToast", "#AgentCallout"]

package/dist/university-content/courses/para-501.json

@@ -789,6 +789,172 @@
           "explanation": "`paradigm_lore_search` supports combining filters: `tag` for arc prefix matching, `type` for entry type, and `symbol` for symbol references. These filters combine (AND logic), so you get only retro entries in the auth-hardening arc that touch the payment service. The assessment tools (B) are deprecated. Using `tags` array (C) uses OR logic, not AND. General search (D) searches the symbol index, not lore content."
         }
       ]
+    },
+    {
+      "id": "symphony-a-mail",
+      "title": "Symphony: Multi-Agent Messaging with The Score",
+      "content": "## Agents Need to Talk\n\nUntil now, every Paradigm agent has worked in isolation. A Claude Code session modifying the backend has no awareness of what the session working on the frontend is doing. Two developers on the same team, each with their own AI assistant, have no way for those assistants to coordinate — even when they are working on the same project at the same time.\n\nSymphony changes this. It is Paradigm's multi-agent, multi-human collaborative intelligence layer. And its foundation is The Score: a lightweight, file-based messaging protocol that gives every Claude Code session its own mailbox.\n\n## The Metaphor: Email for AI Agents\n\nThe Score works exactly like email. Each agent has an identity, an inbox, and an outbox. Messages are delivered as JSONL files on the filesystem. Agents poll for new messages on a timer. There is no persistent server, no WebSocket connection, and no cloud dependency. If two agents are running on the same machine, they can message each other through nothing more than file reads and writes.\n\nThis simplicity is deliberate. The Score is the CLI-only foundation of Symphony — it works with zero dependencies beyond the Paradigm CLI. No Conductor, no Sentinel, no network configuration. The only requirement is that agents are running on the same machine (or connected via a lightweight TCP relay for cross-machine scenarios).\n\n## Agent Identity and Discovery\n\nEvery Claude Code session that participates in The Score has a stable identity. The identity is derived from the project directory and the agent's role — for example, `a-paradigm/backend` or `a-kamiki/frontend`. This deterministic naming means the same project opened in the same context always gets the same identity, even across session restarts.\n\nWhen you run `paradigm symphony join`, the CLI discovers all Claude Code sessions on the current machine and connects them into a mail network. Each session gets a mailbox directory at `~/.paradigm/score/agents/{agent-id}/` containing four files:\n\n- **`inbox.jsonl`** — Messages waiting for this agent, one per line, append-only\n- **`outbox.jsonl`** — Replies from this agent, append-only\n- **`ack.json`** — The ID of the last acknowledged message (for garbage collection)\n- **`identity.json`** — Agent ID, project, role, PID, and session start time\n\nThe JSONL format — one JSON object per line — makes appending atomic and parsing trivial. No file locking, no corruption risk from concurrent writes, no binary format to decode.\n\n## Messaging and Threading\n\nMessages in The Score carry structured metadata beyond plain text. Every message has an **intent** that classifies its purpose:\n\n| Intent | Meaning |\n|---|---|\n| `question` | Asking for information from other agents |\n| `context` | Providing background or context |\n| `proposal` | Proposing an action or fix |\n| `action` | Announcing an action the agent took |\n| `decision` | Recording a decision |\n| `alert` | Forwarding a Sentinel alert |\n| `approval` / `rejection` | Responding to a proposal |\n| `handoff` | Transferring responsibility to another agent |\n| `fileRequest` | Requesting a file from another agent |\n| `fileDelivery` | Delivering a requested file |\n\nIntents serve two purposes. First, they give the receiving agent structured context about what kind of response is expected — a question needs an answer, a proposal needs approval or rejection, a decision needs acknowledgment. Second, they feed into Lore: when a message has `intent: decision`, Symphony can automatically record it as a lore entry.\n\nMessages belong to **threads**. A thread starts when the first message on a topic is sent (with no `parentId`). Subsequent replies reference the thread root, building a conversation tree. Thread state is tracked in `~/.paradigm/score/threads/{thread-id}.json`, which records the topic, participants, message count, and last activity timestamp.\n\n## The File Pipeline\n\nAgents often need to share files — a type definition, an API contract, a configuration file. The Score's file pipeline enables this with a critical security constraint: **every file transfer requires explicit human approval**.\n\nThe flow works like this: Agent A sends a `fileRequest` message specifying the file path, a reason, and the target agent. The request appears in the owning human's terminal (via `paradigm symphony requests`). The human reviews and either approves, denies, or approves with redaction (stripping sensitive lines). Only after human approval does the file content get written to the requester's inbox.\n\nTrust configuration lives in `~/.paradigm/score/trust.yaml`. You can define auto-approve patterns for trusted users (`docs/**`, `*.md`) and never-approve patterns for sensitive files (`.env*`, `*.key`, `*.pem`, `**/secrets/**`). The never-approve list is enforced absolutely — even clicking approve on a `.env` file will be denied by the system. File requests expire after one hour without action, and all transfers are logged.\n\n## /loop: The Agent Heartbeat\n\nThe glue that makes The Score work is `/loop`. Each Claude Code session runs `/loop 10s paradigm_symphony_poll`, which polls the inbox every 10 seconds for new messages. The `paradigm_symphony_poll` MCP tool reads `inbox.jsonl`, formats messages as structured prompts the agent can reason about, and suggests actions.\n\nWithout `/loop`, messages would accumulate in the inbox with nobody reading them. The loop is the heartbeat — it keeps agents responsive. When an agent processes a message and replies via `paradigm_symphony_send`, the reply goes to `outbox.jsonl`. A mail router (or Conductor, in later phases) picks up outbox messages and delivers them to the appropriate inbox files.\n\nThe convenience command `paradigm symphony join` combines registration and loop setup in one step — it registers the session's identity and starts the polling loop automatically.\n\n## Thread Resolution and Lore Integration\n\nConversation threads are not meant to live forever. When a thread reaches a conclusion, any participant (human or agent) can resolve it with `paradigm symphony resolve <thread-id>`. Resolution triggers an automatic lore entry that captures the full conversation: topic, participants, decisions made, actions taken, and symbols discussed.\n\nThis is the bridge between ephemeral conversation and permanent project memory. A 15-minute exchange between three agents about a serialization bug becomes a searchable lore entry tagged with the relevant symbols and arc. The next developer encountering a similar issue can find the conversation, the decision, and the fix — all linked together.\n\n## CLI Commands\n\nThe `paradigm symphony` command group provides the complete human interface:\n\n- `paradigm symphony whoami` — Show this agent's identity and linked peers\n- `paradigm symphony list` — List all known agents with status (awake/asleep) and location\n- `paradigm symphony join` — Discover and connect Claude Code sessions on this machine\n- `paradigm symphony join --remote <ip>` — Connect to a remote machine's mail server\n- `paradigm symphony send \"message\"` — Broadcast to all linked agents\n- `paradigm symphony send --to <agent> \"message\"` — Direct message to a specific agent\n- `paradigm symphony send --thread <id> \"message\"` — Reply to an existing thread\n- `paradigm symphony read` — Show unread messages\n- `paradigm symphony threads` — List active threads\n- `paradigm symphony resolve <id>` — Resolve a thread, creating a lore entry\n- `paradigm symphony status` — Network overview (agents, threads, unread count)\n\nFor the file pipeline: `paradigm symphony request`, `paradigm symphony requests`, `paradigm symphony approve`, and `paradigm symphony deny`.\n\n## MCP Tools for Agent Participation\n\nSix MCP tools power agent-side Symphony participation:\n\n- **`paradigm_symphony_poll`** — The heartbeat. Reads inbox, returns formatted messages and thread summaries. Called by `/loop`.\n- **`paradigm_symphony_send`** — Send a message with intent, text, optional symbols, diff, or decision. Writes to outbox.\n- **`paradigm_symphony_status`** — Overview of the local network: agents, threads, Sentinel endpoint.\n- **`paradigm_symphony_thread`** — Get full context of a conversation thread with messages, participants, and extracted decisions.\n- **`paradigm_symphony_request_file`** — Request a file from another agent. Returns immediately with `pending` status; delivery arrives via future poll.\n- **`paradigm_symphony_approve_file`** — Approve or deny a pending file request after human confirmation.\n\nThese tools compose naturally with existing Paradigm workflows. An agent can poll for messages, discover a question about `#payment-serializer`, call `paradigm_ripple` to check impact, and respond with full context — all within a single `/loop` cycle.",
+      "keyConcepts": [
+        "The Score is Symphony's CLI-only foundation — file-based messaging between agents with zero dependencies beyond the Paradigm CLI",
+        "Agent identity is derived from project directory + role (e.g., a-paradigm/backend), stable across session restarts",
+        "Mailbox protocol uses JSONL files: inbox.jsonl (incoming), outbox.jsonl (replies), ack.json (last acknowledged), identity.json (agent metadata)",
+        "Messages carry structured intents (question, proposal, decision, action, alert, etc.) that classify purpose and drive Lore integration",
+        "Threads group related messages into conversations, tracked in ~/.paradigm/score/threads/{thread-id}.json",
+        "The file pipeline requires explicit human approval for every file transfer, with configurable trust levels and a hard deny list for sensitive files",
+        "/loop is the agent heartbeat — each session runs /loop 10s paradigm_symphony_poll to stay responsive to incoming messages",
+        "Thread resolution via paradigm symphony resolve triggers automatic lore entry creation, bridging ephemeral conversation to permanent project memory",
+        "Six MCP tools: paradigm_symphony_poll, paradigm_symphony_send, paradigm_symphony_status, paradigm_symphony_thread, paradigm_symphony_request_file, paradigm_symphony_approve_file",
+        "paradigm symphony join discovers Claude Code sessions on the local machine; paradigm symphony join --remote <ip> extends to remote machines via TCP"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "You have three Claude Code sessions open on your machine: one working on the core library, one on the backend API, and one on the frontend. You want them to communicate. What is the correct setup sequence?",
+          "choices": {
+            "A": "Start a Sentinel hub, then connect each session to the WebSocket endpoint",
+            "B": "Install Conductor, which automatically links all sessions on the machine",
+            "C": "Run `paradigm symphony join` to discover and connect the sessions, then run `/loop 10s paradigm_symphony_poll` in each session",
+            "D": "Create a `.paradigm-workspace` file listing all three projects — workspace linking enables messaging",
+            "E": "Run `paradigm team orchestrate` which automatically sets up inter-agent communication"
+          },
+          "correct": "C",
+          "explanation": "The Score is the CLI-only foundation that requires no Conductor, no Sentinel, and no workspace setup. `paradigm symphony join` discovers Claude Code sessions on the machine and creates mailboxes. Then each session needs `/loop 10s paradigm_symphony_poll` to poll for incoming messages. Conductor (B) auto-links sessions but is not required — The Score works standalone."
+        },
+        {
+          "id": "q2",
+          "question": "An agent sends a message with `intent: 'decision'` and the text 'Use Redis for session storage instead of in-memory.' What happens beyond normal message delivery?",
+          "choices": {
+            "A": "The message is blocked — only humans can make decisions",
+            "B": "Symphony automatically records a lore entry of type `decision` with the message text, linking it to the conversation thread and referenced symbols",
+            "C": "The message is flagged for human review before delivery",
+            "D": "Nothing special — intent is informational only and has no side effects",
+            "E": "The decision is written to `.paradigm/config.yaml` as a project setting"
+          },
+          "correct": "B",
+          "explanation": "Messages with `intent: decision` trigger automatic Lore integration. Symphony records a lore entry with the decision text, links it to the conversation thread, and tags it with referenced symbols. This bridges ephemeral conversation to permanent project memory without manual recording."
+        },
+        {
+          "id": "q3",
+          "question": "Agent A (on your machine) requests `src/types.ts` from Agent B (on a teammate's machine). What must happen before Agent A receives the file?",
+          "choices": {
+            "A": "Agent B must call `paradigm_symphony_approve_file` — agents can approve their own file requests",
+            "B": "The file is sent automatically since both agents are linked in the same Symphony network",
+            "C": "The teammate (human) must explicitly approve the file transfer — every cross-agent file transfer requires human approval from the file owner's side",
+            "D": "Agent A must have the `^file-access` gate declared in portal.yaml",
+            "E": "The file is sent if it matches the auto-approve glob patterns, but there is no human gate"
+          },
+          "correct": "C",
+          "explanation": "The file pipeline's core security constraint is that every file transfer requires explicit human approval from the owner's side. When Agent A requests a file, the teammate sees a prompt (via Conductor or `paradigm symphony requests`) and must approve, deny, or approve with redaction. Even if auto-approve patterns exist in trust.yaml, the initial setup still requires human-configured trust levels."
+        },
+        {
+          "id": "q4",
+          "question": "An agent's `paradigm_symphony_poll` returns 3 new messages in a thread about a failing test. The agent reads them, investigates the code, and finds the bug. How should the agent communicate its findings?",
+          "choices": {
+            "A": "Call `paradigm_lore_record` with the findings — lore is the communication channel",
+            "B": "Call `paradigm_symphony_send` with `intent: 'context'` providing the investigation results, then `intent: 'proposal'` with the fix, writing to `outbox.jsonl` for delivery to the thread",
+            "C": "Write directly to the other agents' `inbox.jsonl` files for immediate delivery",
+            "D": "Call `paradigm_sentinel_record` to log the bug as an incident",
+            "E": "Call `paradigm symphony send` from the CLI — agents cannot use MCP tools to reply"
+          },
+          "correct": "B",
+          "explanation": "Agents communicate via `paradigm_symphony_send`, which writes structured messages to `outbox.jsonl`. Using multiple messages with appropriate intents (context for the investigation, proposal for the fix) gives other agents structured context. Writing directly to inbox files (C) bypasses the routing protocol. Lore (A) and Sentinel (D) are recording systems, not communication channels."
+        },
+        {
+          "id": "q5",
+          "question": "A thread about a serialization bug has been active for 20 minutes across 4 agents. The team agrees on a fix. What should happen next?",
+          "choices": {
+            "A": "Delete the thread files from `~/.paradigm/score/threads/` to clean up",
+            "B": "Let the thread expire naturally — threads auto-resolve after 1 hour of inactivity",
+            "C": "Run `paradigm symphony resolve <thread-id>` which marks the thread as resolved and automatically creates a lore entry capturing the full conversation, decisions, and actions",
+            "D": "Each agent independently records a lore entry about their contribution",
+            "E": "Run `paradigm_reindex` to incorporate the thread into the project index"
+          },
+          "correct": "C",
+          "explanation": "Thread resolution via `paradigm symphony resolve` is the bridge between ephemeral conversation and permanent project memory. It marks the thread as resolved and automatically creates a comprehensive lore entry with the topic, participants, decisions, actions, and referenced symbols. This single action preserves the entire collaborative context for future reference."
+        }
+      ]
+    },
+    {
+      "id": "platform-agent-ui",
+      "title": "Platform & Agent-Driven UI",
+      "content": "## The Unified Platform\n\n`paradigm serve` launches the Paradigm Platform — a unified development management interface on port 3850 that absorbs every Paradigm tool (Lore, Graph, Sentinel, University, Symphony) into one browser tab.\n\nThe Platform is built on Express + WebSocket on the server, React 18 + Zustand on the client. Sections are lazy-loaded. A shared design system provides consistent theming and symbol colors.\n\n### Architecture\n\n```\nlocalhost:3850 (Express + WebSocket)\n├── /api/lore/*        ← LoreRouter\n├── /api/symbols/*     ← SymbolsRouter\n├── /api/graphs/*      ← GraphsRouter\n├── /api/platform/*    ← PlatformRouter (health, sections, agent-command)\n├── /ws                ← WebSocket (agent commands + user activity)\n└── /                  ← Platform UI SPA\n```\n\n## Agent-Driven UI\n\nThe breakthrough: **the AI agent can drive the browser in real-time.** Five MCP tools let the agent navigate, highlight, annotate, observe, and clear — turning the Platform from a passive viewer into a shared workspace.\n\n### The Pipeline: MCP → HTTP → WebSocket → Browser\n\n```\nAgent (Claude Code)       Platform Server          Browser\n      │                          │                    │\n      │ paradigm_platform_*      │                    │\n      │ POST /api/platform/cmd   │                    │\n      │ ─────────────────────────►│                    │\n      │   ◄── { ok: true } ──────│                    │\n      │                          │  ws: agent:*       │\n      │                          │──────────────────►│\n      │                          │                    │ UI updates\n```\n\nWhy HTTP not file-based: the <500ms latency requirement rules out file-watching. Why not direct WebSocket from MCP: MCP tools are stdio-based with no event loop for persistent WS connections.\n\n### The Five Tools\n\n| Tool | Purpose |\n|------|---------|\n| `paradigm_platform_navigate` | Switch sections, select symbols, open lore entries |\n| `paradigm_platform_highlight` | Pulsing glow on symbols with color + label, auto-expires |\n| `paradigm_platform_annotate` | Toasts (notifications), callouts (on graph nodes), badges |\n| `paradigm_platform_observe` | Read user's current section, selected symbol, theme, mute state |\n| `paradigm_platform_clear` | Remove all agent highlights and annotations |\n\n### Conflict Resolution: User Always Wins\n\nThe agent must never hijack the user's attention:\n\n- **User idle (>5s):** Agent navigation executes immediately\n- **User active (<5s):** A prompt appears: \"Agent wants to show you #X — [Go there] [Dismiss]\"\n- **User muted:** All agent effects are silently discarded; `observe` returns `{ muted: true }`\n\n### Agent Presence\n\nThe `#AgentPresenceManager` tracks connected agents by their Symphony identity (`{project}/{role}`). Each agent gets a deterministic color from its ID hash. Presence dots appear in the Platform header with a mute toggle.\n\nStale agents are auto-pruned after 2 minutes of inactivity.\n\n### User State Tracking\n\nThe `#UserStateTracker` accumulates user activity — what section they're viewing, what symbol is selected, theme preference. This state is served to `paradigm_platform_observe` so the agent can reason about what the user is looking at.\n\nBrowser clients report activity via WebSocket messages: `user:navigate`, `user:select`, `user:theme`, `user:mute`.\n\n### Visual Treatment\n\n| Element | Human | Agent |\n|---------|-------|-------|\n| Selection ring | Solid 2px blue | Dashed 2px agent-color |\n| Highlight | N/A | Pulsing glow animation |\n| Toast | N/A | Left border + robot icon |\n| Navigation | Instant | 300ms ease + toast notification |\n\n### Browser Architecture\n\nThe agent UI layer sits alongside existing stores:\n\n- `agentStore.ts` — Zustand store managing presence, highlights, annotations, toasts, mute, pending navigation\n- `useAgentEffects` — Hook connecting WebSocket `agent:*` messages to store actions, with auto-reconnect\n- `useActivityReporter` — Hook reporting section/theme changes back to server\n- `AgentToast` — Severity-colored toast component\n- `AgentCallout` — Floating callout overlay + navigation conflict prompt",
+      "keyConcepts": [
+        "paradigm serve unifies all tools on port 3850 in one browser tab",
+        "Agent-Driven UI: 5 MCP tools (navigate, highlight, annotate, observe, clear) control the browser in real-time",
+        "Pipeline: MCP → HTTP POST → Platform server → WebSocket broadcast → browser Zustand store → visual effect",
+        "Conflict resolution: user idle → auto-navigate, user active → prompt, user muted → silently discard",
+        "Agent identity reuses Symphony pattern: {project}/{role} with deterministic color from hash",
+        "AgentPresenceManager tracks agents, auto-prunes after 2min idle",
+        "UserStateTracker accumulates section/symbol/theme for observe tool",
+        "Visual distinction: agent effects use dashed rings, pulsing glow, robot-icon toasts vs. human solid styles"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "An AI agent calls `paradigm_platform_navigate({ section: 'graph', symbol: '#payment-service' })` while the user is actively typing in the lore section. What happens in the browser?",
+          "choices": {
+            "A": "The browser immediately switches to the graph section and selects the node",
+            "B": "The command fails with an error because the user is in a different section",
+            "C": "A prompt appears: 'Agent wants to show you #payment-service — [Go there] [Dismiss]' — the user decides",
+            "D": "The agent's command is queued and executes when the user next switches sections",
+            "E": "The browser switches to graph but keeps the lore section visible in a split view"
+          },
+          "correct": "C",
+          "explanation": "When the user is active (last interaction <5s ago), the agent's navigation creates a pending navigation prompt instead of auto-navigating. The user sees 'Agent wants to show you #payment-service — [Go there] [Dismiss]' and chooses whether to follow. This is the conflict resolution model: user always wins."
+        },
+        {
+          "id": "q2",
+          "question": "What is the communication pipeline when an MCP tool like `paradigm_platform_highlight` sends a command to the browser?",
+          "choices": {
+            "A": "MCP tool → direct WebSocket connection to browser → UI update",
+            "B": "MCP tool → writes to file → browser polls file every 500ms → UI update",
+            "C": "MCP tool → HTTP POST to Platform server → server broadcasts via WebSocket → browser Zustand store → UI update",
+            "D": "MCP tool → writes to scan-index.json → browser watches index file → UI update",
+            "E": "MCP tool → sends message via Symphony mailbox → browser reads mailbox → UI update"
+          },
+          "correct": "C",
+          "explanation": "The pipeline is MCP → HTTP POST → WebSocket broadcast → browser. The MCP tool calls the platform-bridge helper which POSTs to /api/platform/agent-command. The server validates the command, updates server-side state (presence, highlights), and broadcasts a typed WebSocket message (e.g., agent:highlight) to all connected browsers. The browser's useAgentEffects hook receives the message and dispatches to the Zustand agentStore."
+        },
+        {
+          "id": "q3",
+          "question": "The user clicks the 'Mute' button in the Platform header. An agent then calls `paradigm_platform_annotate({ type: 'toast', message: 'Found a bug in #auth' })`. What happens?",
+          "choices": {
+            "A": "The toast appears but with reduced opacity",
+            "B": "The command returns `{ annotated: false, reason: 'Agent actions are muted by user' }` and no toast appears",
+            "C": "The toast is queued and shown when the user unmutes",
+            "D": "The command throws an error that the agent must handle",
+            "E": "The toast appears regardless — mute only affects navigation, not annotations"
+          },
+          "correct": "B",
+          "explanation": "When the user mutes agent actions, ALL agent effects are silently discarded — navigate, highlight, annotate, and clear commands all return a response with `reason: 'Agent actions are muted by user'`. The server checks UserStateTracker.isMuted() before broadcasting. The agent can detect this via `paradigm_platform_observe` which returns `{ muted: true }`."
+        },
+        {
+          "id": "q4",
+          "question": "How does the Platform determine an agent's display color in the header presence indicator?",
+          "choices": {
+            "A": "Each agent chooses its color when connecting via WebSocket",
+            "B": "Colors are assigned sequentially from a fixed palette (first agent = blue, second = green, etc.)",
+            "C": "The color is deterministically computed from a hash of the agent's Symphony identity string ({project}/{role})",
+            "D": "Colors are stored in .paradigm/config.yaml under platform.agentColors",
+            "E": "All agents share the same color — they're distinguished by name only"
+          },
+          "correct": "C",
+          "explanation": "Agent colors are deterministic: the AgentPresenceManager computes a hash of the agentId string (e.g., 'a-paradigm/core') and maps it to one of 8 predefined colors. This means the same agent always gets the same color across sessions, making it recognizable. The identity reuses Symphony's {project}/{role} pattern."
+        },
+        {
+          "id": "q5",
+          "question": "An agent wants to understand what the user is currently looking at before deciding what to highlight. Which approach is correct?",
+          "choices": {
+            "A": "Read the platformStore.ts file to check the activeSection variable",
+            "B": "Call `paradigm_platform_observe()` which returns the current section, selected symbol, theme, mute state, and connected agents",
+            "C": "Call `paradigm_status` which includes the Platform UI state in its output",
+            "D": "Check the browser's localStorage via a Bash command",
+            "E": "Call `paradigm_navigate({ intent: 'context' })` which includes Platform UI state"
+          },
+          "correct": "B",
+          "explanation": "paradigm_platform_observe is the dedicated tool for reading UI state. It sends an 'observe' command to the Platform server, which returns the UserStateTracker's accumulated state: current section, selected symbol, theme, mute status, connected agents, and optionally active highlights/annotations. This is real-time data from the server, not a file read."
+        }
+      ]
     }
   ]
 }

package/dist/university-content/plsat/.purpose

@@ -147,3 +147,9 @@ components:
     file: v3.0.json
     tags: [plsat, para-101]
     references: ["#cold-start", "#disciplines"]
+
+  plsat-questions-platform-agent-ui:
+    description: "PLSAT questions testing Platform agent-driven UI — MCP→HTTP→WS pipeline, conflict resolution, observe, highlights, presence pruning, useAgentEffects (slots 109-112, para-501)"
+    file: v3.0.json
+    tags: [plsat, para-501]
+    references: ["#PlatformWebSocket", "#AgentPresenceManager", "#UserStateTracker", "#PlatformTools", "#AgentStore"]