oficina-opencode 2.1.0 → 3.0.0

package/dist/v2.js

@@ -0,0 +1,419 @@
+/**
+ * OFICINA — entry point del plugin para **OpenCode v2**.
+ *
+ * ## Por qué existe este archivo
+ *
+ * OpenCode v1 y v2 tienen APIs de plugins **incomunes**: no es que
+ * cambiara una firma, es que cambió la forma. v1 exportaba una funcion que
+ * devuelve hooks; v2 exige `export default { id, setup(ctx) }`. Un plugin
+ * v1 bajo v2 falla con:
+ *
+ *     PluginModule.LoadError: Plugin must export a default definition with
+ *     an id and an effect or setup function.
+ *
+ * Y al reves: un plugin v2 bajo v1 no carga.
+ *
+ * Este archivo es la implementacion **v2**. La de v1 vive en `v1.ts` y el
+ * motor (`core/`, `tools/`) no depende de ninguna de las dos APIs: define
+ * las tools en una forma neutra y cada entry la traduce.
+ *
+ * ## Que registra
+ *
+ * - **Tools** (`oficina_*`): la superficie de trabajo, via `ctx.tool.transform`.
+ * - **Guard de scope** (`ctx.tool.hook` + `ctx.permission.hook`): dos capas.
+ *   La primera intercepta la tool; la segunda es el punto de enforcement del
+ *   framework y puede `deny` de verdad.
+ * - **Tripwire** (`ctx.tool.hook("execute.after")`): detecta escrituras que se
+ *   colaron por un comando de shell.
+ * - **Estado de la oficina** (`ctx.session.hook("context")`): el agente no
+ *   repregunta lo que ya sabe.
+ * - **Auto-continuacion** (`session.idle`): la corrida sigue sola cuando el
+ *   modelo para.
+ * - **Costo** (`session.usage.recorded`): el numero real que reporta el motor.
+ */
+import { Plugin } from "@opencode/plugin";
+import { z } from "zod";
+import { Office } from "./core/office.js";
+import { buildTools } from "./tools/index.js";
+import { analyzeShellCommand, checkScope } from "./core/sandbox.js";
+import { extractCommand, extractPaths, resolveScopeCard } from "./hooks/scopeGuard.js";
+import { Tripwire } from "./core/tripwire.js";
+import { logger } from "./core/log.js";
+const log = logger("oficina:v2");
+/** Tools que escriben un archivo. */
+const FILE_WRITE_TOOLS = new Set([
+    "edit",
+    "write",
+    "patch",
+    "multiedit",
+    "apply_patch",
+    "notebook_edit",
+    "str_replace",
+    "str_replace_editor",
+    "edit_file",
+    "edit_notebook_file",
+    "create_file",
+    "write_file",
+    "create_or_update_file",
+]);
+/** Tools que ejecutan shell. */
+const SHELL_TOOLS = new Set([
+    "bash",
+    "shell",
+    "run",
+    "run_command",
+    "execute_command",
+    "terminal",
+    "powershell",
+    "cmd",
+]);
+/** Acciones de permiso que implican escribir un archivo. */
+const WRITE_ACTIONS = new Set(["edit", "write", "patch", "multiedit", "apply_patch"]);
+/**
+ * Convierte un schema zod a JSON Schema.
+ *
+ * v2 exige JSON Schema plano en `tool.input`. zod v4 lo hace nativo.
+ */
+function toJsonSchema(schema) {
+    if (!schema)
+        return { type: "object", additionalProperties: true };
+    try {
+        const converted = z.toJSONSchema(schema, {
+            io: "input",
+            unrepresentable: "any",
+        });
+        // Si el schema no es de un objeto, se acepta igual pero se documenta.
+        if (converted["type"] !== "object") {
+            return { type: "object", additionalProperties: true, description: converted["description"] };
+        }
+        return { ...converted, additionalProperties: false };
+    }
+    catch {
+        return { type: "object", additionalProperties: true };
+    }
+}
+export default Plugin.define({
+    id: "oficina",
+    async setup(ctx) {
+        const options = (ctx.options ?? {});
+        const enforce = options.enforceScope !== false;
+        const directory = ctx.location.directory;
+        const office = new Office({ cwd: directory });
+        await office.init();
+        const tripwire = new Tripwire(office.paths.projectRoot, {
+            maxFiles: options.tripwireMaxFiles ?? 4000,
+        });
+        /** El scope que aplica a una sesion, si tiene. */
+        const scopeOf = async (sessionID) => {
+            try {
+                const state = await office.loadState();
+                const card = await resolveScopeCard(state, sessionID, { enforce });
+                if (!card)
+                    return undefined;
+                const policy = {
+                    mayTouch: card.scope.mayTouch,
+                    forbidden: card.scope.forbidden,
+                };
+                return { card, policy };
+            }
+            catch (err) {
+                log.debug("no se pudo resolver el scope de la sesion", { sessionID, error: String(err) });
+                return undefined;
+            }
+        };
+        /* ────────────────────────────────────────────────────────────────────────
+         * 1. TOOLS
+         * ──────────────────────────────────────────────────────────────────────── */
+        const defs = buildTools(office);
+        await ctx.tool.transform((editor) => {
+            for (const [name, def] of Object.entries(defs)) {
+                editor.add({
+                    name,
+                    description: def.description,
+                    input: toJsonSchema(def.args),
+                    execute: async (input, toolCtx) => {
+                        const result = await def.execute((input ?? {}), {
+                            directory,
+                            sessionID: toolCtx.sessionID,
+                            agent: toolCtx.agent,
+                            messageID: toolCtx.messageID,
+                        });
+                        return {
+                            content: result.output,
+                            metadata: result.metadata,
+                        };
+                    },
+                });
+            }
+        });
+        /* ────────────────────────────────────────────────────────────────────────
+         * 2. GUARD DE SCOPE
+         *
+         * Dos capas, porque cada una cubre lo que la otra no:
+         *
+         * - `tool.hook("execute.before")`: ve el path exacto de cada tool que
+         *   escribe, incluso los que no pasan por el sistema de permisos.
+         * - `permission.hook("evaluate")`: es el punto de enforcement del
+         *   framework y puede `deny` de verdad, con motivo.
+         * ──────────────────────────────────────────────────────────────────────── */
+        /** Verifica un path contra el scope. Devuelve el motivo si viola. */
+        const violation = async (sessionID, rawPath) => {
+            const scope = await scopeOf(sessionID);
+            if (!scope)
+                return undefined;
+            const verdict = await checkScope(office.paths.projectRoot, rawPath, scope.policy);
+            if (verdict.allowed)
+                return undefined;
+            return { reason: verdict.reason, kind: verdict.kind };
+        };
+        await ctx.tool.hook("execute.before", async (event) => {
+            const tool = String(event.tool);
+            const input = (event.input ?? {});
+            // Lecturas: nunca se tocan.
+            if (!FILE_WRITE_TOOLS.has(tool) && !SHELL_TOOLS.has(tool))
+                return;
+            const scope = await scopeOf(event.sessionID);
+            if (!scope)
+                return;
+            if (FILE_WRITE_TOOLS.has(tool)) {
+                for (const rawPath of extractPaths(tool, input)) {
+                    const bad = await violation(event.sessionID, rawPath);
+                    if (!bad)
+                        continue;
+                    const mensaje = `[OFICINA] Scope violado: ${bad.reason} (card ${scope.card.id})`;
+                    log.warn("scope violado (archivo)", { card: scope.card.id, path: rawPath, kind: bad.kind });
+                    if (enforce)
+                        throw new Error(mensaje);
+                }
+                return;
+            }
+            if (SHELL_TOOLS.has(tool)) {
+                const command = extractCommand(input);
+                if (!command)
+                    return;
+                for (const candidate of analyzeShellCommand(command)) {
+                    if (candidate.uncertain) {
+                        // Hay una escritura que no sabemos interpretar. No se bloquea
+                        // (seria inservible), pero el tripwire va a mirar.
+                        log.warn("shell con escritura no interpretable", {
+                            card: scope.card.id,
+                            op: candidate.op,
+                        });
+                        continue;
+                    }
+                    const bad = await violation(event.sessionID, candidate.target);
+                    if (!bad)
+                        continue;
+                    const mensaje = `[OFICINA] Scope violado: ${bad.reason} (card ${scope.card.id})`;
+                    log.warn("scope violado (shell)", {
+                        card: scope.card.id,
+                        target: candidate.target,
+                        kind: bad.kind,
+                    });
+                    if (enforce && options.enforceScope !== false)
+                        throw new Error(mensaje);
+                }
+            }
+        });
+        await ctx.permission.hook("evaluate", async (event) => {
+            if (!WRITE_ACTIONS.has(String(event.action)))
+                return;
+            const scope = await scopeOf(event.sessionID);
+            if (!scope)
+                return;
+            for (const resource of event.resources) {
+                const bad = await violation(event.sessionID, resource);
+                if (!bad)
+                    continue;
+                event.effect = "deny";
+                event.message = `[OFICINA] ${bad.reason} (card ${scope.card.id})`;
+                log.warn("permiso denegado por scope", {
+                    card: scope.card.id,
+                    resource,
+                    kind: bad.kind,
+                });
+                return;
+            }
+        });
+        /* ────────────────────────────────────────────────────────────────────────
+         * 3. TRIPWIRE
+         *
+         * Fotografia el arbol antes de una tool y compara despues. Lo que cambio
+         * fuera del scope se reporta por el bus: detecta, no revierte.
+         * ──────────────────────────────────────────────────────────────────────── */
+        await ctx.tool.hook("execute.before", async (event) => {
+            const scope = await scopeOf(event.sessionID);
+            if (!scope)
+                return;
+            await tripwire.arm(String(event.id), scope.policy.mayTouch);
+        });
+        await ctx.tool.hook("execute.after", async (event) => {
+            const scope = await scopeOf(event.sessionID);
+            if (!scope)
+                return;
+            const cambios = await tripwire.check(String(event.id), scope.policy.mayTouch);
+            if (cambios.length === 0)
+                return;
+            const detalle = cambios.map((c) => `  - ${c.kind}: ${c.path}`).join("\n");
+            log.warn("escrituras fuera del scope detectadas", {
+                card: scope.card.id,
+                tool: event.tool,
+                cambios: cambios.length,
+            });
+            await office.bus
+                .send("peer", {
+                from: "oficina",
+                to: ["*"],
+                kind: "NOTICE",
+                subject: scope.card.id,
+                body: {
+                    notice: "scope",
+                    message: `Se detectaron ${cambios.length} cambio(s) fuera del scope de la card ${scope.card.id} ` +
+                        `durante \`${event.tool}\`:\n${detalle}\n\n` +
+                        `Si fue deliberado, avisalo por el bus. Si no, revisé lo que tocaste.`,
+                },
+            })
+                .catch(() => undefined);
+        });
+        /* ────────────────────────────────────────────────────────────────────────
+         * 4. EL ESTADO DE LA OFICINA VIAJA CON CADA LLAMADA
+         * ──────────────────────────────────────────────────────────────────────── */
+        await ctx.session.hook("context", async (event) => {
+            try {
+                const { buildSystemPrompt } = await import("./core/systemPrompt.js");
+                const state = await office.loadState();
+                event.system.push({ type: "text", text: await buildSystemPrompt(office, state) });
+            }
+            catch (err) {
+                log.debug("no se pudo inyectar el estado", { error: String(err) });
+            }
+        });
+        /* ────────────────────────────────────────────────────────────────────────
+         * 5. COMPACTACION
+         *
+         * El estado sobrevive a la compactacion: se lee del disco, no de la
+         * memoria de la conversacion.
+         * ──────────────────────────────────────────────────────────────────────── */
+        await ctx.session.hook("compaction", async (event) => {
+            try {
+                const { buildSystemPrompt } = await import("./core/systemPrompt.js");
+                const state = await office.loadState();
+                event.system.push({ type: "text", text: await buildSystemPrompt(office, state) });
+            }
+            catch (err) {
+                log.debug("no se pudo inyectar el estado al compactar", { error: String(err) });
+            }
+        });
+        /* ────────────────────────────────────────────────────────────────────────
+         * 6. EVENTOS: auto-continuacion y costo
+         * ──────────────────────────────────────────────────────────────────────── */
+        const maxAutoResumes = options.maxAutoResumes ?? 25;
+        const resumes = new Map();
+        const lastResume = new Map();
+        const controller = new AbortController();
+        void (async () => {
+            try {
+                for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+                    /* ── Auto-continuacion ── */
+                    if (event.type === "session.idle") {
+                        const sessionID = event.data?.sessionID;
+                        if (!sessionID)
+                            continue;
+                        try {
+                            const state = await office.loadState();
+                            if (state.status !== "running")
+                                continue;
+                            if (state.halt)
+                                continue;
+                            const cards = Object.values(state.cards);
+                            const pending = cards.filter((c) => c.state !== "done");
+                            if (pending.length === 0)
+                                continue;
+                            const count = resumes.get(sessionID) ?? 0;
+                            if (count >= maxAutoResumes) {
+                                log.warn("tope de auto-reanudaciones alcanzado", { sessionID, count });
+                                continue;
+                            }
+                            const last = lastResume.get(sessionID);
+                            if (last !== undefined && Date.now() - last < 1_500)
+                                continue;
+                            lastResume.set(sessionID, Date.now());
+                            resumes.set(sessionID, count + 1);
+                            const { renderMesaBrief, snapshotMesa } = await import("./core/mesa.js");
+                            const mesa = await snapshotMesa(office);
+                            const mesaBrief = renderMesaBrief(mesa);
+                            const texto = [
+                                "[OFICINA - auto-continuacion]",
+                                "",
+                                `La corrida sigue abierta. Quedan ${pending.length} card(s) sin terminar.`,
+                                "",
+                                ...(mesaBrief ? ["---", "", "**La mesa:**", "", mesaBrief] : []),
+                                "",
+                                "Usá `oficina_board` para el panorama y `oficina_mesa` para ver la mesa.",
+                                "No declares la corrida terminada mientras queden cards sin DONE.",
+                            ].join("\n");
+                            await ctx.session.synthetic({
+                                sessionID,
+                                text: texto,
+                                description: "OFICINA: auto-continuacion",
+                            });
+                        }
+                        catch (err) {
+                            log.error("fallo en la auto-continuacion", { error: String(err) });
+                        }
+                        continue;
+                    }
+                    /* ── Costo ── */
+                    //
+                    // El evento trae el numero REAL que reporto el motor. No se estima.
+                    //
+                    // El tipo del stream publicado no incluye los eventos de usage (el
+                    // union tipado es mas angosto que el manifiesto del schema), asi
+                    // que se lee de forma laxa y a mano: si la forma no coincide, se
+                    // ignora en vez de romper.
+                    const raw = event;
+                    if (raw.type === "session.usage.recorded" || raw.type === "session.usage.updated") {
+                        const data = raw.data;
+                        if (!data?.sessionID)
+                            continue;
+                        try {
+                            const state = await office.loadState();
+                            const binding = state.sessions[data.sessionID];
+                            await office.recordUsage({
+                                agentId: binding?.agentId ?? data.sessionID,
+                                role: binding?.agentId ?? "agente",
+                                cardId: binding?.cardId ?? null,
+                                phase: binding?.cardId ? "implementation" : "exploration",
+                                model: "desconocido",
+                                provider: "desconocido",
+                                cost: data.cost ?? 0,
+                                tokens: {
+                                    input: data.tokens?.input ?? 0,
+                                    output: data.tokens?.output ?? 0,
+                                    reasoning: data.tokens?.reasoning ?? 0,
+                                    cache: { read: data.tokens?.cache?.read ?? 0, write: data.tokens?.cache?.write ?? 0 },
+                                },
+                                latencyMs: 0,
+                            });
+                        }
+                        catch (err) {
+                            log.debug("no se pudo registrar el uso", { error: String(err) });
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (!controller.signal.aborted) {
+                    log.error("el stream de eventos se corto", { error: String(err) });
+                }
+            }
+        })();
+        log.info("plugin inicializado", {
+            directory,
+            tools: Object.keys(defs).length,
+            officeDir: office.paths.officeDir,
+        });
+        return () => controller.abort();
+    },
+});
+//# sourceMappingURL=v2.js.map

package/dist/v2.js.map

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

package/docs/COMPATIBILITY.md

@@ -9,43 +9,69 @@ nadie verificó.
 
 ---
 
-## Versiones
+## ⚠️ El cambio de API de plugins es el punto que hay que entender
 
-| Componente | Versión | Cómo se verificó |
+**OpenCode v1 y v2 tienen APIs de plugins incompatibles.** No es que cambiara
+una firma: cambió la forma.
+
+| | OpenCode v1 | OpenCode v2 |
 |---|---|---|
-| `@opencode-ai/plugin` | `1.15.11` | Compilación con `strict` + `noUncheckedIndexedAccess` contra los tipos reales del paquete. Un hook que no exista en el tipo **no compila**. |
-| Node.js | `>=20` | CI corre la matriz `[20, 22]` en `ubuntu-latest` y `windows-latest`. |
-| TypeScript | `>=5.6` | `tsc --noEmit` en modo `strict`. |
+| Export default | una **función** que devuelve hooks | un **objeto** `{ id, setup(ctx) }` |
+| Registrar tools | `hooks.tool = { nombre: tool({...}) }` | `ctx.tool.transform(editor => editor.add({...}))` |
+| Forma de los args | schema **zod** | **JSON Schema** plano |
+| Interceptar tools | hook `tool.execute.before` | `ctx.tool.hook("execute.before")` |
+| Denegar una acción | hook `permission.ask` | `ctx.permission.hook("evaluate")` → `effect = "deny"` |
+| Inyectar al system prompt | `experimental.chat.system.transform` | `ctx.session.hook("context")` |
+| Eventos | hook `event` | `ctx.event.subscribe({ signal })` |
+| Auto-continuación | `client.session.promptAsync` | `ctx.session.synthetic({...})` |
 
-La API de plugin es la que manda: el plugin importa sus tipos, así que
-**la compatibilidad se verifica en tiempo de compilación**, no por
-inspección visual.
+Un plugin v1 bajo v2 falla con:
 
-## Hooks que usa el plugin
+```
+PluginModule.LoadError: Plugin must export a default definition with an id
+and an effect or setup function.
+```
 
-| Hook | Para qué | Si el host no lo soporta |
-|---|---|---|
-| `event` (`session.idle`) | Auto-reanudación de la corrida | La corrida sigue, pero no se reanuda sola. |
-| `event` (`message.updated`) | Contabilidad de costo | No hay registro de costo. La oficina sigue funcionando. |
-| `tool.execute.before` | Guard de scope | **Sin protección**: el scope pasa a ser una instrucción, no una restricción. |
-| `tool.execute.after` | Tripwire | No hay detección de escrituras coladas. |
-| `permission.ask` | Segunda capa de enforcement | Queda solo la primera capa. |
-| `experimental.chat.system.transform` | El estado viaja con cada llamada | El agente tiene que preguntar el estado. |
-| `experimental.session.compacting` | El estado sobrevive a la compactación | La compactación pierde el contexto de la oficina. |
-| `experimental.compaction.autocontinue` | Freno de emergencia | El freno frena el trabajo, pero la auto-continuación post-compactación sigue. |
+Y al revés, un plugin v2 bajo v1 no carga.
 
-## Mínimo verificable
+### Cómo lo resuelve AI-OFFICE
 
-La parte del plugin que **no degrada bien** es el guard de scope. Por eso
-el proyecto declara un mínimo:
+El **motor** (`core/`, `tools/`) no depende de ninguna de las dos APIs:
 
-- **`@opencode-ai/plugin` >= 1.15.11**: a partir de esta versión existen
-  `tool.execute.before`, `tool.execute.after` y `permission.ask` con las
-  firmas que usa el plugin.
+- Las tools se definen en una **forma neutra** (`{ description, args, execute }`).
+- `src/v2.ts` las traduce a v2 (zod → JSON Schema con `z.toJSONSchema`).
+- `src/v1.ts` las traduce a v1 (el helper `tool()` del plugin v1).
 
-Si se instala con una versión anterior, el typecheck falla en la
-instalación del consumidor y eso es intencional: es mejor un error de
-compilación que una instalación que parece protegida y no lo está.
+El texto del system prompt también es compartido: vive en
+`core/systemPrompt.ts` y cada entry lo inyecta donde su API lo permite. Si
+viviera dentro de cada hook, las dos copias se desincronizarían.
+
+| Entry | Versión de OpenCode |
+|---|---|
+| `oficina-opencode` (`.`) | **v2** — la principal |
+| `oficina-opencode/v1` | v1 (legacy) |
+
+## Versiones
+
+| Componente | Versión | Cómo se verificó |
+|---|---|---|
+| `@opencode/plugin` | `^2.1.2` | Compilación con `strict` + `noUncheckedIndexedAccess` contra los tipos reales. Un hook que no exista en el tipo **no compila**. |
+| `@opencode-ai/plugin` | `^1.15.11` *(peer opcional)* | Solo lo necesita el entry `./v1`. |
+| OpenCode CLI | `2.1.1` | Probado con el servicio real: el plugin carga, registra las 16 tools y responde. |
+| Node.js | `>=20` | CI corre la matriz `[20, 22]` en `ubuntu-latest` y `windows-latest`. |
+| TypeScript | `>=5.8` | `tsc --noEmit` en modo `strict`. |
+
+## Hooks que usa el plugin v2
+
+| Hook | Para qué | Si el host no lo soporta |
+|---|---|---|
+| `ctx.tool.transform` | Registra las 16 tools | **Sin tools, la oficina no existe.** |
+| `ctx.tool.hook("execute.before")` | Guard de scope + armado del tripwire | El scope pasa a ser una instrucción. |
+| `ctx.tool.hook("execute.after")` | Tripwire: detecta escrituras coladas | No hay detección. |
+| `ctx.permission.hook("evaluate")` | Segunda capa: `deny` real | Queda solo el guard propio. |
+| `ctx.session.hook("context")` | El estado viaja con cada llamada | El agente repregunta lo que ya sabe. |
+| `ctx.session.hook("compaction")` | El estado sobrevive a la compactación | La compactación pierde el contexto. |
+| `ctx.event.subscribe` | Auto-continuación (`session.idle`) y costo (`session.usage.recorded`) | Sin auto-continuación ni contabilidad de costo. |
 
 ## Pruebas de integración por versión
 
@@ -56,26 +82,21 @@ os:   [ubuntu-latest, windows-latest]
 node: [20, 22]
 ```
 
-En cada combinación se corre:
-
-1. `npm run typecheck` — la API de plugin compila.
-2. `npm run test` — la suite completa (los tests del plugin usan un host
-   simulado con la misma forma que el real).
-3. `npm run build` — el `dist/` se genera.
-4. `npm pack --dry-run` — el paquete se puede armar.
+En cada combinación: `npm run typecheck`, `npm run test`, `npm run build`,
+`npm pack --dry-run`. Y en un job aparte, el smoke del CLI sobre el `dist/`
+real.
 
-Y en un job aparte, el smoke del CLI sobre el `dist/` real.
+Los tests del plugin v2 (`tests/pluginV2.test.ts`) mockean el contexto de v2
+y comprueban que las tools se registran con JSON Schema, que los hooks se
+instalan y que las tools responden.
 
 ## OpenCode
 
 | Versión de OpenCode | Soporte |
 |---|---|
-| La que trae el host actual | Sí. Es la que se prueba en desarrollo. |
-| Versiones anteriores | No declaradas. El plugin usa `session.prompt` con partes `subtask`, `session.promptAsync`, `session.get` y `client.app.log`. |
-
-El plugin **no fija** una versión de OpenCode: se instala como plugin y usa
-el API que el host expone. Lo que sí fija es la versión del **API de
-plugin**, que es lo que usa directamente.
+| **v2.x** (>= 2.1) | **Sí.** Es la que se prueba en desarrollo y en el servicio real. |
+| v1 (>= 1.18.29) | Legacy, via `oficina-opencode/v1`. Los hooks v1 funcionan; los de v2 no. |
+| v1 anteriores a 1.18.29 | No. La forma de objeto no estaba soportada. |
 
 ## Requisitos del usuario, no del plugin
 
@@ -87,6 +108,26 @@ plugin**, que es lo que usa directamente.
 
 ---
 
+## Un detalle que obliga a resolver el paquete en runtime
+
+El loader de plugins de OpenCode v2 **no resuelve bare specifiers** desde
+`~/.config/opencode/plugins/`. Un `export { default } from "oficina-opencode"`
+falla con:
+
+```
+Cannot find package 'oficina-opencode' imported from
+C:\Users\...\ .config\opencode\plugins\oficina.js
+```
+
+Node sí lo resolvería (subiendo por los `node_modules`). Bun, que es el
+runtime de OpenCode, no.
+
+Por eso `oficina install` escribe un entry (`dist/pluginEntry.js`) que
+**busca el paquete en runtime** — en el `node_modules` de la config, en la
+cache de npm de OpenCode, o subiendo desde el propio archivo — y lo importa
+por ruta absoluta. Se resuelve en runtime y no al instalar, así que
+reinstalar el paquete en otro lugar no rompe el entry.
+
 ## Cómo se mantiene esta tabla
 
 Las cifras de versiones salen del `package.json` real y se verifican en el

package/docs/QUE-ES.md

@@ -3,10 +3,10 @@
 <!-- BEGIN GENERATED: facts -->
 | | |
 |---|---|
-| **Paquete** | `oficina-opencode` v2.1.0 |
+| **Paquete** | `oficina-opencode` v3.0.0 |
 | **Tools** | 16 |
 | **Hooks** | 7 |
-| **API de plugin** | `@opencode-ai/plugin@1.15.11` |
+| **API de plugin** | `@opencode/plugin@2.1.2` |
 | **Node** | >=20 |
 | **Catálogo** | 258 agentes resolubles en 18 divisiones |
 | **Divisiones** | academic, design, engineering, finance, game-development, gis, healthcare, marketing, paid-media, product, project-management, research, sales, spatial-computing, specialized, strategy, support, testing |