@f5-sales-demo/xcsh 19.51.2

package/src/tools/jtd-to-typescript.ts

@@ -0,0 +1,136 @@
+/**
+ * Convert JSON Type Definition (JTD) to TypeScript interface notation.
+ *
+ * Produces human-readable TypeScript for embedding in system prompts,
+ * helping models understand expected output structure.
+ */
+
+import type { JTDPrimitive } from "./jtd-utils.js";
+import {
+	isJTDDiscriminator,
+	isJTDElements,
+	isJTDEnum,
+	isJTDProperties,
+	isJTDRef,
+	isJTDType,
+	isJTDValues,
+} from "./jtd-utils.js";
+
+const primitiveMap: Record<JTDPrimitive, string> = {
+	boolean: "boolean",
+	string: "string",
+	timestamp: "string",
+	float32: "number",
+	float64: "number",
+	int8: "number",
+	uint8: "number",
+	int16: "number",
+	uint16: "number",
+	int32: "number",
+	uint32: "number",
+};
+
+function convertToTypeScript(schema: unknown, inline = false): string {
+	if (schema === null || schema === undefined || (typeof schema === "object" && Object.keys(schema).length === 0)) {
+		return "unknown";
+	}
+
+	if (isJTDType(schema)) {
+		const tsType = primitiveMap[schema.type as JTDPrimitive];
+		return tsType ?? "unknown";
+	}
+
+	if (isJTDEnum(schema)) {
+		return schema.enum.map(v => `"${v}"`).join(" | ");
+	}
+
+	if (isJTDElements(schema)) {
+		const itemType = convertToTypeScript(schema.elements, true);
+		if (itemType.includes("\n") || itemType.length > 40) {
+			return `Array<${itemType}>`;
+		}
+		return `${itemType}[]`;
+	}
+
+	if (isJTDValues(schema)) {
+		const valueType = convertToTypeScript(schema.values, true);
+		return `Record<string, ${valueType}>`;
+	}
+
+	if (isJTDProperties(schema)) {
+		const lines: string[] = [];
+		lines.push("{");
+
+		if (schema.properties) {
+			for (const [key, value] of Object.entries(schema.properties)) {
+				const propType = convertToTypeScript(value, true);
+				const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `"${key}"`;
+				lines.push(`  ${safeName}: ${propType};`);
+			}
+		}
+
+		if (schema.optionalProperties) {
+			for (const [key, value] of Object.entries(schema.optionalProperties)) {
+				const propType = convertToTypeScript(value, true);
+				const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `"${key}"`;
+				lines.push(`  ${safeName}?: ${propType};`);
+			}
+		}
+
+		lines.push("}");
+
+		if (inline && lines.length <= 4) {
+			// Compact single-line for small objects
+			const props = lines.slice(1, -1).map(l => l.trim());
+			if (props.join(" ").length < 60) {
+				return `{ ${props.join(" ")} }`;
+			}
+		}
+
+		return lines.join("\n");
+	}
+
+	if (isJTDDiscriminator(schema)) {
+		const variants: string[] = [];
+		for (const [tag, props] of Object.entries(schema.mapping)) {
+			const propsType = convertToTypeScript(props, true);
+			if (propsType === "{}") {
+				variants.push(`{ ${schema.discriminator}: "${tag}" }`);
+			} else {
+				// Merge discriminator into props
+				const inner = propsType.slice(1, -1).trim();
+				variants.push(`{ ${schema.discriminator}: "${tag}"; ${inner} }`);
+			}
+		}
+		return variants.join(" | ");
+	}
+
+	if (isJTDRef(schema)) {
+		return schema.ref;
+	}
+
+	return "unknown";
+}
+
+/**
+ * Convert JTD schema to TypeScript interface string.
+ *
+ * @example
+ * ```ts
+ * const schema = {
+ *   properties: {
+ *     name: { type: "string" },
+ *     count: { type: "int32" }
+ *   }
+ * };
+ * jtdToTypeScript(schema);
+ * // Returns:
+ * // {
+ * //   name: string;
+ * //   count: number;
+ * // }
+ * ```
+ */
+export function jtdToTypeScript(schema: unknown): string {
+	return convertToTypeScript(schema, false);
+}

