@piagent/platform 1.4.0 → 1.5.1

package/packages/piagent-webui/server/core-inspection-provider.ts

@@ -22,7 +22,7 @@ type EventStore = {
 };
 
 async function loadCoreInspection() {
-  const [{ collectFileDiff }, { buildWebUiInspectionProjection }, { matchesProtectedPath }, reviewProjection, reviewStore, mutationProjection, revertProjection, openProjection, commitSummaryProjection, taskIndexProjection, taskTimelineProjection, recoveryHistoryProjection, handoffHistoryProjection, subagentTreeProjection, releaseMonitorProjection] = await Promise.all([
+  const [{ collectFileDiff }, { buildWebUiInspectionProjection }, { matchesProtectedPath }, reviewProjection, reviewStore, mutationProjection, revertProjection, openProjection, commitSummaryProjection, taskIndexProjection, taskTimelineProjection, recoveryHistoryProjection, handoffHistoryProjection, subagentTreeProjection, releaseMonitorProjection, documentWorkspaceProjection] = await Promise.all([
     import(`${CORE_ROOT}/runtime/inspection/diff-projection.ts`),
     import(`${CORE_ROOT}/runtime/inspection/webui-snapshot.ts`),
     import(`${CORE_ROOT}/extensions/policy-core.js`),
@@ -37,9 +37,10 @@ async function loadCoreInspection() {
     import(`${CORE_ROOT}/runtime/inspection/task-compaction-history.ts`),
     import(`${CORE_ROOT}/runtime/inspection/task-handoff-history.ts`),
     import(`${CORE_ROOT}/runtime/inspection/task-subagent-tree.ts`),
-    import("./benchmark-release-monitor.ts")
+    import("./benchmark-release-monitor.ts"),
+    import(`${CORE_ROOT}/runtime/inspection/document-workspace-projection.ts`)
   ]);
-  return { collectFileDiff, buildWebUiInspectionProjection, matchesProtectedPath, ...reviewProjection, ...reviewStore, ...mutationProjection, ...revertProjection, ...openProjection, ...commitSummaryProjection, ...taskIndexProjection, ...taskTimelineProjection, ...recoveryHistoryProjection, ...handoffHistoryProjection, ...subagentTreeProjection, ...releaseMonitorProjection };
+  return { collectFileDiff, buildWebUiInspectionProjection, matchesProtectedPath, ...reviewProjection, ...reviewStore, ...mutationProjection, ...revertProjection, ...openProjection, ...commitSummaryProjection, ...taskIndexProjection, ...taskTimelineProjection, ...recoveryHistoryProjection, ...handoffHistoryProjection, ...subagentTreeProjection, ...releaseMonitorProjection, ...documentWorkspaceProjection };
 }
 
 export type CoreInspectionInput = {
@@ -52,12 +53,16 @@ export type CoreInspectionInput = {
   currentActivity?: () => unknown[];
   sessionEntries?: () => unknown[];
   protectedPaths?: () => string[];
+  // Extra directories the operator granted through the profile. The document
+  // workspace lists them beside the project; without them it shows the project
+  // only, which is the same answer a host with no grants gives.
+  documentReadRoots?: () => unknown;
   contextUsage?: () => { tokens: number | null; contextWindow: number; percent: number | null } | undefined;
   model?: () => { provider?: unknown; id?: unknown; name?: unknown; reasoning?: unknown; input?: unknown; thinkingLevelMap?: unknown; contextWindow?: unknown; maxTokens?: unknown } | undefined;
   thinkingLevel?: () => unknown;
   queueProjection?: () => unknown;
   modelCatalog?: () => unknown;
-  attachmentCapability?: () => { kinds: Array<"file" | "image">; mimeTypes: string[] };
+  attachmentCapability?: () => { kinds: Array<"file" | "image" | "document">; mimeTypes: string[] };
   approvalProjection?: () => { revision: string | null; summary: Record<string, unknown> };
   approvalDetail?: (approvalRef: string) => unknown | null;
   sourceMutationGuardAvailable?: () => boolean;
@@ -75,6 +80,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
   #cachedProjection: { at: number; value: any } | null = null;
   #invalidationEpoch = 0;
   readonly #diffCache = new Map<string, { at: number; value: unknown }>();
+  #documentCache: { at: number; value: unknown } | null = null;
   readonly #sourceRevertConfirmationKey = randomBytes(32);
 
   constructor(input: CoreInspectionInput) { this.#input = input; }
@@ -83,6 +89,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     this.#invalidationEpoch += 1;
     this.#cachedProjection = null;
     this.#diffCache.clear();
+    this.#documentCache = null;
   }
 
   async #projection() {
@@ -97,11 +104,22 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
       contextUsage: this.#input.contextUsage?.(), model: this.#input.model?.(), thinkingLevel: this.#input.thinkingLevel?.(),
       eventCursor: this.#input.eventStore.currentCursor(), resyncRequired: this.#input.eventStore.resyncRequired(), eventReplay: retention
     });
+    // What the host will accept as an attachment is a property of the machine and
+    // the model, not of chat control. The Gateway drives sessions without a chat
+    // bridge at all, and a capability published only alongside that bridge left
+    // its composer believing no file type was supported.
+    if (this.#input.attachmentCapability) {
+      const attachment = this.#input.attachmentCapability();
+      value.snapshot.capabilities.capabilities.attachments = { status: "available", version: 1, reason: null,
+        kinds: attachment.kinds, mimeTypes: attachment.mimeTypes };
+      Object.assign(value.snapshot.capabilities.limits, { maxRequestBodyBytes: 11_250_000, maxAttachmentCount: 4,
+        maxAttachmentFileBytes: 8_388_608, maxAttachmentTotalBytes: 16_777_216 });
+    }
     const control = this.#input.chatControl?.();
     if (control?.state === "ready" && control.identity && control.revisions && !this.#input.eventStore.resyncRequired()) {
       const available = { available: true, reasonCode: null }, disabled = (reasonCode: string) => ({ available: false, reasonCode });
       const lifecycle = this.#input.lifecycleControl?.(), terminal = control.taskState === "terminal";
-      const dispatchBlocked = terminal || lifecycle?.dispatchBlocked === true;
+      const dispatchBlocked = lifecycle?.dispatchBlocked === true && lifecycle.state !== "terminal";
       value.snapshot.identity = structuredClone(control.identity);
       value.snapshot.capabilities.identity = structuredClone(control.identity);
       for (const name of ["runtimeRevision", "taskRevision", "controlRevision", "sessionOptionRevision", "queueRevision"])
@@ -109,17 +127,10 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
       value.snapshot.capabilities.mode = "control-enabled";
       value.snapshot.capabilities.capabilities["control.chat"] = {
         status: "available", version: 1, reason: null, queuePersistence: "runtime-lifetime",
-        actions: { send: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : available, hold: available, editHeld: available,
-          deleteHeld: available, dispatchHeld: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : available,
-          interruptAndSend: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : control.liveness === "running" ? available : disabled("agent-not-running") }
+        actions: { send: dispatchBlocked ? disabled("task-control-gate-closed") : available, hold: available, editHeld: available,
+          deleteHeld: available, dispatchHeld: dispatchBlocked ? disabled("task-control-gate-closed") : available,
+          interruptAndSend: dispatchBlocked ? disabled("task-control-gate-closed") : control.liveness === "running" ? available : disabled("agent-not-running") }
       };
-      if (!terminal && this.#input.attachmentCapability) {
-        const attachment = this.#input.attachmentCapability();
-        value.snapshot.capabilities.capabilities.attachments = { status: "available", version: 1, reason: null,
-          kinds: attachment.kinds, mimeTypes: attachment.mimeTypes };
-        Object.assign(value.snapshot.capabilities.limits, { maxRequestBodyBytes: 11_250_000, maxAttachmentCount: 4,
-          maxAttachmentFileBytes: 8_388_608, maxAttachmentTotalBytes: 16_777_216 });
-      }
       let modelCatalog: any;
       try { modelCatalog = this.#input.modelCatalog?.(); }
       catch { modelCatalog = null; }
@@ -190,6 +201,32 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     const source = (await this.#projection()).sourceViews;
     return view === "working-tree" ? source.workingTree : source[view];
   }
+  // The listing walks the project and every granted root, so it costs real
+  // filesystem work — hundreds of milliseconds on a large repository. It also
+  // changes only when files change, so a short cache keeps a browser that
+  // re-renders from re-walking the disk, without holding a stale view long
+  // enough for the operator to notice.
+  async documents(): Promise<unknown> {
+    const cached = this.#documentCache;
+    if (cached && Date.now() - cached.at <= 2_000) return cached.value;
+    const core = await loadCoreInspection();
+    const value = core.projectDocumentWorkspaceListing(this.#documentWorkspaceInput(core.matchesProtectedPath));
+    this.#documentCache = { at: Date.now(), value };
+    return value;
+  }
+
+  async document(documentRef: string): Promise<unknown> {
+    const core = await loadCoreInspection();
+    return core.projectDocumentWorkspaceDocument({ ...this.#documentWorkspaceInput(core.matchesProtectedPath), documentRef });
+  }
+
+  #documentWorkspaceInput(matchesProtectedPath: (candidate: string, patterns: string[]) => unknown) {
+    const protectedPaths = this.#input.protectedPaths?.() ?? [];
+    return { cwd: this.#input.cwd, profileRoots: this.#input.documentReadRoots?.(),
+      environmentRoots: process.env.PIAGENT_ADDITIONAL_READ_ROOTS,
+      isProtectedPath: (candidate: string) => Boolean(matchesProtectedPath(candidate, protectedPaths)) };
+  }
+
   async activity(): Promise<unknown> { return (await this.#projection()).snapshot.activity; }
   async logPreview(activityRef: string): Promise<unknown> {
     const activity = (await this.#projection()).snapshot.activity;

package/packages/piagent-webui/server/ipc-read-model-client.ts

@@ -62,6 +62,8 @@ export class IpcReadModelClient implements WebUiReadModelProvider {
   handoffHistory(runRef: string): Promise<unknown> { return this.#request("handoffHistory", [runRef]); }
   subagentTree(runRef: string): Promise<unknown> { return this.#request("subagentTree", [runRef]); }
   releaseMonitor(): Promise<unknown> { return this.#request("releaseMonitor"); }
+  documents(): Promise<unknown> { return this.#request("documents"); }
+  document(documentRef: string): Promise<unknown> { return this.#request("document", [documentRef]); }
   activity(): Promise<unknown> { return this.#request("activity"); }
   logPreview(activityRef: string): Promise<unknown> { return this.#request("logPreview", [activityRef]); }
   transcript(beforeCursor: string | null, limit: number): Promise<unknown> { return this.#request("transcript", [beforeCursor, limit]); }

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,50 @@ 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();
+  if (/(?:authentication|auth|token|credential).{0,48}expired|expired.{0,48}(?:authentication|auth|token|credential)/.test(detail)) {
+    return "provider-auth-expired";
+  }
+  if (/(?:authentication|unauthorized|forbidden|credential|api[ _-]?key|log[ -]?in|sign[ -]?in)/.test(detail)) {
+    return "provider-auth-required";
+  }
+  if (/(?:rate[ _-]?limit|too many requests|quota)/.test(detail)) return "provider-rate-limited";
+  if (/(?:network|fetch failed|econn|timed? ?out|unavailable)/.test(detail)) return "provider-unavailable";
+  return "provider-response-failed";
+}
 function safeText(value: string): { full: string; preview: string; redacted: boolean; truncated: boolean } {
   const clean = value.replace(ANSI, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
   const redaction = redactSensitiveText(clean);
@@ -69,21 +115,31 @@ 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,
       textChars: Math.min(1_000_000_000, projected.full.length), digest: `sha256:${hash(projected.full)}`, truncated: projected.truncated,
       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",