@aiti-ai/aiti-agent-manager 0.0.0-stage → 0.2.9

package/AGENTS.md

@@ -0,0 +1,51 @@
+# aiti-agent-manager 扩展（部署目录直改指南）
+
+## 结构
+- 运行时文件平铺在本目录根（index.ts / core.cjs …，宿主 loader 按相对路径加载——**禁手改运行时平铺文件**，改 src/ 再 build）
+- `src/` 源码（client/src + 服务端 ts/cjs）· `dist/` 构建产物（禁手改）· `tools/` 构建/部署脚本
+- npm 包形态的扩展：本目录 package.json 含 version 与 aitiConfigs 声明
+
+## 小改现场流程（改文案/样式/小逻辑）
+1. 改 `src/` 下对应源码
+2. `node tools/build.mjs`（client 有构建产物的扩展；纯服务端改动跳过）
+3. `curl -X POST http://127.0.0.1:3001/api/extensions/reload`（dev；prod 3002；外部经 nginx 带 basePath：/dev、/mac、/mdev、/win、/wdev → `/xxx/api/extensions/reload`）
+4. 浏览器刷新页面验证
+
+## 大改回源码仓
+- 源码仓：`extensions/aiti-agent-manager/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-agent-manager`）
+
+## 数据目录（数据分层：config / cache）
+- `ctx.configDir` 根级 = 配置与关键小状态（aiti-configs 备份范围；小、珍贵、人可读）
+- `ctx.cacheDir`（= `<configDir>/cache/`）= 可删缓存：db/venv/日志/大文件；rm -rf 后扩展下次访问自动重建
+- `ctx.dataDir` 已移除（访问即抛）——新代码禁用
+- 本扩展白名单（永不为 cache 的配置文件）见 package.json `aitiConfigs.configFiles`
+
+## 账号档（多账号备份/切换，2026-09-13）
+- **单文件存储**：`<configDir>/agent-accounts.json`（0600）——所有 agent、所有账号档收在一个 JSON；
+  aiti-configs 备份时按 encrypt pattern 加密（`agent-accounts.json`，见其 protected/patterns）。
+- **共享引擎**：`agent-accounts.ts` 是本目录对 `_shared/agent-accounts.ts` 的逐字节副本
+  （shared-copy-sync 测试钉一致性；改动先改 `_shared` 再 cp 副本）。
+- **架构（二版）：manager 只做框架，各家自报家门**——每家 agent 扩展 startup 里
+  `ctx.services.provide("<extId>.agent", descriptor)`（label/modes/fs 探测表/accountSlots/actions）；
+  manager 遍历宿主 `registry.status()` + `services.get` 动态收集，**不写死任何一家**（未 provide 的扩展不出现）。
+  descriptor 契约见 `agents-registry.ts`；6 家 agent 扩展各自提供。
+- **凭据槽位**：由**各家扩展 descriptor.accountSlots(ctx) 自己声明**（路径知识留在各家，可闭包 configDir）；manager 只消费。
+- **静态 ui 插入点**：`ui.toolbar`（`aiti-agent-manager-panel`，icons/bot.svg）+ `ui.dialogs`（与 client registerItems id 一一对应；extman 展示/懒加载对账用）。
+- **current 判定**：内容签名（sha256）+ 账号身份（identity）双判定——token 自动刷新（内容轮换）时靠身份仍标「当前」（`saveAccount({identity})`）。
+- **自动保险**：登录（/ctl start、codebuddy tui-start）、切换、登出前，当前登录若未被任何档覆盖（签名或身份命中）→
+  自动存 `_auto-before-{login,switch,logout}`；永不因切换/重新登录丢账号。
+- **面板样式**：自持样式层 `client/src/agent-manager-styles.mjs`（`am-*` 类；config-button 设计语言 + 主题 var 跟随；`ensureStyles()` 幂等注入）。
+- **账号额度（可选能力，2026-09-13）**：扩展 descriptor 加 `accountQuota: true` 并提供
+  `GET /login/quota[?force=1]`（60s 成功缓存 / 10s 失败退避；形状 `{available,display?,unit?,remaining?,total?,used?,usedPercent?,packages?,note?,expiresAt?,fetchedAt}`）；
+  manager 聚合进 `/agents` 并在账号行渲染 chip（`display` 优先、tooltip 分包、点击走 `/quota/{agent}?force=1` 强制刷新）。
+  **接入契约全文（新 agent 清单 + 六家现状/待办 + 平台坑）→ `docs/pi-web-ext-agent-account-contract.md`。**
+- **API**：`GET /accounts`（总览）；`POST /accounts/{agent}/{save|switch|remove|logout} {alias?}`；
+  `/agents` 聚合带每个 agent 的 `accounts: [...]`（含 current 标记）。
+- **边界**：只做文件级快照/恢复，不解析 token；feature/env 注入的凭据不在文件层（登出后仍生效，属预期）。
+
+## 红线
+- 禁轮询（setInterval 拉取）；需要等待用事件/回调/SSE（桥的 SSE、aiti-event-bus topics）
+- 禁重启生产服务（pi-web 3002 等 restart 须用户明确同意）
+- 禁手改 dist/ 与运行时平铺文件；跨扩展通信走 ctx.services（禁 globalThis.__ext 直穿）
+- 服务端：SQLite 一律 WAL + 分批小事务（批间 setImmediate 让步）；禁 execFileSync 调 >1s 外部程序；>8MB 文件禁同步读

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiti-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @aiti-ai/aiti-agent-manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 统一聚合外部 agent 登录态 + 登录操作代理 + 多账号档（备份/别名/一键切换）+ 账号额度显示——不实现任何登录协议
+
+## 来源 · Origin
+
+本包是 **aiti** 生态的组成部分——以 [pi](https://pi.dev) 为引擎的个人 AI 开发工作台与本地调试注入生态：**aiti-agent**（自托管 Web 工作台，基于开源项目 [pi-web](https://github.com/aiti-ai/pi-web) 构建，浏览器为主操作面）+ 各开发工具内的调试注入（aiti-devtools）+ 丰富的扩展体系。
+
+This package is part of the **aiti** ecosystem — a personal AI development workbench powered by [pi](https://pi.dev): **aiti-agent** (a self-hosted web workbench built on the open-source [pi-web](https://github.com/aiti-ai/pi-web)) plus debug injection into mainstream dev tools (aiti-devtools) and a rich extension system.
+
+- 工作台 / workbench: <https://github.com/aiti-ai/pi-web>
+- 生态仓库 / monorepo: <https://github.com/aiti-ai/aiti-ai>
+- 官网 / site: <https://aiti.pw>
+
+## 功能定位（中文）
+
+统一聚合外部 agent 登录态 + 登录操作代理 + 多账号档（备份/别名/一键切换）+ 账号额度显示——不实现任何登录协议
+
+多 agent 后端 · tags: `agent` · `manager` · `login` · `oauth` · `account` · `quota` · `credits` · `multi-agent`
+
+## Positioning (English)
+
+Unified aggregation of external agent login states + login action proxying + multi-account profiles (backup/alias/one-click switch) + account quota display — implements no login protocol at all
+
+## 安装 / 部署
+
+```bash
+# 部署到 ~/.pi/web/extensions/aiti-agent-manager/ 后 reload
+```
+
+## 文档 · Documentation
+
+- 中文完整文档（aiti-docs）: <https://aiti.pw/extensions/aiti-agent-manager.html>
+- English docs: <https://aiti.pw/en/extensions/aiti-agent-manager.html>
+- 扩展注册表 / registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
+
+## License
+
+MIT

package/agents-registry.test.mjs

@@ -0,0 +1,108 @@
+/**
+ * aiti-agent-manager — agents-registry 纯模块测试（descriptor 收集 / fs 探测 / 聚合 / piHost）。
+ *
+ * Run: node --test pi-web-ext/aiti-agent-manager/agents-registry.test.mjs
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { existsSync, mkdtempSync, mkdirSync, statSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AGENT_DESCRIPTOR_SUFFIX, collectAgents, aggregateAgent, probeAuthEntries,
+  readPiHostAuthProviders, toPiHostProvider,
+} from "./agents-registry.ts";
+
+const HOME = "/home/u";
+
+test("collectAgents：动态收集（跳过未 provide/禁用/不合法），按 agent 名排序", () => {
+  const status = {
+    "aiti-zcode-agent": {},
+    "aiti-codebuddy-agent": {},
+    "aiti-extra": {},                    // 未 provide 描述符 → 跳过
+    "aiti-disabled": { enabled: false }, // 禁用 → 跳过
+  };
+  const services = {
+    get: (k) => {
+      if (k === "aiti-zcode-agent" + AGENT_DESCRIPTOR_SUFFIX) return { agent: "zcode", label: "ZCode", modes: ["url"] };
+      if (k === "aiti-codebuddy-agent" + AGENT_DESCRIPTOR_SUFFIX) return { agent: "codebuddy", label: "CBC", modes: ["apikey", "tui"] };
+      if (k === "aiti-disabled" + AGENT_DESCRIPTOR_SUFFIX) return { agent: "x", label: "X", modes: [] };
+      if (k === "aiti-extra" + AGENT_DESCRIPTOR_SUFFIX) return { label: "缺 agent" }; // 不合法 → 跳过
+      return undefined;
+    },
+  };
+  const got = collectAgents({ status, getService: services.get });
+  assert.deepEqual(got.map((c) => c.def.agent), ["codebuddy", "zcode"], "按 agent 字典序");
+  assert.equal(got[0].extId, "aiti-codebuddy-agent");
+});
+
+test("collectAgents：status 缺失 → 空表（集群未就绪不炸）", () => {
+  assert.deepEqual(collectAgents({ status: null, getService: () => undefined }), []);
+  assert.deepEqual(collectAgents({ status: undefined, getService: () => undefined }), []);
+});
+
+test("probeAuthEntries：file 命中（非空）/ 空文件跳过 / dir 存在即命中 / env 非空命中", () => {
+  const root = mkdtempSync(join(tmpdir(), "am-probe-"));
+  try {
+    mkdirSync(join(root, ".claude"), { recursive: true });
+    writeFileSync(join(root, ".claude", ".credentials.json"), "{}");
+    mkdirSync(join(root, ".qoder"), { recursive: true });
+    const fs = { existsSync: (p) => existsSync(p), statSync: (p) => statSync(p) };
+    assert.equal(probeAuthEntries([{ kind: "file", path: [".claude", ".credentials.json"], label: "x" }], root, {}, fs), "ready");
+    assert.equal(probeAuthEntries([{ kind: "dir", path: [".qoder"], label: "x" }], root, {}, fs), "ready");
+    assert.equal(probeAuthEntries([{ kind: "file", path: [".missing", "a.json"], label: "x" }], root, {}, fs), "missing");
+    assert.equal(probeAuthEntries([{ kind: "env", path: ["ZCODE_API_KEY"], label: "x" }], root, { ZCODE_API_KEY: "k" }, fs), "ready");
+    assert.equal(probeAuthEntries([{ kind: "env", path: ["ZCODE_API_KEY"], label: "x" }], root, { ZCODE_API_KEY: "  " }, fs), "missing", "空白 env 不算");
+    assert.equal(probeAuthEntries([], root, {}, fs), "missing");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("aggregateAgent：扩展智能端点（state 归一）优先于 fs", () => {
+  const def = { agent: "codebuddy", label: "CBC", modes: ["apikey"], extReportsAuthState: true, auth: [{ kind: "file", path: [".codebuddy", "settings.json"], label: "x" }] };
+  const hit = aggregateAgent(def, { home: HOME, env: {}, fs: { existsSync: () => true, statSync: () => ({ size: 1 }) }, extStatus: { state: "ready" } });
+  assert.equal(hit.authState, "ready");
+  assert.equal(hit.source, "ext");
+  const miss = aggregateAgent(def, { home: HOME, env: {}, fs: { existsSync: () => true, statSync: () => ({ size: 1 }) }, extStatus: { state: "missing" } });
+  assert.equal(miss.authState, "missing");
+});
+
+test("aggregateAgent：流程态 waiting → logging-in；其余 idle", () => {
+  const def = { agent: "claude", label: "Claude", modes: ["paste"], auth: [{ kind: "file", path: [".claude", ".credentials.json"], label: "x" }] };
+  const fs = { existsSync: (p) => p.endsWith(".credentials.json"), statSync: () => ({ size: 3 }) };
+  const a = aggregateAgent(def, { home: HOME, env: {}, fs, extStatus: { state: "waiting" } });
+  assert.equal(a.flowState, "logging-in");
+  assert.equal(a.authState, "ready");
+  assert.equal(a.source, "fs");
+  const b = aggregateAgent(def, { home: HOME, env: {}, fs, extStatus: { state: "success" } });
+  assert.equal(b.flowState, "idle");
+});
+
+test("aggregateAgent：无候选表且无智能端点 → unknown（fail-honest）", () => {
+  const def = { agent: "qoder", label: "Qoder", modes: ["url"], auth: [] };
+  const a = aggregateAgent(def, { home: HOME, env: {}, fs: { existsSync: () => false, statSync: () => ({ size: 0 }) }, extStatus: null });
+  assert.equal(a.authState, "unknown");
+  assert.equal(a.source, "none");
+});
+
+test("toPiHostProvider：name 优先于 email；无字段省略", () => {
+  const p = toPiHostProvider("openai", { type: "oauth", name: "李永", email: "a@b.c", expires: "2099-01-01T00:00:00.000Z" });
+  assert.equal(p.user, "李永");
+  assert.equal(p.expired, false);
+  assert.equal(toPiHostProvider("x", {}).user, undefined);
+});
+
+test("readPiHostAuthProviders：只取展示字段（token 不出服务端）+ 坏文件容错", () => {
+  const doc = JSON.stringify({
+    zai: { type: "oauth", email: "me@x.com", access: "SECRET-A", refresh: "SECRET-R", expires: "2099-01-01T00:00:00.000Z" },
+    bad: "not-object",
+  });
+  const list = readPiHostAuthProviders("/agent", () => doc);
+  assert.equal(list.length, 1);
+  assert.equal(list[0].provider, "zai");
+  assert.equal(list[0].user, "me@x.com");
+  assert.equal(JSON.stringify(list).includes("SECRET"), false, "token 不返回");
+  assert.deepEqual(readPiHostAuthProviders("/agent", () => null), []);
+  assert.deepEqual(readPiHostAuthProviders("/agent", () => "{broken"), []);
+});

package/agents-registry.ts

@@ -0,0 +1,213 @@
+/**
+ * agents-registry —— agent 描述符契约 + 动态收集 + 聚合逻辑（纯模块，可测）。
+ *
+ * 架构（2026-09-13 二版，拍板）：**manager 不写死任何一家 agent**——每家 agent 扩展在
+ * startup 里 `ctx.services.provide("<extId>.agent", descriptor)` 自报家门（label / modes /
+ * fs 探测表 / 凭据槽位 / 登录动作）；manager 遍历宿主扩展清单（`registry.status()`）
+ * 动态发现、聚合并统一展示。未 provide 的扩展 = 不出现在管理面（其登录能力本就不可用）。
+ *
+ * 聚合原则不变：
+ *   - **不实现任何登录协议、不碰凭据内容**——只做 stat 级存在性探测与端点转发；
+ *   - 扩展智能状态端点（`/login/status` 返回 `{state: ready|missing|…}`）优先，
+ *     否则按 descriptor.auth 候选探测表（file 非空 / dir 存在 / env 非空）；
+ *   - 账号档凭据槽位由 `descriptor.accountSlots(ctx)` 提供（各家的路径知识留在各家）。
+ *
+ * 探测表事实依据（2026-09-10/11 实测本机，现由各家自行声明）：
+ *   zcode ~/.zcode/v2/credentials.json · claude ~/.claude/.credentials.json ·
+ *   codex ~/.codex/auth.json · cursor ~/.config/cursor/auth.json ·
+ *   qoder ~/.qoder{,-cn}/.auth/user · codebuddy 扩展端点优先（CLI auth + 托管凭据）
+ */
+
+export type AuthState = "ready" | "missing" | "unknown";
+
+export interface AuthProbeEntry {
+  kind: "file" | "dir" | "env";
+  /** file/dir: 相对 HOME 的路径段；env: 环境变量名 */
+  path: string[];
+  label: string;
+}
+
+/** 登录形态：url=A url-only / paste=B paste-relay / apikey=API-key 注入 / tui=服务端 PTY 驱动。 */
+export type AgentMode = "url" | "paste" | "apikey" | "tui";
+
+/** 账号档凭据槽位（账号档引擎通用形状；key 为逻辑标识，path 为当前机器绝对路径）。 */
+export interface AccountSlot {
+  key: string;
+  label: string;
+  path: string;
+}
+
+/** descriptor.accountSlots 的入参：manager 组装的当前机器上下文。 */
+export interface AccountSlotContext {
+  home: string;
+  /** PI_WEB_DATA_DIR（或默认 ~/.pi/web/data）——data 根；派生各扩展 configDir 用（<data>/<extId>/config）。 */
+  webDataRoot: string;
+  env: Record<string, string | undefined>;
+  platform: string;
+}
+
+/** 登录动作代理映射（manager /ctl/{agent}/{action} 转发用）。 */
+export interface AgentActionSpec {
+  m: string;
+  sub: string[];
+  body?: boolean;
+}
+
+/**
+ * 各 agent 扩展在 startup 里 provide 的描述符（key = `<extId>.agent`）。
+ * 扩展侧直接写对象字面量（无需 import 本类型）；manager 侧消费。
+ */
+export interface AgentDescriptor {
+  /** agent 唯一 key（/ctl/{agent} 与账号档分组用，如 "codebuddy"） */
+  agent: string;
+  label: string;
+  modes: AgentMode[];
+  /** true = 本扩展 /login/status 返回 {state:"ready"|"missing"} 语义（优先于 fs 探测） */
+  extReportsAuthState?: boolean;
+  /** true = 支持官方账号额度查询（GET /login/quota；如 codebuddy credits） */
+  accountQuota?: boolean;
+  dependencyHint?: string;
+  /** fs/env 候选探测（任一命中 = ready）；缺省 = 只信扩展端点 */
+  auth?: AuthProbeEntry[];
+  /** 本家账号档凭据槽位（路径知识在本家；可闭包捕获 configDir） */
+  accountSlots?: (ctx: AccountSlotContext) => AccountSlot[];
+  /** 非标准登录动作（如 codebuddy 的 tui-start/set-key/clear）；缺省 = 标准 start/cancel/submit */
+  actions?: Record<string, AgentActionSpec>;
+}
+
+/** 服务 key 后缀约定：`<extId>.agent`。 */
+export const AGENT_DESCRIPTOR_SUFFIX = ".agent";
+
+export interface CollectedAgent {
+  extId: string;
+  def: AgentDescriptor;
+}
+
+/**
+ * 从宿主扩展清单 + 服务定位器动态收集 agent 描述符（纯函数）。
+ * 跳过：未启用/报错的扩展、未 provide 描述符或不合法（agent/label 缺失）的扩展。
+ * 返回按 agent 名排序（面板顺序稳定）。
+ */
+export function collectAgents(opts: {
+  status: Record<string, unknown> | null;
+  getService: (key: string) => unknown;
+}): CollectedAgent[] {
+  if (!opts.status || typeof opts.status !== "object") return [];
+  const out: CollectedAgent[] = [];
+  for (const [extId, raw] of Object.entries(opts.status)) {
+    const entry = raw as { enabled?: unknown } | undefined;
+    if (entry && entry.enabled === false) continue;
+    let d: AgentDescriptor | undefined;
+    try {
+      d = opts.getService(extId + AGENT_DESCRIPTOR_SUFFIX) as AgentDescriptor | undefined;
+    } catch {
+      d = undefined;
+    }
+    if (!d || typeof d.agent !== "string" || !d.agent) continue;
+    if (typeof d.label !== "string" || !d.label) continue;
+    if (!Array.isArray(d.modes)) d = { ...d, modes: [] };
+    out.push({ extId, def: d });
+  }
+  return out.sort((a, b) => a.def.agent.localeCompare(b.def.agent));
+}
+
+export interface ProbeFs {
+  existsSync(path: string): boolean;
+  statSync(path: string): { size: number };
+}
+
+/** fs/env 候选探测：任一命中 = ready；全不命中 = missing（空候选表由调用方归 unknown）。 */
+export function probeAuthEntries(entries: AuthProbeEntry[], home: string, env: Record<string, string | undefined>, fs: ProbeFs): AuthState {
+  for (const e of entries) {
+    if (e.kind === "env") {
+      const v = env[e.path[0]];
+      if (typeof v === "string" && v.trim()) return "ready";
+      continue;
+    }
+    const p = [home, ...e.path].join("/");
+    if (!fs.existsSync(p)) continue;
+    if (e.kind === "dir") return "ready"; // 目录存在即命中
+    try {
+      if (fs.statSync(p).size > 0) return "ready"; // 文件存在且非空
+    } catch { /* raced → 下一候选 */ }
+  }
+  return "missing";
+}
+
+/** 单 agent 聚合：扩展智能端点 > fs 探测；无候选表且无智能端点 = unknown（fail-honest）。 */
+export function aggregateAgent(def: AgentDescriptor, opts: {
+  home: string;
+  env: Record<string, string | undefined>;
+  fs: ProbeFs;
+  /** 扩展 /login/status 响应（拉取失败 = null） */
+  extStatus: { authState?: unknown; state?: unknown } | null;
+}): { authState: AuthState; flowState: "idle" | "logging-in" | string; source: "ext" | "fs" | "none" } {
+  // 流程态：waiting = 登录中
+  const flowState = opts.extStatus?.state === "waiting" ? "logging-in" : "idle";
+  let authState: AuthState = "unknown";
+  let source: "ext" | "fs" | "none" = "none";
+  if (def.extReportsAuthState && opts.extStatus) {
+    // 扩展智能端点：authState 字段优先，state 字段（codebuddy 语义 ready|missing）归一
+    const raw = opts.extStatus.authState ?? opts.extStatus.state;
+    if (raw === "ready" || raw === "missing") {
+      authState = raw;
+      source = "ext";
+    }
+  } else if (def.auth && def.auth.length > 0) {
+    authState = probeAuthEntries(def.auth, opts.home, opts.env, opts.fs);
+    source = "fs";
+  }
+  return { authState, flowState, source };
+}
+
+// ============================================================================
+// §9.5 步 5：pi 宿主订阅 provider 状态（auth.json 只读；**绝不返回 token 内容**）
+// ============================================================================
+
+export interface PiHostProvider {
+  provider: string;
+  type?: string;
+  user?: string;
+  expires?: string;
+  /** expires 已过期（能解析时） */
+  expired?: boolean;
+}
+
+/** auth.json 单 provider 行归一（只取展示字段）。 */
+export function toPiHostProvider(provider: string, raw: Record<string, unknown>): PiHostProvider {
+  const out: PiHostProvider = { provider };
+  if (typeof raw.type === "string") out.type = raw.type;
+  const user = typeof raw.name === "string" && raw.name ? raw.name : typeof raw.email === "string" ? raw.email : undefined;
+  if (user) out.user = user;
+  const expires = typeof raw.expires === "string" ? raw.expires : typeof raw.expires === "number" ? new Date(raw.expires).toISOString() : undefined;
+  if (expires) {
+    out.expires = expires;
+    const ms = Date.parse(expires);
+    if (Number.isFinite(ms)) out.expired = ms < Date.now();
+  }
+  return out;
+}
+
+/**
+ * 读 pi 宿主订阅 provider 清单（auth.json 顶层键 = provider id；只取展示字段，
+ * access/refresh token 一律不读出不返回）。文件缺失/坏 JSON → 空数组（面板隐藏该组）。
+ */
+export function readPiHostAuthProviders(agentDir: string, readFile: (p: string) => string | null): PiHostProvider[] {
+  let raw: string | null;
+  try {
+    raw = readFile(`${agentDir}/auth.json`);
+  } catch {
+    return [];
+  }
+  if (!raw) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  return Object.entries(parsed as Record<string, unknown>)
+    .filter(([, v]) => v && typeof v === "object" && !Array.isArray(v))
+    .map(([provider, v]) => toPiHostProvider(provider, v as Record<string, unknown>));
+}