@caupulican/pi-adaptative 0.80.103 → 0.81.1

package/dist/core/runtime-builder.js

@@ -0,0 +1,640 @@
+/**
+ * Runtime build & reload: the session's tool-registry assembly and the self-modification-safe
+ * extension reload path. Owns building the base tool definitions, wrapping them into the live tool
+ * registry (`_refreshToolRegistry`), constructing the {@link ExtensionRunner} for a rebuilt runtime
+ * (`_buildRuntime`), and the repo's self-modification safety crown jewel: the preflight-guarded
+ * `reload()` with its snapshot / doctor / commit-or-rollback sequence, plus the single-extension
+ * live load/unload/reconcile operations that rebuild the runtime in place.
+ *
+ * Extracted verbatim from agent-session.ts (god-file decomposition). Owns ONLY the tool-registry
+ * state — the base tool definitions, the wrapped tool registry, the definition registry, and the
+ * per-tool prompt snippet/guideline maps. Everything else the build & reload touch — the live
+ * {@link ExtensionRunner}, the agent's tool/system-prompt state, the base system prompt, the
+ * resource loader, the session/settings managers, the model registry, the profile tool filter and
+ * its warning sinks, the requested-active-tool-names request, the memory subsystem, and the many
+ * host callbacks the rebuilt tools/runtime are wired to — is reached through narrow deps accessors
+ * that read and write the SAME storage the host owns today.
+ *
+ * Snapshot-ownership boundary (deliberate, load-bearing for reload safety): the reload snapshot
+ * spans state owned by OTHER collaborators — the extension runner and its ref, `agent.state.tools`
+ * / `agent.state.systemPrompt`, and `_baseSystemPrompt`. Those are captured and restored through
+ * {@link RuntimeBuilderDeps} get/set accessors so save/restore mutate exactly the host/agent fields
+ * they mutated before extraction; only the five tool-registry maps are captured by direct field
+ * reference here (this builder owns them). The `_extensionRunnerRef.current` update folds into
+ * {@link RuntimeBuilderDeps.setExtensionRunner} (the same field-then-ref pattern the host used at
+ * every assignment site), so no observer runs between the two writes.
+ *
+ * Host-binding boundary (deliberate): `_bindExtensionCore` — which exposes the SESSION's own public
+ * surface (sendMessage, setModel, compact, abort, reload, …) to the extension runner — stays
+ * host-side and is invoked from {@link buildRuntime} via {@link RuntimeBuilderDeps.bindExtensionCore};
+ * it is host identity, not build logic, and moving it would only re-export ~30 host methods through
+ * deps to hand them straight back. The host keeps one-line delegations for the public reload /
+ * load / unload / reconcile API and for `getAllTools` / `getToolDefinition`, and a private
+ * `_refreshToolRegistry` delegation for its internal callers.
+ */
+import { resetApiProviders } from "@caupulican/pi-ai";
+import { createCoreDiagnosticsToolDefinitions } from "./extensions/builtin.js";
+import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
+import { disposeExtensionEventSubscriptions } from "./extensions/loader.js";
+import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { matchesResourceProfilePattern, } from "./settings-manager.js";
+import { createSyntheticSourceInfo } from "./source-info.js";
+import { buildReflexUserPrompt, parseReflexPlan, REFLEX_INTERPRETER_SYSTEM_PROMPT, } from "./toolkit/reflex-interpreter.js";
+import { executeToolkitScript } from "./toolkit/script-runner.js";
+import { createDelegateToolDefinition } from "./tools/delegate.js";
+import { createGoalToolDefinition } from "./tools/goal.js";
+import { createAllToolDefinitions } from "./tools/index.js";
+import { createModelFitnessToolDefinition } from "./tools/model-fitness.js";
+import { createRunToolkitScriptToolDefinition } from "./tools/run-toolkit-script.js";
+import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
+/**
+ * Owns the tool-registry build and the self-modification-safe extension reload extracted from
+ * {@link AgentSession}. See the module header for the snapshot-ownership and host-binding boundaries.
+ */
+export class RuntimeBuilder {
+    // Tool registry for extension getTools/setTools
+    _toolRegistry = new Map();
+    _toolDefinitions = new Map();
+    _toolPromptSnippets = new Map();
+    _toolPromptGuidelines = new Map();
+    _baseToolDefinitions = new Map();
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Whether a tool name is present in the live wrapped registry. */
+    hasTool(name) {
+        return this._toolRegistry.has(name);
+    }
+    /** The live wrapped tool for a name, if registered (activation lookup). */
+    getRegisteredTool(name) {
+        return this._toolRegistry.get(name);
+    }
+    /** A registered tool's normalized prompt snippet, if any. */
+    getToolPromptSnippet(name) {
+        return this._toolPromptSnippets.get(name);
+    }
+    /** A registered tool's normalized prompt guidelines, if any. */
+    getToolPromptGuidelines(name) {
+        return this._toolPromptGuidelines.get(name);
+    }
+    /**
+     * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
+     */
+    getAllTools() {
+        return Array.from(this._toolDefinitions.values()).map(({ definition, sourceInfo }) => ({
+            name: definition.name,
+            description: definition.description,
+            parameters: definition.parameters,
+            promptGuidelines: definition.promptGuidelines,
+            sourceInfo,
+        }));
+    }
+    getToolDefinition(name) {
+        return this._toolDefinitions.get(name)?.definition;
+    }
+    refreshToolRegistry(options) {
+        const previousRegistryNames = new Set(this._toolRegistry.keys());
+        // Re-derive from the pre-filter REQUEST, never from agent.state.tools: the active set is
+        // capability/profile-filtered, so feeding it back through setActiveToolsByName would
+        // permanently shrink what a later switch to a larger model (or permissive profile) restores.
+        const previousActiveToolNames = this.deps.getRequestedActiveToolNames() ?? this.deps.getActiveToolNames();
+        const allowedToolNames = this.deps.getAllowedToolNames();
+        const excludedToolNames = this.deps.getExcludedToolNames();
+        const toolProfileFilter = this.deps.getToolProfileFilter();
+        const isAllowedTool = (name) => {
+            if (allowedToolNames && !allowedToolNames.has(name))
+                return false;
+            if (excludedToolNames?.has(name))
+                return false;
+            if (!toolProfileFilter)
+                return true;
+            if (toolProfileFilter.allow.length > 0 && !matchesResourceProfilePattern(name, toolProfileFilter.allow)) {
+                return false;
+            }
+            if (matchesResourceProfilePattern(name, toolProfileFilter.block))
+                return false;
+            return true;
+        };
+        const registeredTools = this.deps.getExtensionRunner().getAllRegisteredTools();
+        const allCustomTools = [
+            ...registeredTools,
+            ...this.deps.getCustomTools().map((definition) => ({
+                definition,
+                sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
+            })),
+            // Memory subsystem provider tools (e.g. file-store's `memory` tool).
+            ...this.deps
+                .getMemoryManager()
+                .getToolDefinitions()
+                .map((definition) => ({
+                definition,
+                sourceInfo: createSyntheticSourceInfo(`<memory:${definition.name}>`, { source: "sdk" }),
+            })),
+        ].filter((tool) => isAllowedTool(tool.definition.name));
+        const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
+            .filter(([name]) => isAllowedTool(name))
+            .map(([name, definition]) => [
+            name,
+            {
+                definition,
+                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
+            },
+        ]));
+        for (const tool of allCustomTools) {
+            definitionRegistry.set(tool.definition.name, {
+                definition: tool.definition,
+                sourceInfo: tool.sourceInfo,
+            });
+        }
+        this._toolDefinitions = definitionRegistry;
+        this._toolPromptSnippets = new Map(Array.from(definitionRegistry.values())
+            .map(({ definition }) => {
+            const snippet = this.deps.normalizePromptSnippet(definition.promptSnippet);
+            return snippet ? [definition.name, snippet] : undefined;
+        })
+            .filter((entry) => entry !== undefined));
+        this._toolPromptGuidelines = new Map(Array.from(definitionRegistry.values())
+            .map(({ definition }) => {
+            const guidelines = this.deps.normalizePromptGuidelines(definition.promptGuidelines);
+            return guidelines.length > 0 ? [definition.name, guidelines] : undefined;
+        })
+            .filter((entry) => entry !== undefined));
+        const runner = this.deps.getExtensionRunner();
+        const wrappedExtensionTools = wrapRegisteredTools(allCustomTools, runner);
+        const wrappedBuiltInTools = wrapRegisteredTools(Array.from(this._baseToolDefinitions.values())
+            .filter((definition) => isAllowedTool(definition.name))
+            .map((definition) => ({
+            definition,
+            sourceInfo: createSyntheticSourceInfo(`<builtin:${definition.name}>`, { source: "builtin" }),
+        })), runner);
+        const toolRegistry = new Map(wrappedBuiltInTools.map((tool) => [tool.name, tool]));
+        for (const tool of wrappedExtensionTools) {
+            toolRegistry.set(tool.name, tool);
+        }
+        this._toolRegistry = toolRegistry;
+        const requestedBase = options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames];
+        const nextActiveToolNames = requestedBase.filter((name) => isAllowedTool(name));
+        const autoActivated = [];
+        if (allowedToolNames) {
+            for (const toolName of this._toolRegistry.keys()) {
+                if (allowedToolNames.has(toolName)) {
+                    nextActiveToolNames.push(toolName);
+                    autoActivated.push(toolName);
+                }
+            }
+        }
+        else if (options?.includeAllExtensionTools) {
+            for (const tool of wrappedExtensionTools) {
+                nextActiveToolNames.push(tool.name);
+                autoActivated.push(tool.name);
+            }
+        }
+        else if (!options?.activeToolNames) {
+            for (const toolName of this._toolRegistry.keys()) {
+                if (!previousRegistryNames.has(toolName)) {
+                    nextActiveToolNames.push(toolName);
+                    autoActivated.push(toolName);
+                }
+            }
+        }
+        // Strict UAC: the active profile is the COMPLETE grant, so a tool the profile names
+        // explicitly is itself a request for that tool — it must ACTIVATE from the registry even
+        // if the session never requested it. Without this, activation is only ever the requested
+        // defaults ∩ allow-list, and a profile granting non-default tools (a search-only profile's
+        // grep/find) yields an empty or truncated tool set on load and /reload. A blanket "*"
+        // stays grant-only: activation then still derives from the request/defaults above.
+        const explicitAllowPatterns = toolProfileFilter?.allow.filter((pattern) => pattern !== "*") ?? [];
+        if (explicitAllowPatterns.length > 0) {
+            const boundPatterns = new Set();
+            for (const toolName of this._toolRegistry.keys()) {
+                if (!isAllowedTool(toolName))
+                    continue;
+                for (const pattern of explicitAllowPatterns) {
+                    if (matchesResourceProfilePattern(toolName, [pattern]))
+                        boundPatterns.add(pattern);
+                }
+                if (matchesResourceProfilePattern(toolName, explicitAllowPatterns)) {
+                    nextActiveToolNames.push(toolName);
+                    autoActivated.push(toolName);
+                }
+            }
+            // G13: an explicit grant that binds to NO registered tool is a silent no-op — typo'd
+            // name, or the owning extension is not granted/loaded. Surface it.
+            this.deps.setUnboundToolGrantWarnings(explicitAllowPatterns
+                .filter((pattern) => !boundPatterns.has(pattern))
+                .map((pattern) => `profile tool grant "${pattern}" binds to no registered tool (typo, or the owning extension is not granted/loaded)`));
+        }
+        else {
+            this.deps.setUnboundToolGrantWarnings([]);
+        }
+        // artifact_retrieve companion auto-activation is enforced inside
+        // setActiveToolsByName() itself (not duplicated here), so every activation path --
+        // including the public, extension-exposed setActiveTools() -- gets the same
+        // guarantee, not just this settings/profile refresh flow.
+        this.deps.setActiveToolsByName([...new Set(nextActiveToolNames)]);
+        // setActiveToolsByName just stored the profile-filtered ACTIVE set as the request; restore
+        // the true pre-filter request (plus this refresh's auto-activations) so an internal refresh
+        // can never permanently narrow it.
+        this.deps.setRequestedActiveToolNames([...new Set([...requestedBase, ...autoActivated])]);
+    }
+    _createReloadRuntimeSnapshot() {
+        const agent = this.deps.getAgent();
+        return {
+            extensionRunner: this.deps.getExtensionRunner(),
+            baseToolDefinitions: this._baseToolDefinitions,
+            toolRegistry: this._toolRegistry,
+            toolDefinitions: this._toolDefinitions,
+            toolPromptSnippets: this._toolPromptSnippets,
+            toolPromptGuidelines: this._toolPromptGuidelines,
+            agentTools: agent.state.tools,
+            agentSystemPrompt: agent.state.systemPrompt,
+            baseSystemPrompt: this.deps.getBaseSystemPrompt(),
+        };
+    }
+    _restoreReloadRuntimeSnapshot(snapshot) {
+        // setExtensionRunner restores both _extensionRunner and _extensionRunnerRef.current together
+        // (the same field-then-ref pair the host wrote at every assignment site); nothing reads the
+        // ref between the two writes, so folding them is unobservable.
+        this.deps.setExtensionRunner(snapshot.extensionRunner);
+        this._baseToolDefinitions = snapshot.baseToolDefinitions;
+        this._toolRegistry = snapshot.toolRegistry;
+        this._toolDefinitions = snapshot.toolDefinitions;
+        this._toolPromptSnippets = snapshot.toolPromptSnippets;
+        this._toolPromptGuidelines = snapshot.toolPromptGuidelines;
+        const agent = this.deps.getAgent();
+        agent.state.tools = snapshot.agentTools;
+        agent.state.systemPrompt = snapshot.agentSystemPrompt;
+        this.deps.setBaseSystemPrompt(snapshot.baseSystemPrompt);
+        this.deps.applyExtensionBindings(snapshot.extensionRunner);
+    }
+    _doctorReloadRuntime() {
+        const extensionErrors = this.deps.getResourceLoader().getExtensions().errors;
+        if (extensionErrors.length > 0) {
+            const summary = extensionErrors
+                .slice(0, 6)
+                .map((error) => `${error.path}: ${error.error}`)
+                .join("; ");
+            throw new Error(`Extension reload failed doctor: ${summary}`);
+        }
+        const missingActiveTools = this.deps.getActiveToolNames().filter((name) => !this._toolRegistry.has(name));
+        if (missingActiveTools.length > 0) {
+            throw new Error(`Extension reload failed doctor: active tool(s) missing after reload: ${missingActiveTools.join(", ")}`);
+        }
+        for (const tool of this.deps.getAgent().state.tools) {
+            if (!this._toolDefinitions.has(tool.name)) {
+                throw new Error(`Extension reload failed doctor: tool ${tool.name} missing from definition registry`);
+            }
+        }
+        this.deps.createAgentContextSnapshot();
+        this.deps.getContextUsage();
+    }
+    buildRuntime(options) {
+        const settingsManager = this.deps.getSettingsManager();
+        const autoResizeImages = settingsManager.getImageAutoResize();
+        const shellCommandPrefix = settingsManager.getShellCommandPrefix();
+        const shellPath = settingsManager.getShellPath();
+        const baseToolsOverride = this.deps.getBaseToolsOverride();
+        // grep/find must not emit a "Full output: artifact tool-output:<id>" handle that
+        // nothing can resolve. If artifact_retrieve is explicitly excluded/blocked/outside
+        // an active allowlist, don't hand grep/find an artifact store at all: they fall
+        // back to their pre-existing bounded preview/truncation behavior, with no
+        // payload/meta files ever written and no retrieval promise made.
+        const toolArtifactStore = this.deps.isToolOrCommandAllowedByProfile("artifact_retrieve")
+            ? this.deps.getToolArtifactStore()
+            : undefined;
+        const baseToolDefinitions = baseToolsOverride
+            ? Object.fromEntries(Object.entries(baseToolsOverride).map(([name, tool]) => [name, createToolDefinitionFromAgentTool(tool)]))
+            : createAllToolDefinitions(this.deps.getCwd(), {
+                read: { autoResizeImages },
+                bash: { commandPrefix: shellCommandPrefix, shellPath },
+                grep: { artifactStore: toolArtifactStore },
+                find: { artifactStore: toolArtifactStore },
+                artifact_retrieve: { artifactStore: toolArtifactStore },
+            });
+        this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
+        if (!baseToolsOverride) {
+            for (const definition of createCoreDiagnosticsToolDefinitions(() => this.deps.getActiveToolNames(), () => this.getAllTools(), (messages) => this.deps.getContextGcReport(messages), () => this.deps.getMemoryAuditDiagnostics())) {
+                this._baseToolDefinitions.set(definition.name, definition);
+            }
+            const goalToolDefinition = createGoalToolDefinition({
+                getGoalState: () => this.deps.getGoalStateSnapshot(),
+                saveGoalState: (state) => {
+                    this.deps.saveGoalStateSnapshot(state);
+                },
+            });
+            this._baseToolDefinitions.set(goalToolDefinition.name, goalToolDefinition);
+            const delegateToolDefinition = createDelegateToolDefinition({
+                runWorkerDelegation: (args) => this.deps.runWorkerDelegationOnce(args),
+            });
+            this._baseToolDefinitions.set(delegateToolDefinition.name, delegateToolDefinition);
+            // Registered but not default-active: probes spend tokens on the probed model, so
+            // activation is an explicit choice (settings/profile/setActiveTools or /autonomy fitness).
+            const modelFitnessToolDefinition = createModelFitnessToolDefinition({
+                runProbe: (args) => this.deps.runModelFitness(args),
+            });
+            this._baseToolDefinitions.set(modelFitnessToolDefinition.name, modelFitnessToolDefinition);
+            const runToolkitScriptToolDefinition = createRunToolkitScriptToolDefinition({
+                getScripts: () => this.deps.getSettingsManager().getToolkitScripts(),
+                execute: (script, scriptArgs) => executeToolkitScript({ script, scriptArgs, cwd: this.deps.getCwd() }),
+                // Reflex brain (fitness-gated local model): resolves ambiguous requests into a
+                // registry pick. Best-effort — absent/unfit brain keeps the shortlist behavior.
+                interpret: async (request, scripts) => {
+                    const model = this.deps.resolveCurationModelIfFit();
+                    if (!model)
+                        return undefined;
+                    const completion = await this.deps.runIsolatedCompletion({
+                        systemPrompt: REFLEX_INTERPRETER_SYSTEM_PROMPT,
+                        messages: [
+                            {
+                                role: "user",
+                                content: [{ type: "text", text: buildReflexUserPrompt(request, scripts) }],
+                                timestamp: Date.now(),
+                            },
+                        ],
+                        model,
+                        thinkingLevel: "off",
+                        maxTokens: 256,
+                        cacheRetention: "short",
+                    });
+                    if (completion.usage.cost.total > 0 || completion.usage.totalTokens > 0) {
+                        this.deps.addSpawnedUsage(completion.usage, { label: "toolkit-brain" });
+                    }
+                    return parseReflexPlan(completion.text);
+                },
+            });
+            this._baseToolDefinitions.set(runToolkitScriptToolDefinition.name, runToolkitScriptToolDefinition);
+        }
+        const extensionsResult = this.deps.getResourceLoader().getExtensions();
+        if (options.flagValues) {
+            for (const [name, value] of options.flagValues) {
+                extensionsResult.runtime.flagValues.set(name, value);
+            }
+        }
+        const extensions = this.deps.filterExtensionsForRuntime(extensionsResult.extensions);
+        const runtimeExtensionPaths = new Set(extensions.map((extension) => extension.path));
+        extensionsResult.runtime.pendingProviderRegistrations =
+            extensionsResult.runtime.pendingProviderRegistrations.filter((registration) => runtimeExtensionPaths.has(registration.extensionPath));
+        const runner = new ExtensionRunner(extensions, extensionsResult.runtime, this.deps.getCwd(), this.deps.getSessionManager(), this.deps.getModelRegistry());
+        this.deps.setExtensionRunner(runner);
+        this.deps.bindExtensionCore(runner);
+        this.deps.applyExtensionBindings(runner);
+        const defaultActiveToolNames = baseToolsOverride
+            ? Object.keys(baseToolsOverride)
+            : ["read", "bash", "edit", "write", "context_audit", "goal", "delegate", "run_toolkit_script"];
+        const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
+        this.refreshToolRegistry({
+            activeToolNames: baseActiveToolNames,
+            includeAllExtensionTools: options.includeAllExtensionTools,
+        });
+    }
+    async reload() {
+        if (this.deps.isStreaming()) {
+            throw new Error("Cannot reload while the agent is streaming or a tool call is active");
+        }
+        if (this.deps.isCompacting()) {
+            throw new Error("Cannot reload while context compaction or branch summarization is active");
+        }
+        const previousRunner = this.deps.getExtensionRunner();
+        const snapshot = this._createReloadRuntimeSnapshot();
+        // Preserve the pre-filter tool REQUEST across the rebuild, not the capability/profile-filtered
+        // active set — otherwise a reload under a small model permanently shrinks the restorable set.
+        const activeToolNames = this.deps.getRequestedActiveToolNames() ?? this.deps.getActiveToolNames();
+        const previousFlagValues = previousRunner.getFlagValues();
+        const reloadErrors = [];
+        let newRunner;
+        try {
+            await this.deps.getSettingsManager().reload();
+            // Re-derive the resource-profile tool filter from the freshly reloaded settings.
+            // Unlike skills/prompts/themes (which re-filter through the resource loader on every
+            // reload), the tool filter is held on the session, so without this a live edit to the
+            // active profile's tools allow/block — or switching the active profile — would not
+            // apply on /reload and allowed tools would stay missing.
+            this.deps.setToolProfileFilter(this.deps.deriveToolProfileFilter());
+            // Re-apply the active profile's model/thinking from the freshly reloaded settings, so a live
+            // profile edit (or switch) takes effect on /reload. Skipped when the launch used an explicit
+            // --model/--thinking flag, which must win over the profile across reloads.
+            await this.deps.reapplyActiveProfileModelSettings();
+            await this.deps.getResourceLoader().reload({ failOnExtensionErrors: true, deferExtensionDispose: true });
+            resetApiProviders();
+            this.buildRuntime({
+                activeToolNames,
+                flagValues: previousFlagValues,
+                includeAllExtensionTools: true,
+            });
+            newRunner = this.deps.getExtensionRunner();
+            const offDoctorErrors = newRunner.onError((error) => {
+                reloadErrors.push(`${error.extensionPath} ${error.event}: ${error.error}`);
+            });
+            try {
+                this._doctorReloadRuntime();
+                // Reload starts memory providers fresh; loaded extensions re-register below.
+                this.deps.clearPendingMemoryProviders();
+                const hasBindings = this.deps.getExtensionUIContext() ||
+                    this.deps.getExtensionCommandContextActions() ||
+                    this.deps.getExtensionShutdownHandler() ||
+                    this.deps.getExtensionErrorListener();
+                if (hasBindings) {
+                    await newRunner.emit({ type: "session_start", reason: "reload" });
+                    await this.deps.extendResourcesFromExtensions("reload");
+                    this._doctorReloadRuntime();
+                }
+            }
+            finally {
+                offDoctorErrors();
+            }
+            if (reloadErrors.length > 0) {
+                throw new Error(`Extension reload failed doctor: ${reloadErrors.slice(0, 6).join("; ")}`);
+            }
+            await emitSessionShutdownEvent(previousRunner, { type: "session_shutdown", reason: "reload" });
+            previousRunner.invalidate();
+            this.deps.getResourceLoader().commitReload?.();
+            // Re-derive the memory subsystem from the reloaded settings/providers.
+            await this.deps.initializeMemory();
+        }
+        catch (error) {
+            if (newRunner && newRunner !== previousRunner) {
+                newRunner.invalidate("This extension ctx was discarded because reload failed and Pi restored the previous valid runtime.");
+            }
+            this.deps.getResourceLoader().rollbackReload?.();
+            this._restoreReloadRuntimeSnapshot(snapshot);
+            throw error;
+        }
+    }
+    /**
+     * Unload a single extension without full reload.
+     * Runs the extension's session_shutdown lifecycle, unregisters its providers,
+     * disposes its event subscriptions, and rebuilds the runtime.
+     * Falls back to full reload on error.
+     */
+    async unloadExtensionLive(extensionPath) {
+        if (this.deps.isStreaming()) {
+            throw new Error("Cannot unload extension while the agent is streaming or a tool call is active");
+        }
+        if (this.deps.isCompacting()) {
+            throw new Error("Cannot unload extension while context compaction or branch summarization is active");
+        }
+        const ext = this.deps.getResourceLoader().getLoadedExtension(extensionPath);
+        if (!ext) {
+            return; // Nothing to unload
+        }
+        const previousRunner = this.deps.getExtensionRunner();
+        try {
+            // Run session_shutdown lifecycle for this extension only
+            await this.deps.getExtensionRunner().emitToExtension(ext, { type: "session_shutdown", reason: "unload" });
+            // Unregister its providers (keyed by the extension's own path, as registered)
+            const runtime = this.deps.getResourceLoader().getExtensions().runtime;
+            for (const name of runtime.getProvidersForExtension(ext.path)) {
+                runtime.unregisterProvider(name, ext.path);
+            }
+            // Dispose its event subscriptions and run disposers
+            await disposeExtensionEventSubscriptions([ext]);
+            // Remove from loaded extensions
+            this.deps.getResourceLoader().removeLoadedExtension(extensionPath);
+            // Rebuild runtime with new extension set
+            const activeToolNames = this.deps.getRequestedActiveToolNames() ?? this.deps.getActiveToolNames();
+            const previousFlagValues = previousRunner.getFlagValues();
+            this.buildRuntime({
+                activeToolNames,
+                flagValues: previousFlagValues,
+                includeAllExtensionTools: true,
+            });
+            previousRunner.invalidate();
+            // Notify extensions-changed listeners
+            this.deps.notifyExtensionsChanged();
+        }
+        catch (error) {
+            // Fall back to full reload on error
+            try {
+                await this.reload();
+            }
+            catch {
+                // Suppress nested error; original error will be thrown below
+            }
+            throw error;
+        }
+    }
+    /**
+     * Load a single extension without full reload.
+     * Loads the extension with fresh import, rebuilds the runtime,
+     * and runs the extension's session_start lifecycle.
+     * Falls back to full reload on error.
+     */
+    async loadExtensionLive(extensionPath) {
+        if (this.deps.isStreaming()) {
+            throw new Error("Cannot load extension while the agent is streaming or a tool call is active");
+        }
+        if (this.deps.isCompacting()) {
+            throw new Error("Cannot load extension while context compaction or branch summarization is active");
+        }
+        const previousRunner = this.deps.getExtensionRunner();
+        try {
+            // Load the extension with fresh import
+            const { extension, error } = await this.deps.getResourceLoader().loadSingleExtension(extensionPath);
+            if (error || !extension) {
+                throw new Error(error || `Failed to load extension: ${extensionPath}`);
+            }
+            // Rebuild runtime to aggregate tools/commands/handlers/providers
+            const activeToolNames = this.deps.getRequestedActiveToolNames() ?? this.deps.getActiveToolNames();
+            const previousFlagValues = previousRunner.getFlagValues();
+            this.buildRuntime({
+                activeToolNames,
+                flagValues: previousFlagValues,
+                includeAllExtensionTools: true,
+            });
+            // Run session_start lifecycle for the new extension only
+            await this.deps.getExtensionRunner().emitToExtension(extension, { type: "session_start", reason: "load" });
+            // Notify extensions-changed listeners
+            this.deps.notifyExtensionsChanged();
+        }
+        catch (error) {
+            // Fall back to full reload on error
+            try {
+                await this.reload();
+            }
+            catch {
+                // Suppress nested error; original error will be thrown below
+            }
+            throw error;
+        }
+    }
+    /**
+     * Reconcile loaded extensions with the active profile.
+     * Loads extensions that should be enabled but aren't, and unloads extensions that shouldn't be.
+     * Falls back to full reload if any individual load/unload fails.
+     */
+    async reconcileLoadedExtensions() {
+        if (this.deps.isStreaming()) {
+            throw new Error("Cannot reconcile extensions while the agent is streaming or a tool call is active");
+        }
+        if (this.deps.isCompacting()) {
+            throw new Error("Cannot reconcile extensions while context compaction or branch summarization is active");
+        }
+        try {
+            // Get all discoverable extension paths
+            const allDiscoverablePaths = await this.deps.getResourceLoader().getDiscoverableExtensionPaths();
+            // Get the target enabled set based on profile filters
+            const targetEnabledSet = new Set();
+            for (const path of allDiscoverablePaths) {
+                if (this.deps.getSettingsManager().isResourceAllowedByProfile("extensions", path)) {
+                    targetEnabledSet.add(path);
+                }
+            }
+            // Get currently loaded set
+            const loadedExtensions = this.deps.getResourceLoader().getExtensions().extensions;
+            const loadedSet = new Set();
+            for (const ext of loadedExtensions) {
+                loadedSet.add(ext.path);
+            }
+            // Collect unloads and loads
+            const toUnload = [];
+            const toLoad = [];
+            for (const path of loadedSet) {
+                if (!targetEnabledSet.has(path)) {
+                    toUnload.push(path);
+                }
+            }
+            for (const path of targetEnabledSet) {
+                if (!loadedSet.has(path)) {
+                    toLoad.push(path);
+                }
+            }
+            // Apply unloads first, then loads, to minimize churn
+            // Collect errors but continue through all operations
+            const errors = [];
+            for (const path of toUnload) {
+                try {
+                    await this.unloadExtensionLive(path);
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            for (const path of toLoad) {
+                try {
+                    await this.loadExtensionLive(path);
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            // If any errors occurred, throw the first one (already fell back to full reload in load/unload)
+            if (errors.length > 0) {
+                throw errors[0];
+            }
+            // Single notification at the end
+            this.deps.notifyExtensionsChanged();
+        }
+        catch (error) {
+            // Fall back to full reload on error
+            try {
+                await this.reload();
+            }
+            catch {
+                // Suppress nested error; original error will be thrown below
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=runtime-builder.js.map