package/src/tools/jtd-utils.ts

@@ -0,0 +1,102 @@
+/**
+ * JSON Type Definition (JTD) utility types and guards.
+ *
+ * Shared type definitions and type guard functions for JTD schema validation.
+ *
+ * @see https://jsontypedef.com/
+ * @see https://datatracker.ietf.org/doc/html/rfc8927
+ */
+
+export type JTDPrimitive =
+	| "boolean"
+	| "string"
+	| "timestamp"
+	| "float32"
+	| "float64"
+	| "int8"
+	| "uint8"
+	| "int16"
+	| "uint16"
+	| "int32"
+	| "uint32";
+
+export interface JTDType {
+	type: JTDPrimitive;
+}
+
+export interface JTDEnum {
+	enum: string[];
+}
+
+export interface JTDElements {
+	elements: JTDSchema;
+}
+
+export interface JTDValues {
+	values: JTDSchema;
+}
+
+export interface JTDProperties {
+	properties?: Record<string, JTDSchema>;
+	optionalProperties?: Record<string, JTDSchema>;
+}
+
+export interface JTDDiscriminator {
+	discriminator: string;
+	mapping: Record<string, JTDProperties>;
+}
+
+export interface JTDRef {
+	ref: string;
+}
+
+export interface JTDEmpty {}
+
+export type JTDSchema =
+	| JTDType
+	| JTDEnum
+	| JTDElements
+	| JTDValues
+	| JTDProperties
+	| JTDDiscriminator
+	| JTDRef
+	| JTDEmpty;
+
+// Type guards
+
+export function isJTDType(schema: unknown): schema is JTDType {
+	return typeof schema === "object" && schema !== null && "type" in schema;
+}
+
+export function isJTDEnum(schema: unknown): schema is JTDEnum {
+	return typeof schema === "object" && schema !== null && "enum" in schema && Array.isArray(schema.enum);
+}
+
+export function isJTDElements(schema: unknown): schema is JTDElements {
+	return typeof schema === "object" && schema !== null && "elements" in schema;
+}
+
+export function isJTDValues(schema: unknown): schema is JTDValues {
+	return typeof schema === "object" && schema !== null && "values" in schema;
+}
+
+export function isJTDProperties(schema: unknown): schema is JTDProperties {
+	return typeof schema === "object" && schema !== null && ("properties" in schema || "optionalProperties" in schema);
+}
+
+export function isJTDDiscriminator(schema: unknown): schema is JTDDiscriminator {
+	return (
+		typeof schema === "object" &&
+		schema !== null &&
+		"discriminator" in schema &&
+		"mapping" in schema &&
+		typeof schema.discriminator === "string" &&
+		typeof schema.mapping === "object" &&
+		schema.mapping !== null &&
+		!Array.isArray(schema.mapping)
+	);
+}
+
+export function isJTDRef(schema: unknown): schema is JTDRef {
+	return typeof schema === "object" && schema !== null && "ref" in schema;
+}

package/src/tools/list-limit.ts

@@ -0,0 +1,40 @@
+import type { LimitsMeta } from "./output-meta";
+
+export interface ListLimitResult<T> {
+	items: T[];
+	limitReached?: number;
+	meta: Partial<LimitsMeta>;
+}
+
+export interface ListLimitOptions {
+	limit?: number;
+	headLimit?: number;
+	limitType?: "match" | "result";
+}
+
+export function applyListLimit<T>(items: T[], options: ListLimitOptions): ListLimitResult<T> {
+	const meta: Partial<LimitsMeta> = {};
+	const limitType = options.limitType ?? "result";
+	const effectiveLimit = options.limit !== undefined && options.limit > 0 ? options.limit : undefined;
+	const effectiveHeadLimit = options.headLimit !== undefined && options.headLimit > 0 ? options.headLimit : undefined;
+	let limited = items;
+	let limitReached: number | undefined;
+
+	if (effectiveLimit !== undefined && items.length >= effectiveLimit) {
+		limited = items.slice(0, effectiveLimit);
+		limitReached = effectiveLimit;
+		const suggestion = effectiveLimit * 2;
+		if (limitType === "match") {
+			meta.matchLimit = { reached: effectiveLimit, suggestion };
+		} else {
+			meta.resultLimit = { reached: effectiveLimit, suggestion };
+		}
+	}
+
+	if (effectiveHeadLimit !== undefined && limited.length > effectiveHeadLimit) {
+		limited = limited.slice(0, effectiveHeadLimit);
+		meta.headLimit = { reached: effectiveHeadLimit, suggestion: effectiveHeadLimit * 2 };
+	}
+
+	return { items: limited, limitReached, meta };
+}

