can1357
386385f18b
- Prevent xdev state allocation and tool mounting in sessions lacking a write tool. - Expose discoverable tools top-level instead of auto-granting write transports.
1359 lines
57 KiB
TypeScript
1359 lines
57 KiB
TypeScript
import type { Agent, AgentTool } from "@oh-my-pi/pi-agent-core";
|
|
import type { Model } from "@oh-my-pi/pi-ai";
|
|
import { isRecord, logger, prompt, stringProperty } from "@oh-my-pi/pi-utils";
|
|
import { reset as resetCapabilities } from "../capability";
|
|
import type { ModelRegistry } from "../config/model-registry";
|
|
import { formatModelString } from "../config/model-resolver";
|
|
import type { Settings, SkillsSettings } from "../config/settings";
|
|
import type { CustomTool, CustomToolContext } from "../extensibility/custom-tools/types";
|
|
import { CustomToolAdapter } from "../extensibility/custom-tools/wrapper";
|
|
import type { ExtensionRunner } from "../extensibility/extensions";
|
|
import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
|
|
import { loadSkills, type Skill, type SkillWarning, setActiveSkills } from "../extensibility/skills";
|
|
import { type LocalProtocolOptions, XD_URL_PREFIX } from "../internal-urls";
|
|
import { deduplicateMCPToolsByName } from "../mcp/tool-bridge";
|
|
import { resolveMemoryBackend } from "../memory-backend/resolve";
|
|
import { MEMORY_BACKEND_TOOL_NAMES } from "../memory-backend/tool-names";
|
|
import type { MemoryBackendStartOptions } from "../memory-backend/types";
|
|
import xdevMountNoticePrompt from "../prompts/system/xdev-mount-notice.md" with { type: "text" };
|
|
import { usesCodexTaskPrompt } from "../task/prompt-policy";
|
|
import { isMCPToolName, normalizeToolNames } from "../tools/builtin-names";
|
|
import { computerExposureMode } from "../tools/computer/exposure";
|
|
import { wrapToolWithMetaNotice } from "../tools/output-meta";
|
|
import { ToolAbortError, ToolError } from "../tools/tool-errors";
|
|
import { isMountableUnderXdev, listXdevTools, type XdevState, xdevDocsFor, xdevEntries } from "../tools/xdev";
|
|
import { type EditMode, resolveEditMode } from "../utils/edit-mode";
|
|
import { type InspectImageMode, isInspectImageToolActive } from "../utils/inspect-image-mode";
|
|
import { formatLocalCalendarDate } from "../utils/local-date";
|
|
import {
|
|
extractPermissionLocations,
|
|
getPermissionIntent,
|
|
PERMISSION_OPTIONS,
|
|
PERMISSION_OPTIONS_BY_ID,
|
|
PERMISSION_REQUIRED_TOOLS,
|
|
} from "./acp-permission-gate";
|
|
import type { ClientBridge, ClientBridgePermissionOutcome } from "./client-bridge";
|
|
import type { CustomMessage } from "./messages";
|
|
import type { SessionManager } from "./session-manager";
|
|
|
|
/** Capabilities borrowed from the owning AgentSession. */
|
|
export interface SessionToolsHost {
|
|
agent: Agent;
|
|
sessionManager: SessionManager;
|
|
settings: Settings;
|
|
modelRegistry: ModelRegistry;
|
|
extensionRunner(): ExtensionRunner | undefined;
|
|
clientBridge(): ClientBridge | undefined;
|
|
agentKind(): "main" | "sub";
|
|
isDisposed(): boolean;
|
|
isStreaming(): boolean;
|
|
queuedMessageCount(): number;
|
|
planModeEnabled(): boolean;
|
|
model(): Model | undefined;
|
|
memoryBackendSession(): MemoryBackendStartOptions["session"];
|
|
clearInheritedProviderPromptCacheKey(): void;
|
|
clearMemoryPromotionSnapshot(): void;
|
|
captureMemoryPromotionSnapshot(prompt: string[]): void;
|
|
emitNotice(level: "info" | "warning" | "error", message: string, source?: string): void;
|
|
notifyCommandMetadataChanged(): void;
|
|
localProtocolOptions(): LocalProtocolOptions;
|
|
/** Session-scoped `/vision` override; undefined means "follow the persisted setting". */
|
|
getInspectImageModeOverride(): InspectImageMode | undefined;
|
|
setInspectImageModeOverride(mode: InspectImageMode | undefined): void;
|
|
}
|
|
|
|
interface SessionToolsOptions {
|
|
autoApprove?: boolean;
|
|
toolRegistry?: Map<string, AgentTool>;
|
|
createVibeTools?: () => AgentTool[];
|
|
createComputerTool?: () => Promise<AgentTool | null>;
|
|
/** Creates the built-in `inspect_image` tool for session-scoped runtime enablement (see {@link SessionTools.setInspectImageMode}). */
|
|
createInspectImageTool?: () => Promise<AgentTool | null>;
|
|
builtInToolNames?: Iterable<string>;
|
|
presentationPinnedToolNames?: ReadonlySet<string>;
|
|
ensureWriteRegistered?: () => Promise<boolean>;
|
|
rebuildSystemPrompt?: (
|
|
toolNames: string[],
|
|
tools: Map<string, AgentTool>,
|
|
) => Promise<{ systemPrompt: string[]; xdevCatalogNames?: readonly string[] }>;
|
|
getLocalCalendarDate?: () => string;
|
|
getMcpServerInstructions?: () => Map<string, string> | undefined;
|
|
xdev?: XdevState;
|
|
setActiveToolNames?: (names: Iterable<string>) => void;
|
|
baseSystemPrompt: string[];
|
|
skills?: Skill[];
|
|
skillWarnings?: SkillWarning[];
|
|
skillsSettings?: SkillsSettings;
|
|
skillsReloadable?: boolean;
|
|
}
|
|
|
|
export interface MountedMCPToolRouteSource {
|
|
readonly name: string;
|
|
readonly mcpServerName?: unknown;
|
|
readonly mcpToolName?: unknown;
|
|
}
|
|
|
|
export interface MountedMCPToolRoute {
|
|
readonly mcpServerName: string;
|
|
readonly mcpToolName: string;
|
|
readonly name: string;
|
|
}
|
|
|
|
export interface MCPXdevGuidanceMapping extends MountedMCPToolRoute {
|
|
readonly label: string;
|
|
readonly path: string;
|
|
}
|
|
|
|
export interface MCPXdevGuidanceProjection {
|
|
readonly mappings: readonly MCPXdevGuidanceMapping[];
|
|
readonly hasOmittedMappings: boolean;
|
|
}
|
|
|
|
const MAX_MCP_XDEV_GUIDANCE_MAPPING_DATA_LENGTH = 4000;
|
|
const MAX_MCP_XDEV_GUIDANCE_MAPPINGS = 64;
|
|
|
|
/** Yield exact mounted MCP ownership and route metadata. */
|
|
export function* collectMountedMCPToolRoutes(
|
|
tools: Iterable<MountedMCPToolRouteSource>,
|
|
): Generator<MountedMCPToolRoute> {
|
|
for (const tool of tools) {
|
|
if (typeof tool.mcpServerName !== "string" || typeof tool.mcpToolName !== "string") continue;
|
|
yield {
|
|
mcpServerName: tool.mcpServerName,
|
|
mcpToolName: tool.mcpToolName,
|
|
name: tool.name,
|
|
};
|
|
}
|
|
}
|
|
|
|
function formatMCPXdevGuidanceLabel(label: string): string {
|
|
return (JSON.stringify(label) ?? '""')
|
|
.replaceAll("`", "\\u0060")
|
|
.replaceAll("\u2028", "\\u2028")
|
|
.replaceAll("\u2029", "\\u2029");
|
|
}
|
|
|
|
/**
|
|
* Project exact live MCP routes into the bounded, Markdown-safe mapping data
|
|
* rendered by the static MCP guidance prompt.
|
|
*/
|
|
export function projectMountedMCPXdevGuidance(routes: Iterable<MountedMCPToolRoute>): MCPXdevGuidanceProjection {
|
|
const mappings: MCPXdevGuidanceMapping[] = [];
|
|
let remainingMappingDataLength = MAX_MCP_XDEV_GUIDANCE_MAPPING_DATA_LENGTH;
|
|
let hasOmittedMappings = false;
|
|
for (const route of routes) {
|
|
const rawMappingDataLength = route.mcpToolName.length + XD_URL_PREFIX.length + route.name.length;
|
|
if (mappings.length >= MAX_MCP_XDEV_GUIDANCE_MAPPINGS || rawMappingDataLength > remainingMappingDataLength) {
|
|
hasOmittedMappings = true;
|
|
continue;
|
|
}
|
|
const label = formatMCPXdevGuidanceLabel(route.mcpToolName);
|
|
const path = `${XD_URL_PREFIX}${route.name}`;
|
|
const mappingDataLength = label.length + path.length;
|
|
if (mappingDataLength > remainingMappingDataLength) {
|
|
hasOmittedMappings = true;
|
|
continue;
|
|
}
|
|
mappings.push({ ...route, label, path });
|
|
remainingMappingDataLength -= mappingDataLength;
|
|
}
|
|
return { mappings, hasOmittedMappings };
|
|
}
|
|
|
|
const XDEV_MOUNT_NOTICE_MESSAGE_TYPE = "xdev-mount-notice";
|
|
|
|
/**
|
|
* Structured payload persisted on each {@link XDEV_MOUNT_NOTICE_MESSAGE_TYPE}
|
|
* custom message. Lets a resumed session reconstruct which dynamic devices the
|
|
* model has already been told about, so reconnecting hosts do not re-announce
|
|
* (and re-splice a redundant developer message that busts the provider
|
|
* prompt-cache prefix).
|
|
*/
|
|
interface XdevMountNoticeDetails {
|
|
added: string[];
|
|
removed: string[];
|
|
}
|
|
|
|
/** Owns tool registration, presentation, prompt rebuilding, skills, and permissions. */
|
|
export class SessionTools {
|
|
readonly #host: SessionToolsHost;
|
|
#autoApprove: boolean;
|
|
#toolRegistry: Map<string, AgentTool>;
|
|
#createVibeTools: (() => AgentTool[]) | undefined;
|
|
#createComputerTool: SessionToolsOptions["createComputerTool"];
|
|
#createInspectImageTool: SessionToolsOptions["createInspectImageTool"];
|
|
#installedVibeToolNames = new Set<string>();
|
|
#builtInToolNames: Set<string>;
|
|
#rpcHostToolNames = new Set<string>();
|
|
#xdev: XdevState | undefined;
|
|
#pendingXdevMountDelta: { added: Set<string>; removed: Set<string> } | undefined;
|
|
/**
|
|
* Dynamic (`xd://`) devices the model has already been told are mounted.
|
|
* Seeded lazily from persisted history on resume (see
|
|
* {@link #ensureAnnouncedMountsSeeded}) and updated as notices are emitted, so
|
|
* a host reconnect that re-mounts the same device does not re-announce it.
|
|
*/
|
|
#announcedMounts = new Set<string>();
|
|
#announcedMountsSeeded = false;
|
|
#presentationPinnedToolNames: ReadonlySet<string> | undefined;
|
|
#runtimeSelectedToolNames: ReadonlySet<string> | undefined;
|
|
#baseSystemPrompt: string[];
|
|
#lastAppliedToolSignature: string | undefined;
|
|
/**
|
|
* `xd://` device names the current base system prompt renders in its catalog
|
|
* (the last rebuild's {@link BuildSystemPromptResult.xdevCatalogNames}). Consulted
|
|
* when a pending mount notice is delivered: a device the outgoing prompt already
|
|
* lists is recorded as announced without a redundant notice line. Empty when the
|
|
* prompt carries no catalog (no mounts, or a custom prompt that omits the section).
|
|
*/
|
|
#basePromptXdevNames: ReadonlySet<string> = new Set();
|
|
#mcpRefreshTail: Promise<void> = Promise.resolve();
|
|
#promptModelKey: string | undefined;
|
|
#rebuildSystemPrompt: SessionToolsOptions["rebuildSystemPrompt"];
|
|
#getLocalCalendarDate: () => string;
|
|
#getMcpServerInstructions: SessionToolsOptions["getMcpServerInstructions"];
|
|
#setActiveToolNames: SessionToolsOptions["setActiveToolNames"];
|
|
#ensureWriteRegistered: SessionToolsOptions["ensureWriteRegistered"];
|
|
#skills: Skill[];
|
|
#skillWarnings: SkillWarning[];
|
|
#skillsSettings: SkillsSettings | undefined;
|
|
#skillsReloadable: boolean;
|
|
#acpPermissionDecisions = new Map<string, "allow_always" | "reject_always">();
|
|
|
|
constructor(host: SessionToolsHost, options: SessionToolsOptions) {
|
|
this.#host = host;
|
|
this.#autoApprove = options.autoApprove === true;
|
|
this.#toolRegistry = options.toolRegistry ?? new Map();
|
|
this.#createVibeTools = options.createVibeTools;
|
|
this.#createComputerTool = options.createComputerTool;
|
|
this.#createInspectImageTool = options.createInspectImageTool;
|
|
this.#builtInToolNames = new Set(options.builtInToolNames ?? []);
|
|
this.#presentationPinnedToolNames = options.presentationPinnedToolNames;
|
|
this.#ensureWriteRegistered = options.ensureWriteRegistered;
|
|
this.#rebuildSystemPrompt = options.rebuildSystemPrompt;
|
|
this.#getLocalCalendarDate = options.getLocalCalendarDate ?? formatLocalCalendarDate;
|
|
this.#getMcpServerInstructions = options.getMcpServerInstructions;
|
|
this.#xdev = options.xdev;
|
|
if (this.#xdev && this.#xdev.tools !== this.#toolRegistry) {
|
|
throw new Error("xd:// state must reference the canonical session tool map");
|
|
}
|
|
if (this.#xdev) this.#xdev.decorateExecution = tool => this.#wrapToolForAcpPermission(tool);
|
|
this.#setActiveToolNames = options.setActiveToolNames;
|
|
this.#baseSystemPrompt = options.baseSystemPrompt;
|
|
this.#skills = options.skills ?? [];
|
|
this.#skillWarnings = options.skillWarnings ?? [];
|
|
this.#skillsSettings = options.skillsSettings;
|
|
this.#skillsReloadable = options.skillsReloadable ?? true;
|
|
this.#promptModelKey = this.#currentPromptModelKey();
|
|
}
|
|
|
|
/** Mutable registry shared with controller hosts that inspect available tools. */
|
|
get registry(): Map<string, AgentTool> {
|
|
return this.#toolRegistry;
|
|
}
|
|
|
|
/** Current stable base system prompt. */
|
|
get baseSystemPrompt(): string[] {
|
|
return this.#baseSystemPrompt;
|
|
}
|
|
|
|
/** Replaces the controller-owned base prompt without applying it to the agent. */
|
|
setBaseSystemPrompt(prompt: string[]): void {
|
|
this.#baseSystemPrompt = prompt;
|
|
}
|
|
|
|
/** Skills currently rendered into the system prompt. */
|
|
get skills(): Skill[] {
|
|
return this.#skills;
|
|
}
|
|
|
|
/** Diagnostics produced while loading the current skills. */
|
|
get skillWarnings(): SkillWarning[] {
|
|
return this.#skillWarnings;
|
|
}
|
|
|
|
/** Settings snapshot used for the current skill discovery. */
|
|
get skillsSettings(): SkillsSettings | undefined {
|
|
return this.#skillsSettings;
|
|
}
|
|
|
|
/** Drops cached per-session ACP `allow_always`/`reject_always` decisions. */
|
|
clearAcpPermissionDecisions(): void {
|
|
this.#acpPermissionDecisions.clear();
|
|
}
|
|
|
|
/** Drops cached ACP decisions and re-wraps active tools after the client changes. */
|
|
refreshAcpPermissionGates(): void {
|
|
this.#acpPermissionDecisions.clear();
|
|
const activeTools = this.getActiveToolNames()
|
|
.map(name => this.#toolRegistry.get(name))
|
|
.filter((tool): tool is AgentTool => tool !== undefined)
|
|
.map(tool => this.#wrapToolForAcpPermission(tool));
|
|
this.#host.agent.setTools(activeTools);
|
|
}
|
|
|
|
#getActiveNonMCPToolNames(): string[] {
|
|
return this.getEnabledToolNames().filter(name => !isMCPToolName(name) && this.#toolRegistry.has(name));
|
|
}
|
|
|
|
/** Names of tools currently exposed at the top level. */
|
|
getActiveToolNames(): string[] {
|
|
return this.#host.agent.state.tools.map(t => t.name);
|
|
}
|
|
|
|
/** Enabled top-level and discoverable tool names. */
|
|
getEnabledToolNames(): string[] {
|
|
const mountedNames = this.#xdev?.mountedNames;
|
|
if (!mountedNames || mountedNames.size === 0) return this.getActiveToolNames();
|
|
return [...this.getActiveToolNames(), ...mountedNames];
|
|
}
|
|
|
|
/** Names currently presented as `xd://` devices. */
|
|
getMountedXdevToolNames(): string[] {
|
|
return [...(this.#xdev?.mountedNames ?? [])];
|
|
}
|
|
|
|
/** Whether the edit tool is registered. */
|
|
get hasEditTool(): boolean {
|
|
return this.#toolRegistry.has("edit");
|
|
}
|
|
|
|
/** Looks up a registered tool by name. */
|
|
getToolByName(name: string): AgentTool | undefined {
|
|
return this.#toolRegistry.get(name);
|
|
}
|
|
|
|
/** Whether a registry entry came from a built-in factory. */
|
|
hasBuiltInTool(name: string): boolean {
|
|
return this.#builtInToolNames.has(name);
|
|
}
|
|
|
|
/** Names of every registered tool. */
|
|
getAllToolNames(): string[] {
|
|
return Array.from(this.#toolRegistry.keys());
|
|
}
|
|
|
|
#wrapRuntimeTool(tool: AgentTool): AgentTool {
|
|
const wrapped = wrapToolWithMetaNotice(tool);
|
|
const extensionRunner = this.#host.extensionRunner();
|
|
return extensionRunner ? new ExtensionToolWrapper(wrapped, extensionRunner) : wrapped;
|
|
}
|
|
|
|
/** Installs and activates the ephemeral vibe tool set. */
|
|
async activateVibeTools(baseToolNames: string[]): Promise<void> {
|
|
const createVibeTools = this.#createVibeTools;
|
|
if (!createVibeTools) {
|
|
throw new Error("Vibe tools are unavailable in this session.");
|
|
}
|
|
|
|
const tools = createVibeTools();
|
|
const vibeToolNames = tools.map(tool => tool.name);
|
|
if (new Set(vibeToolNames).size !== vibeToolNames.length) {
|
|
throw new Error("Vibe tool names must be unique.");
|
|
}
|
|
|
|
for (const tool of tools) {
|
|
if (this.#toolRegistry.has(tool.name)) continue;
|
|
this.#toolRegistry.set(tool.name, this.#wrapRuntimeTool(tool));
|
|
this.#builtInToolNames.add(tool.name);
|
|
this.#installedVibeToolNames.add(tool.name);
|
|
}
|
|
|
|
await this.applyActiveToolsByName([...new Set([...baseToolNames, ...vibeToolNames])]);
|
|
}
|
|
|
|
/** Uninstalls vibe tools and activates the replacement set. */
|
|
async deactivateVibeTools(nextToolNames: string[]): Promise<void> {
|
|
this.#uninstallVibeTools();
|
|
await this.applyActiveToolsByName(nextToolNames);
|
|
}
|
|
|
|
/** Removes vibe tools without restoring a source-session snapshot. */
|
|
async removeVibeToolsPreservingActive(): Promise<void> {
|
|
const removed = new Set(this.#installedVibeToolNames);
|
|
this.#uninstallVibeTools();
|
|
const nextActive = this.getActiveToolNames().filter(name => !removed.has(name));
|
|
await this.applyActiveToolsByName(nextActive);
|
|
}
|
|
|
|
#uninstallVibeTools(): void {
|
|
for (const name of this.#installedVibeToolNames) {
|
|
this.#toolRegistry.delete(name);
|
|
this.#builtInToolNames.delete(name);
|
|
}
|
|
this.#installedVibeToolNames.clear();
|
|
}
|
|
|
|
#getEditModeSession() {
|
|
return {
|
|
settings: this.#host.settings,
|
|
getActiveModelString: () => {
|
|
const model = this.#host.model();
|
|
return model ? formatModelString(model) : undefined;
|
|
},
|
|
} as const;
|
|
}
|
|
|
|
/** Resolves the edit mode for the active model and settings. */
|
|
resolveActiveEditMode(): EditMode {
|
|
return resolveEditMode(this.#getEditModeSession());
|
|
}
|
|
|
|
#currentPromptModelKey(): string | undefined {
|
|
const activeModel = this.#host.model();
|
|
const model = activeModel ? formatModelString(activeModel) : undefined;
|
|
if (!model || this.#host.settings.get("includeModelInPrompt")) return model;
|
|
return usesCodexTaskPrompt(model) ? "task-policy:gpt-5.6" : "task-policy:default";
|
|
}
|
|
|
|
#logComputerState(message: string, enabled: boolean): void {
|
|
const model = this.#host.model();
|
|
logger.debug(message, {
|
|
enabled,
|
|
active: this.getEnabledToolNames().includes("computer"),
|
|
model: model ? formatModelString(model) : undefined,
|
|
exposure: computerExposureMode(model),
|
|
});
|
|
}
|
|
|
|
/** Rebuilds model-dependent tool prompts after a model change. */
|
|
async syncAfterModelChange(previousEditMode: EditMode): Promise<void> {
|
|
const currentEditMode = this.resolveActiveEditMode();
|
|
const editModeChanged = previousEditMode !== currentEditMode && this.getActiveToolNames().includes("edit");
|
|
// The system prompt selects model-specific policy even when it does not display the model id.
|
|
const modelChanged = this.#currentPromptModelKey() !== this.#promptModelKey;
|
|
if (editModeChanged || modelChanged) {
|
|
await this.refreshBaseSystemPrompt();
|
|
}
|
|
const computerExpected = this.#host.settings.get("computer.enabled");
|
|
const computerActive = this.getEnabledToolNames().includes("computer");
|
|
if (computerExpected && !computerActive) {
|
|
const model = this.#host.model();
|
|
const modelName = model ? formatModelString(model) : "the current model";
|
|
logger.warn("Enabled computer tool missing after model change", { model: modelName });
|
|
this.#host.emitNotice(
|
|
"warning",
|
|
`Computer use remains enabled, but the computer tool is unavailable to ${modelName}.`,
|
|
"computer",
|
|
);
|
|
} else if (computerExpected) {
|
|
this.#logComputerState("Computer tool retained after model change", true);
|
|
}
|
|
|
|
// inspect_image auto mode keys off model image capability, so a model
|
|
// switch can flip the tool either way.
|
|
await this.reconcileInspectImageAfterModelChange();
|
|
}
|
|
|
|
/** Enabled MCP tools in their current presentation partition. */
|
|
getSelectedMCPToolNames(): string[] {
|
|
// Every connected MCP tool is enabled; presentation (top-level vs xd://) is
|
|
// decided by loadMode. Return the enabled MCP tools in the current set.
|
|
return this.getEnabledToolNames().filter(name => isMCPToolName(name) && this.#toolRegistry.has(name));
|
|
}
|
|
|
|
/**
|
|
* Wrap a tool with a permission-gate proxy when an ACP client is connected.
|
|
* Only wraps tools whose name is in PERMISSION_REQUIRED_TOOLS and only when
|
|
* the bridge exposes `requestPermission`. No-ops for all other cases.
|
|
*
|
|
* When the user has explicitly opted into `yolo` / auto-approve behavior (via
|
|
* the SDK/CLI `autoApprove` flag or a configured `tools.approvalMode: yolo`),
|
|
* skips the gate unless the per-tool policy explicitly requires a prompt or
|
|
* deny. The schema default is also `yolo`, so an explicit configuration or
|
|
* explicit session flag is required: default-config ACP sessions keep the
|
|
* client-side permission gate.
|
|
*/
|
|
#wrapToolForAcpPermission<T extends AgentTool>(tool: T): T {
|
|
const bridge = this.#host.clientBridge();
|
|
// Match the capability+method gating pattern used by read/write/bash.
|
|
if (!bridge?.capabilities.requestPermission || !bridge.requestPermission) return tool;
|
|
if (PERMISSION_REQUIRED_TOOLS[tool.name] !== true) return tool;
|
|
// Skip the gate only on explicit yolo opt-in; honour per-tool policies
|
|
// that require a prompt or deny (matching the normal approval wrapper).
|
|
if (this.#isExplicitAutoApproveMode()) {
|
|
const userPolicies = (this.#host.settings.get("tools.approval") ?? {}) as Record<string, unknown>;
|
|
const toolPolicy = userPolicies[tool.name];
|
|
if (!toolPolicy || toolPolicy === "allow") return tool;
|
|
}
|
|
return new Proxy(tool, {
|
|
get: (target, prop) => {
|
|
if (prop !== "execute") return target[prop as keyof T];
|
|
return async (
|
|
toolCallId: string,
|
|
args: unknown,
|
|
signal: AbortSignal | undefined,
|
|
onUpdate: never,
|
|
ctx: never,
|
|
) => {
|
|
const permissionIntent = getPermissionIntent(target.name, args);
|
|
if (!permissionIntent) {
|
|
return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
|
|
}
|
|
const command =
|
|
target.name === "bash" && args && typeof args === "object" && !Array.isArray(args)
|
|
? stringProperty(args, "command")
|
|
: undefined;
|
|
const commandContent = command
|
|
? [{ type: "content" as const, content: { type: "text" as const, text: `$ ${command}` } }]
|
|
: undefined;
|
|
// Short-circuit on persisted decisions.
|
|
const persisted = this.#acpPermissionDecisions.get(permissionIntent.cacheKey);
|
|
if (persisted === "allow_always") {
|
|
return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
|
|
}
|
|
if (persisted === "reject_always") {
|
|
throw new ToolError(`Tool call rejected by user (preference)`);
|
|
}
|
|
if (signal?.aborted) {
|
|
throw new ToolAbortError("Permission request cancelled");
|
|
}
|
|
type PermissionRaceResult =
|
|
| { kind: "permission"; outcome: ClientBridgePermissionOutcome }
|
|
| { kind: "aborted" };
|
|
const { promise: abortPromise, resolve: resolveAbort } = Promise.withResolvers<PermissionRaceResult>();
|
|
const onAbort = () => resolveAbort({ kind: "aborted" });
|
|
signal?.addEventListener("abort", onAbort, { once: true });
|
|
let raced: PermissionRaceResult;
|
|
try {
|
|
const permissionPromise = bridge.requestPermission!(
|
|
{
|
|
toolCallId,
|
|
toolName: target.name,
|
|
title: permissionIntent.title,
|
|
...(target.name === "bash" ? { kind: "execute" } : {}),
|
|
status: "pending",
|
|
rawInput: args,
|
|
...(commandContent ? { content: commandContent } : {}),
|
|
locations: extractPermissionLocations(
|
|
args,
|
|
this.#host.sessionManager.getCwd(),
|
|
permissionIntent.paths,
|
|
),
|
|
},
|
|
PERMISSION_OPTIONS,
|
|
signal,
|
|
).then(outcome => ({ kind: "permission" as const, outcome }));
|
|
raced = await Promise.race([permissionPromise, abortPromise]);
|
|
} finally {
|
|
signal?.removeEventListener("abort", onAbort);
|
|
}
|
|
if (raced.kind === "aborted" || signal?.aborted) {
|
|
throw new ToolAbortError("Permission request cancelled");
|
|
}
|
|
const outcome = raced.outcome;
|
|
if (outcome.outcome === "cancelled") {
|
|
throw new ToolAbortError("Permission request cancelled");
|
|
}
|
|
const selectedOption = PERMISSION_OPTIONS_BY_ID.get(outcome.optionId);
|
|
if (!selectedOption) {
|
|
throw new ToolError(`Tool permission response used unknown option ID: ${outcome.optionId}`);
|
|
}
|
|
if (selectedOption.kind === "allow_always") {
|
|
this.#acpPermissionDecisions.set(permissionIntent.cacheKey, "allow_always");
|
|
} else if (selectedOption.kind === "reject_always") {
|
|
this.#acpPermissionDecisions.set(permissionIntent.cacheKey, "reject_always");
|
|
}
|
|
if (selectedOption.kind === "reject_once" || selectedOption.kind === "reject_always") {
|
|
throw new ToolError(`Tool call rejected by user (${target.name})`);
|
|
}
|
|
return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
|
|
};
|
|
},
|
|
}) as T;
|
|
}
|
|
|
|
#isExplicitAutoApproveMode(): boolean {
|
|
return (
|
|
this.#autoApprove ||
|
|
(this.#host.settings.isConfigured("tools.approvalMode") &&
|
|
this.#host.settings.get("tools.approvalMode") === "yolo")
|
|
);
|
|
}
|
|
|
|
/** Applies an enabled tool set and reconciles its `xd://` partition. */
|
|
async applyActiveToolsByName(toolNames: string[]): Promise<void> {
|
|
toolNames = normalizeToolNames(toolNames);
|
|
let builtInWriteAvailable = this.#builtInToolNames.has("write");
|
|
if (toolNames.includes("write") && !builtInWriteAvailable) {
|
|
builtInWriteAvailable = (await this.#ensureWriteRegistered?.()) === true;
|
|
if (builtInWriteAvailable) this.#builtInToolNames.add("write");
|
|
}
|
|
const selectedTools = toolNames.flatMap(name => {
|
|
const tool = this.#toolRegistry.get(name);
|
|
return tool ? [{ name, tool }] : [];
|
|
});
|
|
const xdevReadAvailable = this.#builtInToolNames.has("read") && selectedTools.some(({ name }) => name === "read");
|
|
const xdevWriteAvailable = builtInWriteAvailable && selectedTools.some(({ name }) => name === "write");
|
|
const isPresentationPinned = (name: string): boolean =>
|
|
this.#presentationPinnedToolNames?.has(name) === true || this.#runtimeSelectedToolNames?.has(name) === true;
|
|
const mountCandidates = selectedTools.filter(
|
|
({ name, tool }) =>
|
|
this.#xdev !== undefined &&
|
|
xdevReadAvailable &&
|
|
xdevWriteAvailable &&
|
|
!isPresentationPinned(name) &&
|
|
isMountableUnderXdev(tool),
|
|
);
|
|
const mountNames = new Set(mountCandidates.map(({ name }) => name));
|
|
const tools: AgentTool[] = [];
|
|
const validToolNames: string[] = [];
|
|
for (const { name, tool } of selectedTools) {
|
|
if (mountNames.has(name)) continue;
|
|
tools.push(this.#wrapToolForAcpPermission(tool));
|
|
validToolNames.push(name);
|
|
}
|
|
|
|
const pinnedWrite = isPresentationPinned("write");
|
|
const activeDeferrableTool = tools.some(tool => tool.deferrable === true);
|
|
const transportNeeded = mountNames.size > 0 || activeDeferrableTool || this.#host.planModeEnabled();
|
|
if (transportNeeded && !builtInWriteAvailable) {
|
|
builtInWriteAvailable = (await this.#ensureWriteRegistered?.()) === true;
|
|
if (builtInWriteAvailable) this.#builtInToolNames.add("write");
|
|
}
|
|
if (transportNeeded && builtInWriteAvailable) {
|
|
const write = this.#toolRegistry.get("write");
|
|
if (write && !validToolNames.includes("write")) {
|
|
tools.push(this.#wrapToolForAcpPermission(write));
|
|
validToolNames.push("write");
|
|
}
|
|
} else if (
|
|
!pinnedWrite &&
|
|
(this.#presentationPinnedToolNames !== undefined || this.#runtimeSelectedToolNames !== undefined)
|
|
) {
|
|
const writeNameIndex = validToolNames.indexOf("write");
|
|
if (writeNameIndex >= 0 && this.#builtInToolNames.has("write")) validToolNames.splice(writeNameIndex, 1);
|
|
const writeToolIndex = tools.findIndex(tool => tool.name === "write" && this.#builtInToolNames.has("write"));
|
|
if (writeToolIndex >= 0) tools.splice(writeToolIndex, 1);
|
|
}
|
|
|
|
const previousMounted = new Set(this.#xdev?.mountedNames ?? []);
|
|
const previousActiveToolNames = this.getActiveToolNames();
|
|
this.#setMountedNames(mountNames);
|
|
this.#setActiveToolNames?.(validToolNames);
|
|
|
|
let rebuiltSystemPrompt: string[] | undefined;
|
|
let rebuiltSignature: string | undefined;
|
|
let rebuiltXdevCatalogNames: readonly string[] | undefined;
|
|
try {
|
|
if (this.#rebuildSystemPrompt) {
|
|
const signature = this.#computeAppliedToolSignature(validToolNames, tools);
|
|
if (signature !== this.#lastAppliedToolSignature) {
|
|
const built = await this.#rebuildSystemPrompt(validToolNames, this.#toolRegistry);
|
|
rebuiltSystemPrompt = built.systemPrompt;
|
|
rebuiltSignature = signature;
|
|
rebuiltXdevCatalogNames = built.xdevCatalogNames;
|
|
}
|
|
}
|
|
} catch (error) {
|
|
this.#setMountedNames(previousMounted);
|
|
this.#setActiveToolNames?.(previousActiveToolNames);
|
|
throw error;
|
|
}
|
|
|
|
if (this.#host.isDisposed()) {
|
|
this.#setMountedNames(previousMounted);
|
|
this.#setActiveToolNames?.(previousActiveToolNames);
|
|
return;
|
|
}
|
|
|
|
this.#notifyXdevMountDelta(previousMounted);
|
|
this.#host.agent.setTools(tools);
|
|
if (rebuiltSystemPrompt && rebuiltSignature) {
|
|
if (this.#lastAppliedToolSignature !== undefined) this.#host.clearInheritedProviderPromptCacheKey();
|
|
this.#baseSystemPrompt = rebuiltSystemPrompt;
|
|
this.#host.clearMemoryPromotionSnapshot();
|
|
this.#host.agent.setSystemPrompt(this.#baseSystemPrompt);
|
|
this.#lastAppliedToolSignature = rebuiltSignature;
|
|
this.#promptModelKey = this.#currentPromptModelKey();
|
|
this.#basePromptXdevNames = new Set(rebuiltXdevCatalogNames);
|
|
}
|
|
}
|
|
|
|
#setMountedNames(names: Iterable<string>): void {
|
|
const mountedNames = this.#xdev?.mountedNames;
|
|
if (!mountedNames) return;
|
|
mountedNames.clear();
|
|
for (const name of names) mountedNames.add(name);
|
|
}
|
|
|
|
/**
|
|
* Record a mid-session `xd://` mount delta for the model. Non-MCP mount
|
|
* churn remains notice-only, leaving the system prompt and provider cache
|
|
* prefix byte-stable; mounted MCP route changes additionally rebuild the
|
|
* global route guidance through the applied-tool signature. The delta is NOT
|
|
* steered immediately — a steered notice landing at a run's stop boundary
|
|
* (or while the session is idle) forces an unsolicited extra assistant turn
|
|
* — so it is coalesced into {@link #pendingXdevMountDelta} and rides along
|
|
* with the next prompt (docs + schema stay one `read xd://<tool>` away).
|
|
* Full docs join the system prompt opportunistically on a rebuild.
|
|
*/
|
|
#notifyXdevMountDelta(previousMounted: ReadonlySet<string>): void {
|
|
const current = this.#xdev?.mountedNames;
|
|
if (!current) return;
|
|
const addedNames = [...current].filter(name => !previousMounted.has(name));
|
|
const removedNames = [...previousMounted].filter(name => !current.has(name));
|
|
if (addedNames.length === 0 && removedNames.length === 0) return;
|
|
// Coalesce against the unannounced delta: an unmount cancels a pending
|
|
// mount the model never learned about, and a remount cancels a pending
|
|
// unmount.
|
|
const pending = this.#pendingXdevMountDelta ?? { added: new Set<string>(), removed: new Set<string>() };
|
|
for (const name of addedNames) {
|
|
if (!pending.removed.delete(name)) pending.added.add(name);
|
|
}
|
|
for (const name of removedNames) {
|
|
if (!pending.added.delete(name)) pending.removed.add(name);
|
|
}
|
|
this.#pendingXdevMountDelta = pending.added.size > 0 || pending.removed.size > 0 ? pending : undefined;
|
|
if (this.#host.settings.get("startup.quiet")) return;
|
|
const parts: string[] = [];
|
|
if (addedNames.length > 0) parts.push(`mounted ${addedNames.join(", ")}`);
|
|
if (removedNames.length > 0) parts.push(`unmounted ${removedNames.join(", ")}`);
|
|
this.#host.emitNotice("info", `xd://: ${parts.join("; ")}`, "xdev");
|
|
}
|
|
|
|
/**
|
|
* Forget the announced-mount baseline for a replaced transcript. Called when
|
|
* session history is swapped wholesale (`/new`, `switchSession`, `branch`): the
|
|
* previous transcript's persisted notices no longer apply, so the next notice
|
|
* re-seeds from the new history and a device reconnecting into it announces
|
|
* again.
|
|
*
|
|
* The pending delta is deliberately preserved: it holds mounts that are still
|
|
* live but not yet delivered to the model, and `branch()` does not rebuild the
|
|
* base system prompt, so dropping it would leave the branched transcript
|
|
* unaware of a still-mounted device that no later refresh would re-queue.
|
|
*/
|
|
resetAnnouncedMounts(): void {
|
|
this.#announcedMounts.clear();
|
|
this.#announcedMountsSeeded = false;
|
|
}
|
|
|
|
/**
|
|
* Seed {@link #announcedMounts} from persisted mount notices the first time a
|
|
* notice is consumed. On resume the in-memory mount set is rebuilt from
|
|
* scratch, so without replaying history every already-announced dynamic device
|
|
* would look freshly mounted and re-announce.
|
|
*/
|
|
#ensureAnnouncedMountsSeeded(): void {
|
|
if (this.#announcedMountsSeeded) return;
|
|
this.#announcedMountsSeeded = true;
|
|
for (const message of this.#host.agent.state.messages) {
|
|
if (message.role !== "custom" || message.customType !== XDEV_MOUNT_NOTICE_MESSAGE_TYPE) continue;
|
|
const details = message.details;
|
|
if (
|
|
isRecord(details) &&
|
|
Array.isArray(details.added) &&
|
|
details.added.every(name => typeof name === "string") &&
|
|
Array.isArray(details.removed) &&
|
|
details.removed.every(name => typeof name === "string")
|
|
) {
|
|
for (const name of details.added) this.#announcedMounts.add(name);
|
|
for (const name of details.removed) this.#announcedMounts.delete(name);
|
|
continue;
|
|
}
|
|
|
|
// Releases before structured notice details persisted only the rendered
|
|
// prompt. Replay its two stable inventory sections so the first resume
|
|
// after upgrading does not re-announce every dynamic device once.
|
|
if (typeof message.content !== "string") continue;
|
|
let section: "added" | "removed" | undefined;
|
|
for (const line of message.content.split("\n")) {
|
|
if (line === "These tools became available:") {
|
|
section = "added";
|
|
continue;
|
|
}
|
|
if (line.startsWith("No longer mounted")) {
|
|
section = "removed";
|
|
continue;
|
|
}
|
|
if (line === "Configured inline device docs:" || line === "</system-notice>") break;
|
|
if (line.startsWith("Read `xd://<tool>`")) {
|
|
section = undefined;
|
|
continue;
|
|
}
|
|
if (!section) continue;
|
|
const match = /^- xd:\/\/(\S+?)(?:\s+—|$)/.exec(line);
|
|
const name = match?.[1];
|
|
if (!name) continue;
|
|
if (section === "added") this.#announcedMounts.add(name);
|
|
else this.#announcedMounts.delete(name);
|
|
}
|
|
}
|
|
}
|
|
|
|
/** Consumes the hidden notice for unannounced `xd://` mount changes. */
|
|
takePendingXdevMountNotice(baseCatalogDelivered: boolean): CustomMessage<XdevMountNoticeDetails> | undefined {
|
|
const pending = this.#pendingXdevMountDelta;
|
|
if (!pending) return undefined;
|
|
this.#pendingXdevMountDelta = undefined;
|
|
this.#ensureAnnouncedMountsSeeded();
|
|
// A pending add for a device the outgoing base prompt already lists in its
|
|
// catalog needs no notice line — but only when the final provider prompt
|
|
// still carries that base catalog. A `before_agent_start` replacement drops
|
|
// it, so its additions must remain in the notice. Record prompt-carried
|
|
// devices announced here, after the final prompt is known and immediately
|
|
// before delivery. The pending delta remains untouched by rebuilds, letting
|
|
// {@link #notifyXdevMountDelta} cancel a mount followed by an unmount before
|
|
// any request is sent (issue #7139 reviews).
|
|
if (baseCatalogDelivered) {
|
|
for (const name of pending.added) {
|
|
if (this.#basePromptXdevNames.has(name)) this.#announcedMounts.add(name);
|
|
}
|
|
}
|
|
// Only announce a net change relative to what the model already knows (from
|
|
// this session and persisted history): a re-mount of an already-announced
|
|
// device — the common resume/reconnect case — and an unmount for a device
|
|
// it was never told about are both suppressed, keeping the provider prompt
|
|
// cache prefix byte-stable across resumes.
|
|
const addedNames = [...pending.added].filter(name => !this.#announcedMounts.has(name));
|
|
const removedNames = [...pending.removed].filter(name => this.#announcedMounts.has(name));
|
|
if (addedNames.length === 0 && removedNames.length === 0) return undefined;
|
|
const summaries = new Map(this.#xdev ? xdevEntries(this.#xdev).map(entry => [entry.name, entry.summary]) : []);
|
|
const added = addedNames.map(name => ({ name, summary: summaries.get(name) ?? "" }));
|
|
const removed = removedNames.map(name => ({ name }));
|
|
const docs = this.#xdev
|
|
? xdevDocsFor(
|
|
this.#xdev,
|
|
new Set(addedNames),
|
|
this.#host.settings.get("tools.xdevDocs"),
|
|
this.#host.settings.get("tools.xdevInlineDevices"),
|
|
)
|
|
: "";
|
|
for (const name of addedNames) this.#announcedMounts.add(name);
|
|
for (const name of removedNames) this.#announcedMounts.delete(name);
|
|
return {
|
|
role: "custom",
|
|
customType: XDEV_MOUNT_NOTICE_MESSAGE_TYPE,
|
|
content: prompt.render(xdevMountNoticePrompt, { added, removed, docs }),
|
|
details: { added: addedNames, removed: removedNames },
|
|
attribution: "agent",
|
|
display: false,
|
|
timestamp: Date.now(),
|
|
};
|
|
}
|
|
|
|
/** Rediscovers reloadable skills and refreshes prompt metadata. */
|
|
async refreshSkills(): Promise<void> {
|
|
resetCapabilities();
|
|
if (this.#skillsReloadable) {
|
|
const skillsSettings = this.#host.settings.getGroup("skills");
|
|
const discovered = await loadSkills({
|
|
...skillsSettings,
|
|
cwd: this.#host.sessionManager.getCwd(),
|
|
disabledExtensions: this.#host.settings.get("disabledExtensions") ?? [],
|
|
});
|
|
this.#skills = discovered.skills;
|
|
this.#skillWarnings = discovered.warnings;
|
|
this.#skillsSettings = skillsSettings;
|
|
|
|
if (this.#host.agentKind() === "main") {
|
|
setActiveSkills(this.#skills);
|
|
}
|
|
}
|
|
await this.refreshBaseSystemPrompt();
|
|
this.#host.notifyCommandMetadataChanged();
|
|
}
|
|
|
|
/** Selects enabled tools, ignoring names absent from the registry. */
|
|
async setActiveToolsByName(toolNames: string[]): Promise<void> {
|
|
const normalized = normalizeToolNames(toolNames);
|
|
// Transport-write eligibility keys off the *current* active set: an ordinary
|
|
// selection change should not demote `write` unless it is already active.
|
|
await this.#applyToolPresentation(
|
|
normalized,
|
|
this.#xdev?.mountedNames ?? new Set(),
|
|
this.getActiveToolNames().includes("write"),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Restore an enabled tool set with its exact top-level versus `xd://` partition.
|
|
*
|
|
* Both inputs are required because {@link setActiveToolsByName} only receives the
|
|
* enabled name list and classifies mounts from the current presentation set.
|
|
* Rollback/restore callers must pass the snapshotted mounted subset so names that
|
|
* were top-level stay pinned (`#runtimeSelectedToolNames`) and names that were under
|
|
* `xd://` remain mount-eligible, even when the live mount set has drifted.
|
|
*
|
|
* Names outside `mountedToolNames` are pinned top-level for this application;
|
|
* names in the mounted subset remain eligible for xdev mounting. Delegates the
|
|
* actual apply through {@link applyActiveToolsByName} and restores the prior runtime
|
|
* selection if that apply throws.
|
|
*/
|
|
async setActiveToolPresentation(toolNames: string[], mountedToolNames: string[]): Promise<void> {
|
|
const normalized = normalizeToolNames(toolNames);
|
|
// Restoration targets a snapshot, so write eligibility comes from the
|
|
// *target* set rather than whatever happens to be active mid-rollback.
|
|
await this.#applyToolPresentation(
|
|
normalized,
|
|
new Set(normalizeToolNames(mountedToolNames)),
|
|
normalized.includes("write"),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Shared body for {@link setActiveToolsByName} and {@link setActiveToolPresentation}:
|
|
* pins non-mounted names as the runtime selection (holding `write` back when it is
|
|
* transport-only) and applies the set, rolling the selection back if apply throws.
|
|
*/
|
|
async #applyToolPresentation(
|
|
normalized: string[],
|
|
mounted: ReadonlySet<string>,
|
|
writeSelected: boolean,
|
|
): Promise<void> {
|
|
const transportWriteActive =
|
|
writeSelected &&
|
|
this.#builtInToolNames.has("write") &&
|
|
this.#presentationPinnedToolNames?.has("write") !== true &&
|
|
this.#runtimeSelectedToolNames?.has("write") !== true &&
|
|
(mounted.size > 0 || this.#host.planModeEnabled());
|
|
const previousRuntimeSelectedToolNames = this.#runtimeSelectedToolNames;
|
|
this.#runtimeSelectedToolNames = new Set(
|
|
normalized.filter(name => !mounted.has(name) && !(name === "write" && transportWriteActive)),
|
|
);
|
|
try {
|
|
await this.applyActiveToolsByName(normalized);
|
|
} catch (error) {
|
|
this.#runtimeSelectedToolNames = previousRuntimeSelectedToolNames;
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
/** Replaces memory-backend tools while preserving unrelated selections. */
|
|
async replaceMemoryTools(tools: AgentTool[]): Promise<void> {
|
|
const removed = new Set<string>(MEMORY_BACKEND_TOOL_NAMES.filter(name => this.#builtInToolNames.has(name)));
|
|
const nextActive = this.getEnabledToolNames().filter(name => !removed.has(name));
|
|
for (const name of removed) {
|
|
this.#toolRegistry.delete(name);
|
|
this.#builtInToolNames.delete(name);
|
|
}
|
|
|
|
for (const tool of tools) {
|
|
if (!MEMORY_BACKEND_TOOL_NAMES.some(name => name === tool.name) || this.#toolRegistry.has(tool.name)) {
|
|
continue;
|
|
}
|
|
const wrapped = this.#wrapRuntimeTool(tool);
|
|
this.#toolRegistry.set(wrapped.name, wrapped);
|
|
this.#builtInToolNames.add(wrapped.name);
|
|
nextActive.push(wrapped.name);
|
|
}
|
|
await this.applyActiveToolsByName([...new Set(nextActive)]);
|
|
}
|
|
|
|
/**
|
|
* Session-scoped enable/disable for the settings-gated `computer` tool.
|
|
*
|
|
* `createTools` derives the built-in slate once at session start, so a runtime
|
|
* `computer.enabled` override alone never changes the active tools. Enabling
|
|
* builds the tool through the config factory on first use (later toggles reuse
|
|
* the registry entry, so only one desktop controller is ever registered) and
|
|
* activates it; disabling drops it from the active set while keeping the
|
|
* registry entry. Takes effect before the next model call.
|
|
*
|
|
* @returns false when enabling was requested but this session cannot build the
|
|
* tool (e.g. restricted child sessions have no factory).
|
|
*/
|
|
async setComputerToolEnabled(enabled: boolean): Promise<boolean> {
|
|
const logState = (): void => this.#logComputerState("Computer tool state changed", enabled);
|
|
const active = this.getEnabledToolNames();
|
|
if (!enabled) {
|
|
if (active.includes("computer")) {
|
|
await this.applyActiveToolsByName(active.filter(name => name !== "computer"));
|
|
}
|
|
logState();
|
|
return true;
|
|
}
|
|
if (!this.#toolRegistry.has("computer")) {
|
|
const tool = await this.#createComputerTool?.();
|
|
if (tool?.name !== "computer") {
|
|
const model = this.#host.model();
|
|
logger.warn("Computer tool could not be created", {
|
|
model: model ? formatModelString(model) : undefined,
|
|
});
|
|
return false;
|
|
}
|
|
const wrapped = this.#wrapRuntimeTool(tool);
|
|
this.#toolRegistry.set(wrapped.name, wrapped);
|
|
this.#builtInToolNames.add(wrapped.name);
|
|
}
|
|
if (!active.includes("computer")) {
|
|
await this.applyActiveToolsByName([...active, "computer"]);
|
|
}
|
|
logState();
|
|
return true;
|
|
}
|
|
|
|
/** Current effective inspect_image state for `/vision status`. */
|
|
inspectImageState(): { mode: InspectImageMode; active: boolean; model: string | undefined } {
|
|
const model = this.#host.model();
|
|
return {
|
|
mode: this.#host.getInspectImageModeOverride() ?? this.#host.settings.get("inspect_image.mode"),
|
|
active: this.getEnabledToolNames().includes("inspect_image"),
|
|
model: model ? formatModelString(model) : undefined,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Brings the active tool set in line with the effective inspect_image state
|
|
* (mode setting, `/vision` override, active-model image capability).
|
|
* Mirrors {@link setComputerToolEnabled}: enabling builds the tool through
|
|
* the config factory on first use and reuses the registry entry afterwards.
|
|
* Idempotent — safe to call from every model/settings change path.
|
|
*
|
|
* @returns false when the tool should be active but this session cannot
|
|
* build it (e.g. restricted child sessions have no factory).
|
|
*/
|
|
async reconcileInspectImageTool(): Promise<boolean> {
|
|
const expected = isInspectImageToolActive({
|
|
settings: this.#host.settings,
|
|
getActiveModel: () => this.#host.model(),
|
|
getInspectImageModeOverride: () => this.#host.getInspectImageModeOverride(),
|
|
});
|
|
// Keep the read tool's advertised description in sync BEFORE any prompt
|
|
// rebuild below, passing the post-change availability so the prompt never
|
|
// lags a flip in either direction. Per-read lazy sync is the backstop.
|
|
const syncReadDescription = (available: boolean): void => {
|
|
const readTool = this.#toolRegistry.get("read") as
|
|
| { syncInspectImageState?: (available?: boolean) => boolean }
|
|
| undefined;
|
|
readTool?.syncInspectImageState?.(available);
|
|
};
|
|
const active = this.getEnabledToolNames();
|
|
const isActive = active.includes("inspect_image");
|
|
if (expected === isActive) {
|
|
syncReadDescription(isActive);
|
|
return true;
|
|
}
|
|
if (!expected) {
|
|
syncReadDescription(false);
|
|
await this.applyActiveToolsByName(active.filter(name => name !== "inspect_image"));
|
|
return true;
|
|
}
|
|
if (!this.#toolRegistry.has("inspect_image")) {
|
|
const tool = await this.#createInspectImageTool?.();
|
|
if (tool?.name !== "inspect_image") {
|
|
logger.warn("inspect_image tool could not be created", {
|
|
model: this.#host.model()?.id,
|
|
});
|
|
syncReadDescription(false);
|
|
return false;
|
|
}
|
|
const wrapped = this.#wrapRuntimeTool(tool);
|
|
this.#toolRegistry.set(wrapped.name, wrapped);
|
|
this.#builtInToolNames.add(wrapped.name);
|
|
}
|
|
syncReadDescription(true);
|
|
await this.applyActiveToolsByName([...active, "inspect_image"]);
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* Reconciles inspect_image after a model change and surfaces a notice when
|
|
* the visible tool set actually flipped. Called from every model-change
|
|
* path — including retry-fallback switches that bypass
|
|
* {@link syncAfterModelChange}.
|
|
*/
|
|
async reconcileInspectImageAfterModelChange(): Promise<void> {
|
|
const before = this.getEnabledToolNames().includes("inspect_image");
|
|
const reconciled = await this.reconcileInspectImageTool();
|
|
const after = this.getEnabledToolNames().includes("inspect_image");
|
|
if (!reconciled || before === after) return;
|
|
const model = this.#host.model();
|
|
const modelName = model ? formatModelString(model) : "the current model";
|
|
this.#host.emitNotice(
|
|
"info",
|
|
after
|
|
? `inspect_image is now available: ${modelName} has no native image input.`
|
|
: `inspect_image is now hidden: ${modelName} supports image input natively. Override with /vision on.`,
|
|
"vision",
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Session-scoped `/vision` override. `auto` clears the override so the
|
|
* persisted `inspect_image.mode` setting (itself possibly `auto`) decides;
|
|
* `on`/`off` force the tool for this session only. Takes effect before the
|
|
* next model call.
|
|
*
|
|
* @returns false when `on` was requested but the tool cannot be built here.
|
|
*/
|
|
async setInspectImageMode(mode: InspectImageMode): Promise<boolean> {
|
|
this.#host.setInspectImageModeOverride(mode === "auto" ? undefined : mode);
|
|
const applied = await this.reconcileInspectImageTool();
|
|
const { active, model } = this.inspectImageState();
|
|
logger.debug("inspect_image mode changed", { mode, active, model });
|
|
return applied;
|
|
}
|
|
|
|
/** Rebuilds the stable base prompt for the current tools and model. */
|
|
async refreshBaseSystemPrompt(): Promise<void> {
|
|
if (this.#host.isDisposed() || !this.#rebuildSystemPrompt) return;
|
|
const activeToolNames = this.getActiveToolNames();
|
|
this.#setActiveToolNames?.(activeToolNames);
|
|
const previousBaseSystemPrompt = this.#baseSystemPrompt;
|
|
const built = await this.#rebuildSystemPrompt(activeToolNames, this.#toolRegistry);
|
|
if (this.#host.isDisposed()) return;
|
|
this.#baseSystemPrompt = built.systemPrompt;
|
|
this.#basePromptXdevNames = new Set(built.xdevCatalogNames);
|
|
this.#host.clearMemoryPromotionSnapshot();
|
|
if (
|
|
previousBaseSystemPrompt.length !== this.#baseSystemPrompt.length ||
|
|
previousBaseSystemPrompt.some((part, index) => part !== this.#baseSystemPrompt[index])
|
|
) {
|
|
this.#host.clearInheritedProviderPromptCacheKey();
|
|
}
|
|
this.#host.agent.setSystemPrompt(this.#baseSystemPrompt);
|
|
this.#promptModelKey = this.#currentPromptModelKey();
|
|
// Refresh the cached signature so a subsequent `applyActiveToolsByName` with
|
|
// the same tool set does not re-rebuild on top of the explicit refresh we
|
|
// just performed (and conversely, a different set forces a fresh rebuild).
|
|
const activeTools = activeToolNames
|
|
.map(name => this.#toolRegistry.get(name))
|
|
.filter((tool): tool is AgentTool => tool != null);
|
|
this.#lastAppliedToolSignature = this.#computeAppliedToolSignature(activeToolNames, activeTools);
|
|
}
|
|
|
|
/** Applies one-turn memory prompt injection before an agent run. */
|
|
async buildSystemPromptForAgentStart(promptText: string): Promise<string[]> {
|
|
const backend = await resolveMemoryBackend(this.#host.settings);
|
|
if (!backend.beforeAgentStartPrompt) return this.#baseSystemPrompt;
|
|
|
|
try {
|
|
const injected = await backend.beforeAgentStartPrompt(this.#host.memoryBackendSession(), promptText);
|
|
if (!injected) return this.#baseSystemPrompt;
|
|
|
|
const previousBaseSystemPrompt = this.#baseSystemPrompt;
|
|
try {
|
|
await this.refreshBaseSystemPrompt();
|
|
} catch (refreshErr) {
|
|
logger.debug("Memory backend prompt refresh after beforeAgentStartPrompt failed", {
|
|
backend: backend.id,
|
|
error: String(refreshErr),
|
|
});
|
|
}
|
|
|
|
if (
|
|
this.#baseSystemPrompt.length !== previousBaseSystemPrompt.length ||
|
|
this.#baseSystemPrompt.some((part, index) => part !== previousBaseSystemPrompt[index])
|
|
) {
|
|
return this.#baseSystemPrompt;
|
|
}
|
|
|
|
this.#host.captureMemoryPromotionSnapshot(previousBaseSystemPrompt);
|
|
const stablePrompt = [...previousBaseSystemPrompt, injected];
|
|
this.#baseSystemPrompt = stablePrompt;
|
|
this.#host.agent.setSystemPrompt(stablePrompt);
|
|
return stablePrompt;
|
|
} catch (err) {
|
|
logger.debug("Memory backend beforeAgentStartPrompt failed", {
|
|
backend: backend.id,
|
|
error: String(err),
|
|
});
|
|
return this.#baseSystemPrompt;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Compose a stable signature for the inputs that `rebuildSystemPrompt` reads.
|
|
* Two calls producing identical signatures are guaranteed to produce identical
|
|
* system prompt bytes, so the rebuild can be skipped.
|
|
*
|
|
* The signature covers:
|
|
* 1. Active tool names in order (the prompt renders them in this order).
|
|
* 2. Active tool labels, descriptions, and wire-visible names — all are
|
|
* rendered into the prompt body (see `system-prompt.md` `{{label}}: \`{{name}}\``
|
|
* and `toolPromptNames` in `buildSystemPrompt`). The wire name comes from
|
|
* `tool.customWireName` and overrides the internal name on the model wire
|
|
* (e.g. `edit` exposes itself as `apply_patch` to GPT-5 in apply_patch mode);
|
|
* a stale wire name would desync prompt guidance from actual tool routing.
|
|
* 3. The bounded mounted-MCP projection: escaped original-name labels,
|
|
* actual `xd://` paths, and the omission flag in catalog order. These are
|
|
* the exact values rendered by the global transport guidance; catalog
|
|
* churn wholly behind the fallback does not change the prompt.
|
|
* 4. MCP server instructions text (per server), since `rebuildSystemPrompt`
|
|
* embeds these in the appended prompt under "## MCP Server Instructions".
|
|
* A server upgrade can change instructions while keeping tools identical.
|
|
*
|
|
* Settings-driven tool metadata is covered automatically: built-in tools that
|
|
* depend on settings expose `description`/`label` via getters (see `TaskTool`,
|
|
* `SearchToolBm25Tool`, `EditTool`), and the signature reads them live on every
|
|
* call - so a settings flip that mutates the rendered string differs the signature
|
|
* the next time {@link applyActiveToolsByName} runs. Do not refactor `describeTool`
|
|
* to cache per-tool strings without preserving this property.
|
|
*
|
|
* Inputs NOT covered: tool input schemas; memory instructions read from disk;
|
|
* and SDK-init-time closure constants in `sdk.ts` (`inlineToolDescriptors`,
|
|
* `eagerTasks`, `intentField`, `mcpDiscoveryEnabled`, `secretsEnabled`). The
|
|
* closure-captured ones cannot change at runtime regardless of skip behavior.
|
|
* For everything else, callers must explicitly call {@link refreshBaseSystemPrompt}
|
|
* after side-effecting changes; see the memory hooks and {@link syncAfterModelChange}.
|
|
*
|
|
* The current calendar date IS covered (appended as a segment) because
|
|
* `buildSystemPrompt` injects it into the prompt body (`Today is '{{date}}'`).
|
|
* Without this, a session spanning midnight with only tool-stable MCP
|
|
* reconnects would keep yesterday's date indefinitely.
|
|
*/
|
|
#computeAppliedToolSignature(toolNames: string[], tools: AgentTool[]): string {
|
|
// Order-preserving join: any reorder must produce a different signature so
|
|
// the rebuild fires and the new tool list reaches the API.
|
|
const nameSegment = toolNames.join("\u0001");
|
|
const describeTool = (tool: AgentTool): string =>
|
|
`${tool.name}=${tool.label ?? ""}|${tool.description ?? ""}|${tool.customWireName ?? ""}`;
|
|
const descriptionSegment = tools.map(describeTool).join("\u0002");
|
|
const mountedMCPProjection = projectMountedMCPXdevGuidance(
|
|
collectMountedMCPToolRoutes(this.#xdev ? listXdevTools(this.#xdev) : []),
|
|
);
|
|
const mountedMCPRouteSegment =
|
|
JSON.stringify({
|
|
mappings: mountedMCPProjection.mappings.map(mapping => [mapping.label, mapping.path] as const),
|
|
hasOmittedMappings: mountedMCPProjection.hasOmittedMappings,
|
|
}) ?? "{}";
|
|
const serverInstructions = this.#getMcpServerInstructions?.();
|
|
let instructionsSegment = "";
|
|
if (serverInstructions && serverInstructions.size > 0) {
|
|
// Sort by server name so transport flap order does not perturb the signature.
|
|
const entries: string[] = [];
|
|
for (const [server, instructions] of serverInstructions) {
|
|
entries.push(`${server}=${instructions}`);
|
|
}
|
|
entries.sort();
|
|
instructionsSegment = entries.join("\u0006");
|
|
}
|
|
// The non-MCP remainder of the xd:// inventory is deliberately NOT part
|
|
// of the signature: its mount/unmount announces itself through
|
|
// `#notifyXdevMountDelta` rather than rewriting the system prompt, keeping
|
|
// the provider cache prefix byte-stable. Mounted MCP routes are the narrow
|
|
// exception above, bounded to the exact projection rendered in the global
|
|
// route guidance so churn wholly behind its fallback does not rebuild.
|
|
const date = this.#getLocalCalendarDate();
|
|
return `${nameSegment}\u0003${descriptionSegment}\u0007${instructionsSegment}\u0008${mountedMCPRouteSegment}|${date}`;
|
|
}
|
|
|
|
/**
|
|
* Replace MCP tools in the registry and enable them immediately. Refreshes
|
|
* are serialized so an older asynchronous prompt rebuild cannot commit
|
|
* after a newer catalog snapshot. Every connected MCP tool becomes available
|
|
* (mounted under `xd://` when that transport is active, else top-level).
|
|
*/
|
|
refreshMCPTools(mcpTools: CustomTool[]): Promise<void> {
|
|
const snapshot = [...mcpTools];
|
|
const refresh = this.#mcpRefreshTail.then(() =>
|
|
this.#host.isDisposed() ? undefined : this.#applyMCPToolRefresh(snapshot),
|
|
);
|
|
this.#mcpRefreshTail = refresh.catch(() => {});
|
|
return refresh;
|
|
}
|
|
|
|
async #applyMCPToolRefresh(mcpTools: CustomTool[]): Promise<void> {
|
|
const existingNames = Array.from(this.#toolRegistry.keys());
|
|
const previousMcpTools = new Map(
|
|
existingNames.flatMap(name => {
|
|
const tool = this.#toolRegistry.get(name);
|
|
return isMCPToolName(name) && tool ? [[name, tool] as const] : [];
|
|
}),
|
|
);
|
|
const restorePreviousMcpTools = () => {
|
|
for (const name of this.#toolRegistry.keys()) {
|
|
if (isMCPToolName(name)) this.#toolRegistry.delete(name);
|
|
}
|
|
for (const [name, tool] of previousMcpTools) this.#toolRegistry.set(name, tool);
|
|
};
|
|
for (const name of existingNames) {
|
|
if (isMCPToolName(name)) {
|
|
this.#toolRegistry.delete(name);
|
|
}
|
|
}
|
|
|
|
const getCustomToolContext = (): CustomToolContext => ({
|
|
sessionManager: this.#host.sessionManager,
|
|
modelRegistry: this.#host.modelRegistry,
|
|
model: this.#host.model(),
|
|
isIdle: () => !this.#host.isStreaming(),
|
|
hasQueuedMessages: () => this.#host.queuedMessageCount() > 0,
|
|
abort: () => {
|
|
this.#host.agent.abort();
|
|
},
|
|
settings: this.#host.settings,
|
|
localProtocolOptions: this.#host.localProtocolOptions(),
|
|
});
|
|
|
|
const extensionRunner = this.#host.extensionRunner();
|
|
const uniqueMcpTools = deduplicateMCPToolsByName(mcpTools);
|
|
for (const customTool of uniqueMcpTools) {
|
|
const wrapped = wrapToolWithMetaNotice(CustomToolAdapter.wrap(customTool, getCustomToolContext) as AgentTool);
|
|
const finalTool = (
|
|
extensionRunner ? new ExtensionToolWrapper(wrapped, extensionRunner) : wrapped
|
|
) as AgentTool;
|
|
this.#toolRegistry.set(finalTool.name, finalTool);
|
|
}
|
|
|
|
// Every connected MCP tool is selected; centralized repartitioning owns
|
|
// presentation pins and write-transport activation/removal.
|
|
const nextActive = [...new Set([...this.#getActiveNonMCPToolNames(), ...uniqueMcpTools.map(tool => tool.name)])];
|
|
try {
|
|
await this.applyActiveToolsByName(nextActive);
|
|
if (this.#host.isDisposed()) restorePreviousMcpTools();
|
|
} catch (error) {
|
|
restorePreviousMcpTools();
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
/** Replaces RPC host-owned tools and refreshes the active set before the next model call. */
|
|
async refreshRpcHostTools(rpcTools: AgentTool[]): Promise<void> {
|
|
const nextToolNames = rpcTools.map(tool => tool.name);
|
|
const uniqueToolNames = new Set(nextToolNames);
|
|
if (uniqueToolNames.size !== nextToolNames.length) {
|
|
throw new Error("RPC host tool names must be unique");
|
|
}
|
|
|
|
for (const name of uniqueToolNames) {
|
|
if (this.#toolRegistry.has(name) && !this.#rpcHostToolNames.has(name)) {
|
|
throw new Error(`RPC host tool "${name}" conflicts with an existing tool`);
|
|
}
|
|
}
|
|
|
|
const previousRpcHostToolNames = new Set(this.#rpcHostToolNames);
|
|
const previousActiveToolNames = this.getEnabledToolNames();
|
|
const previousRpcHostTools = new Map(
|
|
[...previousRpcHostToolNames].flatMap(name => {
|
|
const tool = this.#toolRegistry.get(name);
|
|
return tool ? [[name, tool] as const] : [];
|
|
}),
|
|
);
|
|
for (const name of previousRpcHostToolNames) {
|
|
this.#toolRegistry.delete(name);
|
|
}
|
|
this.#rpcHostToolNames.clear();
|
|
|
|
const extensionRunner = this.#host.extensionRunner();
|
|
for (const tool of rpcTools) {
|
|
const metaWrapped = wrapToolWithMetaNotice(tool);
|
|
const finalTool = (
|
|
extensionRunner ? new ExtensionToolWrapper(metaWrapped, extensionRunner) : metaWrapped
|
|
) as AgentTool;
|
|
this.#toolRegistry.set(finalTool.name, finalTool);
|
|
this.#rpcHostToolNames.add(finalTool.name);
|
|
}
|
|
|
|
const activeNonRpcToolNames = previousActiveToolNames.filter(name => !previousRpcHostToolNames.has(name));
|
|
const preservedRpcToolNames = previousActiveToolNames.filter(
|
|
name => previousRpcHostToolNames.has(name) && this.#rpcHostToolNames.has(name),
|
|
);
|
|
const autoActivatedRpcToolNames = rpcTools
|
|
.filter(tool => !tool.hidden && !previousRpcHostToolNames.has(tool.name))
|
|
.map(tool => tool.name);
|
|
try {
|
|
await this.applyActiveToolsByName(
|
|
Array.from(new Set([...activeNonRpcToolNames, ...preservedRpcToolNames, ...autoActivatedRpcToolNames])),
|
|
);
|
|
} catch (error) {
|
|
for (const name of this.#rpcHostToolNames) this.#toolRegistry.delete(name);
|
|
this.#rpcHostToolNames = previousRpcHostToolNames;
|
|
for (const [name, tool] of previousRpcHostTools) this.#toolRegistry.set(name, tool);
|
|
throw error;
|
|
}
|
|
}
|
|
}
|