@inobit/pi-instabox 0.0.0-stage → 0.1.0

package/src/resolve.ts

@@ -0,0 +1,216 @@
+/**
+ * @inobit/pi-instabox — 解析链纯函数：决定「这一次打到哪台 box」。
+ *
+ * 契约（方案 §4.3/§4.4、§5.1、T6）：
+ * - 5 级来源，顺序固定：`box` 参数 → 本轮最后一条 user 消息 → 会话目标 entry →
+ *   配置 `defaultBox` → `instabox ls` 第一台。先命中先返回，命中即停。
+ * - **不静默降级**：`box` 参数与会话目标写错是硬错误（`invalid-param` /
+ *   `invalid-session`），绝不退到下一级；消息里出现多个箱名是 `ambiguous`，不猜。
+ *   唯一允许降级的是配置里的 `defaultBox`：`onConfigMissing` 默认 `"skip"`（**默认降级**），
+ *   并在结果里带 `skippedConfig: true`；`"fail"` 时才返回 `invalid-config`。
+ * - 调用方义务（T14/T15 参照）：看到 `skippedConfig: true` 时按**每会话只 warn 一次**提示
+ *   「`config.defaultBox` 指向不存在的箱，已回落到 `ls` 第一台」，并继续按 `first` 执行；
+ *   本模块只负责把「配置没生效」标出来，不打印、不去重、不记忆会话。
+ * - 名字匹配是**精确 token**（前后不是字母/数字/`_`/`-`）且大小写敏感，不做子串匹配：
+ *   `agentic` / `agent-browser` / `Agent` 都不算 `agent`。
+ * - 只把 `boxes` 里存在的名字当作候选：消息里提到一个不存在的箱名等于没提（那种名字
+ *   本来也打不到），因此走下一级。
+ * - 纯函数：不 import pi 运行时、不调 CLI、不读文件、无时钟；`boxes` 的顺序是唯一语义。
+ *   埋点只经 `logEvent`（未配置 logger 时 no-op），不参与结果构造。
+ */
+
+import type { BoxInfo } from "./boxes.ts";
+import { logEvent } from "./log.ts";
+
+/** 埋点里候选名单的上限：`ls` 可能很长，日志只记前 N 个名字（箱数本身另由名单长度体现）。 */
+const LOG_CANDIDATE_LIMIT = 10;
+
+/** 命中来源，与解析链 5 级一一对应 */
+export type ResolveSource = "param" | "message" | "session" | "config" | "first";
+
+/** 解析失败原因（前 4 种是硬错误，`no-boxes` 是环境问题） */
+export type ResolveFailureKind = "no-boxes" | "invalid-param" | "invalid-session" | "ambiguous" | "invalid-config";
+
+/**
+ * 解析结果：成功带来源（供 `[box=…]` 回显与 `/instabox-status` 展示），
+ * 失败带可直接展示的 `message` 与 `candidates`（当前可用箱名，供提示与命令补全）。
+ */
+export type ResolveResult =
+	| {
+			ok: true;
+			box: string;
+			source: ResolveSource;
+			/** 仅在跳过不存在的配置 `defaultBox` 并回落到 `ls` 第一台时出现 */
+			skippedConfig?: true;
+	  }
+	| { ok: false; kind: ResolveFailureKind; message: string; candidates: string[] };
+
+/** 配置 `defaultBox` 指向不存在的箱时的处理：`skip` 降级到第一台（默认），`fail` 硬错误 */
+export type ConfigMissingPolicy = "fail" | "skip";
+
+/** `resolveBox` 的输入：所有来源都由调用方取好再传进来（本模块不碰宿主与 CLI） */
+export interface ResolveBoxInput {
+	/** 模型显式传的 `box` 参数（空串/纯空白视为未传） */
+	paramBox?: string;
+	/** 本轮最后一条 user 消息的纯文本（只用来找箱名提及） */
+	lastUserMessage?: string;
+	/** `readTarget(getBranch())` 的结果 */
+	sessionTarget?: string;
+	/** 配置里的 `defaultBox`（空串＝未配置） */
+	configDefaultBox?: string;
+	/** `instabox ls` 的结果（可能为空；只有顺序有意义） */
+	boxes: BoxInfo[];
+	/** 配置 `defaultBox` 不存在时的策略，默认 `"skip"` */
+	onConfigMissing?: ConfigMissingPolicy;
+}
+
+/**
+ * 5 级解析链：返回第一个命中的来源，或一个带候选的失败结果。
+ * 失败结果**不 throw**，由调用方决定转成工具 `isError` 结果还是命令提示。
+ */
+export function resolveBox(input: ResolveBoxInput): ResolveResult {
+	const names = boxNames(input.boxes);
+	const param = nonEmpty(input.paramBox);
+	// 提及名单提前算好（纯函数，下面第 2 级用的就是这一份）：零命中也要留下一条埋点
+	const mentions = findBoxMentions(input.lastUserMessage ?? "", names);
+
+	/**
+	 * 埋点出口：成功记 `resolve`（命中的箱、来源、提及、本次扫描的候选、是否降级），
+	 * 失败记 `resolve.fail`。只记名字，不记消息全文。
+	 * `resolve` 是 `info` 级（每次工具调用最多一条，量小）：默认级别下也要能事后分析选箱。
+	 */
+	const done = (result: ResolveResult): ResolveResult => {
+		if (result.ok) {
+			logEvent(
+				"resolve",
+				{
+					param,
+					source: result.source,
+					box: result.box,
+					mentions,
+					candidates: names.slice(0, LOG_CANDIDATE_LIMIT),
+					degraded: result.skippedConfig === true,
+				},
+				"info",
+			);
+		} else {
+			logEvent(
+				"resolve.fail",
+				{
+					kind: result.kind,
+					message: result.message,
+					candidates: result.candidates.slice(0, LOG_CANDIDATE_LIMIT),
+				},
+				"warn",
+			);
+		}
+		return result;
+	};
+
+	if (param !== undefined) {
+		if (names.includes(param)) return done({ ok: true, box: param, source: "param" });
+		return done(failure("invalid-param", `unknown box "${param}"`, names));
+	}
+
+	const mention = mentions.length === 1 ? mentions[0] : undefined;
+	if (mention !== undefined) return done({ ok: true, box: mention, source: "message" });
+	if (mentions.length > 1) {
+		return done(
+			failure("ambiguous", `the message mentions ${mentions.length} boxes (${mentions.join(", ")})`, mentions),
+		);
+	}
+
+	const session = nonEmpty(input.sessionTarget);
+	if (session !== undefined) {
+		if (names.includes(session)) return done({ ok: true, box: session, source: "session" });
+		return done(failure("invalid-session", `session target "${session}" is not an existing box`, names));
+	}
+
+	const config = nonEmpty(input.configDefaultBox);
+	let skippedConfig = false;
+	if (config !== undefined) {
+		if (names.includes(config)) return done({ ok: true, box: config, source: "config" });
+		if ((input.onConfigMissing ?? "skip") === "fail") {
+			return done(failure("invalid-config", `config defaultBox "${config}" is not an existing box`, names));
+		}
+		// 配置写错只降级、不硬失败；用 skippedConfig 让调用方仍能 warn 一次
+		skippedConfig = true;
+	}
+
+	// 取过滤后的名字（而非 `boxes[0]`）：`name: ""` 的条目在别处都被当无效，
+	// 这里也不能把空箱名当成命中的第一台。
+	const first = names[0];
+	if (first === undefined) return done(failure("no-boxes", "instabox ls returned no boxes", []));
+	if (skippedConfig) return done({ ok: true, box: first, source: "first", skippedConfig: true });
+	return done({ ok: true, box: first, source: "first" });
+}
+
+/**
+ * 在文本里找出所有**精确 token** 形式的箱名提及：去重、按首次出现位置排序。
+ * 大小写敏感；`agentic` / `agent-browser` / `Agent` 都不匹配 `agent`。
+ */
+export function findBoxMentions(text: string, names: string[]): string[] {
+	const hits: { name: string; at: number }[] = [];
+	for (const name of uniqueNames(names)) {
+		const at = firstTokenIndex(text, name);
+		if (at >= 0) hits.push({ name, at });
+	}
+	hits.sort((a, b) => a.at - b.at);
+	return hits.map((hit) => hit.name);
+}
+
+/**
+ * token 边界字符集：ASCII 字母、数字、`_`、`-`。
+ *
+ * 只把 ASCII 算作 token 内字符，因此中文/日文等直接相邻的写法（如 `用agent跑`）仍算
+ * 一次提及——instabox 箱名本身是 ASCII，CJK 贴着箱名写是正常表达而不是子串误判；
+ * 反过来，箱名被夹在非拉丁单词里（现实中不出现）会漏判，这个方向的误判是安全的。
+ */
+const TOKEN_CHAR = /[A-Za-z0-9_-]/;
+
+/** `name` 在 `text` 里作为独立 token 的首次出现位置；没有则 `-1` */
+function firstTokenIndex(text: string, name: string): number {
+	let from = 0;
+	while (from <= text.length) {
+		const at = text.indexOf(name, from);
+		if (at < 0) return -1;
+		if (isBoundary(text.charAt(at - 1)) && isBoundary(text.charAt(at + name.length))) return at;
+		from = at + 1;
+	}
+	return -1;
+}
+
+/** 空串（越界）或非 token 字符即边界 */
+function isBoundary(ch: string): boolean {
+	return !TOKEN_CHAR.test(ch);
+}
+
+/** `boxes` → 去重后的名字列表（保持 `ls` 顺序；空名忽略） */
+function boxNames(boxes: readonly BoxInfo[]): string[] {
+	return uniqueNames(boxes.map((box) => box.name));
+}
+
+/** 去重并丢掉空名，保持首次出现顺序 */
+function uniqueNames(names: readonly string[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const name of names) {
+		if (name === "" || seen.has(name)) continue;
+		seen.add(name);
+		out.push(name);
+	}
+	return out;
+}
+
+/** 归一化单值来源：`undefined` 表示「这一级没给值」（空串/纯空白等同未给） */
+function nonEmpty(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed === "" ? undefined : trimmed;
+}
+
+/** 构造失败结果：`message` 后统一附上候选，便于直接展示与给模型纠错 */
+function failure(kind: ResolveFailureKind, head: string, candidates: string[]): ResolveResult {
+	const tail = candidates.length > 0 ? `available boxes: ${candidates.join(", ")}` : "instabox ls returned no boxes";
+	return { ok: false, kind, message: `${head}; ${tail}`, candidates: [...candidates] };
+}

