// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

import {
    AppAgent,
    SessionContext,
    AppAgentManifest,
    AppAgentInitSettings,
} from "@typeagent/agent-sdk";
import { CommandHandlerContext } from "./commandHandlerContext.js";
import {
    convertToActionConfig,
    ActionConfig,
    getGrammarContent,
} from "../translation/actionConfig.js";
import {
    ActionConfigProvider,
    ActionSchemaFile,
} from "../translation/actionConfigProvider.js";
import { getAppAgentName } from "../translation/agentTranslators.js";
import { createSessionContext } from "../execute/sessionContext.js";
import { AppAgentProvider } from "../agentProvider/agentProvider.js";
import registerDebug from "debug";
import { DispatcherName } from "./dispatcher/dispatcherUtils.js";
import {
    ActionSchemaSemanticMap,
    EmbeddingCache,
} from "../translation/actionSchemaSemanticMap.js";
import { ActionSchemaFileCache } from "../translation/actionSchemaFileCache.js";
import path from "node:path";
import { callEnsureError } from "../utils/exceptions.js";
import {
    AppAgentStateConfig,
    appAgentStateKeys,
} from "./appAgentStateConfig.js";
import { GrammarStore } from "agent-cache";
import {
    Grammar,
    grammarFromJson,
    AgentGrammarRegistry,
    compileGrammarToNFA,
    enrichGrammarWithCheckedVariables,
    loadGrammarRulesNoThrow,
} from "action-grammar";
import fs from "node:fs";
import { FlowDefinition } from "../execute/flowInterpreter.js";

const debug = registerDebug("typeagent:dispatcher:agents");
const debugError = registerDebug("typeagent:dispatcher:agents:error");
const debugLoad = registerDebug("typeagent:dispatcher:agents:load");

type AppAgentRecord = {
    name: string;
    provider?: AppAgentProvider | undefined;
    schemas: Set<string>;
    actions: Set<string>;
    commands: boolean;
    manifest: AppAgentManifest;
    appAgent?: AppAgent | undefined;
    sessionContext?: SessionContext | undefined;
    sessionContextP?: Promise<SessionContext> | undefined;
    schemaErrors: Map<string, Error>;
    port?: number | undefined;
};

export type AppAgentStateSettings = Partial<AppAgentStateConfig>;

function computeStateChange(
    settings: AppAgentStateSettings | undefined,
    kind: keyof AppAgentStateConfig,
    name: string,
    defaultEnabled: boolean,
    failed: [string, boolean, Error][],
) {
    const alwaysEnabled = alwaysEnabledAgents[kind].includes(name);
    const effectiveEnabled = settings?.[kind]?.[name] ?? defaultEnabled;
    if (alwaysEnabled && !effectiveEnabled) {
        failed.push([
            name,
            effectiveEnabled,
            new Error(`Cannot disable ${kind} for '${name}'`),
        ]);
    }
    return alwaysEnabled || effectiveEnabled;
}

export type SetStateResult = {
    changed: {
        schemas: [string, boolean][];
        actions: [string, boolean][];
        commands: [string, boolean][];
    };
    failed: {
        schemas: [string, boolean, Error][];
        actions: [string, boolean, Error][];
        commands: [string, boolean, Error][];
    };
};

export const alwaysEnabledAgents = {
    schemas: [DispatcherName],
    actions: [DispatcherName],
    commands: ["system"],
};

function loadGrammar(actionConfig: ActionConfig): Grammar | undefined {
    const grammarContent = getGrammarContent(actionConfig);
    if (grammarContent === undefined) {
        return undefined;
    }

    if (grammarContent.format !== "ag") {
        throw new Error(
            `Unsupported grammar file extension: ${actionConfig.grammarFile}`,
        );
    }
    return grammarFromJson(JSON.parse(grammarContent.content));
}

export class AppAgentManager implements ActionConfigProvider {
    private readonly agents = new Map<string, AppAgentRecord>();
    private readonly actionConfigs = new Map<string, ActionConfig>();
    private readonly loadingSchemas = new Set<string>();
    private readonly flowRegistry = new Map<string, FlowDefinition>();
    private readonly transientAgents: Record<string, boolean | undefined> = {};
    private readyWaiters: Array<() => void> = [];
    private readonly actionSemanticMap?: ActionSchemaSemanticMap;
    private readonly actionSchemaFileCache: ActionSchemaFileCache;
    public constructor(
        cacheDir: string | undefined,
        private readonly allowSharedLocalView?: string[],
        private readonly agentInitOptions?: Record<string, unknown>,
    ) {
        this.actionSchemaFileCache = new ActionSchemaFileCache(
            cacheDir
                ? path.join(cacheDir, "actionSchemaFileCache.json")
                : undefined,
        );

        try {
            this.actionSemanticMap = new ActionSchemaSemanticMap();
        } catch (e) {
            if (process.env.NODE_ENV !== "test") {
                console.log("Failed to create action semantic map", e);
            }
        }
    }
    public getAppAgentNames(): string[] {
        return Array.from(this.agents.keys());
    }

