@narumitw/pi-inspect 0.1.0 → 0.2.1

package/src/web/tool-inspector.css

@@ -0,0 +1,175 @@
+.tool-inspector {
+  container-type: inline-size;
+  font:
+    11px / 1.5 Consolas,
+    "SFMono-Regular",
+    monospace;
+  min-width: 0;
+}
+.tool-browser {
+  display: grid;
+  grid-template-columns: minmax(130px, 30%) minmax(0, 1fr);
+  gap: 10px;
+}
+.tool-navigation {
+  min-width: 0;
+  border-right: 1px solid var(--panel-border);
+  padding-right: 8px;
+}
+.tool-navigation input {
+  width: 100%;
+  min-width: 0;
+  padding: 5px 7px;
+  border: 1px solid var(--panel-border);
+  border-radius: 4px;
+  background: var(--panel-bg);
+  color: inherit;
+}
+.tool-list {
+  display: grid;
+  gap: 3px;
+  max-height: 320px;
+  overflow-y: auto;
+  margin-top: 6px;
+}
+.tool-list button {
+  text-align: left;
+  border: 0;
+  border-left: 2px solid transparent;
+  border-radius: 3px;
+  background: transparent;
+  color: inherit;
+  padding: 5px 7px;
+  min-width: 0;
+}
+.tool-list button:hover {
+  background: var(--surface-hover);
+}
+.tool-list button[aria-pressed="true"] {
+  background: var(--selected-bg);
+  border-left-color: var(--accent-9);
+}
+.tool-list strong {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  overflow-wrap: anywhere;
+}
+.tool-list span {
+  display: block;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--secondary);
+}
+.tool-documentation {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+.tool-heading {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+  gap: 8px;
+}
+.tool-inspector .copy-button {
+  margin: 0;
+  flex-shrink: 0;
+}
+.tool-heading h3 {
+  min-width: 0;
+  margin: 0 0 6px;
+  font-size: 14px;
+}
+.tool-documentation h4 {
+  margin: 12px 0 4px;
+  font-size: 11px;
+}
+.tool-prose {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  margin: 8px 0;
+}
+.tool-muted,
+.schema-annotation {
+  color: var(--secondary);
+}
+.tool-documentation pre {
+  max-width: 100%;
+  overflow-x: auto;
+  white-space: pre;
+  padding: 7px;
+  border: 1px solid var(--panel-border);
+  border-radius: 3px;
+  background: var(--code-bg);
+  font: inherit;
+}
+.schema-scroll {
+  max-width: 100%;
+  overflow-x: auto;
+}
+.parameter-schema {
+  width: 100%;
+  min-width: 400px;
+  border-collapse: collapse;
+  table-layout: fixed;
+  font-size: 10px;
+}
+.parameter-schema caption {
+  text-align: left;
+  font-weight: bold;
+  padding: 8px 0 4px;
+}
+.parameter-schema th,
+.parameter-schema td {
+  text-align: left;
+  vertical-align: top;
+  padding: 6px 5px;
+  border-bottom: 1px solid var(--panel-border);
+  overflow-wrap: anywhere;
+}
+.parameter-schema thead {
+  color: var(--secondary);
+  background: var(--code-bg);
+}
+.parameter-schema th:nth-child(1) {
+  width: 25%;
+}
+.parameter-schema th:nth-child(2) {
+  width: 18%;
+}
+.parameter-schema th:nth-child(3) {
+  width: 16%;
+}
+.parameter-schema code {
+  font: inherit;
+}
+.schema-type {
+  color: var(--accent-11);
+}
+.schema-toggle {
+  text-align: left;
+  padding: 0;
+  border: 0;
+  color: inherit;
+  background: transparent;
+  font-weight: inherit;
+  overflow-wrap: anywhere;
+}
+.parameter-schema .tool-prose {
+  margin: 0 0 3px;
+}
+@container (max-width: 540px) {
+  .tool-browser {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .tool-navigation {
+    border-right: 0;
+    border-bottom: 1px solid var(--panel-border);
+    padding: 0 0 8px;
+  }
+  .tool-list {
+    max-height: 145px;
+  }
+}

package/src/web/tool-inspector.tsx

@@ -0,0 +1,210 @@
+import { Fragment, useMemo, useState } from "react";
+import type { Capture, Json } from "../model.js";
+import { Copy, Data } from "./components.js";
+import { output } from "./format.js";
+import { parseSchema, type SchemaNode, type ToolDoc, toolDocuments } from "./tool-schema.js";
+
+function DocumentationText({ value }: { value: string }) {
+  const parts = useMemo(() => {
+    const parts: { id: string; text: string; code: boolean }[] = [];
+    let offset = 0;
+    for (const match of value.matchAll(/^```[^\n]*\n([\s\S]*?)^```[ \t]*(?:\n|$)/gm)) {
+      parts.push({ id: `text-${offset}`, text: value.slice(offset, match.index), code: false });
+      parts.push({ id: `code-${match.index}`, text: match[1] ?? "", code: true });
+      offset = match.index + match[0].length;
+    }
+    parts.push({ id: `text-${offset}`, text: value.slice(offset), code: false });
+    return parts;
+  }, [value]);
+  return parts.map((part) =>
+    part.code ? (
+      <pre key={part.id}>{part.text}</pre>
+    ) : (
+      <div key={part.id} className="tool-prose">
+        {part.text}
+      </div>
+    ),
+  );
+}
+
+function SchemaRows({ node, depth = 0 }: { node: SchemaNode; depth?: number }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Fragment>
+      <tr>
+        <th scope="row" style={{ paddingLeft: `${8 + Math.min(depth, 8) * 12}px` }}>
+          {node.children.length ? (
+            <button type="button" className="schema-toggle" aria-expanded={open} onClick={() => setOpen(!open)}>
+              <span aria-hidden="true">{open ? "▾" : "▸"}</span> {node.name}
+            </button>
+          ) : (
+            node.name
+          )}
+        </th>
+        <td>
+          <code className="schema-type">{node.type}</code>
+        </td>
+        <td
+          title={
+            node.required === "unknown"
+              ? "Other schema constraints or documentation limits may require this field; inspect the schema branches or Raw JSON."
+              : undefined
+          }
+        >
+          {node.required === undefined ? "—" : node.required === "unknown" ? "Unknown" : node.required ? "Yes" : "No"}
+        </td>
+        <td>
+          {node.description && <div className="tool-prose">{node.description}</div>}
+          {node.annotations.map(([key, value]) => (
+            <div className="schema-annotation" key={key}>
+              <span>{key}: </span>
+              <code>{JSON.stringify(value)}</code>
+            </div>
+          ))}
+          {node.limited && (
+            <p role="status">Documentation limit reached; inspect Raw JSON for the complete captured schema.</p>
+          )}
+        </td>
+      </tr>
+      {open && node.children.map((child) => <SchemaRows key={child.id} node={child} depth={depth + 1} />)}
+    </Fragment>
+  );
+}
+export function ParameterSchema({ value }: { value: Json }) {
+  const root = useMemo(() => parseSchema(value), [value]);
+  return (
+    <div className="schema-scroll">
+      <table className="parameter-schema">
+        <caption>Input parameters</caption>
+        <thead>
+          <tr>
+            <th scope="col">Parameter</th>
+            <th scope="col">Type</th>
+            <th scope="col">Required</th>
+            <th scope="col">Description / constraints</th>
+          </tr>
+        </thead>
+        <tbody>
+          <SchemaRows node={{ ...root, children: [] }} />
+          {root.children.map((node) => (
+            <SchemaRows key={node.id} node={node} />
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+function ToolDetails({ tool, scope, truncated }: { tool: ToolDoc; scope: string; truncated: boolean }) {
+  const [mode, setMode] = useState("documentation");
+  return (
+    <section className="tool-documentation" aria-label="Selected tool documentation">
+      <div className="tool-heading">
+        <h3>{tool.name}</h3>
+        <Copy key={JSON.stringify(tool.raw)} value={JSON.stringify(tool.raw, null, 2)} />
+      </div>
+      <div className="view-switch">
+        {["documentation", "raw"].map((value) => (
+          <button type="button" key={value} aria-pressed={mode === value} onClick={() => setMode(value)}>
+            {value === "raw" ? "Raw JSON" : "Documentation"}
+          </button>
+        ))}
+      </div>
+      {mode === "raw" ? (
+        <Data
+          label="Original captured tool declaration"
+          data={{ value: tool.raw, truncated }}
+          scope={`${scope}-tool-${tool.id}`}
+        />
+      ) : (
+        <>
+          {tool.description ? (
+            <DocumentationText value={tool.description} />
+          ) : (
+            <p className="tool-muted">No description supplied.</p>
+          )}
+          {tool.parameters === undefined ? (
+            <p className="tool-muted">Input schema unspecified.</p>
+          ) : (
+            <ParameterSchema value={tool.parameters} />
+          )}
+          {tool.returns !== undefined && (
+            <section>
+              <h4>Returns</h4>
+              <p className="tool-muted">Declared or documented return information; not an inferred output schema.</p>
+              <pre>{output(tool.returns)}</pre>
+            </section>
+          )}
+          {tool.codemode && (
+            <section>
+              <h4>Codemode</h4>
+              <DocumentationText value={tool.codemode} />
+            </section>
+          )}
+          {tool.examples.length > 0 && (
+            <section>
+              <h4>Declared examples</h4>
+              {tool.examples.map((example) => (
+                <div key={example.id}>
+                  <Copy key={JSON.stringify(example.value)} value={JSON.stringify(example.value, null, 2)} />
+                  <pre>{JSON.stringify(example.value, null, 2)}</pre>
+                </div>
+              ))}
+            </section>
+          )}
+        </>
+      )}
+    </section>
+  );
+}
+export function ToolInspector({ data, scope }: { data?: Capture; scope: string }) {
+  const tools = useMemo(() => toolDocuments(data?.value), [data?.value]);
+  const [query, setQuery] = useState("");
+  const [selected, setSelected] = useState<number>();
+  const filtered = useMemo(() => {
+    const search = query.trim().toLocaleLowerCase();
+    return tools.filter((tool) =>
+      `${tool.name}\n${tool.description}\n${tool.codemode}`.toLocaleLowerCase().includes(search),
+    );
+  }, [tools, query]);
+  const tool = filtered.find((tool) => tool.id === selected) ?? filtered[0];
+  if (!data || !Array.isArray(data.value))
+    return <Data label="Historical declared tools · preview branch" data={data} scope={scope} />;
+  return (
+    <section className="tool-inspector" aria-label="Historical declared tools">
+      <p className="tool-muted">Historical declared tools · preview branch · {tools.length} tools</p>
+      {data.truncated && (
+        <p role="status">
+          Captured declarations are truncated. Documentation and Raw JSON show only the available display copy.
+        </p>
+      )}
+      <div className="tool-browser">
+        <nav className="tool-navigation" aria-label="Declared tools">
+          <input
+            type="search"
+            aria-label="Search tools"
+            placeholder="Search tools…"
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+          />
+          <div className="tool-list">
+            {filtered.map((item) => (
+              <button
+                type="button"
+                key={item.id}
+                aria-pressed={tool?.id === item.id}
+                onClick={() => setSelected(item.id)}
+              >
+                <strong>{item.name}</strong>
+                <span>{item.description.split("\n")[0] || "No description supplied"}</span>
+              </button>
+            ))}
+          </div>
+          {!filtered.length && (
+            <p className="tool-muted">{tools.length ? "No matching tools." : "No declared tools."}</p>
+          )}
+        </nav>
+        {tool && <ToolDetails key={`${scope}:${tool.id}`} tool={tool} scope={scope} truncated={data.truncated} />}
+      </div>
+    </section>
+  );
+}

package/src/web/tool-schema.ts

@@ -0,0 +1,217 @@
+import type { Json } from "../model.js";
+import { record } from "./format.js";
+
+export interface SchemaNode {
+  id: string;
+  name: string;
+  type: string;
+  required?: boolean | "unknown";
+  description: string;
+  annotations: [string, Json][];
+  children: SchemaNode[];
+  limited: boolean;
+}
+const structural = new Set([
+  "type",
+  "description",
+  "properties",
+  "required",
+  "items",
+  "prefixItems",
+  "additionalProperties",
+  "patternProperties",
+  "anyOf",
+  "oneOf",
+  "allOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "$defs",
+  "definitions",
+]);
+function schemaType(value: Json): string {
+  if (value === true) return "any";
+  if (value === false) return "never";
+  const schema = record(value);
+  if (!schema) return "unspecified";
+  if (typeof schema.type === "string") return schema.type;
+  if (Array.isArray(schema.type)) return schema.type.filter((type) => typeof type === "string").join(" | ");
+  if (schema.$ref) return "reference";
+  if (schema.anyOf || schema.oneOf || schema.allOf) return "composition";
+  return "unspecified";
+}
+
+interface RequiredProperties {
+  names: Set<string>;
+  unresolved: boolean;
+}
+// Resolve only unconditional required/allOf declarations at the same instance.
+// References and other assertions can require fields; their absence from a local
+// required array is not sufficient evidence to label a parameter optional.
+function requiredProperties(value: Json, depth = 0, budget = { remaining: 2000 }): RequiredProperties {
+  const schema = record(value);
+  const names = new Set(
+    Array.isArray(schema?.required) ? schema.required.filter((name): name is string => typeof name === "string") : [],
+  );
+  if (--budget.remaining < 0 || depth >= 32) return { names, unresolved: true };
+  if (!schema) return { names, unresolved: value !== true };
+  let unresolved = [
+    "$ref",
+    "$dynamicRef",
+    "$recursiveRef",
+    "anyOf",
+    "oneOf",
+    "not",
+    "if",
+    "then",
+    "else",
+    "dependentRequired",
+    "dependentSchemas",
+    "dependencies",
+    "minProperties",
+    "const",
+    "enum",
+  ].some((keyword) => schema[keyword] !== undefined);
+  if (schema.required !== undefined && !Array.isArray(schema.required)) unresolved = true;
+  if (schema.allOf !== undefined) {
+    if (!Array.isArray(schema.allOf)) unresolved = true;
+    else
+      for (const part of schema.allOf) {
+        const child = requiredProperties(part, depth + 1, budget);
+        for (const name of child.names) names.add(name);
+        unresolved ||= child.unresolved;
+        if (budget.remaining <= 0) {
+          unresolved = true;
+          break;
+        }
+      }
+  }
+  return { names, unresolved };
+}
+
+// Limit documentation work, never the stored declaration. Keep references and
+// composition branches explicit rather than rewriting or flattening the schema.
+export function parseSchema(value: Json): SchemaNode {
+  let remaining = 2000;
+  function parse(
+    value: Json,
+    name: string,
+    required?: SchemaNode["required"],
+    depth = 0,
+    inherited?: RequiredProperties,
+  ): SchemaNode {
+    const schema = record(value);
+    const node: SchemaNode = {
+      id: `${remaining}:${name}`,
+      name,
+      type: schemaType(value),
+      required,
+      description: typeof schema?.description === "string" ? schema.description : "",
+      annotations: [],
+      children: [],
+      limited: false,
+    };
+    if (--remaining < 0 || depth >= 32) {
+      node.limited = true;
+      return node;
+    }
+    if (!schema) {
+      if (typeof value !== "boolean") node.annotations.push(["Unrecognized schema", value]);
+      return node;
+    }
+    node.annotations = Object.entries(schema).filter(([key]) => !structural.has(key));
+    const requirements = requiredProperties(value);
+    if (inherited) {
+      for (const name of inherited.names) requirements.names.add(name);
+      requirements.unresolved ||= inherited.unresolved;
+    }
+    function child(value: Json, label: string, required?: SchemaNode["required"], inherited?: RequiredProperties) {
+      if (remaining <= 0) {
+        node.limited = true;
+        return;
+      }
+      node.children.push(parse(value, label, required, depth + 1, inherited));
+    }
+    for (const [key, property] of Object.entries(record(schema.properties) ?? {})) {
+      child(property, key, requirements.names.has(key) ? true : requirements.unresolved ? "unknown" : false);
+    }
+    if (schema.required !== undefined) node.annotations.push(["required", schema.required]);
+    for (const keyword of ["patternProperties", "$defs", "definitions"]) {
+      for (const [key, property] of Object.entries(record(schema[keyword]) ?? {}))
+        child(property, `${keyword}: ${key}`);
+    }
+    for (const keyword of ["items", "prefixItems", "anyOf", "oneOf", "allOf"]) {
+      const part = schema[keyword];
+      if (part === undefined) continue;
+      if (Array.isArray(part))
+        part.forEach((item, index) => {
+          child(
+            item,
+            `${keyword} [${index + 1}]`,
+            undefined,
+            ["allOf", "anyOf", "oneOf"].includes(keyword) ? requirements : undefined,
+          );
+        });
+      else child(part, keyword === "items" ? "items []" : keyword);
+    }
+    for (const keyword of ["additionalProperties", "not", "if", "then", "else"]) {
+      if (schema[keyword] !== undefined)
+        child(schema[keyword], keyword, undefined, ["if", "then", "else"].includes(keyword) ? requirements : undefined);
+    }
+    return node;
+  }
+  return parse(value, "Input");
+}
+
+function documentedReturn(codemode: string): string | undefined {
+  const result = /\btools\.[\w$]+\(args\)`? resolves to[ \t]+([^\n]+)(?:\n|$)/.exec(codemode);
+  let type = result?.[1]?.trim().replace(/\.$/, "");
+  if (type?.startsWith("`")) {
+    if (!type.endsWith("`") || type.length < 2) return undefined;
+    type = type.slice(1, -1);
+  } else type = type?.replace(/`$/, "");
+  if (!type || /[|&,:]$/.test(type)) return undefined;
+  // A wrapped/incomplete type is still readable in Codemode documentation, but
+  // must not be presented as a complete return declaration.
+  for (const [open, close] of [
+    ["{", "}"],
+    ["[", "]"],
+    ["(", ")"],
+  ] as const) {
+    if (type.split(open).length !== type.split(close).length) return undefined;
+  }
+  return type;
+}
+
+export interface ToolDoc {
+  id: number;
+  name: string;
+  description: string;
+  codemode: string;
+  returns?: Json;
+  parameters?: Json;
+  examples: { id: string; value: Json }[];
+  raw: Json;
+}
+export function toolDocuments(value: Json | undefined): ToolDoc[] {
+  if (!Array.isArray(value)) return [];
+  return value.map((raw, id) => {
+    const tool = record(raw);
+    const description = typeof tool?.description === "string" ? tool.description : "";
+    const marker = /(?:^|\n)[ \t]*Codemode:[ \t]*/i.exec(description);
+    const codemode = marker ? description.slice(marker.index + marker[0].length).trim() : "";
+    return {
+      id,
+      name: typeof tool?.name === "string" && tool.name ? tool.name : `Unnamed tool ${id + 1}`,
+      description: marker ? description.slice(0, marker.index).trimEnd() : description,
+      codemode,
+      returns: tool?.outputSchema ?? tool?.returnType ?? documentedReturn(codemode),
+      parameters: tool?.parameters ?? tool?.inputSchema,
+      examples: Array.isArray(tool?.examples)
+        ? tool.examples.map((value, index) => ({ id: `example-${index}`, value }))
+        : [],
+      raw,
+    };
+  });
+}

package/src/web/trace.css

@@ -148,6 +148,7 @@
   flex-shrink: 0;
 }
 .row-title > span {
+  max-width: 100%;
   color: var(--secondary);
   text-overflow: ellipsis;
   overflow: hidden;