@chainingintention/pi-web-cn 1.202606.10 → 1.202606.12

package/dist/server/sessions/piSessionService.js

@@ -1,9 +1,5 @@
-import { spawn } from "node:child_process";
-import { constants } from "node:fs";
-import { access as fsAccess, mkdir as fsMkdir, readFile, readdir as fsReaddir, realpath as fsRealpath, stat as fsStat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { AuthStorage, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, defineTool, getAgentDir, ModelRegistry, SessionManager, } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { readFile, writeFile } from "node:fs/promises";
+import { AuthStorage, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, defineTool, getAgentDir, ModelRegistry, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { pageMessagesAtSafeBoundary } from "./messagePaging.js";
 import { BUILTIN_COMMANDS } from "./builtinCommands.js";
 import { SessionCommandService } from "./sessionCommandService.js";
@@ -11,15 +7,25 @@ import { SessionArchiveStore } from "./sessionArchiveStore.js";
 import { findArchiveCandidateByIdOrPrefix, planSessionArchiveTree } from "./sessionArchiveTree.js";
 import { fallbackSessionName, generateShortSessionName } from "./sessionNameGenerator.js";
 import { computeEditPreview } from "./editPreview.js";
-import { managementToolAllowed } from "../managementEmbed.js";
-import { bubblewrapUnavailableReason, createBubblewrapPythonInvocation, createManagedPythonFallbackPrelude, createManagedSandboxEnvironment, DEFAULT_BUBBLEWRAP_PATHS } from "./managementSandbox.js";
-import { PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR, managementAgentToolNames, withRuntimeCreationEnvironment, writeManagementPermissionSystemPolicy } from "./managementPermissionSystem.js";
+import { createPiSessionManagerGateway } from "./piSessionManagerGateway.js";
+import { attachmentsToInlineImages, saveAttachmentsToWorkspace } from "./attachmentService.js";
+import { parsePromptAttachments } from "../../shared/promptAttachments.js";
+import { cwdPathsEqual } from "../workingDirectory.js";
 function noop() {
     // Intentionally empty default unsubscribe callback.
 }
 function authLossWarningKey(sessionId, provider, modelId) {
     return `${sessionId}:${provider}/${modelId}`;
 }
+function sessionIdFromLookup(ref) {
+    return typeof ref === "string" ? ref : ref.id;
+}
+function isPiSessionRef(ref) {
+    return typeof ref !== "string";
+}
+function lookupMatchesActiveSession(ref, active) {
+    return !isPiSessionRef(ref) || cwdPathsEqual(active.runtime.cwd, ref.cwd);
+}
 function requirePromptText(value) {
     if (typeof value !== "string")
         throw new Error("Prompt text is required");
@@ -39,47 +45,17 @@ function defaultCreateAgentRuntime(createRuntime, options) {
 }
 function createDefaultRuntimeFactory(authStorage, modelRegistry) {
     return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
-        return withRuntimeCreationEnvironment({}, async () => {
-            const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
-            const customTools = [createPiWebEditToolDefinition(cwd)];
-            const options = sessionStartEvent === undefined
-                ? { services, sessionManager, customTools }
-                : { services, sessionManager, sessionStartEvent, customTools };
-            const result = await createAgentSessionFromServices(options);
-            return { ...result, services, diagnostics: services.diagnostics };
-        });
-    };
-}
-function createManagementRuntimeFactory(authStorage, modelRegistry, managementContext) {
-    return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
-        const policyAgentDir = await writeManagementPermissionSystemPolicy(agentDir, cwd, managementContext);
-        return withRuntimeCreationEnvironment({ [PI_PERMISSION_SYSTEM_POLICY_AGENT_DIR]: policyAgentDir }, async () => {
-            const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
-            const customTools = createManagementSandboxToolDefinitions(cwd, managementContext);
-            const options = sessionStartEvent === undefined
-                ? { services, sessionManager, customTools, tools: managementAgentToolNames(managementContext) }
-                : { services, sessionManager, sessionStartEvent, customTools, tools: managementAgentToolNames(managementContext) };
-            // @ts-expect-error SDK customTools accepts concrete ToolDefinition instances at runtime, but the published type is invariant in render callbacks.
-            const result = await createAgentSessionFromServices(options);
-            return { ...result, services, diagnostics: services.diagnostics };
-        });
+        const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
+        const customTools = [createPiWebEditToolDefinition(cwd)];
+        const options = sessionStartEvent === undefined
+            ? { services, sessionManager, customTools }
+            : { services, sessionManager, sessionStartEvent, customTools };
+        const result = await createAgentSessionFromServices(options);
+        return { ...result, services, diagnostics: services.diagnostics };
     };
 }
-export { managementAgentToolNames };
-export function createManagementSandboxToolDefinitions(cwd, context) {
-    const operations = createManagedFileOperations(cwd);
-    return [
-        createReadToolDefinition(cwd, { operations: operations.read }),
-        createWriteToolDefinition(cwd, { operations: operations.write }),
-        createPiWebEditToolDefinition(cwd, operations.edit),
-        createLsToolDefinition(cwd, { operations: operations.ls }),
-        createGrepToolDefinition(cwd, { operations: operations.grep }),
-        createFindToolDefinition(cwd, { operations: operations.find }),
-        createManagedPythonToolDefinition(cwd, context),
-    ];
-}
-function createPiWebEditToolDefinition(cwd, operations) {
-    const editTool = createEditToolDefinition(cwd, operations === undefined ? undefined : { operations });
+function createPiWebEditToolDefinition(cwd) {
+    const editTool = createEditToolDefinition(cwd);
     return defineTool({
         name: editTool.name,
         label: editTool.label,
@@ -99,211 +75,6 @@ function createPiWebEditToolDefinition(cwd, operations) {
         },
     });
 }
-const pythonSchema = Type.Object({
-    code: Type.String({ description: "Python code to run in the managed project workspace" }),
-    timeoutMs: Type.Optional(Type.Number({ description: "Execution timeout in milliseconds" })),
-});
-function createManagedPythonToolDefinition(cwd, context) {
-    return defineTool({
-        name: "python",
-        label: "python",
-        description: "Run Python code inside the managed project workspace. Shell commands and paths outside the project are blocked.",
-        promptSnippet: "Run Python code in the current project",
-        promptGuidelines: ["Use python for scripts and calculations. Do not use it to run shell commands."],
-        parameters: pythonSchema,
-        async execute(_toolCallId, params, signal) {
-            const configuredPython = context.sandbox?.pythonExecutable?.trim();
-            const pythonExecutable = configuredPython !== undefined && configuredPython !== "" ? configuredPython : "python3";
-            const timeoutMs = Math.max(1_000, Math.min(params.timeoutMs ?? 30_000, 120_000));
-            const configuredBubblewrap = process.env["PI_WEB_BWRAP_EXECUTABLE"]?.trim();
-            const bubblewrapExecutable = configuredBubblewrap !== undefined && configuredBubblewrap !== "" ? configuredBubblewrap : "bwrap";
-            const env = createManagedSandboxEnvironment({ hostEnv: process.env, context });
-            return runManagedPython({ pythonExecutable, bubblewrapExecutable, cwd, code: params.code, timeoutMs, env, signal });
-        },
-    });
-}
-async function runManagedPython(options) {
-    const root = await fsRealpath(options.cwd);
-    const invocation = createBubblewrapPythonInvocation({
-        bubblewrapExecutable: options.bubblewrapExecutable,
-        pythonExecutable: options.pythonExecutable,
-        workspaceRoot: root,
-        env: options.env,
-        readOnlyPaths: await readableBubblewrapPaths(),
-    });
-    const result = await runPythonProcess({ command: invocation.command, args: invocation.args, cwd: root, env: options.env, code: options.code, timeoutMs: options.timeoutMs, signal: options.signal });
-    const unavailable = bubblewrapUnavailableReason(result.output);
-    if (unavailable !== undefined) {
-        return runManagedPythonFallback({ pythonExecutable: options.pythonExecutable, cwd: root, code: options.code, timeoutMs: options.timeoutMs, env: options.env, signal: options.signal });
-    }
-    return pythonToolResult(result.code, result.output);
-}
-async function runManagedPythonFallback(options) {
-    const code = `${createManagedPythonFallbackPrelude(options.cwd)}\n${options.code}`;
-    const result = await runPythonProcess({ command: options.pythonExecutable, args: ["-I", "-"], cwd: options.cwd, env: options.env, code, timeoutMs: options.timeoutMs, signal: options.signal });
-    return pythonToolResult(result.code, result.output);
-}
-async function runPythonProcess(options) {
-    return new Promise((resolvePromise, reject) => {
-        if (options.signal?.aborted === true) {
-            reject(new Error("Operation aborted"));
-            return;
-        }
-        const child = spawn(options.command, options.args, { cwd: options.cwd, env: options.env, stdio: ["pipe", "pipe", "pipe"], shell: false });
-        let stdout = "";
-        let stderr = "";
-        const timer = setTimeout(() => {
-            child.kill();
-            reject(new Error(`Python execution timed out after ${String(options.timeoutMs)}ms`));
-        }, options.timeoutMs);
-        const onAbort = () => {
-            child.kill();
-            reject(new Error("Operation aborted"));
-        };
-        options.signal?.addEventListener("abort", onAbort, { once: true });
-        child.stdout.on("data", (chunk) => { stdout += chunk.toString("utf8"); });
-        child.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
-        child.on("error", (error) => {
-            clearTimeout(timer);
-            options.signal?.removeEventListener("abort", onAbort);
-            if (isNodeErrorWithCode(error, "ENOENT"))
-                reject(new Error("Python sandbox is unavailable"));
-            else
-                reject(error);
-        });
-        child.on("close", (codeValue) => {
-            clearTimeout(timer);
-            options.signal?.removeEventListener("abort", onAbort);
-            const output = truncateToolOutput([stdout.trimEnd(), stderr.trimEnd()].filter((part) => part !== "").join("\n"));
-            resolvePromise({ code: codeValue, output });
-        });
-        child.stdin.end(options.code);
-    });
-}
-function pythonToolResult(codeValue, output) {
-    const prefix = codeValue === 0 ? "" : `Python exited with code ${String(codeValue)}\n`;
-    return { content: [{ type: "text", text: `${prefix}${output}`.trimEnd() }], details: undefined };
-}
-async function readableBubblewrapPaths() {
-    const paths = await Promise.all(DEFAULT_BUBBLEWRAP_PATHS.map(async (path) => {
-        try {
-            await fsAccess(path, constants.R_OK);
-            return path;
-        }
-        catch {
-            return undefined;
-        }
-    }));
-    return paths.filter(isDefined);
-}
-function createManagedFileOperations(cwd) {
-    const read = {
-        readFile: async (absolutePath) => readFile(await assertExistingInside(cwd, absolutePath)),
-        access: async (absolutePath) => { await fsAccess(await assertExistingInside(cwd, absolutePath), constants.R_OK); },
-    };
-    const write = {
-        writeFile: async (absolutePath, content) => { await writeFile(await assertWritableInside(cwd, absolutePath), content, "utf8"); },
-        mkdir: async (dir) => { await fsMkdir(await assertPotentialInside(cwd, dir), { recursive: true }); },
-    };
-    const edit = {
-        readFile: read.readFile,
-        writeFile: write.writeFile,
-        access: async (absolutePath) => { await fsAccess(await assertExistingInside(cwd, absolutePath), constants.R_OK | constants.W_OK); },
-    };
-    const ls = {
-        exists: async (absolutePath) => pathExistsInside(cwd, absolutePath),
-        stat: async (absolutePath) => fsStat(await assertExistingInside(cwd, absolutePath)),
-        readdir: async (absolutePath) => fsReaddir(await assertExistingInside(cwd, absolutePath)),
-    };
-    const grep = {
-        isDirectory: async (absolutePath) => (await fsStat(await assertExistingInside(cwd, absolutePath))).isDirectory(),
-        readFile: async (absolutePath) => (await readFile(await assertExistingInside(cwd, absolutePath), "utf8")),
-    };
-    const find = {
-        exists: async (absolutePath) => pathExistsInside(cwd, absolutePath),
-        glob: async (pattern, searchPath, options) => managedGlob(cwd, pattern, searchPath, options.limit),
-    };
-    return { read, write, edit, ls, grep, find };
-}
-async function pathExistsInside(rootPath, targetPath) {
-    try {
-        await assertExistingInside(rootPath, targetPath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function managedGlob(rootPath, pattern, searchPath, limit) {
-    const root = await fsRealpath(rootPath);
-    const start = await assertExistingInside(root, searchPath);
-    const regex = globPatternToRegExp(pattern);
-    const results = [];
-    async function walk(dir) {
-        if (results.length >= limit)
-            return;
-        const entries = await fsReaddir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (results.length >= limit)
-                return;
-            if (entry.name === ".git" || entry.name === "node_modules")
-                continue;
-            const fullPath = resolve(dir, entry.name);
-            const safePath = await assertExistingInside(root, fullPath);
-            const rel = relative(start, safePath).split(sep).join("/");
-            if (entry.isDirectory()) {
-                await walk(safePath);
-            }
-            else if (regex.test(rel)) {
-                results.push(safePath);
-            }
-        }
-    }
-    await walk(start);
-    return results;
-}
-function globPatternToRegExp(pattern) {
-    const escaped = pattern
-        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-        .replace(/\*\*/g, "\0")
-        .replace(/\*/g, "[^/]*")
-        .replace(/\?/g, "[^/]")
-        .replace(/\0/g, ".*");
-    return new RegExp(`^${escaped}$`);
-}
-async function assertExistingInside(rootPath, targetPath) {
-    const [root, target] = await Promise.all([fsRealpath(rootPath), fsRealpath(targetPath)]);
-    ensurePathInside(root, target);
-    return target;
-}
-async function assertWritableInside(rootPath, targetPath) {
-    try {
-        return await assertExistingInside(rootPath, targetPath);
-    }
-    catch {
-        const parent = await assertExistingInside(rootPath, dirname(targetPath));
-        const target = resolve(parent, basename(targetPath));
-        ensurePathInside(await fsRealpath(rootPath), target);
-        return target;
-    }
-}
-async function assertPotentialInside(rootPath, targetPath) {
-    const root = await fsRealpath(rootPath);
-    const target = resolve(targetPath);
-    ensurePathInside(root, target);
-    return target;
-}
-function ensurePathInside(root, target) {
-    const rel = relative(root, target);
-    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel) && (sep === "/" || !rel.split(sep).includes(".."))))
-        return;
-    throw new Error("Path is outside the managed project sandbox");
-}
-function truncateToolOutput(value, limit = 64_000) {
-    if (value.length <= limit)
-        return value;
-    return `${value.slice(0, limit)}\n[output truncated]`;
-}
 export class PiSessionService {
     constructor(events, deps = {}) {
         this.events = events;
@@ -312,10 +83,9 @@ export class PiSessionService {
         this.compactionPromptQueues = new Map();
         this.compactionDrainTimers = new Map();
         this.authLossWarnings = new Set();
-        this.managementContexts = new Map();
         this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
         this.agentDir = deps.agentDir ?? getAgentDir();
-        this.sessionManager = deps.sessionManager ?? SessionManager;
+        this.sessionManager = deps.sessionManager ?? createPiSessionManagerGateway({ agentDir: this.agentDir });
         this.modelRegistry = deps.modelRegistry ?? ModelRegistry.create(AuthStorage.create());
         this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry);
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
@@ -343,7 +113,6 @@ export class PiSessionService {
         this.activities.clear();
         this.compactionPromptQueues.clear();
         this.authLossWarnings.clear();
-        this.managementContexts.clear();
         await Promise.all(activeSessions.map(async (active) => {
             active.unsubscribe();
             this.workspaceActivity?.removeSession(active.runtime.session.sessionId, active.runtime.session.sessionManager.getCwd());
@@ -366,11 +135,10 @@ export class PiSessionService {
             .filter(isDefined);
         return [...unarchivedSessions, ...archivedSessions];
     }
-    async start(cwd, managementContext) {
-        const active = await this.create(this.sessionManager.create(cwd), cwd, managementContext);
+    async start(cwd, _managementContext) {
+        void _managementContext;
+        const active = await this.create(this.sessionManager.create(cwd), cwd);
         const { session } = active.runtime;
-        if (managementContext !== undefined)
-            this.managementContexts.set(session.sessionId, managementContext);
         return {
             id: session.sessionId,
             path: session.sessionFile ?? "",
@@ -381,24 +149,24 @@ export class PiSessionService {
             firstMessage: "",
         };
     }
-    async messages(sessionId, page) {
-        const session = await this.getOrOpen(sessionId);
+    async messages(ref, page) {
+        const session = await this.getOrOpen(ref);
         return pageMessagesAtSafeBoundary(historyMessages(session), page);
     }
-    async status(sessionId) {
-        return this.statusFromSession(await this.getOrOpen(sessionId));
+    async status(ref) {
+        return this.statusFromSession(await this.getOrOpen(ref));
     }
-    async availableModels(sessionId) {
-        const session = await this.getOrOpen(sessionId);
+    async availableModels(ref) {
+        const session = await this.getOrOpen(ref);
         session.modelRegistry.refresh();
         const models = session.scopedModels.length > 0
             ? session.scopedModels.map((scoped) => scoped.model)
             : session.modelRegistry.getAvailable();
         return models.map(modelToClientModel);
     }
-    async setModel(sessionId, provider, modelId) {
-        await this.assertWritable(sessionId);
-        const session = await this.getOrOpen(sessionId);
+    async setModel(ref, provider, modelId) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
         session.modelRegistry.refresh();
         const candidates = session.scopedModels.length > 0
             ? session.scopedModels.map((scoped) => scoped.model)
@@ -412,9 +180,9 @@ export class PiSessionService {
         this.publishStatus(session);
         return this.statusFromSession(session);
     }
-    async cycleModel(sessionId, direction) {
-        await this.assertWritable(sessionId);
-        const session = await this.getOrOpen(sessionId);
+    async cycleModel(ref, direction) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
         const result = await session.cycleModel(direction);
         if (result === undefined)
             throw new Error(session.scopedModels.length > 0 ? "Only one model in scope" : "Only one model available");
@@ -422,21 +190,27 @@ export class PiSessionService {
         this.publishStatus(session);
         return this.statusFromSession(session);
     }
-    async availableThinkingLevels(sessionId) {
-        const session = await this.getOrOpen(sessionId);
+    async availableThinkingLevels(ref) {
+        const session = await this.getOrOpen(ref);
         return session.getAvailableThinkingLevels();
     }
-    async setThinkingLevel(sessionId, level) {
-        await this.assertWritable(sessionId);
-        const session = await this.getOrOpen(sessionId);
-        session.setThinkingLevel(level);
+    async setThinkingLevel(ref, level) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        // pi owns the valid set; validate against the session's live levels rather
+        // than a hardcoded union so this stays correct if pi changes the set.
+        const available = session.getAvailableThinkingLevels();
+        const match = available.find((candidate) => candidate === level);
+        if (match === undefined)
+            throw new Error(`Invalid thinking level: ${level}`);
+        session.setThinkingLevel(match);
         this.publishActivity(session, `thinking: ${session.thinkingLevel}`, "idle");
         this.publishStatus(session);
         return this.statusFromSession(session);
     }
-    async cycleThinkingLevel(sessionId) {
-        await this.assertWritable(sessionId);
-        const session = await this.getOrOpen(sessionId);
+    async cycleThinkingLevel(ref) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
         const level = session.cycleThinkingLevel();
         if (level === undefined)
             throw new Error("Current model does not support thinking");
@@ -444,8 +218,8 @@ export class PiSessionService {
         this.publishStatus(session);
         return this.statusFromSession(session);
     }
-    async commands(sessionId) {
-        const session = await this.getOrOpen(sessionId);
+    async commands(ref) {
+        const session = await this.getOrOpen(ref);
         const commands = [...BUILTIN_COMMANDS];
         for (const command of session.extensionRunner.getRegisteredCommands()) {
             commands.push({ name: command.invocationName, ...(command.description === undefined ? {} : { description: command.description }), source: "extension" });
@@ -458,30 +232,34 @@ export class PiSessionService {
         }
         return commands.sort((a, b) => a.name.localeCompare(b.name));
     }
-    async prompt(sessionId, text, streamingBehavior, managementContext) {
+    async prompt(ref, text, streamingBehavior, attachments, _managementContext) {
+        void _managementContext;
         const promptText = requirePromptText(text);
         const requestedBehavior = parsePromptStreamingBehavior(streamingBehavior);
-        await this.assertWritable(sessionId);
-        const session = await this.getOrOpen(sessionId, managementContext);
+        const parsedAttachments = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false });
+        const images = (await attachmentsToInlineImages(parsedAttachments)).map((entry) => entry.image);
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
         this.maybeGenerateSessionName(session, promptText);
         const isQueued = session.isStreaming || session.isCompacting;
         const behavior = isQueued ? requestedBehavior ?? "followUp" : undefined;
-        if (isQueued && this.hasQueuedMessageText(session, promptText)) {
+        if (isQueued && images.length === 0 && this.hasQueuedMessageText(session, promptText)) {
             this.publishActivity(session, "duplicate queued message ignored", "active");
             this.publishStatus(session);
             return;
         }
         if (session.isCompacting) {
-            this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp");
+            this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp", images);
             return;
         }
-        void this.submitPrompt(session, promptText, behavior);
+        void this.submitPrompt(session, promptText, behavior, images);
     }
-    submitPrompt(session, text, behavior) {
+    submitPrompt(session, text, behavior, images = []) {
         this.publishActivity(session, behavior === "steer" ? "steering queued" : behavior === "followUp" ? "message queued" : "prompt accepted", "active");
         if (behavior === undefined)
-            this.events.publish(session.sessionId, { type: "message.append", message: userTextMessage(text) });
-        const promptPromise = session.prompt(text, behavior === undefined ? undefined : { streamingBehavior: behavior }).catch((error) => {
+            this.events.publish(session.sessionId, { type: "message.append", message: userMessage(text, images) });
+        const promptOptions = buildPromptOptions(behavior, images);
+        const promptPromise = session.prompt(text, promptOptions).catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
             this.publishActivity(session, "error", "error", message);
             this.events.publish(session.sessionId, { type: "session.error", message });
@@ -489,20 +267,25 @@ export class PiSessionService {
         void promptPromise;
         return promptPromise;
     }
-    enqueuePromptDuringCompaction(session, text, kind) {
+    enqueuePromptDuringCompaction(session, text, kind, images = []) {
         const queue = this.compactionPromptQueues.get(session.sessionId) ?? [];
-        queue.push({ kind, text });
+        queue.push({ kind, text, ...(images.length > 0 ? { images } : {}) });
         this.compactionPromptQueues.set(session.sessionId, queue);
         this.publishActivity(session, "message queued during compaction", "active");
         this.publishStatus(session);
     }
-    async shell(sessionId, text, managementContext) {
-        await this.assertWritable(sessionId);
-        this.assertManagedSessionAccess(sessionId, managementContext);
-        const effectiveContext = managementContext ?? this.managementContexts.get(sessionId);
-        if (effectiveContext !== undefined && !managementToolAllowed(effectiveContext, "shell"))
-            throw new Error("Shell commands are disabled in management embed mode");
-        const active = await this.getActive(sessionId);
+    async saveAttachments(ref, attachments, folder) {
+        const parsed = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false });
+        if (parsed.length === 0)
+            return [];
+        await this.assertWritable(ref);
+        const active = await this.getActive(ref);
+        return saveAttachmentsToWorkspace(active.runtime.cwd, parsed, folder === undefined ? {} : { folder });
+    }
+    async shell(ref, text, _managementContext) {
+        void _managementContext;
+        await this.assertWritable(ref);
+        const active = await this.getActive(ref);
         const { session } = active.runtime;
         const isExcluded = text.startsWith("!!");
         const command = (isExcluded ? text.slice(2) : text.slice(1)).trim();
@@ -535,40 +318,27 @@ export class PiSessionService {
             this.publishStatus(session);
         });
     }
-    async runCommand(sessionId, text, managementContext) {
-        await this.assertWritable(sessionId);
-        this.assertManagedSessionAccess(sessionId, managementContext);
-        return this.commandService.run(sessionId, text);
+    async runCommand(ref, text, _managementContext) {
+        void _managementContext;
+        await this.assertWritable(ref);
+        const active = await this.getActive(ref);
+        return this.commandService.run(active.runtime.session.sessionId, text);
     }
-    async respondToCommand(sessionId, requestId, value) {
-        await this.assertWritable(sessionId);
-        return this.commandService.respond(sessionId, requestId, value);
+    async respondToCommand(ref, requestId, value) {
+        await this.assertWritable(ref);
+        const active = await this.getActive(ref);
+        return this.commandService.respond(active.runtime.session.sessionId, requestId, value);
     }
-    async archive(sessionId) {
-        const session = await this.getOrOpen(sessionId);
+    async archive(ref) {
+        const session = await this.getOrOpen(ref);
         if (this.hasActiveWork(session))
             throw new Error("Stop current session activity before archiving");
         const archiveInput = await this.archiveInputForSession(session);
         await this.closeActive(session.sessionId);
-        this.managementContexts.delete(session.sessionId);
         await this.archiveStore.archive(archiveInput);
     }
-    assertManagedSessionAccess(sessionId, context) {
-        const existing = this.managementContexts.get(sessionId);
-        if (context === undefined || existing === undefined)
-            return;
-        if (existing.user.rootUserId !== context.user.rootUserId)
-            throw new Error("Session is outside the managed embed authorization scope");
-    }
-    rememberManagedSessionAccess(sessionId, context) {
-        if (context === undefined)
-            return;
-        this.assertManagedSessionAccess(sessionId, context);
-        if (!this.managementContexts.has(sessionId))
-            this.managementContexts.set(sessionId, context);
-    }
-    async archiveTree(sessionId) {
-        const session = await this.getOrOpen(sessionId);
+    async archiveTree(ref) {
+        const session = await this.getOrOpen(ref);
         const catalog = await this.workspaceArchiveCandidates(session.sessionManager.getCwd());
         const root = findArchiveCandidateByIdOrPrefix(catalog, session.sessionId) ?? archiveCandidateFromActiveSession(session, false);
         const plan = planSessionArchiveTree(root, catalog);
@@ -587,29 +357,56 @@ export class PiSessionService {
             skippedAlreadyArchivedCount: plan.skippedAlreadyArchivedCount,
         };
     }
-    async restore(sessionId) {
-        await this.closeActive(sessionId);
-        await this.archiveStore.restore(sessionId);
+    async restore(ref) {
+        const archived = await this.getArchived(ref);
+        if (archived === undefined)
+            throw new Error("Session not found");
+        await this.closeActive(archived.sessionId);
+        await this.archiveStore.restore(archived.sessionId);
+    }
+    async deleteArchived(ref) {
+        const record = await this.getArchived(ref);
+        if (record === undefined)
+            throw new Error("Archived session not found");
+        if (this.archiveStore.deleteArchived === undefined)
+            throw new Error("Archive store does not support deletion");
+        await this.closeActive(record.sessionId);
+        if (record.archivePath === undefined)
+            await this.ensureArchivedRecordMoved(record);
+        await this.archiveStore.deleteArchived(record.sessionId);
+    }
+    async reload(ref) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        if (this.hasActiveWork(session))
+            throw new Error("Stop current session activity before reloading");
+        await this.closeActive(session.sessionId);
+        const reopened = await this.getActive(ref);
+        this.publishStatus(reopened.runtime.session);
     }
-    async detachParent(sessionId) {
-        const session = await this.getOrOpen(sessionId);
+    async detachParent(ref) {
+        const session = await this.getOrOpen(ref);
         const sessionFile = session.sessionFile;
         if (sessionFile === undefined || sessionFile === "")
             throw new Error("Session is not persisted");
         await clearParentSession(sessionFile);
     }
-    async abort(sessionId) {
-        const active = this.active.get(sessionId);
-        if (!active)
+    async abort(ref) {
+        const active = this.activeForLookup(ref);
+        if (active === undefined)
             return;
+        const sessionId = active.runtime.session.sessionId;
         this.clearCompactionPromptQueue(sessionId);
         clearSessionQueue(active.runtime.session);
         await active.runtime.session.abort();
         this.publishActivity(active.runtime.session, "stopped", "idle");
         this.publishStatus(active.runtime.session);
     }
-    stop(sessionId) {
-        void this.closeActive(sessionId).catch(() => {
+    stop(ref) {
+        const active = this.activeForLookup(ref);
+        if (active === undefined)
+            return;
+        void this.closeActive(active.runtime.session.sessionId).catch(() => {
             // Best-effort shutdown; callers that need errors await closeActive directly.
         });
     }
@@ -632,6 +429,12 @@ export class PiSessionService {
             return record;
         }
     }
+    async ensureArchivedRecordMoved(record) {
+        const session = (await this.sessionManager.list(record.cwd)).find((candidate) => candidate.id === record.sessionId);
+        if (session === undefined)
+            return record;
+        return this.archiveStore.archive(archiveInputFromListEntry(session));
+    }
     async archiveInputForSession(session) {
         const cwd = session.sessionManager.getCwd();
         const sessionFile = session.sessionFile;
@@ -697,7 +500,6 @@ export class PiSessionService {
         if (!active)
             return;
         this.active.delete(sessionId);
-        this.managementContexts.delete(sessionId);
         this.activities.delete(sessionId);
         this.workspaceActivity?.removeSession(sessionId, active.runtime.session.sessionManager.getCwd());
         this.clearAuthLossWarningsForSession(sessionId);
@@ -711,67 +513,74 @@ export class PiSessionService {
             await active.runtime.dispose();
         }
     }
-    async assertWritable(sessionId) {
-        if (await this.archiveStore.isArchived(sessionId))
+    async assertWritable(ref) {
+        if (await this.getArchived(ref) !== undefined)
             throw new Error("Archived sessions are read-only. Restore the session to continue.");
     }
-    async getOrOpen(sessionId, managementContext) {
-        return (await this.getActive(sessionId, managementContext)).runtime.session;
+    async getOrOpen(ref) {
+        return (await this.getActive(ref)).runtime.session;
     }
-    async getActive(sessionId, managementContext) {
-        const active = this.active.get(sessionId);
-        if (active) {
-            const activeSessionId = active.runtime.session.sessionId;
-            const existingContext = this.managementContexts.get(activeSessionId);
-            if (managementContext !== undefined && existingContext === undefined) {
-                const sessionFile = active.runtime.session.sessionFile;
-                if (sessionFile === undefined || sessionFile === "")
-                    throw new Error("Managed embed session must be persisted before it can be resumed safely");
-                const activeCwd = active.runtime.session.sessionManager.getCwd();
-                await this.closeActive(activeSessionId);
-                return this.create(this.sessionManager.open(sessionFile), activeCwd, managementContext);
-            }
-            this.rememberManagedSessionAccess(active.runtime.session.sessionId, managementContext);
+    async getActive(ref) {
+        const active = this.activeForLookup(ref);
+        if (active !== undefined)
             return active;
-        }
-        const archived = await this.archiveStore.get(sessionId);
+        const archived = await this.getArchived(ref);
         if (archived?.archivePath !== undefined)
-            return this.create(this.sessionManager.open(archived.archivePath), archived.cwd, managementContext);
-        const match = (await this.sessionManager.listAll()).find((s) => s.id === sessionId || s.id.startsWith(sessionId));
+            return this.create(this.sessionManager.open(archived.archivePath), archived.cwd);
+        const match = isPiSessionRef(ref)
+            ? (await this.sessionManager.list(ref.cwd)).find((s) => s.id === ref.id || s.id.startsWith(ref.id))
+            : (await this.sessionManager.listAll?.() ?? []).find((s) => s.id === ref || s.id.startsWith(ref));
         if (!match)
             throw new Error("Session not found");
-        return this.create(this.sessionManager.open(match.path), match.cwd, managementContext);
-    }
-    async create(sessionManager, cwd, managementContext) {
-        const createRuntime = managementContext === undefined
-            ? this.createRuntime
-            : createManagementRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry, managementContext);
-        const runtimeOptions = managementContext === undefined
-            ? { cwd, agentDir: this.agentDir, sessionManager }
-            : { cwd, agentDir: this.agentDir, sessionManager, managementContext };
-        const runtime = await this.createAgentRuntime(createRuntime, runtimeOptions);
+        return this.create(this.sessionManager.open(match.path), match.cwd);
+    }
+    async getArchived(ref) {
+        const archived = await this.archiveStore.get(sessionIdFromLookup(ref));
+        if (archived === undefined)
+            return undefined;
+        if (isPiSessionRef(ref) && archived.cwd !== ref.cwd)
+            return undefined;
+        return archived;
+    }
+    activeForLookup(ref) {
+        const sessionId = sessionIdFromLookup(ref);
+        const exact = this.active.get(sessionId);
+        if (exact !== undefined && lookupMatchesActiveSession(ref, exact))
+            return exact;
+        for (const [candidateId, active] of this.active.entries()) {
+            if (candidateId.startsWith(sessionId) && lookupMatchesActiveSession(ref, active))
+                return active;
+        }
+        return undefined;
+    }
+    async create(sessionManager, cwd) {
+        const runtime = await this.createAgentRuntime(this.createRuntime, { cwd, agentDir: this.agentDir, sessionManager });
+        await this.bindSessionExtensions(runtime.session);
         const active = { runtime, unsubscribe: noop };
         this.bindRuntime(active);
-        runtime.setRebindSession(() => {
+        runtime.setRebindSession(async (session) => {
+            await this.bindSessionExtensions(session);
             this.bindRuntime(active);
-            return Promise.resolve();
         });
         this.active.set(runtime.session.sessionId, active);
-        this.rememberManagedSessionAccess(runtime.session.sessionId, managementContext);
         this.publishStatus(runtime.session);
         return active;
     }
+    async bindSessionExtensions(session) {
+        await session.bindExtensions({
+            onError: (error) => {
+                const message = `${error.extensionPath}: ${error.error}`;
+                this.publishActivity(session, "extension error", "error", message);
+                this.events.publish(session.sessionId, { type: "session.error", message });
+            },
+        });
+    }
     bindRuntime(active) {
         active.unsubscribe();
         const { session } = active.runtime;
         for (const [sessionId, candidate] of this.active.entries()) {
             if (candidate === active) {
                 this.active.delete(sessionId);
-                const context = this.managementContexts.get(sessionId);
-                if (context !== undefined && sessionId !== session.sessionId) {
-                    this.managementContexts.delete(sessionId);
-                    this.managementContexts.set(session.sessionId, context);
-                }
                 if (sessionId !== session.sessionId)
                     this.clearCompactionPromptQueue(sessionId);
             }
@@ -812,14 +621,14 @@ export class PiSessionService {
                 return;
             this.publishStatus(session);
             for (const prompt of queued)
-                void this.submitPrompt(session, prompt.text, prompt.kind);
+                void this.submitPrompt(session, prompt.text, prompt.kind, prompt.images);
             return;
         }
         const prompt = this.shiftCompactionPrompt(sessionId);
         if (prompt === undefined)
             return;
         this.publishStatus(session);
-        const submitted = this.submitPrompt(session, prompt.text, undefined);
+        const submitted = this.submitPrompt(session, prompt.text, undefined, prompt.images);
         void submitted.finally(() => { this.scheduleCompactionQueueDrain(sessionId); });
     }
     takeCompactionPromptQueue(sessionId) {
@@ -1195,9 +1004,6 @@ function archivedTimestamp(record) {
 function isDefined(value) {
     return value !== undefined;
 }
-function isNodeErrorWithCode(error, code) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === code;
-}
 async function clearParentSession(sessionFile) {
     const content = await readFile(sessionFile, "utf8");
     const newlineIndex = content.indexOf("\n");
@@ -1224,6 +1030,28 @@ function queuedMessagesFromSession(session, extraQueuedMessages = []) {
 function userTextMessage(text) {
     return { role: "user", content: text };
 }
+/**
+ * Build the optimistic user message echoed to clients. When images are present
+ * we mirror pi's content-array shape (`[{type:"text"}, {type:"image"}, ...]`) so
+ * the local echo matches what pi persists in the session branch.
+ */
+function userMessage(text, images) {
+    if (images.length === 0)
+        return userTextMessage(text);
+    const content = [];
+    if (text !== "")
+        content.push({ type: "text", text });
+    content.push(...images);
+    return { role: "user", content };
+}
+function buildPromptOptions(behavior, images) {
+    const options = {};
+    if (behavior !== undefined)
+        options.streamingBehavior = behavior;
+    if (images.length > 0)
+        options.images = images;
+    return Object.keys(options).length > 0 ? options : undefined;
+}
 function stringValue(value) {
     return typeof value === "string" ? value : "";
 }