@oqtopus-team/pi-qdash 0.1.2 → 0.1.3

package/README.md

@@ -71,6 +71,7 @@ See [Development Guide](./docs/DEVELOPMENT.md) for the fork workflow, local test
 
 ## Documentation
 
+- [Architecture](./docs/ARCHITECTURE.md)
 - [Tool Reference](./docs/tools.md)
 - [Commands & Skills](./docs/commands.md)
 - [Development Guide](./docs/DEVELOPMENT.md)

package/extensions/lib/figure-analysis.ts

@@ -0,0 +1,112 @@
+type PlotlyTrace = Record<string, unknown>;
+
+export type FigureAnalysis = {
+  path: string;
+  taskId?: string;
+  traceCount: number;
+  summaries: string[];
+  warnings: string[];
+};
+
+function numericArray(value: unknown): number[] {
+  return Array.isArray(value) ? value.filter((item): item is number => typeof item === "number" && Number.isFinite(item)) : [];
+}
+
+function numericMatrix(value: unknown): number[][] {
+  return Array.isArray(value)
+    ? value.map((row) => numericArray(row)).filter((row) => row.length > 0)
+    : [];
+}
+
+function matrixValue(matrix: number[][], row: number, column: number): number | undefined {
+  return matrix[row]?.[column];
+}
+
+function formatNumber(value: number): string {
+  const abs = Math.abs(value);
+  if (abs >= 1000 || (abs > 0 && abs < 0.001)) return value.toExponential(2);
+  if (abs >= 100) return value.toFixed(1);
+  if (abs >= 10) return value.toFixed(3);
+  return value.toFixed(5).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function formatMaybeNumber(value: number | undefined): string {
+  return typeof value === "number" && Number.isFinite(value) ? formatNumber(value) : "n/a";
+}
+
+function compactStats(values: number[]): string {
+  if (!values.length) return "no numeric values";
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  return `n=${values.length} min=${formatNumber(min)} max=${formatNumber(max)} mean=${formatNumber(mean)}`;
+}
+
+function boxed(title: string, body: string[]): string[] {
+  const rawLines = [` ${title} `, ...body];
+  const width = Math.min(100, Math.max(...rawLines.map((line) => line.length), title.length + 4));
+  const top = `╭${` ${title} `.padEnd(width, "─")}╮`;
+  const bottom = `╰${"─".repeat(width)}╯`;
+  const middle = body.map((line) => `│ ${line.padEnd(width - 2)} │`);
+  return [top, ...middle, bottom];
+}
+
+export function analyzePlotlyFigure(path: string, figure: unknown, taskId?: string): FigureAnalysis {
+  const object = figure && typeof figure === "object" ? figure as Record<string, unknown> : {};
+  const traces = Array.isArray(object.data) ? object.data.filter((trace): trace is PlotlyTrace => Boolean(trace) && typeof trace === "object") : [];
+  const summaries: string[] = [];
+  const warnings: string[] = [];
+
+  traces.forEach((trace, index) => {
+    const type = typeof trace.type === "string" ? trace.type : "unknown";
+    const name = typeof trace.name === "string" ? trace.name : `trace ${index}`;
+    if (type === "scatter" || Array.isArray(trace.y)) {
+      const y = numericArray(trace.y);
+      const x = numericArray(trace.x);
+      const err = trace.error_y && typeof trace.error_y === "object" ? (trace.error_y as Record<string, unknown>).value : undefined;
+      summaries.push(`${index}: scatter ${name} y(${compactStats(y)}) first=${formatMaybeNumber(y[0])} last=${formatMaybeNumber(y[y.length - 1])}${typeof err === "number" ? ` err=${formatNumber(err)}` : ""}`);
+      if (y.length >= 5) {
+        const tail = y.slice(Math.floor(y.length / 2));
+        const tailSpan = Math.max(...tail) - Math.min(...tail);
+        if (tailSpan > 0.4) warnings.push(`scatter ${name}: late repetitions still have large span ${formatNumber(tailSpan)}; repeated-pulse response may be unstable`);
+        const firstStep = Math.abs((y[1] ?? y[0]) - y[0]);
+        if (firstStep > 0.6 && Math.abs(y[y.length - 1]) > 0.1) warnings.push(`scatter ${name}: large first-step contrast but non-zero final offset ${formatNumber(y[y.length - 1])}`);
+      }
+      if (x.length && y.length && x.length !== y.length) warnings.push(`scatter ${name}: x/y length mismatch ${x.length}/${y.length}`);
+      return;
+    }
+
+    if (type === "heatmap" || Array.isArray(trace.z)) {
+      const z = numericMatrix(trace.z);
+      const flat = z.flat();
+      summaries.push(`${index}: heatmap ${z.length}x${z[0]?.length ?? 0} z(${compactStats(flat)})`);
+      if (z.length === 4 && z.every((row) => row.length === 4)) {
+        const diag = [0, 1, 2, 3].map((i) => z[i][i]);
+        const pop10 = diag[2];
+        const coh0011Re = matrixValue(z, 0, 3);
+        summaries.push(`   4x4 diag=[${diag.map(formatNumber).join(", ")}]  z00,11=${formatMaybeNumber(coh0011Re)}`);
+        if (pop10 > 0.15) warnings.push(`4x4 heatmap: |10> population/component is high (${formatNumber(pop10)}); suspect Bell/Zx angle, phase, or cancel error`);
+      }
+      return;
+    }
+
+    summaries.push(`${index}: ${type}`);
+  });
+
+  if (!traces.length) warnings.push("no Plotly data traces found");
+  return { path, taskId, traceCount: traces.length, summaries, warnings };
+}
+
+export function figureAnalysisText(analysis: FigureAnalysis): string {
+  return boxed("QDash Figure Analysis", [
+    `path ${analysis.path}`,
+    ...(analysis.taskId ? [`task ${analysis.taskId}`] : []),
+    `traces ${analysis.traceCount}`,
+    "",
+    "Summaries",
+    ...analysis.summaries.map((line) => `  - ${line}`),
+    "",
+    "Warnings",
+    ...(analysis.warnings.length ? analysis.warnings.map((line) => `  - ${line}`) : ["  - none"]),
+  ]).join("\n");
+}

package/extensions/lib/figures.ts

@@ -0,0 +1,78 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Image, truncateToWidth } from "@earendil-works/pi-tui";
+import type { QDashClient } from "@oqtopus-team/qdash-client";
+
+export type FigureDetails = {
+  tool: string;
+  path: string;
+  mediaType: string;
+  sizeBytes: number;
+  base64?: string;
+  text?: string;
+  taskId?: string;
+  figurePaths?: string[];
+  jsonFigurePaths?: string[];
+};
+
+export function mediaTypeForPath(path: string): string {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".json")) return "application/json";
+  return "application/octet-stream";
+}
+
+export async function fetchFigureDetails(client: QDashClient, path: string): Promise<FigureDetails> {
+  const file = await client.getExecutionFigure(path);
+  const bytes = Buffer.from(file.data);
+  const mediaType = file.mediaType || mediaTypeForPath(path);
+  const details: FigureDetails = {
+    tool: "qdash_get_figure",
+    path,
+    mediaType,
+    sizeBytes: bytes.byteLength,
+  };
+  if (mediaType.startsWith("image/")) details.base64 = bytes.toString("base64");
+  else details.text = bytes.toString("utf8");
+  return details;
+}
+
+function boxed(title: string, body: string[]): string[] {
+  const rawLines = [` ${title} `, ...body];
+  const width = Math.min(100, Math.max(...rawLines.map((line) => line.length), title.length + 4));
+  const top = `╭${` ${title} `.padEnd(width, "─")}╮`;
+  const bottom = `╰${"─".repeat(width)}╯`;
+  const middle = body.map((line) => `│ ${line.padEnd(width - 2)} │`);
+  return [top, ...middle, bottom];
+}
+
+export function figureResultText(details: FigureDetails): string {
+  const lines = boxed("QDash Figure", [
+    `path ${details.path}`,
+    `type ${details.mediaType}`,
+    `size ${details.sizeBytes} bytes`,
+    ...(details.taskId ? [`task ${details.taskId}`] : []),
+    ...(details.figurePaths?.length ? [`figures ${details.figurePaths.length}`] : []),
+    ...(details.jsonFigurePaths?.length ? [`json figures ${details.jsonFigurePaths.length}`] : []),
+    ...(details.text ? ["", ...details.text.split("\n").slice(0, 12).map((line) => `  ${line}`)] : []),
+  ]);
+  return lines.join("\n");
+}
+
+function textComponent(lines: string[]) {
+  return {
+    render(width: number) {
+      return lines.map((line) => truncateToWidth(line, width));
+    },
+    invalidate() {},
+  };
+}
+
+export function figureComponent(details: FigureDetails, theme: Theme) {
+  if (details.base64 && details.mediaType.startsWith("image/")) {
+    return new Image(details.base64, details.mediaType, { fallbackColor: (text: string) => theme.fg("dim", text) }, { maxWidthCells: 90, maxHeightCells: 30 });
+  }
+  return textComponent(figureResultText(details).split("\n"));
+}

