oh-my-agent-web 0.4.0 → 0.6.0

package/dist/server/engine/pi-plugins.js

@@ -0,0 +1,310 @@
+/**
+ * 插件（pi package / 本机扩展）的读取与操作。
+ *
+ * 「插件」在 pi 里就是 **package**：`settings.json` 的 `packages`（npm / git / 本地目录），
+ * 一个包可以同时带扩展、技能、提示词模板、主题；另外还有散装放在
+ * `~/.pi/agent/extensions/`（或项目 `.pi/extensions/`）里的单文件扩展。
+ *
+ * 与参考实现 `/data/git/pi-web`（`app/api/plugins/route.ts`）对齐的几条：
+ *   - **谁说了算：pi 自己**。哪些资源、开没开，全部取自 `DefaultPackageManager.resolve()`；
+ *     `onMissing` 一律回 `skip` —— 查询时绝不顺手跑 npm install。
+ *   - **两个作用域**：全局（`~/.pi/agent/settings.json`）+ 项目（`<workspace>/.pi/settings.json`），
+ *     跟会话加载时用的 cwd 是同一个，所以面板显示的就是这个项目里真正加载的东西。
+ *     OMAW 没有「项目信任」的交互（ADR 未引入），与 SDK 的默认值一致：项目资源按已信任处理。
+ *   - **停用 ≠ 卸载**：写 `autoload: false`（pi 文档：先清空、再按 patterns 加回），
+ *     不删文件、不动 npm 目录、**不丢用户手写的资源过滤**；开回来只删这一个键。
+ *     `pi config` 那种「四类数组都置空」的停用也认，一并显示成已停用。
+ *   - **状态四态**：loaded（有资源真的加载了）/ installed（装了但没加载出资源）/
+ *     missing（配置里有、本地没装）/ disabled（已停用）。
+ */
+import { readFile } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, sep } from "node:path";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+export const RESOURCE_KEYS = ["extensions", "skills", "prompts", "themes"];
+const EMPTY_COUNTS = { extensions: 0, skills: 0, prompts: 0, themes: 0 };
+const KIND_OF = {
+    extensions: "extension",
+    skills: "skill",
+    prompts: "prompt",
+    themes: "theme",
+};
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function scopeOf(scope) {
+    return scope === "project" ? "project" : "global";
+}
+function sourceOf(entry) {
+    return typeof entry === "string" ? entry : entry.source;
+}
+/** `pi config` 的停用写法：四类资源数组全部置空 */
+function isEmptiedEntry(entry) {
+    if (typeof entry === "string")
+        return false;
+    return RESOURCE_KEYS.every((key) => Array.isArray(entry[key]) && entry[key].length === 0);
+}
+function isDisabledEntry(entry) {
+    if (typeof entry === "string")
+        return false;
+    return entry.autoload === false || isEmptiedEntry(entry);
+}
+/** 源里钉住的版本：`npm:@scope/pkg@1.2.3` → `1.2.3`；git 的 `#v1` / `@v1` 同理 */
+function configuredVersionOf(source) {
+    if (source.startsWith("npm:")) {
+        const spec = source.slice(4).trim();
+        const lastAt = spec.lastIndexOf("@");
+        const nameEnd = spec.startsWith("@") ? spec.indexOf("/", 1) : 0;
+        return lastAt > nameEnd ? spec.slice(lastAt + 1) || undefined : undefined;
+    }
+    if (source.startsWith("git:") || /^[a-z]+:\/\//i.test(source)) {
+        const lastAt = Math.max(source.lastIndexOf("@"), source.lastIndexOf("#"));
+        const lastSlash = source.lastIndexOf("/");
+        return lastAt > lastSlash ? source.slice(lastAt + 1) || undefined : undefined;
+    }
+    return undefined;
+}
+async function readPackageMetadata(root) {
+    if (!root)
+        return {};
+    try {
+        const raw = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        if (typeof raw !== "object" || raw === null)
+            return {};
+        const record = raw;
+        return {
+            name: typeof record.name === "string" ? record.name : undefined,
+            version: typeof record.version === "string" ? record.version : undefined,
+            description: typeof record.description === "string" ? record.description : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function resourceName(path, kind) {
+    const file = basename(path);
+    const ext = extname(file);
+    if (kind === "skill" && file.toLowerCase() === "skill.md")
+        return basename(dirname(path));
+    if (kind === "extension" && /^index\.[cm]?[jt]s$/.test(file))
+        return basename(dirname(path));
+    return ext ? file.slice(0, -ext.length) : file;
+}
+function resourceRelativePath(resource) {
+    const base = resource.metadata.baseDir;
+    if (!base)
+        return resource.path;
+    const rel = relative(base, resource.path);
+    return rel !== "" && !rel.startsWith("..") ? rel.split(sep).join("/") : resource.path;
+}
+function toResourceInfo(resource, key) {
+    const kind = KIND_OF[key];
+    return {
+        kind,
+        name: resourceName(resource.path, kind),
+        path: resource.path,
+        relativePath: resourceRelativePath(resource),
+    };
+}
+/** 插件面板的 key：scope + source（同一个包可能在两个作用域各配一份） */
+export function pluginKey(source, scope) {
+    return `${scope}\0${source}`;
+}
+export function createPluginStore(options) {
+    const agentDir = options.agentDir;
+    /** 安装 / 卸载 / 更新会跑 npm，串起来做，别让两个 npm 抢同一个目录 */
+    let queue = Promise.resolve();
+    const serialize = (task) => {
+        const run = queue.then(task, task);
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    function open(workspace) {
+        // 与 SDK 会话同一个 cwd + 默认信任：面板看到的就是这个项目里真正加载的
+        const settings = SettingsManager.create(workspace, agentDir);
+        const manager = new DefaultPackageManager({ cwd: workspace, agentDir, settingsManager: settings });
+        return { settings, manager };
+    }
+    async function readView(workspace) {
+        let opened;
+        try {
+            opened = open(workspace);
+        }
+        catch (error) {
+            return {
+                packages: [],
+                extensions: [],
+                totals: { ...EMPTY_COUNTS },
+                diagnostics: [],
+                projectLoaded: false,
+                error: `读不到 pi 的设置：${describe(error)}`,
+            };
+        }
+        const { settings, manager } = opened;
+        const diagnostics = [];
+        const loadError = settings.drainErrors()[0];
+        if (loadError) {
+            diagnostics.push({
+                type: "error",
+                message: `${loadError.path ?? loadError.scope}：${describe(loadError.error)}`,
+            });
+        }
+        const countsByPackage = new Map();
+        const resourcesByPackage = new Map();
+        const totals = { ...EMPTY_COUNTS };
+        const extensions = [];
+        let resolved;
+        try {
+            resolved = await manager.resolve(async (source) => {
+                diagnostics.push({ type: "warning", source, message: "配置了这个插件包，但本地还没装" });
+                return "skip";
+            });
+        }
+        catch (error) {
+            diagnostics.push({ type: "error", message: `读取已装插件失败：${describe(error)}` });
+            resolved = { extensions: [], skills: [], prompts: [], themes: [] };
+        }
+        for (const key of RESOURCE_KEYS) {
+            for (const resource of resolved[key]) {
+                if (resource.metadata.origin === "top-level") {
+                    if (key !== "extensions")
+                        continue; // 散装技能/模板/主题归各自的 panel
+                    extensions.push({
+                        path: resource.path,
+                        name: resourceName(resource.path, "extension"),
+                        scope: scopeOf(resource.metadata.scope),
+                        enabled: resource.enabled,
+                    });
+                    if (resource.enabled)
+                        totals.extensions += 1;
+                    continue;
+                }
+                if (!resource.enabled)
+                    continue;
+                const scope = scopeOf(resource.metadata.scope);
+                const id = pluginKey(resource.metadata.source, scope);
+                const counts = countsByPackage.get(id) ?? { ...EMPTY_COUNTS };
+                counts[key] += 1;
+                totals[key] += 1;
+                countsByPackage.set(id, counts);
+                const list = resourcesByPackage.get(id) ?? [];
+                list.push(toResourceInfo(resource, key));
+                resourcesByPackage.set(id, list);
+            }
+        }
+        const disabled = new Map();
+        const filtered = new Map();
+        for (const scope of ["global", "project"]) {
+            const entries = scope === "global" ? settings.getGlobalSettings().packages : settings.getProjectSettings().packages;
+            for (const entry of entries ?? []) {
+                const id = pluginKey(sourceOf(entry), scope);
+                disabled.set(id, isDisabledEntry(entry));
+                filtered.set(id, typeof entry === "object" && !isEmptiedEntry(entry));
+            }
+        }
+        const packages = [];
+        for (const configured of manager.listConfiguredPackages()) {
+            const scope = scopeOf(configured.scope);
+            const id = pluginKey(configured.source, scope);
+            const counts = countsByPackage.get(id) ?? { ...EMPTY_COUNTS };
+            const metadata = await readPackageMetadata(configured.installedPath);
+            const isDisabled = disabled.get(id) ?? false;
+            const loaded = counts.extensions + counts.skills + counts.prompts + counts.themes;
+            packages.push({
+                source: configured.source,
+                scope,
+                name: metadata.name,
+                version: metadata.version,
+                description: metadata.description,
+                configuredVersion: configuredVersionOf(configured.source),
+                disabled: isDisabled,
+                filtered: filtered.get(id) ?? false,
+                installedPath: configured.installedPath,
+                status: isDisabled ? "disabled" : loaded > 0 ? "loaded" : configured.installedPath ? "installed" : "missing",
+                counts,
+                resources: resourcesByPackage.get(id) ?? [],
+            });
+        }
+        const projectLoaded = settings.isProjectTrusted();
+        return { packages, extensions, totals, diagnostics, projectLoaded };
+    }
+    /** 改一条 package 的启停；只动目标条目，其它条目与管理器里的其它键原样保留 */
+    function setDisabled(settings, source, scope, wanted) {
+        const current = scope === "global" ? [...(settings.getGlobalSettings().packages ?? [])] : [...(settings.getProjectSettings().packages ?? [])];
+        const index = current.findIndex((entry) => sourceOf(entry) === source);
+        if (index === -1)
+            return false;
+        const entry = current[index];
+        if (isDisabledEntry(entry) === wanted)
+            return false;
+        let next;
+        if (wanted) {
+            // 停用：autoload:false = 「先清空，再按 patterns 加回」。保留用户手写的过滤规则，
+            // 否则「停一下再开」会把过滤弄丢（参考实现在这点上会丢，这里刻意不跟）。
+            next = { ...(typeof entry === "string" ? { source: entry } : entry), autoload: false };
+        }
+        else if (typeof entry === "string") {
+            next = entry;
+        }
+        else {
+            const restored = { ...entry };
+            delete restored.autoload;
+            // `pi config` 那种「四类数组全空」的停用：开回来就把空数组删掉
+            if (isEmptiedEntry(entry))
+                for (const key of RESOURCE_KEYS)
+                    delete restored[key];
+            next = RESOURCE_KEYS.some((key) => restored[key] !== undefined) ? restored : restored.source;
+        }
+        current[index] = next;
+        if (scope === "global")
+            settings.setPackages(current);
+        else
+            settings.setProjectPackages(current);
+        return true;
+    }
+    async function act(input) {
+        const scope = input.scope ?? "global";
+        const source = input.source?.trim() ?? "";
+        let actionError;
+        let notice;
+        if (input.action !== "update" && source === "") {
+            return { ...(await readView(input.workspace)), actionError: "没有指定插件包" };
+        }
+        try {
+            if (input.action === "install" || input.action === "remove" || input.action === "update") {
+                await serialize(async () => {
+                    const { manager } = open(input.workspace);
+                    if (input.action === "install") {
+                        await manager.installAndPersist(source, { local: scope === "project" });
+                        notice = "装好了（对新会话生效）";
+                    }
+                    else if (input.action === "remove") {
+                        await manager.removeAndPersist(source, { local: scope === "project" });
+                        notice = "已卸载";
+                    }
+                    else {
+                        await manager.update(source === "" ? undefined : source);
+                        notice = "已更新（对新会话生效）";
+                    }
+                });
+            }
+            else {
+                const { settings } = open(input.workspace);
+                const changed = setDisabled(settings, source, scope, input.action === "disable");
+                await settings.flush();
+                const writeError = settings.drainErrors()[0];
+                if (writeError)
+                    throw new Error(describe(writeError.error));
+                if (!changed)
+                    actionError = "这个插件包已经不在配置里了（刷新一下再看）";
+                else
+                    notice = input.action === "disable" ? "已停用（对新会话生效）" : "已启用（对新会话生效）";
+            }
+        }
+        catch (error) {
+            actionError = describe(error);
+        }
+        return { ...(await readView(input.workspace)), actionError, notice };
+    }
+    return { view: readView, act };
+}

package/dist/server/engine/pi-sdk.js

@@ -9,15 +9,72 @@
 import { DefaultResourceLoader, SessionManager, createAgentSession, getAgentDir, } from "@earendil-works/pi-coding-agent";
 import { classifyScope } from "../approval/scope.js";
 import { mapSessionEvent } from "./pi-events.js";
+import { createPiSubagents } from "./pi-subagents.js";
+import { makeSubagentToolExtension } from "./pi-subagent-tool.js";
+import { enabledSubagentSpecs, readSubagentSettings } from "../subagents/profile-store.js";
 import { readSessionModel } from "./pi-session-model.js";
 import { entriesToUiMessages } from "./pi-transcript.js";
 function asRecord(value) {
     return typeof value === "object" && value !== null ? value : {};
 }
+/**
+ * provider 的显示名：只覆盖 SDK 名字太长/不直观的两个（和 pi-web 的选择一致），
+ * 其余直接用引擎给的 OAuth 名称（`Anthropic (Claude Pro/Max)`、`xAI (Grok/X subscription)` 等）。
+ */
+const OAUTH_LABELS = {
+    "openai-codex": "ChatGPT Plus/Pro",
+    "github-copilot": "GitHub Copilot",
+};
+/** SDK 的 AuthPrompt → 端口的 ProviderAuthPrompt */
+function toAuthPrompt(prompt) {
+    const record = asRecord(prompt);
+    const type = record.type;
+    const options = Array.isArray(record.options)
+        ? record.options.map((option) => {
+            const item = asRecord(option);
+            return {
+                id: String(item.id ?? ""),
+                label: String(item.label ?? item.id ?? ""),
+                ...(typeof item.description === "string" ? { description: item.description } : {}),
+            };
+        })
+        : undefined;
+    return {
+        type: type === "select" || type === "secret" || type === "manual_code" || type === "text" ? type : "text",
+        message: String(record.message ?? ""),
+        ...(typeof record.placeholder === "string" ? { placeholder: record.placeholder } : {}),
+        ...(options ? { options } : {}),
+    };
+}
+/** SDK 的 AuthEvent → 端口的 ProviderAuthEvent（未知事件当 info，不静默丢） */
+function toAuthEvent(event) {
+    const record = asRecord(event);
+    if (record.type === "auth_url" && typeof record.url === "string") {
+        return {
+            type: "auth_url",
+            url: record.url,
+            ...(typeof record.instructions === "string" ? { instructions: record.instructions } : {}),
+        };
+    }
+    if (record.type === "device_code" && typeof record.userCode === "string") {
+        return {
+            type: "device_code",
+            userCode: record.userCode,
+            verificationUri: String(record.verificationUri ?? ""),
+            ...(typeof record.intervalSeconds === "number" ? { intervalSeconds: record.intervalSeconds } : {}),
+            ...(typeof record.expiresInSeconds === "number" ? { expiresInSeconds: record.expiresInSeconds } : {}),
+        };
+    }
+    if (record.type === "progress")
+        return { type: "progress", message: String(record.message ?? "") };
+    return { type: "info", message: String(record.message ?? "") };
+}
 /** 教模型怎么写「下一步建议」（ADR-0022）：刻意写得短（每次请求都付 token） */
 import { reloadModelRegistry } from "./model-registry-reload.js";
+import { NARRATE_GUIDANCE } from "./narrate-guidance.js";
 import { SUGGESTION_GUIDANCE } from "./suggestion-guidance.js";
-export { SUGGESTION_GUIDANCE };
+import { SUBAGENT_GUIDANCE } from "./subagent-guidance.js";
+export { NARRATE_GUIDANCE, SUGGESTION_GUIDANCE, SUBAGENT_GUIDANCE };
 import { createPiThinking } from "./pi-thinking.js";
 import { piSdkVersion } from "./pi-version.js";
 import { renameSessionIn } from "./pi-rename.js";
@@ -26,6 +83,17 @@ export function createPiSdkEngine(options = {}) {
     const thinking = createPiThinking(sessions);
     let approvalHandler = null;
     const notice = (text, level = "warn") => options.onNotice?.(text, level);
+    // 子代理运行时（ADR：多开 + 面板管理）：会话文件放在父会话旁边，工具白名单来自模板
+    const resolvedAgentDir = options.agentDir ?? getAgentDir();
+    const subagentSettings = readSubagentSettings(resolvedAgentDir);
+    const subagents = createPiSubagents({
+        agentDir: resolvedAgentDir,
+        sessionDir: options.sessionDir,
+        concurrency: subagentSettings.concurrency,
+        onNotice: (text, level) => notice(text, level ?? "warn"),
+        // 子代理沿用父会话的模型运行时 / 当前模型（不然扩展提供的 provider 在子会话里不存在）
+        getParentSession: (conversationId) => sessions.get(conversationId)?.session ?? null,
+    });
     /** 审批用的 inline 扩展：拦在工具真正执行之前（SDK 的公开拦截点） */
     function makeApprovalExtension(workspace) {
         return {
@@ -61,12 +129,34 @@ export function createPiSdkEngine(options = {}) {
     /** 建 resourceLoader 并拉起一个 AgentSession（createSession 与 openSession 共用） */
     async function startSession(sessionId, workspace, sessionManager, sessionPath = null) {
         const agentDir = options.agentDir ?? getAgentDir();
+        // 子会话要按父会话归档：会话文件名在 createAgentSession 之后才确定，所以用一个懒引用
+        const parentSessionPath = () => sessionManager.getSessionFile() ?? sessionPath;
+        const extensionFactories = [makeApprovalExtension(workspace)];
+        // 子代理开着、且有可用模板时，才把「什么时候派活」这段拼进系统提示
+        const subagentReady = sessionId !== PREWARM_ID
+            && readSubagentSettings(agentDir).enabled
+            && enabledSubagentSpecs(agentDir).length > 0;
+        // 预热会话不暴露 Agent 工具：它不下发提示词，给它一个委派入口只会误伤
+        if (sessionId !== PREWARM_ID) {
+            extensionFactories.push(makeSubagentToolExtension({
+                port: subagents,
+                agentDir,
+                conversationId: sessionId,
+                workspace,
+                parentSessionPath,
+            }));
+        }
         const resourceLoader = new DefaultResourceLoader({
             cwd: workspace,
             agentDir,
-            extensionFactories: [makeApprovalExtension(workspace)],
+            extensionFactories,
             // 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具
-            appendSystemPrompt: [SUGGESTION_GUIDANCE],
+            // 「动手前先说话」：过程默认折叠，不写正文用户就不知道它在干什么
+            appendSystemPrompt: [
+                SUGGESTION_GUIDANCE,
+                NARRATE_GUIDANCE,
+                ...(subagentReady ? [SUBAGENT_GUIDANCE] : []),
+            ],
         });
         await resourceLoader.reload();
         const { session } = await createAgentSession({
@@ -104,6 +194,49 @@ export function createPiSdkEngine(options = {}) {
             options.onNotice?.(`模型表预热失败：${error instanceof Error ? error.message : String(error)}`, "warn");
         }
     }
+    /**
+     * 订阅服务要一个 ModelRuntime：优先用预热会话的那个（内存会话，不落盘），
+     * 没有就建一个 —— 不带任何会话也让用户先登录。
+     */
+    async function authRuntime() {
+        const runtimeOf = (handle) => {
+            if (!handle)
+                return null;
+            return handle.session.modelRuntime ?? null;
+        };
+        const existing = runtimeOf(sessions.get(PREWARM_ID) ?? [...sessions.values()].at(-1));
+        if (existing)
+            return existing;
+        await warmUp();
+        return runtimeOf(sessions.get(PREWARM_ID));
+    }
+    /** 接口给界面的一行：能 OAuth 登录的 provider + 当前连上了没 */
+    async function listProviderAuth() {
+        const runtime = await authRuntime();
+        if (!runtime)
+            return [];
+        const credentials = new Map();
+        try {
+            for (const credential of await runtime.listCredentials()) {
+                credentials.set(credential.providerId, credential.type);
+            }
+        }
+        catch {
+            // auth.json 坏了不该让整个列表空掉：退回「都算未连接」
+        }
+        return runtime
+            .getProviders()
+            .filter((provider) => Boolean(provider.auth.oauth))
+            .map((provider) => ({
+            id: provider.id,
+            name: OAUTH_LABELS[provider.id] ?? provider.auth.oauth?.name ?? provider.name,
+            subscription: provider.auth.oauth?.isSubscription === true,
+            connected: credentials.get(provider.id) === "oauth",
+            supportsApiKey: Boolean(provider.auth.apiKey),
+            modelCount: runtime.getModels(provider.id).length,
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id));
+    }
     return {
         /** 预热：pi 的 modelRuntime 挂在会话上，没会话就列不出模型（内存会话，不落盘） */
         async prewarm() {
@@ -118,6 +251,33 @@ export function createPiSdkEngine(options = {}) {
         },
         version: piSdkVersion,
         reloadModels: () => reloadModelRegistry(sessions, PREWARM_ID, warmUp, options.agentDir ?? getAgentDir()),
+        /** 子代理：起子会话 / 停掉它 / 状态订阅（宿主投影进快照） */
+        subagents,
+        providerAuth: {
+            list: () => listProviderAuth(),
+            async login(providerId, interaction) {
+                const runtime = await authRuntime();
+                if (!runtime)
+                    throw new Error("引擎还没拿到模型运行时（先开一次会话，或稍后重试）");
+                if (!runtime.getProviders().find((provider) => provider.id === providerId)?.auth.oauth) {
+                    throw new Error(`${providerId} 不支持订阅登录`);
+                }
+                await runtime.login(providerId, "oauth", {
+                    prompt: (prompt) => interaction.prompt(toAuthPrompt(prompt)),
+                    notify: (event) => interaction.notify(toAuthEvent(event)),
+                    ...(interaction.signal ? { signal: interaction.signal } : {}),
+                });
+                // 凭据已写进引擎的 auth.json：重载模型表，不然新 provider 的模型要等下次重启才出现
+                await reloadModelRegistry(sessions, PREWARM_ID, warmUp, options.agentDir ?? getAgentDir());
+            },
+            async logout(providerId) {
+                const runtime = await authRuntime();
+                if (!runtime)
+                    throw new Error("引擎还没拿到模型运行时");
+                await runtime.logout(providerId);
+                await reloadModelRegistry(sessions, PREWARM_ID, warmUp, options.agentDir ?? getAgentDir());
+            },
+        },
         async createSession(sessionOptions) {
             // ADR-0021 §2：新建会话就落在 **pi 的会话存储**里（不再用 inMemory + 自建 jsonl），
             // 用我们的 sessionId 当 SDK 的会话 id → 两边 id 空间完全一致。