@chainingintention/pi-web-cn 1.202606.11 → 1.202606.13

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,43 +7,37 @@ 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";
+import { createSpawnSessionToolDefinition } from "./spawnSessionTool.js";
+const noopLogger = { info() { } };
 function noop() {
     // Intentionally empty default unsubscribe callback.
 }
+function spawnTargetError(decision) {
+    if (decision.reason === "not-registered")
+        return new Error("派生会话不在已注册项目中");
+    return new Error(`cwd 必须是此项目的工作区。允许的路径：${decision.allowedCwds.join(", ")}`);
+}
 function authLossWarningKey(sessionId, provider, modelId) {
     return `${sessionId}:${provider}/${modelId}`;
 }
-const SUPPORTED_PROMPT_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
-const MAX_PROMPT_IMAGES = 4;
+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");
+        throw new Error("提示文本为必填项");
     return value;
 }
-function requirePromptImages(value) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value))
-        throw new Error("Prompt images must be an array");
-    if (value.length > MAX_PROMPT_IMAGES)
-        throw new Error(`Prompt images are limited to ${String(MAX_PROMPT_IMAGES)}`);
-    return value.map((image) => {
-        if (!isRecord(image))
-            throw new Error("Prompt image must be an object");
-        if (image["type"] !== "image")
-            throw new Error('Prompt image type must be "image"');
-        const data = image["data"];
-        const mimeType = image["mimeType"];
-        if (typeof data !== "string" || data === "")
-            throw new Error("Prompt image data is required");
-        if (typeof mimeType !== "string" || !SUPPORTED_PROMPT_IMAGE_MIME_TYPES.has(mimeType))
-            throw new Error(`Unsupported prompt image MIME type: ${String(mimeType)}`);
-        return { type: "image", data, mimeType };
-    });
-}
 function parsePromptStreamingBehavior(value) {
     if (value === undefined)
         return undefined;
@@ -60,49 +50,22 @@ function defaultCreateAgentRuntime(createRuntime, options) {
         throw new Error("Default runtime creation requires an SDK SessionManager");
     return createAgentSessionRuntime(createRuntime, { ...options, sessionManager: options.sessionManager });
 }
-function createDefaultRuntimeFactory(authStorage, modelRegistry) {
+function createDefaultRuntimeFactory(authStorage, modelRegistry, spawn) {
     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),
+            ...(spawn === undefined ? [] : [createSpawnSessionToolDefinition(cwd, { spawn })]),
+        ];
+        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,
@@ -122,211 +85,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;
@@ -335,16 +93,17 @@ 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.spawnTargets = deps.spawnTargets;
+        this.logger = deps.logger ?? noopLogger;
+        this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input));
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
         this.workspaceActivity = deps.workspaceActivity;
         this.heartbeat = setInterval(() => { this.publishHeartbeats(); }, deps.heartbeatIntervalMs ?? 2000);
