@piagent/platform 1.4.1 → 1.5.2

package/packages/piagent-webui/gateway/session-command-controller.ts

@@ -35,7 +35,10 @@ function nullableRef(value: unknown): value is string | null { return value ===
 
 function validPayload(action: SessionAction, payload: Record<string, unknown>): boolean {
   if (["session.archive", "session.unarchive", "session.acquire", "session.release"].includes(action)) return exactKeys(payload, []);
-  if (action === "session.send") return exactKeys(payload, ["delivery", "message", "messageRequestId", "expectedOperationRef"])
+  if (action === "session.send") return exactKeys(payload, ["delivery", "message", "messageRequestId", "expectedOperationRef", "attachmentRefs"])
+    && Array.isArray(payload.attachmentRefs) && payload.attachmentRefs.length <= 4
+    && new Set(payload.attachmentRefs as unknown[]).size === payload.attachmentRefs.length
+    && (payload.attachmentRefs as unknown[]).every((item) => typeof item === "string" && REF.test(item))
     && ["new-operation", "follow-up", "steer"].includes(String(payload.delivery)) && typeof payload.message === "string"
     && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0") && REF.test(String(payload.messageRequestId))
     && nullableRef(payload.expectedOperationRef) && (payload.delivery === "new-operation" ? payload.expectedOperationRef === null : payload.expectedOperationRef !== null);
@@ -52,11 +55,12 @@ function validPayload(action: SessionAction, payload: Record<string, unknown>):
   if (action === "session.fork") return exactKeys(payload, ["entryRef", "title"]) && nullableRef(payload.entryRef)
     && (payload.title === null || typeof payload.title === "string" && payload.title.length >= 1 && payload.title.length <= 500
       && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(payload.title));
-  return exactKeys(payload, ["projectRef", "placeRef", "modelRef", "thinkingLevel", "message", "messageRequestId"])
+  const createKeys = ["projectRef", "placeRef", "modelRef", "thinkingLevel", "message", "messageRequestId"];
+  return (exactKeys(payload, createKeys) || exactKeys(payload, [...createKeys, "deferInitialMessage"]))
     && REF.test(String(payload.projectRef)) && REF.test(String(payload.placeRef)) && nullableRef(payload.modelRef)
     && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(payload.thinkingLevel))
     && typeof payload.message === "string" && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0")
-    && REF.test(String(payload.messageRequestId));
+    && REF.test(String(payload.messageRequestId)) && (payload.deferInitialMessage === undefined || typeof payload.deferInitialMessage === "boolean");
 }
 
 function parseCommand(value: unknown): SessionCommand | null {
@@ -86,10 +90,15 @@ export class SessionCommandController {
   readonly #metadata: SessionMetadataStore | null;
   readonly #now: () => Date;
   readonly #chains = new Map<string, Promise<unknown>>();
+  readonly #prepareAttachments: ((sessionRef: string, refs: string[], messageRequestId: string, text: string) => Promise<{
+    text: string; images: unknown[]; commit(): void; release(): void }>) | undefined;
 
   constructor(options: { catalog(): Promise<Catalog>; runtimes: SessionRuntimeSupervisor; store: SessionCommandStore; events: GatewayEventStore;
     metadata?: SessionMetadataStore;
+    prepareAttachments?(sessionRef: string, refs: string[], messageRequestId: string, text: string): Promise<{
+      text: string; images: unknown[]; commit(): void; release(): void }>;
     now?: () => Date }) {
+    this.#prepareAttachments = options.prepareAttachments;
     this.#catalog = options.catalog; this.#runtimes = options.runtimes; this.#store = options.store; this.#events = options.events;
     this.#metadata = options.metadata ?? null;
     this.#now = options.now ?? (() => new Date());
@@ -129,8 +138,10 @@ export class SessionCommandController {
     try { this.#store.admit(command, this.#now()); }
     catch { return this.#rejected(command, current, row, "unavailable", "session-command-admission-failed"); }
     let targetSessionRef = command.sessionRef;
+    let attachmentReservation: { commit(): void; release(): void } | null = null;
+    let sendAttempted = false;
     try {
-      let resultCode: "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
+      let resultCode: "created" | "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
         | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
         operationRef: string | null = null;
       if (command.action === "session.create") {
@@ -138,18 +149,32 @@ export class SessionCommandController {
           command.payload.modelRef === null ? null : String(command.payload.modelRef), String(command.payload.thinkingLevel));
         const created = await this.#readyCatalog(), createdRow = created.sessions.find((item) => item.sessionRef === targetSessionRef);
         if (!createdRow) throw new Error("session-catalog-refresh-failed");
-        const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message: String(command.payload.message),
-          expectedOperationRef: null }, createdRow.sessionRevision);
-        resultCode = sent.resultCode === "started" ? "started" : sent.resultCode; operationRef = sent.operationRef;
+        if (command.payload.deferInitialMessage === true) resultCode = "created";
+        else {
+          const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message: String(command.payload.message),
+            expectedOperationRef: null }, createdRow.sessionRevision);
+          resultCode = sent.resultCode === "started" ? "started" : sent.resultCode; operationRef = sent.operationRef;
+        }
       } else if (command.action === "session.acquire") { await this.#runtimes.acquire(command.sessionRef!); resultCode = "acquired"; }
       else if (command.action === "session.release") { await this.#runtimes.release(command.sessionRef!); resultCode = "released"; }
       else if (command.action === "session.send") {
         await this.#runtimes.acquire(command.sessionRef!);
         const acquired = await this.#readyCatalog(), acquiredRow = acquired.sessions.find((item) => item.sessionRef === command.sessionRef);
         if (!acquiredRow) throw new Error("session-catalog-refresh-failed");
-        const sent = await this.#runtimes.send(command.sessionRef!, command.payload as {
-          delivery: "new-operation" | "follow-up" | "steer"; message: string; expectedOperationRef: string | null
-        }, acquiredRow.sessionRevision);
+        const payload = command.payload as { delivery: "new-operation" | "follow-up" | "steer"; message: string;
+          expectedOperationRef: string | null; messageRequestId: string; attachmentRefs: string[] };
+        // Staged refs are claimed once, here, before the runtime is asked to
+        // dispatch. Documents were turned into text at staging so they join the
+        // message; images travel on the host's own channel.
+        const prepared = this.#prepareAttachments
+          ? await this.#prepareAttachments(command.sessionRef!, payload.attachmentRefs, payload.messageRequestId, payload.message)
+          : { text: payload.message, images: [] as unknown[], commit() {}, release() {} };
+        attachmentReservation = prepared;
+        if (!this.#prepareAttachments && payload.attachmentRefs.length > 0) throw new Error("session-attachment-unavailable");
+        sendAttempted = true;
+        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message: prepared.text, images: prepared.images },
+          acquiredRow.sessionRevision);
+        prepared.commit();
         resultCode = sent.resultCode; operationRef = sent.operationRef;
       } else if (command.action === "session.abort") {
         operationRef = String(command.payload.operationRef);
@@ -195,10 +220,18 @@ export class SessionCommandController {
       return receipt;
     } catch (cause) {
       const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef) ?? row;
-      const code = cause instanceof Error && /recovery/.test(cause.message) ? "recovery-required"
-        : cause instanceof Error && /(owner-conflict|operation-conflict|runtime-busy)/.test(cause.message) ? "owner-conflict" : "effect-unknown";
+      const message = cause instanceof Error ? cause.message : "session-command-failed";
+      const noDispatchEffect = command.action === "session.send" && (!sendAttempted
+        || /^(session-runtime-unavailable|session-operation-conflict|session-owner-conflict|session-runtime-busy)$/.test(message));
+      if (attachmentReservation) {
+        try { if (noDispatchEffect) attachmentReservation.release(); else attachmentReservation.commit(); }
+        catch { /* an attempted dispatch with an unprovable reservation remains uncertain */ }
+      }
+      const code = /recovery/.test(message) ? "recovery-required"
+        : /(owner-conflict|operation-conflict|runtime-busy)/.test(message) ? "owner-conflict"
+          : noDispatchEffect || command.action === "session.send" && !sendAttempted ? "unavailable" : "effect-unknown";
       const receipt = code === "effect-unknown" ? this.#uncertain(command, after, afterRow, "session-command-effect-unknown")
-        : this.#rejected(command, after, afterRow, code, cause instanceof Error ? cause.message : "session-command-failed");
+        : this.#rejected(command, after, afterRow, code, message);
       try { this.#store.settle(command, receipt, this.#now()); } catch { /* intent remains uncertain */ }
       return receipt;
     }
@@ -219,7 +252,7 @@ export class SessionCommandController {
       sessionRevisionAfter: row?.sessionRevision ?? null, deduplicated: false };
   }
   #settled(command: SessionCommand, catalog: Catalog, row: SessionRow,