    public isSchemaLoading(schemaName: string): boolean {
        return this.loadingSchemas.has(schemaName);
    }

    public getAppAgentDescription(appAgentName: string) {
        const record = this.getRecord(appAgentName);
        return record.manifest.description;
    }

    public getAppAgentEmoji(appAgentName: string) {
        const record = this.getRecord(appAgentName);
        return record.manifest.emojiChar;
    }

    public getLocalHostPort(appAgentName: string) {
        const record = this.getRecord(appAgentName);
        return record.port;
    }

    public setLocalHostPort(appAgentName: string, port: number) {
        const record = this.getRecord(appAgentName);
        record.port = port;
        debug(`Port ${port} assigned to ${appAgentName}`);
    }

    public getSharedLocalHostPort(requester: string, target: string) {
        const record = this.agents.get(target);

        // Denied access if it is not a valid agent name to avoid leaking information
        // about whether agent exists or not.
        if (
            record === undefined ||
            (!this.allowSharedLocalView?.includes(requester) && // host declare allowed agents to share
                record.manifest.sharedLocalView?.includes(requester) !== true) // agent declared allowed agents to share.
        ) {
            throw new Error(
                `Agent '${requester}' is not allowed to access '${target}' local view.`,
            );
        }

        if (record.port === undefined) {
            throw new Error(`Local view not available for agent '${target}'.`);
        }

        if (record.appAgent === undefined) {
            throw new Error(
                `Agent '${target}' is not initialized. Local view not available.`,
            );
        }
        return record.port;
    }

    public isAppAgentName(appAgentName: string) {
        return this.agents.get(appAgentName) !== undefined;
    }

    public getFlow(
        schemaName: string,
        actionName: string,
    ): FlowDefinition | undefined {
        const appAgentName = getAppAgentName(schemaName);
        return this.flowRegistry.get(`${appAgentName}/${actionName}`);
    }

    // Throws if schemaName is invalid.
    public isSchemaEnabled(schemaName: string) {
        const appAgentName = getAppAgentName(schemaName);
        const record = this.getRecord(appAgentName);
        return record.schemas.has(schemaName);
    }

    // Throws if schemaName is invalid.
    public isSchemaActive(schemaName: string) {
        return (
            this.isSchemaEnabled(schemaName) &&
            this.transientAgents[schemaName] !== false
        );
    }

    public getActiveSchemas() {
        return this.getSchemaNames().filter((name) =>
            this.isSchemaActive(name),
        );
    }

    // Throws if schemaName is invalid.
    public isActionActive(schemaName: string) {
        return (
            this.isActionEnabled(schemaName) &&
            this.transientAgents[schemaName] !== false
        );
    }

    // Throws if schemaName is invalid.
    public isActionEnabled(schemaName: string) {
        const appAgentName = getAppAgentName(schemaName);
        const record = this.getRecord(appAgentName);
        return record.actions.has(schemaName);
    }

    // Throws if appAgentName is invalid.
    public isCommandEnabled(appAgentName: string) {
        const record = this.getRecord(appAgentName);
        return record.commands && record.appAgent?.executeCommand !== undefined;
    }

    // Return undefined if we don't know because the agent isn't loaded yet.
    // Return null if the agent doesn't support commands.
    // Throws if appAgentName is invalid.
    public getCommandEnabledState(appAgentName: string) {
        const record = this.getRecord(appAgentName);
        return record.appAgent !== undefined
            ? record.appAgent.executeCommand !== undefined
                ? record.commands
                : null
            : undefined;
    }

    public async semanticSearchActionSchema(
        request: string,
        maxMatches: number = 1,
        filter: (schemaName: string) => boolean = (schemaName) =>
            this.isSchemaActive(schemaName),
    ) {
        return this.actionSemanticMap?.nearestNeighbors(
            request,
            maxMatches,
            filter,
        );
    }

