@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/chat/tools/nac3_invoke.js

@@ -0,0 +1,896 @@
+import { findVerb, findVerbByAlias, validateArgs, suggestVerbs, manifest, } from '../../nac3/internal_manifest.js';
+import { resolveManifestMode } from '../../nac3/manifest_lazy.js';
+import { getDoctrines, listDoctrineSlugs } from '../../core/doctrine_resolver.js';
+import { logDispatch, newTraceId, redactArgs, } from '../../nac3/dispatch_log.js';
+import { enqueueApproval } from '../../nac3/approval_queue.js';
+import { VERSION as FORGE_VERSION } from '../../version.js';
+/* alpha.42 -- policies that REQUIRE panel-side approval before
+ *  the legacy handler runs. The dispatcher pushes a pending row
+ *  and returns an envelope; the panel modal handles the rest. */
+const POLICIES_NEED_APPROVAL = new Set(['destructive', 'approval-required']);
+export const NAC3_INVOKE_SPEC = {
+    name: 'nac3_invoke',
+    description: 'Invoke a NAC3 verb from the internal manifest. The manifest '
+        + 'lives in the system prompt. ALWAYS pick verb_id from there.\n\n'
+        + 'Rules:\n'
+        + '  - If no verb matches what the user asked, REPLY in chat '
+        + '"No tengo verbo NAC3 para X" -- do NOT improvise.\n'
+        + '  - Args must satisfy the verb schema. Read the schema in '
+        + 'the manifest before composing args.\n'
+        + '  - Check the verb policy before dispatching. Destructive / '
+        + 'approval-required verbs need a clear user signal first.\n'
+        + '  - On is_error=true: tell the user what failed; do not '
+        + 'paper over it. Past-tense ("listo", "guardado") is allowed '
+        + 'only after is_error=false.\n'
+        + '  - When the result carries nac3_panel_dispatch=true, the '
+        + 'panel will execute the verb; treat that as success.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            verb_id: {
+                type: 'string',
+                description: 'Stable verb id from the manifest, e.g. yujin.pizarron.create-tab.',
+            },
+            args: {
+                type: 'object',
+                description: 'Arguments for the verb. Must satisfy the verb schema.',
+            },
+            idempotency_key: {
+                type: 'string',
+                description: 'Optional. Same key on retry -> server may dedupe.',
+            },
+        },
+        required: ['verb_id'],
+    },
+    requires_approval: false,
+};
+export async function runNac3Invoke(rawArgs, ctx, opts) {
+    const trace_id = newTraceId();
+    const startedAt = Date.now();
+    const m = manifest();
+    const baseEntry = {
+        trace_id,
+        panel_session_id: opts.panelSessionId,
+        forge_version: FORGE_VERSION,
+        llm_turn_id: opts.llmTurnId,
+        user_text_hash: opts.userTextHash,
+        manifest_version: m.version,
+    };
+    const verb_id = typeof rawArgs.verb_id === 'string' ? rawArgs.verb_id.trim() : '';
+    const args = (rawArgs.args && typeof rawArgs.args === 'object' && !Array.isArray(rawArgs.args))
+        ? rawArgs.args
+        : {};
+    if (!verb_id) {
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'schema-fail',
+            ...baseEntry,
+            result_ok: false,
+            result_error: 'verb_id missing',
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: true,
+            result: { error: 'verb_id is required (string).' },
+            display: 'nac3_invoke <- missing verb_id',
+        };
+    }
+    /* alpha.59z.38 NAC-3 v3.x backend tools (task #23 slice 2) --
+     * app.* namespace dispatcher. These verbs are NOT in the
+     * internal manifest; they come from the adopter app's
+     * yujin.forge.json nac3_backend.tools[] section + surface via
+     * buildBackendToolsSection at prompt build time. Resolving here
+     * before findVerb so the rest of the pipeline (gate, R8,
+     * legacy aliasing) skips entirely. */
+    if (verb_id.startsWith('app.')) {
+        const toolId = verb_id.slice(4);
+        const { runAppBackendTool } = await import('./app_backend_dispatch.js');
+        return await runAppBackendTool({
+            toolId,
+            args,
+            baseEntry,
+            startedAt,
+            /* PND-052 (sec 2.5) -- use the dispatcher's project root, not
+             * process.cwd(). The panel server's cwd is not guaranteed to be
+             * the active project, so cwd would read the wrong (or no)
+             * yujin.forge.json backend catalogue. */
+            projectRoot: ctx.projectRoot,
+        });
+    }
+    let verb = findVerb(verb_id);
+    let alias_used;
+    if (!verb) {
+        /* Tolerate the LLM passing a legacy tool name as verb_id. */
+        verb = findVerbByAlias(verb_id);
+        if (verb) {
+            alias_used = verb_id;
+            await logDispatch({
+                ts: new Date().toISOString(),
+                kind: 'deprecated-alias',
+                ...baseEntry,
+                verb_id: verb.id,
+                alias_used: verb_id,
+                args_sample: redactArgs(args),
+                result_ok: undefined,
+                duration_ms: Date.now() - startedAt,
+            });
+        }
+    }
+    if (!verb) {
+        const closest = suggestVerbs(verb_id, 3);
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'verb-not-found',
+            ...baseEntry,
+            verb_id,
+            closest_verbs: closest,
+            args_sample: redactArgs(args),
+            result_ok: false,
+            result_error: 'verb not found',
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: true,
+            result: {
+                error: 'No NAC3 verb with id "' + verb_id + '". Pick from the manifest.',
+                closest_verbs: closest,
+                hint: 'The full manifest is in your system prompt. If you genuinely need a new verb, say so to the user instead of guessing.',
+            },
+            display: 'nac3_invoke <- unknown verb ' + verb_id,
+        };
+    }
+    /* Schema validation. */
+    const schemaErr = validateArgs(verb, args);
+    if (schemaErr) {
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'schema-fail',
+            ...baseEntry,
+            verb_id: verb.id,
+            args_sample: redactArgs(args),
+            result_ok: false,
+            result_error: schemaErr,
+            duration_ms: Date.now() - startedAt,
+        });
+        /* alpha.59x mitigation #1 -- auto-recovery on schema fail in
+         *  lazy manifest mode. The LLM saw only the stub (no schema),
+         *  so missing/wrong args are likely "I forgot to call
+         *  discover-schemas first". Return the schema inline so the
+         *  next round can compose args correctly without an extra
+         *  discovery call. In eager mode the schema is already in the
+         *  system prompt -- still safe to repeat, costs ~200 tokens
+         *  and saves a regression turn. */
+        const lazyHint = resolveManifestMode() === 'lazy'
+            ? ('Lazy manifest mode: call yujin.nac3.discover-schemas '
+                + 'before invoking complex verbs to avoid this round-trip. '
+                + 'Schema for "' + verb.id + '" included below; retry with '
+                + 'compliant args.')
+            : 'Schema for "' + verb.id + '" repeated below; retry with compliant args.';
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: true,
+            result: {
+                error: 'Args do not match the verb schema: ' + schemaErr,
+                verb_id: verb.id,
+                schema: verb.schema,
+                description: verb.description,
+                policy: verb.policy,
+                side_effects: verb.side_effects,
+                hint: lazyHint,
+            },
+            display: 'nac3_invoke <- schema fail (' + verb.id + ')',
+        };
+    }
+    /* alpha.59z.0 meta-verb -- discover-doctrine. Handled inline
+     *  because it is pure markdown read (no side effects, no
+     *  legacy alias). */
+    if (verb.id === 'yujin.doctrine.discover') {
+        const raw = args.slugs;
+        const slugs = Array.isArray(raw)
+            ? raw.filter((x) => typeof x === 'string')
+            : [];
+        let payload;
+        if (slugs.length === 0) {
+            const available = await listDoctrineSlugs();
+            payload = { ok: true, available };
+        }
+        else {
+            const got = await getDoctrines(slugs);
+            payload = { doctrines: got };
+        }
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'invoke',
+            ...baseEntry,
+            verb_id: verb.id,
+            args_sample: redactArgs(args),
+            policy: verb.policy,
+            side_effects_declared: verb.side_effects,
+            side_effects_actual: ['none'],
+            result_ok: true,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: payload,
+            display: 'nac3_invoke -> doctrine:' + slugs.length,
+        };
+    }
+    /* alpha.59x meta-verb -- discover-schemas. Handled inline
+     *  because it is pure manifest introspection (no side effects,
+     *  no legacy alias) and we want the schema lookup to be as
+     *  cheap as a manifest read. */
+    if (verb.id === 'yujin.nac3.discover-schemas') {
+        const verbIdsRaw = args.verb_ids;
+        const verbIds = Array.isArray(verbIdsRaw)
+            ? verbIdsRaw.filter((x) => typeof x === 'string')
+            : [];
+        const out = {};
+        for (const id of verbIds) {
+            const v = findVerb(id) ?? findVerbByAlias(id);
+            if (v) {
+                out[id] = {
+                    id: v.id,
+                    role: v.role,
+                    action: v.action,
+                    label: v.label,
+                    description: v.description ?? '',
+                    schema: v.schema,
+                    policy: v.policy,
+                    side_effects: v.side_effects,
+                    handler_side: v.handler_side,
+                    /* Same fields as the stub plus the schema -- the LLM can
+                     *  copy/paste into args confidently. */
+                };
+            }
+            else {
+                const closest = suggestVerbs(id, 3);
+                out[id] = { error: 'unknown verb_id', closest_verbs: closest };
+            }
+        }
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'invoke',
+            ...baseEntry,
+            verb_id: verb.id,
+            args_sample: redactArgs(args),
+            policy: verb.policy,
+            side_effects_declared: verb.side_effects,
+            side_effects_actual: ['none'],
+            result_ok: true,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: {
+                verbs: out,
+                manifest_mode: resolveManifestMode(),
+                manifest_version: m.version,
+            },
+            display: 'nac3_invoke -> schemas:' + verbIds.length,
+        };
+    }
+    /* alpha.59z.26 F101 slice 2 -- MCP bridge meta verbs.
+     *
+     * list-bridges    : real, queries the registry from slice 1.
+     * show-tools      : slice 2 stub returns the bridge endpoint +
+     *                   "tool catalogue load deferred to slice 4".
+     * discover-tools  : slice 2 stub returns a placeholder; slice 4
+     *                   wires the on-demand schema fetch.
+     * toggle          : slice 2 stub (requires persistent enabled-
+     *                   state file; ships in slice 4 alongside the
+     *                   proxy dispatcher).
+     * set-creds       : slice 2 stub (requires CredentialVault per-
+     *                   bridge slot; ships in slice 4).
+     *
+     * Per the MCP-opcional invariants documented in F101_MCP_BRIDGE,
+     * these verbs only appear in the LLM-visible stub when the
+     * registry discovered >=1 bridge. findVerb/validateArgs still
+     * resolve them; the gate is on the prompt-side. */
+    if (verb.id === 'yujin.mcp.list-bridges') {
+        const { getActiveBridges } = await import('../../mcp/bridge_registry.js');
+        const bridges = await getActiveBridges({ projectRoot: process.cwd() });
+        const payload = {
+            ok: true,
+            bridges: bridges.map((b) => ({
+                id: b.id,
+                endpoint: b.endpoint,
+                source: b.source,
+                enabled: b.enabled,
+                display_name: b.display_name ?? b.id,
+            })),
+            count: bridges.length,
+        };
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'invoke',
+            ...baseEntry,
+            verb_id: verb.id,
+            args_sample: {},
+            policy: verb.policy,
+            side_effects_declared: verb.side_effects,
+            side_effects_actual: ['none'],
+            result_ok: true,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: payload,
+            display: 'nac3_invoke -> bridges:' + bridges.length,
+        };
+    }
+    if (verb.id === 'yujin.mcp.show-tools') {
+        /* F101 slice 4 FULL: delegate to the MCPClient appropriate
+         * for the bridge protocol (http_rest / stdio / sse). The
+         * http_rest path preserves slice 4 minimal behaviour. */
+        const bridgeId = String(args.bridge_id ?? '');
+        const { getActiveBridges } = await import('../../mcp/bridge_registry.js');
+        const bridges = await getActiveBridges({ projectRoot: process.cwd() });
+        const bridge = bridges.find((b) => b.id === bridgeId);
+        if (!bridge) {
+            await logDispatch({
+                ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+                verb_id: verb.id, args_sample: redactArgs(args),
+                policy: verb.policy, side_effects_declared: verb.side_effects,
+                side_effects_actual: ['none'], result_ok: false,
+                result_error: 'unknown_bridge_id:' + bridgeId,
+                duration_ms: Date.now() - startedAt,
+            });
+            return {
+                tool: NAC3_INVOKE_SPEC.name, is_error: true,
+                result: { ok: false, error: 'unknown_bridge_id', bridge_id: bridgeId, available: bridges.map((b) => b.id) },
+                display: 'nac3_invoke <- bridge not found',
+            };
+        }
+        const { getMCPClient } = await import('../../mcp/protocol_client.js');
+        const client = getMCPClient(bridge);
+        const listResult = await client.listTools();
+        const sideActual = client.transport === 'stdio' ? ['process'] : ['network'];
+        await logDispatch({
+            ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+            verb_id: verb.id, args_sample: redactArgs(args),
+            policy: verb.policy, side_effects_declared: verb.side_effects,
+            side_effects_actual: sideActual,
+            result_ok: listResult.ok,
+            result_error: listResult.ok ? undefined : (listResult.detail || listResult.error),
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: listResult.ok
+                ? { ok: true, bridge_id: bridgeId, endpoint: bridge.endpoint, transport: client.transport, tools: listResult.tools, count: listResult.count }
+                : { ok: false, bridge_id: bridgeId, transport: client.transport, error: listResult.error, detail: listResult.detail },
+            display: listResult.ok
+                ? 'nac3_invoke -> tools:' + listResult.count + ' via ' + client.transport
+                : 'nac3_invoke <- ' + listResult.error + ' (' + client.transport + ')',
+        };
+    }
+    if (verb.id === 'yujin.mcp.invoke-tool') {
+        /* Slice 4 real: POST <endpoint>/tools/<tool_slug>/invoke with
+         * the args body. Bridge response is forwarded verbatim. Audit
+         * trail records bridge_id + bridge_endpoint + tool_slug so
+         * MCP-proxied invocations are queryable separately from native
+         * dispatch. R8 modal already triggered upstream by the gate
+         * since the verb policy is approval-required. */
+        const bridgeId = String(args.bridge_id ?? '');
+        const toolSlug = String(args.tool_slug ?? '');
+        const toolArgs = args.args ?? {};
+        const { getActiveBridges } = await import('../../mcp/bridge_registry.js');
+        const bridges = await getActiveBridges({ projectRoot: process.cwd() });
+        const bridge = bridges.find((b) => b.id === bridgeId);
+        if (!bridge) {
+            await logDispatch({
+                ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+                verb_id: verb.id, args_sample: redactArgs(args),
+                policy: verb.policy, side_effects_declared: verb.side_effects,
+                side_effects_actual: ['none'], result_ok: false,
+                result_error: 'unknown_bridge_id:' + bridgeId,
+                duration_ms: Date.now() - startedAt,
+            });
+            return {
+                tool: NAC3_INVOKE_SPEC.name, is_error: true,
+                result: { ok: false, error: 'unknown_bridge_id', bridge_id: bridgeId, available: bridges.map((b) => b.id) },
+                display: 'nac3_invoke <- bridge not found',
+            };
+        }
+        /* F101 slice 5 sub-slice 2 -- attach Authorization: Bearer
+         * <token> when the per-bridge Vault slot has a value. Slot
+         * name follows the canonical mcp_<bridge_id>_token pattern.
+         * The header is only relevant to the http_rest + sse transports;
+         * the stdio client ignores it (auth on stdio happens via env
+         * vars set at spawn time). */
+        const credsSlot = 'mcp_' + bridgeId.toLowerCase().replace(/[^a-z0-9_-]/g, '_') + '_token';
+        const authHeaders = {};
+        try {
+            const { getKey } = await import('../../core/provider_keys.js');
+            const token = await getKey(credsSlot);
+            if (token)
+                authHeaders['authorization'] = 'Bearer ' + token;
+        }
+        catch { /* swallow -- proceed without auth */ }
+        /* F101 slice 4 FULL: dispatch via MCPClient picked by bridge
+         * protocol. http_rest preserves slice 4 minimal; stdio + sse
+         * add real MCP transport support. */
+        const { getMCPClient } = await import('../../mcp/protocol_client.js');
+        const client = getMCPClient(bridge);
+        const invokeResult = await client.invokeTool(toolSlug, toolArgs, authHeaders);
+        let toolResult = null;
+        let invokeError;
+        if (invokeResult.ok) {
+            toolResult = invokeResult.response;
+        }
+        else {
+            invokeError = invokeResult.detail || invokeResult.error;
+            toolResult = invokeResult.partial_response ?? null;
+        }
+        await logDispatch({
+            ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+            verb_id: verb.id,
+            args_sample: redactArgs({
+                bridge_id: bridgeId,
+                bridge_endpoint: bridge.endpoint,
+                tool_slug: toolSlug,
+                /* Args from the tool are NOT redacted into the audit log
+                 * field because they could carry per-tool semantics (file
+                 * paths, query strings) that operators need to see. The
+                 * redactor handles standard secret patterns. */
+                ...(typeof toolArgs === 'object' && toolArgs !== null ? toolArgs : {}),
+            }),
+            policy: verb.policy, side_effects_declared: verb.side_effects,
+            side_effects_actual: invokeError ? ['network'] : ['network', 'external-api'],
+            result_ok: !invokeError,
+            result_error: invokeError,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            /* PND-052 (sec 2.4) -- reflect the real outcome (was hard-coded
+             * false, so a failed MCP tool call looked successful). */
+            is_error: !!invokeError,
+            result: {
+                ok: !invokeError,
+                bridge_id: bridgeId,
+                tool_slug: toolSlug,
+                ...(invokeError ? { error: 'bridge_invoke_failed', detail: invokeError, partial_response: toolResult } : { response: toolResult }),
+            },
+            display: invokeError
+                ? 'nac3_invoke <- mcp:' + bridgeId + '/' + toolSlug + ' failed'
+                : 'nac3_invoke -> mcp:' + bridgeId + '/' + toolSlug,
+        };
+    }
+    if (verb.id === 'yujin.mcp.toggle') {
+        /* F101 slice 5 sub-slice 1: persistent enabled-state writer.
+         * Writes to ~/.yujin-forge/mcp-state.json atomically + busts
+         * the discovery cache so the next chat turn sees the new
+         * state. R8 modal already fired upstream (approval-required
+         * policy). */
+        const bridgeId = String(args.bridge_id ?? '');
+        const enabled = Boolean(args.enabled);
+        const { getActiveBridges, resetBridgeCache } = await import('../../mcp/bridge_registry.js');
+        const bridges = await getActiveBridges({ projectRoot: process.cwd() });
+        const bridge = bridges.find((b) => b.id === bridgeId);
+        if (!bridge) {
+            await logDispatch({
+                ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+                verb_id: verb.id, args_sample: redactArgs(args),
+                policy: verb.policy, side_effects_declared: verb.side_effects,
+                side_effects_actual: ['none'], result_ok: false,
+                result_error: 'unknown_bridge_id:' + bridgeId,
+                duration_ms: Date.now() - startedAt,
+            });
+            return {
+                tool: NAC3_INVOKE_SPEC.name, is_error: true,
+                result: { ok: false, error: 'unknown_bridge_id', bridge_id: bridgeId, available: bridges.map((b) => b.id) },
+                display: 'nac3_invoke <- bridge not found',
+            };
+        }
+        const { setBridgeEnabled } = await import('../../mcp/state.js');
+        await setBridgeEnabled(bridgeId, enabled);
+        resetBridgeCache();
+        await logDispatch({
+            ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+            verb_id: verb.id, args_sample: redactArgs(args),
+            policy: verb.policy, side_effects_declared: verb.side_effects,
+            side_effects_actual: ['filesystem'], result_ok: true,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name, is_error: false,
+            result: {
+                ok: true, bridge_id: bridgeId, enabled,
+                message: 'Bridge ' + bridgeId + ' set to ' + (enabled ? 'enabled' : 'disabled') + '. The next chat turn will reflect this change.',
+            },
+            display: 'nac3_invoke -> mcp toggle ' + bridgeId + '=' + (enabled ? 'on' : 'off'),
+        };
+    }
+    if (verb.id === 'yujin.mcp.set-creds') {
+        /* F101 slice 5 sub-slice 2: write a per-bridge bearer token
+         * to CredentialVault under the dynamic slot
+         * mcp_<bridge_id>_token. R8 modal already fired upstream
+         * (destructive policy).
+         *
+         * The verb args include creds_slot for back-compat with the
+         * slice 2 schema, but the canonical slot name is the dynamic
+         * mcp_<bridge_id>_token pattern. If creds_slot does not match
+         * this pattern we reject -- the bridge_id MUST be in the slot
+         * name for the invoke-tool handler to find it without an extra
+         * args field. The set-creds verb does NOT carry the secret
+         * token itself in its args (LLM should not see it); the
+         * actual token must come via a separate `yf keys set <slot>`
+         * step. The verb just records the binding + verifies the
+         * slot exists. */
+        const bridgeId = String(args.bridge_id ?? '');
+        const credsSlot = String(args.creds_slot ?? '');
+        const expected = 'mcp_' + bridgeId.toLowerCase().replace(/[^a-z0-9_-]/g, '_') + '_token';
+        if (credsSlot !== expected) {
+            await logDispatch({
+                ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+                verb_id: verb.id, args_sample: redactArgs(args),
+                policy: verb.policy, side_effects_declared: verb.side_effects,
+                side_effects_actual: ['none'], result_ok: false,
+                result_error: 'creds_slot mismatch; expected ' + expected,
+                duration_ms: Date.now() - startedAt,
+            });
+            return {
+                tool: NAC3_INVOKE_SPEC.name, is_error: true,
+                result: {
+                    ok: false,
+                    error: 'creds_slot_mismatch',
+                    expected_slot: expected,
+                    received_slot: credsSlot,
+                    hint: 'Slot name MUST be mcp_<bridge_id>_token. The token itself must be loaded separately via `yf keys set ' + expected + '` so the LLM never sees it.',
+                },
+                display: 'nac3_invoke <- mcp creds slot mismatch',
+            };
+        }
+        const { hasKey } = await import('../../core/provider_keys.js');
+        const present = await hasKey(expected);
+        await logDispatch({
+            ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+            verb_id: verb.id, args_sample: redactArgs(args),
+            policy: verb.policy, side_effects_declared: verb.side_effects,
+            side_effects_actual: ['filesystem'], result_ok: true,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name, is_error: false,
+            result: {
+                ok: true,
+                bridge_id: bridgeId,
+                slot: expected,
+                token_present: present,
+                message: present
+                    ? 'Binding confirmed. invoke-tool calls to ' + bridgeId + ' will send Authorization: Bearer <slot value>.'
+                    : 'Slot ' + expected + ' is empty. Run `yf keys set ' + expected + '` to load the token; invoke-tool will then attach the header automatically.',
+            },
+            display: 'nac3_invoke -> mcp creds ' + bridgeId + ' (token ' + (present ? 'loaded' : 'pending') + ')',
+        };
+    }
+    if (verb.id === 'yujin.mcp.discover-tools') {
+        /* Slice 4 full ships the on-demand schema fetch for
+         * MCP-proxied tools via the stdio/SSE protocol client. Until
+         * then the brain calls show-tools which returns the full
+         * catalogue (slice 4 minimal). */
+        const payload = {
+            ok: false,
+            deferred_to: 'F101 slice 4 full (MCP stdio/SSE client)',
+            message: 'discover-tools is the lazy variant of show-tools. Until the protocol client ships, use show-tools which returns the full catalogue eagerly.',
+            args_received: args,
+        };
+        await logDispatch({
+            ts: new Date().toISOString(), kind: 'invoke', ...baseEntry,
+            verb_id: verb.id, args_sample: redactArgs(args),
+            policy: verb.policy, side_effects_declared: verb.side_effects,
+            side_effects_actual: ['none'], result_ok: false,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name, is_error: false, result: payload,
+            display: 'nac3_invoke -> mcp-stub (' + verb.id + ')',
+        };
+    }
+    /* Policy gate (server-enforced side; the panel double-gates
+     *  visible-policy verbs). */
+    if (verb.policy === 'byok-required') {
+        /* Stub: read the BYOK key catalogue and check at least one
+         *  brain key exists. The detailed enforcement is up to the
+         *  verb handler. */
+        /* Intentionally not implemented yet; alpha.40 ships the
+         *  dispatch surface and uses byok-required as documentation. */
+    }
+    if (verb.policy === 'project-root-gated') {
+        /* For args carrying a 'path' or 'subdir', defence-in-depth.
+         *  The legacy handlers already enforce this; we just log. */
+    }
+    /* alpha.42 -- destructive / approval-required GATE.
+     *
+     * The dispatcher does NOT run the legacy handler here. Instead
+     * it enqueues a pending approval row keyed by trace_id and
+     * returns an envelope. The panel intercept opens a modal; the
+     * user clicks Approve / Reject; the panel POSTs the decision
+     * to /api/forge/nac3-approve or /nac3-reject. The endpoint
+     * resolves the row and runs the actual handler (or logs the
+     * rejection).
+     *
+     * Approval is bypassed when:
+     *   - opts.approval_bypass === true (already-approved re-entry
+     *     from the approve endpoint; would otherwise loop).
+     * Nothing else is exempt -- destructive ALWAYS hits the modal.
+     */
+    if (POLICIES_NEED_APPROVAL.has(verb.policy)
+        && verb.handler_side === 'server'
+        && !opts.approval_bypass) {
+        /* alpha.59d -- Danger Zone master toggle. When ON, the
+         *  modal is skipped + the call proceeds with approval_mode=
+         *  'danger_zone_bypass' so the audit log still records the
+         *  invocation cleanly. */
+        let dangerZoneBypass = false;
+        try {
+            const { readLimitsConfig } = await import('../../core/limits_config.js');
+            const lim = await readLimitsConfig();
+            if (lim.danger_zone && lim.danger_zone.auto_approve_all === true) {
+                dangerZoneBypass = true;
+            }
+        }
+        catch { /* swallow */ }
+        /* Resolve the alias OR fall back to verb_id (alpha.59d
+         *  native handlers like yujin.shell.exec). */
+        const alias = (verb.deprecated_aliases && verb.deprecated_aliases[0]) || verb.id;
+        if (!alias) {
+            return {
+                tool: NAC3_INVOKE_SPEC.name,
+                is_error: true,
+                result: { error: 'destructive verb "' + verb.id + '" has no legacy implementation' },
+                display: 'nac3_invoke <- no impl ' + verb.id,
+            };
+        }
+        if (dangerZoneBypass) {
+            /* Skip the modal, dispatch directly with the audit
+             *  approval_mode set. */
+            const argsWithMode = {
+                ...args,
+                approval_mode: 'danger_zone_bypass',
+            };
+            try {
+                const r = await opts.legacyRun(alias, argsWithMode, ctx);
+                await logDispatch({
+                    ts: new Date().toISOString(),
+                    kind: 'invoke',
+                    ...baseEntry,
+                    verb_id: verb.id,
+                    alias_used: alias,
+                    args_sample: redactArgs(args),
+                    policy: verb.policy,
+                    side_effects_declared: verb.side_effects,
+                    result_ok: !r.is_error,
+                    result_error: r.is_error ? String(r.result?.error ?? 'error') : undefined,
+                    duration_ms: Date.now() - startedAt,
+                });
+                return r;
+            }
+            catch (err) {
+                return {
+                    tool: NAC3_INVOKE_SPEC.name,
+                    is_error: true,
+                    result: { error: 'danger zone handler threw: ' + (err instanceof Error ? err.message : String(err)) },
+                    display: 'nac3_invoke <- danger zone error',
+                };
+            }
+        }
+        enqueueApproval({
+            trace_id,
+            verb,
+            args,
+            ctx,
+            legacy_alias: alias,
+            legacy_run: opts.legacyRun,
+            created_at: Date.now(),
+            agent_slug: opts.agentSlug,
+        });
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'invoke',
+            ...baseEntry,
+            verb_id: verb.id,
+            alias_used: alias,
+            args_sample: redactArgs(args),
+            policy: verb.policy,
+            side_effects_declared: verb.side_effects,
+            result_ok: true,
+            duration_ms: Date.now() - startedAt,
+            /* mark as awaiting -- the row will be paired later with the
+               approve/reject decision in nac3_approvals.jsonl. */
+            result_error: 'awaiting_user_approval',
+        });
+        /* alpha.59d.2 -- attach a classification block so the panel
+         *  modal can render a coloured risk badge + reasons. For
+         *  shell.exec the bucket comes from shell_classifier (rich
+         *  signal); for other verbs we synthesise a bucket from the
+         *  policy + side_effects so the modal still gets a chip. */
+        let classification;
+        if (verb.id === 'yujin.shell.exec') {
+            try {
+                const { classifyShellCommand } = await import('../../core/shell_classifier.js');
+                const cmd = typeof args.command === 'string'
+                    ? args.command
+                    : '';
+                const sc = classifyShellCommand(cmd);
+                classification = { bucket: sc.bucket, reasons: sc.reasons };
+            }
+            catch {
+                classification = { bucket: 'approval', reasons: ['classifier unavailable'] };
+            }
+        }
+        else if (verb.policy === 'destructive') {
+            classification = {
+                bucket: 'destructive',
+                reasons: ['policy=destructive', 'side_effects=' + (verb.side_effects || []).join(',')],
+            };
+        }
+        else {
+            classification = {
+                bucket: 'approval',
+                reasons: ['policy=' + verb.policy, 'side_effects=' + (verb.side_effects || []).join(',')],
+            };
+        }
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: {
+                nac3_panel_approval_required: true,
+                trace_id,
+                verb: {
+                    id: verb.id,
+                    action: verb.action,
+                    role: verb.role,
+                    label: verb.label,
+                    policy: verb.policy,
+                    side_effects: verb.side_effects,
+                },
+                args,
+                classification,
+            },
+            display: 'nac3_invoke -> awaiting approval (' + verb.id + ' [' + classification.bucket + '])',
+        };
+    }
+    /* Dispatch. */
+    if (verb.handler_side === 'panel') {
+        /* Return an envelope the panel will pick up from tool_rounds. */
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'invoke',
+            ...baseEntry,
+            verb_id: verb.id,
+            alias_used,
+            args_sample: redactArgs(args),
+            policy: verb.policy,
+            side_effects_declared: verb.side_effects,
+            side_effects_actual: ['dom'],
+            result_ok: true,
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: {
+                nac3_panel_dispatch: true,
+                trace_id,
+                verb: {
+                    id: verb.id,
+                    action: verb.action,
+                    role: verb.role,
+                    policy: verb.policy,
+                    side_effects: verb.side_effects,
+                },
+                args,
+            },
+            display: 'nac3_invoke -> panel:' + verb.action + ' (' + verb.id + ')',
+        };
+    }
+    /* handler_side === 'server': route to a handler. alpha.59d --
+     *  prefer the verb_id directly (the dispatcher's switch knows
+     *  yujin.* verbs natively); fall back to the legacy alias for
+     *  pre-alpha.41 surfaces. */
+    let alias = verb.deprecated_aliases && verb.deprecated_aliases[0];
+    if (!alias) {
+        /* No legacy alias declared -- try the verb_id itself as a
+         *  native handler name. tools.ts adds cases for yujin.* verbs
+         *  introduced in alpha.59d (mkdir / move / project.init /
+         *  project.set-root / shell.exec). */
+        alias = verb.id;
+    }
+    /* Forward the dispatcher-resolved approval mode to the handler
+     *  via args.approval_mode so audit rows capture how the invocation
+     *  was approved (auto / user / danger_zone). PND-052 (sec 2.1) --
+     *  was `_approval_mode` (underscore), which no handler ever read,
+     *  so every audit row defaulted to 'user_approved' regardless of
+     *  the real mode. The handlers + panel audit read `approval_mode`. */
+    const argsWithMode = { ...args };
+    if (typeof args.approval_mode !== 'string') {
+        argsWithMode.approval_mode = verb.policy === 'unrestricted' ? 'auto_approved' : 'user_approved';
+    }
+    let r;
+    try {
+        r = await opts.legacyRun(alias, argsWithMode, ctx);
+    }
+    catch (err) {
+        await logDispatch({
+            ts: new Date().toISOString(),
+            kind: 'invoke',
+            ...baseEntry,
+            verb_id: verb.id,
+            alias_used: alias,
+            args_sample: redactArgs(args),
+            policy: verb.policy,
+            side_effects_declared: verb.side_effects,
+            result_ok: false,
+            result_error: err instanceof Error ? err.message : String(err),
+            duration_ms: Date.now() - startedAt,
+        });
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: true,
+            result: {
+                error: 'verb handler threw: ' + (err instanceof Error ? err.message : String(err)),
+                verb_id: verb.id,
+            },
+            display: 'nac3_invoke <- handler threw',
+        };
+    }
+    await logDispatch({
+        ts: new Date().toISOString(),
+        kind: 'invoke',
+        ...baseEntry,
+        verb_id: verb.id,
+        alias_used: alias,
+        args_sample: redactArgs(args),
+        policy: verb.policy,
+        side_effects_declared: verb.side_effects,
+        side_effects_actual: verb.side_effects,
+        result_ok: !r.is_error,
+        result_error: r.is_error
+            ? (typeof r.result === 'object' && r.result && 'error' in r.result
+                ? String(r.result.error)
+                : 'unknown')
+            : undefined,
+        duration_ms: Date.now() - startedAt,
+    });
+    /* panel_consume = the server-side handler ran (e.g. read a file
+     *  from disk) and the result is meant to materialise a UI update
+     *  in the panel. Wrap as a panel-dispatch envelope so the panel
+     *  intercept sees the canonical shape (same as handler_side=
+     *  panel verbs above). */
+    if (!r.is_error && verb.panel_consume) {
+        return {
+            tool: NAC3_INVOKE_SPEC.name,
+            is_error: false,
+            result: {
+                nac3_panel_dispatch: true,
+                trace_id,
+                verb: {
+                    id: verb.id,
+                    action: verb.action,
+                    role: verb.role,
+                    policy: verb.policy,
+                    side_effects: verb.side_effects,
+                },
+                args,
+                server_payload: r.result,
+            },
+            display: 'nac3_invoke -> panel(consume):' + verb.action + ' (' + verb.id + ')',
+        };
+    }
+    return {
+        tool: NAC3_INVOKE_SPEC.name,
+        is_error: r.is_error ?? false,
+        result: r.result,
+        display: 'nac3_invoke -> ' + verb.id + (r.is_error ? ' (error)' : ' (ok)'),
+    };
+}
+//# sourceMappingURL=nac3_invoke.js.map