-    resultCode: "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
+    resultCode: "created" | "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
       | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
     operationRef: string | null): Receipt {
     return { ...this.#base(command, catalog, row), operationRef, phase: "settled", resultCode, settledAt: this.#now().toISOString(),

package/packages/piagent-webui/gateway/session-inspection-registry.ts

@@ -3,16 +3,18 @@ import path from "node:path";
 
 import { readContextTelemetry } from "../../piagent-core/extensions/context-engine.js";
 import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
-import { runtimeConnectionDefinitions, runtimeProtectedPaths } from "../../piagent-core/runtime/inspection/project-runtime-inspection.ts";
+import { runtimeConnectionDefinitions, runtimeDocumentReadRoots, runtimeProtectedPaths } from "../../piagent-core/runtime/inspection/project-runtime-inspection.ts";
 import { setRuntimeMcpEnabled } from "../../piagent-core/runtime/inspection/mcp-control.ts";
 import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import { piApprovalBroker } from "../../piagent-core/runtime/inspection/approval-broker.ts";
+import { attachmentCapability } from "../../piagent-core/runtime/input/attachment-store.ts";
 import { CoreInspectionProvider } from "../server/core-inspection-provider.ts";
 import { ReadModelNotFound, type WebUiReadModelProvider } from "../server/read-model-provider.ts";
-import { projectRefForCwd, sessionRefForPath, type PiSessionInfo } from "./session-catalog.ts";
+import { isUserConversationSession, projectRefForCwd, sessionRefForPath, type PiSessionInfo } from "./session-catalog.ts";
 import { nativeProjectPickerAvailable } from "./native-project-picker.ts";
 import type { McpAuthBroker } from "./mcp-auth-broker.ts";
+import { inspectWebSearchCapability } from "./ai-capability-inspection.ts";
 
 type PiHost = {
   SessionManager: {
@@ -95,19 +97,26 @@ function persistedContextUsage(host: PiHost, entries: unknown[], messages: unkno
 export class SessionInspectionRegistry {
   readonly #gatewayInstanceRef: string;
   readonly #host: PiHost;
+  readonly #listSessions: () => Promise<PiSessionInfo[]>;
+  readonly #openLiveSession: ((sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null) | null;
   readonly #key: Buffer;
   readonly #packageRoot: string;
+  readonly #agentDir?: string;
   readonly #models?: ModelRuntime;
   readonly #projects?: ProjectSource;
   readonly #mcpAuth?: McpAuthBroker;
   readonly #providers = new Map<string, { modifiedAt: string; provider: CoreInspectionProvider }>();
 
-  constructor(options: { gatewayInstanceRef: string; host: PiHost; key: Buffer; packageRoot: string; models?: ModelRuntime; projects?: ProjectSource;
-    mcpAuth?: McpAuthBroker }) {
+  constructor(options: { gatewayInstanceRef: string; host: PiHost; key: Buffer; packageRoot: string; agentDir?: string; models?: ModelRuntime; projects?: ProjectSource;
+    mcpAuth?: McpAuthBroker; listSessions?: () => Promise<PiSessionInfo[]>;
+    openLiveSession?: (sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null }) {
     this.#gatewayInstanceRef = options.gatewayInstanceRef;
     this.#host = options.host;
+    this.#listSessions = options.listSessions ?? (() => options.host.SessionManager.listAll());
+    this.#openLiveSession = options.openLiveSession ?? null;
     this.#key = options.key;
     this.#packageRoot = options.packageRoot;
+    this.#agentDir = options.agentDir;
     this.#models = options.models;
     this.#projects = options.projects;
     this.#mcpAuth = options.mcpAuth;
@@ -118,7 +127,7 @@ export class SessionInspectionRegistry {
   }
 
   async #sessionInfo(sessionRef: string): Promise<PiSessionInfo> {
-    const sessions = await this.#host.SessionManager.listAll();
+    const sessions = (await this.#listSessions()).filter(isUserConversationSession);
     const found = sessions.filter((candidate) => sessionRefForPath(this.#key, candidate.path) === sessionRef);
     if (found.length !== 1) throw new ReadModelNotFound();
     return found[0]!;
@@ -168,7 +177,7 @@ export class SessionInspectionRegistry {
   }
 
   async creationOptions(): Promise<unknown> {
-    const sessions = await this.#host.SessionManager.listAll();
+    const sessions = (await this.#listSessions()).filter(isUserConversationSession);
     const projects = new Map<string, { projectRef: string; placeRef: string; label: string }>();
     for (const info of sessions) {
       if (!info.cwd) continue;
@@ -179,7 +188,8 @@ export class SessionInspectionRegistry {
     for (const project of safeRead(() => this.#projects?.list() ?? [], [])) {
       if (!projects.has(project.projectRef)) projects.set(project.projectRef, project);
     }
-    const models = (this.#models?.getAvailableSnapshot() ?? []).slice(0, 300).flatMap((value) => {
+    const availableModels = (this.#models?.getAvailableSnapshot() ?? []).slice(0, 300);
+    const models = availableModels.flatMap((value) => {
       const provider = safeModelId(value.provider);
       const modelId = safeModelId(value.id);
       if (!provider || !modelId || typeof value.reasoning !== "boolean") return [];
@@ -187,11 +197,12 @@ export class SessionInspectionRegistry {
         ? value.thinkingLevelMap as Record<string, unknown> : {};
       const thinkingLevels = value.reasoning ? ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
         .filter((level) => mapping[level] !== null && !(["xhigh", "max"].includes(level) && mapping[level] === undefined)) : ["off"];
+      const inputs = Array.isArray(value.input) ? value.input.filter((item): item is string => typeof item === "string") : null;
       return [{ modelRef: webUiModelRef(provider, modelId), provider, modelId, displayName: safeName(value.name ?? modelId),
-        reasoning: value.reasoning, thinkingLevels }];
+        reasoning: value.reasoning, imageInput: inputs ? inputs.includes("image") : null, thinkingLevels }];
     });
     return { schemaVersion: 1, version: "piagent-session-creation-options-v1", generatedAt: new Date().toISOString(),
-      projects: [...projects.values()].slice(0, 200), models,
+      projects: [...projects.values()].slice(0, 200), models, webSearch: inspectWebSearchCapability({ agentDir: this.#agentDir, models: availableModels }),
       projectImport: nativeProjectPickerAvailable() ? { status: "available", reasonCode: null }
         : { status: "unavailable", reasonCode: "native-project-picker-unavailable" },
       reasonCode: projects.size ? null : "no-known-project" };
@@ -204,7 +215,7 @@ export class SessionInspectionRegistry {
     if (cached?.modifiedAt === modifiedAt) return cached.provider;
 
     let manager: ReturnType<PiHost["SessionManager"]["open"]>;
-    try { manager = this.#host.SessionManager.open(info.path); }
+    try { manager = this.#openLiveSession?.(sessionRef) ?? this.#host.SessionManager.open(info.path); }
     catch { throw new ReadModelNotFound(); }
     const context = safeRead(() => manager.buildSessionContext(), { model: null, thinkingLevel: "unknown", messages: [] });
     const model = context.model ? this.#models?.getModel(context.model.provider, context.model.modelId) : undefined;
@@ -225,6 +236,15 @@ export class SessionInspectionRegistry {
       activityEvents: () => safeRead(() => readContextTelemetry(info.cwd, { limit: 5_000 }), []),
       sessionEntries: () => entries,
       protectedPaths: () => runtimeProtectedPaths(this.#packageRoot, info.cwd),
+      // The document workspace lists the project plus whatever the operator
+      // granted in the profile. Without this it silently shows the project only,
+      // which reads as "the grant does not work" rather than "it was not asked for".
+      documentReadRoots: () => safeRead(() => runtimeDocumentReadRoots(this.#packageRoot, info.cwd), []),
+      // Derived from the model and the host, with no store instance involved:
+      // the store for this session is built from the very snapshot this call
+      // helps produce, so asking the store would be circular.
+      attachmentCapability: () => attachmentCapability({
+        images: Array.isArray(model?.input) && model.input.includes("image"), now: Date.now() }),
       contextUsage: () => contextUsage,
       model: () => model,
       thinkingLevel: () => context.thinkingLevel,

package/packages/piagent-webui/gateway/session-runtime-supervisor.ts

@@ -7,7 +7,7 @@ import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
 import { inspectTaskControlState } from "../../piagent-core/runtime/inspection/task-control-journal.ts";
 import { piApprovalBroker, type ApprovalAuthority, type ApprovalBrokerEvent } from "../../piagent-core/runtime/inspection/approval-broker.ts";
 import type { SessionOwnerProjection, PiSessionInfo } from "./session-catalog.ts";
-import { projectRefForCwd, sessionRefForPath } from "./session-catalog.ts";
+import { isUserConversationSession, projectRefForCwd, sessionRefForPath } from "./session-catalog.ts";
 import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-store.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { GatewaySessionStream } from "./gateway-session-stream.ts";
@@ -20,7 +20,7 @@ type RuntimeHandle = { dispose(): Promise<void>; session?: any };
 type RuntimeFactory = (info: PiSessionInfo, runtimeInstanceRef: string, sessionManager?: any) => Promise<RuntimeHandle>;
 type ActiveRuntime = { runtime: RuntimeHandle; lease: SessionLeaseSnapshot; info: PiSessionInfo; operationRef: string | null;
   unsubscribe: (() => void) | null; completion: Promise<void> | null; settling: boolean; approvalWaiting: boolean;
-  unbindApproval: (() => void) | null; unsubscribeApproval: (() => void) | null };
+  unbindApproval: (() => void) | null; unsubscribeApproval: (() => void) | null; sessionManager: any | null };
 type Projection = { sessionRevision: string; liveState: "offline" | "idle" | "running" | "paused" | "waiting-approval" | "uncertain" };
 
 function rpcUiContext(): object {
@@ -129,7 +129,7 @@ export class SessionRuntimeSupervisor {
   setProjectionReader(reader: (sessionRef: string) => Promise<Projection>): void { this.#readProjection = reader; }
 
   async listSessions(): Promise<PiSessionInfo[]> {
-    const persisted = await this.#listSessions();
+    const persisted = (await this.#listSessions()).filter(isUserConversationSession);
     const paths = new Set(persisted.map((info) => info.path));
     for (const [sessionRef, info] of this.#created) {
       if (paths.has(info.path)) this.#created.delete(sessionRef);
@@ -140,7 +140,7 @@ export class SessionRuntimeSupervisor {
   async create(projectRef: string, placeRef: string, modelRef: string | null, thinkingLevel: string): Promise<string> {
     if (this.#closed || !this.#host) throw new Error("session-create-unavailable");
     if (placeRef !== projectRef) throw new Error("session-place-mismatch");
-    const sessions = await this.#listSessions();
+    const sessions = (await this.#listSessions()).filter(isUserConversationSession);
     const imported = this.#resolveProject?.(projectRef) ?? null;
     const candidates = [...new Set([...sessions.filter((info) => projectRefForCwd(this.#key, info.cwd) === projectRef).map((info) => info.cwd),
       ...(imported ? [imported] : [])])];
@@ -166,6 +166,8 @@ export class SessionRuntimeSupervisor {
     return sessionRef;
   }
 
+  liveSessionManager(sessionRef: string): any | null { return this.#active.get(sessionRef)?.sessionManager ?? null; }
+
   async acquire(sessionRef: string): Promise<SessionLeaseSnapshot> {
     if (this.#closed) throw new Error("session-runtime-supervisor-closed");
     const active = this.#active.get(sessionRef);
@@ -179,7 +181,8 @@ export class SessionRuntimeSupervisor {
 
   async #acquire(sessionRef: string): Promise<SessionLeaseSnapshot> {
     if (this.#active.size + this.#opening.size > MAX_WARM_RUNTIMES) throw new Error("session-runtime-capacity");
-    const found = (await this.#listSessions()).filter((info) => sessionRefForPath(this.#key, info.path) === sessionRef);
+    const found = (await this.#listSessions()).filter(isUserConversationSession)
+      .filter((info) => sessionRefForPath(this.#key, info.path) === sessionRef);
     if (found.length !== 1) throw new Error(found.length ? "session-ref-ambiguous" : "session-not-found");
     return await this.#activate(sessionRef, found[0]!);
   }
@@ -201,7 +204,8 @@ export class SessionRuntimeSupervisor {
         throw new Error("session-owner-continuity-lost");
       }
       const active: ActiveRuntime = { runtime, lease: current, info, operationRef: null, unsubscribe: null, completion: null,
-        settling: false, approvalWaiting: false, unbindApproval: null, unsubscribeApproval: null };
+        settling: false, approvalWaiting: false, unbindApproval: null, unsubscribeApproval: null,
+        sessionManager: sessionManager ?? runtime.session?.sessionManager ?? null };
       this.#active.set(sessionRef, active);
       this.#bindApproval(sessionRef, active);
       return current;
@@ -271,15 +275,20 @@ export class SessionRuntimeSupervisor {
     };
   }
 
+  // `message` arrives already carrying any attached document text, and `images`
+  // already split out: the command controller claims staged refs before it calls
+  // here, so this layer only forwards what the host prompt takes.
   async send(sessionRef: string, payload: { delivery: "new-operation" | "follow-up" | "steer"; message: string;
-    expectedOperationRef: string | null }, sessionRevision: string): Promise<{ resultCode: "started" | "queued" | "steered"; operationRef: string }> {
+    expectedOperationRef: string | null; images?: unknown[] }, sessionRevision: string):
+  Promise<{ resultCode: "started" | "queued" | "steered"; operationRef: string }> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
     if (!active || !session) throw new Error("session-runtime-unavailable");
     if (payload.delivery !== "new-operation") {
       if (!active.operationRef || active.operationRef !== payload.expectedOperationRef || !session.isStreaming) throw new Error("session-operation-conflict");
-      if (payload.delivery === "follow-up") { await session.followUp(payload.message); return { resultCode: "queued", operationRef: active.operationRef }; }
-      await session.steer(payload.message); return { resultCode: "steered", operationRef: active.operationRef };
+      const images = payload.images?.length ? payload.images : undefined;
+      if (payload.delivery === "follow-up") { await session.followUp(payload.message, images); return { resultCode: "queued", operationRef: active.operationRef }; }
+      await session.steer(payload.message, images); return { resultCode: "steered", operationRef: active.operationRef };
     }
     if (payload.expectedOperationRef !== null || active.operationRef || active.settling || !session.isIdle) throw new Error("session-operation-conflict");
     const operationRef = `operation_${randomBytes(24).toString("base64url")}`;
@@ -292,7 +301,7 @@ export class SessionRuntimeSupervisor {
       created.firstMessage = payload.message; created.allMessagesText = payload.message; created.messageCount = 1; created.modified = new Date();
     }
     let prompt: Promise<void>;
-    try { prompt = session.prompt(payload.message); }
+    try { prompt = session.prompt(payload.message, payload.images?.length ? { images: payload.images } : undefined); }
     catch (error) { await this.#finishOperation(sessionRef, operationRef, stream); throw error; }
     active.completion = prompt.then(() => this.#finishOperation(sessionRef, operationRef, stream),
       () => this.#finishOperation(sessionRef, operationRef, stream));

package/packages/piagent-webui/package.json

@@ -17,7 +17,9 @@
     "@mui/icons-material": "^9.3.1",
     "@mui/material": "^9.3.1",
     "react": "19.2.8",
-    "react-dom": "19.2.8"
+    "react-dom": "19.2.8",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
     "@types/react": "19.2.18",

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,6 +104,17 @@ 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 });
@@ -113,13 +131,6 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
           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 (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]); }