    public async addProvider(
        provider: AppAgentProvider,
        actionGrammarStore: GrammarStore | undefined,
        actionEmbeddingCache?: EmbeddingCache,
        agentGrammarRegistry?: AgentGrammarRegistry,
        useNFAGrammar?: boolean,
        stateRefreshFn?: () => Promise<void>,
    ) {
        const agentNames = provider.getAppAgentNames();
        const semanticMapP: Promise<void>[] = [];
        for (const name of agentNames) {
            const manifest = await provider.getAppAgentManifest(name);
            this.addAgentManifest(
                name,
                manifest,
                semanticMapP,

                actionGrammarStore,
                provider,
                actionEmbeddingCache,
                agentGrammarRegistry,
                useNFAGrammar,
            );
        }
        debug("Waiting for action embeddings");
        await Promise.all(semanticMapP);
        debug("Finish action embeddings");

        if (provider.onSchemaReady && stateRefreshFn) {
            // Mark only the agents that are actually loading asynchronously (e.g.
            // serverCommand MCP agents with slow startup).  Agents that failed
            // synchronously should show ❌, not ⏳.
            const loadingNames = new Set(
                provider.getLoadingAgentNames?.() ?? [],
            );
            for (const name of agentNames) {
                if (!loadingNames.has(name)) {
                    continue;
                }
                const record = this.agents.get(name);
                if (record) {
                    for (const schemaName of Object.keys(
                        convertToActionConfig(name, record.manifest),
                    )) {
                        this.loadingSchemas.add(schemaName);
                    }
                }
            }

            provider.onSchemaReady(async (agentName, manifest) => {
                try {
                    const refreshSemanticMapP: Promise<void>[] = [];
                    this.refreshAgentSchema(
                        agentName,
                        manifest,
                        refreshSemanticMapP,
                        actionGrammarStore,
                        actionEmbeddingCache,
                        agentGrammarRegistry,
                        useNFAGrammar,
                    );
                    await Promise.all(refreshSemanticMapP);
                    await stateRefreshFn();
                } catch (e) {
                    debugError(
                        `Failed to refresh schema for agent '${agentName}': ${e}`,
                    );
                }
            });
        }
    }

    private refreshAgentSchema(
        appAgentName: string,
        manifest: AppAgentManifest,
        semanticMapP: Promise<void>[],
        actionGrammarStore: GrammarStore | undefined,
        actionEmbeddingCache?: EmbeddingCache,
        agentGrammarRegistry?: AgentGrammarRegistry,
        useNFAGrammar?: boolean,
    ) {
        const record = this.agents.get(appAgentName);
        if (record === undefined) {
            throw new Error(`Agent not found: ${appAgentName}`);
        }

        // Update the manifest (emoji, schema, etc.)
        record.manifest = manifest;

        const actionConfigs = convertToActionConfig(appAgentName, manifest);
        for (const [schemaName, config] of Object.entries(actionConfigs)) {
            debug(`Refreshing action config: ${schemaName}`);
            this.actionConfigs.set(schemaName, config);
            if (config.transient) {
                this.transientAgents[schemaName] = false;
            }
            try {
                const actionSchemaFile =
                    this.actionSchemaFileCache.getActionSchemaFile(config);
                if (this.actionSemanticMap) {
                    semanticMapP.push(
                        this.actionSemanticMap.addActionSchemaFile(
                            config,
                            actionSchemaFile,
                            actionEmbeddingCache,
                        ),
                    );
                }
                record.schemaErrors.delete(schemaName);
                this.loadingSchemas.delete(schemaName);
            } catch (e: any) {
                record.schemaErrors.set(schemaName, e);
                this.loadingSchemas.delete(schemaName);
            } finally {
                this.notifyReadyIfDone();
            }
        }
    }

