@piagent/platform 1.4.1 → 1.5.1

package/packages/piagent-webui/server/loopback-server.ts

@@ -19,7 +19,8 @@ const MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024;
 const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
 
 type ReadCapabilities = () => unknown | Promise<unknown>;
-type RateState = { windowStart: number; requests: number; bootstraps: number; controls: number };
+type RateState = { windowStart: number; requests: number; bootstraps: number };
+type ControlRateState = { windowStart: number; controls: number };
 
 export type LoopbackServer = {
   origin: string;
@@ -57,6 +58,7 @@ export async function startLoopbackServer(options: {
   readSessionCatalog?: () => unknown | Promise<unknown>;
   readSessionCreationOptions?: () => unknown | Promise<unknown>;
   readSessionModel?: (sessionRef: string) => WebUiReadModelProvider | Promise<WebUiReadModelProvider>;
+  executeSessionAttachment?: (sessionRef: string, command: unknown) => unknown | Promise<unknown>;
   readSessionConnections?: (sessionRef: string) => unknown | Promise<unknown>;
   executeSessionConnection?: (command: unknown) => unknown | Promise<unknown>;
   readMcpAuthJob?: (jobRef: string) => unknown | Promise<unknown>;
@@ -82,6 +84,15 @@ export async function startLoopbackServer(options: {
   const auth = new SessionAuthority({ bootstrapTtlMs: options.bootstrapTtlMs, sessionTtlMs: options.sessionTtlMs });
   const sse = options.readModel ? new SseHub(options.readModel) : null;
   const rates = new Map<string, RateState>();
+  const controlRates = new Map<string, ControlRateState>();
+  const consumeControl = (sessionId: string, now: number): boolean => {
+    for (const [id, value] of controlRates) if (now - value.windowStart >= 60_000) controlRates.delete(id);
+    const value = controlRates.get(sessionId) ?? { windowStart: now, controls: 0 };
+    if (now - value.windowStart >= 60_000) Object.assign(value, { windowStart: now, controls: 0 });
+    value.controls += 1; controlRates.set(sessionId, value);
+    while (controlRates.size > 64) controlRates.delete(controlRates.keys().next().value as string);
+    return value.controls <= CONTROLS_PER_MINUTE;
+  };
   let origin = "";
   const server = http.createServer(async (request, response) => {
     applySecurityHeaders(response, styleNonce);
@@ -90,9 +101,16 @@ export async function startLoopbackServer(options: {
     const requestOrigin = request.headers.origin;
     if (requestOrigin && requestOrigin !== origin) return errorResponse(response, 403, "origin-mismatch");
     const remote = request.socket.remoteAddress ?? "unknown", now = Date.now();
-    const rate = rates.get(remote) ?? { windowStart: now, requests: 0, bootstraps: 0, controls: 0 };
-    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstraps: 0, controls: 0 });
-    rate.requests += 1; rates.set(remote, rate);
+    // A browser session is already a launch-scoped authenticated capability.
+    // Charging every tab and every prior launch to one localhost IP lets a
+    // refresh or an unauthenticated local process lock out the active operator.
+    const browserSession = auth.authenticate(request, now);
+    const rateKey = browserSession ? `${remote}:${browserSession.id}` : `remote:${remote}`;
+    for (const [key, value] of rates) if (now - value.windowStart >= 60_000) rates.delete(key);
+    const rate = rates.get(rateKey) ?? { windowStart: now, requests: 0, bootstraps: 0 };
+    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstraps: 0 });
+    rate.requests += 1; rates.set(rateKey, rate);
+    while (rates.size > 128) rates.delete(rates.keys().next().value as string);
     if (rate.requests > REQUESTS_PER_MINUTE) return errorResponse(response, 429, "rate-limit");
     let url: URL;
     try { url = new URL(request.url ?? "/", origin); }
@@ -122,10 +140,10 @@ export async function startLoopbackServer(options: {
 
     if (request.method === "POST" && ["/api/v1/chat/messages", "/api/v1/session-options", "/api/v1/lifecycle",
       "/api/v1/control/resume-and-continue", "/api/v1/reviews", "/api/v1/source-mutations", "/api/v1/source-handoffs"].includes(url.pathname) && options.executeControl) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let command: unknown;
       try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
@@ -135,10 +153,10 @@ export async function startLoopbackServer(options: {
     }
 
     if (request.method === "POST" && url.pathname === "/api/v1/projects/import" && options.executeProjectImport) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let command: unknown;
       try { command = JSON.parse((await requestBody(request, MAX_BOOTSTRAP_BODY_BYTES)).toString("utf8")); }
@@ -155,10 +173,10 @@ export async function startLoopbackServer(options: {
     }
 
     if (request.method === "POST" && url.pathname === "/api/v1/provider-auth" && options.executeProviderAuth) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let command: unknown;
       try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
@@ -172,10 +190,10 @@ export async function startLoopbackServer(options: {
     }
 
     if (request.method === "POST" && url.pathname === "/api/v1/session-connections" && options.executeSessionConnection) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let command: unknown;
       try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
@@ -188,9 +206,10 @@ export async function startLoopbackServer(options: {
     }
 
     if (request.method === "POST" && url.pathname.startsWith("/api/v1/mcp-auth/jobs/") && url.pathname.endsWith("/cancel") && options.cancelMcpAuthJob) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
-      if (requestOrigin !== origin || !auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       const jobRef = url.pathname.slice("/api/v1/mcp-auth/jobs/".length, -"/cancel".length);
       if (!CURSOR.test(jobRef) || jobRef.includes("/") || url.search) return errorResponse(response, 400, "invalid-mcp-auth-job-ref");
       try { return jsonResponse(response, 200, await options.cancelMcpAuthJob(jobRef)); }
@@ -198,10 +217,10 @@ export async function startLoopbackServer(options: {
     }
 
     if (request.method === "POST" && url.pathname === "/api/v1/attachments" && options.executeAttachment) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let command: unknown;
       try { command = JSON.parse((await requestBody(request, MAX_ATTACHMENT_BODY_BYTES)).toString("utf8")); }
@@ -210,11 +229,30 @@ export async function startLoopbackServer(options: {
       catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
     }
 
+    // The Gateway drives many sessions, so an attachment has to name the one it
+    // belongs to in the path. The body is the same bounded stage/discard command
+    // the single-session route takes, and every guard in front of it is the same.
+    if (request.method === "POST" && url.pathname.startsWith("/api/v1/sessions/") && url.pathname.endsWith("/attachments")
+      && options.executeSessionAttachment) {
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
+      const sessionRef = url.pathname.slice("/api/v1/sessions/".length, -"/attachments".length);
+      if (!CURSOR.test(sessionRef) || sessionRef.includes("/")) return errorResponse(response, 400, "invalid-session-attachment-ref");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_ATTACHMENT_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-attachment-command"); }
+      try { return jsonResponse(response, 200, await options.executeSessionAttachment(sessionRef, command)); }
+      catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
+    }
+
     if (request.method === "POST" && url.pathname.startsWith("/api/v1/approvals/") && url.pathname.endsWith("/decision") && options.executeApproval) {
-      rate.controls += 1;
-      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       const approvalRef = url.pathname.slice("/api/v1/approvals/".length, -"/decision".length);
       if (!CURSOR.test(approvalRef) || approvalRef.includes("/")) return errorResponse(response, 400, "invalid-approval-ref");

package/packages/piagent-webui/server/read-model-provider.ts

@@ -22,6 +22,8 @@ export type WebUiReadModelProvider = {
   handoffHistory(runRef: string): unknown | Promise<unknown>;
   subagentTree(runRef: string): unknown | Promise<unknown>;
   releaseMonitor(): unknown | Promise<unknown>;
+  documents(): unknown | Promise<unknown>;
+  document(documentRef: string): unknown | Promise<unknown>;
   activity(): unknown | Promise<unknown>;
   logPreview(activityRef: string): unknown | Promise<unknown>;
   transcript(beforeCursor: string | null, limit: number): unknown | Promise<unknown>;

package/packages/piagent-webui/server/read-only-router.ts

@@ -29,6 +29,12 @@ export async function routeReadOnlyRequest(url: URL, provider: WebUiReadModelPro
     if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-task-run-ref" } } };
     return { handled: true, status: 200, value: await provider.subagentTree(ref) };
   }
+  if (url.pathname === "/api/v1/documents" && !url.search) return { handled: true, status: 200, value: await provider.documents() };
+  if (url.pathname.startsWith("/api/v1/documents/")) {
+    const ref = url.pathname.slice("/api/v1/documents/".length);
+    if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-document-ref" } } };
+    return { handled: true, status: 200, value: await provider.document(ref) };
+  }
   if (url.pathname === "/api/v1/chat/queue" && !url.search) return { handled: true, status: 200, value: await provider.queue() };
   if (url.pathname === "/api/v1/session-options/models" && !url.search) return { handled: true, status: 200, value: await provider.modelCatalog() };
   if (url.pathname.startsWith("/api/v1/approvals/")) {

package/packages/piagent-webui/server/transcript-projection.ts

@@ -13,8 +13,10 @@ type TranscriptRevision = { runtimeRevision: string; taskRevision: string | null
   indexRevision: string | null; approvalRevision: string | null; sessionOptionRevision: string | null; queueRevision: string | null };
 type TranscriptContent = { state: "available" | "redacted" | "unavailable"; text: string | null; textChars: number | null; digest: string | null;
   truncated: boolean; redacted: boolean; imageCount: number; reasonCode: string | null };
+type TranscriptAttachment = { displayName: string; kind: "file" | "image" | "document"; mimeType: string; truncated: boolean };
 type TranscriptItem = { messageRef: string; parentMessageRef: string | null; role: "user" | "assistant" | "tool-result"; recordedAt: string;
   agentOperationId: string | null; turnIndex: number | null; content: TranscriptContent;
+  attachments?: TranscriptAttachment[];
   toolCalls: Array<{ toolCallRef: string; toolName: string; state: "requested" | "completed" | "failed" | "unknown" }> };
 export type TranscriptDocument = { schemaVersion: 1; version: "piagent-webui-transcript-v1"; generatedAt: string; identity: TranscriptIdentity;
   revision: TranscriptRevision; eventCursor: string; state: "ready" | "unavailable"; items: TranscriptItem[];
@@ -41,6 +43,37 @@ function messageText(message: any): string {
   if (!Array.isArray(message?.content)) return "";
   return message.content.filter((item: any) => item?.type === "text" && typeof item.text === "string").map((item: any) => item.text).join("\n");
 }
+function safeAttachmentName(value: unknown): string {
+  const projected = safeText(String(value ?? "attachment"));
+  return projected.full.replace(/[\\/]/g, "_").replace(/\s+/g, " ").trim().slice(0, 160) || "attachment";
+}
+function userMessageProjection(message: any): { text: string; attachments: TranscriptAttachment[] } {
+  if (message?.role !== "user" || !Array.isArray(message?.content)) return { text: messageText(message), attachments: [] };
+  const textParts = message.content.filter((part: any) => part?.type === "text" && typeof part.text === "string");
+  const attachments: TranscriptAttachment[] = [];
+  for (const part of textParts.slice(1)) {
+    const lines = String(part.text).split("\n", 3);
+    if (!lines[0]?.startsWith("attached file: ") || !lines[1]?.startsWith("format: ")) continue;
+    let displayName: unknown;
+    try { displayName = JSON.parse(lines[0].slice("attached file: ".length)); } catch { continue; }
+    if (typeof displayName !== "string") continue;
+    const format = /^format: ([A-Za-z0-9][A-Za-z0-9.+-]*\/[A-Za-z0-9][A-Za-z0-9.+-]*)(, truncated)?$/.exec(lines[1]);
+    if (!format) continue;
+    const mimeType = format[1]!;
+    const kind = mimeType === "application/pdf" || mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+      ? "document" as const : "file" as const;
+    attachments.push({ displayName: safeAttachmentName(displayName), kind, mimeType, truncated: Boolean(format[2]) });
+  }
+  for (const part of message.content) {
+    if (part?.type !== "image" || typeof part.mimeType !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.+-]*\/[A-Za-z0-9][A-Za-z0-9.+-]*$/.test(part.mimeType)) continue;
+    attachments.push({ displayName: "Image", kind: "image", mimeType: part.mimeType.slice(0, 120), truncated: false });
+  }
+  // Attachment bodies are provider input, not transcript prose. Showing or
+  // hashing them here would turn the chat bubble into a document dump and make
+  // a bounded UI digest an oracle over user files. The first block is the exact
+  // text the operator typed; the remaining recognized blocks become cards.
+  return { text: attachments.length ? String(textParts[0]?.text ?? "") : messageText(message), attachments: attachments.slice(0, 4) };
+}
 function assistantFailureReason(message: any): string | null {
   if (message?.role !== "assistant" || message?.stopReason !== "error") return null;
   const detail = String(message?.errorMessage ?? "").toLowerCase();
@@ -82,15 +115,22 @@ function toolCalls(message: any, sessionRef: string, role: TranscriptItem["role"
 function role(message: any): TranscriptItem["role"] | null {
   return message?.role === "user" ? "user" : message?.role === "assistant" ? "assistant" : message?.role === "toolResult" ? "tool-result" : null;
 }
+function isInternalFreshTransition(message: any): boolean {
+  if (message?.role !== "user") return false;
+  return /^\/fresh\s+(?:task|scout|be-to-fe)\s+(?:--session-title\s+"[^"\r\n]{1,64}"\s+)?Read task intake from \.pi\/task-inbox\/[A-Za-z0-9._-]+\.md\.\s+Current session is near context limits; use a fresh governed session\.$/u
+    .test(messageText(message).trim());
+}
 function unavailableContent(reasonCode: string): TranscriptContent {
   return { state: "unavailable", text: null, textChars: null, digest: null, truncated: false, redacted: false, imageCount: 0, reasonCode };
 }
 function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
   if (!entry || entry.type !== "message" || !entry.message) return null;
+  if (isInternalFreshTransition(entry.message)) return null;
   const itemRole = role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
   if (!itemRole || !recordedAt || typeof entry.id !== "string" || entry.id.length === 0) return null;
+  const userProjection = userMessageProjection(entry.message);
   const content = itemRole === "tool-result" ? unavailableContent("tool-output-in-activity-preview") : (() => {
-    const projected = safeText(messageText(entry.message));
+    const projected = safeText(itemRole === "user" ? userProjection.text : messageText(entry.message));
     const failureReason = projected.full.length === 0 ? assistantFailureReason(entry.message) : null;
     if (failureReason) return unavailableContent(failureReason);
     return { state: projected.redacted ? "redacted" as const : "available" as const, text: projected.preview,
@@ -98,7 +138,8 @@ function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
       redacted: projected.redacted, imageCount: imageCount(entry.message), reasonCode: projected.redacted ? "sensitive-values-redacted" as const : null };
   })();
   return { messageRef: opaque("message", [identity.sessionRef, entry.id]), parentMessageRef: null, role: itemRole, recordedAt,
-    agentOperationId: null, turnIndex: null, content, toolCalls: toolCalls(entry.message, identity.sessionRef, itemRole) };
+    agentOperationId: null, turnIndex: null, content, ...(userProjection.attachments.length ? { attachments: userProjection.attachments } : {}),
+    toolCalls: toolCalls(entry.message, identity.sessionRef, itemRole) };
 }
 function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit: number): TranscriptDocument {
   return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),

package/schemas/piagent-webui/attachment-v1.schema.json

@@ -49,7 +49,12 @@
             "image/bmp",
             "text/plain",
             "text/markdown",
-            "application/json"
+            "text/csv",
+            "text/tab-separated-values",
+            "application/json",
+            "application/yaml",
+            "application/pdf",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
           ]
         },
         "dataBase64": {
@@ -86,7 +91,7 @@
     "attachment": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["attachmentRef", "messageRequestId", "displayName", "kind", "mimeType", "sizeBytes", "expiresAt"],
+      "required": ["attachmentRef", "messageRequestId", "displayName", "kind", "mimeType", "sizeBytes", "sourceBytes", "truncated", "expiresAt"],
       "properties": {
         "attachmentRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
@@ -96,14 +101,29 @@
           "maxLength": 160,
           "pattern": "^[^\\u0000-\\u001F\\u007F/\\\\]*$"
         },
-        "kind": { "enum": ["file", "image"] },
+        "kind": { "enum": ["file", "image", "document"] },
         "mimeType": {
           "type": "string",
           "minLength": 3,
           "maxLength": 127,
           "pattern": "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+*-]+$"
         },
-        "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 8388608 },
+        "sizeBytes": {
+          "description": "Bytes held for dispatch: image bytes, or the UTF-8 text extracted from a text or document file.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8388608
+        },
+        "sourceBytes": {
+          "description": "Bytes of the file the operator selected, before extraction. Equal to sizeBytes for images.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8388608
+        },
+        "truncated": {
+          "description": "True when extraction produced more text than the per-attachment cap, so Pi receives a prefix.",
+          "type": "boolean"
+        },
         "expiresAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" }
       }
     },

package/schemas/piagent-webui/capabilities-v1.schema.json

@@ -535,9 +535,9 @@
         "kinds": {
           "type": "array",
           "minItems": 1,
-          "maxItems": 2,
+          "maxItems": 3,
           "uniqueItems": true,
-          "items": { "enum": ["file", "image"] }
+          "items": { "enum": ["file", "image", "document"] }
         },
         "mimeTypes": {
           "type": "array",

package/schemas/piagent-webui/catalog-v1.json

@@ -173,6 +173,15 @@
       "supported": true,
       "current": true
     },
+    {
+      "name": "document-workspace-v1",
+      "file": "document-workspace-v1.schema.json",
+      "id": "https://piagent.io.vn/schemas/piagent-webui/document-workspace-v1.schema.json",
+      "documentVersion": 1,
+      "role": "read-model",
+      "supported": true,
+      "current": true
+    },
     {
       "name": "control-command-v1",
       "file": "control-command-v1.schema.json",

package/schemas/piagent-webui/document-workspace-v1.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piagent.io.vn/schemas/piagent-webui/document-workspace-v1.schema.json",
+  "title": "Piagent WebUI bounded document workspace v1",
+  "oneOf": [
+    { "$ref": "#/$defs/listing" },
+    { "$ref": "#/$defs/document" }
+  ],
+  "$defs": {
+    "displayText": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]*$"
+    },
+    "nullableDisplayText": {
+      "anyOf": [
+        { "$ref": "#/$defs/displayText" },
+        { "type": "null" }
+      ]
+    },
+    "root": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rootRef", "path", "source", "documentCount"],
+      "properties": {
+        "rootRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "path": { "$ref": "#/$defs/displayText" },
+        "source": { "enum": ["project", "profile", "environment"] },
+        "documentCount": { "type": "integer", "minimum": 0, "maximum": 2000 }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["documentRef", "rootRef", "name", "relativePath", "extension", "sizeBytes", "modifiedAt"],
+      "properties": {
+        "documentRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "rootRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "name": { "$ref": "#/$defs/displayText" },
+        "relativePath": { "$ref": "#/$defs/displayText" },
+        "extension": {
+          "enum": ["md", "markdown", "txt", "text", "csv", "tsv", "json", "yaml", "yml", "pdf", "docx"]
+        },
+        "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 12582912 },
+        "modifiedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "version", "messageType", "generatedAt", "state", "roots", "documents", "truncated", "reasonCode"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "version": { "const": "piagent-webui-document-workspace-v1" },
+        "messageType": { "const": "listing" },
+        "generatedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
+        "state": { "enum": ["ready", "unavailable"] },
+        "roots": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/root" }
+        },
+        "documents": {
+          "type": "array",
+          "maxItems": 2000,
+          "items": { "$ref": "#/$defs/entry" }
+        },
+        "truncated": { "type": "boolean" },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "unavailable" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "roots": { "type": "array", "maxItems": 0 },
+              "documents": { "type": "array", "maxItems": 0 },
+              "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "state": { "const": "ready" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "roots": { "type": "array", "minItems": 1 },
+              "reasonCode": { "type": "null" }
+            }
+          }
+        }
+      ]
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "version", "messageType", "generatedAt", "documentRef", "state", "name", "relativePath", "rootRef", "format", "text", "sizeBytes", "truncated", "redacted", "reasonCode"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "version": { "const": "piagent-webui-document-workspace-v1" },
+        "messageType": { "const": "document" },
+        "generatedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
+        "documentRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "state": { "enum": ["ready", "unavailable"] },
+        "name": { "$ref": "#/$defs/nullableDisplayText" },
+        "relativePath": { "$ref": "#/$defs/nullableDisplayText" },
+        "rootRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+        "format": { "enum": ["text", "docx", "pdf", null] },
+        "text": {
+          "anyOf": [
+            { "type": "string", "maxLength": 400000 },
+            { "type": "null" }
+          ]
+        },
+        "sizeBytes": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1, "maximum": 12582912 },
+            { "type": "null" }
+          ]
+        },
+        "truncated": { "type": "boolean" },
+        "redacted": { "type": "boolean" },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "ready" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "name": { "$ref": "#/$defs/displayText" },
+              "relativePath": { "$ref": "#/$defs/displayText" },
+              "rootRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+              "format": { "enum": ["text", "docx", "pdf"] },
+              "text": { "type": "string", "maxLength": 400000 },
+              "reasonCode": { "type": "null" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "state": { "const": "unavailable" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "text": { "type": "null" },
+              "format": { "type": "null" },
+              "truncated": { "const": false },
+              "redacted": { "const": false },
+              "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/piagent-webui/session-command-v1.schema.json

@@ -56,7 +56,11 @@
                 "modelRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
                 "thinkingLevel": { "$ref": "#/$defs/thinkingLevel" },
                 "message": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "^[^\\u0000]*$" },
-                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" }
+                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+                "deferInitialMessage": {
+                  "description": "Create the durable session without dispatching the first turn so the client can stage selected attachments against the new session before sending it.",
+                  "type": "boolean"
+                }
               }
             }
           }
@@ -75,12 +79,19 @@
             "payload": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["delivery", "message", "messageRequestId", "expectedOperationRef"],
+              "required": ["delivery", "message", "messageRequestId", "expectedOperationRef", "attachmentRefs"],
               "properties": {
                 "delivery": { "enum": ["new-operation", "follow-up", "steer"] },
                 "message": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "^[^\\u0000]*$" },
                 "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
-                "expectedOperationRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" }
+                "expectedOperationRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+                "attachmentRefs": {
+                  "description": "Refs staged for this exact messageRequestId. Claimed once at dispatch and consumed.",
+                  "type": "array",
+                  "maxItems": 4,
+                  "uniqueItems": true,
+                  "items": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" }
+                }
               },
               "allOf": [
                 {

package/schemas/piagent-webui/transcript-v1.schema.json

@@ -188,6 +188,12 @@
         "agentOperationId": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
         "turnIndex": { "$ref": "#/$defs/nullableCount" },
         "content": { "$ref": "#/$defs/content" },
+        "attachments": {
+          "type": "array",
+          "maxItems": 4,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/attachmentSummary" }
+        },
         "toolCalls": {
           "type": "array",
           "maxItems": 64,
@@ -217,6 +223,27 @@
         }
       ]
     },
+    "attachmentSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["displayName", "kind", "mimeType", "truncated"],
+      "properties": {
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[^\\u0000-\\u001F\\u007F/\\\\]*$"
+        },
+        "kind": { "enum": ["file", "image", "document"] },
+        "mimeType": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9.+-]*/[A-Za-z0-9][A-Za-z0-9.+-]*$"
+        },
+        "truncated": { "type": "boolean" }
+      }
+    },
     "page": {
       "type": "object",
       "additionalProperties": false,