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

package/dist/chat/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/chat/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAyDH,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QACxG,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,gEAAgE;IAChE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB;;gDAE4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD,eAAO,MAAM,kBAAkB,EAAE,QAchC,CAAC;AAEF,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA+C3G;AAMD,eAAO,MAAM,gBAAgB,EAAE,QAkB9B,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7C,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CAmDrB;AAED;;0BAE0B;AAC1B,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,EAAE,CAkClF;AAoBD,eAAO,MAAM,eAAe,EAAE,QAsB7B,CAAC;AAOF,wBAAsB,YAAY,CAChC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5D,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CAkErB;AASD;;;0BAG0B;AAC1B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,IAAI,CAUhG;AAMD,eAAO,MAAM,cAAc,EAAE,QAkB5B,CAAC;AAKF,wBAAsB,WAAW,CAC/B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1C,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CAiGrB;AAaD,eAAO,MAAM,gBAAgB,EAAE,QAAQ,EAyCtC,CAAC;AAEF;oEACoE;AACpE,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CA0DrB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/chat/tools.ts"],"names":[],"mappings":"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"}

package/dist/chat/tools.js

@@ -35,9 +35,16 @@ import path from 'node:path';
 import { CREATE_GITHUB_REPO_SPEC, CLONE_REPO_SPEC, BRANCH_STATUS_SPEC, runCreateGithubRepo, runCloneRepo, runBranchStatus, } from './tools/github.js';
 import { GIT_COMMIT_SPEC, GIT_PUSH_SPEC, GIT_PULL_SPEC, GIT_LOG_SPEC, runGitCommit, runGitPush, runGitPull, runGitLog, } from './tools/git.js';
 import { AUDIT_CONSUMERS_SPEC, runAuditConsumers, } from './tools/audit_consumers.js';
+import { WORKFLOW_STATE_SPEC, WORKFLOW_SET_SPEC, WORKFLOW_RUN_STEP_SPEC, WORKFLOW_LOG_STEP_SPEC, runWorkflowState, runWorkflowSet, runWorkflowRunStep, runWorkflowLogStep, runWorkflowStart, runWorkflowAddTask, runWorkflowConfigure, } from './tools/workflow.js';
+import { GET_BYOK_STATUS_SPEC, SET_BYOK_KEY_SPEC, runGetByokStatus, runSetByokKey, } from './tools/keys.js';
+import { SHOW_IN_PIZARRON_SPEC, runShowInPizarron, } from './tools/pizarron.js';
+import { NAC3_INVOKE_SPEC, runNac3Invoke, } from './tools/nac3_invoke.js';
+import { runOpenFileForEditor, runWriteProjectFile, } from './tools/fs_editor.js';
 import { RUN_APP_SPEC, STOP_APP_SPEC, RESTART_APP_SPEC, runApp, stopApp, restartApp, } from './tools/lifecycle.js';
 import { READER_OPEN_SPEC, READER_LIST_DOCS_SPEC, READER_READ_SECTION_SPEC, READER_NEXT_BLOCK_SPEC, READER_SEARCH_SPEC, READER_BOOKMARK_SET_SPEC, READER_BOOKMARK_JUMP_SPEC, READER_RECAP_SPEC, runReaderOpen, runReaderListDocuments, runReaderReadSection, runReaderNextBlock, runReaderSearch, runReaderBookmarkSet, runReaderBookmarkJump, runReaderRecap, } from './tools/reader.js';
 import { MANUAL_OPEN_SPEC, runManualOpen, } from './tools/manual.js';
+import { runFsMkdir, runFsMove, runProjectInit, runProjectSetRoot, } from './tools/project_lifecycle.js';
+import { runShellExec } from './tools/shell.js';
 /* ============================================================
  * forge.read_manifest
  * ============================================================ */
@@ -341,6 +348,101 @@ function clampListMax(n) {
         return 500;
     return Math.floor(n);
 }
