@tea-agent/loop-agent 0.43.0-next.9 → 0.43.0

package/dist/worker/console/chat/pi-runtime/inspection.js

@@ -0,0 +1,439 @@
+/**
+ * Runtime inspection: browser-safe snapshot projection, slash-command
+ * inventory, and ResourceLoader/package/MCP collection. Does not own
+ * session lifecycle, preference-file cache, or prompt/reload locks.
+ */
+import { RUNTIME_CONTEXT_TEXT_MAX, redactRuntimeText, } from "../runtime-context.js";
+import { isAutoInvocationEnabled, skillResourceId, } from "../resource-preferences-store.js";
+/**
+ * Browser-safe projection of a live runtime snapshot (design §2.2 / RF-03).
+ *
+ * Every browser-visible string runs the shared secret-scrub chain
+ * (scrubSecrets + ghp_/Bearer redaction via redactRuntimeText) and a fixed
+ * per-field length limit: 200 (names/spec/source/origin), 400 (paths/errors/
+ * diagnostic messages), 600 (skill descriptions), 80 (package versions);
+ * truncation uses the fixed `…[truncated N chars …]` marker. The server-only
+ * `raw` prompt and the RAW-based `sha256`/`characters` pass through untouched,
+ * and real empty lists stay empty.
+ *
+ * Pure + deterministic and exported so the route harness reuses the exact
+ * production implementation (same code path as getRuntimeSnapshot).
+ */
+export function projectRuntimeSnapshot(input) {
+    const field = (value, max) => value === undefined ? undefined : redactRuntimeText(value, max);
+    const projectSkill = (skill) => ({
+        name: field(skill.name, 200) ?? "",
+        description: field(skill.description, 600) ?? "",
+        path: field(skill.path, 400) ?? "",
+        ...(skill.baseDir ? { baseDir: field(skill.baseDir, 400) } : {}),
+        scope: skill.scope,
+        source: field(skill.source, 200) ?? "",
+        resourceId: field(skill.resourceId, 200) ?? "",
+        autoInvocationEnabled: skill.autoInvocationEnabled,
+        diagnostics: skill.diagnostics.map((diag) => field(diag, 400) ?? ""),
+    });
+    const projectExtension = (ext) => ({
+        name: field(ext.name, 200) ?? "",
+        path: field(ext.path, 400) ?? "",
+        ...(ext.resolvedPath
+            ? { resolvedPath: field(ext.resolvedPath, 400) }
+            : {}),
+        source: field(ext.source, 200) ?? "",
+        scope: ext.scope,
+        ...(ext.origin ? { origin: field(ext.origin, 200) } : {}),
+        enabled: ext.enabled,
+        ...(ext.error ? { error: field(ext.error, 400) } : {}),
+    });
+    const projectPackage = (pkg) => ({
+        spec: field(pkg.spec, 200) ?? "",
+        scope: pkg.scope,
+        enabled: pkg.enabled,
+        ...(pkg.version ? { version: field(pkg.version, 80) } : {}),
+        ...(pkg.configuredVersion
+            ? { configuredVersion: field(pkg.configuredVersion, 80) }
+            : {}),
+        ...(pkg.packageName ? { packageName: field(pkg.packageName, 200) } : {}),
+        ...(pkg.path ? { path: field(pkg.path, 400) } : {}),
+        ...(pkg.installedPath ? { installedPath: field(pkg.installedPath, 400) } : {}),
+        ...(pkg.cwd ? { cwd: field(pkg.cwd, 400) } : {}),
+        resolved: pkg.resolved.map((resource) => ({
+            type: resource.type,
+            name: field(resource.name, 200) ?? "",
+            path: field(resource.path, 400) ?? "",
+            source: field(resource.source, 200) ?? "",
+            scope: resource.scope,
+        })),
+        diagnostics: pkg.diagnostics.map((diag) => field(diag, 400) ?? ""),
+    });
+    const projectMcpTool = (tool) => ({
+        name: field(tool.name, 200) ?? "",
+        description: field(tool.description, 600) ?? "",
+        ...(tool.server ? { server: field(tool.server, 200) } : {}),
+        source: field(tool.source, 200) ?? "",
+        scope: tool.scope,
+        ...(tool.path ? { path: field(tool.path, 400) } : {}),
+        active: tool.active,
+    });
+    const projectMcp = (mcp) => ({
+        servers: mcp.servers.map((server) => ({
+            name: field(server.name, 200) ?? "",
+            scope: server.scope,
+            status: server.status,
+            enabled: server.enabled,
+            ...(server.transport ? { transport: field(server.transport, 80) } : {}),
+            ...(server.command ? { command: field(server.command, 400) } : {}),
+            ...(server.url ? { url: field(server.url, 400) } : {}),
+            ...(server.configPath ? { configPath: field(server.configPath, 400) } : {}),
+            tools: server.tools.map(projectMcpTool),
+        })),
+        unassignedTools: mcp.unassignedTools.map(projectMcpTool),
+    });
+    const projectDiagnostic = (diag) => ({
+        type: diag.type,
+        ...(diag.code ? { code: diag.code } : {}),
+        message: field(diag.message, 400) ?? "",
+        ...(diag.path ? { path: field(diag.path, 400) } : {}),
+        ...(diag.retryable !== undefined
+            ? { retryable: diag.retryable }
+            : {}),
+    });
+    return {
+        sessionId: input.sessionId,
+        revision: input.revision,
+        loadedAt: input.loadedAt,
+        selection: {
+            ...(input.selection.model
+                ? {
+                    model: {
+                        provider: input.selection.model.provider,
+                        id: input.selection.model.id,
+                        ...(input.selection.model.name
+                            ? { name: field(input.selection.model.name, 200) }
+                            : {}),
+                    },
+                }
+                : {}),
+            thinkingSelection: input.selection.thinkingSelection,
+            ...(input.selection.effectiveThinkingLevel
+                ? { effectiveThinkingLevel: input.selection.effectiveThinkingLevel }
+                : {}),
+        },
+        models: input.models.map((model) => ({
+            provider: model.provider,
+            id: model.id,
+            ...(model.name ? { name: field(model.name, 200) } : {}),
+            ...(model.hasCredentials !== undefined
+                ? { hasCredentials: model.hasCredentials }
+                : {}),
+        })),
+        thinkingLevels: input.thinkingLevels.map((option) => ({ ...option })),
+        systemPrompt: {
+            ...(input.systemPrompt.raw !== undefined
+                ? { raw: input.systemPrompt.raw }
+                : {}),
+            text: redactRuntimeText(input.systemPrompt.text, RUNTIME_CONTEXT_TEXT_MAX),
+            sha256: input.systemPrompt.sha256,
+            characters: input.systemPrompt.characters,
+        },
+        activeTools: [...input.activeTools],
+        contextFiles: input.contextFiles.map((file) => ({
+            path: field(file.path, 400) ?? "",
+            characters: file.characters,
+        })),
+        skills: input.skills.map(projectSkill),
+        extensions: input.extensions.map(projectExtension),
+        packages: input.packages.map(projectPackage),
+        mcp: projectMcp(input.mcp ?? { servers: [], unassignedTools: [] }),
+        diagnostics: input.diagnostics.map(projectDiagnostic),
+        hasBash: input.hasBash,
+    };
+}
+/**
+ * Browser-safe slash command projection for UI-11.
+ * Sources: current Session extension commands, prompt templates, skills.
+ * Never returns prompt/skill file bodies. Same-name conflict priority:
+ * extension > skill > prompt.
+ */
+export function collectSlashCommands(input) {
+    const scrub = (value) => {
+        const raw = String(value ?? "");
+        return raw
+            .replace(/\/Users\/[^\s]+/gi, "~")
+            .replace(/[A-Za-z]:\\Users\\[^\s]+/gi, "~")
+            .slice(0, 240);
+    };
+    const session = input.session;
+    if (!session)
+        return { commands: [] };
+    const SOURCE_RANK = {
+        extension: 0,
+        skill: 1,
+        prompt: 2,
+    };
+    const byKey = new Map();
+    const sourceWarnings = [];
+    const push = (command, label, description, source) => {
+        const name = command.startsWith("/") ? command : `/${command}`;
+        const key = name.toLowerCase();
+        if (!key || key === "/")
+            return;
+        const next = {
+            command: name,
+            label: (label || name).slice(0, 80),
+            description: scrub(description),
+            source,
+        };
+        const existing = byKey.get(key);
+        if (!existing || SOURCE_RANK[source] < SOURCE_RANK[existing.source]) {
+            byKey.set(key, next);
+        }
+    };
+    try {
+        const cmds = session.extensionRunner?.getRegisteredCommands?.() ?? [];
+        for (const cmd of cmds) {
+            const name = cmd.invocationName || cmd.name;
+            if (!name)
+                continue;
+            push(String(name), String(cmd.name || name), String(cmd.description || ""), "extension");
+        }
+    }
+    catch (error) {
+        sourceWarnings.push(`extension: ${scrub(error instanceof Error ? error.message : String(error))}`);
+    }
+    try {
+        for (const tpl of session.promptTemplates ?? []) {
+            if (!tpl?.name)
+                continue;
+            push(String(tpl.name), String(tpl.name), String(tpl.description || ""), "prompt");
+        }
+    }
+    catch (error) {
+        sourceWarnings.push(`prompt: ${scrub(error instanceof Error ? error.message : String(error))}`);
+    }
+    try {
+        const skills = input.resourceLoader?.getSkills?.()?.skills ?? [];
+        for (const skill of skills) {
+            if (!skill?.name)
+                continue;
+            const command = skill.name.startsWith("skill:")
+                ? `/${skill.name}`
+                : `/skill:${skill.name}`;
+            push(command, skill.name, String(skill.description || ""), "skill");
+        }
+    }
+    catch (error) {
+        sourceWarnings.push(`skill: ${scrub(error instanceof Error ? error.message : String(error))}`);
+    }
+    const warning = sourceWarnings.length > 0
+        ? sourceWarnings.join("; ").slice(0, 160)
+        : undefined;
+    return {
+        commands: [...byKey.values()],
+        ...(warning ? { warning } : {}),
+    };
+}
+/**
+ * Collect ResourceLoader / package / MCP inventories for a live session.
+ * Preference-file loading stays with ConsolePiRuntime; this function only
+ * consumes already-loaded prefs (or a captured load error).
+ */
+export async function collectRuntimeInventories(input) {
+    const contextFiles = [];
+    const skills = [];
+    const extensions = [];
+    const diagnostics = [];
+    const resolvedResources = [];
+    const resourceFailure = (subface, error) => {
+        diagnostics.push({
+            type: "error",
+            code: "RESOURCE_LOAD_FAILED",
+            message: `${subface} inventory failed: ${error instanceof Error ? error.message : String(error)}`,
+            retryable: true,
+        });
+    };
+    if (input.skillPrefsError !== undefined) {
+        diagnostics.push({
+            type: "error",
+            code: "PI_RESOURCE_PREFERENCES_MALFORMED",
+            message: input.skillPrefsError instanceof Error
+                ? input.skillPrefsError.message
+                : String(input.skillPrefsError),
+            retryable: true,
+        });
+    }
+    const resourceLoader = input.resourceLoader;
+    if (resourceLoader) {
+        try {
+            const agentsFiles = resourceLoader.getAgentsFiles?.();
+            for (const file of agentsFiles?.agentsFiles ?? []) {
+                if (!file.path)
+                    continue;
+                contextFiles.push({
+                    path: file.path,
+                    characters: file.content?.length ?? 0,
+                });
+            }
+        }
+        catch (error) {
+            resourceFailure("context files", error);
+        }
+        try {
+            const skillsResult = resourceLoader.getSkills?.();
+            for (const skill of skillsResult?.skills ?? []) {
+                const resourceId = skillResourceId({
+                    name: skill.name,
+                    filePath: skill.filePath,
+                });
+                const prefEnabled = isAutoInvocationEnabled(input.skillPrefs, resourceId);
+                const autoInvocationEnabled = prefEnabled && skill.disableModelInvocation !== true;
+                skills.push({
+                    name: skill.name,
+                    description: skill.description ?? "",
+                    path: skill.filePath,
+                    ...(skill.baseDir ? { baseDir: skill.baseDir } : {}),
+                    scope: skill.sourceInfo?.scope ?? "unknown",
+                    source: skill.sourceInfo?.source ?? "",
+                    resourceId,
+                    autoInvocationEnabled,
+                    diagnostics: [],
+                });
+                resolvedResources.push({
+                    type: "skill",
+                    name: skill.name,
+                    path: skill.filePath,
+                    source: skill.sourceInfo?.source ?? "",
+                    scope: skill.sourceInfo?.scope ?? "unknown",
+                });
+            }
+            for (const diag of skillsResult?.diagnostics ?? []) {
+                if (!diag?.message)
+                    continue;
+                diagnostics.push({
+                    type: diag.type ?? "warning",
+                    message: diag.message,
+                    ...(diag.path ? { path: diag.path } : {}),
+                });
+            }
+        }
+        catch (error) {
+            resourceFailure("skills", error);
+        }
+        try {
+            const extResult = resourceLoader.getExtensions?.();
+            for (const ext of extResult?.extensions ?? []) {
+                const path = ext.resolvedPath ?? ext.path ?? "";
+                extensions.push({
+                    name: ext.sourceInfo?.source ?? ext.path ?? "extension",
+                    path,
+                    ...(ext.resolvedPath ? { resolvedPath: ext.resolvedPath } : {}),
+                    source: ext.sourceInfo?.source ?? "",
+                    scope: ext.sourceInfo?.scope ?? "unknown",
+                    ...(ext.sourceInfo?.origin ? { origin: ext.sourceInfo.origin } : {}),
+                    enabled: true,
+                });
+                resolvedResources.push({
+                    type: "extension",
+                    name: ext.sourceInfo?.source ?? ext.path ?? "extension",
+                    path,
+                    source: ext.sourceInfo?.source ?? "",
+                    scope: ext.sourceInfo?.scope ?? "unknown",
+                });
+            }
+            for (const err of extResult?.errors ?? []) {
+                if (!err?.error)
+                    continue;
+                diagnostics.push({
+                    type: "error",
+                    message: err.error,
+                    ...(err.path ? { path: err.path } : {}),
+                });
+            }
+        }
+        catch (error) {
+            resourceFailure("extensions", error);
+        }
+        try {
+            const promptsResult = resourceLoader.getPrompts?.();
+            for (const prompt of promptsResult?.prompts ?? []) {
+                resolvedResources.push({
+                    type: "prompt",
+                    name: prompt.name,
+                    path: prompt.filePath,
+                    source: prompt.sourceInfo?.source ?? "",
+                    scope: prompt.sourceInfo?.scope ?? "unknown",
+                });
+            }
+            for (const diag of promptsResult?.diagnostics ?? []) {
+                if (!diag?.message)
+                    continue;
+                diagnostics.push({
+                    type: diag.type ?? "warning",
+                    message: diag.message,
+                    ...(diag.path ? { path: diag.path } : {}),
+                });
+            }
+        }
+        catch (error) {
+            resourceFailure("prompts", error);
+        }
+        try {
+            const themesResult = resourceLoader.getThemes?.();
+            for (const theme of themesResult?.themes ?? []) {
+                if (!theme.path)
+                    continue;
+                resolvedResources.push({
+                    type: "theme",
+                    name: theme.name ?? theme.path,
+                    path: theme.path,
+                    source: "",
+                    scope: "unknown",
+                });
+            }
+            for (const diag of themesResult?.diagnostics ?? []) {
+                if (!diag?.message)
+                    continue;
+                diagnostics.push({
+                    type: diag.type ?? "warning",
+                    message: diag.message,
+                    ...(diag.path ? { path: diag.path } : {}),
+                });
+            }
+        }
+        catch (error) {
+            resourceFailure("themes", error);
+        }
+    }
+    const { readPackageInventory } = await import("../pi-console-config.js");
+    let packages = [];
+    try {
+        packages = (await readPackageInventory(input.agentDir, input.cwd, resolvedResources));
+    }
+    catch (error) {
+        packages = [];
+        diagnostics.push({
+            type: "error",
+            code: "PACKAGE_INVENTORY_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            retryable: true,
+        });
+    }
+    const { readMcpInventory } = await import("../mcp-inventory.js");
+    let mcp = { servers: [], unassignedTools: [] };
+    try {
+        mcp = await readMcpInventory({
+            agentDir: input.agentDir,
+            cwd: input.cwd,
+            tools: (Array.isArray(input.tools) ? input.tools : []),
+            activeToolNames: input.activeToolNames,
+        });
+    }
+    catch (error) {
+        diagnostics.push({
+            type: "error",
+            code: "MCP_INVENTORY_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            retryable: true,
+        });
+    }
+    return { contextFiles, skills, extensions, packages, mcp, diagnostics };
+}