    private addAgentManifest(
        appAgentName: string,
        manifest: AppAgentManifest,
        semanticMapP: Promise<void>[],
        actionGrammarStore: GrammarStore | undefined,
        provider?: AppAgentProvider,
        actionEmbeddingCache?: EmbeddingCache,
        agentGrammarRegistry?: AgentGrammarRegistry,
        useNFAGrammar?: boolean,
    ) {
        if (this.isAppAgentName(appAgentName)) {
            throw new Error(`Conflicting app agents name '${appAgentName}'`);
        }
        const actionConfigs = convertToActionConfig(appAgentName, manifest);

        const entries = Object.entries(actionConfigs);
        const schemaErrors = new Map<string, Error>();

        for (const [schemaName, config] of entries) {
            debug(`Adding action config: ${schemaName}`);
            this.actionConfigs.set(schemaName, config);
            if (config.transient) {
                this.transientAgents[schemaName] = false;
            }
            try {
                const actionSchemaFile =
                    this.actionSchemaFileCache.getActionSchemaFile(config);

                if (this.actionSemanticMap) {
                    semanticMapP.push(
                        this.actionSemanticMap.addActionSchemaFile(
                            config,
                            actionSchemaFile,
                            actionEmbeddingCache,
                        ),
                    );
                }

                if (actionGrammarStore) {
                    let g: Grammar | undefined = undefined;

                    try {
                        g = loadGrammar(config);
                    } catch (e) {
                        // Grammar file doesn't exist or failed to load
                        debugError(
                            `Failed to load grammar for schema: ${schemaName}\n${e}`,
                        );
                    }

                    // If no grammar file exists but we're using NFA system, create an empty grammar
                    // This allows dynamic grammar generation to work for agents without pre-existing grammars
                    if (!g && useNFAGrammar && agentGrammarRegistry) {
                        debug(
                            `No grammar file found for ${schemaName}, creating empty grammar for dynamic generation`,
                        );
                        g = { alternatives: [] };
                    }

                    if (g) {
                        // In NFA mode, only add to agentGrammarRegistry (not actionGrammarStore)
                        // The merged grammar will be synced to the store later via syncAgentGrammar
                        if (useNFAGrammar && agentGrammarRegistry) {
                            debug(
                                `Adding grammar to NFA registry for schema: ${schemaName}`,
                            );
                        } else {
                            // In non-NFA mode, add directly to grammar store
                            debug(`Adding grammar for schema: ${schemaName}`);
                            actionGrammarStore.addGrammar(schemaName, g);
                        }

                        // Add to NFA grammar registry if using NFA system
                        if (useNFAGrammar && agentGrammarRegistry) {
                            try {
                                // Enrich grammar with checked variables from parsed schema
                                try {
                                    enrichGrammarWithCheckedVariables(
                                        g,
                                        actionSchemaFile.parsedActionSchema,
                                    );
                                    debug(
                                        `Enriched grammar with checked variables for schema: ${schemaName}`,
                                    );
                                } catch (enrichError) {
                                    debug(
                                        `Could not enrich grammar with checked variables for ${schemaName}: ${enrichError}`,
                                    );
                                }

                                const nfa = compileGrammarToNFA(g, schemaName);
                                agentGrammarRegistry.registerAgent(
                                    schemaName,
                                    g,
                                    nfa,
                                );
                                debug(
                                    `Added NFA grammar for schema: ${schemaName} (${g.alternatives.length} rules)`,
                                );
                            } catch (nfaError) {
                                debugError(
                                    `Failed to compile NFA for schema: ${schemaName}\n${nfaError}`,
                                );
                            }
                        }
                    }
                }
            } catch (e: any) {
                schemaErrors.set(schemaName, e);
            }
        }

        const port = manifest.localView ? 0 : undefined;

        if (port !== undefined) {
            debug(`Dynamic port (OS-assigned) reserved for ${appAgentName}`);
        }

        const record: AppAgentRecord = {
            name: appAgentName,
            provider,
            actions: new Set(),
            schemas: new Set(),
            schemaErrors,
            commands: false,
            manifest,
            port,
        };

        this.agents.set(appAgentName, record);

        // Load registered flow definitions from manifest
        if (manifest.flows) {
            for (const [actionName, flowPath] of Object.entries(
                manifest.flows,
            ) as [string, string][]) {
                try {
                    const content = fs.readFileSync(flowPath, "utf-8");
                    const flowDef: FlowDefinition = JSON.parse(content);
                    this.flowRegistry.set(
                        `${appAgentName}/${actionName}`,
                        flowDef,
                    );
                    debug(`Loaded flow: ${appAgentName}.${actionName}`);
                } catch (e) {
                    debugError(
                        `Failed to load flow '${actionName}' from '${flowPath}': ${e}`,
                    );
                }
            }
        }

        return record;
    }

    public async addDynamicAgent(
        appAgentName: string,
        manifest: AppAgentManifest,
        appAgent: AppAgent,
        actionGrammarStore?: GrammarStore,
    ) {
        if (this.agents.has(appAgentName)) {
            throw new Error(`App agent '${appAgentName}' already exists`);
        }

        // REVIEW: action embedding is not cached.
        const semanticMapP: Promise<void>[] = [];
        const record = this.addAgentManifest(
            appAgentName,
            manifest,
            semanticMapP,
            actionGrammarStore,
        );
        record.appAgent = appAgent;

        debug("Waiting for action embeddings");
        await Promise.all(semanticMapP);
        debug("Finish action embeddings");
    }

    private cleanupAgent(appAgentName: string, grammarStore?: GrammarStore) {
        const schemasToRemove: string[] = [];

        for (const [schemaName, config] of this.actionConfigs) {
            if (getAppAgentName(schemaName) !== appAgentName) {
                continue;
            }

            schemasToRemove.push(schemaName);

            try {
                this.actionSchemaFileCache.unloadActionSchemaFile(schemaName);
            } catch (error) {
                console.warn(
                    `Failed to unload schema file ${schemaName}:`,
                    error,
                );
            }

            try {
                this.actionSemanticMap?.removeActionSchemaFile(schemaName);
            } catch (error) {
                console.warn(
                    `Failed to remove from semantic map ${schemaName}:`,
                    error,
                );
            }

            if (grammarStore) {
                try {
                    grammarStore.removeGrammar(schemaName);
                } catch (error) {
                    console.warn(
                        `Failed to remove grammar ${schemaName}:`,
                        error,
                    );
                }
            }

            if (config.transient) {
                delete this.transientAgents[schemaName];
            }
        }

        for (const schemaName of schemasToRemove) {
            this.actionConfigs.delete(schemaName);
        }
    }

