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

package/dist/schema-text.js

@@ -0,0 +1,429 @@
+const indentWidth = 2;
+const maximumDepth = 8;
+const maximumLines = 400;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function literal(value) {
+    const json = JSON.stringify(value);
+    return json ?? String(value);
+}
+function plain(text) {
+    return { text, tone: "plain" };
+}
+function indentText(depth) {
+    return " ".repeat(depth * indentWidth);
+}
+function descriptionLines(description, depth) {
+    if (typeof description !== "string" || description.trim() === "") {
+        return [];
+    }
+    return description
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => [plain(`${indentText(depth)}${line}`)]);
+}
+function withoutReference(node) {
+    const { $ref: _reference, ...rest } = node;
+    return rest;
+}
+function decodedPointerKey(rawKey) {
+    try {
+        return decodeURIComponent(rawKey);
+    }
+    catch {
+        return rawKey;
+    }
+}
+/** Resolves local `$ref`s, as zod and MCP servers emit for shared definitions. */
+function resolveReference(node, root, visiting) {
+    const reference = node.$ref;
+    if (typeof reference !== "string" || !reference.startsWith("#")) {
+        return { node, recursive: false };
+    }
+    if (visiting.has(reference)) {
+        return { node, reference, recursive: true };
+    }
+    let target = root;
+    for (const rawKey of reference.slice(1).split("/").filter(Boolean)) {
+        const key = decodedPointerKey(rawKey)
+            .replaceAll("~1", "/")
+            .replaceAll("~0", "~");
+        target = isObject(target) ? target[key] : undefined;
+    }
+    return isObject(target)
+        ? {
+            node: { ...target, ...withoutReference(node) },
+            reference,
+            recursive: false,
+        }
+        : { node, reference, recursive: false };
+}
+function referenceName(reference) {
+    const name = reference.split("/").at(-1) ?? "";
+    return name === "" || name === "#" ? "the whole input" : name;
+}
+function nonEmptyList(value) {
+    if (Array.isArray(value) && value.length > 0) {
+        const items = value;
+        return items;
+    }
+    return undefined;
+}
+function variants(node) {
+    return nonEmptyList(node.anyOf) ?? nonEmptyList(node.oneOf);
+}
+function hasCombinators(node) {
+    return variants(node) !== undefined || nonEmptyList(node.allOf) !== undefined;
+}
+/** Folds `allOf` members' properties and required names into one object schema. */
+function mergedAllOf(node, root, visiting) {
+    const members = nonEmptyList(node.allOf);
+    if (members === undefined) {
+        return node;
+    }
+    const properties = {};
+    const required = new Set();
+    for (const member of [...members, node]) {
+        if (!isObject(member)) {
+            continue;
+        }
+        const resolved = resolveReference(member, root, visiting);
+        const memberVisiting = resolved.reference === undefined
+            ? visiting
+            : new Set([...visiting, resolved.reference]);
+        const memberNode = member === node
+            ? member
+            : resolved.recursive
+                ? {}
+                : mergedAllOf(resolved.node, root, memberVisiting);
+        if (isObject(memberNode.properties)) {
+            Object.assign(properties, memberNode.properties);
+        }
+        if (Array.isArray(memberNode.required)) {
+            const memberRequired = memberNode.required;
+            for (const name of memberRequired) {
+                required.add(name);
+            }
+        }
+    }
+    const { allOf: _allOf, ...rest } = node;
+    return Object.keys(properties).length === 0
+        ? rest
+        : { ...rest, properties, required: [...required] };
+}
+function pluralType(type) {
+    if (type === "any") {
+        return "values";
+    }
+    if (type.startsWith('"') || type.includes(" ")) {
+        return `items of ${type}`;
+    }
+    return type.endsWith("s") ? type : `${type}s`;
+}
+function typeName(schema, root, visiting, depth) {
+    if (schema === true ||
+        (isObject(schema) && Object.keys(schema).length === 0)) {
+        return "any";
+    }
+    if (schema === false) {
+        return "never";
+    }
+    if (!isObject(schema)) {
+        return "unknown";
+    }
+    if (depth > maximumDepth) {
+        return "…";
+    }
+    const resolved = resolveReference(schema, root, visiting);
+    if (resolved.recursive && resolved.reference !== undefined) {
+        return referenceName(resolved.reference);
+    }
+    const nextVisiting = resolved.reference === undefined
+        ? visiting
+        : new Set([...visiting, resolved.reference]);
+    const node = mergedAllOf(resolved.node, root, nextVisiting);
+    const nestedName = (nested) => typeName(nested, root, nextVisiting, depth + 1);
+    const arrayName = () => {
+        if (node.items === undefined) {
+            return "array";
+        }
+        if (Array.isArray(node.items)) {
+            const items = node.items;
+            return `tuple of ${items.map(nestedName).join(", ")}`;
+        }
+        return `array of ${pluralType(nestedName(node.items))}`;
+    };
+    if (Object.hasOwn(node, "const")) {
+        return literal(node.const);
+    }
+    if (Array.isArray(node.enum) && node.enum.length > 0) {
+        return node.enum.map(literal).join(" | ");
+    }
+    const alternatives = variants(node);
+    if (alternatives !== undefined) {
+        return [...new Set(alternatives.map(nestedName))].join(" | ");
+    }
+    const type = node.type;
+    if (Array.isArray(type)) {
+        const names = type
+            .filter((item) => typeof item === "string")
+            .map((item) => (item === "array" ? arrayName() : item));
+        return names.length === 0 ? "any" : names.join(" | ");
+    }
+    if (type === "array") {
+        return arrayName();
+    }
+    if (type === "object" || isObject(node.properties)) {
+        if (!isObject(node.properties) && isObject(node.additionalProperties)) {
+            return `object with ${nestedName(node.additionalProperties)} values`;
+        }
+        return "object";
+    }
+    return typeof type === "string" ? type : "any";
+}
+const unboundedLimits = new Set([
+    Number.MAX_SAFE_INTEGER,
+    Number.MIN_SAFE_INTEGER,
+    Number.MAX_VALUE,
+    -Number.MAX_VALUE,
+]);
+function constraintNotes(node) {
+    const notes = [];
+    const bound = (key, symbol) => {
+        const value = node[key];
+        if (typeof value === "number" && !unboundedLimits.has(value)) {
+            notes.push(`${symbol} ${value}`);
+        }
+    };
+    bound("minimum", "≥");
+    bound("exclusiveMinimum", ">");
+    bound("maximum", "≤");
+    bound("exclusiveMaximum", "<");
+    const count = (key, label) => {
+        const value = node[key];
+        if (typeof value === "number") {
+            notes.push(`${label} ${value}`);
+        }
+    };
+    count("minLength", "min length");
+    count("maxLength", "max length");
+    count("minItems", "min items");
+    count("maxItems", "max items");
+    if (typeof node.format === "string") {
+        notes.push(`format ${node.format}`);
+    }
+    if (typeof node.pattern === "string") {
+        notes.push(`pattern "${node.pattern.replaceAll("\n", "\\n")}"`);
+    }
+    if (Object.hasOwn(node, "default")) {
+        notes.push(`default ${literal(node.default)}`);
+    }
+    if (node.deprecated === true) {
+        notes.push("deprecated");
+    }
+    return notes;
+}
+/** The object schema whose properties appear nested under a property, if any. */
+function nestedObject(node, root, visiting) {
+    const resolved = resolveReference(node, root, visiting);
+    if (resolved.recursive) {
+        return undefined;
+    }
+    const nextVisiting = resolved.reference === undefined
+        ? visiting
+        : new Set([...visiting, resolved.reference]);
+    const merged = mergedAllOf(resolved.node, root, nextVisiting);
+    // An empty `properties` beside a union, as some schema generators emit, defers to the union.
+    if (isObject(merged.properties) &&
+        (Object.keys(merged.properties).length > 0 ||
+            variants(merged) === undefined)) {
+        return { node: merged, visiting: nextVisiting };
+    }
+    const items = merged.items;
+    if (isObject(items)) {
+        return nestedObject(items, root, nextVisiting);
+    }
+    const alternatives = variants(merged);
+    if (alternatives !== undefined) {
+        const objects = alternatives
+            .filter(isObject)
+            .map((variant) => nestedObject(variant, root, nextVisiting))
+            .filter((variant) => variant !== undefined);
+        return objects.length === 1 ? objects[0] : undefined;
+    }
+    return undefined;
+}
+function muted(text) {
+    return { text, tone: "muted" };
+}
+function listedObjectVariants(node, root, visiting) {
+    return (variants(node) ?? []).filter((variant) => isObject(variant) && nestedObject(variant, root, visiting) !== undefined).length;
+}
+/** Whether listing a union option says more than "object". */
+function informativeVariant(variant, root, visiting) {
+    const type = typeName(variant, root, visiting, 0);
+    return ((type !== "object" && type !== "any") ||
+        (isObject(variant) && nestedObject(variant, root, visiting) !== undefined));
+}
+/** The union of several object options under a property, following array items, if any. */
+function objectUnion(node, root, visiting) {
+    const resolved = resolveReference(node, root, visiting);
+    if (resolved.recursive) {
+        return undefined;
+    }
+    const nextVisiting = resolved.reference === undefined
+        ? visiting
+        : new Set([...visiting, resolved.reference]);
+    const merged = mergedAllOf(resolved.node, root, nextVisiting);
+    if (listedObjectVariants(merged, root, nextVisiting) > 1) {
+        return { node: merged, visiting: nextVisiting };
+    }
+    // A nullable union wraps the union beside a null option.
+    const present = (variants(merged) ?? []).filter((variant) => !(isObject(variant) && variant.type === "null"));
+    if (present.length === 1 && isObject(present[0])) {
+        return objectUnion(present[0], root, nextVisiting);
+    }
+    return isObject(merged.items)
+        ? objectUnion(merged.items, root, nextVisiting)
+        : undefined;
+}
+/**
+ * Lists an object schema's properties, then each option of a union beside them, indented by
+ * depth.
+ */
+function propertyLines(objectSchema, root, visiting, depth) {
+    if (depth > maximumDepth) {
+        return [[plain(`${indentText(depth)}…`)]];
+    }
+    /** Lists each option of a union, or nothing when no option says more than "object". */
+    const optionLines = (schema) => {
+        const alternatives = variants(schema);
+        if (alternatives?.some((variant) => informativeVariant(variant, root, visiting)) !== true) {
+            return [];
+        }
+        return alternatives.flatMap((variant, index) => {
+            const heading = [
+                plain(indentText(depth)),
+                { text: `Option ${index + 1}`, tone: "name" },
+            ];
+            const nested = isObject(variant)
+                ? nestedObject(variant, root, visiting)
+                : undefined;
+            const lines = nested === undefined
+                ? []
+                : propertyLines(nested.node, root, nested.visiting, depth + 1);
+            return lines.length > 0
+                ? [heading, ...lines]
+                : [
+                    [
+                        ...heading,
+                        muted(`  ${typeName(variant, root, visiting, depth)}`),
+                    ],
+                ];
+        });
+    };
+    const properties = isObject(objectSchema.properties)
+        ? Object.entries(objectSchema.properties)
+        : [];
+    const options = optionLines(objectSchema);
+    if (properties.length === 0) {
+        return options;
+    }
+    const required = new Set(Array.isArray(objectSchema.required)
+        ? objectSchema.required.filter((name) => typeof name === "string")
+        : []);
+    const fields = properties.flatMap(([name, property]) => {
+        const resolved = isObject(property)
+            ? mergedAllOf(resolveReference(property, root, visiting).node, root, visiting)
+            : {};
+        const details = [
+            typeName(property, root, visiting, depth),
+            ...(required.has(name) ? ["required"] : []),
+            ...constraintNotes(resolved),
+        ];
+        const heading = [
+            plain(indentText(depth)),
+            { text: name, tone: "name" },
+            { text: `  ${details.join(", ")}`, tone: "muted" },
+        ];
+        const nested = isObject(property)
+            ? nestedObject(property, root, visiting)
+            : undefined;
+        const union = nested === undefined && isObject(property)
+            ? objectUnion(property, root, visiting)
+            : undefined;
+        const childLines = nested !== undefined
+            ? propertyLines(nested.node, root, nested.visiting, depth + 1)
+            : union !== undefined
+                ? propertyLines(union.node, root, union.visiting, depth + 1)
+                : [];
+        return [
+            heading,
+            ...descriptionLines(resolved.description, depth + 1),
+            ...childLines,
+        ];
+    });
+    return options.length === 0
+        ? fields
+        : [...fields, [plain(indentText(depth)), muted("And one of:")], ...options];
+}
+function rawSchemaLines(schema) {
+    return [
+        [muted("OpenCode reported this input schema:")],
+        ...JSON.stringify(schema, undefined, indentWidth)
+            .split("\n")
+            .map((line) => [muted(line)]),
+    ];
+}
+function capped(lines) {
+    if (lines.length <= maximumLines) {
+        return lines;
+    }
+    return [
+        ...lines.slice(0, maximumLines),
+        [muted(`… ${lines.length - maximumLines} more lines not shown.`)],
+    ];
+}
+function rootLines(schema) {
+    const nested = nestedObject(schema, schema, new Set());
+    if (nested !== undefined) {
+        const lines = propertyLines(nested.node, schema, nested.visiting, 0);
+        if (lines.length > 0) {
+            return lines;
+        }
+    }
+    const resolved = resolveReference(schema, schema, new Set()).node;
+    const alternatives = variants(mergedAllOf(resolved, schema, new Set()));
+    const informative = alternatives?.some((variant) => informativeVariant(variant, schema, new Set()));
+    if (alternatives !== undefined && informative === true) {
+        return [
+            [muted("Takes one of these inputs:")],
+            ...propertyLines(mergedAllOf(resolved, schema, new Set()), schema, new Set(), 0),
+        ];
+    }
+    const type = typeName(schema, schema, new Set(), 0);
+    if (type === "object" || type === "any") {
+        return hasCombinators(resolved)
+            ? rawSchemaLines(schema)
+            : [[muted("Takes no input.")]];
+    }
+    return [[plain("Input is "), { text: type, tone: "name" }]];
+}
+/** Renders a tool's input JSON schema as indented, readable lines. */
+export function schemaLines(schema) {
+    if (!isObject(schema)) {
+        return [[muted("OpenCode did not report an input schema.")]];
+    }
+    try {
+        return capped(rootLines(schema));
+    }
+    catch {
+        return capped(rawSchemaLines(schema));
+    }
+}
+export function linesText(lines) {
+    return lines
+        .map((line) => line.map((segment) => segment.text).join(""))
+        .join("\n");
+}