package/dist/worker/console/chat/pi-runtime/progressive-tools.js

@@ -0,0 +1,195 @@
+/** Model exposure only. Capability registry and dispatch remain the authority. */
+import { Type } from "typebox";
+import { buildModelCallableToolSchemas } from "../tool-adapter.js";
+import { computeChatActiveToolNames } from "../session-mode.js";
+import { filterActiveInterviewTools } from "../../interview/tools.js";
+export const TOOL_EXPOSURE_ENTRY = "console-tool-exposure";
+export const TOOL_CATALOG_VERSION = 1;
+export const CORE_WORKFLOW_TOOLS = Object.freeze(`prepareScheduledTask scheduledGoalGet scheduledGoalList newTask importPrd sourceInstructions contractDraftSave contractShow contractValidate contractDiff taskAdvance prepareDagConfirmation prepareDagExecution runDag operationGet operationList operationEventSummary operationWait observeLink dagReport dagDoctor dagRerunPlan dagRerun prepareMutationGate standaloneTaskRerun workerTaskRetry status planList operatorCapabilities`.split(" "));
+const SCHEDULED_BOOKING_READ_TOOLS = new Set(["read", "find", "ls", "grep"]);
+export function isScheduledBookingTurn(text) {
+    return /(?:预约|定时|稍后|分钟后|小时后|schedule(?:d)?|\blater\b)/i.test(text);
+}
+/** Keep booking turns on typed workflow actions and local read-only inspection. */
+export function pinScheduledBookingTurnTools(session) {
+    const allowed = session.getActiveToolNames().filter(name => CORE_WORKFLOW_TOOLS.includes(name) || SCHEDULED_BOOKING_READ_TOOLS.has(name));
+    session.setActiveToolsByName(allowed);
+    return allowed;
+}
+export const WORKFLOW_TOOL_GROUPS = [
+    { id: "scheduling", examples: ["prepareScheduledGoal"], description: "高级预约：已有 DAG/Task 的冻结预约", tools: ["prepareScheduledGoal"] },
+    { id: "diagnostics", examples: ["inspect", "doctor", "dagValidate"], description: "DAG 深度诊断、校验、决策、上下文与初始化检查", tools: ["inspect", "doctor", "statsContext", "spineCheck", "dagRunTask", "dagValidate", "dagPromptOverrideConfig", "dagInterruptEligibility", "dagStatus", "dagDecisionInspect", "dagDecisionValidate"] },
+    { id: "governance", examples: ["planCreate", "docsAudit", "closeoutTask"], description: "计划管理、文档审计、交接覆盖与任务收口", tools: ["planCreate", "planComplete", "planCheck", "docsAudit", "handoffCheck", "handoffCoverage", "coverageReport", "stats", "promoteRun", "closeoutTask", "dagCloseoutDraft"] },
+    { id: "knowledge", examples: ["knowledgeQuery"], description: "查询项目知识", tools: ["knowledgeQuery"] },
+    { id: "worker", examples: ["workerSchedulerStatus", "workerPoolDoctor", "workerReportMorning"], description: "Worker 任务池、功能审查、调度诊断与报表", tools: ["workerPoolDoctor", "workerFeatureReview", "workerFeatureDoctor", "workerTaskValidate", "workerBatchPlanReady", "workerReportMorning", "workerReportMetrics", "workerAdmissionShow", "workerSchedulerList", "workerSchedulerStatus", "workerSchedulerLedger", "workerSchedulerDoctor"] },
+];
+export function configuredToolExposure(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    if (value === "full" || value === "progressive")
+        return value;
+    throw new Error("CONSOLE_CHAT_TOOL_EXPOSURE must be full or progressive");
+}
+/** Fail closed on catalog drift, including duplicate or human-only entries. */
+export function validateWorkflowToolCatalog() {
+    const expected = new Set(buildModelCallableToolSchemas().map(t => t.toolId));
+    const names = [...CORE_WORKFLOW_TOOLS, ...WORKFLOW_TOOL_GROUPS.flatMap(g => [...g.tools])];
+    if (names.length !== new Set(names).size || names.length !== expected.size || names.some(n => !expected.has(n)))
+        throw new Error("WORKFLOW_TOOL_CATALOG_DRIFT");
+}
+export const TOOL_DISCOVERY_DESCRIPTION = "Load a workflow capability missing from the visible tools. Choose target by the user's intent from the capability directory, even when no tool name was mentioned. Pass a group ID or exact tool name; omit target if unsure. After loading, call the matching typed tool in the NEXT model response. Discovery alone does not fulfill the request, execute work or grant approval. Prefer discovery over recreating a workflow with shell or file edits.";
+export class WorkflowToolExposure {
+    override;
+    state;
+    session;
+    interview = false;
+    manager;
+    // Failed persistence must not let the next turn silently undo full fallback.
+    // The active branch must still contain this ancestor; sibling branches do not inherit it.
+    volatileFallback;
+    constructor(manager, override) {
+        this.override = override;
+        this.manager = (manager ?? {});
+        this.state = { version: TOOL_CATALOG_VERSION, mode: override ?? "full", groups: [] };
+        try {
+            this.restore();
+        }
+        catch {
+            this.state = { version: TOOL_CATALOG_VERSION, mode: "full", groups: [], fallbackReason: "TOOL_EXPOSURE_STATE_READ_FAILED" };
+        }
+    }
+    get mode() { return this.state.mode; }
+    get snapshot() { return { ...this.state, groups: [...this.state.groups] }; }
+    restore() {
+        const entries = this.manager.getBranch?.() ?? [];
+        const latest = entries.filter(e => e.type === "custom" && e.customType === TOOL_EXPOSURE_ENTRY).at(-1);
+        if (!latest) {
+            this.state = { version: TOOL_CATALOG_VERSION, mode: this.override ?? "full", groups: [] };
+            return;
+        }
+        const raw = latest.data;
+        if (raw?.version !== TOOL_CATALOG_VERSION || !["full", "progressive"].includes(raw.mode ?? "") || !Array.isArray(raw.groups) || raw.groups.some(id => !WORKFLOW_TOOL_GROUPS.some(g => g.id === id))) {
+            this.state = { version: TOOL_CATALOG_VERSION, mode: "full", groups: [], fallbackReason: "INVALID_SAVED_TOOL_EXPOSURE" };
+            return;
+        }
+        const mode = raw.mode === "full" && raw.fallbackReason ? "full" : (this.override ?? raw.mode);
+        this.state = { version: TOOL_CATALOG_VERSION, mode, groups: [...new Set(raw.groups)], ...(mode === "full" && raw.fallbackReason ? { fallbackReason: raw.fallbackReason } : {}) };
+    }
+    persist() {
+        if (!this.manager.appendCustomEntry || !this.manager.getBranch)
+            throw new Error("TOOL_EXPOSURE_PERSISTENCE_UNAVAILABLE");
+        const previous = this.manager.getBranch().filter(e => e.type === "custom" && e.customType === TOOL_EXPOSURE_ENTRY).at(-1)?.data;
+        if (JSON.stringify(previous) !== JSON.stringify(this.state))
+            this.manager.appendCustomEntry(TOOL_EXPOSURE_ENTRY, this.snapshot);
+    }
+    exposed() {
+        if (this.state.mode === "full")
+            return undefined;
+        return [...CORE_WORKFLOW_TOOLS, ...WORKFLOW_TOOL_GROUPS.filter(g => this.state.groups.includes(g.id)).flatMap(g => [...g.tools])];
+    }
+    apply() {
+        if (!this.session)
+            throw new Error("TOOL_EXPOSURE_SESSION_UNAVAILABLE");
+        const names = computeChatActiveToolNames(this.session, "workflow", this.exposed());
+        const allowed = this.interview ? filterActiveInterviewTools(names).allowed : names;
+        this.session.setActiveToolsByName(allowed);
+        // SDK silently ignores unknown names: verify actual registration, not intent.
+        if (this.session.getAllTools) {
+            const registered = new Set(this.session.getAllTools().map(t => t.name));
+            const actual = new Set(this.session.getActiveToolNames());
+            const required = this.interview ? [] : (this.exposed() ?? CORE_WORKFLOW_TOOLS);
+            if (required.some(name => !registered.has(name) || !actual.has(name)))
+                throw new Error("TOOL_EXPOSURE_REQUIRED_TOOL_MISSING");
+            if (allowed.some(n => registered.has(n) && !actual.has(n)) || [...actual].some(n => !allowed.includes(n)))
+                throw new Error("TOOL_EXPOSURE_ACTIVATION_MISMATCH");
+        }
+    }
+    fallback(reason) {
+        this.state = { version: TOOL_CATALOG_VERSION, mode: "full", groups: [], fallbackReason: reason };
+        this.apply(); // A failure here is fatal; never pretend full mode is active.
+        try {
+            this.persist();
+            this.volatileFallback = undefined;
+        }
+        catch {
+            let anchor;
+            try {
+                anchor = this.manager.getBranch?.().at(-1);
+            }
+            catch { /* Conservatively keep full when branch cannot be read. */ }
+            this.volatileFallback = { anchor, state: this.snapshot };
+        }
+    }
+    pin(session, interview = false) {
+        this.session = session;
+        this.interview = interview;
+        // Reconstruct from the active branch, including after compaction/reopen.
+        try {
+            const pending = this.volatileFallback;
+            const branch = this.manager.getBranch?.() ?? [];
+            if (pending && (!pending.anchor || branch.some(entry => entry === pending.anchor ||
+                (pending.anchor?.id !== undefined && entry.id === pending.anchor.id)))) {
+                this.state = { ...pending.state, groups: [...pending.state.groups] };
+            }
+            else {
+                this.volatileFallback = undefined;
+                this.restore();
+            }
+            validateWorkflowToolCatalog();
+            this.apply();
+            // Full mode also records the session policy when supported.
+            if (this.mode === "progressive" || this.manager.appendCustomEntry) {
+                this.persist();
+                this.volatileFallback = undefined;
+            }
+        }
+        catch {
+            this.fallback(this.state.fallbackReason ?? "TOOL_EXPOSURE_RESTORE_OR_ACTIVATION_FAILED");
+        }
+    }
+    discover(target) {
+        if (this.interview)
+            return { ok: false, code: "TOOL_DISCOVERY_INTERVIEW_DENIED" };
+        const catalog = WORKFLOW_TOOL_GROUPS.map(g => ({ id: g.id, description: g.description, examples: [...g.examples], active: this.mode === "full" || this.state.groups.includes(g.id) }));
+        if (!target)
+            return { ok: true, ...this.snapshot, catalog };
+        if (CORE_WORKFLOW_TOOLS.includes(target)) {
+            if (!this.session?.getActiveToolNames().includes(target))
+                return { ok: false, code: "TOOL_EXPOSURE_REQUIRED_TOOL_MISSING" };
+            return { ok: true, alreadyActive: true, tools: [target] };
+        }
+        const group = WORKFLOW_TOOL_GROUPS.find(g => g.id === target || g.tools.includes(target));
+        if (!group)
+            return { ok: false, code: "TOOL_DISCOVERY_NOT_FOUND", catalog };
+        if (!this.session)
+            return { ok: false, code: "TOOL_EXPOSURE_SESSION_UNAVAILABLE" };
+        const registered = new Set(this.session.getAllTools?.().map(t => t.name) ?? []);
+        if (group.tools.some(n => !registered.has(n))) {
+            this.fallback("TOOL_EXPOSURE_GROUP_UNAVAILABLE");
+            return { ok: false, code: "TOOL_EXPOSURE_GROUP_UNAVAILABLE", ...this.snapshot };
+        }
+        try {
+            this.state = { ...this.state, groups: [...new Set([...this.state.groups, group.id])] };
+            this.apply();
+            this.persist();
+        }
+        catch {
+            this.fallback("TOOL_EXPOSURE_LOAD_FAILED");
+        }
+        return { ok: true, ...this.snapshot, group: group.id, tools: [...group.tools], effective: "next-model-response", guidance: "Use the activated typed tools in your next response. Loading has not executed any business action." };
+    }
+    buildTool(fullTool) {
+        return { name: "operatorCapabilities", label: "发现工作流工具", description: TOOL_DISCOVERY_DESCRIPTION,
+            // One short navigation line; detailed semantics live in schema description.
+            promptSnippet: "工作流能力目录：按用户意图选组；所需能力未显示时先调用 operatorCapabilities(target=组ID)，再调用加载后的业务工具完成请求：" + WORKFLOW_TOOL_GROUPS.map(g => `${g.id}: ${g.description} (${g.examples.join(", ")})`).join("; "),
+            parameters: Type.Object({ target: Type.Optional(Type.String({ maxLength: 80, description: "Group ID or exact tool name; omit to list groups." })) }, { additionalProperties: false }),
+            execute: async (_id, params, signal) => {
+                if (signal?.aborted)
+                    throw new Error("Tool discovery aborted");
+                if (this.mode === "full" && !this.interview && !params.target && fullTool)
+                    return fullTool.execute(_id, {});
+                const result = this.discover(params.target);
+                return { isError: result.ok === false, content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+            } };
+    }
+}