    public async forceCleanupAgent(
        appAgentName: string,
        grammarStore?: GrammarStore,
    ): Promise<void> {
        console.warn(`Force cleanup for agent: ${appAgentName}`);

        const schemas = Array.from(this.actionConfigs.keys()).filter(
            (name) => getAppAgentName(name) === appAgentName,
        );

        for (const schemaName of schemas) {
            try {
                this.actionSchemaFileCache.unloadActionSchemaFile(schemaName);
            } catch (e) {
                console.warn(`Force cleanup schema file failed:`, e);
            }

            try {
                this.actionSemanticMap?.removeActionSchemaFile(schemaName);
            } catch (e) {
                console.warn(`Force cleanup semantic map failed:`, e);
            }

            if (grammarStore) {
                try {
                    grammarStore.removeGrammar(schemaName);
                } catch (e) {
                    console.warn(`Force cleanup grammar failed:`, e);
                }
            }

            try {
                const config = this.actionConfigs.get(schemaName);
                if (config?.transient) {
                    delete this.transientAgents[schemaName];
                }
            } catch (e) {
                console.warn(`Force cleanup transient failed:`, e);
            }

            try {
                this.actionConfigs.delete(schemaName);
            } catch (e) {
                console.warn(`Force cleanup config failed:`, e);
            }
        }

        try {
            this.agents.delete(appAgentName);
        } catch (e) {
            console.warn(`Force cleanup agent record failed:`, e);
        }

        console.warn(`Force cleanup complete for: ${appAgentName}`);
    }

    public async removeAgent(
        appAgentName: string,
        grammarStore?: GrammarStore,
    ) {
        // Check if agent exists before trying to remove it
        if (!this.isAppAgentName(appAgentName)) {
            debug(`Agent '${appAgentName}' does not exist, skipping removal`);
            return;
        }

        const record = this.getRecord(appAgentName);
        this.agents.delete(appAgentName);
        this.cleanupAgent(appAgentName, grammarStore);

        await this.closeSessionContext(record);
        if (record.appAgent !== undefined) {
            await record.provider?.unloadAppAgent(record.name);
        }
    }

    public getActionEmbeddings() {
        return this.actionSemanticMap?.embeddings();
    }
    public tryGetActionConfig(mayBeSchemaName: string) {
        return this.actionConfigs.get(mayBeSchemaName);
    }
    public getActionConfig(schemaName: string) {
        const config = this.tryGetActionConfig(schemaName);
        if (config === undefined) {
            throw new Error(`Unknown schema name: ${schemaName}`);
        }
        return config;
    }

    public getSchemaNames() {
        return Array.from(this.actionConfigs.keys());
    }
    public getActionConfigs() {
        return Array.from(this.actionConfigs.values());
    }

    /** Resolves immediately if no schemas are loading, otherwise waits until all pending async schema loads complete. */
    public waitUntilReady(): Promise<void> {
        if (this.loadingSchemas.size === 0) {
            return Promise.resolve();
        }
        return new Promise((resolve) => {
            this.readyWaiters.push(resolve);
        });
    }

    private notifyReadyIfDone(): void {
        if (this.loadingSchemas.size === 0 && this.readyWaiters.length > 0) {
            const waiters = this.readyWaiters.splice(0);
            for (const resolve of waiters) {
                resolve();
            }
        }
    }

    public getAppAgent(appAgentName: string): AppAgent {
        const record = this.getRecord(appAgentName);
        if (record.appAgent === undefined) {
            throw new Error(`App agent '${appAgentName}' is not initialized`);
        }
        return record.appAgent;
    }

    public getSessionContext(appAgentName: string): SessionContext {
        const record = this.getRecord(appAgentName);
        if (record.sessionContext === undefined) {
            throw new Error(
                `Session context for '${appAgentName}' is not initialized`,
            );
        }
        return record.sessionContext;
    }