package/src/tools/mermaid-renderer.ts

@@ -0,0 +1,127 @@
+/** TUI renderer for the render_mermaid tool — single F5-framed, themed, colorized diagram. */
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Text, visibleWidth } from "@f5xc-salesdemos/pi-tui";
+import { detectDiagramType, type MermaidDiagramType } from "@f5xc-salesdemos/pi-utils";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { renderMermaidThemed } from "../modes/theme/mermaid-cache";
+import type { Theme } from "../modes/theme/theme";
+import { CachedOutputBlock, F5_TOOL_BORDER_COLOR, type OutputBlockOptions, renderStatusLine } from "../tui";
+import type { RenderMermaidToolDetails } from "./render-mermaid";
+import { formatErrorMessage, replaceTabs } from "./render-utils";
+
+const TOOL_TITLE = "Mermaid";
+
+/** Human-friendly caption for the diagram type, shown in the F5 frame header. */
+export function diagramTypeLabel(type: MermaidDiagramType): string {
+	switch (type) {
+		case "flowchart":
+			return "flowchart";
+		case "sequence":
+			return "sequence diagram";
+		case "class":
+			return "class diagram";
+		case "er":
+			return "ER diagram";
+		case "state":
+			return "state diagram";
+		case "xychart":
+			return "xychart";
+		default:
+			return "diagram";
+	}
+}
+
+/**
+ * Build the F5 output-block options that frame a themed/colored mermaid diagram.
+ * Shared by the render_mermaid tool result AND inline ```mermaid markdown blocks, so
+ * every mermaid render gets the SAME single F5 frame — and the diagram is clipped
+ * (wrapContent: false), never wrapped, so a wide diagram can't reflow or overflow.
+ */
+export function buildMermaidBlockOptions(
+	diagramText: string,
+	opts: { width: number; theme: Theme; typeLabel: string; artifactId?: string },
+): OutputBlockOptions {
+	// Unlabeled section: the header already reads "Mermaid · <type>", so a "Diagram"
+	// bar would be redundant. The diagram keeps its own colors; we only normalize tabs.
+	const lines = diagramText.split("\n").map(line => replaceTabs(line));
+	const meta = opts.artifactId ? [opts.theme.fg("dim", `artifact:${opts.artifactId.slice(0, 8)}`)] : undefined;
+	const header = renderStatusLine(
+		{ title: TOOL_TITLE, titleColor: "dim", description: opts.theme.fg("muted", opts.typeLabel), meta },
+		opts.theme,
+	);
+	// Size the frame SNUGLY to the diagram (+ one space of padding each side), capped at
+	// the available width and kept wide enough for the header caption — so the diagram
+	// feels enclosed in a small padded frame instead of spanning the whole terminal
+	// (tiny diagram) or clipping against the right border (wide diagram).
+	const maxDiagramWidth = lines.reduce((max, line) => Math.max(max, visibleWidth(line)), 0);
+	const desired = Math.max(maxDiagramWidth + 4, visibleWidth(header) + 8);
+	const width = Math.min(opts.width, Math.max(1, desired));
+	return {
+		header,
+		state: "success",
+		sections: [{ lines }],
+		width,
+		borderColor: F5_TOOL_BORDER_COLOR,
+		wrapContent: false,
+	};
+}
+
+type MermaidRenderArgs = {
+	mermaid?: string;
+};
+
+export const mermaidRenderer = {
+	renderCall(_args: MermaidRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const text = renderStatusLine(
+			{ icon: "pending", title: TOOL_TITLE, description: uiTheme.fg("muted", "rendering diagram") },
+			uiTheme,
+		);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: {
+			content: Array<{ type: string; text?: string }>;
+			details?: RenderMermaidToolDetails;
+			isError?: boolean;
+		},
+		_options: RenderResultOptions,
+		uiTheme: Theme,
+		args?: MermaidRenderArgs,
+	): Component {
+		if (result.isError === true) {
+			const errorText = result.content?.find(c => c.type === "text")?.text;
+			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+		}
+
+		const rawText = result.content?.find(c => c.type === "text")?.text ?? "";
+		// Strip artifact reference from the plain result text (fallback path).
+		const artifactIdx = rawText.indexOf("\n\nSaved artifact:");
+		const plainText = artifactIdx >= 0 ? rawText.slice(0, artifactIdx) : rawText;
+
+		// Prefer re-rendering from the original source: themed, per-node-tinted, colored.
+		const source = args?.mermaid?.trim();
+		const typeLabel = source ? diagramTypeLabel(detectDiagramType(source)) : "diagram";
+		const artifactId = result.details?.artifactId;
+
+		const block = new CachedOutputBlock();
+		return {
+			render(width: number): string[] {
+				// Expand the diagram toward the available width (inside the frame), then
+				// size the frame snugly around the result.
+				const targetWidth = Math.max(20, width - 4);
+				const diagramText = (source ? renderMermaidThemed(source, uiTheme, { targetWidth }) : null) ?? plainText;
+				return block.render(
+					buildMermaidBlockOptions(diagramText, { width, theme: uiTheme, typeLabel, artifactId }),
+					uiTheme,
+				);
+			},
+			invalidate() {
+				block.invalidate();
+			},
+		};
+	},
+
+	mergeCallAndResult: true,
+	inline: true,
+};

