@selesai/code 0.13.14 → 0.13.16

package/dist/extensions/capability-gateway/index.ts

@@ -0,0 +1,329 @@
+/**
+ * Progressive capability gateway (experimental, opt-in).
+ *
+ * Issue #1: keep the full tool/skill ecosystem reachable without paying to
+ * expose every extension-tool schema and skill description on every request.
+ *
+ * Behavior:
+ * - On by default; disable via SELESAI_CAPABILITY_GATEWAY=0.
+ * - At session start, extension tools (except the gateway's own tools) become
+ *   dormant: they stay registered but are removed from the active tool set.
+ *   Built-in tools are never touched.
+ * - A compact catalog tool lists eligible tools/skills with one-line summaries.
+ * - capability_discover validates one catalogued tool and activates its native
+ *   definition for the current agent run; capability_skill_show loads exactly
+ *   the selected skill instructions.
+ * - A deterministic router inspects each user prompt and, for a unique
+ *   high-confidence tool match, activates it before the run; for a unique
+ *   high-confidence skill match it adds a concise recommendation; ambiguous
+ *   matches add a catalog hint; unrelated prompts are untouched.
+ * - Temporary activations reset at agent_settled, restoring the baseline
+ *   active-tool set.
+ * - The system-prompt skill index is replaced by a compact capability
+ *   instruction; full skill instructions load only on explicit show/invoke.
+ * - Telemetry events are emitted on the shared event bus.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stripFrontmatter, type ExtensionAPI, type ToolInfo } from "@selesai/code";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import {
+	buildSkillCatalog,
+	buildToolCatalog,
+	BUILTIN_TOOL_NAMES,
+	route,
+	type CatalogEntry,
+} from "./catalog.ts";
+
+export const GATEWAY_ENV = "SELESAI_CAPABILITY_GATEWAY";
+export const GATEWAY_TOOLS = new Set(["capability_catalog", "capability_discover", "capability_skill_show"]);
+
+export const CAPABILITY_INSTRUCTION = `Optional capabilities (extension tools and skills) are not listed here by default. To use one:
+- Search the compact catalog with capability_catalog (kind: "tool" or "skill", natural-language query) when no active tool fits or a specialized integration/workflow is requested.
+- Activate a catalogued tool with capability_discover, then call it normally on the next turn.
+- Load a skill's full instructions with capability_skill_show before applying it.
+Never invent optional tool names, actions, or fields; discover them first.`;
+
+function isEnabled(): boolean {
+	return process.env[GATEWAY_ENV] !== "0";
+}
+
+function eligibleTools(pi: ExtensionAPI): ToolInfo[] {
+	return pi
+		.getAllTools()
+		.filter((tool) => !GATEWAY_TOOLS.has(tool.name) && !BUILTIN_TOOL_NAMES.has(tool.name));
+}
+
+function catalogEntries(pi: ExtensionAPI): CatalogEntry[] {
+	const tools = buildToolCatalog(eligibleTools(pi), GATEWAY_TOOLS);
+	const skills = buildSkillCatalog(pi.getResolvedSkills());
+	return [...tools, ...skills];
+}
+
+const EMBEDDED_SKILL_BLOCK = /<skill\s+name="([^"]+)"[^>]*>[\s\S]*?<\/skill>/gi;
+
+function routePrompt(prompt: string, entries: CatalogEntry[]): ReturnType<typeof route> {
+	const loadedSkills = new Set([...prompt.matchAll(EMBEDDED_SKILL_BLOCK)].map((match) => match[1]!.toLowerCase()));
+	const query = prompt.replace(EMBEDDED_SKILL_BLOCK, " ");
+	return route(
+		query,
+		entries.filter((entry) => entry.kind !== "skill" || !loadedSkills.has(entry.name.toLowerCase())),
+	);
+}
+
+function formatCatalog(entries: CatalogEntry[]): string {
+	const lines = entries.map(
+		(entry) =>
+			`- ${entry.kind} ${entry.name}${entry.category ? ` [${entry.category}]` : ""}: ${entry.summary}`,
+	);
+	return lines.length > 0 ? lines.join("\n") : "(no matching capabilities)";
+}
+
+function findEntry(entries: CatalogEntry[], name: string): CatalogEntry | undefined {
+	const normalized = name.trim().toLowerCase();
+	return entries.find(
+		(entry) => entry.name.toLowerCase() === normalized || entry.aliases.some((alias) => alias.toLowerCase() === normalized),
+	);
+}
+
+function skillByFile(pi: ExtensionAPI, filePath: string): { name: string; body: string } | undefined {
+	const skill = pi.getResolvedSkills().find((s) => s.filePath === filePath);
+	if (!skill) return undefined;
+	try {
+		const body = stripFrontmatter(readFileSync(skill.filePath, "utf-8")).trim();
+		return { name: skill.name, body };
+	} catch {
+		return undefined;
+	}
+}
+
+function emitTelemetry(pi: ExtensionAPI, event: string, data: Record<string, unknown>): void {
+	try {
+		pi.events.emit("capability-gateway", { event, ...data });
+	} catch {
+		// Telemetry must never break the session.
+	}
+}
+
+export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
+	if (!isEnabled()) return;
+
+	// ------------------------------------------------------------------
+	// Session start: snapshot baseline, make extension tools dormant, and
+	// install the compact skill index (action methods are stubs until bind).
+	// ------------------------------------------------------------------
+	pi.on("session_start", (_event, ctx) => {
+		const baseline = pi.getActiveTools();
+		const keep = baseline.filter(
+			(name) => !eligibleTools(pi).some((tool) => tool.name === name),
+		);
+		pi.setActiveTools(keep);
+		// Replace the eager skill index with a single compact capability
+		// instruction entry. Full skill instructions load only on show/invoke.
+		pi.setSkillsIndexFilter(() => [
+			{
+				name: "capability-gateway",
+				description: CAPABILITY_INSTRUCTION,
+				filePath: "<capability-gateway>",
+				baseDir: "<capability-gateway>",
+				sourceInfo: { path: "<capability-gateway>", source: "builtin", scope: "user", origin: "top-level" },
+				disableModelInvocation: false,
+			},
+		]);
+		emitTelemetry(pi, "session_start", { baselineCount: baseline.length, dormantCount: baseline.length - keep.length });
+		void ctx;
+	});
+
+	// ------------------------------------------------------------------
+	// Tools
+	// ------------------------------------------------------------------
+	pi.registerTool({
+		name: "capability_catalog",
+		label: "Capability Catalog",
+		description:
+			"Search the compact capability catalog for optional extension tools and skills. Returns name, kind (tool or skill), category, and a one-line purpose for each match. Use when no active tool fits or a specialized integration/workflow is requested.",
+		promptSnippet: "Search the compact catalog of optional tools and skills",
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ minLength: 1, description: "Natural-language query; omit to list all." })),
+			kind: Type.Optional(StringEnum(["tool", "skill"] as const, { description: "Filter by capability kind." })),
+		}),
+		async execute(_id, params) {
+			const entries = catalogEntries(pi);
+			const filtered = entries.filter(
+				(entry) => !params.kind || entry.kind === params.kind,
+			);
+			const matched = params.query ? route(params.query, filtered) : { action: "none" as const };
+			const shown =
+				params.query && matched.candidates
+					? matched.candidates
+					: params.query
+						? filtered.filter((entry) => {
+								const q = params.query!.toLowerCase();
+								return (
+									entry.name.toLowerCase().includes(q) ||
+									entry.summary.toLowerCase().includes(q) ||
+									entry.aliases.some((alias) => alias.toLowerCase().includes(q))
+								);
+							})
+						: filtered;
+			const text = formatCatalog(shown);
+			emitTelemetry(pi, "catalog", { query: params.query ?? "", kind: params.kind ?? "", results: shown.length });
+			return {
+				content: [{ type: "text", text }],
+				details: { count: shown.length, total: filtered.length },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "capability_discover",
+		label: "Capability Discover",
+		description:
+			"Activate one catalogued extension tool for the current agent run. The tool's real schema and validation contract become available on the next model turn; it is removed again when the run ends. Use the exact name from capability_catalog.",
+		promptSnippet: "Activate a catalogued extension tool for the current run",
+		parameters: Type.Object({
+			name: Type.String({ minLength: 1, description: "Exact catalogued tool name." }),
+		}),
+		async execute(_id, params) {
+			const entries = catalogEntries(pi);
+			const entry = findEntry(entries, params.name);
+			if (!entry || entry.kind !== "tool") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown tool "${params.name}". Search capability_catalog for the exact name, or refine your query.`,
+						},
+					],
+					details: { activated: false },
+				};
+			}
+			const active = pi.getActiveTools();
+			if (!active.includes(entry.name)) {
+				pi.setActiveTools([...active, entry.name]);
+			}
+			emitTelemetry(pi, "discover", { tool: entry.name });
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Activated "${entry.name}" for this run. Call it normally on the next turn; it is removed when the run ends.`,
+					},
+				],
+				details: { activated: true, tool: entry.name },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "capability_skill_show",
+		label: "Capability Skill Show",
+		description:
+			"Load the complete instructions for one skill from the resolved skill catalog. Use the exact skill name from capability_catalog. This is the explicit boundary that loads full SKILL.md content.",
+		promptSnippet: "Load a skill's full instructions by name",
+		parameters: Type.Object({
+			name: Type.String({ minLength: 1, description: "Exact skill name." }),
+		}),
+		async execute(_id, params) {
+			const skill = pi.getResolvedSkills().find((s) => s.name === params.name);
+			if (!skill) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown skill "${params.name}". Search capability_catalog (kind: "skill") for the exact name.`,
+						},
+					],
+					details: { loaded: false },
+				};
+			}
+			const loaded = skillByFile(pi, skill.filePath);
+			if (!loaded) {
+				return {
+					content: [{ type: "text", text: `Skill "${params.name}" exists but its file could not be read.` }],
+					details: { loaded: false },
+				};
+			}
+			emitTelemetry(pi, "skill_show", { skill: loaded.name });
+			return {
+				content: [
+					{
+						type: "text",
+						text: `<skill name="${loaded.name}" location="${skill.filePath}">\nThe full instructions for this skill are embedded inline below; do not read its file again.\nReferences are relative to ${dirname(skill.filePath)}.\n\n${loaded.body}\n</skill>`,
+					},
+				],
+				details: { loaded: true, skill: loaded.name },
+			};
+		},
+	});
+
+	// ------------------------------------------------------------------
+	// Deterministic routing: high-confidence activation/recommendation,
+	// ambiguity hints, or nothing for unrelated prompts.
+	// ------------------------------------------------------------------
+	pi.on("before_agent_start", (event) => {
+		const result = routePrompt(event.prompt, catalogEntries(pi));
+		if (result.action === "none") return undefined;
+		if (result.action === "activate" && result.entry) {
+			const active = pi.getActiveTools();
+			if (!active.includes(result.entry.name)) {
+				pi.setActiveTools([...active, result.entry.name]);
+			}
+			emitTelemetry(pi, "route_activate", { tool: result.entry.name });
+			return undefined;
+		}
+		if (result.action === "recommend" && result.entry) {
+			emitTelemetry(pi, "route_recommend", { skill: result.entry.name });
+			return {
+				message: {
+					customType: "capability-gateway-hint",
+					content: `The request matches the optional skill "${result.entry.name}". Load it with capability_skill_show before applying it.`,
+					display: false,
+				},
+			};
+		}
+		if (result.action === "hint" && result.candidates) {
+			const names = result.candidates.map((c) => c.name).join(", ");
+			emitTelemetry(pi, "route_hint", { candidates: result.candidates.map((c) => c.name) });
+			return {
+				message: {
+					customType: "capability-gateway-hint",
+					content: `The request may match optional capabilities: ${names}. Search capability_catalog to confirm before selecting.`,
+					display: false,
+				},
+			};
+		}
+		return undefined;
+	});
+
+	// ------------------------------------------------------------------
+	// Reset: restore the baseline active-tool set after the run settles.
+	// ------------------------------------------------------------------
+	pi.on("agent_settled", () => {
+		const baseline = pi.getActiveTools().filter((name) => !eligibleTools(pi).some((tool) => tool.name === name));
+		pi.setActiveTools(baseline);
+		emitTelemetry(pi, "reset", { activeCount: baseline.length });
+	});
+
+	// ------------------------------------------------------------------
+	// Command: /capability-gateway status
+	// ------------------------------------------------------------------
+	pi.registerCommand("capability-gateway", {
+		description: "Show capability gateway status and catalog counts.",
+		async handler(_args, ctx) {
+			const tools = buildToolCatalog(eligibleTools(pi), GATEWAY_TOOLS);
+			const skills = buildSkillCatalog(pi.getResolvedSkills());
+			const active = pi.getActiveTools();
+			const dormant = tools.filter((t) => !active.includes(t.name)).length;
+			const text = [
+				`Capability gateway: enabled`,
+				`catalogued tools: ${tools.length} (${dormant} dormant)`,
+				`catalogued skills: ${skills.length}`,
+				`active tools: ${active.join(", ") || "(none)"}`,
+			].join("\n");
+			ctx.ui.notify(text);
+		},
+	});
+}

package/dist/extensions/capability-gateway/integration.test.ts

@@ -0,0 +1,238 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { fauxProvider } from "@earendil-works/pi-ai/providers/faux";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	ModelRuntime,
+	SessionManager,
+	SettingsManager,
+	type AgentSession,
+} from "@selesai/code";
+
+const EXTENSIONS_DIR = fileURLToPath(new URL("../../", import.meta.url));
+const GATEWAY_DIR = fileURLToPath(new URL(".", import.meta.url));
+const GREP_APP_DIR = fileURLToPath(new URL("../grep-app", import.meta.url));
+const INLINE_SKILLS_FILE = fileURLToPath(new URL("../inline-skills.ts", import.meta.url));
+
+interface Harness {
+	session: AgentSession;
+	dispose: () => Promise<void>;
+}
+
+async function createGatewaySession(options: {
+	enabled: boolean;
+	withSkill?: boolean;
+	extensions?: string[];
+}): Promise<Harness> {
+	const extensionPaths = options.extensions ?? [EXTENSIONS_DIR];
+	const cwd = mkdtempSync(join(tmpdir(), "gw-cwd-"));
+	const home = mkdtempSync(join(tmpdir(), "gw-home-"));
+	const previousCwd = process.cwd();
+	const previousHome = process.env.HOME;
+	const previousUserProfile = process.env.USERPROFILE;
+	const previousAgentDir = process.env.SELESAI_CODING_AGENT_DIR;
+	const previousGateway = process.env.SELESAI_CAPABILITY_GATEWAY;
+
+	process.chdir(cwd);
+	process.env.HOME = home;
+	process.env.USERPROFILE = home;
+	process.env.SELESAI_CODING_AGENT_DIR = home;
+	if (options.enabled) delete process.env.SELESAI_CAPABILITY_GATEWAY;
+	else process.env.SELESAI_CAPABILITY_GATEWAY = "0";
+
+	if (options.withSkill) {
+		mkdirSync(join(home, "skills", "research"), { recursive: true });
+		writeFileSync(
+			join(home, "skills", "research", "SKILL.md"),
+			"---\nname: research\ndescription: Investigate a question against high-trust primary sources.\n---\nResearch instructions body.\n",
+		);
+	}
+
+	const faux = fauxProvider({ provider: "faux-gw", models: [{ id: "gw", contextWindow: 200_000 }] });
+	const modelRuntime = await ModelRuntime.create({
+		authPath: join(home, "auth.json"),
+		modelsPath: null,
+		allowModelNetwork: false,
+	});
+	modelRuntime.registerProvider(faux.provider.id, {
+		name: faux.provider.name,
+		api: faux.api,
+		apiKey: "faux",
+		streamSimple: faux.provider.streamSimple,
+		models: [...faux.models],
+	});
+	await modelRuntime.refresh({ allowNetwork: false });
+	const model = modelRuntime.getModel(faux.provider.id, "gw");
+	if (!model) throw new Error("faux model not registered");
+
+	const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
+	const loader = new DefaultResourceLoader({
+		cwd,
+		agentDir: home,
+		settingsManager,
+		additionalExtensionPaths: extensionPaths,
+		noPromptTemplates: true,
+		noThemes: true,
+		noContextFiles: true,
+	});
+	await loader.reload();
+
+	const created = await createAgentSession({
+		cwd,
+		agentDir: home,
+		model,
+		modelRuntime,
+		resourceLoader: loader,
+		sessionManager: SessionManager.create(cwd, join(home, "sessions")),
+		settingsManager,
+	});
+	const session = created.session;
+	await session.bindExtensions({});
+
+	const dispose = async () => {
+		try {
+			await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+		} catch {}
+		try {
+			session.dispose();
+		} catch {}
+		process.chdir(previousCwd);
+		if (previousHome === undefined) delete process.env.HOME;
+		else process.env.HOME = previousHome;
+		if (previousUserProfile === undefined) delete process.env.USERPROFILE;
+		else process.env.USERPROFILE = previousUserProfile;
+		if (previousAgentDir === undefined) delete process.env.SELESAI_CODING_AGENT_DIR;
+		else process.env.SELESAI_CODING_AGENT_DIR = previousAgentDir;
+		if (previousGateway === undefined) delete process.env.SELESAI_CAPABILITY_GATEWAY;
+		else process.env.SELESAI_CAPABILITY_GATEWAY = previousGateway;
+		rmSync(cwd, { recursive: true, force: true });
+		rmSync(home, { recursive: true, force: true });
+	};
+
+	return { session, dispose };
+}
+
+const harnesses: Harness[] = [];
+afterEach(async () => {
+	for (const h of harnesses.splice(0)) await h.dispose();
+});
+
+describe("capability gateway integration", () => {
+	it("keeps extension tools dormant and built-ins active when enabled", async () => {
+		const h = await createGatewaySession({ enabled: true });
+		harnesses.push(h);
+		const active = h.session.getActiveToolNames();
+		expect(active).toContain("read");
+		expect(active).toContain("bash");
+		expect(active).not.toContain("grep_app_search");
+		expect(active).not.toContain("subagent");
+		// Gateway's own tools stay active so the agent can discover.
+		expect(active).toContain("capability_catalog");
+	});
+
+	it("keeps all-visible behavior when disabled (compatibility mode)", async () => {
+		const h = await createGatewaySession({ enabled: false });
+		harnesses.push(h);
+		const active = h.session.getActiveToolNames();
+		expect(active).toContain("read");
+		expect(active).toContain("grep_app_search");
+		expect(active).toContain("subagent");
+	});
+
+	it("replaces the eager skill index with the compact capability instruction", async () => {
+		const h = await createGatewaySession({ enabled: true, withSkill: true });
+		harnesses.push(h);
+		const prompt = h.session.systemPrompt;
+		expect(prompt).toContain("capability_catalog");
+		expect(prompt).toContain("Never invent optional tool names");
+		// The full skill list is gone from the default prompt: the research
+		// skill name and body are absent, only the compact instruction remains.
+		expect(prompt).not.toContain("Research instructions body.");
+		const block = prompt.slice(prompt.indexOf("<available_skills>"), prompt.indexOf("</available_skills>"));
+		expect(block).not.toContain("research");
+		expect(block).toContain("capability-gateway");
+	});
+
+	it("activates a discovered tool for the run and resets after agent_settled", async () => {
+		const h = await createGatewaySession({ enabled: true });
+		harnesses.push(h);
+		const baseline = h.session.getActiveToolNames();
+		expect(baseline).not.toContain("grep_app_search");
+
+		// capability_discover activates the native tool.
+		const discover = h.session.getToolDefinition("capability_discover");
+		expect(discover).toBeDefined();
+		const result = await discover!.execute("call-1", { name: "grep_app_search" }, undefined, undefined, {} as never);
+		expect(result.content[0]!.type).toBe("text");
+		expect(String(result.content[0]!.text)).toContain("Activated");
+		expect(h.session.getActiveToolNames()).toContain("grep_app_search");
+
+		// agent_settled restores the baseline.
+		await h.session.extensionRunner.emit({ type: "agent_settled" });
+		expect(h.session.getActiveToolNames()).toEqual(baseline);
+	});
+
+	it("routes a high-confidence prompt to automatic activation", async () => {
+		// Minimal extension set (gateway + grep-app) so no other extension's
+		// before_agent_start handler interferes with the routing result.
+		const h = await createGatewaySession({ enabled: true, extensions: [GATEWAY_DIR, GREP_APP_DIR] });
+		harnesses.push(h);
+		expect(h.session.getActiveToolNames()).not.toContain("grep_app_search");
+
+		const runner = h.session.extensionRunner;
+		const result = await runner.emitBeforeAgentStart(
+			"search github code with grep_app_search",
+			undefined,
+			h.session.systemPrompt,
+			{ cwd: process.cwd() } as never,
+		);
+		expect(result).toBeUndefined();
+		expect(h.session.getActiveToolNames()).toContain("grep_app_search");
+	});
+
+	it("does not auto-load skills from fuzzy matching", async () => {
+		const h = await createGatewaySession({
+			enabled: true,
+			withSkill: true,
+			extensions: [GATEWAY_DIR, GREP_APP_DIR],
+		});
+		harnesses.push(h);
+		const runner = h.session.extensionRunner;
+		const result = await runner.emitBeforeAgentStart(
+			"do research on this topic",
+			undefined,
+			h.session.systemPrompt,
+			{ cwd: process.cwd() } as never,
+		);
+		// A recommendation message is injected, but the skill body is not loaded
+		// into the prompt and the skill is not auto-activated.
+		expect(result?.messages?.[0]?.content).toContain("research");
+		expect(h.session.systemPrompt).not.toContain("Research instructions body.");
+	});
+
+	it("does not recommend capability_skill_show for an inline-loaded $skill", async () => {
+		const h = await createGatewaySession({
+			enabled: true,
+			withSkill: true,
+			extensions: [GATEWAY_DIR, GREP_APP_DIR, INLINE_SKILLS_FILE],
+		});
+		harnesses.push(h);
+		const runner = h.session.extensionRunner;
+		const input = await runner.emitInput("Use $research now", undefined, "interactive", undefined);
+		expect(input.action).toBe("transform");
+		if (input.action !== "transform") throw new Error("inline skill was not expanded");
+		expect(input.text).toContain("Research instructions body.");
+
+		const result = await runner.emitBeforeAgentStart(
+			input.text,
+			undefined,
+			h.session.systemPrompt,
+			{ cwd: process.cwd() } as never,
+		);
+		expect(result).toBeUndefined();
+	});
+});

package/dist/extensions/capability-gateway/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "@selesai/capability-gateway",
+	"version": "0.1.0",
+	"private": true,
+	"description": "Experimental progressive capability gateway: dormant extension tools and skills with compact catalog, deterministic routing, and native activation.",
+	"type": "module",
+	"pi": {
+		"extensions": ["./index.ts"]
+	},
+	"peerDependencies": {
+		"@selesai/code": "*",
+		"@earendil-works/pi-ai": "*",
+		"typebox": "*"
+	}
+}

package/dist/extensions/package.json

@@ -26,6 +26,7 @@
 			"./pi-hermes-memory",
 			"./web-agent-onboarding.ts",
 			"./tps.ts",
+			"./capability-gateway",
 			"./pi-zentui/extensions/zentui/index.ts"
 		]
 	}

package/dist/extensions/pi-web-agent/src/backends/config.ts

@@ -1,4 +1,5 @@
 import type { FanoutMode, SearchProviderName } from '../types.js';
+import { hasActiveTokenInAccount } from './settings-reader.js';
 
 export type SearxngOptions = {
   categories?: string[];

package/dist/extensions/pi-web-agent/src/backends/settings-reader.ts

@@ -19,9 +19,11 @@ export function hasActiveTokenInAccount(authPath: string = join(getAgentDir(), '
 		if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
 		const auth = parsed as { accounts?: unknown; activeId?: unknown };
 		if (!Array.isArray(auth.accounts) || typeof auth.activeId !== 'string') return false;
-		return auth.accounts.some(
-			(a) => a && typeof a === 'object' && !Array.isArray(a) && (a as { id?: unknown }).id === auth.activeId
-		);
+		return auth.accounts.some((a) => {
+			if (!a || typeof a !== 'object' || Array.isArray(a)) return false;
+			const account = a as { id?: unknown; apiKey?: unknown };
+			return account.id === auth.activeId && typeof account.apiKey === 'string' && account.apiKey.trim() !== '';
+		});
 	} catch {
 		return false;
 	}

package/dist/extensions/pi-web-agent/src/search/tokenin.ts

@@ -27,7 +27,9 @@ export function readActiveTokenInAccount(
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
     const auth = parsed as TokenInAuth;
     if (!Array.isArray(auth.accounts) || typeof auth.activeId !== 'string') return undefined;
-    return auth.accounts.find((a) => a && typeof a === 'object' && a.id === auth.activeId && typeof a.apiKey === 'string');
+    return auth.accounts.find(
+      (a) => a && typeof a === 'object' && a.id === auth.activeId && typeof a.apiKey === 'string' && a.apiKey.trim() !== ''
+    );
   } catch {
     return undefined;
   }
@@ -82,8 +84,10 @@ export function createTokenInSearchTool({
       });
     }
 
-    const baseUrl = (account.baseUrl ?? TOKENIN_DEFAULT_BASE_URL).replace(/\/+$/, '');
-    const url = `${baseUrl}/v1/search/${TOKENIN_SEARCH_TOOL_NAME}`;
+    const rootUrl = (account.baseUrl ?? TOKENIN_DEFAULT_BASE_URL)
+      .replace(/\/+$/, '')
+      .replace(/\/v1$/, '');
+    const url = `${rootUrl}/v1/search/${TOKENIN_SEARCH_TOOL_NAME}`;
 
     try {
       const response = await fetchImpl(url, {

package/dist/extensions/pi-web-agent/src/types.ts

@@ -34,7 +34,7 @@ export type ToolError = {
 export type SearchMetadata = {
   backend: SearchProviderName;
   cacheHit: boolean;
-  fallbackFrom?: Exclude<SearchProviderName, 'tokenin'>;
+  fallbackFrom?: SearchProviderName;
   fallbackReason?: string;
   fanout?: FanoutMetadata;
 };

package/dist/extensions/pi-zentui/extensions/zentui/working-line.ts

@@ -972,12 +972,17 @@ export function buildWorkingLinePreviewFrames(
 }
 
 function workingLineUi(ctx: WorkingLineContext): WorkingLineUi | undefined {
-	if (ctx.hasUI === false || (ctx.mode !== undefined && ctx.mode !== "tui")) return undefined;
-	const ui = ctx.ui as unknown as Partial<WorkingLineUi>;
-	if (typeof ui.setWorkingMessage !== "function" || typeof ui.setWorkingIndicator !== "function") {
+	try {
+		if (ctx.hasUI === false || (ctx.mode !== undefined && ctx.mode !== "tui")) return undefined;
+		const ui = ctx.ui as unknown as Partial<WorkingLineUi>;
+		if (typeof ui.setWorkingMessage !== "function" || typeof ui.setWorkingIndicator !== "function") {
+			return undefined;
+		}
+		return ui as WorkingLineUi;
+	} catch {
+		// A stale ctx (after session replacement or reload) must not crash timer-driven updates.
 		return undefined;
 	}
-	return ui as WorkingLineUi;
 }
 
 export type WorkingLineReconcileResult = { applied: boolean; reason?: string };