    public async setState(
        context: CommandHandlerContext,
        settings?: AppAgentStateSettings,
    ): Promise<SetStateResult> {
        const changedSchemas: [string, boolean][] = [];
        const failedSchemas: [string, boolean, Error][] = [];
        const changedActions: [string, boolean][] = [];
        const failedActions: [string, boolean, Error][] = [];
        const changedCommands: [string, boolean][] = [];
        const failedCommands: [string, boolean, Error][] = [];

        const p: Promise<void>[] = [];
        for (const [name, config] of this.actionConfigs) {
            const record = this.getRecord(getAppAgentName(name));

            const enableSchema = computeStateChange(
                settings,
                "schemas",
                name,
                config.schemaDefaultEnabled,
                failedSchemas,
            );
            if (enableSchema !== record.schemas.has(name)) {
                if (enableSchema) {
                    if (this.loadingSchemas.has(name)) {
                        // Schema is still loading (e.g. slow MCP server start).
                        // Skip for now; refreshAgentSchema will re-run setState once ready.
                        debug(
                            `Schema '${name}' is still loading, skipping enable`,
                        );
                    } else {
                        const e = record.schemaErrors.get(name);
                        if (e !== undefined) {
                            failedSchemas.push([name, enableSchema, e]);
                            debugError(
                                `Schema '${name}' is not enabled because of error: ${e.message}`,
                            );
                        } else {
                            record.schemas.add(name);
                            changedSchemas.push([name, enableSchema]);
                            debug(`Schema enabled ${name}`);
                        }
                    }
                } else {
                    record.schemas.delete(name);
                    changedSchemas.push([name, enableSchema]);
                    debug(`Schema disabled ${name}`);
                }
            }

            const enableAction = computeStateChange(
                settings,
                "actions",
                name,
                config.actionDefaultEnabled,
                failedActions,
            );
            if (enableAction !== record.actions.has(name)) {
                if (enableAction && this.loadingSchemas.has(name)) {
                    // Action agent is still loading — skip to avoid blocking on server startup.
                    debug(`Action '${name}' is still loading, skipping enable`);
                } else {
                    p.push(
                        (async () => {
                            try {
                                await this.updateAction(
                                    name,
                                    record,
                                    enableAction,
                                    context,
                                );
                                changedActions.push([name, enableAction]);
                            } catch (e: any) {
                                failedActions.push([name, enableAction, e]);
                            }
                        })(),
                    );
                }
            }
        }

        for (const record of this.agents.values()) {
            const enableCommands = computeStateChange(
                settings,
                "commands",
                record.name,
                record.manifest.commandDefaultEnabled ??
                    record.manifest.defaultEnabled ??
                    true,
                failedCommands,
            );

            if (enableCommands !== record.commands) {
                if (enableCommands) {
                    p.push(
                        (async () => {
                            try {
                                await this.ensureSessionContext(
                                    record,
                                    context,
                                );
                                record.commands = true;
                                changedCommands.push([
                                    record.name,
                                    enableCommands,
                                ]);
                                debug(`Command enabled ${record.name}`);
                            } catch (e: any) {
                                failedCommands.push([
                                    record.name,
                                    enableCommands,
                                    e,
                                ]);
                            }
                        })(),
                    );
                } else {
                    debug(`Command disabled ${record.name}`);
                    record.commands = false;
                    changedCommands.push([record.name, enableCommands]);
                    await this.checkCloseSessionContext(record);
                }
            }
        }

        await Promise.all(p);
        return {
            changed: {
                schemas: changedSchemas,
                actions: changedActions,
                commands: changedCommands,
            },
            failed: {
                schemas: failedSchemas,
                actions: failedActions,
                commands: failedCommands,
            },
        };
    }

    public getTransientState(schemaName: string) {
        return this.transientAgents[schemaName];
    }

    public toggleTransient(schemaName: string, enable: boolean) {
        if (this.transientAgents[schemaName] === undefined) {
            throw new Error(`Transient sub agent not found: ${schemaName}`);
        }
        debug(
            `Toggle transient agent '${schemaName}' to ${enable ? "enabled" : "disabled"}`,
        );
        this.transientAgents[schemaName] = enable;
    }
    public async close() {
        const closeP: Promise<void>[] = [];
        for (const record of this.agents.values()) {
            closeP.push(
                (async () => {
                    await this.closeSessionContext(record);
                    record.actions.clear();
                    record.commands = false;
                    if (record.appAgent !== undefined) {
                        await record.provider?.unloadAppAgent(record.name);
                        record.appAgent = undefined;
                    }
                })(),
            );
        }
        await Promise.all(closeP);
    }

    private async loadDynamicGrammar(
        schemaName: string,
        appAgent: AppAgent,
        sessionContext: SessionContext,
        context: CommandHandlerContext,
    ): Promise<void> {
        let dynamicGrammar: Grammar | undefined;

        // Prefer the agent callback over file-based convention
        if (appAgent.getDynamicGrammar) {
            const grammarContent = await appAgent.getDynamicGrammar(
                sessionContext,
                schemaName,
            );
            if (grammarContent?.content?.trim()) {
                if (grammarContent.format === "ag") {
                    dynamicGrammar = grammarFromJson(
                        JSON.parse(grammarContent.content),
                    );
                } else {
                    // "agr" format — raw grammar rule text
                    const errors: string[] = [];
                    dynamicGrammar =
                        loadGrammarRulesNoThrow(
                            `${schemaName}-dynamic.agr`,
                            grammarContent.content,
                            errors,
                        ) ?? undefined;
                    if (errors.length > 0) {
                        debugError(
                            `Failed to parse dynamic grammar for ${schemaName}: ${errors.join(", ")}`,
                        );
                    }
                }
            }
        }

        // Fallback: read grammar/dynamic.agr from instance storage
        if (dynamicGrammar === undefined) {
            const instanceStorage = sessionContext.instanceStorage;
            if (instanceStorage) {
                try {
                    const agrText = await instanceStorage.read(
                        "grammar/dynamic.agr",
                        "utf8",
                    );
                    if (agrText?.trim()) {
                        const errors: string[] = [];
                        dynamicGrammar =
                            loadGrammarRulesNoThrow(
                                `${schemaName}-dynamic.agr`,
                                agrText,
                                errors,
                            ) ?? undefined;
                        if (errors.length > 0) {
                            debugError(
                                `Failed to parse dynamic grammar for ${schemaName}: ${errors.join(", ")}`,
                            );
                        }
                    }
                } catch {
                    // No dynamic grammar file
                }
            }
        }

        if (!dynamicGrammar || dynamicGrammar.alternatives.length === 0) return;

        const config = this.actionConfigs.get(schemaName);
        const staticGrammar = config ? loadGrammar(config) : undefined;

        const merged: Grammar = {
            alternatives: [
                ...(staticGrammar?.alternatives ?? []),
                ...dynamicGrammar.alternatives,
            ],
        };

        context.agentCache.grammarStore.addGrammar(schemaName, merged);
        debug(
            `Loaded dynamic grammar for ${schemaName} (${dynamicGrammar.alternatives.length} dynamic rules merged with ${staticGrammar?.alternatives.length ?? 0} static rules)`,
        );
    }

