@nac3/forge-cli 1.23.4 → 1.23.5

package/dist/mcp/panel_invoke.d.ts

@@ -0,0 +1,51 @@
+/**
+ * El canal por el que un server MCP le pide a Forge que ejecute un verbo.
+ *
+ * Los dos servers MCP (forge_panel y forge_verbs) son NIETOS de Forge: Forge
+ * lanza `claude -p` y `claude -p` los lanza a ellos. No comparten memoria con
+ * el servidor de chat, asi que cada invocacion viaja por HTTP al loopback
+ * (POST /api/forge/panel-invoke), donde corre el dispatcher real.
+ *
+ * POR QUE EL REENVIO VIVE ACA Y NO EN CADA SERVER (PND-235). Estaba duplicado
+ * -- dos copias de la misma funcion, una en cada server -- y las dos heredaban
+ * el mismo techo de cinco minutos de undici. Un techo duplicado se arregla dos
+ * veces o, peor, una sola: el otro sigue roto y nadie se da cuenta hasta que
+ * el usuario lo pisa. Es la misma leccion que el export web y su dependencia
+ * del workspace (PND-239), el mismo dia.
+ *
+ * El presupuesto de la espera sale de lo que el VERBO declara
+ * (nac3/verb_budget.ts) y el transporte es el compartido con el camino del
+ * telefono (core/loopback_post.ts).
+ *
+ * ASCII puro.
+ */
+import { type LoopbackResponse } from '../core/loopback_post.js';
+/** Puerto + token del servidor de chat, que Forge le pasa al server MCP por
+ *  env al generar el mcp-config. El token gatea el endpoint para que ningun
+ *  otro proceso local pueda inyectar invocaciones. */
+export interface PanelChannel {
+    port?: string | undefined;
+    token?: string | undefined;
+}
+/** El transporte, inyectable para test. Misma forma que postLoopbackJson. */
+export type LoopbackPost = (args: {
+    port: number;
+    path: string;
+    payload: unknown;
+    budgetMs: number;
+}) => Promise<LoopbackResponse>;
+export declare const PANEL_INVOKE_PATH = "/api/forge/panel-invoke";
+export declare function panelChannelFromEnv(env?: NodeJS.ProcessEnv): PanelChannel;
+/**
+ * Reenvia una invocacion al chat server (dispatcher real) y devuelve el texto
+ * del resultado.
+ *
+ * Nunca lanza: el llamador es un handler JSON-RPC y lo unico que puede hacer
+ * con una excepcion es convertirla en texto, asi que se convierte aca una sola
+ * vez y bien.
+ */
+export declare function forwardInvoke(verbId: string, args: Record<string, unknown>, env?: PanelChannel, post?: LoopbackPost): Promise<{
+    ok: boolean;
+    text: string;
+}>;
+//# sourceMappingURL=panel_invoke.d.ts.map

package/dist/mcp/panel_invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel_invoke.d.ts","sourceRoot":"","sources":["../../src/mcp/panel_invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAiC,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAKhG;;sDAEsD;AACtD,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE;IAChC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;CAChE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEhC,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAEtF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,GAAE,YAAoC,EACzC,IAAI,GAAE,YAA+B,GACpC,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA6DxC"}

package/dist/mcp/panel_invoke.js

