@lunchbox-labs/opencode-tool-inspector 0.1.0 → 0.2.0

package/README.md

@@ -4,8 +4,6 @@ Browse the tools available to OpenCode agents from the TUI: each tool's descript
 
 Requires Node **22.18+**. Built for OpenCode **1.19.x**, starting at **1.19.0**.
 
-This plugin is in early development and does not provide any commands yet.
-
 ## Install
 
 Add the package to `plugin` in `tui.jsonc`:
@@ -13,3 +11,17 @@ Add the package to `plugin` in `tui.jsonc`:
 ```jsonc
 { "plugin": ["@lunchbox-labs/opencode-tool-inspector"] }
 ```
+
+## Browse tools
+
+Run `/tools`, or **Browse tools** from the command palette, to list the tools OpenCode offers a model: the one the current session's latest message used, otherwise your configured `model`, otherwise the first connected provider's default. The dialog's title names the model and where it came from. If you switch models before your next prompt, the tools offered may differ.
+
+Type to filter the list, and press Enter to see a tool's input schema, the agents that can use it and its full description. The input shows each field's type, whether it's required, its allowed values, default and limits, with nested objects shown under their parent and each option of a union listed with its own fields. Escape returns to the list.
+
+The list includes built-in and plugin tools. MCP server tools aren't listed, because OpenCode only adds them when it runs a prompt; a toast says so when an MCP server is connected. If OpenCode can't resolve tools for a model, the list shows tool names only.
+
+## Agent access
+
+The list isn't filtered by agent. Instead, a tool's detail lists each agent and whether it's allowed to use the tool, asks first, is denied, or isn't offered the tool at all, following each agent's merged `permission` rules and the rules of the current top-level session. Input patterns with different access, such as `read` asking first for `*.env` files, are listed under the agent. Agents with mode `all` also show their access when they run as a subagent, where that differs, since OpenCode always denies subagents any `experimental.primary_tools`, and denies `todowrite` and `task` unless the agent's own rules name them.
+
+OpenCode's own hidden agents, such as `compaction` and `title`, are left out. If OpenCode's agents can't be read, details open without this section and a toast says why.

package/dist/agent-text.d.ts

@@ -0,0 +1,4 @@
+import type { ToolAgentAccess } from "./agents.ts";
+import type { TextLine } from "./schema-text.ts";
+/** Renders which agents can use a tool, primary agents first. */
+export declare function agentAccessLines(access: ToolAgentAccess): TextLine[];

package/dist/agent-text.js