    private async loadDynamicSchema(
        schemaName: string,
        appAgent: AppAgent,
        sessionContext: SessionContext,
        context: CommandHandlerContext,
    ): Promise<void> {
        if (!appAgent.getDynamicSchema) return;

        const schemaContent = await appAgent.getDynamicSchema(
            sessionContext,
            schemaName,
        );
        if (!schemaContent?.content) return;

        const config = this.actionConfigs.get(schemaName);
        if (!config) return;

        // Replace the schema content with the dynamic version
        config.schemaFile = schemaContent;

        // Invalidate cached parsed schema so it gets re-parsed from new content
        this.actionSchemaFileCache.unloadActionSchemaFile(schemaName);

        // Clear translator cache so next translation uses the updated schema
        context.translatorCache.clear();

        debug(`Loaded dynamic schema for ${schemaName}`);
    }

    private async updateAction(
        schemaName: string,
        record: AppAgentRecord,
        enable: boolean,
        context: CommandHandlerContext,
    ) {
        if (enable) {
            if (record.actions.has(schemaName)) {
                return;
            }

            record.actions.add(schemaName);
            try {
                const sessionContext = await this.ensureSessionContext(
                    record,
                    context,
                );
                await callEnsureError(() =>
                    record.appAgent!.updateAgentContext?.(
                        enable,
                        sessionContext,
                        schemaName,
                    ),
                );
                // Load dynamic schema and grammar from agent callbacks
                await this.loadDynamicSchema(
                    schemaName,
                    record.appAgent!,
                    sessionContext,
                    context,
                );
                await this.loadDynamicGrammar(
                    schemaName,
                    record.appAgent!,
                    sessionContext,
                    context,
                );
            } catch (e) {
                // Rollback if there is a exception
                record.actions.delete(schemaName);
                throw e;
            }
            debug(`Action enabled ${schemaName}`);
        } else {
            if (!record.actions.has(schemaName)) {
                return;
            }
            record.actions.delete(schemaName);
            const sessionContext = await record.sessionContextP!;
            try {
                await callEnsureError(() =>
                    record.appAgent!.updateAgentContext?.(
                        enable,
                        sessionContext,
                        schemaName,
                    ),
                );
            } finally {
                // Assume that it is disabled even when there is an exception
                debug(`Action disabled ${schemaName}`);
                await this.checkCloseSessionContext(record);
            }
        }
    }

    private async ensureSessionContext(
        record: AppAgentRecord,
        context: CommandHandlerContext,
    ) {
        if (record.sessionContextP === undefined) {
            record.sessionContextP = this.initializeSessionContext(
                record,
                context,
            );
        }

        return record.sessionContextP;
    }
    private async initializeSessionContext(
        record: AppAgentRecord,
        context: CommandHandlerContext,
    ) {
        const appAgent = await this.ensureAppAgent(record);
        let agentContext: unknown | undefined;
        if (appAgent.initializeAgentContext !== undefined) {
            const options = this.agentInitOptions?.[record.name];
            let settings: AppAgentInitSettings | undefined =
                record.port !== undefined
                    ? {
                          localHostPort: record.port,
                      }
                    : undefined;

            if (options !== undefined) {
                if (settings === undefined) {
                    settings = {};
                }
                settings.options = options;
            }
            agentContext = await callEnsureError(() =>
                appAgent.initializeAgentContext!(settings),
            );
        }
        record.sessionContext = createSessionContext(
            record.name,
            agentContext,
            context,
            record.manifest.allowDynamicAgents === true,
        );

        debug(`Session context created for ${record.name}`);
        return record.sessionContext;
    }

    private async checkCloseSessionContext(record: AppAgentRecord) {
        if (record.actions.size === 0 && !record.commands) {
            await this.closeSessionContext(record);
        }
    }
    private async closeSessionContext(record: AppAgentRecord) {
        if (record.sessionContextP !== undefined) {
            const sessionContext = await record.sessionContextP;
            record.sessionContext = undefined;
            record.sessionContextP = undefined;
            try {
                // Since we have a session context, appAgent must be defined as well.
                const appAgent = record.appAgent!;
                if (appAgent.updateAgentContext !== undefined) {
                    // Disable all actions first.
                    for (const action of record.actions) {
                        await appAgent.updateAgentContext(
                            false,
                            sessionContext,
                            action,
                        );
                    }
                }
                await appAgent.closeAgentContext?.(sessionContext);
                // TODO: unload agent as well?
                debug(`Session context closed for ${record.name}`);
            } catch (e) {
                debugError(
                    `Failed to close session context for ${record.name}. Error ignored`,
                    e,
                );
                // Ignore error
            }
        }
    }

