@piagent/platform 1.4.0 → 1.5.1

package/packages/piagent-webui/dist/client/index.html

@@ -7,8 +7,8 @@
     <meta name="csp-nonce" content="__PIAGENT_CSP_NONCE__" />
     <meta name="piagent-webui-mode" content="__PIAGENT_WEBUI_MODE__" />
     <title>Piagent WebUI</title>
-    <script type="module" crossorigin src="/assets/index-DjMntaK5.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DwKCWbwd.css">
+    <script type="module" crossorigin src="/assets/index-MBZq8XLV.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BV-_03yl.css">
   </head>
   <body>
     <div id="root"></div>

package/packages/piagent-webui/extension/lifecycle-controller.ts

@@ -131,6 +131,21 @@ export class LifecycleController {
     return !inspectTaskControlState(current.cwd, task).dispatchBlocked && !this.#pendingStop;
   }
 
+  inputAllowed(ctx?: ExtensionContext): boolean {
+    const current = ctx ?? this.#ctx; if (!current || !this.#sameSession(current) || this.#pendingStop) return false;
+    const task = this.#task(current); if (!task) return true;
+    const state = inspectTaskControlState(current.cwd, task).state;
+    return state === "active" || state === "terminal";
+  }
+
+  toolAllowed(toolName: string, ctx?: ExtensionContext): boolean {
+    if (this.dispatchAllowed(ctx)) return true;
+    const current = ctx ?? this.#ctx; if (!current || !this.#sameSession(current) || this.#pendingStop) return false;
+    const task = this.#task(current);
+    return toolName === "piagent_task_start" && Boolean(task)
+      && inspectTaskControlState(current.cwd, task).state === "terminal";
+  }
+
   observeAgentStart(ctx: ExtensionContext): void { if (!this.#sameSession(ctx)) return; this.#phase = "model"; }
   observeToolStart(ctx: ExtensionContext): void { if (!this.#sameSession(ctx)) return; this.#toolDepth += 1; this.#phase = "tool"; }
   observeToolEnd(ctx: ExtensionContext): void { if (!this.#sameSession(ctx)) return; this.#toolDepth = Math.max(0, this.#toolDepth - 1);

package/packages/piagent-webui/extension/piagent-webui.ts

@@ -20,7 +20,7 @@ import { piSourceMutationGuard } from "../../piagent-core/runtime/policy/source-
 import { CoreInspectionProvider } from "../server/core-inspection-provider.ts";
 import type { SourceView } from "../server/read-model-provider.ts";
 import { SameSessionPiBridge, type BridgeTaskFacts } from "./same-session-bridge.ts";
-import { AttachmentStore } from "./attachment-store.ts";
+import { AttachmentStore } from "../../piagent-core/runtime/input/attachment-store.ts";
 import { HeldMessageQueue } from "./held-message-queue.ts";
 import { LifecycleController } from "./lifecycle-controller.ts";
 import { lifecycleRuntimeDraft } from "./lifecycle-event-adapter.ts";
@@ -78,6 +78,14 @@ function protectedPaths(ctx: ExtensionContext): string[] {
   } catch { return [".pi/piagent-state/**", ".pi/context-index.json"]; }
 }
 
+// The same profile grant `piagent_document_read` honours. Read from the profile
+// on every call rather than captured once, so an operator who adds a directory
+// mid-session sees it in the workspace without restarting Pi.
+function documentReadRoots(ctx: ExtensionContext): unknown {
+  try { return loadProjectContextIndexPolicy(PLATFORM_ROOT, ctx.cwd).profile.additionalReadRoots; }
+  catch { return []; }
+}
+
 function writeDescriptor(ctx: ExtensionContext, value: Record<string, unknown>): string {
   const directory = ensurePrivateStateDirectory(ctx.cwd, descriptorDirectory(ctx.cwd), "WebUI launcher directory");
   const target = resolveLocalStatePath(ctx.cwd, descriptorPath(ctx), { label: "WebUI launcher descriptor" });
@@ -144,6 +152,8 @@ function readMethod(provider: CoreInspectionProvider, queue: HeldMessageQueue, s
   if (method === "handoffHistory" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.handoffHistory(args[0]);
   if (method === "subagentTree" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.subagentTree(args[0]);
   if (method === "releaseMonitor" && args.length === 0) return provider.releaseMonitor();
+  if (method === "documents" && args.length === 0) return provider.documents();
+  if (method === "document" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.document(args[0]);
   if (method === "logPreview" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.logPreview(args[0]);
   if (method === "transcript" && args.length === 2 && (args[0] === null || typeof args[0] === "string" && REF.test(args[0]))
     && Number.isInteger(args[1]) && Number(args[1]) >= 1 && Number(args[1]) <= 200) return provider.transcript(args[0] as string | null, Number(args[1]));
@@ -184,7 +194,9 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
   let approvalBinding: { key: string; unbind(): void; unsubscribe(): void } | null = null;
   const bridge = new SameSessionPiBridge(pi, { runtimeInstanceId, taskFacts,
     prepareAttachments: (refs, request, identity, text) => {
-      if (!attachments) throw new Error("attachment-store-unavailable"); return attachments.claim(refs, request, identity, text);
+      if (!attachments) throw new Error("attachment-store-unavailable");
+      const reservation = attachments.reserve(refs, request, identity, text);
+      return { ...reservation.prepared, commit: reservation.commit, release: reservation.release };
     } });
   try { attachments = new AttachmentStore({ runtimeInstanceId, bridgeSnapshot: () => bridge.snapshot(),
     modelSupportsImages: () => Array.isArray(currentContext?.model?.input) && currentContext.model.input.includes("image") }); }
@@ -301,6 +313,7 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
       task: () => activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()),
       activityEvents: () => readContextTelemetry(ctx.cwd, { limit: 5_000 }) as unknown[],
       currentActivity: () => [], sessionEntries: () => ctx.sessionManager.getBranch(), protectedPaths: () => protectedPaths(ctx),
+      documentReadRoots: () => documentReadRoots(ctx),
       contextUsage: () => ctx.getContextUsage(), model: () => ctx.model,
       thinkingLevel: () => ctx.thinkingLevel ?? pi.getThinkingLevel(),
       queueProjection: () => queue.projection(),
@@ -398,10 +411,10 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("tool_call", (_event, ctx) => { publishPersisted(ctx); if (!isGatewayRuntimeContext(ctx) && !terminalAdapter?.dispatchAllowed(ctx)) return { block: true,
+  pi.on("tool_call", (event, ctx) => { publishPersisted(ctx); if (!isGatewayRuntimeContext(ctx) && !terminalAdapter?.dispatchAllowed(ctx)) return { block: true,
     reason: `Piagent cannot prove this terminal owns the session (${terminalAdapter?.reasonCode() ?? "terminal-session-adapter-unavailable"}).` };
-    if (!lifecycle.dispatchAllowed(ctx)) return { block: true,
-    reason: "Piagent lifecycle control blocks new tool work while the task is paused or stopping." }; });
+    if (!lifecycle.toolAllowed(String(event.toolName ?? ""), ctx)) return { block: true,
+    reason: "Piagent lifecycle control blocks tool work while the task is paused, stopping, or terminal. A terminal task may only start its successor." }; });
   pi.on("tool_result", (_event, ctx) => publishPersisted(ctx));
   pi.on("input", (event, ctx) => {
     if (!isGatewayRuntimeContext(ctx) && !terminalAdapter?.dispatchAllowed(ctx)) {
@@ -409,7 +422,7 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
       catch { /* optional UI */ }
       return { action: "handled" } as const;
     }
-    if (!lifecycle.dispatchAllowed(ctx)) {
+    if (!lifecycle.inputAllowed(ctx)) {
       try { ctx.ui.notify("Piagent task is paused or stopping. Resume it before sending new work.", "warning"); } catch { /* optional UI */ }
       return { action: "handled" } as const;
     }

package/packages/piagent-webui/extension/same-session-bridge.ts

@@ -5,11 +5,9 @@ import { webUiProjectRef, webUiSessionRef } from "../../piagent-core/runtime/ins
 export const WEBUI_CONTROL_ENTRY_TYPE = "piagent-webui-control-receipt-v1";
 const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/, PUBLIC_REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
 const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/, DIGEST = /^sha256:[a-f0-9]{64}$/;
-const IDEMPOTENCY = /^[A-Za-z0-9._~-]{32,128}$/;
-const MAX_EVENTS = 256, MAX_SESSION_ENTRIES = 50_000; type NullableRef = string | null;
-export type BridgeIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null; agentOperationId: string | null; toolCallId: null };
-export type BridgeRevisions = { runtimeRevision: string; taskRevision: NullableRef; controlRevision: NullableRef; workspaceRevision: NullableRef;
-  indexRevision: NullableRef; approvalRevision: NullableRef; sessionOptionRevision: NullableRef; queueRevision: NullableRef };
+const IDEMPOTENCY = /^[A-Za-z0-9._~-]{32,128}$/, MAX_EVENTS = 256, MAX_SESSION_ENTRIES = 50_000; type NullableRef = string | null;
+export type { BridgeIdentity, BridgeRevisions, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
+import type { BridgeIdentity, BridgeRevisions, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
 export type BridgeTaskFacts = { taskId: string; taskRunId: string; taskRevision: string; controlRevision: string;
   controlState: "active" | "pause-requested" | "paused" | "terminal" | "unknown" } | null;
 export type NewOperationChatCommand = {
@@ -29,13 +27,11 @@ export type ChatReceipt = {
 };
 export type BridgeEvent = { sequence: number; at: string; kind: "binding.ready" | "binding.closed" | "operation.started" | "operation.settled" | "command.receipt";
   sessionRef: string | null; operationRef: string | null; commandId: string | null; resultCode: string | null };
-export type BridgeSnapshot = { state: "unbound" | "ready" | "replacement-pending" | "shutdown"; identity: BridgeIdentity | null; revisions: BridgeRevisions | null;
-  liveness: "idle" | "running" | "unknown"; taskState: "none" | "active" | "pause-requested" | "paused" | "terminal" | "unknown"; eventSequence: number };
 export type SessionOptionMutationPermit = { commitObservation(record: (before: BridgeRevisions, after: BridgeRevisions) => void): { before: BridgeRevisions; after: BridgeRevisions; recorded: boolean } | null; release(): void };
 type Binding = { ctx: ExtensionContext; rawSessionId: string; identity: BridgeIdentity; revisions: BridgeRevisions; state: BridgeSnapshot["state"] };
 type SessionOptionPermitState = { token: number; generation: number; rawSessionId: string; before: BridgeRevisions; externalConflict: boolean };
 type DispatchContent = Parameters<ExtensionAPI["sendUserMessage"]>[0];
-type PreparedDispatch = { content: DispatchContent; observedText: string };
+type PreparedDispatch = { content: DispatchContent; observedText: string; commit?(): void; release?(): void };
 type PendingDispatch = { command: NewOperationChatCommand; operationId: string; before: BridgeRevisions; leafBefore: string | null; correlationToken: string;
   observedText: string; resolve(receipt: ChatReceipt): void; timer: NodeJS.Timeout; inputObserved: boolean };
 type Stored = { receipt: ChatReceipt; messageRequestId?: string; contentDigest?: string; attachmentRefs?: string[] };
@@ -371,11 +367,11 @@ export class SameSessionPiBridge {
       return this.#rejection(command, "stale-revision", "stale-revision", "The current Pi session changed before dispatch.");
     if (this.#sessionOptionPermit)
       return this.#rejection(command, "capability-unavailable", "session-option-change-in-progress", "A model or thinking change is being settled.");
+    const delivery = command.payload.delivery;
     const controlState = this.#taskFacts(binding.ctx)?.controlState;
-    if (controlState && controlState !== "active")
+    if (controlState && controlState !== "active" && !(controlState === "terminal" && delivery === "new-operation"))
       return this.#rejection(command, "capability-unavailable", controlState === "terminal" ? "task-terminal" : "task-control-gate-closed",
-        controlState === "terminal" ? "A completed task cannot accept another dispatch." : "Task lifecycle control currently blocks dispatch.");
-    const delivery = command.payload.delivery;
+        controlState === "terminal" ? "A terminal task accepts only a new operation that can establish its successor." : "Task lifecycle control currently blocks dispatch.");
     if (delivery === "new-operation" && (!binding.ctx.isIdle() || binding.identity.agentOperationId))
       return this.#rejection(command, "dispatch-rejected", "agent-not-idle", "A new operation can start only while the Pi session is idle.");
     if (delivery !== "new-operation" && (binding.ctx.isIdle() || !binding.identity.agentOperationId))
@@ -394,6 +390,7 @@ export class SameSessionPiBridge {
     this.#queueCounter += 1; const before = copy(binding.revisions); this.#refresh();
     const requested = this.#receipt(command, before, "requested", "dispatch-requested", null, false, operationId);
     if (!this.#record(requested, command.payload.messageRequestId, command.payload.contentDigest, command.payload.attachmentRefs)) {
+      prepared.release?.();
       if (delivery === "new-operation") {
         binding.identity.agentOperationId = null; this.#operationCounter += 1; this.#refresh();
       }
@@ -407,7 +404,10 @@ export class SameSessionPiBridge {
         correlationToken, observedText: prepared.observedText, resolve, timer, inputObserved: false };
       try { this.#dispatchContext.run(correlationToken, () => this.#pi.sendUserMessage(prepared.content,
         delivery === "new-operation" ? undefined : { deliverAs: delivery === "steer" ? "steer" : "followUp" })); }
-      catch { this.#settlePending("dispatch-rejected", "rejected", "pi-send-user-message-rejected", false); }
+      catch { prepared.release?.(); this.#messageRequests.delete(command.payload.messageRequestId);
+        this.#settlePending("dispatch-rejected", "rejected", "pi-send-user-message-rejected", false); return; }
+      try { prepared.commit?.(); }
+      catch { this.#settlePending("dispatch-unknown", "uncertain", "attachment-commit-unavailable", false); }
     });
   }
   #validate(command: NewOperationChatCommand): string | null {

package/packages/piagent-webui/gateway/ai-capability-inspection.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const PACKAGE_NAME = "pi-web-access";
+const VERSION = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/;
+const MAX_PACKAGE_MANIFEST_BYTES = 32 * 1024;
+
+export type WebSearchCapabilityProjection = {
+  state: "configured" | "unavailable";
+  route: "codex-first" | "automatic" | null;
+  provider: "openai-codex" | null;
+  fallbackProvider: "exa" | null;
+  integration: { name: "pi-web-access"; version: string } | null;
+  reasonCode: string | null;
+};
+
+function installedWebAccess(agentDir: string | undefined): { name: "pi-web-access"; version: string } | null {
+  if (!agentDir) return null;
+  const root = path.resolve(agentDir), manifest = path.resolve(root, "npm", "node_modules", PACKAGE_NAME, "package.json");
+  if (path.relative(root, manifest).startsWith("..")) return null;
+  try {
+    const canonicalRoot = fs.realpathSync.native(root), canonicalManifest = fs.realpathSync.native(manifest);
+    const relative = path.relative(canonicalRoot, canonicalManifest);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+    const inspected = fs.lstatSync(manifest);
+    if (!inspected.isFile() || inspected.isSymbolicLink() || inspected.size < 2 || inspected.size > MAX_PACKAGE_MANIFEST_BYTES) return null;
+    const parsed = JSON.parse(fs.readFileSync(manifest, "utf8")) as { name?: unknown; version?: unknown };
+    if (parsed.name !== PACKAGE_NAME || typeof parsed.version !== "string" || parsed.version.length > 64 || !VERSION.test(parsed.version)) return null;
+    return { name: PACKAGE_NAME, version: parsed.version };
+  } catch {
+    return null;
+  }
+}
+
+export function inspectWebSearchCapability(input: {
+  agentDir?: string;
+  models: readonly Record<string, unknown>[];
+}): WebSearchCapabilityProjection {
+  const integration = installedWebAccess(input.agentDir);
+  if (!integration) return {
+    state: "unavailable", route: null, provider: null, fallbackProvider: null, integration: null,
+    reasonCode: "web-search-integration-not-installed"
+  };
+  const codexAvailable = input.models.some((model) => model.provider === "openai-codex");
+  return {
+    state: "configured",
+    route: codexAvailable ? "codex-first" : "automatic",
+    provider: codexAvailable ? "openai-codex" : null,
+    fallbackProvider: "exa",
+    integration,
+    reasonCode: codexAvailable ? null : "codex-auth-not-available"
+  };
+}

package/packages/piagent-webui/gateway/extension-authority.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type ExtensionLoadResult = {
+  extensions: Array<{ path: string; resolvedPath: string }>;
+  errors: Array<{ path: string; error: string }>;
+  runtime: unknown;
+};
+
+const PIAGENT_GUARD_SUFFIX = path.join("packages", "piagent-core", "extensions", "piagent-guard.ts");
+
+function canonicalExtensionPath(value: string): string {
+  try { return fs.realpathSync.native(value); }
+  catch { return path.resolve(value); }
+}
+
+function isPiagentGuardPath(value: string): boolean {
+  const normalized = path.normalize(value);
+  return normalized === PIAGENT_GUARD_SUFFIX || normalized.endsWith(`${path.sep}${PIAGENT_GUARD_SUFFIX}`);
+}
+
+export function preferAuthoritativePiagentGuard(
+  guardPath: string
+): (base: ExtensionLoadResult) => ExtensionLoadResult {
+  const authoritative = canonicalExtensionPath(guardPath);
+  const authorityAliases = [guardPath, path.resolve(guardPath), authoritative].map((value) => path.normalize(value));
+  return (base) => {
+    const loadedAuthoritative = base.extensions.some((extension) =>
+      canonicalExtensionPath(extension.resolvedPath || extension.path) === authoritative);
+    if (!loadedAuthoritative) return base;
+    const removed = new Set<string>();
+    const extensions = base.extensions.filter((extension) => {
+      const resolved = canonicalExtensionPath(extension.resolvedPath || extension.path);
+      const duplicate = resolved !== authoritative && isPiagentGuardPath(resolved);
+      if (duplicate) removed.add(resolved);
+      return !duplicate;
+    });
+    if (removed.size === 0) return base;
+    const errors = base.errors.filter((diagnostic) => {
+      const diagnosticPath = canonicalExtensionPath(diagnostic.path);
+      return !(removed.has(diagnosticPath)
+        && diagnostic.error.includes("conflicts with")
+        && authorityAliases.some((value) => diagnostic.error.includes(value)));
+    });
+    return { ...base, extensions, errors };
+  };
+}

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import type { PiagentGatewayCapabilityHandshakeV1 } from "../contracts/generated/gateway-capabilities-v1.ts";
+import type { PiagentWebUICanonicalSnapshotV1 } from "../contracts/generated/snapshot-v1.ts";
 import { startLoopbackServer } from "../server/loopback-server.ts";
 import { startGatewayControlSocket, type GatewayControlResponse } from "./control-socket.ts";
 import { loadPinnedPiHost } from "./pi-host.ts";
@@ -24,6 +25,7 @@ import { SessionCommandStore } from "./session-command-store.ts";
 import { SessionCommandController } from "./session-command-controller.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionInspectionRegistry } from "./session-inspection-registry.ts";
+import { SessionAttachmentRegistry } from "./session-attachment-registry.ts";
 import { ProjectRegistry } from "./project-registry.ts";
 import { pickNativeProjectFolders } from "./native-project-picker.ts";
 import { ProviderAuthBroker } from "./provider-auth-broker.ts";
@@ -91,6 +93,7 @@ export async function startPiagentGateway(options: {
   let control: Awaited<ReturnType<typeof startGatewayControlSocket>> | null = null;
   let runtimes: SessionRuntimeSupervisor | null = null;
   let mcpAuth: McpAuthBroker | null = null;
+  let attachments: SessionAttachmentRegistry | null = null;
   let closing: Promise<void> | null = null;
   let settleWait: (() => void) | null = null;
   const waited = new Promise<void>((resolve) => { settleWait = resolve; });
@@ -100,6 +103,10 @@ export async function startPiagentGateway(options: {
     closing = (async () => {
       removeGatewayDescriptor(state, gatewayInstanceRef);
       await loopback?.close().catch(() => undefined);
+      // Staged bytes are private temp files. Closing deletes them rather than
+      // leaving a directory per session behind for the TTL sweep that will never
+      // run once this process is gone.
+      try { attachments?.close(); } catch { /* shutdown never fails on cleanup */ }
       await mcpAuth?.close().catch(() => undefined);
       await runtimes?.close().catch(() => undefined);
       await control?.close().catch(() => undefined);
@@ -161,11 +168,23 @@ export async function startPiagentGateway(options: {
       return { sessionRevision: session.sessionRevision, liveState: session.liveState };
     });
     const commands = new SessionCommandController({ catalog: readCatalog, runtimes, metadata,
-      store: new SessionCommandStore(state.root, key), events });
+      store: new SessionCommandStore(state.root, key), events,
+      // Resolved at call time: the attachment registry is built after this
+      // controller, because it reads sessions through the inspection registry.
+      prepareAttachments: (sessionRef, refs, messageRequestId, text) => {
+        if (!attachments) throw new Error("session-attachment-unavailable");
+        return attachments.reserveForPrompt(sessionRef, refs, messageRequestId, text);
+      } });
     const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true), catalog: readCatalog,
       events, command: commands });
-    const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot,
-      models: inspectionModels, projects, mcpAuth });
+    const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
+      models: inspectionModels, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
+      openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef) });
+    // Staged bytes live beside the inspection projection they were checked
+    // against, so both read the same session through the same registry.
+    attachments = new SessionAttachmentRegistry({
+      inspect: async (sessionRef) => await (await inspections.provider(sessionRef)).snapshot() as PiagentWebUICanonicalSnapshotV1
+    });
     loopback = await startLoopbackServer({
       staticRoot,
       mode: "gateway",
@@ -175,6 +194,7 @@ export async function startPiagentGateway(options: {
       readSessionModel: (sessionRef) => inspections.provider(sessionRef),
       readSessionConnections: (sessionRef) => inspections.connections(sessionRef),
       executeSessionConnection: (command) => inspections.executeConnectionCommand(command),
+      executeSessionAttachment: (sessionRef, command) => attachments.execute(sessionRef, command),
       executeApproval: (approvalRef, decision) => runtimes!.decideApproval(approvalRef, decision),
       readMcpAuthJob: (jobRef) => mcpAuth!.read(jobRef),
       cancelMcpAuthJob: (jobRef) => mcpAuth!.cancel(jobRef),

package/packages/piagent-webui/gateway/native-project-picker.ts

@@ -1,10 +1,27 @@
 import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-export function nativeProjectPickerAvailable(): boolean { return process.platform === "darwin"; }
+type PickerSpec = { executable: string; args: string[] };
+type PickerEnvironment = Readonly<Record<string, string | undefined>>;
 
-export function pickNativeProjectFolders(): Promise<string[]> {
-  if (!nativeProjectPickerAvailable()) return Promise.reject(new Error("native-project-picker-unavailable"));
-  return new Promise((resolve, reject) => {
+function executableOnPath(name: string, environment: PickerEnvironment): string | null {
+  for (const directory of String(environment.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(directory, name);
+    try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* try the next PATH entry */ }
+  }
+  return null;
+}
+
+// The browser deliberately cannot reveal an absolute directory path. The
+// Gateway therefore uses the desktop's own picker and receives only the paths
+// the operator selected. macOS ships AppleScript; Linux desktops commonly ship
+// one of the freedesktop-facing dialog helpers below.
+export function resolveNativeProjectPicker(options: { platform?: NodeJS.Platform; environment?: PickerEnvironment } = {}): PickerSpec | null {
+  const platform = options.platform ?? process.platform, environment = options.environment ?? process.env;
+  if (platform === "darwin") {
+    try { fs.accessSync("/usr/bin/osascript", fs.constants.X_OK); } catch { return null; }
     const script = [
       'set chosenFolders to choose folder with prompt "Choose project folders for Piagent" with multiple selections allowed',
       'set output to ""',
@@ -13,9 +30,48 @@ export function pickNativeProjectFolders(): Promise<string[]> {
       'end repeat',
       'return output'
     ].join("\n");
-    execFile("/usr/bin/osascript", ["-e", script], { timeout: 5 * 60_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
-      if (error) { reject(new Error("project-import-cancelled")); return; }
-      const selected = [...new Set(stdout.split("\n").map((value) => value.trim()).filter(Boolean))].slice(0, 32);
+    return { executable: "/usr/bin/osascript", args: ["-e", script] };
+  }
+  if (platform !== "linux" || !(environment.DISPLAY || environment.WAYLAND_DISPLAY)) return null;
+  for (const name of ["zenity", "qarma"]) {
+    const executable = executableOnPath(name, environment);
+    if (executable) return { executable, args: ["--file-selection", "--directory", "--multiple", "--separator=\n",
+      "--title=Choose project folders for Piagent"] };
+  }
+  const kdialog = executableOnPath("kdialog", environment);
+  return kdialog ? { executable: kdialog, args: ["--getexistingdirectory", process.cwd(), "--title", "Choose a project folder for Piagent"] } : null;
+}
+
+export function nativeProjectPickerAvailable(options: { platform?: NodeJS.Platform; environment?: PickerEnvironment } = {}): boolean {
+  return resolveNativeProjectPicker(options) !== null;
+}
+
+function selectedFolders(stdout: string): string[] {
+  const selected: string[] = [];
+  for (const raw of stdout.split("\n")) {
+    const value = raw.trim(); if (!value) continue;
+    let candidate = value;
+    if (value.startsWith("file:")) {
+      try { candidate = fileURLToPath(value); } catch { continue; }
+    }
+    if (candidate.includes("\0") || /[\u0001-\u001f\u007f]/.test(candidate) || selected.includes(candidate)) continue;
+    selected.push(candidate);
+    if (selected.length === 32) break;
+  }
+  return selected;
+}
+
+export function pickNativeProjectFolders(): Promise<string[]> {
+  const picker = resolveNativeProjectPicker();
+  if (!picker) return Promise.reject(new Error("native-project-picker-unavailable"));
+  return new Promise((resolve, reject) => {
+    execFile(picker.executable, picker.args, { timeout: 5 * 60_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
+      if (error) {
+        const exitCode = typeof (error as NodeJS.ErrnoException & { code?: unknown }).code === "number"
+          ? (error as unknown as { code: number }).code : null;
+        reject(new Error(exitCode === 1 ? "project-import-cancelled" : "project-import-picker-failed")); return;
+      }
+      const selected = selectedFolders(stdout);
       if (!selected.length) { reject(new Error("project-import-cancelled")); return; }
       resolve(selected);
     });

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

@@ -0,0 +1,165 @@
+import type { PiagentWebUICanonicalSnapshotV1 } from "../contracts/generated/snapshot-v1.ts";
+import { AttachmentStore, type DiscardReceipt, type PreparedAttachments,
+  type StageReceipt } from "../../piagent-core/runtime/input/attachment-store.ts";
+import type { AttachmentReservation } from "../../piagent-core/runtime/input/attachment-reservation.ts";
+import type { BridgeIdentity, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
+
+// Attachments for sessions the Gateway drives.
+//
+// The in-session WebUI stages attachments against a live `SameSessionPiBridge`,
+// which knows the identity and revisions of the session it is bound to. The
+// Gateway has no such bridge: it owns many sessions and reads each one through
+// an inspection provider. What it does have is the exact snapshot the browser
+// was given, and that snapshot carries the same identity and revisions the
+// browser will quote back in a stage command.
+//
+// So the bridge the store needs is synthesised from that snapshot, immediately
+// before the store reads it. The store's identity and revision checks then
+// compare the browser's claim against the same projection the browser was
+// answering, which is the property those checks exist to enforce — a command
+// aimed at a session that has since changed is refused rather than applied to
+// whatever the session became.
+
+const MAX_SESSION_STORES = 16;
+
+function bridgeIdentity(snapshot: PiagentWebUICanonicalSnapshotV1): BridgeIdentity {
+  const identity = snapshot.identity;
+  return { projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId, sessionRef: identity.sessionRef,
+    taskId: identity.taskId ?? null, taskRunId: identity.taskRunId ?? null, agentOperationId: identity.agentOperationId ?? null,
+    toolCallId: null };
+}
+
+function bridgeSnapshotOf(snapshot: PiagentWebUICanonicalSnapshotV1): BridgeSnapshot {
+  const revision = snapshot.revision;
+  // A terminal session refuses staging inside the store. Everything else the
+  // Gateway can answer for is a session the operator may still attach to.
+  const controlState = snapshot.session.controlState;
+  return {
+    state: "ready",
+    identity: bridgeIdentity(snapshot),
+    revisions: { runtimeRevision: revision.runtimeRevision, taskRevision: revision.taskRevision ?? null,
+      controlRevision: revision.controlRevision ?? null, workspaceRevision: revision.workspaceRevision ?? null,
+      indexRevision: revision.indexRevision ?? null, approvalRevision: revision.approvalRevision ?? null,
+      sessionOptionRevision: revision.sessionOptionRevision ?? null, queueRevision: revision.queueRevision ?? null },
+    liveness: snapshot.session.operation.liveness === "running" ? "running" : "idle",
+    taskState: controlState === "terminal" ? "terminal" : controlState === "active" ? "active" : "unknown",
+    eventSequence: 0
+  };
+}
+
+function supportsImages(snapshot: PiagentWebUICanonicalSnapshotV1): boolean {
+  const model = snapshot.session.model;
+  // The contract types this as a tuple union to bound its length, which leaves
+  // includes() narrowed to never. The runtime value is a list of strings.
+  const capabilities = model.value?.inputCapabilities as readonly string[] | undefined;
+  return model.state === "known" && Boolean(capabilities?.includes("image"));
+}
+
+type Slot = { store: AttachmentStore; current: BridgeSnapshot; images: boolean };
+
+export class SessionAttachmentRegistry {
+  readonly #slots = new Map<string, Slot>();
+  readonly #inspect: (sessionRef: string) => Promise<PiagentWebUICanonicalSnapshotV1>;
+  readonly #tempRoot: string | undefined;
+  readonly #now: (() => Date) | undefined;
+  #closed = false;
+
+  constructor(options: { inspect: (sessionRef: string) => Promise<PiagentWebUICanonicalSnapshotV1>; tempRoot?: string; now?: () => Date }) {
+    this.#inspect = options.inspect;
+    this.#tempRoot = options.tempRoot;
+    this.#now = options.now;
+  }
+
+  // Every entry point refreshes the synthesised bridge first. A store that kept
+  // the snapshot it was created with would accept a command aimed at a revision
+  // the session has already moved past.
+  async #slot(sessionRef: string): Promise<Slot> {
+    if (this.#closed) throw new Error("session-attachment-registry-closed");
+    const snapshot = await this.#inspect(sessionRef);
+    const existing = this.#slots.get(sessionRef);
+    if (existing) {
+      existing.current = bridgeSnapshotOf(snapshot);
+      existing.images = supportsImages(snapshot);
+      // Refresh recency so the cap evicts the least recently used session.
+      this.#slots.delete(sessionRef); this.#slots.set(sessionRef, existing);
+      return existing;
+    }
+    const slot: Slot = { current: bridgeSnapshotOf(snapshot), images: supportsImages(snapshot), store: null as unknown as AttachmentStore };
+    slot.store = new AttachmentStore({
+      runtimeInstanceId: snapshot.identity.runtimeInstanceId,
+      bridgeSnapshot: () => slot.current,
+      modelSupportsImages: () => slot.images,
+      tempRoot: this.#tempRoot,
+      now: this.#now
+    });
+    this.#slots.set(sessionRef, slot);
+    // Each store owns a private directory and staged bytes, so an unbounded map
+    // is unbounded disk. The evicted store deletes what it held.
+    while (this.#slots.size > MAX_SESSION_STORES) {
+      const oldest = this.#slots.keys().next().value as string;
+      if (oldest === sessionRef) break;
+      this.#slots.get(oldest)?.store.close();
+      this.#slots.delete(oldest);
+    }
+    return slot;
+  }
+
+  async execute(sessionRef: string, command: unknown): Promise<StageReceipt | DiscardReceipt> {
+    return (await this.#slot(sessionRef)).store.execute(command);
+  }
+
+  async capability(sessionRef: string): Promise<{ kinds: Array<"file" | "image" | "document">; mimeTypes: string[] }> {
+    return (await this.#slot(sessionRef)).store.capability();
+  }
+
+  // Claimed at dispatch, from the send path, which already holds the identity it
+  // is sending under. Refs are one-shot: a claim consumes them.
+  async claim(sessionRef: string, refs: string[], messageRequestId: string, text: string): Promise<PreparedAttachments> {
+    const slot = await this.#slot(sessionRef);
+    if (!slot.current.identity) throw new Error("session-attachment-identity-unavailable");
+    return slot.store.claim(refs, messageRequestId, slot.current.identity, text);
+  }
+
+  async reserve(sessionRef: string, refs: string[], messageRequestId: string, text: string): Promise<AttachmentReservation<PreparedAttachments>> {
+    const slot = await this.#slot(sessionRef);
+    if (!slot.current.identity) throw new Error("session-attachment-identity-unavailable");
+    return slot.store.reserve(refs, messageRequestId, slot.current.identity, text);
+  }
+
+  // The shape the host prompt takes. Documents and text files were already
+  // turned into text when they were staged, so they join the prompt string;
+  // images ride the host's own `images` channel. Split here rather than in the
+  // supervisor so the knowledge of what a claim returns stays next to the store
+  // that produced it.
+  async claimForPrompt(sessionRef: string, refs: string[], messageRequestId: string, message: string):
+  Promise<{ text: string; images: unknown[] }> {
+    if (refs.length === 0) return { text: message, images: [] };
+    const prepared = await this.claim(sessionRef, refs, messageRequestId, message);
+    const parts = Array.isArray(prepared.content) ? prepared.content : [{ type: "text" as const, text: message }];
+    return {
+      text: parts.filter((part) => part.type === "text").map((part) => part.text).join("\n"),
+      images: parts.filter((part) => part.type === "image")
+    };
+  }
+
+
+  async reserveForPrompt(sessionRef: string, refs: string[], messageRequestId: string, message: string):
+  Promise<{ text: string; images: unknown[]; commit(): void; release(): void }> {
+    if (refs.length === 0) return { text: message, images: [], commit() {}, release() {} };
+    const reservation = await this.reserve(sessionRef, refs, messageRequestId, message);
+    const parts = Array.isArray(reservation.prepared.content) ? reservation.prepared.content
+      : [{ type: "text" as const, text: message }];
+    return {
+      text: parts.filter((part) => part.type === "text").map((part) => part.text).join("\n"),
+      images: parts.filter((part) => part.type === "image"),
+      commit: reservation.commit,
+      release: reservation.release
+    };
+  }
+
+  close(): void {
+    this.#closed = true;
+    for (const slot of this.#slots.values()) slot.store.close();
+    this.#slots.clear();
+  }
+}