@@ -0,0 +1,102 @@
+/**
+ * El canal por el que un server MCP le pide a Forge que ejecute un verbo.
+ *
+ * Los dos servers MCP (forge_panel y forge_verbs) son NIETOS de Forge: Forge
+ * lanza `claude -p` y `claude -p` los lanza a ellos. No comparten memoria con
+ * el servidor de chat, asi que cada invocacion viaja por HTTP al loopback
+ * (POST /api/forge/panel-invoke), donde corre el dispatcher real.
+ *
+ * POR QUE EL REENVIO VIVE ACA Y NO EN CADA SERVER (PND-235). Estaba duplicado
+ * -- dos copias de la misma funcion, una en cada server -- y las dos heredaban
+ * el mismo techo de cinco minutos de undici. Un techo duplicado se arregla dos
+ * veces o, peor, una sola: el otro sigue roto y nadie se da cuenta hasta que
+ * el usuario lo pisa. Es la misma leccion que el export web y su dependencia
+ * del workspace (PND-239), el mismo dia.
+ *
+ * El presupuesto de la espera sale de lo que el VERBO declara
+ * (nac3/verb_budget.ts) y el transporte es el compartido con el camino del
+ * telefono (core/loopback_post.ts).
+ *
+ * ASCII puro.
+ */
+import { postLoopbackJson, LoopbackCut } from '../core/loopback_post.js';
+import { renderForgeError, E_VERB_CALL_UNANSWERED } from '../core/error_catalog.js';
+import { formatForgeErrorText } from '../core/error_formatter.js';
+import { invokeBudgetMs } from '../nac3/verb_budget.js';
+export const PANEL_INVOKE_PATH = '/api/forge/panel-invoke';
+export function panelChannelFromEnv(env = process.env) {
+    return { port: env['FORGE_PANEL_PORT'], token: env['FORGE_PANEL_TOKEN'] };
+}
+/**
+ * Reenvia una invocacion al chat server (dispatcher real) y devuelve el texto
+ * del resultado.
+ *
+ * Nunca lanza: el llamador es un handler JSON-RPC y lo unico que puede hacer
+ * con una excepcion es convertirla en texto, asi que se convierte aca una sola
+ * vez y bien.
+ */
+export async function forwardInvoke(verbId, args, env = panelChannelFromEnv(), post = postLoopbackJson) {
+    if (!env.port || !env.token) {
+        return { ok: false, text: 'El canal de Forge no esta configurado (sin puerto/token).' };
+    }
+    /* Un puerto que no es un numero es una MALA CONFIGURACION, y hay que decirlo
+     * asi. Sin esta guarda, `http.request({port: NaN})` tira y el error cae en
+     * el catch de abajo, que lo reporta como "la invocacion no contesto" -- o
+     * sea: el unico caso en que se sabe con certeza que el verbo no corrio se
+     * reportaria como el caso en que pudo haber corrido. */
+    const port = Number(env.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        return {
+            ok: false,
+            text: 'El canal de Forge esta mal configurado: FORGE_PANEL_PORT no es un puerto ('
+                + JSON.stringify(env.port) + '). El verbo NO se ejecuto.',
+        };
+    }
+    const budgetMs = invokeBudgetMs(verbId, args);
+    let r;
+    try {
+        r = await post({
+            port,
+            path: PANEL_INVOKE_PATH,
+            payload: { token: env.token, verb_id: verbId, args },
+            budgetMs,
+        });
+    }
+    catch (err) {
+        if (err instanceof LoopbackCut && err.kind === 'undelivered') {
+            /* Prueba positiva de que no corrio nada: el saludo TCP no existio. Es el
+             * unico caso en que se puede afirmar que el verbo no se ejecuto. */
+            return {
+                ok: false,
+                text: 'El canal de Forge no respondio: no hay nadie escuchando en el puerto '
+                    + env.port + '. El verbo NO se ejecuto.',
+            };
+        }
+        /* En cualquier otro corte el verbo pudo haber corrido, asi que no se dice
+         * que fracaso: se dice que no hubo respuesta y donde mirar el rastro. */
+        const minutes = Math.max(1, Math.round(budgetMs / 60_000));
+        return {
+            ok: false,
+            text: formatForgeErrorText(renderForgeError(E_VERB_CALL_UNANSWERED, { verb: verbId, minutes })),
+        };
+    }
+    if (r.status < 200 || r.status >= 300) {
+        return { ok: false, text: 'Forge rechazo la invocacion (HTTP ' + r.status + ').' };
+    }
+    let j;
+    try {
+        j = JSON.parse(r.body);
+    }
+    catch {
+        /* 200 con un cuerpo que no es JSON: no es "no contesto", es que contesto
+         * otra cosa. Decirlo con lo que llego adentro, que es el unico dato que
+         * permite diagnosticarlo. */
+        return {
+            ok: false,
+            text: 'Forge contesto algo que no es JSON (HTTP ' + r.status + '): '
+                + r.body.slice(0, 300),
+        };
+    }
+    return { ok: j.ok !== false, text: j.text || 'Listo.' };
+}
+//# sourceMappingURL=panel_invoke.js.map

package/dist/mcp/panel_invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel_invoke.js","sourceRoot":"","sources":["../../src/mcp/panel_invoke.ts"],"names":[],"mappings":"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"}

package/dist/nac3/internal_manifest.d.ts

@@ -9,6 +9,8 @@ export interface Nac3JsonSchema {
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        minimum?: number;
+        maximum?: number;
         pattern?: string;
     }>;
     required: readonly string[];