package/src/schema.ts

@@ -0,0 +1,370 @@
+/**
+ * @inobit/pi-instabox — 远端 `inputSchema` → TypeBox，并注入 `box` 目标参数（方案 §4.8 D8）。
+ *
+ * 保守子集转换：认识的形态用 `Type.*` 顶层工厂重建（模型看到的是可读 schema）；
+ * 其余（`$ref`/`allOf`/`not`/未知 `format`/白名单外的关键字/超深递归）把该节点**整体**交给
+ * `Type.Unsafe(raw)`——pi 的工具参数按 JSON Schema 校验，原样透传仍然可校验，只是不美化。
+ * 只用 `Type.*` 顶层工厂（typebox 1.3.x 稳定面），不用 `typebox/compile`、`typebox/value`。
+ *
+ * 两条方案未覆盖处的选择：
+ * - 非法输入（`null`/数组/标量）→ `Type.Any()`：没有可保留的 raw，用 typebox 原生的「任意值」，
+ *   不用 `Type.Unsafe({})`（那会假装存在一份 raw schema）。
+ * - `injectBoxParam` 只认顶层像 object 的 schema（`type: "object"` 或带 `properties`）；否则
+ *   不注入、只回 warning —— 与「远端自带 `box`」走同一降级（解析链退到 2–5 级），
+ *   绝不改动远端 schema 的形状（凭空挂一个参数名会让调用语义变味）。
+ */
+
+import {
+	Type,
+	type TArrayOptions,
+	type TNumberOptions,
+	type TObjectOptions,
+	type TSchema,
+	type TSchemaOptions,
+	type TStringOptions,
+} from "typebox";
+
+type JsonRecord = Record<string, unknown>;
+
+/**
+ * 递归深度上限（层数，不是最大下标）：`depth` 为 0-based 层号，`depth >= MAX_SCHEMA_DEPTH`
+ * 的节点整体交给 `Type.Unsafe` —— 至多 `MAX_SCHEMA_DEPTH` 层（depth `0..MAX_SCHEMA_DEPTH-1`）
+ * 被转换（方案 §4.8 ③）。
+ */
+export const MAX_SCHEMA_DEPTH = 8;
+
+/** 注入的 `box` 参数文案：一次调用指定目标箱，缺省走会话目标，失败不静默换箱。 */
+export const BOX_PARAM_DESCRIPTION =
+	"Target instabox box for this call. Omit to use the session's target box. A failure is reported; it never falls back to another box silently.";
+
+/** 远端 schema 已自带 `box` → 不注入（方案 §4.8 ④：解析链退到 2–5 级，由调用方记一次 warning）。 */
+const BOX_CONFLICT_WARNING =
+	"remote inputSchema already declares a `box` property, so the instabox `box` parameter was not injected; per-call box targeting is unavailable for this tool";
+
+/** 顶层不是 object schema → `box` 无处安放，同一降级。 */
+const NON_OBJECT_SCHEMA_WARNING =
+	"remote inputSchema is not an object schema, so the instabox `box` parameter was not injected; per-call box targeting is unavailable for this tool";
+
+/** 每个 kind 允许出现且会被转换的关键字；白名单外的键 → 整节点回落，不静默丢校验语义。 */
+const KEYWORDS_BY_KIND = {
+	object: ["type", "properties", "required", "additionalProperties"],
+	array: ["type", "items", "minItems", "maxItems"],
+	string: ["type", "format", "minLength", "maxLength", "pattern"],
+	number: ["type", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"],
+	integer: ["type", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"],
+	boolean: ["type"],
+	null: ["type"],
+	enum: ["type", "enum"],
+	union: ["anyOf", "oneOf"],
+	any: [],
+} as const;
+
+type Kind = keyof typeof KEYWORDS_BY_KIND;
+
+/** 任何 kind 都允许的键：注释类关键字（透传给模型）+ OpenAPI 的 `nullable`（转成 `Union([T, Null])`）。 */
+const SHARED_KEYS: readonly string[] = [
+	"title",
+	"description",
+	"default",
+	"examples",
+	"readOnly",
+	"writeOnly",
+	"nullable",
+];
+
+/** 标准 `format` 白名单（JSON Schema 标准集）；白名单外一律回落（方案 §4.8 ②）。 */
+const STANDARD_FORMATS: ReadonlySet<string> = new Set([
+	"date-time",
+	"date",
+	"time",
+	"duration",
+	"email",
+	"idn-email",
+	"hostname",
+	"idn-hostname",
+	"ipv4",
+	"ipv6",
+	"uri",
+	"uri-reference",
+	"uri-template",
+	"iri",
+	"iri-reference",
+	"uuid",
+	"json-pointer",
+	"relative-json-pointer",
+	"regex",
+]);
+
+function isRecord(value: unknown): value is JsonRecord {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** `TSchema` 是 typebox 的空接口（运行时就是 JSON Schema 对象）；读/改顶层关键字前转成键值视图。 */
+function jsonView(schema: TSchema): JsonRecord {
+	return schema as JsonRecord;
+}
+
+/** 键序稳定（方案 §4.8 ⑤）：按名字码位序重排，输出与远端 key 顺序无关。 */
+function sortByKey<T>(source: Record<string, T>): Record<string, T> {
+	return Object.fromEntries(
+		Object.entries(source).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),
+	);
+}
+
+function numberOrUndefined(value: unknown): number | undefined {
+	return typeof value === "number" ? value : undefined;
+}
+
+/** 注释类关键字按固定顺序重建，保证键序稳定。 */
+function annotationsOf(node: JsonRecord): TSchemaOptions {
+	const options: TSchemaOptions = {};
+	const title = node["title"];
+	if (typeof title === "string") options.title = title;
+	const description = node["description"];
+	if (typeof description === "string") options.description = description;
+	const defaultValue = node["default"];
+	if (defaultValue !== undefined) options.default = defaultValue;
+	const examples = node["examples"];
+	if (Array.isArray(examples)) options.examples = examples;
+	if (node["readOnly"] === true) options.readOnly = true;
+	if (node["writeOnly"] === true) options.writeOnly = true;
+	return options;
+}
+
+/** 整节点回落：原样透传给 pi 的 JSON Schema 校验器（方案 §4.8 ②）。 */
+function unsafeCopy(node: JsonRecord): TSchema {
+	return Type.Unsafe<Record<string, unknown>>(node);
+}
+
+/** 标量 → `Type.Literal`／`Type.Null`；对象、数组、大整数等用 `Literal` 表达不了。 */
+function scalarVariant(value: unknown, options: TSchemaOptions): TSchema | undefined {
+	if (value === null) return Type.Null(options);
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+		return Type.Literal(value, options);
+	}
+	return undefined;
+}
+
+function resolveKind(node: JsonRecord): Kind | undefined {
+	if (Array.isArray(node["enum"])) return "enum";
+	const anyOf = node["anyOf"];
+	const oneOf = node["oneOf"];
+	if (anyOf !== undefined || oneOf !== undefined) {
+		// 两种分支语义不同（`oneOf` 要求恰好命中一个），同时出现无法用一个 `Union` 表达
+		return anyOf !== undefined && oneOf !== undefined ? undefined : "union";
+	}
+	const type = node["type"];
+	if (
+		type === "object" ||
+		type === "array" ||
+		type === "string" ||
+		type === "number" ||
+		type === "integer" ||
+		type === "boolean" ||
+		type === "null"
+	) {
+		return type;
+	}
+	// 数组型 `type`（`["string", "null"]`）与未知/非字符串 `type` 都不在子集里
+	if (type !== undefined) return undefined;
+	if (isRecord(node["properties"])) return "object";
+	if (node["items"] !== undefined) return "array";
+	return "any";
+}
+
+function hasOnlySupportedKeywords(node: JsonRecord, kind: Kind): boolean {
+	const allowed = new Set<string>([...SHARED_KEYS, ...KEYWORDS_BY_KIND[kind]]);
+	return Object.keys(node).every((key) => allowed.has(key));
+}
+
+function readRequired(node: JsonRecord): readonly string[] | undefined {
+	const required = node["required"];
+	if (required === undefined) return [];
+	if (Array.isArray(required) && required.every((name): name is string => typeof name === "string")) {
+		return required;
+	}
+	return undefined;
+}
+
+function buildObject(node: JsonRecord, depth: number): TSchema {
+	const required = readRequired(node);
+	if (required === undefined) return unsafeCopy(node);
+	const requiredNames = new Set(required);
+	const rawProperties = node["properties"];
+	// `required` 由 properties 的 `~optional` 标记派生，所以可选性在这里落；
+	// 用 `Object.fromEntries` 而不是逐键赋值，属性名不经过 `__proto__` 之类的 setter。
+	const converted: [string, TSchema][] = [];
+	if (rawProperties !== undefined) {
+		if (!isRecord(rawProperties)) return unsafeCopy(node);
+		for (const [name, property] of Object.entries(sortByKey(rawProperties))) {
+			const schema = toTypeBox(property, depth + 1);
+			converted.push([name, requiredNames.has(name) ? schema : Type.Optional(schema)]);
+		}
+	}
+	// `required` 指向一个没有 properties 条目的名字：`Type.Optional` 表达不了，整节点回落
+	if ([...requiredNames].some((name) => !converted.some(([key]) => key === name))) return unsafeCopy(node);
+	const properties = Object.fromEntries(converted);
+	const options: TObjectOptions = { ...annotationsOf(node) };
+	const additional = node["additionalProperties"];
+	if (additional === false || additional === true) options.additionalProperties = additional;
+	else if (isRecord(additional)) options.additionalProperties = toTypeBox(additional, depth + 1);
+	else if (additional !== undefined) return unsafeCopy(node);
+	return Type.Object(properties, options);
+}
+
+function buildArray(node: JsonRecord, depth: number): TSchema {
+	const items = node["items"];
+	let element: TSchema;
+	if (items === undefined) element = Type.Any();
+	else if (isRecord(items)) element = toTypeBox(items, depth + 1);
+	else return unsafeCopy(node); // 元组型 `items: [...]` 不在子集里
+	const options: TArrayOptions = { ...annotationsOf(node) };
+	const minItems = numberOrUndefined(node["minItems"]);
+	if (minItems !== undefined) options.minItems = minItems;
+	const maxItems = numberOrUndefined(node["maxItems"]);
+	if (maxItems !== undefined) options.maxItems = maxItems;
+	return Type.Array(element, options);
+}
+
+function buildString(node: JsonRecord): TSchema {
+	const options: TStringOptions = { ...annotationsOf(node) };
+	const format = node["format"];
+	if (typeof format === "string") {
+		if (!STANDARD_FORMATS.has(format)) return unsafeCopy(node);
+		options.format = format;
+	}
+	const minLength = numberOrUndefined(node["minLength"]);
+	if (minLength !== undefined) options.minLength = minLength;
+	const maxLength = numberOrUndefined(node["maxLength"]);
+	if (maxLength !== undefined) options.maxLength = maxLength;
+	const pattern = node["pattern"];
+	if (typeof pattern === "string") options.pattern = pattern;
+	return Type.String(options);
+}
+
+function numericOptions(node: JsonRecord): TNumberOptions {
+	const options: TNumberOptions = { ...annotationsOf(node) };
+	const minimum = numberOrUndefined(node["minimum"]);
+	if (minimum !== undefined) options.minimum = minimum;
+	const maximum = numberOrUndefined(node["maximum"]);
+	if (maximum !== undefined) options.maximum = maximum;
+	const exclusiveMinimum = numberOrUndefined(node["exclusiveMinimum"]);
+	if (exclusiveMinimum !== undefined) options.exclusiveMinimum = exclusiveMinimum;
+	const exclusiveMaximum = numberOrUndefined(node["exclusiveMaximum"]);
+	if (exclusiveMaximum !== undefined) options.exclusiveMaximum = exclusiveMaximum;
+	const multipleOf = numberOrUndefined(node["multipleOf"]);
+	if (multipleOf !== undefined) options.multipleOf = multipleOf;
+	return options;
+}
+
+function buildEnum(node: JsonRecord): TSchema {
+	const values = node["enum"];
+	if (!Array.isArray(values) || values.length === 0) return unsafeCopy(node);
+	const options = annotationsOf(node);
+	// 单值 `enum` → `Type.Literal`（注释挂在该节点上）；多值 → `Union`（注释挂在 union 上）
+	const single = values.length === 1;
+	const variants: TSchema[] = [];
+	for (const value of values) {
+		const variant = scalarVariant(value, single ? options : {});
+		if (variant === undefined) return unsafeCopy(node);
+		variants.push(variant);
+	}
+	const [only] = variants;
+	if (only !== undefined && variants.length === 1) return only;
+	return Type.Union(variants, options);
+}
+
+function buildUnion(node: JsonRecord, depth: number): TSchema {
+	const branches = node["anyOf"] ?? node["oneOf"];
+	if (!Array.isArray(branches) || branches.length === 0) return unsafeCopy(node);
+	const variants = branches.map((branch) => toTypeBox(branch, depth + 1));
+	return Type.Union(variants, annotationsOf(node));
+}
+
+function buildBase(node: JsonRecord, kind: Kind, depth: number): TSchema {
+	switch (kind) {
+		case "object":
+			return buildObject(node, depth);
+		case "array":
+			return buildArray(node, depth);
+		case "string":
+			return buildString(node);
+		case "number":
+			return Type.Number(numericOptions(node));
+		case "integer":
+			return Type.Integer(numericOptions(node));
+		case "boolean":
+			return Type.Boolean(annotationsOf(node));
+		case "null":
+			return Type.Null(annotationsOf(node));
+		case "enum":
+			return buildEnum(node);
+		case "union":
+			return buildUnion(node, depth);
+		case "any":
+			return Type.Any(annotationsOf(node));
+	}
+}
+
+/** 一个 JSON Schema 节点 → TypeBox（`depth` 为当前递归深度，顶层为 0）。 */
+function toTypeBox(node: unknown, depth: number): TSchema {
+	if (!isRecord(node)) return Type.Any();
+	// 深度上限只截断递归本身：该层整节点原样透传，校验语义不丢（方案 §4.8 ③）
+	if (depth >= MAX_SCHEMA_DEPTH) return unsafeCopy(node);
+	const kind = resolveKind(node);
+	if (kind === undefined) return unsafeCopy(node);
+	if (!hasOnlySupportedKeywords(node, kind)) return unsafeCopy(node);
+	const base = buildBase(node, kind, depth);
+	return node["nullable"] === true ? Type.Union([base, Type.Null()], annotationsOf(node)) : base;
+}
+
+/**
+ * 远端 `inputSchema` → TypeBox。不 throw：非法输入 → `Type.Any()`，不支持的节点 → `Type.Unsafe(raw)`。
+ *
+ * `depth` 只给递归内部用；外部调用保持默认 0。
+ */
+export function jsonSchemaToTypeBox(schema: unknown, depth = 0): TSchema {
+	return toTypeBox(schema, depth);
+}
+
+export interface InjectBoxParamOptions {
+	/** 覆盖 `box` 参数文案（默认 `BOX_PARAM_DESCRIPTION`）。 */
+	description?: string;
+}
+
+export interface InjectBoxParamResult {
+	schema: TSchema;
+	injected: boolean;
+	warning?: string;
+}
+
+/**
+ * 在**顶层 `properties`** 加一个可选 `box` 参数（方案 §4.8 ④）。
+ *
+ * - 只改顶层：返回值是替换了顶层 `properties` 的 JSON Schema 对象，其它顶层关键字
+ *   （含 Unsafe 回落带过来的 `allOf` 等）原样保留。
+ * - 返回值是**纯 JSON Schema 视图**（`{ ...node, properties }`）：对象展开只复制可枚举键，
+ *   typebox 的 `~kind`/`~unsafe` 反射标记是非枚举属性，注入后不保留。pi 按 JSON Schema
+ *   校验工具参数，运行时无影响；要判断某节点是否为 Unsafe 回落，用**注入前**的对象统计。
+ * - 不进 `required`：`box` 是可选参数，缺省走会话目标。
+ * - 远端已有 `box`（属性或 `required` 里的名字）→ 不注入、原样返回并给 warning。
+ * - 顶层不是 object schema → 同样不注入、原样返回并给 warning。
+ */
+export function injectBoxParam(schema: TSchema, opts: InjectBoxParamOptions = {}): InjectBoxParamResult {
+	const node = jsonView(schema);
+	const rawProperties = node["properties"];
+	if (node["type"] !== "object" && !isRecord(rawProperties)) {
+		return { schema, injected: false, warning: NON_OBJECT_SCHEMA_WARNING };
+	}
+	const existing: JsonRecord = isRecord(rawProperties) ? rawProperties : {};
+	const required = readRequired(node) ?? [];
+	if ("box" in existing || required.includes("box")) {
+		return { schema, injected: false, warning: BOX_CONFLICT_WARNING };
+	}
+	const description = opts.description ?? BOX_PARAM_DESCRIPTION;
+	const properties = sortByKey({
+		...existing,
+		box: Type.Optional(Type.String({ description })),
+	});
+	return { schema: { ...node, properties }, injected: true };
+}

package/src/session-target.ts

@@ -0,0 +1,100 @@
+/**
+ * @inobit/pi-instabox — 会话级目标 entry 的读写（纯函数，不 import pi 运行时类型）。
+ *
+ * 两处会话级目标都用 CustomEntry 存（不进 LLM 上下文，重载会话后从会话条目重建）：
+ * - {@link TARGET_ENTRY}：桌面工具的当前目标箱，由 `/instabox-use <box>` 写入；
+ * - {@link DEVTOOLS_TARGET_ENTRY}：DevTools MCP 的会话绑定箱，由 `/instabox-devtools on <box>` 写入。
+ *
+ * 唯一合法的读取来源是 `ctx.sessionManager.getBranch()`：`getEntries()` 会带上被
+ * `/tree` 放弃的分支，读到那里的目标会把「切分支后目标回到未设置」这条承诺破掉。
+ * 因此本模块只接受调用方传入的分支条目，不自己碰会话管理器。
+ */
+
+/** 目标 entry 的 customType，写入与识别的唯一依据 */
+export const TARGET_ENTRY = "instabox-target";
+
+/** 目标 entry 的 data 形状（`at` 为写入时刻的 ISO 时间串，仅供排查） */
+export interface TargetEntryData {
+	box: string;
+	at: string;
+}
+
+/** DevTools 会话绑定 entry 的 customType，写入与识别的唯一依据 */
+export const DEVTOOLS_TARGET_ENTRY = "instabox-devtools-target";
+
+/**
+ * DevTools 绑定 entry 的 data 形状。
+ *
+ * `reset: true` 是一条**清除标记**（`box` 恒为空串）：它只终止向后扫描，让更早的绑定失效，
+ * 但不清除任何已注册的 MCP server——开关状态与注册都归装配层管，entry 只表达「box 绑到哪台」。
+ */
+export interface DevtoolsTargetEntryData {
+	box: string;
+	at: string;
+	reset?: true;
+}
+
+/** 会话条目的最小形态：只声明本模块用到的字段 */
+export interface SessionEntryLike {
+	type: string;
+	customType?: string;
+	data?: unknown;
+}
+
+/** 是否为某个 customType 的 custom entry（仅认 type=custom + customType，不做其它推断） */
+function isEntryOf(entry: unknown, customType: string): boolean {
+	const e = entry as SessionEntryLike | null | undefined;
+	return typeof e === "object" && e !== null && e.type === "custom" && e.customType === customType;
+}
+
+/** 是否为本次目标 entry（仅认 type=custom + customType） */
+export function isTargetEntry(entry: unknown): boolean {
+	return isEntryOf(entry, TARGET_ENTRY);
+}
+
+/** 构造 entry data；`at` 缺省取当前时刻，测试可显式传入以获得确定性 */
+export function targetEntryData(box: string, at?: string): TargetEntryData {
+	return { box, at: at ?? new Date().toISOString() };
+}
+
+/**
+ * 构造 DevTools 绑定 entry data：`box` 为空串且 `reset: true` 时是清除标记。
+ * `at` 缺省取当前时刻，测试可显式传入以获得确定性。
+ */
+export function devtoolsTargetEntryData(box: string, at?: string): DevtoolsTargetEntryData {
+	const data: DevtoolsTargetEntryData = { box, at: at ?? new Date().toISOString() };
+	if (box === "") data.reset = true;
+	return data;
+}
+
+/**
+ * 从分支条目末尾向前扫，返回最近一次写入的目标箱名；无目标 entry 时返回 undefined。
+ * `entries` 必须是 `getBranch()` 的结果（调用方负责），被放弃分支上的旧目标读不到。
+ */
+export function readTarget(entries: readonly SessionEntryLike[]): string | undefined {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (!isTargetEntry(entry)) continue;
+		const box = (entry?.data as Partial<TargetEntryData> | undefined)?.box;
+		if (typeof box === "string" && box.length > 0) return box;
+	}
+	return undefined;
+}
+
+/**
+ * 从分支条目末尾向前扫，返回最近一次的 DevTools 绑定箱名。
+ *
+ * `reset: true` 的清除标记**终止**扫描并返回 undefined：它之后的绑定才算数，更早的绑定已失效。
+ * 无绑定（或最近一条是清除标记）时返回 undefined，调用方据此回退到 flag / config。
+ */
+export function readDevtoolsTarget(entries: readonly SessionEntryLike[]): string | undefined {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (!isEntryOf(entry, DEVTOOLS_TARGET_ENTRY)) continue;
+		const data = entry?.data as Partial<DevtoolsTargetEntryData> | undefined;
+		if (data?.reset === true) return undefined;
+		const box = data?.box;
+		if (typeof box === "string" && box.length > 0) return box;
+	}
+	return undefined;
+}