@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/tools/inspect-image.ts

@@ -0,0 +1,173 @@
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import { type Api, type AssistantMessage, completeSimple, type Model } from "@f5xc-salesdemos/pi-ai";
+import { prompt } from "@f5xc-salesdemos/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { expandRoleAlias, resolveModelFromString } from "../config/model-resolver";
+import inspectImageDescription from "../prompts/tools/inspect-image.md" with { type: "text" };
+import inspectImageSystemPromptTemplate from "../prompts/tools/inspect-image-system.md" with { type: "text" };
+import {
+	ImageInputTooLargeError,
+	type LoadedImageInput,
+	loadImageInput,
+	MAX_IMAGE_INPUT_BYTES,
+} from "../utils/image-loading";
+import type { ToolSession } from "./index";
+import { ToolError } from "./tool-errors";
+
+const inspectImageSchema = Type.Object(
+	{
+		path: Type.String({ description: "Filesystem path to an image" }),
+		question: Type.String({ description: "Question to ask about the image" }),
+	},
+	{ additionalProperties: false },
+);
+
+export type InspectImageParams = Static<typeof inspectImageSchema>;
+
+export interface InspectImageToolDetails {
+	model: string;
+	imagePath: string;
+	mimeType: string;
+}
+
+function extractResponseText(message: AssistantMessage): string {
+	return message.content
+		.filter(content => content.type === "text")
+		.map(content => content.text)
+		.join("")
+		.trim();
+}
+
+export class InspectImageTool implements AgentTool<typeof inspectImageSchema, InspectImageToolDetails> {
+	readonly name = "inspect_image";
+	readonly label = "InspectImage";
+	readonly description: string;
+	readonly parameters = inspectImageSchema;
+	readonly strict = true;
+
+	constructor(
+		private readonly session: ToolSession,
+		private readonly completeImageRequest: typeof completeSimple = completeSimple,
+	) {
+		this.description = prompt.render(inspectImageDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: InspectImageParams,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<InspectImageToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<InspectImageToolDetails>> {
+		if (this.session.settings.get("images.blockImages")) {
+			throw new ToolError(
+				"Image submission is disabled by settings (images.blockImages=true). Disable it to use inspect_image.",
+			);
+		}
+
+		const modelRegistry = this.session.modelRegistry;
+		if (!modelRegistry) {
+			throw new ToolError("Model registry is unavailable for inspect_image.");
+		}
+
+		const availableModels = modelRegistry.getAvailable();
+		if (availableModels.length === 0) {
+			throw new ToolError("No models available for inspect_image.");
+		}
+
+		const matchPreferences = { usageOrder: this.session.settings.getStorage()?.getModelUsageOrder() };
+		const resolvePattern = (pattern: string | undefined): Model<Api> | undefined => {
+			if (!pattern) return undefined;
+			const expanded = expandRoleAlias(pattern, this.session.settings);
+			return resolveModelFromString(expanded, availableModels, matchPreferences);
+		};
+
+		const activeModelPattern = this.session.getActiveModelString?.() ?? this.session.getModelString?.();
+		const model =
+			resolvePattern("pi/vision") ??
+			resolvePattern("pi/default") ??
+			resolvePattern(activeModelPattern) ??
+			availableModels[0];
+		if (!model) {
+			throw new ToolError("Unable to resolve a model for inspect_image.");
+		}
+
+		if (!model.input.includes("image")) {
+			throw new ToolError(
+				`Resolved model ${model.provider}/${model.id} does not support image input. Configure a vision-capable model for modelRoles.vision.`,
+			);
+		}
+
+		const apiKey = await modelRegistry.getApiKey(model);
+		if (!apiKey) {
+			throw new ToolError(
+				`No API key available for ${model.provider}/${model.id}. Configure credentials for this provider or choose another vision-capable model.`,
+			);
+		}
+
+		let imageInput: LoadedImageInput | null;
+		try {
+			imageInput = await loadImageInput({
+				path: params.path,
+				cwd: this.session.cwd,
+				autoResize: this.session.settings.get("images.autoResize"),
+				maxBytes: MAX_IMAGE_INPUT_BYTES,
+			});
+		} catch (error) {
+			if (error instanceof ImageInputTooLargeError) {
+				throw new ToolError(error.message);
+			}
+			throw error;
+		}
+
+		if (!imageInput) {
+			throw new ToolError("inspect_image only supports PNG, JPEG, GIF, and WEBP files detected by file content.");
+		}
+
+		const response = await this.completeImageRequest(
+			model,
+			{
+				systemPrompt: prompt.render(inspectImageSystemPromptTemplate),
+				messages: [
+					{
+						role: "user",
+						content: [
+							{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
+							{ type: "text", text: params.question },
+						],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{ apiKey, signal },
+		);
+
+		if (response.stopReason === "error") {
+			throw new ToolError(response.errorMessage ?? "inspect_image request failed.");
+		}
+		if (response.stopReason === "aborted") {
+			throw new ToolError("inspect_image request aborted.");
+		}
+
+		const text = extractResponseText(response);
+		if (!text) {
+			throw new ToolError("inspect_image model returned no text output.");
+		}
+
+		return {
+			content: [{ type: "text", text }],
+			details: {
+				model: `${model.provider}/${model.id}`,
+				imagePath: imageInput.resolvedPath,
+				mimeType: imageInput.mimeType,
+			},
+		};
+	}
+}
+
+export { inspectImageToolRenderer } from "./inspect-image-renderer";

package/src/tools/json-tree.ts

@@ -0,0 +1,243 @@
+/**
+ * JSON tree rendering utilities shared across tool renderers.
+ */
+import { INTENT_FIELD } from "@f5xc-salesdemos/pi-agent-core";
+import type { Theme } from "../modes/theme/theme";
+import { truncateToWidth } from "./render-utils";
+
+/** Max depth for JSON tree rendering */
+export const JSON_TREE_MAX_DEPTH_COLLAPSED = 2;
+export const JSON_TREE_MAX_DEPTH_EXPANDED = 6;
+export const JSON_TREE_MAX_LINES_COLLAPSED = 6;
+export const JSON_TREE_MAX_LINES_EXPANDED = 200;
+export const JSON_TREE_SCALAR_LEN_COLLAPSED = 60;
+export const JSON_TREE_SCALAR_LEN_EXPANDED = 2000;
+
+/** Keys injected by the harness that should not be displayed to users */
+const HIDDEN_ARG_KEYS = new Set([INTENT_FIELD, "__partialJson"]);
+
+/** Strip harness-internal keys from tool args for display */
+export function stripInternalArgs(args: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(args)) {
+		if (!HIDDEN_ARG_KEYS.has(key)) result[key] = value;
+	}
+	return result;
+}
+/**
+ * Format a scalar value for inline display.
+ */
+export function formatScalar(value: unknown, maxLen: number): string {
+	if (value === null) return "null";
+	if (value === undefined) return "undefined";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") return String(value);
+	if (typeof value === "string") {
+		const escaped = value.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+		const truncated = truncateToWidth(escaped, maxLen);
+		return `"${truncated}"`;
+	}
+	if (Array.isArray(value)) return `[${value.length} items]`;
+	if (typeof value === "object") {
+		const keys = Object.keys(value);
+		return `{${keys.length} keys}`;
+	}
+	return String(value);
+}
+
+/**
+ * Format args inline for collapsed view.
+ */
+export function formatArgsInline(args: Record<string, unknown>, maxWidth: number): string {
+	const entries = Object.entries(args).filter(([k]) => !HIDDEN_ARG_KEYS.has(k));
+	if (entries.length === 0) return "";
+
+	// Single arg: show key=value
+	if (entries.length === 1) {
+		const [key, value] = entries[0];
+		return `${key}=${formatScalar(value, maxWidth - key.length - 1)}`;
+	}
+
+	// Multiple args: show key=value, key=value...
+	const pairs: string[] = [];
+	let totalLen = 0;
+
+	for (const [key, value] of entries) {
+		const valueStr = formatScalar(value, 24);
+		const pairStr = `${key}=${valueStr}`;
+		const addLen = pairs.length > 0 ? pairStr.length + 2 : pairStr.length;
+
+		if (totalLen + addLen > maxWidth && pairs.length > 0) {
+			pairs.push("…");
+			break;
+		}
+
+		pairs.push(pairStr);
+		totalLen += addLen;
+	}
+
+	return pairs.join(", ");
+}
+
+/**
+ * Build tree prefix for nested rendering.
+ */
+function buildTreePrefix(ancestors: boolean[], theme: Theme): string {
+	return ancestors.map(hasNext => (hasNext ? `${theme.tree.vertical}  ` : "   ")).join("");
+}
+
+/**
+ * Render a JSON value as tree lines.
+ */
+export function renderJsonTreeLines(
+	value: unknown,
+	theme: Theme,
+	maxDepth: number,
+	maxLines: number,
+	maxScalarLen: number,
+): { lines: string[]; truncated: boolean } {
+	const lines: string[] = [];
+	let truncated = false;
+
+	const iconObject = theme.styledSymbol("icon.folder", "muted");
+	const iconArray = theme.styledSymbol("icon.package", "muted");
+	const iconScalar = theme.styledSymbol("icon.file", "muted");
+
+	const pushLine = (line: string): boolean => {
+		if (lines.length >= maxLines) {
+			truncated = true;
+			return false;
+		}
+		lines.push(line);
+		return true;
+	};
+
+	const renderNode = (val: unknown, key: string | undefined, ancestors: boolean[], isLast: boolean, depth: number) => {
+		if (lines.length >= maxLines) {
+			truncated = true;
+			return;
+		}
+
+		const connector = isLast ? theme.tree.last : theme.tree.branch;
+		const prefix = `${buildTreePrefix(ancestors, theme)}${theme.fg("dim", connector)} `;
+
+		// Handle scalars
+		if (val === null || val === undefined || typeof val !== "object") {
+			const label = key ? theme.fg("muted", key) : theme.fg("muted", "value");
+
+			// Special handling for multiline strings
+			if (typeof val === "string" && val.includes("\n")) {
+				const strLines = val.split("\n");
+				const maxStrLines = Math.min(strLines.length, Math.max(1, maxLines - lines.length - 1));
+				const continuePrefix = buildTreePrefix([...ancestors, !isLast], theme);
+
+				// First line with label
+				const firstLine = truncateToWidth(strLines[0], maxScalarLen);
+				pushLine(`${prefix}${iconScalar} ${label}: ${theme.fg("dim", `"${firstLine}`)}`);
+
+				// Subsequent lines indented
+				for (let i = 1; i < maxStrLines; i++) {
+					if (lines.length >= maxLines) {
+						truncated = true;
+						break;
+					}
+					const line = truncateToWidth(strLines[i], maxScalarLen);
+					pushLine(`${continuePrefix}   ${theme.fg("dim", ` ${line}`)}`);
+				}
+
+				// Show truncation and closing quote
+				if (strLines.length > maxStrLines) {
+					truncated = true;
+					pushLine(`${continuePrefix}   ${theme.fg("dim", ` …(${strLines.length - maxStrLines} more lines)"`)}`);
+				} else {
+					// Add closing quote to last line - need to modify the last pushed line
+					const lastIdx = lines.length - 1;
+					lines[lastIdx] = `${lines[lastIdx]}${theme.fg("dim", '"')}`;
+				}
+				return;
+			}
+
+			const scalar = formatScalar(val, maxScalarLen);
+			pushLine(`${prefix}${iconScalar} ${label}: ${theme.fg("dim", scalar)}`);
+			return;
+		}
+
+		// Handle arrays
+		if (Array.isArray(val)) {
+			const header = key ? theme.fg("muted", key) : theme.fg("muted", "array");
+			pushLine(`${prefix}${iconArray} ${header}`);
+			if (val.length === 0) {
+				pushLine(
+					`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "[]")}`,
+				);
+				return;
+			}
+			if (depth >= maxDepth) {
+				pushLine(
+					`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "…")}`,
+				);
+				return;
+			}
+			const nextAncestors = [...ancestors, !isLast];
+			for (let i = 0; i < val.length; i++) {
+				renderNode(val[i], `[${i}]`, nextAncestors, i === val.length - 1, depth + 1);
+				if (lines.length >= maxLines) {
+					truncated = true;
+					return;
+				}
+			}
+			return;
+		}
+
+		// Handle objects
+		const header = key ? theme.fg("muted", key) : theme.fg("muted", "object");
+		pushLine(`${prefix}${iconObject} ${header}`);
+		const entries = Object.entries(val as Record<string, unknown>);
+		if (entries.length === 0) {
+			pushLine(
+				`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "{}")}`,
+			);
+			return;
+		}
+		if (depth >= maxDepth) {
+			pushLine(
+				`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "…")}`,
+			);
+			return;
+		}
+		const nextAncestors = [...ancestors, !isLast];
+		for (let i = 0; i < entries.length; i++) {
+			const [childKey, child] = entries[i];
+			renderNode(child, childKey, nextAncestors, i === entries.length - 1, depth + 1);
+			if (lines.length >= maxLines) {
+				truncated = true;
+				return;
+			}
+		}
+	};
+
+	// Render root level
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const entries = Object.entries(value as Record<string, unknown>);
+		for (let i = 0; i < entries.length; i++) {
+			const [childKey, child] = entries[i];
+			renderNode(child, childKey, [], i === entries.length - 1, 1);
+			if (lines.length >= maxLines) {
+				truncated = true;
+				break;
+			}
+		}
+	} else if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			renderNode(value[i], `[${i}]`, [], i === value.length - 1, 1);
+			if (lines.length >= maxLines) {
+				truncated = true;
+				break;
+			}
+		}
+	} else {
+		renderNode(value, undefined, [], true, 0);
+	}
+
+	return { lines, truncated };
+}

package/src/tools/jtd-to-json-schema.ts

@@ -0,0 +1,199 @@
+/**
+ * Convert JSON Type Definition (JTD) to JSON Schema.
+ *
+ * JTD (RFC 8927) is a simpler schema format. This converter allows users to
+ * write schemas in JTD and have them converted to JSON Schema for model APIs.
+ *
+ * @see https://jsontypedef.com/
+ * @see https://datatracker.ietf.org/doc/html/rfc8927
+ */
+
+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", // ISO 8601
+	float32: "number",
+	float64: "number",
+	int8: "integer",
+	uint8: "integer",
+	int16: "integer",
+	uint16: "integer",
+	int32: "integer",
+	uint32: "integer",
+};
+
+function convertSchema(schema: unknown): unknown {
+	if (schema === null || typeof schema !== "object") {
+		return {};
+	}
+
+	// Enum form: { enum: ["a", "b"] } → { enum: ["a", "b"] }
+	if (isJTDEnum(schema)) {
+		return { enum: schema.enum };
+	}
+
+	// Elements form: { elements: { type: "string" } } → { type: "array", items: ... }
+	if (isJTDElements(schema)) {
+		return {
+			type: "array",
+			items: convertSchema(schema.elements),
+		};
+	}
+
+	// Type form: { type: "string" } → { type: "string" }
+	if (isJTDType(schema)) {
+		const jsonType = primitiveMap[schema.type as JTDPrimitive];
+		if (!jsonType) {
+			return { type: schema.type };
+		}
+		return { type: jsonType };
+	}
+	// Values form: { values: { type: "string" } } → { type: "object", additionalProperties: ... }
+	if (isJTDValues(schema)) {
+		return {
+			type: "object",
+			additionalProperties: convertSchema(schema.values),
+		};
+	}
+
+	// Properties form: { properties: {...}, optionalProperties: {...} }
+	if (isJTDProperties(schema)) {
+		const properties: Record<string, unknown> = {};
+		const required: string[] = [];
+
+		// Required properties
+		if (schema.properties) {
+			for (const [key, value] of Object.entries(schema.properties)) {
+				properties[key] = convertSchema(value);
+				required.push(key);
+			}
+		}
+
+		// Optional properties
+		if (schema.optionalProperties) {
+			for (const [key, value] of Object.entries(schema.optionalProperties)) {
+				properties[key] = convertSchema(value);
+			}
+		}
+
+		const result: Record<string, unknown> = {
+			type: "object",
+			properties,
+			additionalProperties: false,
+		};
+
+		if (required.length > 0) {
+			result.required = required;
+		}
+
+		return result;
+	}
+
+	// Discriminator form: { discriminator: "type", mapping: { ... } }
+	if (isJTDDiscriminator(schema)) {
+		const oneOf: unknown[] = [];
+
+		for (const [tag, props] of Object.entries(schema.mapping)) {
+			const converted = convertSchema(props) as Record<string, unknown>;
+			// Add the discriminator property
+			const properties = (converted.properties || {}) as Record<string, unknown>;
+			properties[schema.discriminator] = { const: tag };
+
+			const required = ((converted.required as string[]) || []).slice();
+			if (!required.includes(schema.discriminator)) {
+				required.push(schema.discriminator);
+			}
+
+			oneOf.push({
+				...converted,
+				properties,
+				required,
+			});
+		}
+
+		return { oneOf };
+	}
+
+	// Ref form: { ref: "MyType" } → { $ref: "#/$defs/MyType" }
+	if (isJTDRef(schema)) {
+		return { $ref: `#/$defs/${schema.ref}` };
+	}
+
+	// Empty form: {} → {} (accepts anything)
+	return {};
+}
+
+/**
+ * Detect if a schema is JTD format (vs JSON Schema).
+ *
+ * JTD schemas use: type (primitives), properties, optionalProperties, elements, values, enum, discriminator, ref
+ * JSON Schema uses: type: "object", type: "array", items, additionalProperties, etc.
+ */
+export function isJTDSchema(schema: unknown): boolean {
+	if (schema === null || typeof schema !== "object") {
+		return false;
+	}
+
+	const obj = schema as Record<string, unknown>;
+
+	// JTD-specific keywords
+	if ("elements" in obj) return true;
+	if ("values" in obj) return true;
+	if ("optionalProperties" in obj) return true;
+	if ("discriminator" in obj) return true;
+	if ("ref" in obj) return true;
+
+	// JTD type primitives (JSON Schema doesn't have int32, float64, etc.)
+	if ("type" in obj) {
+		const jtdPrimitives = ["timestamp", "float32", "float64", "int8", "uint8", "int16", "uint16", "int32", "uint32"];
+		if (jtdPrimitives.includes(obj.type as string)) {
+			return true;
+		}
+	}
+
+	// JTD properties form without type: "object" (JSON Schema requires it)
+	if ("properties" in obj && !("type" in obj)) {
+		return true;
+	}
+
+	return false;
+}
+
+function normalizeMixedSchemaNode(schema: unknown): unknown {
+	if (schema === null || typeof schema !== "object") {
+		return schema;
+	}
+
+	if (Array.isArray(schema)) {
+		return schema.map(item => normalizeMixedSchemaNode(item));
+	}
+
+	if (isJTDSchema(schema)) {
+		return normalizeMixedSchemaNode(convertSchema(schema));
+	}
+
+	const normalized: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(schema)) {
+		normalized[key] = normalizeMixedSchemaNode(value);
+	}
+
+	return normalized;
+}
+/**
+ * Convert JTD schema to JSON Schema.
+ * If already JSON Schema, returns as-is.
+ */
+export function jtdToJsonSchema(schema: unknown): unknown {
+	return normalizeMixedSchemaNode(schema);
+}