+const FIND_DEFAULT_HITS = 50;
+const FIND_MAX_HITS = 500;
+const FIND_DEFAULT_FILES = 1000;
+const FIND_MAX_FILES = 5000;
+const FIND_MAX_FILE_BYTES = 1_048_576; /* 1 MB skip threshold */
+export async function runFsFind(args, ctx) {
+    if (!args.pattern || typeof args.pattern !== 'string') {
+        return { tool: 'yujin.fs.find', result: { error: 'pattern is required (string)' }, is_error: true, display: 'missing pattern' };
+    }
+    const sub = (args.subdir || '.').trim();
+    if (path.isAbsolute(sub) || sub.includes('..')) {
+        return { tool: 'yujin.fs.find', result: { error: 'subdir must be relative + contained within projectRoot' }, is_error: true, display: 'invalid subdir' };
+    }
+    let re;
+    try {
+        re = new RegExp(args.pattern, args.flags || 'i');
+    }
+    catch (err) {
+        return { tool: 'yujin.fs.find', result: { error: 'bad regex: ' + (err instanceof Error ? err.message : String(err)) }, is_error: true, display: 'bad regex' };
+    }
+    const maxHits = Math.max(1, Math.min(FIND_MAX_HITS, Math.floor(args.max_hits ?? FIND_DEFAULT_HITS)));
+    const maxFiles = Math.max(1, Math.min(FIND_MAX_FILES, Math.floor(args.max_files ?? FIND_DEFAULT_FILES)));
+    const matcher = compileBasenameGlob(args.glob);
+    const root = path.join(ctx.projectRoot, sub);
+    const hits = [];
+    let filesScanned = 0;
+    let truncated = false;
+    async function walk(dir, relBase) {
+        if (truncated)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT')
+                throw new Error('subdir not found: ' + sub);
+            throw err;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (truncated)
+                return;
+            if (SKIP_DIRS.has(e.name))
+                continue;
+            const full = path.join(dir, e.name);
+            const rel = relBase ? (relBase + '/' + e.name) : e.name;
+            if (e.isDirectory()) {
+                await walk(full, rel);
+            }
+            else if (e.isFile()) {
+                if (matcher && !matcher(e.name))
+                    continue;
+                filesScanned++;
+                if (filesScanned > maxFiles) {
+                    truncated = true;
+                    return;
+                }
+                try {
+                    const stat = await fs.stat(full);
+                    if (stat.size > FIND_MAX_FILE_BYTES)
+                        continue;
+                    const content = await fs.readFile(full, 'utf-8');
+                    const lines = content.split('\n');
+                    for (let i = 0; i < lines.length; i++) {
+                        const line = lines[i] ?? '';
+                        const m = line.match(re);
+                        if (m) {
+                            hits.push({ path: rel, line: i + 1, match: m[0].slice(0, 200), context: line.slice(0, 300) });
+                            if (hits.length >= maxHits) {
+                                truncated = true;
+                                return;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    /* binary or unreadable -- skip */
+                }
+            }
+        }
+    }
+    try {
+        await walk(root, '');
+    }
+    catch (err) {
+        return { tool: 'yujin.fs.find', result: { error: err.message }, is_error: true, display: 'find failed' };
+    }
+    return {
+        tool: 'yujin.fs.find',
+        result: { pattern: args.pattern, flags: args.flags || 'i', subdir: sub, hits, files_scanned: filesScanned, truncated },
+        display: 'found ' + hits.length + ' hit(s) across ' + filesScanned + ' file(s)' + (truncated ? ' (truncated)' : ''),
+    };
+}
 /** Compile a glob like "*.tsx" / "App.*" into a basename matcher.
  *  Only handles "*" and "?" -- enough for the common adopter case
  *  and keeps the implementation dependency-free.
@@ -488,31 +590,32 @@ function clampReadCap(n) {
 /* ============================================================
  * Registry
  * ============================================================ */
+/* alpha.41: the LLM sees ONE tool. Every action is reachable
+ *  through the NAC3 internal manifest (docs/NAC3_INTERNAL_MANIFEST.md).
+ *  Legacy forge_* implementations stay alive as the engine behind
+ *  runNac3Invoke -- they are routed via deprecated_aliases. */
 export const FORGE_TOOL_SPECS = [
+    NAC3_INVOKE_SPEC,
+];
+/** Legacy tool catalogue, kept exported for tests that directly
+ *  exercise individual specs (alpha 35 era + earlier). NOT served
+ *  to Anthropic anymore. Will be removed in alpha 50 once every
+ *  test verifies the verb through nac3_invoke. */
+export const LEGACY_FORGE_TOOL_SPECS = [
     READ_MANIFEST_SPEC,
     CONSULT_NAC_SPEC,
     LIST_FILES_SPEC,
     READ_FILE_SPEC,
-    /* GitHub tools (V1.11). create_repo + clone_repo are write-class
-       and carry requires_approval=true; branch_status is read-only. */
     CREATE_GITHUB_REPO_SPEC,
     CLONE_REPO_SPEC,
     BRANCH_STATUS_SPEC,
-    /* Local git tools (V1.12). commit / push / pull are write-class;
-       log is read-only. push --force triggers V1.10 liveness via
-       the dispatcher's irreversible classification. */
     GIT_COMMIT_SPEC,
     GIT_PUSH_SPEC,
     GIT_PULL_SPEC,
     GIT_LOG_SPEC,
-    /* App lifecycle tools (V1.13). All three are write-class
-       (they spawn / kill child processes). */
     RUN_APP_SPEC,
     STOP_APP_SPEC,
     RESTART_APP_SPEC,
-    /* Reader tools (V1.28). All read-only; the reader does
-       not write to the project, it parses + remembers state +
-       answers queries. */
     READER_OPEN_SPEC,
     READER_LIST_DOCS_SPEC,
     READER_READ_SECTION_SPEC,
@@ -521,14 +624,14 @@ export const FORGE_TOOL_SPECS = [
     READER_BOOKMARK_SET_SPEC,
     READER_BOOKMARK_JUMP_SPEC,
     READER_RECAP_SPEC,
-    /* Manual tool (Fase F.7 / F.8 -- 10-language HTML manuals
-       resolved by user language). Read-only, requires_approval=false. */
     MANUAL_OPEN_SPEC,
-    /* Producer/Consumer audit tool (SQ Sec X "Producer/Consumer
-       Symmetry"). Forge calls this BEFORE any commit that touches a
-       shared data structure. Read-only grep. */
     AUDIT_CONSUMERS_SPEC,
-    /* More tools land in follow-up commits per the docstring. */
+    WORKFLOW_STATE_SPEC,
+    WORKFLOW_SET_SPEC,
+    WORKFLOW_RUN_STEP_SPEC,
+    GET_BYOK_STATUS_SPEC,
+    SET_BYOK_KEY_SPEC,
+    SHOW_IN_PIZARRON_SPEC,
 ];
 /** Dispatch a tool by name with the args Anthropic returned. Returns
  *  a ToolResult ready to be serialised into a tool_result block. */
@@ -540,6 +643,20 @@ export async function runForgeTool(name, args, ctx) {
             return runConsultNacSpec(args, ctx);
         case LIST_FILES_SPEC.name:
             return runListFiles(args, ctx);
+        case 'yujin.fs.find':
+            /* eslint-disable @typescript-eslint/no-explicit-any */
+            return runFsFind(args, ctx);
+        case 'yujin.json.query': {
+            const { runJsonQuery } = await import('../json/query.js');
+            const { input, query } = args;
+            const r = runJsonQuery(input, query);
+            return {
+                tool: 'yujin.json.query',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('json.query ok') : ('json.query ' + r.error),
+            };
+        }
         case READ_FILE_SPEC.name:
             return runReadFile(args, ctx);
         case CREATE_GITHUB_REPO_SPEC.name:
@@ -556,6 +673,46 @@ export async function runForgeTool(name, args, ctx) {
             return runGitPull(args, ctx);
         case GIT_LOG_SPEC.name:
             return runGitLog(args, ctx);
+        case 'yujin.git.diff': {
+            const { runGitDiff } = await import('./tools/git.js');
+            return runGitDiff(args, ctx);
+        }
+        case 'yujin.git.show': {
+            const { runGitShow } = await import('./tools/git.js');
+            return runGitShow(args, ctx);
+        }
+        case 'yujin.git.status': {
+            const { runGitStatus } = await import('./tools/misc_verbs.js');
+            return runGitStatus(args, ctx.projectRoot);
+        }
+        case 'yujin.git.branch-list': {
+            const { runGitBranchList } = await import('./tools/misc_verbs.js');
+            return runGitBranchList(args, ctx.projectRoot);
+        }
+        case 'yujin.text.diff': {
+            const { runTextDiff } = await import('./tools/misc_verbs.js');
+            return runTextDiff(args);
+        }
+        case 'yujin.url.parse': {
+            const { runUrlParse } = await import('./tools/misc_verbs.js');
+            return runUrlParse(args);
+        }
+        case 'yujin.json.parse': {
+            const { runJsonParse } = await import('./tools/misc_verbs.js');
+            return runJsonParse(args);
+        }
+        case 'yujin.json.stringify': {
+            const { runJsonStringify } = await import('./tools/misc_verbs.js');
+            return runJsonStringify(args);
+        }
+        case 'yujin.env.list': {
+            const { runEnvList } = await import('./tools/misc_verbs.js');
+            return runEnvList(args);
+        }
+        case 'yujin.npm.outdated': {
+            const { runNpmOutdated } = await import('./tools/misc_verbs.js');
+            return runNpmOutdated(args, ctx.projectRoot);
+        }
         case RUN_APP_SPEC.name:
             return runApp(args, ctx);
         case STOP_APP_SPEC.name:
@@ -582,6 +739,358 @@ export async function runForgeTool(name, args, ctx) {
             return runManualOpen(args, ctx);
         case AUDIT_CONSUMERS_SPEC.name:
             return runAuditConsumers(args, ctx);
+        case WORKFLOW_STATE_SPEC.name:
+            return runWorkflowState(args, ctx);
+        case WORKFLOW_SET_SPEC.name:
+            return runWorkflowSet(args, ctx);
+        case WORKFLOW_RUN_STEP_SPEC.name:
+            return runWorkflowRunStep(args, ctx);
+        case WORKFLOW_LOG_STEP_SPEC.name:
+            return runWorkflowLogStep(args, ctx);
+        case 'yujin.workflow.start':
+            return runWorkflowStart(args, ctx);
+        case 'yujin.workflow.add-task':
+            return runWorkflowAddTask(args, ctx);
+        case 'yujin.workflow.configure':
+            return runWorkflowConfigure(args, ctx);
+        case GET_BYOK_STATUS_SPEC.name:
+            return runGetByokStatus(args, ctx);
+        case SET_BYOK_KEY_SPEC.name:
+            return runSetByokKey(args, ctx);
+        case SHOW_IN_PIZARRON_SPEC.name:
+            return runShowInPizarron(args, ctx);
+        case 'forge_open_file_for_editor':
+            return runOpenFileForEditor(args, ctx);
+        case 'forge_write_project_file':
+            return runWriteProjectFile(args, ctx);
+        /* alpha.59d -- lifecycle + shell verbs are routed natively
+         * (no legacy aliases). nac3_invoke falls back to verb_id
+         * as the handler name when no alias is declared. */
+        case 'yujin.fs.mkdir':
+            return runFsMkdir(args, ctx);
+        case 'yujin.fs.move':
+            return runFsMove(args, ctx);
+        case 'yujin.project.init':
+            return runProjectInit(args, ctx);
+        case 'yujin.project.set-root':
+            return runProjectSetRoot(args, ctx);
+        case 'yujin.shell.exec':
+            return runShellExec(args, ctx);
+        /* F106 office verbs -- cross-platform Excel + Word. */
+        case 'office.excel.read': {
+            const { readExcel } = await import('../office/excel.js');
+            const r = await readExcel(args, ctx.projectRoot);
+            return {
+                tool: 'office.excel.read',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('Excel read: ' + r.row_count + ' rows from ' + r.sheet) : ('Excel read failed: ' + r.error),
+            };
+        }
+        case 'office.excel.list-sheets': {
+            const { listSheets } = await import('../office/excel.js');
+            const path = args.path || '';
+            const r = await listSheets(path, ctx.projectRoot);
+            return {
+                tool: 'office.excel.list-sheets',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('Excel sheets: ' + r.sheets.length + ' in ' + r.path) : ('Excel list-sheets failed: ' + r.error),
+            };
+        }
+        case 'office.excel.write': {
+            const { writeExcel } = await import('../office/excel.js');
+            const r = await writeExcel(args, ctx.projectRoot);
+            return {
+                tool: 'office.excel.write',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('Excel write: ' + r.row_count + ' rows -> ' + r.path) : ('Excel write failed: ' + r.error),
+            };
+        }
+        case 'office.excel.update-cell': {
+            const { updateCell } = await import('../office/excel.js');
+            const r = await updateCell(args, ctx.projectRoot);
+            return {
+                tool: 'office.excel.update-cell',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok
+                    ? ('Excel update-cell: ' + r.sheet + '!' + r.cell + ' -> ' + r.path)
+                    : ('Excel update-cell failed: ' + r.error),
+            };
+        }
+        case 'office.excel.append-sheet': {
+            const { appendSheet } = await import('../office/excel.js');
+            const r = await appendSheet(args, ctx.projectRoot);
+            return {
+                tool: 'office.excel.append-sheet',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok
+                    ? ('Excel append-sheet: ' + r.row_count + ' rows -> ' + r.path + ' [' + r.sheet + ']')
+                    : ('Excel append-sheet failed: ' + r.error),
+            };
+        }
+        case 'office.word.read': {
+            const { readWord } = await import('../office/word.js');
+            const r = await readWord(args, ctx.projectRoot);
+            return {
+                tool: 'office.word.read',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('Word read: ' + r.text.length + ' chars, ' + (r.outline?.length ?? 0) + ' headings') : ('Word read failed: ' + r.error),
+            };
+        }
+        case 'office.word.write': {
+            const { writeWord } = await import('../office/word.js');
+            const r = await writeWord(args, ctx.projectRoot);
+            return {
+                tool: 'office.word.write',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('Word write: ' + r.section_count + ' sections -> ' + r.path) : ('Word write failed: ' + r.error),
+            };
+        }
+        case 'office.pdf.read': {
+            const { readPdf } = await import('../office/pdf.js');
+            const r = await readPdf(args, ctx.projectRoot);
+            return {
+                tool: 'office.pdf.read',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok ? ('PDF read: ' + r.page_count + ' pages, title "' + (r.title || 'unknown') + '"') : ('PDF read failed: ' + r.error),
+            };
+        }
+        case 'desktop.open': {
+            const { openNative } = await import('../core/desktop_open.js');
+            const target = args.target || '';
+            const r = await openNative(target, ctx.projectRoot);
+            return {
+                tool: 'desktop.open',
+                result: r,
+                is_error: !r.ok,
+                display: r.ok
+                    ? ('Abriendo ' + (r.opened || target) + ' en ' + (r.app_hint || 'la app nativa'))
+                    : ('desktop.open fallo: ' + r.error),
+            };
+        }
+        case 'yujin.task.run': {
+            const { getTaskSupervisor } = await import('../tasks/supervisor.js');
+            const a = args;
+            if (!a.cmd || typeof a.cmd !== 'string') {
+                return { tool: 'yujin.task.run', result: { error: 'cmd is required' }, is_error: true, display: 'missing cmd' };
+            }
+            const sup = getTaskSupervisor(ctx.projectSlug ?? null);
+            const rec = await sup.run({
+                cmd: a.cmd,
+                args: Array.isArray(a.args) ? a.args.map(String) : [],
+                cwd: a.cwd || ctx.projectRoot,
+                label: a.label,
+            });
+            return {
+                tool: 'yujin.task.run',
+                result: { id: rec.id, status: rec.status, pid: rec.pid, label: rec.label, log_path: rec.log_path },
+                is_error: rec.status === 'failed',
+                display: rec.status === 'failed'
+                    ? ('No pude lanzar la tarea (' + rec.label + ')')
+                    : ('Tarea lanzada: ' + rec.label + ' [' + rec.id + '] -- sobrevive al turno; revisa con yujin.task.status'),
+            };
+        }
+        case 'yujin.task.list': {
+            const { getTaskSupervisor } = await import('../tasks/supervisor.js');
+            const sup = getTaskSupervisor(ctx.projectSlug ?? null);
+            const tasks = sup.list();
+            return {
+                tool: 'yujin.task.list',
+                result: { tasks, count: tasks.length },
+                display: tasks.length === 0 ? 'Sin tareas de fondo' : (tasks.length + ' tarea(s) de fondo'),
+            };
+        }
+        case 'yujin.task.status': {
+            const { getTaskSupervisor } = await import('../tasks/supervisor.js');
+            const id = args.id || '';
+            const sup = getTaskSupervisor(ctx.projectSlug ?? null);
+            const rec = sup.get(id);
+            if (!rec)
+                return { tool: 'yujin.task.status', result: { error: 'unknown task id' }, is_error: true, display: 'tarea no encontrada: ' + id };
+            return { tool: 'yujin.task.status', result: rec, display: 'Tarea ' + rec.label + ': ' + rec.status + (typeof rec.exit_code === 'number' ? ' (exit ' + rec.exit_code + ')' : '') };
+        }
+        case 'yujin.task.log': {
+            const { getTaskSupervisor } = await import('../tasks/supervisor.js');
+            const a = args;
+            const id = a.id || '';
+            const sup = getTaskSupervisor(ctx.projectSlug ?? null);
+            if (!sup.get(id))
+                return { tool: 'yujin.task.log', result: { error: 'unknown task id' }, is_error: true, display: 'tarea no encontrada: ' + id };
+            const lines = typeof a.lines === 'number' && a.lines > 0 ? Math.min(a.lines, 500) : 40;
+            const tail = await sup.tailLog(id, lines);
+            return { tool: 'yujin.task.log', result: { id, tail }, display: 'log de ' + id + ' (' + lines + ' lineas)' };
+        }
+        case 'yujin.task.kill': {
+            const { getTaskSupervisor } = await import('../tasks/supervisor.js');
+            const id = args.id || '';
+            const sup = getTaskSupervisor(ctx.projectSlug ?? null);
+            const ok = sup.kill(id);
+            return { tool: 'yujin.task.kill', result: { id, killed: ok }, is_error: !ok, display: ok ? ('Tarea ' + id + ' detenida') : ('No pude detener ' + id + ' (no existe o ya termino)') };
+        }
+        case 'yujin.fs.stat': {
+            const inputPath = args.path || '';
+            if (!inputPath || typeof inputPath !== 'string') {
+                return { tool: 'yujin.fs.stat', result: { error: 'path is required' }, is_error: true, display: 'missing path' };
+            }
+            if (path.isAbsolute(inputPath) || inputPath.includes('..')) {
+                return { tool: 'yujin.fs.stat', result: { error: 'path must be project-relative + within projectRoot' }, is_error: true, display: 'invalid path' };
+            }
+            const abs = path.join(ctx.projectRoot, inputPath);
+            try {
+                const st = await fs.stat(abs);
+                return {
+                    tool: 'yujin.fs.stat',
+                    result: {
+                        path: inputPath,
+                        exists: true,
+                        is_file: st.isFile(),
+                        is_dir: st.isDirectory(),
+                        size: st.size,
+                        mtime: st.mtime.toISOString(),
+                    },
+                    display: 'stat ' + inputPath + ' (' + (st.isFile() ? 'file' : st.isDirectory() ? 'dir' : 'other') + ', ' + st.size + 'B)',
+                };
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === 'ENOENT') {
+                    return {
+                        tool: 'yujin.fs.stat',
+                        result: { path: inputPath, exists: false, is_file: false, is_dir: false, size: 0, mtime: null },
+                        display: 'stat ' + inputPath + ' (missing)',
+                    };
+                }
+                return { tool: 'yujin.fs.stat', result: { error: err.message }, is_error: true, display: 'stat failed' };
+            }
+        }
+        /* F107 a11y verbs -- handler_side=panel. The server returns the
+         *  validated payload + a nac3_panel_dispatch marker so the panel
+         *  (or mobile shell) can apply it. */
+        case 'yujin.a11y.announce': {
+            const { buildAnnouncePayload } = await import('../a11y/helpers.js');
+            const built = buildAnnouncePayload(args);
+            if ('ok' in built && built.ok === false) {
+                return { tool: 'yujin.a11y.announce', result: built, is_error: true, display: 'a11y announce invalid: ' + built.error };
+            }
+            return {
+                tool: 'yujin.a11y.announce',
+                result: { ok: true, nac3_panel_dispatch: true, payload: built },
+                is_error: false,
+                display: 'a11y announce: ' + ('text' in built ? built.text.slice(0, 60) : ''),
+            };
+        }
+        case 'yujin.a11y.focus': {
+            const { buildFocusPayload } = await import('../a11y/helpers.js');
+            const built = buildFocusPayload(args);
+            if ('ok' in built && built.ok === false) {
+                return { tool: 'yujin.a11y.focus', result: built, is_error: true, display: 'a11y focus invalid: ' + built.error };
+            }
+            return {
+                tool: 'yujin.a11y.focus',
+                result: { ok: true, nac3_panel_dispatch: true, payload: built },
+                is_error: false,
+                display: 'a11y focus: ' + ('slug' in built ? built.slug : ''),
+            };
+        }
+        case 'yujin.a11y.label': {
+            const { buildLabelPayload } = await import('../a11y/helpers.js');
+            const built = buildLabelPayload(args);
+            if ('ok' in built && built.ok === false) {
+                return { tool: 'yujin.a11y.label', result: built, is_error: true, display: 'a11y label invalid: ' + built.error };
+            }
+            return {
+                tool: 'yujin.a11y.label',
+                result: { ok: true, nac3_panel_dispatch: true, payload: built },
+                is_error: false,
+                display: 'a11y label: ' + ('slug' in built ? built.slug : ''),
+            };
+        }
+        case NAC3_INVOKE_SPEC.name:
+            return runNac3Invoke(args, ctx, {
+                legacyRun: (n, a, c) => runForgeTool(n, a, c),
+            });
+        /* yujin.pending.* -- alpha.59z.161 pending_registry */
+        case 'yujin.pending.list': {
+            const { runPendingList } = await import('./tools/pending.js');
+            return runPendingList(args, ctx);
+        }
+        case 'yujin.pending.discover': {
+            const { runPendingDiscover } = await import('./tools/pending.js');
+            return runPendingDiscover(args, ctx);
+        }
+        case 'yujin.pending.add': {
+            const { runPendingAdd } = await import('./tools/pending.js');
+            return runPendingAdd(args, ctx);
+        }
+        case 'yujin.pending.close': {
+            const { runPendingClose } = await import('./tools/pending.js');
+            return runPendingClose(args, ctx);
+        }
+        case 'yujin.pending.note': {
+            const { runPendingNote } = await import('./tools/pending.js');
+            return runPendingNote(args, ctx);
+        }
+        case 'yujin.pending.edit': {
+            const { runPendingEdit } = await import('./tools/pending.js');
+            return runPendingEdit(args, ctx);
+        }
+        /* yujin.graph.* -- alpha.59z.180 semantic_graph local SQLite */
+        case 'yujin.graph.list-relevant': {
+            const { runGraphListRelevant } = await import('./tools/graph.js');
+            return runGraphListRelevant(args, ctx);
+        }
+        case 'yujin.graph.upsert-nodes': {
+            const { runGraphUpsertNodes } = await import('./tools/graph.js');
+            return runGraphUpsertNodes(args, ctx);
+        }
+        case 'yujin.graph.summary': {
+            const { runGraphSummary } = await import('./tools/graph.js');
+            return runGraphSummary(args, ctx);
+        }
+        case 'yujin.graph.list-edges': {
+            const { runGraphListEdges } = await import('./tools/graph.js');
+            return runGraphListEdges(args, ctx);
+        }
+        case 'yujin.graph.upsert-edges': {
+            const { runGraphUpsertEdges } = await import('./tools/graph.js');
+            return runGraphUpsertEdges(args, ctx);
+        }
+        case 'yujin.graph.prune-edges': {
+            const { runGraphPruneEdges } = await import('./tools/graph.js');
+            return runGraphPruneEdges(args, ctx);
+        }
+        case 'yujin.graph.forget': {
+            const { runGraphForget } = await import('./tools/graph.js');
+            return runGraphForget(args, ctx);
+        }
+        /* yujin.wiring.* -- alpha.59z.180 wiring registry */
+        case 'yujin.wiring.list': {
+            const { runWiringList } = await import('./tools/wiring.js');
+            return runWiringList(args, ctx);
+        }
+        case 'yujin.wiring.discover': {
+            const { runWiringDiscover } = await import('./tools/wiring.js');
+            return runWiringDiscover(args, ctx);
+        }
+        case 'yujin.wiring.annotate': {
+            const { runWiringAnnotate } = await import('./tools/wiring.js');
+            return runWiringAnnotate(args, ctx);
+        }
+        case 'yujin.wiring.forget': {
+            const { runWiringForget } = await import('./tools/wiring.js');
+            return runWiringForget(args, ctx);
+        }
+        case 'yujin.wiring.explain': {
+            const { runWiringExplain } = await import('./tools/wiring.js');
+            return runWiringExplain(args, ctx);
+        }
         default:
             return {
                 tool: name,