@trim21/personal-pi-extensions 0.1.608 → 0.1.611

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.608",
+  "version": "0.1.611",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/aft/tools.ts

@@ -427,18 +427,25 @@ export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): vo
 
 /** `BinaryBridge.subscribeStatus` 的能力探测类型：AftProjectTransport 接口上未暴露。 */
 interface StatusSubscribableBridge {
-  subscribeStatus?(listener: (snapshot: StatusSnapshot) => void): () => void;
+  subscribeStatus(listener: (snapshot: StatusSnapshot) => void): () => void;
 }
 
-function subscribeBridgeStatus(
+/**
+ * 运行时能力探测：`AftProjectTransport` 接口没声明 subscribeStatus，但实际实现
+ * （BinaryBridge）有。用 in 收窄做真检查，而不是断言成「一定支持」。
+ */
+export function isStatusSubscribable(
+  bridge: AftProjectTransport,
+): bridge is AftProjectTransport & StatusSubscribableBridge {
+  return "subscribeStatus" in bridge && typeof bridge.subscribeStatus === "function";
+}
+
+export function subscribeBridgeStatus(
   bridge: AftProjectTransport,
   listener: (snapshot: StatusSnapshot) => void,
 ): (() => void) | undefined {
-  const subscribable = bridge as AftProjectTransport & StatusSubscribableBridge;
-  if (typeof subscribable.subscribeStatus !== "function") {
-    return undefined;
-  }
-  return subscribable.subscribeStatus(listener);
+  if (!isStatusSubscribable(bridge)) return undefined;
+  return bridge.subscribeStatus(listener);
 }
 
 /**

package/src/bwrap/core.ts

@@ -31,6 +31,18 @@ export const NETWORK_MODES = ["block", "limited", "allow-all"] as const;
 
 export type NetworkMode = (typeof NETWORK_MODES)[number];
 
+// 模式集合按 string 装：外部输入（CLI 参数）是 string，用它收窄成字面量联合。
+const FS_MODE_SET: ReadonlySet<string> = new Set(FS_MODES);
+const NETWORK_MODE_SET: ReadonlySet<string> = new Set(NETWORK_MODES);
+
+export function isFsMode(value: unknown): value is FsMode {
+  return typeof value === "string" && FS_MODE_SET.has(value);
+}
+
+export function isNetworkMode(value: unknown): value is NetworkMode {
+  return typeof value === "string" && NETWORK_MODE_SET.has(value);
+}
+
 const fsConfigProperties = {
   mode: StringEnum(FS_MODES),
   writablePaths: Type.Array(Type.String()),

package/src/bwrap/mihomo-config.ts

@@ -81,8 +81,8 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
     const match = /^\[(.+)\](?::(\d+))?$/.exec(entry);
     if (match?.[1] === undefined) throw new Error(`Invalid allowlist entry "${entry}"`);
     host = match[1];
-    // 端口组 (?::(\d+))? 可选：无端口时 match[2] 在运行时是 undefined
-    const portPart = match[2] as string | undefined;
+    // 端口组 (?::(\d+))? 可选：无端口时 at(2) 是 undefined
+    const portPart = match.at(2);
     port = portPart === undefined ? undefined : parsePort(portPart);
   } else {
     const colon = entry.lastIndexOf(":");

package/src/bwrap/runtime.ts

@@ -17,6 +17,7 @@ import { type TObject, Type } from "typebox";
 
 import { type CommandSpec, parseCommand } from "../lib/cli.js";
 import { fenceCodeBlock } from "../lib/markdown.js";
+import { isUnknownArray } from "../lib/narrow.js";
 import { formatDisplayPath } from "../lib/path.js";
 import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
 import { type SelectAction, selectMultiple, selectWithOptionalInput } from "../lib/ui.js";
@@ -830,9 +831,8 @@ export class BwrapRuntime {
     if (existsSync(project)) {
       config = JSON.parse(readFileSync(project, "utf8")) as Record<string, unknown>;
     }
-    const existing = Array.isArray(config.approvalRules)
-      ? (config.approvalRules as ApprovalRule[])
-      : [];
+    // 既有规则按不透明值原样保留（形状不认识也不丢），只追加本次允许的规则。
+    const existing = isUnknownArray(config.approvalRules) ? config.approvalRules : [];
     config.approvalRules = [...existing, ...newRules];
     await mkdir(dirname(project), { recursive: true });
     await writeFile(project, `${JSON.stringify(config, null, 2)}\n`, "utf8");

package/src/lib/cli.ts

@@ -32,10 +32,11 @@
  * the result so handlers can display it in chat instead of writing stdout.
  */
 
-import type { Static, TObject } from "typebox";
+import { IsKind, type Static, type TObject, type TSchema } from "typebox";
 import { Value } from "typebox/value";
 
 import { shlexSplit } from "./cli-args.js";
+import { isRecord, isUnknownArray } from "./narrow.js";
 
 /** Per-flag CLI metadata on top of the typebox schema. */
 export interface FlagMeta {
@@ -69,16 +70,6 @@ export type CommandResult<TFlags extends TObject> =
   | { kind: "help"; text: string }
   | { kind: "error"; text: string };
 
-/** Runtime view of a flag schema (typebox's `TSchema` is empty at the type level). */
-interface FlagSchema {
-  "~kind"?: string;
-  "~optional"?: boolean;
-  type?: string;
-  default?: unknown;
-  description?: string;
-  anyOf?: { type?: string; const?: unknown }[];
-}
-
 type FlagKind = "boolean" | "string" | "number" | "enum";
 
 interface FlagInfo {
@@ -88,54 +79,67 @@ interface FlagInfo {
   required: boolean;
   placeholder: string;
   description: string;
-  schema: FlagSchema;
+  schema: TSchema;
 }
 
-function kindOf(key: string, schema: FlagSchema): FlagKind {
-  switch (schema["~kind"]) {
-    case "Boolean": {
-      return "boolean";
-    }
-    case "String": {
-      return "string";
-    }
-    case "Number":
-    case "Integer": {
-      return "number";
-    }
-    case "Union": {
-      return "enum";
-    }
-    default: {
-      throw new TypeError(
-        `Unsupported flag type for '${key}': ${schema["~kind"] ?? schema.type ?? "unknown"} ` +
-          "(use Type.Boolean/String/Number/Integer or a string literal union)",
-      );
-    }
-  }
+/** schema 的种类名，仅用于报错文案。 */
+function schemaKindLabel(schema: TSchema): string {
+  if ("~kind" in schema && typeof schema["~kind"] === "string") return schema["~kind"];
+  if ("type" in schema && typeof schema.type === "string") return schema.type;
+  return "unknown";
+}
+
+function kindOf(key: string, schema: TSchema): FlagKind {
+  if (IsKind(schema, "Boolean")) return "boolean";
+  if (IsKind(schema, "String")) return "string";
+  if (IsKind(schema, "Number") || IsKind(schema, "Integer")) return "number";
+  if (IsKind(schema, "Union")) return "enum";
+  throw new TypeError(
+    `Unsupported flag type for '${key}': ${schemaKindLabel(schema)} ` +
+      "(use Type.Boolean/String/Number/Integer or a string literal union)",
+  );
+}
+
+/** Type.Optional 的 `~optional` 标记：缺省即「不带该 flag 时不报错」。 */
+function isOptionalFlag(schema: TSchema): boolean {
+  return "~optional" in schema && schema["~optional"] === true;
+}
+
+/** schema 声明的 default：有 default 的 flag 缺省时由 typebox 补值，不算 required。 */
+function flagDefault(schema: TSchema): unknown {
+  return "default" in schema ? schema.default : undefined;
+}
+
+function flagDescription(schema: TSchema): string {
+  return "description" in schema && typeof schema.description === "string"
+    ? schema.description
+    : "";
 }
 
 /** Allowed values for a string-literal union flag, or undefined for mixed unions. */
-function enumValues(schema: FlagSchema): string[] | undefined {
-  const anyOf = schema.anyOf;
-  if (!anyOf) return undefined;
-  const values = anyOf.map((s) => s.const).filter((c) => typeof c === "string");
-  return values.length === anyOf.length ? values : undefined;
+function enumValues(schema: TSchema): string[] | undefined {
+  if (!("anyOf" in schema) || !isUnknownArray(schema.anyOf)) return undefined;
+  const values: string[] = [];
+  for (const variant of schema.anyOf) {
+    if (!isRecord(variant) || typeof variant.const !== "string") return undefined;
+    values.push(variant.const);
+  }
+  return values;
 }
 
 function buildFlagInfos<TFlags extends TObject>(spec: CommandSpec<TFlags>): FlagInfo[] {
+  // flagMeta 的键随 flags 泛型变化（映射类型），运行时按字符串键索引需在此收敛一次。
   const meta = spec.flagMeta as Record<string, FlagMeta> | undefined;
   const infos: FlagInfo[] = [];
-  for (const [key, rawSchema] of Object.entries(spec.flags.properties)) {
-    const schema = rawSchema as FlagSchema;
+  for (const [key, schema] of Object.entries(spec.flags.properties)) {
     const m = meta?.[key];
     infos.push({
       key,
       kind: kindOf(key, schema),
       short: m?.short,
-      required: schema["~optional"] !== true && schema.default === undefined,
+      required: !isOptionalFlag(schema) && flagDefault(schema) === undefined,
       placeholder: m?.valuePlaceholder ?? `<${key}>`,
-      description: m?.description ?? schema.description ?? "",
+      description: m?.description ?? flagDescription(schema),
       schema,
     });
   }
@@ -290,19 +294,20 @@ export function parseCommand<TFlags extends TObject>(
   }
 
   for (const f of flags) {
-    if (f.kind === "enum" && typeof rawFlags[f.key] === "string") {
+    const raw = rawFlags[f.key];
+    if (typeof raw === "string" && f.kind === "enum") {
       const values = enumValues(f.schema);
-      if (values && !values.includes(rawFlags[f.key] as string)) {
+      if (values && !values.includes(raw)) {
         return errorResult(
           spec,
-          `Invalid value for '--${f.key}': '${String(rawFlags[f.key])}' (expected one of: ${values.join(", ")})`,
+          `Invalid value for '--${f.key}': '${raw}' (expected one of: ${values.join(", ")})`,
         );
       }
     }
-    if (f.kind === "number" && typeof rawFlags[f.key] === "string") {
-      const n = Number(rawFlags[f.key]);
+    if (typeof raw === "string" && f.kind === "number") {
+      const n = Number(raw);
       if (Number.isNaN(n)) {
-        return errorResult(spec, `Invalid value for '--${f.key}': '${String(rawFlags[f.key])}'`);
+        return errorResult(spec, `Invalid value for '--${f.key}': '${raw}'`);
       }
       rawFlags[f.key] = n;
     }

package/src/lib/file-reads.ts

@@ -16,6 +16,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { isRecord } from "./narrow.js";
+
 const fileSnapshotSchema = Type.Object({
   digest: Type.String(),
   textEditable: Type.Boolean(),
@@ -39,8 +41,11 @@ export function snapshotOf(content: Uint8Array | string, textEditable = true): F
 /** 整文件指纹：流式读取，避免为记账把大文件整个读进内存。 */
 export async function fileDigest(filePath: string): Promise<string> {
   const hash = createHash("sha256");
-  for await (const chunk of createReadStream(filePath)) {
-    hash.update(chunk as Buffer);
+  // createReadStream 的 async iterator 在 @types/node 里是 any：显式声明成 Buffer 流，
+  // 而不是在 update 处断言。
+  const stream: AsyncIterable<Buffer> = createReadStream(filePath);
+  for await (const chunk of stream) {
+    hash.update(chunk);
   }
   return hash.digest("hex");
 }
@@ -150,8 +155,8 @@ export function restoreReads(
   for (const entry of sessionManager.getBranch()) {
     if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
     if (!toolNames.has(entry.message.toolName)) continue;
-    const details = entry.message.details as { reads?: unknown } | undefined;
-    if (!details?.reads) continue;
+    const details = entry.message.details;
+    if (!isRecord(details) || !details.reads) continue;
     for (const [filePath, snapshot] of deserializeReads(details.reads)) {
       state.reads.set(filePath, snapshot);
     }

package/src/lib/github.ts

@@ -11,6 +11,9 @@
 import { spawn } from "node:child_process";
 
 import { Octokit } from "octokit";
+import { type Static, Type } from "typebox";
+
+import { parseWithSchema } from "./parse-with-schema.js";
 
 export type SearchKind = "issue" | "pr";
 
@@ -25,24 +28,36 @@ export interface SearchParams {
   limit?: number;
 }
 
-/** REST /search/issues response shape we consume (item is an issue/pr union). */
-interface RawSearchItem {
-  number: number;
-  state: string;
-  title: string;
-  html_url: string;
+/**
+ * REST /search/issues 里本客户端消费的 item 形状（issue / PR 联合）。只声明真正
+ * 读取的字段，其余键忽略；未声明的字段类型不符时按「响应形状变了」处理，报错而
+ * 不是把 undefined 混进结果。labels 兼容字符串与 {name} 两种形态（openapi 里是
+ * 联合类型）。
+ */
+const searchItemSchema = Type.Object({
+  number: Type.Number(),
+  state: Type.Union([Type.Literal("open"), Type.Literal("closed")]),
+  title: Type.String(),
+  html_url: Type.String(),
   /** The search API exposes the repo as a URL, not as an object. */
-  repository_url: string;
-  user: { login: string } | null;
-  labels: { name: string }[];
-  milestone: { title: string } | null;
-  assignees: { login: string }[];
-  comments: number;
-  created_at: string;
-  updated_at: string;
-  closed_at: string | null;
-  pull_request: { merged_at: string | null } | null;
-}
+  repository_url: Type.String(),
+  user: Type.Union([Type.Object({ login: Type.String() }), Type.Null()]),
+  labels: Type.Array(
+    Type.Union([Type.String(), Type.Object({ name: Type.Optional(Type.String()) })]),
+  ),
+  milestone: Type.Union([Type.Object({ title: Type.Optional(Type.String()) }), Type.Null()]),
+  assignees: Type.Array(Type.Object({ login: Type.String() })),
+  comments: Type.Number(),
+  created_at: Type.String(),
+  updated_at: Type.String(),
+  closed_at: Type.Union([Type.String(), Type.Null()]),
+  pull_request: Type.Union([
+    Type.Object({ merged_at: Type.Optional(Type.Union([Type.String(), Type.Null()])) }),
+    Type.Null(),
+  ]),
+});
+
+type SearchItem = Static<typeof searchItemSchema>;
 
 export interface SearchHit {
   number: number;
@@ -162,21 +177,21 @@ function toDate(iso: string | null | undefined): string {
 const REPO_URL_RE = /\/repos\/([^/]+\/[^/]+)$/;
 
 /** repository_url looks like https://api.github.com/repos/OWNER/REPO */
-function repoName(raw: RawSearchItem): string {
+function repoName(raw: SearchItem): string {
   const match = REPO_URL_RE.exec(raw.repository_url);
   return match?.[1] ?? "";
 }
 
-function normalize(raw: RawSearchItem): SearchHit {
+function normalize(raw: SearchItem): SearchHit {
   const mergedAt = raw.pull_request?.merged_at ?? "";
   return {
     number: raw.number,
-    state: mergedAt ? "merged" : (raw.state as "open" | "closed"),
+    state: mergedAt ? "merged" : raw.state,
     title: raw.title,
     url: raw.html_url,
     repo: repoName(raw),
     author: raw.user?.login ?? "",
-    labels: raw.labels.map((l) => l.name),
+    labels: raw.labels.map((label) => (typeof label === "string" ? label : (label.name ?? ""))),
     milestone: raw.milestone?.title ?? "",
     assignees: raw.assignees.map((a) => a.login),
     comments: raw.comments,
@@ -320,7 +335,7 @@ export function createGithubSearch(options: GithubClientOptions = {}): GithubSea
           q,
           per_page: limit,
         });
-        return data.items.map((item) => normalize(item as RawSearchItem));
+        return data.items.map((item) => normalize(parseWithSchema(searchItemSchema, item)));
       } catch (error) {
         const status = (error as { status?: number }).status;
         const message = (error as { message?: string }).message ?? String(error);

package/src/lib/lsp/lsp.ts

@@ -370,13 +370,24 @@ export type StatusRenderer = (text: string | undefined) => void;
 export type LspInspectQuery = "definition" | "references" | "hover";
 
 /**
- * 返回类型与 query 泛型关联：query 为 "hover" 时返回 hover 内容，否则返回
- * 位置列表。实现内部用 cast 建立关联（TS 无法验证分支与泛型的对应关系）。
+ * 返回类型与 query 关联：query 为 "hover" 时返回 hover 内容，否则返回位置列表。
+ * 关联由 `inspect` 的重载签名建立（泛型参数下 TS 无法验证分支与返回体的对应关系，
+ * 所以接口按 query 分重载，实现体只需返回这个联合）。
  */
 export type LspInspectResult<Q extends LspInspectQuery = LspInspectQuery> = Q extends "hover"
   ? { serverID: string; query: "hover"; hover: Hover | null }
   : { serverID: string; query: "definition" | "references"; locations: InspectLocation[] };
 
+/** 只读符号查询的入参：query 决定返回体（见 LspInspectResult）。line / character 为 0-based。 */
+export interface LspInspectRequest<Q extends LspInspectQuery = LspInspectQuery> {
+  file: string;
+  cwd: string;
+  line: number;
+  character: number;
+  query: Q;
+  options?: LspRequestOptions;
+}
+
 export interface LspRequestOptions {
   notify?: ExtensionUIContext["notify"];
   /** 中止时提前结束诊断等待（已中止时直接跳过诊断）。 */
@@ -427,14 +438,11 @@ export interface LspService {
    * 的服务器，按配置顺序取第一个成功结果；服务器不支持该方法（MethodNotFound）
    * 时跳过并尝试下一个，全部不支持时抛聚合错误。line / character 为 0-based。
    */
-  inspect<Q extends LspInspectQuery>(request: {
-    file: string;
-    cwd: string;
-    line: number;
-    character: number;
-    query: Q;
-    options?: LspRequestOptions;
-  }): Promise<LspInspectResult<Q>>;
+  inspect(request: LspInspectRequest<"hover">): Promise<LspInspectResult<"hover">>;
+  inspect(
+    request: LspInspectRequest<"definition" | "references">,
+  ): Promise<LspInspectResult<"definition" | "references">>;
+  inspect(request: LspInspectRequest): Promise<LspInspectResult>;
   shutdownAll(): Promise<void>;
   /** 停止全部服务器并禁用 LSP：之后工具调用不再 spawn，直到 start/reload。 */
   stop(): Promise<void>;
@@ -994,14 +1002,12 @@ export function createLspService(
   }
 
   /** 只读符号查询：与 rename 同款多服务器策略，但 MethodNotFound 是"跳过"而非失败。 */
-  async function inspect<Q extends LspInspectQuery>(request: {
-    file: string;
-    cwd: string;
-    line: number;
-    character: number;
-    query: Q;
-    options?: LspRequestOptions;
-  }): Promise<LspInspectResult<Q>> {
+  async function inspect(request: LspInspectRequest<"hover">): Promise<LspInspectResult<"hover">>;
+  async function inspect(
+    request: LspInspectRequest<"definition" | "references">,
+  ): Promise<LspInspectResult<"definition" | "references">>;
+  async function inspect(request: LspInspectRequest): Promise<LspInspectResult>;
+  async function inspect(request: LspInspectRequest): Promise<LspInspectResult> {
     const clients = await getClients(
       request.file,
       request.cwd,
@@ -1024,7 +1030,7 @@ export function createLspService(
       try {
         if (request.query === "hover") {
           const hover = await client.hover(position);
-          return { serverID: client.serverID, query: "hover", hover } as LspInspectResult<Q>;
+          return { serverID: client.serverID, query: "hover", hover };
         }
         const locations =
           request.query === "definition"
@@ -1034,7 +1040,7 @@ export function createLspService(
           serverID: client.serverID,
           query: request.query,
           locations,
-        } as LspInspectResult<Q>;
+        };
       } catch (error) {
         // 调用方取消不是"服务器失败"：直接向上抛，别折叠成 all-servers-failed
         request.options?.signal?.throwIfAborted();

package/src/lib/lsp/rename.ts

@@ -17,6 +17,8 @@ import { fileURLToPath } from "node:url";
 
 import type { TextEdit, WorkspaceEdit } from "vscode-languageserver-types";
 
+import { isRecord } from "../narrow.js";
+
 /** 单个文件展开后的编辑结果。 */
 export interface AppliedFileEdit {
   readonly path: string;
@@ -38,13 +40,7 @@ interface RangeLike {
 
 /** 编辑联合里 SnippetTextEdit 没有 newText，应用层不支持且无法静默处理。 */
 function isRangeLike(edit: unknown): edit is RangeLike {
-  return (
-    typeof edit === "object" &&
-    edit !== null &&
-    "range" in edit &&
-    "newText" in edit &&
-    typeof (edit as { newText: unknown }).newText === "string"
-  );
+  return isRecord(edit) && "range" in edit && "newText" in edit && typeof edit.newText === "string";
 }
 
 /** file:// URI → 规范化本地路径；非 file scheme 是服务器的意外行为，直接报错。 */

package/src/lib/lsp/server-config.ts

@@ -25,6 +25,7 @@ import { minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { isRecord } from "../narrow.js";
 import { type LspServerAdapter, type LspServerHandle, type ServerKind } from "./adapter.js";
 import { exists, findBinaryInWorkspace, which } from "./bin.js";
 import { spawnProcess } from "./launch.js";
@@ -185,11 +186,6 @@ async function runConfigCommand(argv: string[], options: ConfigCommandOptions):
 /** 命令 stdout 即 initializationOptions：JSON 对象，经 typebox 校验后作为配置值。 */
 const initializationOptionsOutputSchema = Type.Record(Type.String(), Type.Unknown());
 
-/** 纯对象判定（数组与 null 不算），用于深合并与命令输出校验。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** 深合并 initializationOptions：两侧都是纯对象时逐层递归，其余类型整体覆盖（override 优先）。 */
 function mergeInitializationOptions(
   base: Record<string, unknown> | undefined,

package/src/lib/narrow.ts

@@ -0,0 +1,15 @@
+/**
+ * unknown 收窄守卫：外部数据（JSON、SQLite 行、子进程输出、宿主抛出的错误）
+ * 在类型层是 unknown，用守卫显式收窄，避免用 `as` 断言把未检查的值伪装成
+ * 已知类型。
+ */
+
+/** 纯对象判定（数组与 null 不算）。 */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 数组判定。`Array.isArray` 单独用会把 unknown 收成 any[]，元素仍是未检查的。 */
+export function isUnknownArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}

package/src/opencode/grep.ts

@@ -19,6 +19,7 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { isRecord } from "../lib/narrow.js";
 import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { didYouMean } from "./files.js";
 import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
@@ -74,7 +75,7 @@ export function parseGrepRecord(line: string): GrepMatch | undefined {
   } catch (error) {
     throw new Error("Invalid ripgrep JSON output", { cause: error });
   }
-  if (typeof json !== "object" || json === null || (json as { type?: unknown }).type !== "match") {
+  if (!isRecord(json) || json.type !== "match") {
     return undefined;
   }
   const record = parseWithSchema(rawMatchSchema, json);

package/src/session-name.ts

@@ -36,6 +36,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { isRecord } from "./lib/narrow.js";
+
 // ── constants ────────────────────────────────────────────────────────────────
 
 /** ~/.pi/agent/settings.json：sessionName 配置所在文件 */
@@ -153,13 +155,7 @@ function messageText(content: unknown): string {
   return content
     .map((part: unknown) => {
       if (typeof part === "string") return part;
-      if (
-        part &&
-        typeof part === "object" &&
-        typeof (part as Record<string, unknown>).text === "string"
-      ) {
-        return (part as Record<string, unknown>).text as string;
-      }
+      if (isRecord(part) && typeof part.text === "string") return part.text;
       return "";
     })
     .join("")

package/src/talk/core.ts

@@ -14,6 +14,7 @@
  * poll — so a swallowed sendMessage error no longer destroys the letter.
  */
 
+import { isRecord } from "../lib/narrow.js";
 import { age, formatListing, refusalUnknown, shortAddr } from "./format.js";
 import {
   deleteGroup,
@@ -101,14 +102,11 @@ export const TALK_JOIN_ENTRY_TYPE = "talk:join";
 export function restoreTalkAgentId(branchEntries: readonly unknown[]): string | undefined {
   let agentId: string | undefined;
   for (const entry of branchEntries) {
-    if (typeof entry !== "object" || entry === null) continue;
-    const { type, customType, data } = entry as {
-      type?: unknown;
-      customType?: unknown;
-      data?: unknown;
-    };
+    if (!isRecord(entry)) continue;
+    const { type, customType, data } = entry;
     if (type !== "custom" || customType !== TALK_JOIN_ENTRY_TYPE) continue;
-    const recorded = (data as { agentId?: unknown } | undefined)?.agentId;
+    if (!isRecord(data)) continue;
+    const recorded = data.agentId;
     if (typeof recorded === "string" && recorded.length > 0) agentId = recorded;
   }
   return agentId;

package/src/talk/mailbox.ts

@@ -18,6 +18,7 @@ import { randomUUID } from "node:crypto";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { isRecord } from "../lib/narrow.js";
 import { asksNs, assertAddress, inboxNs } from "./registry.js";
 import type { TalkStorage } from "./storage.js";
 
@@ -49,14 +50,13 @@ export type LetterKind = Letter["kind"];
  */
 export function normalizeLetter(value: unknown): Letter | null {
   if (Value.Check(LetterSchema, value)) return value;
-  const record = value as { from?: unknown } | null;
-  const from = record?.from;
-  if (typeof from !== "object" || from === null) return null;
-  const fromRecord = from as Record<string, unknown>;
-  if (typeof fromRecord.sessionId !== "string") return null;
+  if (!isRecord(value)) return null;
+  const from = value.from;
+  if (!isRecord(from)) return null;
+  if (typeof from.sessionId !== "string") return null;
   const migrated = {
-    ...(value as object),
-    from: { ...fromRecord, agentId: fromRecord.sessionId },
+    ...value,
+    from: { ...from, agentId: from.sessionId },
   };
   return Value.Check(LetterSchema, migrated) ? migrated : null;
 }

package/src/talk/registry.ts

@@ -114,8 +114,9 @@ export async function readRecord(storage: TalkStorage, addr: string): Promise<Ag
   if (Value.Check(AgentRecordSchema, raw)) return raw;
   // Migrate legacy records in place of the `sessionId` → `agentId` rename.
   if (Value.Check(LegacyAgentRecordSchema, raw)) {
-    const { sessionId, ...rest } = raw as { sessionId: string } & Record<string, unknown>;
-    return { ...rest, agentId: sessionId } as AgentRecord;
+    // Value.Check 是类型守卫，raw 已收窄成 legacy 记录的形状，不需要再断言。
+    const { sessionId, ...rest } = raw;
+    return { ...rest, agentId: sessionId };
   }
   return null;
 }

package/src/vision-agent.ts

@@ -33,6 +33,7 @@ import {
 } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { Value } from "typebox/value";
 
 import { type ToolPendant } from "./lib/pendant.js";
 
@@ -83,6 +84,21 @@ export interface VisionConfigSettings {
   model?: string;
 }
 
+/**
+ * ~/.pi/agent/settings.json 里本扩展读取的字段：默认 provider 与视觉模型配置。
+ * 未声明的键（packages / defaultModel 等 pi 自己的配置）忽略；声明了的字段类型
+ * 不符则整份配置视为不可用，退回「未配置」而不是猜。
+ */
+const visionSettingsSchema = Type.Object({
+  defaultProvider: Type.Optional(Type.String()),
+  visionConfig: Type.Optional(
+    Type.Object({
+      provider: Type.Optional(Type.String()),
+      model: Type.Optional(Type.String()),
+    }),
+  ),
+});
+
 /**
  * 视觉识别所需的模型注册表操作：扩展传 ctx.modelRegistry，测试传 mock。
  * 结构化类型（duck typing），只声明用到的两个方法。
@@ -121,26 +137,21 @@ export function loadVisionConfig(settingsPath = SETTINGS_PATH): VisionConfigSett
   } catch {
     return undefined;
   }
+  let parsed: unknown;
   try {
-    const parsed: unknown = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
-    const settings = parsed as Record<string, unknown>;
-    const vc = settings.visionConfig;
-    if (!vc || typeof vc !== "object" || Array.isArray(vc)) return undefined;
-    const config = vc as Record<string, unknown>;
-    const provider =
-      typeof config.provider === "string" ? config.provider.trim() || undefined : undefined;
-    const defaultProvider =
-      typeof settings.defaultProvider === "string"
-        ? settings.defaultProvider.trim() || undefined
-        : undefined;
-    return {
-      provider: provider ?? defaultProvider,
-      model: typeof config.model === "string" ? config.model.trim() || undefined : undefined,
-    };
+    parsed = JSON.parse(raw);
   } catch {
     return undefined;
   }
+  if (!Value.Check(visionSettingsSchema, parsed)) return undefined;
+  const config = parsed.visionConfig;
+  if (config === undefined) return undefined;
+  const provider = config.provider?.trim() || undefined;
+  const defaultProvider = parsed.defaultProvider?.trim() || undefined;
+  return {
+    provider: provider ?? defaultProvider,
+    model: config.model?.trim() || undefined,
+  };
 }
 
 /**