package/src/tools/notebook.ts

@@ -0,0 +1,288 @@
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import { StringEnum } from "@f5xc-salesdemos/pi-ai";
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Text } from "@f5xc-salesdemos/pi-tui";
+import { isEnoent, untilAborted } from "@f5xc-salesdemos/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../sdk";
+import { Hasher, type RenderCache, renderCodeCell, renderStatusLine } from "../tui";
+import { resolveToCwd } from "./path-utils";
+import { formatCount, formatErrorMessage, PREVIEW_LIMITS } from "./render-utils";
+
+const notebookSchema = Type.Object({
+	action: StringEnum(["edit", "insert", "delete"], {
+		description: "Action to perform on the notebook cell",
+	}),
+	notebook_path: Type.String({ description: "Path to the .ipynb file (relative or absolute)" }),
+	cell_index: Type.Number({ description: "0-based index of the cell to operate on" }),
+	content: Type.Optional(Type.String({ description: "New cell content (required for edit/insert)" })),
+	cell_type: Type.Optional(
+		StringEnum(["code", "markdown"], {
+			description: "Cell type for insert (default: code)",
+		}),
+	),
+});
+
+export interface NotebookToolDetails {
+	/** Action performed */
+	action: "edit" | "insert" | "delete";
+	/** Cell index operated on */
+	cellIndex: number;
+	/** Cell type */
+	cellType?: string;
+	/** Total cell count after operation */
+	totalCells: number;
+	/** Cell content lines after operation (or removed content for delete) */
+	cellSource?: string[];
+}
+
+interface NotebookCell {
+	cell_type: "code" | "markdown" | "raw";
+	source: string[];
+	metadata: Record<string, unknown>;
+	execution_count?: number | null;
+	outputs?: unknown[];
+}
+
+interface Notebook {
+	cells: NotebookCell[];
+	metadata: Record<string, unknown>;
+	nbformat: number;
+	nbformat_minor: number;
+}
+
+function splitIntoLines(content: string): string[] {
+	return content.split("\n").map((line, i, arr) => (i < arr.length - 1 ? `${line}\n` : line));
+}
+
+type NotebookParams = Static<typeof notebookSchema>;
+
+export class NotebookTool implements AgentTool<typeof notebookSchema, NotebookToolDetails> {
+	readonly name = "notebook";
+	readonly label = "Notebook";
+	readonly description =
+		"Edit, insert, or delete cells in Jupyter notebooks (.ipynb). cell_index is 0-based. Paths must be absolute.";
+	readonly parameters = notebookSchema;
+	readonly strict = true;
+	readonly concurrency = "exclusive";
+
+	constructor(private readonly session: ToolSession) {}
+
+	async execute(
+		_toolCallId: string,
+		params: NotebookParams,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<NotebookToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<NotebookToolDetails>> {
+		const { action, notebook_path, cell_index, content, cell_type } = params;
+		const absolutePath = resolveToCwd(notebook_path, this.session.cwd);
+
+		return untilAborted(signal, async () => {
+			// Read and parse notebook
+			let notebook: Notebook;
+			try {
+				notebook = await Bun.file(absolutePath).json();
+			} catch (err) {
+				if (isEnoent(err)) throw new Error(`Notebook not found: ${notebook_path}`);
+				throw new Error(`Invalid JSON in notebook: ${notebook_path}`);
+			}
+
+			// Validate notebook structure
+			if (!notebook.cells || !Array.isArray(notebook.cells)) {
+				throw new Error(`Invalid notebook structure (missing cells array): ${notebook_path}`);
+			}
+
+			const cellCount = notebook.cells.length;
+
+			// Validate cell_index based on action
+			if (action === "insert") {
+				if (cell_index < 0 || cell_index > cellCount) {
+					throw new Error(`Cell index ${cell_index} out of range for insert (0-${cellCount}) in ${notebook_path}`);
+				}
+			} else {
+				if (cell_index < 0 || cell_index >= cellCount) {
+					throw new Error(`Cell index ${cell_index} out of range (0-${cellCount - 1}) in ${notebook_path}`);
+				}
+			}
+
+			// Validate content for edit/insert
+			if ((action === "edit" || action === "insert") && content === undefined) {
+				throw new Error(`Content is required for ${action} action`);
+			}
+
+			// Perform the action
+			let resultMessage: string;
+			let finalCellType: string | undefined;
+			let cellSource: string[] | undefined;
+
+			switch (action) {
+				case "edit": {
+					const sourceLines = splitIntoLines(content!);
+					notebook.cells[cell_index].source = sourceLines;
+					finalCellType = notebook.cells[cell_index].cell_type;
+					cellSource = sourceLines;
+					resultMessage = `Replaced cell ${cell_index} (${finalCellType})`;
+					break;
+				}
+				case "insert": {
+					const sourceLines = splitIntoLines(content!);
+					const newCellType = (cell_type as "code" | "markdown") || "code";
+					const newCell: NotebookCell = {
+						cell_type: newCellType,
+						source: sourceLines,
+						metadata: {},
+					};
+					if (newCellType === "code") {
+						newCell.execution_count = null;
+						newCell.outputs = [];
+					}
+					notebook.cells.splice(cell_index, 0, newCell);
+					finalCellType = newCellType;
+					cellSource = sourceLines;
+					resultMessage = `Inserted ${newCellType} cell at position ${cell_index}`;
+					break;
+				}
+				case "delete": {
+					const removedCell = notebook.cells[cell_index];
+					finalCellType = removedCell.cell_type;
+					cellSource = removedCell.source;
+					notebook.cells.splice(cell_index, 1);
+					resultMessage = `Deleted cell ${cell_index} (${finalCellType})`;
+					break;
+				}
+				default: {
+					throw new Error(`Invalid action: ${action}`);
+				}
+			}
+
+			// Write back with single-space indentation
+			await Bun.write(absolutePath, JSON.stringify(notebook, null, 1));
+
+			const newCellCount = notebook.cells.length;
+			return {
+				content: [
+					{
+						type: "text",
+						text: `${resultMessage}. Notebook now has ${newCellCount} cells.`,
+					},
+				],
+				details: {
+					action: action as "edit" | "insert" | "delete",
+					cellIndex: cell_index,
+					cellType: finalCellType,
+					totalCells: newCellCount,
+					cellSource,
+				},
+			};
+		});
+	}
+}
+
+// =============================================================================
+// TUI Renderer
+// =============================================================================
+
+interface NotebookRenderArgs {
+	action: string;
+	notebookPath?: string;
+	notebook_path?: string;
+	cellNumber?: number;
+	cell_index?: number;
+	cellType?: string;
+	cell_type?: string;
+	content?: string;
+}
+
+const COLLAPSED_TEXT_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
+
+export const notebookToolRenderer = {
+	renderCall(args: NotebookRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const meta: string[] = [];
+		const notebookPath = args.notebookPath ?? args.notebook_path;
+		const cellNumber = args.cellNumber ?? args.cell_index;
+		const cellType = args.cellType ?? args.cell_type;
+		meta.push(`in ${notebookPath || "?"}`);
+		if (cellNumber !== undefined) meta.push(`cell:${cellNumber}`);
+		if (cellType) meta.push(`type:${cellType}`);
+
+		const text = renderStatusLine(
+			{ icon: "pending", title: "Notebook", description: args.action || "?", meta },
+			uiTheme,
+		);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: NotebookToolDetails },
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		args?: NotebookRenderArgs,
+	): Component {
+		const content = result.content?.[0];
+		if (content?.type === "text" && content.text?.startsWith("Error:")) {
+			const notebookPath = args?.notebookPath ?? args?.notebook_path ?? "?";
+			const header = renderStatusLine({ title: "Notebook", description: notebookPath }, uiTheme);
+			return new Text([header, formatErrorMessage(content.text, uiTheme)].join("\n"), 0, 0);
+		}
+
+		const details = result.details;
+		const action = details?.action ?? "edit";
+		const cellIndex = details?.cellIndex;
+		const cellType = details?.cellType;
+		const totalCells = details?.totalCells;
+		const cellSource = details?.cellSource ?? [];
+		const lineCount = cellSource.length;
+
+		const actionLabel = action === "insert" ? "Inserted" : action === "delete" ? "Deleted" : "Edited";
+		const cellLabel = cellType || "cell";
+		const summaryParts = [`${actionLabel} ${cellLabel} ${cellIndex ?? "?"}`];
+		if (lineCount > 0) summaryParts.push(formatCount("line", lineCount));
+		if (totalCells !== undefined) summaryParts.push(`${totalCells} total`);
+
+		const outputLines = summaryParts.map(part => uiTheme.fg("dim", part));
+		const codeText = cellSource.join("");
+		const language = cellType === "markdown" ? "markdown" : undefined;
+
+		const notebookPath = args?.notebookPath ?? args?.notebook_path;
+		const notebookLabel = notebookPath ? `${actionLabel} ${notebookPath}` : "Notebook";
+		let cached: RenderCache | undefined;
+
+		return {
+			render: (width: number): string[] => {
+				// REACTIVE: read mutable options at render time
+				const { expanded } = options;
+				const key = new Hasher().bool(expanded).u32(width).digest();
+				if (cached?.key === key) return cached.lines;
+
+				const lines = renderCodeCell(
+					{
+						code: codeText,
+						language,
+						title: notebookLabel,
+						status: "complete",
+						output: outputLines.join("\n"),
+						codeMaxLines: expanded ? Number.POSITIVE_INFINITY : COLLAPSED_TEXT_LIMIT,
+						expanded,
+						width,
+					},
+					uiTheme,
+				);
+
+				cached = { key, lines };
+				return lines;
+			},
+			invalidate: () => {
+				cached = undefined;
+			},
+		};
+	},
+	mergeCallAndResult: true,
+};