-        this.commandService = new SessionCommandService((sessionId) => this.getActive(sessionId), (sessionId, text) => this.prompt(sessionId, text), events, {
+        this.commandService = new SessionCommandService((sessionId) => this.getActive(sessionId), (sessionId, text) => this.prompt(sessionId, text, undefined, undefined, { echoUserMessage: false }), events, {
             onCompactionStart: (session) => {
                 this.publishActivity(session, "compacting", "active");
                 this.publishStatus(session);
@@ -366,7 +125,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());
@@ -389,12 +147,11 @@ 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 {
+        const created = {
             id: session.sessionId,
             path: session.sessionFile ?? "",
             cwd,
@@ -403,25 +160,45 @@ export class PiSessionService {
             messageCount: session.messages.length,
             firstMessage: "",
         };
-    }
-    async messages(sessionId, page) {
-        const session = await this.getOrOpen(sessionId);
+        // Broadcast so other clients (and the spawning agent's UI) can add the new
+        // session to their list without a manual reload.
+        this.events.publishGlobal({ type: "session.created", session: created });
+        return created;
+    }
+    /**
+     * Start a new session on behalf of a LLM and deliver an initial prompt to it.
+     * The target cwd is constrained to a workspace of the same registered project
+     * as the spawning session so the new session is visible in the web UI.
+     */
+    async spawnSession(input) {
+        if (this.spawnTargets === undefined)
+            throw new Error("派生会话已禁用");
+        const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
+        if (!decision.allowed)
+            throw spawnTargetError(decision);
+        const created = await this.start(decision.cwd);
+        await this.prompt(created.id, input.prompt);
+        this.logger.info({ spawningCwd: input.spawningCwd, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length }, "spawn_session started a new session");
+        return { sessionId: created.id, cwd: decision.cwd };
+    }
+    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)
@@ -429,46 +206,52 @@ export class PiSessionService {
         const model = candidates.find((candidate) => candidate.provider === provider && candidate.id === modelId)
             ?? session.modelRegistry.find(provider, modelId);
         if (model === undefined)
-            throw new Error(`Model not found: ${provider}/${modelId}`);
+            throw new Error(`未找到模型：${provider}/${modelId}`);
         await session.setModel(model);
         this.publishActivity(session, `model: ${model.id}`, "idle", model.provider);
         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");
+            throw new Error(session.scopedModels.length > 0 ? "作用域内只有一个模型" : "只有一个可用模型");
         this.publishActivity(session, `model: ${result.model.id}`, "idle", result.model.provider);
         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(`无效的思考级别：${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");
+            throw new Error("当前模型不支持思考");
         this.publishActivity(session, `thinking: ${level}`, "idle");
         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" });
@@ -481,33 +264,40 @@ export class PiSessionService {
         }
         return commands.sort((a, b) => a.name.localeCompare(b.name));
     }
-    async prompt(sessionId, text, streamingBehavior, imagesValue, managementContext) {
+    async prompt(ref, text, streamingBehavior, attachments, options) {
+        const _managementContext = options?.managementContext;
+        void _managementContext;
         const promptText = requirePromptText(text);
+        // Command-forwarded prompts (e.g. /skill:*) are expanded by the agent, which
+        // streams the canonical message back. The client doesn't render the raw
+        // command text, so the server must not echo it either, or it would show up
+        // as a transient line that vanishes on reload.
+        const echoUserMessage = options?.echoUserMessage !== false;
         const requestedBehavior = parsePromptStreamingBehavior(streamingBehavior);
-        const images = requirePromptImages(imagesValue);
-        await this.assertWritable(sessionId);
-        const session = await this.getOrOpen(sessionId, managementContext);
-        if (images.length > 0 && !modelSupportsImageInput(session.model))
-            throw new Error("当前模型不支持图片输入");
+        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", images);
+            this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp", images, echoUserMessage);
             return;
         }
-        void this.submitPrompt(session, promptText, behavior, images);
+        void this.submitPrompt(session, promptText, behavior, images, echoUserMessage);
     }
-    submitPrompt(session, text, behavior, images = []) {
+    submitPrompt(session, text, behavior, images = [], echoUserMessage = true) {
         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: userPromptMessage(text, images) });
-        const promptPromise = session.prompt(text, promptOptions(behavior, images)).catch((error) => {
+        if (behavior === undefined && echoUserMessage)
+            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 });
@@ -515,27 +305,32 @@ export class PiSessionService {
         void promptPromise;
         return promptPromise;
     }
-    enqueuePromptDuringCompaction(session, text, kind, images = []) {
+    enqueuePromptDuringCompaction(session, text, kind, images = [], echoUserMessage = true) {
         const queue = this.compactionPromptQueues.get(session.sessionId) ?? [];
-        queue.push({ kind, text, ...(images.length === 0 ? {} : { images: [...images] }) });
+        queue.push({ kind, text, ...(images.length > 0 ? { images } : {}), ...(echoUserMessage ? {} : { echoUserMessage: false }) });
         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();
         if (!command)
-            throw new Error("Usage: !<shell command>");
+            throw new Error("用法：!<shell command>");
         if (session.isBashRunning)
-            throw new Error("A bash command is already running");
+            throw new Error("已有 bash 命令正在运行");
         this.publishActivity(session, "running bash", "active", command);
         this.events.publish(session.sessionId, { type: "shell.start", command, excludeFromContext: isExcluded });
         void session.executeBash(command, (chunk) => {
@@ -561,46 +356,33 @@ 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");
+            throw new Error("归档前请先停止当前会话活动");
         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);
         const busy = plan.targets.map((target) => target.activeSession).find((target) => target !== undefined && this.hasActiveWork(target));
         if (busy !== undefined)
-            throw new Error(`Stop current session activity before archiving ${sessionDisplayName(busy)}`);
+            throw new Error(`归档 ${sessionDisplayName(busy)} 前请先停止当前会话活动`);
         const archiveInputs = plan.unarchivedTargets.map((target) => archiveInputFromCandidate(target));
         for (const input of archiveInputs)
             await this.closeActive(input.sessionId);
@@ -613,29 +395,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("未找到会话");
+        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("未找到已归档会话");
+        if (this.archiveStore.deleteArchived === undefined)
+            throw new Error("归档存储不支持删除");
+        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("重新加载前请先停止当前会话活动");
+        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");
+            throw new Error("会话尚未持久化");
         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.
         });
     }
@@ -658,11 +467,17 @@ 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;
         if (sessionFile === undefined || sessionFile === "")
-            throw new Error("Session is not persisted");
+            throw new Error("会话尚未持久化");
         const listed = (await this.sessionManager.list(cwd)).find((candidate) => candidate.id === session.sessionId);
         if (listed !== undefined)
             return archiveInputFromListEntry(listed);
@@ -723,7 +538,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);
@@ -737,67 +551,74 @@ export class PiSessionService {
             await active.runtime.dispose();
         }
     }
-    async assertWritable(sessionId) {
-        if (await this.archiveStore.isArchived(sessionId))
-            throw new Error("Archived sessions are read-only. Restore the session to continue.");
+    async assertWritable(ref) {
+        if (await this.getArchived(ref) !== undefined)
+            throw new Error("已归档会话为只读。请恢复会话后继续。");
     }
-    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);
+            throw new Error("未找到会话");
+        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);
             }
@@ -838,14 +659,14 @@ export class PiSessionService {
                 return;
             this.publishStatus(session);
             for (const prompt of queued)
-                void this.submitPrompt(session, prompt.text, prompt.kind, prompt.images ?? []);
+                void this.submitPrompt(session, prompt.text, prompt.kind, prompt.images, prompt.echoUserMessage ?? true);
             return;
         }
         const prompt = this.shiftCompactionPrompt(sessionId);
         if (prompt === undefined)
             return;
         this.publishStatus(session);
-        const submitted = this.submitPrompt(session, prompt.text, undefined, prompt.images ?? []);
+        const submitted = this.submitPrompt(session, prompt.text, undefined, prompt.images, prompt.echoUserMessage ?? true);
         void submitted.finally(() => { this.scheduleCompactionQueueDrain(sessionId); });
     }
     takeCompactionPromptQueue(sessionId) {
@@ -1080,25 +901,14 @@ function modelToClientModel(model) {
         return {};
     const name = getString(model, "name");
     const reasoning = getProperty(model, "reasoning");
-    const input = modelInput(model);
     return {
         provider: model.provider,
         id: model.id,
         ...(name === undefined ? {} : { name }),
         contextWindow: model.contextWindow,
         ...(reasoning === undefined ? {} : { reasoning }),
-        ...(input === undefined ? {} : { input }),
     };
 }
-function modelInput(model) {
-    const input = getProperty(model, "input");
-    if (!Array.isArray(input))
-        return undefined;
-    return input.filter((item) => item === "text" || item === "image");
-}
-function modelSupportsImageInput(model) {
-    return modelInput(model)?.includes("image") === true;
-}
 function clientSessionFromListEntry(session) {
     return {
         id: session.id,
@@ -1128,7 +938,7 @@ function archiveInputFromListEntry(session) {
 function archiveInputFromActiveSession(session) {
     const sessionFile = session.sessionFile;
     if (sessionFile === undefined || sessionFile === "")
-        throw new Error("Session is not persisted");
+        throw new Error("会话尚未持久化");
     const parentSessionPath = session.sessionManager.getHeader?.()?.parentSession;
     return {
         sessionId: session.sessionId,
@@ -1169,7 +979,7 @@ function archiveCandidateFromArchivedRecord(record, fallback) {
 function archiveCandidateFromActiveSession(session, archived) {
     const sessionFile = session.sessionFile;
     if (sessionFile === undefined || sessionFile === "")
-        throw new Error("Session is not persisted");
+        throw new Error("会话尚未持久化");
     const parentSessionPath = session.sessionManager.getHeader?.()?.parentSession;
     return {
         id: session.sessionId,
@@ -1232,9 +1042,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");
@@ -1255,22 +1062,33 @@ function queuedMessagesFromSession(session, extraQueuedMessages = []) {
     return [
         ...session.getSteeringMessages().map((text) => ({ kind: "steer", text })),
         ...session.getFollowUpMessages().map((text) => ({ kind: "followUp", text })),
-        ...extraQueuedMessages.map((message) => queuedPromptSummary(message)),
+        ...extraQueuedMessages,
     ];
 }
-function queuedPromptSummary(message) {
-    const imageCount = message.images?.length ?? 0;
-    return { kind: message.kind, text: message.text, ...(imageCount === 0 ? {} : { imageCount }) };
+function userTextMessage(text) {
+    return { role: "user", content: text };
 }
-function promptOptions(behavior, images) {
-    if (behavior === undefined && images.length === 0)
-        return undefined;
-    return { ...(behavior === undefined ? {} : { streamingBehavior: behavior }), ...(images.length === 0 ? {} : { images: [...images] }) };
-}
-function userPromptMessage(text, images) {
+/**
+ * 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 { role: "user", content: text };
-    return { role: "user", content: [{ type: "text", text }, ...images] };
+        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 : "";