    private async ensureAppAgent(record: AppAgentRecord) {
        if (record.appAgent === undefined) {
            if (record.provider === undefined) {
                throw new Error(
                    `Internal error: no provider to load the app agent: ${record.name}`,
                );
            }
            const start = performance.now();
            record.appAgent = await record.provider.loadAppAgent(record.name);
            debugLoad(
                `App agent loaded: ${record.name} (${(performance.now() - start).toFixed(0)}ms)`,
            );
        }
        return record.appAgent;
    }

    private getRecord(appAgentName: string) {
        const record = this.agents.get(appAgentName);
        if (record === undefined) {
            throw new Error(`Unknown app agent: ${appAgentName}`);
        }
        return record;
    }

    public tryGetActionSchemaFile(schemaName: string) {
        const config = this.tryGetActionConfig(schemaName);
        if (config === undefined) {
            return undefined;
        }
        return this.getActionSchemaFileForConfig(config);
    }

    public getActionSchemaFileForConfig(
        config: ActionConfig,
    ): ActionSchemaFile {
        return this.actionSchemaFileCache.getActionSchemaFile(config);
    }

    public async reloadAgentSchema(
        appAgentName: string,
        context: CommandHandlerContext,
    ): Promise<void> {
        const record = this.getRecord(appAgentName);
        if (record.provider === undefined) {
            return;
        }

        // Unload cached schema files and semantic map entries so they get reloaded
        for (const schemaName of this.actionConfigs.keys()) {
            if (getAppAgentName(schemaName) === appAgentName) {
                this.actionSchemaFileCache.unloadActionSchemaFile(schemaName);
                this.actionSemanticMap?.removeActionSchemaFile(schemaName);
            }
        }

        // Get fresh manifest from provider and refresh schemas
        const manifest =
            await record.provider.getAppAgentManifest(appAgentName);
        const semanticMapP: Promise<void>[] = [];
        this.refreshAgentSchema(
            appAgentName,
            manifest,
            semanticMapP,
            undefined,
        );
        await Promise.all(semanticMapP);

        // Reload dynamic schemas and grammars if agent is active
        if (record.appAgent && record.sessionContextP) {
            const sessionContext = await record.sessionContextP;
            for (const schemaName of record.actions) {
                await this.loadDynamicSchema(
                    schemaName,
                    record.appAgent,
                    sessionContext,
                    context,
                );
                await this.loadDynamicGrammar(
                    schemaName,
                    record.appAgent,
                    sessionContext,
                    context,
                );
            }
        }

        // Clear translator cache to force re-translation with new schema
        context.translatorCache.clear();
    }

    public setTraceNamespaces(namespaces: string) {
        const providers = new Set<AppAgentProvider>();
        for (const { provider } of this.agents.values()) {
            if (provider === undefined || providers.has(provider)) {
                continue;
            }
            provider.setTraceNamespaces?.(namespaces);
            providers.add(provider);
        }
    }
}

export type AppAgentStateInitSettings =
    | string[]
    | boolean
    | undefined
    | {
          schemas?: string[] | boolean | undefined;
          actions?: string[] | boolean | undefined;
          commands?: string[] | boolean | undefined;
      };

export function getAppAgentStateSettings(
    settings: AppAgentStateInitSettings,
    agents: AppAgentManager,
): AppAgentStateSettings | undefined {
    if (settings === undefined) {
        return undefined;
    }
    const result: AppAgentStateSettings = {};
    if (typeof settings === "boolean" || Array.isArray(settings)) {
        for (const key of appAgentStateKeys) {
            const names =
                key === "commands"
                    ? agents.getAppAgentNames()
                    : agents.getSchemaNames();
            const entries = names.map((name) => [
                name,
                typeof settings === "boolean"
                    ? settings
                    : settings.includes(getAppAgentName(name)),
            ]);
            const state = Object.fromEntries(entries);
            for (const name of alwaysEnabledAgents[key]) {
                if (state[name] === false) {
                    state[name] = true;
                }
            }
            result[key] = state;
        }
        return result;
    }
    for (const key of appAgentStateKeys) {
        const state = settings[key];
        if (state === undefined) {
            continue;
        }
        const alwaysEnabled = alwaysEnabledAgents[key];
        const names =
            key === "commands"
                ? agents.getAppAgentNames()
                : agents.getSchemaNames();
        const entries = names.map((name) => [
            name,
            alwaysEnabled.includes(name)
                ? true
                : typeof state === "boolean"
                  ? state
                  : state.includes(name),
        ]);
        result[key] = Object.fromEntries(entries);
    }
    return Object.keys(result).length === 0 ? undefined : result;
}
