@f5-sales-demo/xcsh 19.51.2

package/src/tools/ssh.ts

@@ -0,0 +1,322 @@
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Text } from "@f5xc-salesdemos/pi-tui";
+import { prompt } from "@f5xc-salesdemos/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import type { SSHHost } from "../capability/ssh";
+import { sshCapability } from "../capability/ssh";
+import { loadCapability } from "../discovery";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import sshDescriptionBase from "../prompts/tools/ssh.md" with { type: "text" };
+import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
+import type { SSHHostInfo } from "../ssh/connection-manager";
+import { ensureHostInfo, getHostInfoForHost } from "../ssh/connection-manager";
+import { executeSSH } from "../ssh/ssh-executor";
+import { renderStatusLine } from "../tui";
+import { CachedOutputBlock } from "../tui/output-block";
+import type { ToolSession } from ".";
+import { formatStyledTruncationWarning, type OutputMeta } from "./output-meta";
+import { ToolError } from "./tool-errors";
+import { toolResult } from "./tool-result";
+import { clampTimeout } from "./tool-timeouts";
+
+const sshSchema = Type.Object({
+	host: Type.String({ description: "Host name from managed SSH config or discovered ssh.json files" }),
+	command: Type.String({ description: "Command to execute on the remote host" }),
+	cwd: Type.Optional(Type.String({ description: "Remote working directory (optional)" })),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 60)" })),
+});
+
+export interface SSHToolDetails {
+	meta?: OutputMeta;
+}
+
+async function formatHostEntry(host: SSHHost): Promise<string> {
+	const info = await getHostInfoForHost(host);
+
+	let shell: string;
+	if (!info) {
+		shell = "detecting...";
+	} else if (info.os === "windows") {
+		if (info.compatEnabled) {
+			const compatShell = info.compatShell || "bash";
+			shell = `windows/${compatShell}`;
+		} else if (info.shell === "powershell") {
+			shell = "windows/powershell";
+		} else {
+			shell = "windows/cmd";
+		}
+	} else if (info.os === "linux") {
+		shell = `linux/${info.shell}`;
+	} else if (info.os === "macos") {
+		shell = `macos/${info.shell}`;
+	} else {
+		shell = `unknown/${info.shell}`;
+	}
+
+	return `- ${host.name} (${host.host}) | ${shell}`;
+}
+
+async function formatDescription(hosts: SSHHost[]): Promise<string> {
+	const baseDescription = prompt.render(sshDescriptionBase);
+	if (hosts.length === 0) {
+		return baseDescription;
+	}
+	const hostList = (await Promise.all(hosts.map(formatHostEntry))).join("\n");
+	return `${baseDescription}\n\nAvailable hosts:\n${hostList}`;
+}
+
+function quoteRemotePath(value: string): string {
+	if (value.length === 0) {
+		return "''";
+	}
+	const escaped = value.replace(/'/g, "'\\''");
+	return `'${escaped}'`;
+}
+
+function quotePowerShellPath(value: string): string {
+	if (value.length === 0) {
+		return "''";
+	}
+	const escaped = value.replace(/'/g, "''");
+	return `'${escaped}'`;
+}
+
+function quoteCmdPath(value: string): string {
+	const escaped = value.replace(/"/g, '""');
+	return `"${escaped}"`;
+}
+
+function buildRemoteCommand(command: string, cwd: string | undefined, info: SSHHostInfo): string {
+	if (!cwd) return command;
+
+	if (info.os === "windows" && !info.compatEnabled) {
+		if (info.shell === "powershell") {
+			return `Set-Location -Path ${quotePowerShellPath(cwd)}; ${command}`;
+		}
+		return `cd /d ${quoteCmdPath(cwd)} && ${command}`;
+	}
+
+	return `cd -- ${quoteRemotePath(cwd)} && ${command}`;
+}
+
+async function loadHosts(session: ToolSession): Promise<{
+	hostNames: string[];
+	hostsByName: Map<string, SSHHost>;
+}> {
+	const result = await loadCapability<SSHHost>(sshCapability.id, { cwd: session.cwd });
+	const hostsByName = new Map<string, SSHHost>();
+	for (const host of result.items) {
+		if (!hostsByName.has(host.name)) {
+			hostsByName.set(host.name, host);
+		}
+	}
+	const hostNames = Array.from(hostsByName.keys()).sort();
+	return { hostNames, hostsByName };
+}
+
+type SshToolParams = Static<typeof sshSchema>;
+
+export class SshTool implements AgentTool<typeof sshSchema, SSHToolDetails> {
+	readonly name = "ssh";
+	readonly label = "SSH";
+	readonly parameters = sshSchema;
+	readonly concurrency = "exclusive";
+	readonly strict = true;
+
+	readonly #allowedHosts: Set<string>;
+
+	constructor(
+		private readonly session: ToolSession,
+		private readonly hostNames: string[],
+		private readonly hostsByName: Map<string, SSHHost>,
+		readonly description: string,
+	) {
+		this.#allowedHosts = new Set(this.hostNames);
+	}
+
+	async execute(
+		_toolCallId: string,
+		{ host, command, cwd, timeout: rawTimeout = 60 }: SshToolParams,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<SSHToolDetails>,
+		_ctx?: AgentToolContext,
+	): Promise<AgentToolResult<SSHToolDetails>> {
+		if (!this.#allowedHosts.has(host)) {
+			throw new ToolError(`Unknown SSH host: ${host}. Available hosts: ${this.hostNames.join(", ")}`);
+		}
+
+		const hostConfig = this.hostsByName.get(host);
+		if (!hostConfig) {
+			throw new ToolError(`SSH host not loaded: ${host}`);
+		}
+
+		const hostInfo = await ensureHostInfo(hostConfig);
+		const remoteCommand = buildRemoteCommand(command, cwd, hostInfo);
+
+		// Clamp to reasonable range: 1s - 3600s (1 hour)
+		const timeoutSec = clampTimeout("ssh", rawTimeout);
+		const timeoutMs = timeoutSec * 1000;
+
+		const tailBuffer = new TailBuffer(DEFAULT_MAX_BYTES);
+		const { path: artifactPath, id: artifactId } = (await this.session.allocateOutputArtifact?.("ssh")) ?? {};
+
+		const obfuscator = this.session.obfuscator;
+		const maskSecrets = obfuscator?.hasSecrets() ? (t: string) => obfuscator.obfuscate(t) : undefined;
+
+		const result = await executeSSH(hostConfig, remoteCommand, {
+			timeout: timeoutMs,
+			signal,
+			compatEnabled: hostInfo.compatEnabled,
+			artifactPath,
+			artifactId,
+			maskSecrets,
+			onChunk: chunk => {
+				tailBuffer.append(chunk);
+				if (onUpdate) {
+					const preview = maskSecrets ? maskSecrets(tailBuffer.text()) : tailBuffer.text();
+					onUpdate({
+						content: [{ type: "text", text: preview }],
+						details: {},
+					});
+				}
+			},
+		});
+
+		if (result.cancelled) {
+			throw new ToolError(result.output || "Command aborted");
+		}
+
+		const outputText = result.output || "(no output)";
+		const details: SSHToolDetails = {};
+		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
+
+		if (result.exitCode !== 0 && result.exitCode !== undefined) {
+			throw new ToolError(`${outputText}\n\nCommand exited with code ${result.exitCode}`);
+		}
+
+		return resultBuilder.done();
+	}
+}
+
+export async function loadSshTool(session: ToolSession): Promise<SshTool | null> {
+	const { hostNames, hostsByName } = await loadHosts(session);
+	if (hostNames.length === 0) {
+		return null;
+	}
+
+	const descriptionHosts = hostNames
+		.map(name => hostsByName.get(name))
+		.filter((host): host is SSHHost => host !== undefined);
+	const description = await formatDescription(descriptionHosts);
+
+	return new SshTool(session, hostNames, hostsByName, description);
+}
+
+// =============================================================================
+// TUI Renderer
+// =============================================================================
+
+interface SshRenderArgs {
+	host?: string;
+	command?: string;
+	timeout?: number;
+}
+
+interface SshRenderContext {
+	/** Visual lines for truncated output (pre-computed by tool-execution) */
+	visualLines?: string[];
+	/** Number of lines skipped */
+	skippedCount?: number;
+	/** Total visual lines */
+	totalVisualLines?: number;
+}
+
+export const sshToolRenderer = {
+	renderCall(args: SshRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const host = args.host || "…";
+		const command = args.command || "…";
+		const text = renderStatusLine({ icon: "pending", title: "SSH", description: `[${host}] $ ${command}` }, uiTheme);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: {
+			content: Array<{ type: string; text?: string }>;
+			details?: SSHToolDetails;
+		},
+		options: RenderResultOptions & { renderContext?: SshRenderContext },
+		uiTheme: Theme,
+		args?: SshRenderArgs,
+	): Component {
+		const details = result.details;
+		const host = args?.host || "…";
+		const command = args?.command || "…";
+		const header = renderStatusLine({ title: "SSH", description: `[${host}] $ ${command}` }, uiTheme);
+		const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
+		const outputBlock = new CachedOutputBlock();
+
+		return {
+			render: (width: number): string[] => {
+				// REACTIVE: read mutable options at render time
+				const { expanded, renderContext } = options;
+				const output = textContent.trimEnd();
+				const outputLines: string[] = [];
+
+				if (output) {
+					if (expanded) {
+						outputLines.push(...output.split("\n").map(line => uiTheme.fg("toolOutput", line)));
+					} else if (renderContext?.visualLines) {
+						const { visualLines, skippedCount = 0, totalVisualLines = visualLines.length } = renderContext;
+						if (skippedCount > 0) {
+							outputLines.push(
+								uiTheme.fg(
+									"dim",
+									`… (${skippedCount} earlier lines, showing ${visualLines.length} of ${totalVisualLines}) (ctrl+o to expand)`,
+								),
+							);
+						}
+						const styledVisual = visualLines.map(line =>
+							line.includes("\x1b[") ? line : uiTheme.fg("toolOutput", line),
+						);
+						outputLines.push(...styledVisual);
+					} else {
+						const outputLinesRaw = output.split("\n");
+						const maxLines = 5;
+						const displayLines = outputLinesRaw.slice(0, maxLines);
+						const remaining = outputLinesRaw.length - maxLines;
+						outputLines.push(...displayLines.map(line => uiTheme.fg("toolOutput", line)));
+						if (remaining > 0) {
+							outputLines.push(uiTheme.fg("dim", `… (${remaining} more lines) (ctrl+o to expand)`));
+						}
+					}
+				}
+
+				if (details?.meta?.truncation) {
+					const warning = formatStyledTruncationWarning(details.meta, uiTheme);
+					if (warning) outputLines.push(warning);
+				}
+
+				return outputBlock.render(
+					{
+						header,
+						state: "success",
+						sections: [{ label: uiTheme.fg("toolTitle", "Output"), lines: outputLines }],
+						width,
+					},
+					uiTheme,
+				);
+			},
+			invalidate: () => {
+				outputBlock.invalidate();
+			},
+		};
+	},
+	mergeCallAndResult: true,
+};

package/src/tools/submit-result.ts

@@ -0,0 +1,229 @@
+/**
+ * Submit result tool for structured subagent output.
+ *
+ * Subagents must call this tool to finish and return structured JSON output.
+ */
+
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import { dereferenceJsonSchema, sanitizeSchemaForStrictMode } from "@f5xc-salesdemos/pi-ai/utils/schema";
+import type { Static, TSchema } from "@sinclair/typebox";
+import { Type } from "@sinclair/typebox";
+import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
+import { subprocessToolRegistry } from "../task/subprocess-tool-registry";
+import type { ToolSession } from ".";
+import { jtdToJsonSchema } from "./jtd-to-json-schema";
+
+export interface SubmitResultDetails {
+	data: unknown;
+	status: "success" | "aborted";
+	error?: string;
+}
+
+const ajv = new Ajv({ allErrors: true, strict: false, logger: false });
+
+function normalizeSchema(schema: unknown): { normalized?: unknown; error?: string } {
+	if (schema === undefined || schema === null) return {};
+	if (typeof schema === "string") {
+		try {
+			return { normalized: JSON.parse(schema) };
+		} catch (err) {
+			return { error: err instanceof Error ? err.message : String(err) };
+		}
+	}
+	return { normalized: schema };
+}
+
+function formatSchema(schema: unknown): string {
+	if (schema === undefined) return "No schema provided.";
+	if (typeof schema === "string") return schema;
+	try {
+		return JSON.stringify(schema, null, 2);
+	} catch {
+		return "[unserializable schema]";
+	}
+}
+
+function formatAjvErrors(errors: ErrorObject[] | null | undefined): string {
+	if (!errors || errors.length === 0) return "Unknown schema validation error.";
+	return errors
+		.map(err => {
+			const path = err.instancePath ? `${err.instancePath}: ` : "";
+			return `${path}${err.message ?? "invalid"}`;
+		})
+		.join("; ");
+}
+
+export class SubmitResultTool implements AgentTool<TSchema, SubmitResultDetails> {
+	readonly name = "submit_result";
+	readonly label = "Submit Result";
+	readonly description =
+		"Finish the task with structured JSON output. Call exactly once at the end of the task.\n\n" +
+		'Pass `result: { data: <your output> }` for success, or `result: { error: "message" }` for failure.\n' +
+		"The `data`/`error` wrapper is required — do not put your output directly in `result`.";
+	readonly parameters: TSchema;
+	strict = true;
+	lenientArgValidation = true;
+
+	readonly #validate?: ValidateFunction;
+	#schemaValidationFailures = 0;
+
+	constructor(session: ToolSession) {
+		const createParameters = (dataSchema: TSchema): TSchema =>
+			Type.Object(
+				{
+					result: Type.Union([
+						Type.Object({ data: dataSchema }, { description: "Successfully completed the task" }),
+						Type.Object({
+							error: Type.String({ description: "Error message when the task cannot be completed" }),
+						}),
+					]),
+				},
+				{
+					additionalProperties: false,
+					description: "Submit either `data` for success or `error` for failure",
+				},
+			) as TSchema;
+
+		let validate: ValidateFunction | undefined;
+		let dataSchema: TSchema;
+		let parameters: TSchema;
+		let strict = true;
+
+		try {
+			const schemaResult = normalizeSchema(session.outputSchema);
+			// Convert JTD to JSON Schema if needed (auto-detected)
+			const normalizedSchema =
+				schemaResult.normalized !== undefined ? jtdToJsonSchema(schemaResult.normalized) : undefined;
+			let schemaError = schemaResult.error;
+
+			if (!schemaError && normalizedSchema === false) {
+				schemaError = "boolean false schema rejects all outputs";
+			}
+
+			if (normalizedSchema !== undefined && normalizedSchema !== false && !schemaError) {
+				try {
+					validate = ajv.compile(normalizedSchema as Record<string, unknown> | boolean);
+				} catch (err) {
+					schemaError = err instanceof Error ? err.message : String(err);
+				}
+			}
+
+			const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
+			const schemaDescription = schemaError
+				? `Structured JSON output (output schema invalid; accepting unconstrained object): ${schemaError}`
+				: `Structured output matching the schema:\n${schemaHint}`;
+			const sanitizedSchema =
+				!schemaError &&
+				normalizedSchema != null &&
+				typeof normalizedSchema === "object" &&
+				!Array.isArray(normalizedSchema)
+					? sanitizeSchemaForStrictMode(normalizedSchema as Record<string, unknown>)
+					: !schemaError && normalizedSchema === true
+						? {}
+						: undefined;
+
+			if (sanitizedSchema !== undefined) {
+				const resolved = dereferenceJsonSchema({
+					...sanitizedSchema,
+					description: schemaDescription,
+				});
+				dataSchema = Type.Unsafe(resolved as Record<string, unknown>);
+			} else {
+				dataSchema = Type.Record(Type.String(), Type.Any(), {
+					description: schemaError ? schemaDescription : "Structured JSON output (no schema specified)",
+				});
+			}
+			parameters = createParameters(dataSchema);
+			JSON.stringify(parameters);
+			// Verify the final parameters compile with AJV (catches unresolved $ref, etc.)
+			ajv.compile(parameters as Record<string, unknown>);
+		} catch (err) {
+			const errorMsg = err instanceof Error ? err.message : String(err);
+			dataSchema = Type.Record(Type.String(), Type.Any(), {
+				description: `Structured JSON output (schema processing failed: ${errorMsg})`,
+			});
+			parameters = createParameters(dataSchema);
+			validate = undefined;
+			strict = false;
+		}
+
+		this.#validate = validate;
+		this.parameters = parameters;
+		this.strict = strict;
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: Static<TSchema>,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<SubmitResultDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<SubmitResultDetails>> {
+		const raw = params as Record<string, unknown>;
+		const rawResult = raw.result;
+		if (!rawResult || typeof rawResult !== "object" || Array.isArray(rawResult)) {
+			throw new Error("result must be an object containing either data or error");
+		}
+
+		const resultRecord = rawResult as Record<string, unknown>;
+		const errorMessage = typeof resultRecord.error === "string" ? resultRecord.error : undefined;
+		const data = resultRecord.data;
+
+		if (errorMessage !== undefined && data !== undefined) {
+			throw new Error("result cannot contain both data and error");
+		}
+		if (errorMessage === undefined && data === undefined) {
+			throw new Error(
+				'result must contain either `data` or `error`. Use `{result: {data: <your output>}}` for success or `{result: {error: "message"}}` for failure.',
+			);
+		}
+
+		const status = errorMessage !== undefined ? "aborted" : "success";
+		let schemaValidationOverridden = false;
+		if (status === "success") {
+			if (data === undefined || data === null) {
+				throw new Error("data is required when submit_result indicates success");
+			}
+			if (this.#validate && !this.#validate(data)) {
+				this.#schemaValidationFailures++;
+				if (this.#schemaValidationFailures <= 1) {
+					throw new Error(`Output does not match schema: ${formatAjvErrors(this.#validate.errors)}`);
+				}
+				schemaValidationOverridden = true;
+			}
+		}
+
+		const responseText =
+			status === "aborted"
+				? `Task aborted: ${errorMessage}`
+				: schemaValidationOverridden
+					? `Result submitted (schema validation overridden after ${this.#schemaValidationFailures} failed attempt(s)).`
+					: "Result submitted.";
+		return {
+			content: [{ type: "text", text: responseText }],
+			details: { data, status, error: errorMessage },
+		};
+	}
+}
+
+// Register subprocess tool handler for extraction + termination.
+subprocessToolRegistry.register<SubmitResultDetails>("submit_result", {
+	extractData: event => {
+		const details = event.result?.details;
+		if (!details || typeof details !== "object") return undefined;
+		const record = details as Record<string, unknown>;
+		const status = record.status;
+		if (status !== "success" && status !== "aborted") return undefined;
+		return {
+			data: record.data,
+			status,
+			error: typeof record.error === "string" ? record.error : undefined,
+		};
+	},
+	shouldTerminate: event => !event.isError,
+});

package/src/tools/todo-render.ts

@@ -0,0 +1,33 @@
+import chalk from "chalk";
+import type { Theme } from "../modes/theme/theme";
+import type { TodoItem } from "./todo-write";
+
+export function formatTodoLine(item: TodoItem, theme: Theme, prefix: string): string {
+	switch (item.status) {
+		case "completed":
+			return `${prefix}${theme.fg("chromeAccent", theme.todo.done)} ${theme.fg("dim", chalk.strikethrough(item.content))}`;
+		case "in_progress": {
+			const main = `${prefix}${theme.fg("warning", theme.todo.active)} ${theme.fg("warning", chalk.bold(item.content))}`;
+			if (!item.details) return main;
+			const detailLines = item.details.split("\n").map(l => theme.fg("dim", `${prefix}  ${l}`));
+			return [main, ...detailLines].join("\n");
+		}
+		case "abandoned":
+			return `${prefix}${theme.fg("error", theme.todo.abandoned)} ${theme.fg("error", chalk.strikethrough(item.content))}`;
+		default:
+			return `${prefix}${theme.fg("dim", theme.todo.pending)} ${theme.fg("dim", item.content)}`;
+	}
+}
+
+export function renderTodoSummary(tasks: TodoItem[], theme: Theme): string | null {
+	if (tasks.length <= 1) return null;
+	const active = tasks.filter(t => t.status === "in_progress").length;
+	const pending = tasks.filter(t => t.status === "pending").length;
+	const completed = tasks.filter(t => t.status === "completed").length;
+	const parts: string[] = [];
+	if (active > 0) parts.push(`${active} active`);
+	if (pending > 0) parts.push(`${pending} pending`);
+	if (completed > 0) parts.push(`${completed} completed`);
+	if (parts.length === 0) return null;
+	return theme.fg("dim", parts.join(", "));
+}