@humain/terminal 0.0.2 → 0.0.3-beta.0

package/dist/humain/mcp-adapter/vendor/tool-result-renderer.ts

@@ -0,0 +1,423 @@
+import type { AgentToolResult, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { type Component, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+type McpToolResultDetails = Record<string, unknown> & { error?: unknown };
+type McpToolContentBlock = AgentToolResult<McpToolResultDetails>["content"][number];
+
+interface RenderTheme {
+  fg: (name: string, text: string) => string;
+  bold?: (text: string) => string;
+}
+
+const plainTheme: RenderTheme = { fg: (_name, text) => text };
+
+export interface McpProxyToolCallInput {
+  tool?: string;
+  args?: string | Record<string, unknown>;
+  connect?: string;
+  describe?: string;
+  search?: string;
+  regex?: boolean;
+  includeSchemas?: boolean;
+  server?: string;
+  action?: string;
+}
+
+interface McpToolRenderState {
+  compactTitle?: string;
+}
+
+interface McpToolRenderContext {
+  isError: boolean;
+  isPartial?: boolean;
+  expanded?: boolean;
+  state?: McpToolRenderState;
+}
+
+export type McpToolResultRendering = "compact" | "boxed";
+
+export interface McpToolRenderOptions {
+  resultRendering: McpToolResultRendering;
+  collapsedResultLines: 1 | 2 | 3;
+}
+
+export interface McpToolRenderSettings {
+  toolResultRendering?: unknown;
+  collapsedResultLines?: unknown;
+}
+
+export interface McpToolResultDisplay {
+  lines: string[];
+  truncated: boolean;
+}
+
+const DEFAULT_MAX_CALL_INPUT_CHARS = 1500;
+const DEFAULT_BOXED_COLLAPSED_LINES = 3;
+const DEFAULT_COMPACT_COLLAPSED_LINES = 1;
+const DEFAULT_MAX_COLLAPSED_CHARS = 8000;
+const COLLAPSED_RENDER_CHAR_SLACK = 8;
+
+class EmptyComponent implements Component {
+  render(): string[] {
+    return [];
+  }
+
+  invalidate(): void {}
+}
+
+class CompactMcpToolResult implements Component {
+  private rendered: { width: number; lines: string[] } | null = null;
+
+  constructor(
+    private readonly title: string,
+    private readonly display: McpToolResultDisplay,
+    private readonly theme: RenderTheme,
+  ) {}
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(1, Math.floor(width));
+    if (this.rendered?.width === safeWidth) return this.rendered.lines;
+
+    const resultLines = this.display.lines.filter((line, index, lines) => {
+      return !(this.display.truncated && index === lines.length - 1 && line === "…");
+    });
+    const lines = resultLines.length > 0 ? resultLines : [""];
+    const bodies = lines.map((line, index) => {
+      const prefix = index === 0 && this.title ? `${this.theme.fg("toolTitle", this.title)} → ` : "";
+      return `${prefix}${this.theme.fg("toolOutput", line)}`;
+    });
+    const hiddenText = this.display.truncated || bodies.some((body) => visibleWidth(body) > safeWidth);
+    const rendered = bodies.map((body, index) => {
+      const suffix = hiddenText && index === bodies.length - 1 ? " … (Ctrl+O to expand)" : "";
+      if (!suffix) return truncateToWidth(body, safeWidth, "…");
+      if (safeWidth >= suffix.length + 20) {
+        return `${truncateToWidth(body, safeWidth - suffix.length, "…")}${this.theme.fg("muted", suffix)}`;
+      }
+      const shortSuffix = " (Ctrl+O)";
+      if (safeWidth >= shortSuffix.length + 5) {
+        return `${truncateToWidth(body, safeWidth - shortSuffix.length, "…")}${this.theme.fg("muted", shortSuffix)}`;
+      }
+      return truncateToWidth(this.theme.fg("muted", shortSuffix.trim()), safeWidth, "…");
+    });
+    this.rendered = { width: safeWidth, lines: rendered };
+    return rendered;
+  }
+
+  invalidate(): void {
+    this.rendered = null;
+  }
+}
+
+class CollapsibleText implements Component {
+  private readonly fullText: Text;
+  private readonly footerText: Text;
+  private collapsedText: { charBudget: number; fullyIncluded: boolean; text: Text } | null = null;
+  private collapsedRender: { width: number; charBudget: number; lines: string[] } | null = null;
+
+  constructor(
+    private readonly text: string,
+    private readonly expanded: boolean,
+    private readonly maxCollapsedLines: number,
+    ellipsis: string,
+    expandHint: string,
+    private readonly preTruncated = false,
+  ) {
+    this.fullText = new Text(text, 0, 0);
+    this.footerText = new Text(`${ellipsis}\n${expandHint}`, 0, 0);
+  }
+
+  render(width: number): string[] {
+    if (this.expanded) {
+      return this.fullText.render(width);
+    }
+
+    const safeWidth = Math.max(1, Math.floor(width));
+    const charBudget = safeWidth * (this.maxCollapsedLines + 1) * COLLAPSED_RENDER_CHAR_SLACK;
+    if (!this.collapsedText || this.collapsedText.charBudget !== charBudget) {
+      const prefix = this.text.length > charBudget
+        ? this.text.slice(0, charBudget)
+        : this.text;
+      this.collapsedText = {
+        charBudget,
+        fullyIncluded: prefix === this.text,
+        text: new Text(prefix, 0, 0),
+      };
+      this.collapsedRender = null;
+    }
+
+    const lines = this.collapsedText.text.render(width);
+    if (!this.preTruncated && this.collapsedText.fullyIncluded && lines.length <= this.maxCollapsedLines) return lines;
+    if (this.collapsedRender?.width === width && this.collapsedRender.charBudget === charBudget) {
+      return this.collapsedRender.lines;
+    }
+
+    const rendered = [
+      ...lines.slice(0, this.maxCollapsedLines),
+      ...this.footerText.render(width),
+    ];
+    this.collapsedRender = { width, charBudget, lines: rendered };
+    return rendered;
+  }
+
+  invalidate(): void {
+    this.fullText.invalidate();
+    this.footerText.invalidate();
+    this.collapsedText?.text.invalidate();
+    this.collapsedRender = null;
+  }
+}
+
+function truncateText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function formatJsonish(value: unknown, maxChars: number): string {
+  if (typeof value === "string") {
+    try {
+      return truncateText(JSON.stringify(JSON.parse(value), null, 2), maxChars);
+    } catch {
+      return truncateText(value, maxChars);
+    }
+  }
+
+  try {
+    return truncateText(JSON.stringify(value, null, 2), maxChars);
+  } catch {
+    return truncateText(String(value), maxChars);
+  }
+}
+
+function hasUsefulObjectContent(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+
+export function formatMcpProxyToolCallLines(
+  args: McpProxyToolCallInput,
+  maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS,
+): string[] {
+  if (args.action === "ui-messages") return [`mcp ${args.action}`];
+
+  if (args.tool) {
+    const target = args.server ? `${args.tool} @ ${args.server}` : args.tool;
+    const lines = [`mcp call ${target}`];
+    if (args.args) lines.push(formatJsonish(args.args, maxInputChars));
+    return lines;
+  }
+
+  if (args.connect) return [`mcp connect ${args.connect}`];
+  if (args.describe) return [`mcp describe ${args.describe}`];
+
+  if (args.search) {
+    let line = `mcp search ${args.search}`;
+    if (args.server) line += ` @ ${args.server}`;
+    if (args.regex === true) line += " (regex)";
+    if (args.includeSchemas === false) line += " (schemas hidden)";
+    return [line];
+  }
+
+  if (args.server) return [`mcp list ${args.server}`];
+  if (args.action) return [`mcp ${args.action}`];
+
+  return ["mcp status"];
+}
+
+export function formatMcpDirectToolCallLines(
+  displayName: string,
+  args: Record<string, unknown>,
+  maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS,
+): string[] {
+  if (!hasUsefulObjectContent(args)) return [displayName];
+  return [displayName, formatJsonish(args, maxInputChars)];
+}
+
+function renderToolCallLines(lines: string[], theme?: RenderTheme) {
+  const activeTheme = theme ?? plainTheme;
+  const [title = "mcp", ...rest] = lines;
+  const styledTitle = activeTheme.fg("toolTitle", activeTheme.bold ? activeTheme.bold(title) : title);
+  const styledRest = rest.map(line => activeTheme.fg("muted", line));
+  return new Text([styledTitle, ...styledRest].join("\n"), 0, 0);
+}
+
+export function resolveMcpToolRenderOptions(settings?: McpToolRenderSettings): McpToolRenderOptions {
+  const resultRendering = settings?.toolResultRendering === "boxed" ? "boxed" : "compact";
+  const collapsedLines = settings?.collapsedResultLines;
+  const defaultLines = resultRendering === "boxed" ? DEFAULT_BOXED_COLLAPSED_LINES : DEFAULT_COMPACT_COLLAPSED_LINES;
+  return {
+    resultRendering,
+    collapsedResultLines: collapsedLines === 1 || collapsedLines === 2 || collapsedLines === 3 ? collapsedLines : defaultLines,
+  };
+}
+
+function shouldUseCompactFinalRender(options: McpToolRenderOptions, context?: McpToolRenderContext): boolean {
+  return options.resultRendering === "compact"
+    && context !== undefined
+    && context.isPartial === false
+    && context.expanded !== true
+    && context.isError !== true;
+}
+
+function renderToolCall(
+  lines: string[],
+  theme: RenderTheme | undefined,
+  context: McpToolRenderContext | undefined,
+  options: McpToolRenderOptions,
+) {
+  if (context?.state) context.state.compactTitle = lines[0] ?? "mcp";
+  if (shouldUseCompactFinalRender(options, context)) return new EmptyComponent();
+  return renderToolCallLines(lines, theme);
+}
+
+export function renderMcpProxyToolCall(
+  args: McpProxyToolCallInput,
+  theme?: RenderTheme,
+  context?: McpToolRenderContext,
+) {
+  return renderToolCall(formatMcpProxyToolCallLines(args), theme, context, resolveMcpToolRenderOptions());
+}
+
+export function createMcpProxyToolCallRenderer(options: McpToolRenderOptions) {
+  return (args: McpProxyToolCallInput, theme?: RenderTheme, context?: McpToolRenderContext) => {
+    return renderToolCall(formatMcpProxyToolCallLines(args), theme, context, options);
+  };
+}
+
+export function createMcpDirectToolCallRenderer(displayName: string, options = resolveMcpToolRenderOptions()) {
+  return (args: Record<string, unknown>, theme?: RenderTheme, context?: McpToolRenderContext) => {
+    return renderToolCall(formatMcpDirectToolCallLines(displayName, args), theme, context, options);
+  };
+}
+
+function blockToLines(block: McpToolContentBlock): string[] {
+  if (block.type === "text") {
+    return block.text.split("\n");
+  }
+  return [`[image: ${block.mimeType}]`];
+}
+
+function collectCollapsedResultLines(
+  content: AgentToolResult<McpToolResultDetails>["content"],
+  maxLines: number,
+  maxChars: number,
+): McpToolResultDisplay {
+  if (content.length === 0) return { lines: ["(empty result)"], truncated: false };
+
+  const lines: string[] = [];
+  let remainingChars = maxChars;
+  let truncated = false;
+
+  const appendLine = (line: string) => {
+    if (lines.length >= maxLines || remainingChars <= 0) {
+      truncated = true;
+      return false;
+    }
+
+    if (line.length > remainingChars) {
+      lines.push(line.slice(0, remainingChars));
+      truncated = true;
+      remainingChars = 0;
+      return false;
+    }
+
+    lines.push(line);
+    remainingChars -= line.length + 1;
+    return true;
+  };
+
+  for (const block of content) {
+    if (block.type !== "text") {
+      if (!appendLine(`[image: ${block.mimeType}]`)) break;
+      continue;
+    }
+
+    let start = 0;
+    while (start <= block.text.length) {
+      const newline = block.text.indexOf("\n", start);
+      const line = newline === -1 ? block.text.slice(start) : block.text.slice(start, newline);
+      if (!appendLine(line)) break;
+      if (newline === -1) break;
+      start = newline + 1;
+    }
+
+    if (truncated) break;
+  }
+
+  if (lines.length === 0) lines.push("");
+  if (truncated && lines.length >= maxLines) lines.push("…");
+  return { lines, truncated };
+}
+
+export function formatMcpToolResultIdentity(details: McpToolResultDetails | undefined): string | null {
+  if (details?.mode !== "call") return null;
+  const server = typeof details.server === "string"
+    ? details.server
+    : typeof details.hintServer === "string"
+      ? details.hintServer
+      : null;
+  if (!server) return null;
+  if (typeof details.tool === "string") return `MCP ${server}/${details.tool}`;
+  if (typeof details.resourceUri === "string") return `MCP ${server} resource ${details.resourceUri}`;
+  if (typeof details.requestedTool === "string") return `MCP ${server}/${details.requestedTool}`;
+  return null;
+}
+
+export function formatMcpToolResultLines(
+  result: Pick<AgentToolResult<McpToolResultDetails>, "content">,
+  expanded: boolean,
+  maxCollapsedLines = DEFAULT_BOXED_COLLAPSED_LINES,
+  maxCollapsedChars = DEFAULT_MAX_COLLAPSED_CHARS,
+): McpToolResultDisplay {
+  if (!expanded) {
+    return collectCollapsedResultLines(result.content, maxCollapsedLines, maxCollapsedChars);
+  }
+
+  const allLines = result.content.flatMap(blockToLines);
+  const lines = allLines.length > 0 ? allLines : ["(empty result)"];
+  return { lines, truncated: false };
+}
+
+export function renderMcpToolResult(
+  result: AgentToolResult<McpToolResultDetails>,
+  options: ToolRenderResultOptions,
+  theme?: RenderTheme,
+  context?: McpToolRenderContext,
+  renderOptions = resolveMcpToolRenderOptions(),
+) {
+  const activeTheme = theme ?? plainTheme;
+  if (options.isPartial) {
+    return new Text(activeTheme.fg("warning", "Running MCP tool..."), 0, 0);
+  }
+
+  const hasErrorDetails = Boolean(result.details.error);
+  const expanded = options.expanded || context?.isError === true || hasErrorDetails;
+  if (!expanded && renderOptions.resultRendering === "compact") {
+    const display = formatMcpToolResultLines(result, false, renderOptions.collapsedResultLines);
+    const title = context?.state?.compactTitle ?? formatMcpToolResultIdentity(result.details) ?? "";
+    return new CompactMcpToolResult(title, display, activeTheme);
+  }
+
+  const display = formatMcpToolResultLines(result, expanded, renderOptions.collapsedResultLines);
+  const identity = formatMcpToolResultIdentity(result.details);
+  const output = [
+    ...(identity ? [activeTheme.fg("muted", identity)] : []),
+    ...display.lines.map((line) => activeTheme.fg("toolOutput", line)),
+  ].join("\n");
+
+  return new CollapsibleText(
+    output,
+    expanded,
+    renderOptions.collapsedResultLines + (identity ? 1 : 0),
+    activeTheme.fg("muted", "…"),
+    activeTheme.fg("muted", "(Ctrl+O to expand)"),
+    display.truncated,
+  );
+}
+
+export function createMcpToolResultRenderer(renderOptions: McpToolRenderOptions) {
+  return (
+    result: AgentToolResult<McpToolResultDetails>,
+    options: ToolRenderResultOptions,
+    theme?: RenderTheme,
+    context?: McpToolRenderContext,
+  ) => renderMcpToolResult(result, options, theme, context, renderOptions);
+}

package/dist/humain/mcp-adapter/vendor/ts-shape.ts

@@ -0,0 +1,149 @@
+type Schema = Record<string, unknown>;
+
+const UNSUPPORTED_KEYWORDS = ["if", "then", "else", "allOf", "not", "patternProperties", "additionalProperties"];
+
+/** Renders the useful JSON Schema subset as TypeScript, or null for unsupported schemas. */
+export function renderTsShape(inputSchema: unknown): string | null {
+  try {
+    if (!isSchema(inputSchema)) return null;
+
+    const definitions = new Map<string, Schema>();
+    for (const key of ["$defs", "definitions"]) {
+      const rawDefinitions = inputSchema[key];
+      if (rawDefinitions === undefined) continue;
+      if (!isSchema(rawDefinitions)) return null;
+      for (const [name, definition] of Object.entries(rawDefinitions)) {
+        if (!isSchema(definition)) return null;
+        definitions.set(`${key}/${decodePointerToken(name)}`, definition);
+      }
+    }
+
+    const aliases = new Map<string, string>();
+    const usedAliases = new Set<string>();
+    let aliasIndex = 0;
+    const aliasFor = (definitionKey: string) => {
+      let alias = aliases.get(definitionKey);
+      if (alias) return alias;
+      const name = definitionKey.slice(definitionKey.indexOf("/") + 1);
+      alias = /^[A-Za-z_$][\w$]*$/.test(name) && !usedAliases.has(name) ? name : `Definition${++aliasIndex}`;
+      while (usedAliases.has(alias)) alias = `Definition${++aliasIndex}`;
+      aliases.set(definitionKey, alias);
+      usedAliases.add(alias);
+      return alias;
+    };
+
+    const render = (schema: unknown): string | null => {
+      if (!isSchema(schema) || hasUnsupportedKeyword(schema)) return null;
+
+      if ("$ref" in schema) {
+        if (typeof schema.$ref !== "string") return null;
+        const match = schema.$ref.match(/^#\/(\$defs|definitions)\/([^/]+)$/);
+        if (!match) return null;
+        const definitionGroup = match[1];
+        const definitionName = match[2];
+        if (definitionGroup === undefined || definitionName === undefined) return null;
+        const definitionKey = `${definitionGroup}/${decodePointerToken(definitionName)}`;
+        if (!definitions.has(definitionKey)) return null;
+        return aliasFor(definitionKey);
+      }
+
+      if (Array.isArray(schema.enum)) {
+        const values = schema.enum.map(renderLiteral);
+        return values.every((value): value is string => value !== null) ? values.join(" | ") : null;
+      }
+      if (Object.hasOwn(schema, "const")) return renderLiteral(schema.const);
+
+      if (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf)) {
+        const variants = (schema.anyOf ?? schema.oneOf) as unknown[];
+        if (variants.length === 0) return null;
+        const rendered = variants.map(render);
+        return rendered.every((value): value is string => value !== null) ? rendered.join(" | ") : null;
+      }
+
+      if (schema.type === "object" || schema.properties !== undefined) {
+        if (schema.properties === undefined) return "{}";
+        if (!isSchema(schema.properties)) return null;
+        const required = new Set(Array.isArray(schema.required)
+          ? schema.required.filter((name): name is string => typeof name === "string")
+          : []);
+        const properties: string[] = [];
+        for (const [name, property] of Object.entries(schema.properties)) {
+          const rendered = render(property);
+          if (rendered === null) return null;
+          properties.push(`${formatPropertyName(name)}${required.has(name) ? "" : "?"}: ${rendered};`);
+        }
+        return properties.length === 0 ? "{}" : `{ ${properties.join(" ")} }`;
+      }
+
+      if (schema.type === "array") {
+        if (schema.items === undefined) return "unknown[]";
+        const item = render(schema.items);
+        return item === null ? null : `${needsParentheses(item) ? `(${item})` : item}[]`;
+      }
+
+      if (Array.isArray(schema.type)) {
+        const types = schema.type.map(renderType);
+        return types.every((type): type is string => type !== null) ? types.join(" | ") : null;
+      }
+      if (typeof schema.type === "string") return renderType(schema.type);
+      return "unknown";
+    };
+
+    const root = render(inputSchema);
+    if (root === null) return null;
+
+    const definitionsText: string[] = [];
+    for (const [key, alias] of aliases) {
+      const definition = definitions.get(key);
+      if (!definition) return null;
+      const rendered = render(definition);
+      if (rendered === null) return null;
+      definitionsText.push(`type ${alias} = ${rendered};`);
+    }
+    return definitionsText.length > 0 ? `${definitionsText.join("\n")}\n\n${root}` : root;
+  } catch {
+    return null;
+  }
+}
+
+function isSchema(value: unknown): value is Schema {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasUnsupportedKeyword(schema: Schema): boolean {
+  return UNSUPPORTED_KEYWORDS.some(keyword => {
+    if (!Object.hasOwn(schema, keyword)) return false;
+    // `additionalProperties: false` is a closed-object constraint, not a shape that this renderer needs to understand.
+    return keyword !== "additionalProperties" || schema.additionalProperties !== false;
+  });
+}
+
+function decodePointerToken(token: string): string {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function renderType(type: unknown): string | null {
+  switch (type) {
+    case "string": return "string";
+    case "number":
+    case "integer": return "number";
+    case "boolean": return "boolean";
+    case "null": return "null";
+    case "object": return "{}";
+    case "array": return "unknown[]";
+    default: return null;
+  }
+}
+
+function renderLiteral(value: unknown): string | null {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  return typeof value === "number" && Number.isFinite(value) ? String(value) : null;
+}
+
+function formatPropertyName(name: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+function needsParentheses(type: string): boolean {
+  return type.includes(" | ");
+}