@@ -0,0 +1,85 @@
+const actionLabels = {
+    allow: "allowed",
+    ask: "asks first",
+    deny: "denied",
+};
+const modeLabels = {
+    primary: "primary",
+    subagent: "subagent",
+    all: "primary or subagent",
+    unknown: undefined,
+};
+function muted(text) {
+    return { text, tone: "muted" };
+}
+function plain(text) {
+    return { text, tone: "plain" };
+}
+function indent(depth) {
+    return "  ".repeat(depth);
+}
+function decisionSummary(decision) {
+    if (decision.access === "unknown") {
+        return "unknown, permissions couldn't be read";
+    }
+    if (decision.offeredToModel === false) {
+        return "not offered to the model";
+    }
+    return actionLabels[decision.access];
+}
+function exceptionLines(decision, depth) {
+    if (decision.offeredToModel === false) {
+        return [];
+    }
+    return decision.exceptions.map((exception) => [
+        plain(`${indent(depth)}${actionLabels[exception.access]} for `),
+        { text: exception.pattern, tone: "name" },
+    ]);
+}
+function agentLines(agent) {
+    const notes = [
+        modeLabels[agent.mode],
+        ...(agent.hidden ? ["hidden"] : []),
+    ].filter((note) => note !== undefined);
+    const lines = [
+        [
+            { text: agent.agent, tone: "name" },
+            muted(`  ${notes.length === 0 ? "" : `${notes.join(", ")}: `}${decisionSummary(agent)}`),
+        ],
+        ...exceptionLines(agent, 1),
+    ];
+    if (agent.whenSubagent !== undefined) {
+        lines.push([
+            plain(`${indent(1)}as a subagent: ${decisionSummary(agent.whenSubagent)}`),
+        ], ...exceptionLines(agent.whenSubagent, 2));
+    }
+    return lines;
+}
+/** OpenCode's own hidden agents, such as `compaction` and `title`, never take tool calls. */
+function listed(agent) {
+    return !(agent.native && agent.hidden);
+}
+function primaryFirst(left, right) {
+    const rank = (agent) => (agent.mode === "subagent" ? 1 : 0);
+    return rank(left) - rank(right);
+}
+/** Renders which agents can use a tool, primary agents first. */
+export function agentAccessLines(access) {
+    const agents = access.agents.filter(listed).sort(primaryFirst);
+    if (agents.length === 0) {
+        return [[muted("OpenCode reported no agents that use tools.")]];
+    }
+    const permissionNote = access.permission === access.tool
+        ? []
+        : [[muted(`Checked as the ${access.permission} permission.`)]];
+    const patternNote = agents.some((agent) => exceptionLines(agent, 1).length > 0 ||
+        (agent.whenSubagent !== undefined &&
+            exceptionLines(agent.whenSubagent, 2).length > 0))
+        ? [
+            [
+                muted("Patterns match the call's input, such as a command or path; a later line wins."),
+            ],
+        ]
+        : [];
+    return [...permissionNote, ...agents.flatMap(agentLines), ...patternNote];
+}

package/dist/agents.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Works out which agents may use each tool, following the permission rules
+ * OpenCode 1.19 applies when it offers tools to a model and when a tool asks
+ * for permission.
+ *
+ * Pass the agents from `client.app.agents()` and either the items of
+ * `client.tool.list({ provider, model })` or the ids from `client.tool.ids()`.
+ * Each agent's `permission` ruleset already combines OpenCode's defaults, the
+ * global `permission` and legacy `tools` settings and the agent's own rules,
+ * and disabled agents are already left out. Only permissions are applied here:
+ * OpenCode also withholds some tools depending on the model, such as
+ * `websearch` without a search provider, and `tool.list` already leaves those
+ * out for the model it is given.
+ */
+export type PermissionAction = "allow" | "ask" | "deny";
+export type ToolAccess = PermissionAction | "unknown";
+export type AgentMode = "primary" | "subagent" | "all" | "unknown";
+export interface PermissionRuleInput {
+    readonly permission: string;
+    readonly pattern: string;
+    readonly action: PermissionAction;
+}
+export interface AgentInput {
+    readonly name: string;
+    readonly mode?: string;
+    readonly hidden?: boolean;
+    readonly native?: boolean;
+    readonly permission?: unknown;
+}
+export type ToolInput = string | {
+    readonly id: string;
+};
+export interface ToolAgentAccessOptions {
+    /** `experimental.primary_tools` from the OpenCode config: tools denied to agents running as subagents. */
+    readonly primaryTools?: readonly string[];
+    /**
+     * The permission ruleset of the session the agents would run in, which OpenCode applies after the
+     * agent's rules. Pass a top-level session's ruleset: when it spawns a subagent, OpenCode copies only
+     * its deny and `external_directory` rules into the subagent's session.
+     */
+    readonly sessionPermission?: unknown;
+}
+/** An input pattern whose access differs from the tool's general access. */
+export interface PatternAccess {
+    readonly pattern: string;
+    readonly access: PermissionAction;
+}
+export interface AccessDecision {
+    /**
+     * Access for inputs that no pattern in `exceptions` matches. OpenCode can still ask at call time for
+     * paths outside the project (the `external_directory` permission), and an `ask` the user already
+     * answered with "always" may already be allowed for matching calls.
+     */
+    readonly access: ToolAccess;
+    /** Pattern-specific access in OpenCode's precedence order: a later entry wins over an earlier one when both match. */
+    readonly exceptions: readonly PatternAccess[];
+    /**
+     * Whether OpenCode offers the tool to the model at all. It withholds a tool only when the last rule for
+     * its permission denies the `*` pattern, so a tool can be offered even when every call is denied.
+     * `undefined` when the rules can't be read.
+     */
+    readonly offeredToModel: boolean | undefined;
+}
+export interface AgentToolAccess extends AccessDecision {
+    readonly agent: string;
+    readonly mode: AgentMode;
+    readonly hidden: boolean;
+    readonly native: boolean;
+    /** For agents with mode `all`: access when the agent runs as a subagent, present only when it differs. */
+    readonly whenSubagent?: AccessDecision;
+}
+export interface ToolAgentAccess {
+    readonly tool: string;
+    /** The permission name OpenCode checks for this tool, such as `edit` for `write`. */
+    readonly permission: string;
+    readonly agents: readonly AgentToolAccess[];
+}
+export declare function permissionForTool(toolId: string): string;
+export declare function resolveToolAgentAccess(tools: readonly ToolInput[], agents: readonly AgentInput[], options?: ToolAgentAccessOptions): ToolAgentAccess[];