package/dist/nac3/internal_manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal_manifest.d.ts","sourceRoot":"","sources":["../../src/nac3/internal_manifest.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,KAAK,GACL,YAAY,GACZ,SAAS,GACT,SAAS,GACT,cAAc,GACd,KAAK,CAAC;AAEV,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;QAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB;;;4BAGwB;IACxB,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC;;;;;;qCAMiC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AA+6GD,wBAAgB,QAAQ,IAAI,YAAY,CAOvC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGzD;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAO9D;AAED;;;uDAGuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAgCzF;AAED;;sEAEsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAO/D"}
+{"version":3,"file":"internal_manifest.d.ts","sourceRoot":"","sources":["../../src/nac3/internal_manifest.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,KAAK,GACL,YAAY,GACZ,SAAS,GACT,SAAS,GACT,cAAc,GACd,KAAK,CAAC;AAEV,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;QAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QAKnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB;;;4BAGwB;IACxB,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC;;;;;;qCAMiC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAm7GD,wBAAgB,QAAQ,IAAI,YAAY,CAOvC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGzD;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAO9D;AAED;;;uDAGuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CA2CzF;AAED;;sEAEsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAO/D"}

package/dist/nac3/internal_manifest.js

@@ -1260,7 +1260,7 @@ const VERBS = [
             properties: {
                 command: { type: 'string', description: 'The shell command to run.', minLength: 1, maxLength: 16384 },
                 cwd: { type: 'string', description: 'Working directory. Absolute or project-relative. Outside-root requires extra approval (limits.shell.cwd_boundary_strict).' },
-                timeout_ms: { type: 'number', description: 'Override timeout. Capped by limits.shell.timeout_ms_max.' },
+                timeout_ms: { type: 'number', maximum: 600000, description: 'Override timeout. Capped by limits.shell.timeout_ms_max (whose own hard ceiling is 600000). The transport budget is derived from this maximum: see nac3/verb_budget.ts.' },
                 env: { type: 'object', description: 'Extra env vars to inject on top of the whitelist.' },
                 allow_long_running: { type: 'boolean', description: 'Escape hatch: run a non-terminating command in-turn anyway (rare). Default false -> use yujin.task.run instead.' },
                 allow_heavy: { type: 'boolean', description: 'Escape hatch for the HEAVY guard (test suites, builds, installs, sleeps): run it in-turn anyway. Default false -> yujin.task.run + yujin.task.log({grep}) instead, which does not block the turn.' },
@@ -2871,7 +2871,10 @@ const VERBS = [
             + 'regression, e2e, quality, mutation, load, other. Receipts are what '
             + 'the method accepts as evidence: a plan pending closes with shipped '
             + 'only with its red_proof + green + regression receipts. Blocks the '
-            + 'turn (default 10 min). Never describe a run you did not record here.',
+            + 'turn while the run fits the blocking window (10 min); over that, or '
+            + 'with background:true, it is launched DETACHED and you get a handle -- '
+            + 'the receipt lands either way, read it with yujin.evidence.list. '
+            + 'Never describe a run you did not record here.',
         schema: {
             type: 'object',
             properties: {
@@ -2881,7 +2884,8 @@ const VERBS = [
                 step: { type: 'number', description: 'Urazuke step number, when the run is for a ladder step.' },
                 base_ref: { type: 'string', maxLength: 100, description: 'red_proof: the git ref of the code BEFORE the change. Default HEAD (the uncommitted change is what is being proved).' },
                 test_files: { type: 'array', description: 'red_proof: the new test files, project-relative, carried into the base worktree.' },
-                timeout_ms: { type: 'number', description: 'Max 1800000.' },
+                timeout_ms: { type: 'number', maximum: 1800000, description: 'Max 1800000 (30 min). Over the blocking window (10 min) the run goes to the BACKGROUND and the verb returns a handle instead of the receipt.' },
+                background: { type: 'boolean', description: 'Launch the run DETACHED and return a handle instead of blocking the turn. Automatic when timeout_ms is over the blocking window. The receipt is written by the run itself: read it with yujin.evidence.list when it finishes.' },
                 note: { type: 'string', maxLength: 300 },
             },
             required: ['kind', 'command'],
@@ -3385,6 +3389,17 @@ export function validateArgs(verb, args) {
             return 'arg ' + key + ': expected array, got ' + actual;
         if (expected !== 'array' && actual !== expected)
             return 'arg ' + key + ': expected ' + expected + ', got ' + actual;
+        if (expected === 'number' && typeof val === 'number') {
+            /* Un tope declarado que nadie hace valer es prosa. Y se RECHAZA en vez
+             * de recortar en silencio: el que pide 30 minutos donde entran 10 tiene
+             * que enterarse, no recibir otra cosa de la que pidio. */
+            if (propSchema.minimum != null && val < propSchema.minimum) {
+                return 'arg ' + key + ': too small (min ' + propSchema.minimum + ')';
+            }
+            if (propSchema.maximum != null && val > propSchema.maximum) {
+                return 'arg ' + key + ': too big (max ' + propSchema.maximum + ')';
+            }
+        }
         if (expected === 'string' && typeof val === 'string') {
             if (propSchema.minLength != null && val.length < propSchema.minLength) {
                 return 'arg ' + key + ': too short (min ' + propSchema.minLength + ')';