package/extensions/lib/forum-render.ts

@@ -0,0 +1,152 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import { firstNumber, firstString, payloadTotal } from "./payload.js";
+import { ansi, boxed, boxLinesToWidth } from "./render.js";
+
+function shortId(value: string, length = 10): string {
+  return value.length > length ? `${value.slice(0, length)}…` : value;
+}
+
+export function forumPostsFromPayload(payload: unknown): Record<string, unknown>[] {
+  if (Array.isArray(payload)) return payload.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object");
+  if (payload && typeof payload === "object") {
+    const object = payload as Record<string, unknown>;
+    for (const key of ["posts", "items", "results", "data"]) {
+      if (Array.isArray(object[key])) return object[key].filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object");
+    }
+  }
+  return [];
+}
+
+function forumPostId(post: Record<string, unknown>): string {
+  return firstString(post, ["post_id", "id", "forum_post_id"]) ?? "unknown";
+}
+
+export function forumPostTitle(post: Record<string, unknown>): string {
+  return firstString(post, ["title", "subject", "summary"]) ?? firstString(post, ["content", "body", "text"])?.slice(0, 60) ?? "(untitled)";
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+function forumPostLine(post: Record<string, unknown>): string {
+  const number = firstNumber(post, ["number"]);
+  const id = shortId(forumPostId(post), 10);
+  const title = forumPostTitle(post);
+  const status = firstString(post, ["status"]);
+  const category = firstString(post, ["category"]);
+  const targetType = firstString(post, ["target_type"]);
+  const target = firstString(post, ["target_id", "chip_id", "task_id", "qid"]);
+  const replies = firstNumber(post, ["reply_count"]);
+  const assignee = firstString(post, ["assignee_username", "username"]);
+  return [
+    "•",
+    number ? `#${number}` : id,
+    title,
+    category ? `[${category}]` : undefined,
+    status ? `[${status}]` : undefined,
+    target ? `(${targetType ? `${targetType}:` : ""}${target})` : undefined,
+    replies && replies > 0 ? `↩${replies}` : undefined,
+    assignee ? `@${assignee}` : undefined,
+  ].filter(Boolean).join(" ");
+}
+
+function inlineContentText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value.map((item) => {
+    if (typeof item === "string") return item;
+    if (!item || typeof item !== "object") return "";
+    const object = item as Record<string, unknown>;
+    if (typeof object.text === "string") return object.text;
+    if (object.type === "link") return inlineContentText(object.content);
+    return "";
+  }).join("");
+}
+
+function forumBlockLines(blocks: unknown): string[] {
+  if (!Array.isArray(blocks)) return [];
+  const lines: string[] = [];
+  for (const item of blocks) {
+    if (!item || typeof item !== "object") continue;
+    const block = item as Record<string, unknown>;
+    const type = firstString(block, ["type"]) ?? "block";
+    const props = block.props && typeof block.props === "object" ? block.props as Record<string, unknown> : {};
+    const text = inlineContentText(block.content).trimEnd();
+    if (type === "heading") {
+      const level = firstNumber(props, ["level"]) ?? 2;
+      lines.push(`${"#".repeat(Math.max(1, Math.min(6, level)))} ${text}`.trimEnd());
+    } else if (type === "image") {
+      const name = firstString(props, ["name", "caption"]) ?? "image";
+      const url = firstString(props, ["url"]);
+      lines.push(`🖼 ${name}${url ? `  ${url}` : ""}`);
+    } else if (type === "bulletListItem") {
+      lines.push(`- ${text}`);
+    } else if (type === "numberedListItem") {
+      lines.push(`1. ${text}`);
+    } else if (text) {
+      lines.push(...text.split("\n"));
+    }
+    const childLines = forumBlockLines(block.children);
+    if (childLines.length > 0) lines.push(...childLines.map((line) => `  ${line}`));
+  }
+  return lines;
+}
+
+function forumContentLines(object: Record<string, unknown>): string[] {
+  const blockLines = forumBlockLines(object.content_blocks);
+  if (blockLines.length > 0) return blockLines;
+  const content = firstString(object, ["content", "body", "text", "message", "description"]);
+  return content ? content.split("\n") : ["(no content)"];
+}
+
+export function forumListLines(payload: unknown, title = "QDash Forum", color = false): string[] {
+  const posts = forumPostsFromPayload(payload);
+  const total = payloadTotal(payload);
+  const accent = (text: string) => color ? ansi("1;36", text) : text;
+  const dim = (text: string) => color ? ansi("2", text) : text;
+  return boxed(title, [
+    `posts ${accent(`${posts.length}/${total}`)}`,
+    "",
+    ...(posts.length > 0 ? posts.map((post) => `  ${forumPostLine(post)}`) : [`  ${dim("none")}`]),
+  ], color);
+}
+
+export function forumDetailBodyLines(post: unknown, color = false): string[] {
+  const object = post && typeof post === "object" ? post as Record<string, unknown> : {};
+  const accent = (text: string) => color ? ansi("1;36", text) : text;
+  const muted = (text: string) => color ? ansi("90", text) : text;
+  const labels = stringList(object.labels);
+  const replyCount = firstNumber(object, ["reply_count"]);
+  const meta = [
+    firstString(object, ["category"]) ? `${muted("category")} ${firstString(object, ["category"])}` : undefined,
+    firstString(object, ["status"]) ? `${muted("status")} ${firstString(object, ["status"])}` : undefined,
+    firstString(object, ["target_type"]) || firstString(object, ["target_id"]) ? `${muted("target")} ${[firstString(object, ["target_type"]), firstString(object, ["target_id"])].filter(Boolean).join(":")}` : undefined,
+    firstString(object, ["chip_id"]) ? `${muted("chip")} ${firstString(object, ["chip_id"])}` : undefined,
+    replyCount !== undefined ? `${muted("replies")} ${replyCount}` : undefined,
+  ].filter((line): line is string => typeof line === "string");
+  return [
+    `${muted("id")} ${accent(forumPostId(object))}${firstNumber(object, ["number"]) ? `  ${muted("#")} ${firstNumber(object, ["number"])}` : ""}`,
+    `${muted("title")} ${forumPostTitle(object)}`,
+    `${muted("author")} ${firstString(object, ["username", "user_id"]) ?? "unknown"}${firstString(object, ["assignee_username"]) ? `  ${muted("assignee")} ${firstString(object, ["assignee_username"])}` : ""}`,
+    meta.join("  "),
+    labels.length > 0 ? `${muted("labels")} ${labels.map((label) => `#${label}`).join(" ")}` : undefined,
+    firstString(object, ["created_at"]) ? `${muted("created")} ${firstString(object, ["created_at"])}${firstString(object, ["updated_at"]) ? `  ${muted("updated")} ${firstString(object, ["updated_at"])}` : ""}` : undefined,
+    "",
+    ...forumContentLines(object).map((line) => `  ${line}`),
+  ].filter((line): line is string => typeof line === "string");
+}
+
+export function forumDetailLines(post: unknown, title = "QDash Forum Post", color = false): string[] {
+  return boxed(title, forumDetailBodyLines(post, color), color);
+}
+
+export function forumDetailComponent(post: unknown, theme: Theme) {
+  return {
+    render(width: number) {
+      return boxLinesToWidth("QDash Forum Post", forumDetailBodyLines(post), width, theme);
+    },
+    invalidate() {},
+  };
+}