package/dist/agents.js

@@ -0,0 +1,244 @@
+/**
+ * Works out which agents may use each tool, following the permission rules
+ * OpenCode 1.19 applies when it offers tools to a model and when a tool asks
+ * for permission.
+ *
+ * Pass the agents from `client.app.agents()` and either the items of
+ * `client.tool.list({ provider, model })` or the ids from `client.tool.ids()`.
+ * Each agent's `permission` ruleset already combines OpenCode's defaults, the
+ * global `permission` and legacy `tools` settings and the agent's own rules,
+ * and disabled agents are already left out. Only permissions are applied here:
+ * OpenCode also withholds some tools depending on the model, such as
+ * `websearch` without a search provider, and `tool.list` already leaves those
+ * out for the model it is given.
+ */
+const editTools = new Set(["edit", "write", "apply_patch"]);
+const mcpResourceReadTools = new Set([
+    "list_mcp_resources",
+    "list_mcp_resource_templates",
+    "read_mcp_resource",
+]);
+const unknownDecision = {
+    access: "unknown",
+    exceptions: [],
+    offeredToModel: undefined,
+};
+const compiledWildcards = new Map();
+function field(value, key) {
+    return typeof value === "object" && value !== null
+        ? Reflect.get(value, key)
+        : undefined;
+}
+function isPermissionAction(value) {
+    return value === "allow" || value === "ask" || value === "deny";
+}
+function readRule(value) {
+    const permission = field(value, "permission");
+    const pattern = field(value, "pattern");
+    const action = field(value, "action");
+    if (typeof permission !== "string" ||
+        typeof pattern !== "string" ||
+        !isPermissionAction(action)) {
+        return undefined;
+    }
+    return { permission, pattern, action };
+}
+function readRuleset(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const rules = [];
+    for (const item of value) {
+        const rule = readRule(item);
+        if (rule === undefined) {
+            return undefined;
+        }
+        rules.push(rule);
+    }
+    return rules;
+}
+function readStringList(value) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const strings = [];
+    for (const item of value) {
+        if (typeof item !== "string") {
+            return undefined;
+        }
+        strings.push(item);
+    }
+    return strings;
+}
+function readItems(value) {
+    return Array.isArray(value) ? value : [];
+}
+function readAgent(value) {
+    const name = field(value, "name");
+    if (typeof name !== "string") {
+        return undefined;
+    }
+    const mode = field(value, "mode");
+    return {
+        name,
+        mode: typeof mode === "string" ? mode : undefined,
+        hidden: field(value, "hidden") === true,
+        native: field(value, "native") === true,
+        permission: field(value, "permission"),
+    };
+}
+function readToolId(value) {
+    const id = typeof value === "string" ? value : field(value, "id");
+    return typeof id === "string" ? id : undefined;
+}
+function readMode(mode) {
+    return mode === "primary" || mode === "subagent" || mode === "all"
+        ? mode
+        : "unknown";
+}
+function runsOnWindows() {
+    return typeof process !== "undefined" && process.platform === "win32";
+}
+// Same matching as OpenCode's wildcard helper, including its trailing " *"
+// special case, slash normalization and case-insensitive matching on Windows.
+function compileWildcard(pattern, flags) {
+    let expression = pattern
+        .replaceAll("\\", "/")
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    if (expression.endsWith(" .*")) {
+        expression = `${expression.slice(0, -3)}( .*)?`;
+    }
+    return new RegExp(`^${expression}$`, flags);
+}
+function matchesWildcard(input, pattern) {
+    const flags = runsOnWindows() ? "si" : "s";
+    const key = `${flags}:${pattern}`;
+    let compiled = compiledWildcards.get(key);
+    if (compiled === undefined) {
+        compiled = compileWildcard(pattern, flags);
+        compiledWildcards.set(key, compiled);
+    }
+    return compiled.test(input.replaceAll("\\", "/"));
+}
+// A trailing " *" also matches nothing, so "* *" covers every input too.
+function isCatchAllPattern(pattern) {
+    return /^\*+(?: \*)?$/.test(pattern);
+}
+function decide(permission, rules) {
+    const matching = rules.filter((rule) => matchesWildcard(permission, rule.permission));
+    const lastCatchAll = matching.findLastIndex((rule) => isCatchAllPattern(rule.pattern));
+    const access = matching[lastCatchAll]?.action ?? "ask";
+    const exceptions = [];
+    for (const rule of matching.slice(lastCatchAll + 1)) {
+        const earlier = exceptions.findIndex((exception) => exception.pattern === rule.pattern);
+        if (earlier !== -1) {
+            exceptions.splice(earlier, 1);
+        }
+        if (exceptions.length === 0 && rule.action === access) {
+            continue;
+        }
+        exceptions.push({ pattern: rule.pattern, access: rule.action });
+    }
+    const firstChange = exceptions.findIndex((exception) => exception.access !== access);
+    const lastRule = matching.at(-1);
+    return {
+        access,
+        exceptions: firstChange === -1 ? [] : exceptions.slice(firstChange),
+        offeredToModel: !(lastRule?.pattern === "*" && lastRule.action === "deny"),
+    };
+}
+function sameDecision(first, second) {
+    return (first.access === second.access &&
+        first.offeredToModel === second.offeredToModel &&
+        first.exceptions.length === second.exceptions.length &&
+        first.exceptions.every((exception, index) => exception.pattern === second.exceptions[index]?.pattern &&
+            exception.access === second.exceptions[index].access));
+}
+function denyAll(permission) {
+    return { permission, pattern: "*", action: "deny" };
+}
+// Mirrors the session rules OpenCode's task tool gives a subagent.
+function subagentSessionRules(agentRules, parentSessionRules, primaryTools) {
+    const namesPermission = (permission) => agentRules.some((rule) => rule.permission === permission);
+    const inherited = [
+        ...parentSessionRules.filter((rule) => rule.action === "deny" || rule.permission === "external_directory"),
+        ...["todowrite", "task"]
+            .filter((permission) => !namesPermission(permission))
+            .map(denyAll),
+    ];
+    const isInherited = (deny) => inherited.some((rule) => rule.permission === deny.permission &&
+        rule.pattern === deny.pattern &&
+        rule.action === deny.action);
+    return [
+        ...inherited,
+        ...primaryTools.map(denyAll).filter((deny) => !isInherited(deny)),
+    ];
+}
+function agentAccess(agent, permission, sessionRules, primaryTools) {
+    const mode = readMode(agent.mode);
+    const summary = {
+        agent: agent.name,
+        mode,
+        hidden: agent.hidden === true,
+        native: agent.native === true,
+    };
+    const agentRules = readRuleset(agent.permission);
+    if (agentRules === undefined) {
+        return { ...summary, ...unknownDecision };
+    }
+    const primaryDecision = () => sessionRules === undefined
+        ? unknownDecision
+        : decide(permission, [...agentRules, ...sessionRules]);
+    const subagentDecision = () => primaryTools === undefined || sessionRules === undefined
+        ? unknownDecision
+        : decide(permission, [
+            ...agentRules,
+            ...subagentSessionRules(agentRules, sessionRules, primaryTools),
+        ]);
+    switch (mode) {
+        case "subagent":
+            return { ...summary, ...subagentDecision() };
+        case "all": {
+            const asPrimary = primaryDecision();
+            const asSubagent = subagentDecision();
+            return sameDecision(asPrimary, asSubagent)
+                ? { ...summary, ...asPrimary }
+                : { ...summary, ...asPrimary, whenSubagent: asSubagent };
+        }
+        case "primary":
+        case "unknown":
+            return { ...summary, ...primaryDecision() };
+    }
+}
+export function permissionForTool(toolId) {
+    if (editTools.has(toolId)) {
+        return "edit";
+    }
+    if (mcpResourceReadTools.has(toolId)) {
+        return "read";
+    }
+    return toolId;
+}
+export function resolveToolAgentAccess(tools, agents, options = {}) {
+    const sessionRules = readRuleset(field(options, "sessionPermission") ?? []);
+    const primaryTools = readStringList(field(options, "primaryTools"));
+    const readableAgents = readItems(agents)
+        .map(readAgent)
+        .filter((agent) => agent !== undefined);
+    return readItems(tools)
+        .map(readToolId)
+        .filter((tool) => tool !== undefined)
+        .map((tool) => {
+        const permission = permissionForTool(tool);
+        return {
+            tool,
+            permission,
+            agents: readableAgents.map((agent) => agentAccess(agent, permission, sessionRules, primaryTools)),
+        };
+    });
+}

