@lunchbox-labs/opencode-tool-inspector 0.0.0-stage → 0.2.0

package/dist/tui.js

@@ -0,0 +1,413 @@
+import { resolveToolAgentAccess, } from "./agents.js";
+import { createDetailViewer } from "./detail-viewer.js";
+import { linesText } from "./schema-text.js";
+import { toolDetail } from "./tool-detail.js";
+import { chosenModelLabel, configuredModel, descriptionSummary, inputCount, providerDefaultModel, sessionModel, toolsFromIds, toolsFromList, } from "./tools.js";
+const toastTitle = "Tool Inspector";
+/** The plain-text fallback can't scroll, so long sections are cut short. */
+const plainTextSectionLines = 20;
+function errorText(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "object" && error !== null) {
+        const record = error;
+        if (typeof record.message === "string") {
+            return record.message;
+        }
+        if (typeof record.data?.message === "string") {
+            return record.data.message;
+        }
+        return JSON.stringify(error);
+    }
+    return String(error);
+}
+/** Names of connected MCP servers, whose tools OpenCode's tool list leaves out. */
+function connectedMcpServers(api) {
+    try {
+        return api.state
+            .mcp()
+            .filter((server) => server.status === "connected")
+            .map((server) => server.name);
+    }
+    catch {
+        return [];
+    }
+}
+function mcpNotice(servers) {
+    if (servers.length === 0) {
+        return undefined;
+    }
+    const names = servers.join(", ");
+    return `Tools from MCP servers (${names}) aren't listed, because OpenCode only adds them when it runs a prompt.`;
+}
+function currentSessionId(api) {
+    const route = api.route.current;
+    return route.name === "session" && typeof route.params?.sessionID === "string"
+        ? route.params.sessionID
+        : undefined;
+}
+async function chooseModel(api, signal) {
+    const sessionId = currentSessionId(api);
+    const fromSession = sessionId === undefined
+        ? undefined
+        : sessionModel(api.state.session.messages(sessionId));
+    if (fromSession !== undefined) {
+        return { ...fromSession, source: "session" };
+    }
+    const connectedProviderIds = api.state.provider.map((provider) => provider.id);
+    const configured = configuredModel(api.state.config.model);
+    // OpenCode skips a configured model whose provider isn't connected.
+    if (configured !== undefined &&
+        (connectedProviderIds.length === 0 ||
+            connectedProviderIds.includes(configured.providerID))) {
+        return { ...configured, source: "configured" };
+    }
+    const response = await api.client.config.providers({ directory: api.state.path.directory }, { signal });
+    if (response.error !== undefined) {
+        throw new Error(errorText(response.error));
+    }
+    const fallback = providerDefaultModel(connectedProviderIds, response.data.default);
+    return fallback === undefined
+        ? undefined
+        : { ...fallback, source: "provider default" };
+}
+async function readAgents(api, signal) {
+    // Guards hosts whose client predates the agents route.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the host supplies the client at runtime.
+    if (typeof api.client.app?.agents !== "function") {
+        throw new Error("this OpenCode doesn't list agents");
+    }
+    const response = await api.client.app.agents({ directory: api.state.path.directory }, { signal });
+    if (response.error !== undefined) {
+        throw new Error(errorText(response.error));
+    }
+    const agents = response.data;
+    if (!Array.isArray(agents)) {
+        throw new Error("the response wasn't an agent list");
+    }
+    // resolveToolAgentAccess skips entries it can't read.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- entries are validated field by field downstream.
+    return agents;
+}
+/**
+ * The permission rules of the current session's top-level session, which OpenCode applies after
+ * each agent's own rules. Sessions usually have none. When a parent isn't loaded, the topmost
+ * session found is used, since a child session carries copies of its parent's deny rules.
+ */
+function sessionPermission(api) {
+    const sessionId = currentSessionId(api);
+    if (sessionId === undefined) {
+        return [];
+    }
+    try {
+        let session = api.state.session.get(sessionId);
+        const seen = new Set();
+        while (session?.parentID !== undefined && !seen.has(session.id)) {
+            seen.add(session.id);
+            const parent = api.state.session.get(session.parentID);
+            if (parent === undefined) {
+                break;
+            }
+            session = parent;
+        }
+        return session?.permission ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function primaryTools(api) {
+    try {
+        return api.state.config.experimental?.primary_tools;
+    }
+    catch {
+        return undefined;
+    }
+}
+function accessByTool(api, tools, agents) {
+    const resolved = resolveToolAgentAccess(tools.map((tool) => tool.id), agents, {
+        // The module reads both options defensively and reports unreadable ones as unknown.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- validated in resolveToolAgentAccess.
+        primaryTools: primaryTools(api),
+        sessionPermission: sessionPermission(api),
+    });
+    return new Map(resolved.map((access) => [access.tool, access]));
+}
+async function readToolList(api, signal) {
+    const directory = api.state.path.directory;
+    let modelFailure;
+    const model = await chooseModel(api, signal).catch((error) => {
+        modelFailure = errorText(error);
+        return undefined;
+    });
+    let listFailure;
+    if (model !== undefined) {
+        try {
+            const response = await api.client.tool.list({ directory, provider: model.providerID, model: model.modelID }, { signal });
+            if (response.error === undefined) {
+                const tools = toolsFromList(response.data);
+                if (tools !== undefined) {
+                    return { tools, model, notice: undefined };
+                }
+                listFailure = "the response wasn't a tool list";
+            }
+            else {
+                listFailure = errorText(response.error);
+            }
+        }
+        catch (error) {
+            listFailure = errorText(error);
+        }
+    }
+    const response = await api.client.tool.ids({ directory }, { signal });
+    const tools = response.error === undefined ? toolsFromIds(response.data) : undefined;
+    if (tools === undefined) {
+        throw new Error(listFailure ??
+            modelFailure ??
+            (response.error === undefined
+                ? "OpenCode did not return a readable tool list."
+                : errorText(response.error)));
+    }
+    const namesOnly = model === undefined
+        ? modelFailure === undefined
+            ? "No model is selected, so this lists every registered tool without details. Pick a model to see what OpenCode offers it."
+            : `Could not work out the current model (${modelFailure}), so this lists tool names only.`
+        : `OpenCode did not return tool details for ${chosenModelLabel(model)} (${listFailure ?? "no reason given"}), so this lists tool names only.`;
+    return { tools, model: undefined, notice: namesOnly };
+}
+async function readCatalog(api, signal) {
+    let agentsFailure;
+    const agentsRead = readAgents(api, signal).catch((error) => {
+        agentsFailure = errorText(error);
+        return undefined;
+    });
+    const list = await readToolList(api, signal);
+    const agents = await agentsRead;
+    let access;
+    if (agents !== undefined) {
+        try {
+            access = accessByTool(api, list.tools, agents);
+        }
+        catch (error) {
+            agentsFailure = errorText(error);
+        }
+    }
+    return {
+        ...list,
+        access,
+        agentsNotice: access === undefined
+            ? `Could not read OpenCode's agents (${agentsFailure ?? "no reason given"}), so tool details don't show which agents can use each tool.`
+            : undefined,
+    };
+}
+function inputCountLabel(tool) {
+    const count = inputCount(tool.parameters);
+    if (count === undefined) {
+        return undefined;
+    }
+    return count === 1 ? "1 input" : `${count} inputs`;
+}
+function registerToolBrowser(api) {
+    const toast = (variant, message) => {
+        api.ui.toast({
+            variant,
+            title: toastTitle,
+            message,
+            duration: variant === "warning" ? 10_000 : 5_000,
+        });
+    };
+    let viewer;
+    const detailViewer = () => {
+        viewer ??= createDetailViewer(api).catch((error) => {
+            toast("warning", `Showing tool details as plain text: ${errorText(error)}`);
+            return undefined;
+        });
+        return viewer;
+    };
+    /** Each displayed dialog gets a revision, so stale close callbacks and late reads are ignored. */
+    let revision = 0;
+    let showing = false;
+    /** The read behind the loading dialog, aborted once anything replaces that dialog. */
+    let activeRead;
+    const close = () => {
+        revision++;
+        showing = false;
+        activeRead?.abort();
+        activeRead = undefined;
+        api.ui.dialog.clear();
+    };
+    const viewContext = () => {
+        const directory = api.state.path.directory;
+        const sessionId = currentSessionId(api);
+        const routeName = api.route.current.name;
+        return () => !api.lifecycle.signal.aborted &&
+            directory === api.state.path.directory &&
+            routeName === api.route.current.name &&
+            sessionId === currentSessionId(api);
+    };
+    const display = (render, size, onClosed) => {
+        const active = ++revision;
+        showing = true;
+        activeRead?.abort();
+        activeRead = undefined;
+        api.ui.dialog.replace(render, () => {
+            if (active !== revision) {
+                return;
+            }
+            revision++;
+            showing = false;
+            onClosed?.();
+        });
+        api.ui.dialog.setSize(size);
+        return active;
+    };
+    const views = {
+        async detail(catalog, tool) {
+            const listRevision = revision;
+            const sameView = viewContext();
+            const detail = toolDetail(tool, catalog.model === undefined
+                ? undefined
+                : chosenModelLabel(catalog.model), catalog.access?.get(tool.id));
+            const render = await detailViewer();
+            if (listRevision !== revision || !sameView()) {
+                return;
+            }
+            display(render === undefined
+                ? () => api.ui.DialogAlert({
+                    title: detail.title,
+                    message: detail.sections
+                        .map((section) => `${section.heading}\n${linesText(section.lines.slice(0, plainTextSectionLines))}${section.lines.length > plainTextSectionLines ? "\n…" : ""}`)
+                        .join("\n\n"),
+                })
+                : () => render(detail), "xlarge", () => {
+                const closedRevision = revision;
+                // The host clears the dialog after this callback; return to the list afterwards.
+                queueMicrotask(() => {
+                    if (closedRevision === revision &&
+                        !api.ui.dialog.open &&
+                        sameView()) {
+                        views.list(catalog, tool.id);
+                    }
+                });
+            });
+        },
+        list(catalog, current) {
+            const sameView = viewContext();
+            display(() => api.ui.DialogSelect({
+                title: catalog.model === undefined
+                    ? "Tools"
+                    : `Tools for ${chosenModelLabel(catalog.model)}`,
+                placeholder: "Search tools",
+                current,
+                options: catalog.tools.map((tool) => {
+                    const summary = descriptionSummary(tool.description);
+                    const footer = inputCountLabel(tool);
+                    return {
+                        title: tool.id,
+                        value: tool.id,
+                        ...(summary === "" ? {} : { description: summary }),
+                        ...(footer === undefined ? {} : { footer }),
+                    };
+                }),
+                onSelect: (option) => {
+                    const tool = catalog.tools.find((item) => item.id === option.value);
+                    if (!sameView()) {
+                        close();
+                        toast("info", "The session changed, so run /tools again.");
+                        return;
+                    }
+                    if (tool !== undefined) {
+                        views.detail(catalog, tool).catch((error) => {
+                            toast("warning", `Could not show ${tool.id}: ${errorText(error)}`);
+                        });
+                    }
+                },
+            }), "large");
+        },
+    };
+    const open = async () => {
+        const sameView = viewContext();
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        api.lifecycle.signal.addEventListener("abort", abort, { once: true });
+        const loading = display(() => api.ui.DialogAlert({
+            title: "Loading tools",
+            message: "Reading the tools OpenCode offers…",
+        }), "medium", abort);
+        activeRead = controller;
+        // Load the viewer alongside the list so opening a tool doesn't wait for it.
+        detailViewer().catch(() => undefined);
+        try {
+            const catalog = await readCatalog(api, controller.signal);
+            if (loading !== revision) {
+                return;
+            }
+            if (!sameView()) {
+                close();
+                return;
+            }
+            if (catalog.tools.length === 0) {
+                close();
+                toast("info", "OpenCode reported no tools.");
+                return;
+            }
+            const notices = [
+                catalog.notice,
+                catalog.agentsNotice,
+                mcpNotice(connectedMcpServers(api)),
+            ].filter((notice) => notice !== undefined);
+            if (notices.length > 0) {
+                toast(catalog.notice === undefined && catalog.agentsNotice === undefined
+                    ? "info"
+                    : "warning", notices.join(" "));
+            }
+            views.list(catalog, undefined);
+        }
+        catch (error) {
+            if (loading === revision) {
+                close();
+                if (sameView()) {
+                    toast("warning", `Could not read tools from OpenCode: ${errorText(error)}`);
+                }
+            }
+        }
+        finally {
+            api.lifecycle.signal.removeEventListener("abort", abort);
+        }
+    };
+    const unregister = api.keymap.registerLayer({
+        commands: [
+            {
+                name: "tool-inspector.browse",
+                title: "Browse tools",
+                category: "Tools",
+                namespace: "palette",
+                slashName: "tools",
+                // Native command dispatch clears its picker after invoking the handler.
+                run: () => Promise.resolve()
+                    .then(open)
+                    .catch((error) => {
+                    toast("warning", `Could not open tools: ${errorText(error)}`);
+                }),
+            },
+        ],
+    });
+    const stopWatching = api.event.on("server.instance.disposed", (event) => {
+        if (event.properties.directory === api.state.path.directory && showing) {
+            close();
+        }
+    });
+    api.lifecycle.onDispose(() => {
+        unregister();
+        stopWatching();
+    });
+}
+const ToolInspectorTui = (api) => {
+    registerToolBrowser(api);
+    return Promise.resolve();
+};
+export default {
+    id: "tool-inspector",
+    tui: ToolInspectorTui,
+};

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@lunchbox-labs/opencode-tool-inspector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Inspect the tools available to OpenCode agents from the TUI",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lunchbox-labs/opencode-tool-inspector.git"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "exports": {
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "default": "./dist/tui.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --test tests/*.test.ts tests/*.test.mjs",
+    "lint": "eslint . --max-warnings 0",
+    "format": "prettier --write src tests scripts package.json tsconfig*.json *.config.mjs",
+    "format:check": "prettier --check src tests scripts package.json tsconfig*.json *.config.mjs",
+    "check": "npm run check:static && npm test",
+    "prepack": "npm run build",
+    "test:package": "npm run build && node --experimental-strip-types --test tests/package.integration.ts",
+    "check:static": "concurrently --names typecheck,lint,format --kill-others-on-fail \"npm run typecheck\" \"npm run lint\" \"npm run format:check\"",
+    "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\""
+  },
+  "devDependencies": {
+    "@eslint-community/eslint-plugin-eslint-comments": "4.8.1",
+    "@eslint/js": "10.0.1",
+    "@opencode-ai/plugin": "1.19.5",
+    "@opencode-ai/sdk": "1.19.5",
+    "@opentui/core": "0.4.5",
+    "@opentui/keymap": "0.4.5",
+    "@opentui/solid": "0.4.5",
+    "@types/node": "24.19.2",
+    "concurrently": "10.0.6",
+    "eslint": "10.14.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-regexp": "3.3.3",
+    "globals": "17.14.0",
+    "prettier": "3.9.10",
+    "solid-js": "1.9.12",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.1",
+    "yaml": "2.9.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}