package/extensions/lib/links.ts

@@ -0,0 +1,57 @@
+import type { QDashClient } from "@oqtopus-team/qdash-client";
+
+function firstString(object: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = object[key];
+    if (typeof value === "string" && value.length > 0) return value;
+    if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  }
+  return undefined;
+}
+
+export function qdashWebBaseUrl(client: QDashClient): string {
+  return client.config.baseUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
+}
+
+export function qdashWebUrl(client: QDashClient, path: string): string {
+  return `${qdashWebBaseUrl(client)}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+export function qdashObjectLinks(client: QDashClient, object: Record<string, unknown>): Record<string, string> {
+  const links: Record<string, string> = {};
+  const taskId = firstString(object, ["task_id", "taskId"]);
+  const executionId = firstString(object, ["execution_id", "executionId"]);
+  const postId = firstString(object, ["post_id", "forum_post_id", "id"]);
+  const issueId = firstString(object, ["issue_id"]);
+  const sessionId = firstString(object, ["session_id", "sessionId"]);
+  if (taskId) links.task_result = qdashWebUrl(client, `/task-results/${encodeURIComponent(taskId)}`);
+  if (executionId) links.execution = qdashWebUrl(client, `/executions/${encodeURIComponent(executionId)}`);
+  if (postId) links.forum_post = qdashWebUrl(client, `/forum/posts/${encodeURIComponent(postId)}`);
+  if (issueId) links.issue = qdashWebUrl(client, `/issues/${encodeURIComponent(issueId)}`);
+  if (sessionId) links.agent_session = qdashWebUrl(client, `/agent-sessions/${encodeURIComponent(sessionId)}`);
+  return links;
+}
+
+export function withQDashLinks(client: QDashClient, data: unknown): unknown {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return data;
+  const object = data as Record<string, unknown>;
+  const links = qdashObjectLinks(client, object);
+  if (Object.keys(links).length === 0) return data;
+  return { ...object, _links: links };
+}
+
+export function safeConfig(client: QDashClient, source: string) {
+  const config = client.config;
+  return {
+    source,
+    baseUrl: config.baseUrl,
+    projectId: config.projectId ?? null,
+    timeoutSeconds: config.timeoutSeconds,
+    verifyTls: config.verifyTls,
+    proxyConfigured: Boolean(config.proxy),
+    apiTokenConfigured: Boolean(config.apiToken),
+    cloudflareAccessConfigured: Boolean(config.cfAccessClientId || config.cfAccessClientSecret),
+    userAgent: config.userAgent,
+    retry: config.retry,
+  };
+}

package/extensions/lib/payload.ts

@@ -0,0 +1,70 @@
+function shortId(value: string, length = 10): string {
+  if (value.length <= length) return value;
+  return `${value.slice(0, length)}…`;
+}
+
+export function arrayFromPayload(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) return payload;
+  if (payload && typeof payload === "object") {
+    const object = payload as Record<string, unknown>;
+    for (const key of ["items", "results", "data", "issues", "executions", "chips", "tasks", "insights"]) {
+      if (Array.isArray(object[key])) return object[key];
+    }
+  }
+  return [];
+}
+
+export function compactItems(payload: unknown, keys: string[], limit: number): Record<string, unknown>[] {
+  return arrayFromPayload(payload).slice(0, limit).map((item) => {
+    if (!item || typeof item !== "object") return { value: item };
+    const object = item as Record<string, unknown>;
+    return Object.fromEntries(keys.filter((key) => key in object).map((key) => [key, object[key]]));
+  });
+}
+
+export function payloadTotal(payload: unknown): number {
+  const fallback = arrayFromPayload(payload).length;
+  if (!payload || typeof payload !== "object") return fallback;
+  const object = payload as Record<string, unknown>;
+  for (const key of ["total", "total_count", "count", "total_items"]) {
+    const value = object[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return fallback;
+}
+
+export function firstString(object: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = object[key];
+    if (typeof value === "string" && value.length > 0) return value;
+    if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  }
+  return undefined;
+}
+
+export function firstNumber(object: Record<string, unknown>, keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = object[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+export function statusIcon(status: string | undefined): string {
+  const normalized = status?.toLowerCase() ?? "";
+  if (["completed", "success", "succeeded", "active", "applied"].includes(normalized)) return "✓";
+  if (["failed", "error", "crashed"].includes(normalized)) return "✗";
+  if (["running", "pending", "queued", "in_progress"].includes(normalized)) return "…";
+  if (["cancelled", "canceled"].includes(normalized)) return "-";
+  return "•";
+}
+
+export function formatItem(item: Record<string, unknown>, fallbackId: string): string {
+  const id = firstString(item, ["issue_id", "execution_id", "flow_run_id", "task_id", "id"]) ?? fallbackId;
+  const title = firstString(item, ["title", "task_name", "flow_name", "name"]);
+  const status = firstString(item, ["status", "execution_status", "activity_status"]);
+  const target = firstString(item, ["qid", "coupling_id"]);
+  return [statusIcon(status), shortId(id, 14), title, target ? `(${target})` : undefined, status ? `[${status}]` : undefined]
+    .filter(Boolean)
+    .join(" ");
+}

package/extensions/lib/render.ts

@@ -0,0 +1,110 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export function ansi(code: string, text: string): string {
+  return `\u001b[${code}m${text}\u001b[0m`;
+}
+
+export function stripAnsi(text: string): string {
+  return text.replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+function displayWidth(text: string): number {
+  return visibleWidth(stripAnsi(text));
+}
+
+export function padAnsi(text: string, width: number): string {
+  return text + " ".repeat(Math.max(0, width - displayWidth(text)));
+}
+
+export function truncateDisplay(text: string, width: number): string {
+  if (displayWidth(text) <= width) return text;
+  const ellipsis = "…";
+  const target = Math.max(0, width - visibleWidth(ellipsis));
+  let out = "";
+  let used = 0;
+  for (const char of Array.from(text)) {
+    const charWidth = visibleWidth(char);
+    if (used + charWidth > target) break;
+    out += char;
+    used += charWidth;
+  }
+  return out + ellipsis;
+}
+
+export function boxed(title: string, body: string[], color = false): string[] {
+  const plainTitle = ` ${title} `;
+  const contentWidth = Math.min(
+    92,
+    Math.max(36, ...body.map((line) => displayWidth(line)), visibleWidth(plainTitle)),
+  );
+  const innerWidth = contentWidth + 2;
+  const borderColor = (text: string) => color ? ansi("90", text) : text;
+  const titleText = color ? ansi("1;36", plainTitle) : plainTitle;
+  const top = borderColor("╭") + titleText + borderColor("─".repeat(Math.max(0, innerWidth - plainTitle.length))) + borderColor("╮");
+  const bottom = borderColor("╰" + "─".repeat(innerWidth) + "╯");
+  return [
+    top,
+    ...body.map((line) => {
+      const clipped = color ? truncateToWidth(line, contentWidth) : truncateDisplay(line, contentWidth);
+      return `${borderColor("│")} ${padAnsi(clipped, contentWidth)} ${borderColor("│")}`;
+    }),
+    bottom,
+  ];
+}
+
+export function wrapPlainLine(line: string, width: number): string[] {
+  if (width <= 0 || visibleWidth(line) <= width) return [line];
+  const output: string[] = [];
+  let rest = line;
+  while (visibleWidth(rest) > width) {
+    let slice = "";
+    for (const char of rest) {
+      if (visibleWidth(slice + char) > width) break;
+      slice += char;
+    }
+    output.push(slice);
+    rest = rest.slice(slice.length);
+  }
+  if (rest.length > 0) output.push(rest);
+  return output;
+}
+
+export function boxLinesToWidth(title: string, body: string[], width: number, theme?: Theme): string[] {
+  const contentWidth = Math.max(24, Math.min(100, width - 4));
+  const border = (text: string) => theme ? theme.fg("borderMuted", text) : text;
+  const titleText = ` ${title} `;
+  const top = `${border("╭")}${theme ? theme.fg("accent", theme.bold(titleText)) : titleText}${border("─".repeat(Math.max(0, contentWidth + 2 - visibleWidth(titleText))))}${border("╮")}`;
+  const bottom = border(`╰${"─".repeat(contentWidth + 2)}╯`);
+  const rows = body.flatMap((line) => wrapPlainLine(line, contentWidth));
+  return [
+    top,
+    ...rows.map((line) => `${border("│")} ${padAnsi(truncateDisplay(line, contentWidth), contentWidth)} ${border("│")}`),
+    bottom,
+  ];
+}
+
+export function textComponent(lines: string[], _theme: Theme, wrap = false) {
+  return {
+    render(width: number) {
+      if (!wrap) return lines.map((line) => truncateToWidth(line, width));
+      return lines.flatMap((line) => wrapPlainLine(line, width));
+    },
+    invalidate() {},
+  };
+}
+
+export function formatNumber(value: number): string {
+  const abs = Math.abs(value);
+  if (abs >= 1000 || (abs > 0 && abs < 0.001)) return value.toExponential(2);
+  if (abs >= 100) return value.toFixed(1);
+  if (abs >= 10) return value.toFixed(3);
+  return value.toFixed(5).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+export function compactDate(value: string | undefined): string {
+  if (!value) return "";
+  const date = new Date(value.endsWith("Z") ? value : `${value}Z`);
+  if (Number.isNaN(date.getTime())) return value.slice(0, 10);
+  return `${String(date.getUTCMonth() + 1).padStart(2, "0")}/${String(date.getUTCDate()).padStart(2, "0")} ${String(date.getUTCHours()).padStart(2, "0")}:${String(date.getUTCMinutes()).padStart(2, "0")}`;
+}

package/extensions/lib/results.ts

@@ -0,0 +1,30 @@
+export function redact(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, item]) => {
+        if (/token|password|secret|authorization|api[_-]?key/i.test(key)) return [key, "[redacted]"];
+        return [key, redact(item)];
+      }),
+    );
+  }
+  return value;
+}
+
+export function toToolResult(data: unknown, details: Record<string, unknown> = {}) {
+  const safeData = redact(data);
+  let text = JSON.stringify(safeData, null, 2);
+  if (text.length > 20_000) text = `${text.slice(0, 20_000)}\n... [truncated]`;
+  return {
+    content: [{ type: "text" as const, text }],
+    details: { ...details, data: safeData },
+  };
+}
+
+export function toTextToolResult(text: string, data: unknown, details: Record<string, unknown> = {}) {
+  const safeData = redact(data);
+  return {
+    content: [{ type: "text" as const, text }],
+    details: { ...details, data: safeData },
+  };
+}