package/dist/detail-viewer.d.ts

@@ -0,0 +1,6 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { ToolDetail } from "./tool-detail.ts";
+type DialogElement = ReturnType<TuiPluginApi["ui"]["DialogAlert"]>;
+/** Renders a tool's detail sections in a keyboard-scrollable box inside the host's dialog frame. */
+export declare function createDetailViewer(api: TuiPluginApi): Promise<(detail: ToolDetail) => DialogElement>;
+export {};

package/dist/detail-viewer.js

@@ -0,0 +1,123 @@
+// The host dialog starts a quarter down the screen; its padding plus this view's
+// title, footer, gaps and a margin clear of the status bar take the remaining rows.
+const chromeRows = 9;
+/** Renders a tool's detail sections in a keyboard-scrollable box inside the host's dialog frame. */
+export async function createDetailViewer(api) {
+    // OpenCode supplies its shared runtime; importing this entrypoint stays Node-safe.
+    const { BoxRenderable, RenderableEvents, ScrollBoxRenderable, StyledText, TextAttributes, TextRenderable, } = await import("@opentui/core");
+    return (detail) => {
+        const { renderer } = api;
+        const theme = api.theme.current;
+        const toneColours = {
+            plain: theme.text,
+            name: theme.text,
+            muted: theme.textMuted,
+        };
+        const styled = (lines) => new StyledText(lines.flatMap((line, index) => [
+            ...(index === 0 ? [] : [{ __isChunk: true, text: "\n" }]),
+            ...line.map((segment) => ({
+                __isChunk: true,
+                text: segment.text,
+                fg: toneColours[segment.tone],
+                ...(segment.tone === "name"
+                    ? { attributes: TextAttributes.BOLD }
+                    : {}),
+            })),
+        ]));
+        const rows = () => Math.max(1, renderer.height - Math.floor(renderer.height / 4) - chromeRows);
+        const view = new BoxRenderable(renderer, {
+            flexDirection: "column",
+            paddingX: 2,
+            paddingBottom: 1,
+            gap: 1,
+        });
+        view.add(new TextRenderable(renderer, {
+            content: detail.title,
+            fg: theme.text,
+            attributes: TextAttributes.BOLD,
+            selectable: false,
+        }));
+        const body = new BoxRenderable(renderer, {
+            flexDirection: "column",
+            gap: 1,
+        });
+        if (detail.subtitle !== undefined) {
+            body.add(new TextRenderable(renderer, {
+                content: detail.subtitle,
+                fg: theme.textMuted,
+                wrapMode: "word",
+            }));
+        }
+        for (const section of detail.sections) {
+            const block = new BoxRenderable(renderer, { flexDirection: "column" });
+            block.add(new TextRenderable(renderer, {
+                content: section.heading,
+                fg: theme.accent,
+                attributes: TextAttributes.BOLD,
+                selectable: false,
+            }));
+            block.add(new TextRenderable(renderer, {
+                content: styled(section.lines),
+                fg: theme.text,
+                wrapMode: "word",
+            }));
+            body.add(block);
+        }
+        const unwrappedRows = detail.sections.reduce((total, section) => total + section.lines.length + 2, detail.subtitle === undefined ? 0 : 2);
+        const scroll = new ScrollBoxRenderable(renderer, {
+            height: Math.min(rows(), unwrappedRows),
+            flexShrink: 0,
+            verticalScrollbarOptions: {
+                paddingLeft: 1,
+                trackOptions: {
+                    backgroundColor: theme.backgroundElement,
+                    foregroundColor: theme.border,
+                },
+            },
+        });
+        // Short details keep a compact dialog; long ones scroll within the terminal.
+        const fit = () => {
+            if (!scroll.isDestroyed) {
+                scroll.height = Math.max(1, Math.min(rows(), body.height));
+            }
+        };
+        body.onSizeChange = fit;
+        scroll.add(body);
+        view.add(scroll);
+        view.add(new TextRenderable(renderer, {
+            content: "↑/↓ scroll · pgup/pgdn page · home/end · esc back",
+            fg: theme.textMuted,
+            selectable: false,
+        }));
+        renderer.on("resize", fit);
+        // The session's global paging keys close dialogs; a later layer on the
+        // focused box takes precedence, as the host's own DialogSelect does.
+        const unbind = api.keymap.registerLayer({
+            target: scroll,
+            targetMode: "focus",
+            bindings: [
+                { key: "pageup", cmd: () => scroll.scrollBy(-1 / 2, "viewport") },
+                { key: "pagedown", cmd: () => scroll.scrollBy(1 / 2, "viewport") },
+                { key: "home", cmd: () => scroll.scrollBy(-1, "content") },
+                { key: "end", cmd: () => scroll.scrollBy(1, "content") },
+            ],
+        });
+        // Escape first restores the host's previous input focus, as after native DialogSelect.
+        const focus = setTimeout(() => {
+            if (!scroll.isDestroyed && !api.lifecycle.signal.aborted) {
+                scroll.focus();
+            }
+        }, 1);
+        const dispose = () => view.destroyRecursively();
+        api.lifecycle.signal.addEventListener("abort", dispose, { once: true });
+        view.on(RenderableEvents.DESTROYED, () => {
+            clearTimeout(focus);
+            renderer.off("resize", fit);
+            unbind();
+            api.lifecycle.signal.removeEventListener("abort", dispose);
+        });
+        // OpenTUI accepts Renderable children; Solid's shared JSX type still names DOM nodes.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- OpenTUI's reconciler inserts Renderable instances directly.
+        return view;
+    };
+}

package/dist/schema-text.d.ts

@@ -0,0 +1,10 @@
+export type TextTone = "plain" | "name" | "muted";
+export interface TextSegment {
+    text: string;
+    tone: TextTone;
+}
+/** A line of rendered text, split into toned segments so the viewer can colour names and types. */
+export type TextLine = TextSegment[];
+/** Renders a tool's input JSON schema as indented, readable lines. */
+export declare function schemaLines(schema: unknown): TextLine[];
+export declare function linesText(lines: readonly TextLine[]): string;