From e5168fe79d57617fb9c57910f3649d21b0f37b76 Mon Sep 17 00:00:00 2001
From: Chaim <chaim@marcus-law.co.il>
Date: Wed, 10 Jun 2026 09:33:44 +0000
Subject: [PATCH] refactor(web-ui): disambiguate Paperclip agent DTO; document
 platform-presentation boundary (R3, G12, #112)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ממצא: התוכנית המקורית (namespace ל-paperclip.* ב-types.ts) בלתי-ישימה — types.ts
נוצר-אוטומטית מ-OpenAPI ("Do not make direct changes"); הפניות-Paperclip שם רק משקפות
את ה-API של ה-backend, ונשלטות ע"י מודלי-ה-Pydantic, לא ע"י הפרונט. הפרונט אינו
שכבת-אינטליגנציה — הפניות-Paperclip בו הן הצגת-נתוני-פלטפורמה (activity feed, קישור
לדאשבורד, סטטוס-ארכוב) או UI-ניהול מוצהר (paperclip-tab/agents-tab) — כולן shell-adjacent
לגיטימי תחת G12.

הבעיה האמיתית-והישימה: התנגשות-שם — `PaperclipAgent` הוגדר פעמיים עם shapes שונים
(config ב-paperclip-agents.ts מול activity ב-agents.ts). פוצל: ה-activity-DTO →
`PaperclipAgentStatus`; ה-config שומר `PaperclipAgent`. + הערת-כותרת שמסמנת את agents.ts
כמודול הצגת-פלטפורמה מוצהר.

מזין את R4 (#113): leak-guard חייב להחריג קבצים-נוצרים (types.ts) ולא לכלול את הפרונט
בהיקף שכבת-האינטליגנציה המוגנת.

אימות: tsc --noEmit נקי; eslint נקי על הקבצים ששונו.

Invariants: G12 (גבול-פלטפורמה מוצהר בפרונט), G2 (הסרת שם-טיפוס כפול-משמעות).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/cases/agent-status-widget.tsx   |  4 ++--
 web-ui/src/lib/api/agents.ts                       | 14 +++++++++++---
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/web-ui/src/components/cases/agent-status-widget.tsx b/web-ui/src/components/cases/agent-status-widget.tsx
index 6bb13ce..499addd 100644
--- a/web-ui/src/components/cases/agent-status-widget.tsx
+++ b/web-ui/src/components/cases/agent-status-widget.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAgentActivity } from "@/lib/api/agents";
-import type { PaperclipAgent } from "@/lib/api/agents";
+import type { PaperclipAgentStatus } from "@/lib/api/agents";
 import { Bot } from "lucide-react";
 
 /* ── Status dot colors ───────────────────────────────────────── */
@@ -26,7 +26,7 @@ function statusDot(status: string) {
 
 /* ── Agent row ───────────────────────────────────────────────── */
 
-function AgentRow({ agent }: { agent: PaperclipAgent }) {
+function AgentRow({ agent }: { agent: PaperclipAgentStatus }) {
   return (
     <div className="flex items-center gap-2 py-1">
       <span
diff --git a/web-ui/src/lib/api/agents.ts b/web-ui/src/lib/api/agents.ts
index 65db828..f749ffb 100644
--- a/web-ui/src/lib/api/agents.ts
+++ b/web-ui/src/lib/api/agents.ts
@@ -1,5 +1,13 @@
 /**
- * Paperclip agent activity hooks — mirror agent work into Legal-AI UI.
+ * Paperclip agent ACTIVITY hooks — mirror live agent work into the Legal-AI UI.
+ *
+ * Frontend platform-presentation module (G12 / docs/spec/X15): the web-ui is a
+ * presentation layer, and showing the agent platform's live activity is a
+ * legitimate, declared use of platform data. Distinct from
+ * `paperclip-agents.ts`, which is the settings/management view of an agent's
+ * full config — hence the activity DTO here is `PaperclipAgentStatus`, not the
+ * config `PaperclipAgent` (the two are different projections; the name no
+ * longer collides).
  */
 
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -32,7 +40,7 @@ export type PaperclipComment = {
   agent_icon: string | null;
 };
 
-export type PaperclipAgent = {
+export type PaperclipAgentStatus = {
   id: string;
   name: string;
   role: string;
@@ -105,7 +113,7 @@ export type Interaction = {
 export type AgentActivityResponse = {
   issues: PaperclipIssue[];
   comments: PaperclipComment[];
-  agents: PaperclipAgent[];
+  agents: PaperclipAgentStatus[];
   interactions: Interaction[];
 };
 
-- 
2.49.1