package/dist/tool-detail.d.ts

@@ -0,0 +1,17 @@
+import type { ToolAgentAccess } from "./agents.ts";
+import { type TextLine } from "./schema-text.ts";
+import type { BrowsableTool } from "./tools.ts";
+export interface DetailSection {
+    heading: string;
+    lines: TextLine[];
+}
+export interface ToolDetail {
+    title: string;
+    subtitle: string | undefined;
+    sections: DetailSection[];
+}
+/**
+ * The detail view's content. The Agents section is left out when OpenCode's agents couldn't be
+ * read.
+ */
+export declare function toolDetail(tool: BrowsableTool, modelLabel: string | undefined, access?: ToolAgentAccess): ToolDetail;

package/dist/tool-detail.js

@@ -0,0 +1,41 @@
+import { agentAccessLines } from "./agent-text.js";
+import { schemaLines } from "./schema-text.js";
+function muted(text) {
+    return [[{ text, tone: "muted" }]];
+}
+function textLines(text) {
+    return text
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => [{ text: line, tone: "plain" }]);
+}
+/**
+ * The detail view's content. The Agents section is left out when OpenCode's agents couldn't be
+ * read.
+ */
+export function toolDetail(tool, modelLabel, access) {
+    const detailsMissing = "OpenCode reported only this tool's name.";
+    return {
+        title: tool.id,
+        subtitle: modelLabel === undefined ? undefined : `As offered to ${modelLabel}`,
+        sections: [
+            {
+                heading: "Input",
+                lines: tool.description === undefined && tool.parameters === undefined
+                    ? muted(detailsMissing)
+                    : schemaLines(tool.parameters),
+            },
+            ...(access === undefined
+                ? []
+                : [{ heading: "Agents", lines: agentAccessLines(access) }]),
+            {
+                heading: "Description",
+                lines: tool.description === undefined
+                    ? muted(detailsMissing)
+                    : tool.description.trim() === ""
+                        ? muted("No description.")
+                        : textLines(tool.description),
+            },
+        ],
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,34 @@
+export interface ModelChoice {
+    providerID: string;
+    modelID: string;
+}
+/** Where the browsed model came from, since the next prompt may use another. */
+export type ModelSource = "session" | "configured" | "provider default";
+export interface ChosenModel extends ModelChoice {
+    source: ModelSource;
+}
+export interface BrowsableTool {
+    id: string;
+    /** Undefined when OpenCode reported only the tool's id. */
+    description: string | undefined;
+    parameters: unknown;
+}
+export declare function modelLabel(model: ModelChoice): string;
+export declare function chosenModelLabel(model: ChosenModel): string;
+/** The model of the session's latest user message, which OpenCode resolves tools for on the next prompt. */
+export declare function sessionModel(messages: readonly unknown[]): ModelChoice | undefined;
+/** Parses the `provider/model` form used by the `model` setting. */
+export declare function configuredModel(model: unknown): ModelChoice | undefined;
+/** The first connected provider's default model, which OpenCode falls back to when none is configured. */
+export declare function providerDefaultModel(connectedProviderIds: readonly string[], defaults: unknown): ModelChoice | undefined;
+/** Keeps well-formed entries from OpenCode's tool list, sorted by id. */
+export declare function toolsFromList(response: unknown): BrowsableTool[] | undefined;
+/** Tool ids without details, for when OpenCode can't resolve tools for a model. */
+export declare function toolsFromIds(response: unknown): BrowsableTool[] | undefined;
+/** The first line of a description without its list marker, short enough for one list row. */
+export declare function descriptionSummary(description: string | undefined): string;
+/**
+ * The number of top-level input properties, or undefined when the schema has none to count, such
+ * as a union beside empty `properties`.
+ */
+export declare function inputCount(parameters: unknown): number | undefined;

package/dist/tools.js

@@ -0,0 +1,119 @@
+const sourceLabels = {
+    session: "this session's model",
+    configured: "configured model",
+    "provider default": "provider default",
+};
+/** OpenCode's placeholder for unknown tool calls, never offered to agents as a real tool. */
+const internalToolIds = new Set(["invalid"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function modelLabel(model) {
+    return `${model.providerID}/${model.modelID}`;
+}
+export function chosenModelLabel(model) {
+    return `${modelLabel(model)} (${sourceLabels[model.source]})`;
+}
+/** The model of the session's latest user message, which OpenCode resolves tools for on the next prompt. */
+export function sessionModel(messages) {
+    for (const message of [...messages].reverse()) {
+        if (!isRecord(message) || message.role !== "user") {
+            continue;
+        }
+        const model = message.model;
+        if (isRecord(model) &&
+            typeof model.providerID === "string" &&
+            typeof model.modelID === "string" &&
+            model.providerID !== "" &&
+            model.modelID !== "") {
+            return { providerID: model.providerID, modelID: model.modelID };
+        }
+    }
+    return undefined;
+}
+/** Parses the `provider/model` form used by the `model` setting. */
+export function configuredModel(model) {
+    if (typeof model !== "string") {
+        return undefined;
+    }
+    const separator = model.indexOf("/");
+    if (separator <= 0 || separator === model.length - 1) {
+        return undefined;
+    }
+    return {
+        providerID: model.slice(0, separator),
+        modelID: model.slice(separator + 1),
+    };
+}
+/** The first connected provider's default model, which OpenCode falls back to when none is configured. */
+export function providerDefaultModel(connectedProviderIds, defaults) {
+    if (!isRecord(defaults)) {
+        return undefined;
+    }
+    for (const providerID of connectedProviderIds) {
+        const modelID = defaults[providerID];
+        if (typeof modelID === "string" && modelID !== "") {
+            return { providerID, modelID };
+        }
+    }
+    return undefined;
+}
+function byId(left, right) {
+    return left.id.localeCompare(right.id);
+}
+/** Keeps well-formed entries from OpenCode's tool list, sorted by id. */
+export function toolsFromList(response) {
+    if (!Array.isArray(response)) {
+        return undefined;
+    }
+    const tools = new Map();
+    for (const item of response) {
+        if (!isRecord(item) ||
+            typeof item.id !== "string" ||
+            item.id === "" ||
+            internalToolIds.has(item.id)) {
+            continue;
+        }
+        tools.set(item.id, {
+            id: item.id,
+            description: typeof item.description === "string" ? item.description : undefined,
+            parameters: item.parameters,
+        });
+    }
+    return [...tools.values()].sort(byId);
+}
+/** Tool ids without details, for when OpenCode can't resolve tools for a model. */
+export function toolsFromIds(response) {
+    if (!Array.isArray(response)) {
+        return undefined;
+    }
+    const ids = new Set(response.filter((id) => typeof id === "string" && id !== "" && !internalToolIds.has(id)));
+    return [...ids]
+        .map((id) => ({ id, description: undefined, parameters: undefined }))
+        .sort(byId);
+}
+const summaryLength = 100;
+/** The first line of a description without its list marker, short enough for one list row. */
+export function descriptionSummary(description) {
+    const firstLine = description
+        ?.split(/\r?\n/)
+        .map((line) => line.trim().replace(/^[-*•]\s+/, ""))
+        .find((line) => line !== "") ?? "";
+    return firstLine.length > summaryLength
+        ? `${firstLine.slice(0, summaryLength - 1).trimEnd()}…`
+        : firstLine;
+}
+/**
+ * The number of top-level input properties, or undefined when the schema has none to count, such
+ * as a union beside empty `properties`.
+ */
+export function inputCount(parameters) {
+    if (!isRecord(parameters) || !isRecord(parameters.properties)) {
+        return undefined;
+    }
+    const count = Object.keys(parameters.properties).length;
+    return count === 0 &&
+        (parameters.anyOf !== undefined || parameters.oneOf !== undefined)
+        ? undefined
+        : count;
+}