@nghyane/arcane 0.1.0

package/src/tools/submit-result.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 "@nghyane/arcane-agent";
+import { StringEnum } from "@nghyane/arcane-ai";
+import type { Static, TObject } 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 });
+
+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<TObject, 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" +
+		"If you cannot complete the task, call with status='aborted' and an error message.";
+	readonly parameters: TObject;
+
+	readonly #validate?: ValidateFunction;
+	readonly #schemaError?: string;
+
+	constructor(session: ToolSession) {
+		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 (normalizedSchema !== undefined && !schemaError) {
+			try {
+				this.#validate = ajv.compile(normalizedSchema as any);
+			} catch (err) {
+				schemaError = err instanceof Error ? err.message : String(err);
+			}
+		}
+
+		this.#schemaError = schemaError;
+
+		const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
+
+		// Use actual schema if provided, otherwise fall back to Type.Any
+		// Merge description into the JSON schema for better tool documentation
+		const dataSchema = normalizedSchema
+			? Type.Unsafe({
+					...(normalizedSchema as object),
+					description: `Structured output matching the schema:\n${schemaHint}`,
+				})
+			: Type.Any({ description: "Structured JSON output (no schema specified)" });
+
+		this.parameters = Type.Object({
+			data: Type.Optional(dataSchema),
+			status: Type.Optional(
+				StringEnum(["success", "aborted"], {
+					description: "Use 'aborted' if the task cannot be completed, defaults to 'success'",
+				}),
+			),
+			error: Type.Optional(Type.String({ description: "Error message when status is 'aborted'" })),
+		});
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: Static<TObject>,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<SubmitResultDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<SubmitResultDetails>> {
+		const status = (params.status ?? "success") as "success" | "aborted";
+
+		// Skip validation when aborting - data is optional for aborts
+		if (status === "success") {
+			if (params.data === undefined || params.data === null) {
+				throw new Error("data is required when status is 'success' (got null/undefined)");
+			}
+			if (this.#schemaError) {
+				throw new Error(`Invalid output schema: ${this.#schemaError}`);
+			}
+			if (this.#validate && !this.#validate(params.data)) {
+				throw new Error(`Output does not match schema: ${formatAjvErrors(this.#validate.errors)}`);
+			}
+		}
+
+		const responseText =
+			status === "aborted" ? `Task aborted: ${params.error || "No reason provided"}` : "Result submitted.";
+
+		return {
+			content: [{ type: "text", text: responseText }],
+			details: { data: params.data, status, error: params.error as string | undefined },
+		};
+	}
+}
+
+// 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-write.ts

@@ -0,0 +1,255 @@
+import path from "node:path";
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import { StringEnum } from "@nghyane/arcane-ai";
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
+import { logger, Snowflake } from "@nghyane/arcane-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import chalk from "chalk";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import todoWriteDescription from "../prompts/tools/todo-write.md" with { type: "text" };
+import type { ToolSession } from "../sdk";
+import { renderStatusLine, renderTreeList } from "../tui";
+import { PREVIEW_LIMITS } from "./render-utils";
+
+const todoWriteSchema = Type.Object({
+	todos: Type.Array(
+		Type.Object({
+			id: Type.Optional(Type.String({ description: "Stable todo id" })),
+			content: Type.String({ description: "Task description (e.g., 'Run tests')" }),
+			status: StringEnum(["pending", "in_progress", "completed"]),
+		}),
+		{ description: "The updated todo list" },
+	),
+});
+
+type TodoStatus = "pending" | "in_progress" | "completed";
+
+export interface TodoItem {
+	id: string;
+	content: string;
+	status: TodoStatus;
+}
+
+interface TodoFile {
+	updatedAt: number;
+	todos: TodoItem[];
+}
+
+export interface TodoWriteToolDetails {
+	todos: TodoItem[];
+	updatedAt: number;
+	storage: "session" | "memory";
+}
+
+const TODO_FILE_NAME = "todos.json";
+
+type TodoWriteParams = Static<typeof todoWriteSchema>;
+
+function normalizeTodoStatus(status?: string): TodoStatus {
+	switch (status) {
+		case "in_progress":
+			return "in_progress";
+		case "completed":
+		case "done":
+		case "complete":
+			return "completed";
+		default:
+			return "pending";
+	}
+}
+
+function normalizeTodos(items: Array<{ id?: string; content?: string; status?: string }>): TodoItem[] {
+	return items.map(item => {
+		if (!item.content) {
+			throw new Error("Todo content is required.");
+		}
+		const content = item.content.trim();
+		if (!content) {
+			throw new Error("Todo content cannot be empty.");
+		}
+		return {
+			id: item.id && item.id.trim().length > 0 ? item.id : Snowflake.next(),
+			content,
+			status: normalizeTodoStatus(item.status),
+		};
+	});
+}
+
+function validateSequentialTodos(todos: TodoItem[]): { valid: boolean; error?: string } {
+	if (todos.length === 0) return { valid: true };
+
+	const firstIncompleteIndex = todos.findIndex(todo => todo.status !== "completed");
+	if (firstIncompleteIndex >= 0) {
+		for (let i = firstIncompleteIndex + 1; i < todos.length; i++) {
+			if (todos[i].status === "completed") {
+				return {
+					valid: false,
+					error: `Error: Cannot complete "${todos[i].content}" before completing "${todos[firstIncompleteIndex].content}". Todos must be completed sequentially.`,
+				};
+			}
+		}
+	}
+
+	const inProgressIndices = todos.reduce<number[]>((acc, todo, index) => {
+		if (todo.status === "in_progress") acc.push(index);
+		return acc;
+	}, []);
+
+	for (const idx of inProgressIndices) {
+		const hasPriorIncomplete = todos.slice(0, idx).some(t => t.status === "pending");
+		if (hasPriorIncomplete) {
+			return {
+				valid: false,
+				error: `Cannot start "${todos[idx].content}" while earlier tasks are still pending.`,
+			};
+		}
+	}
+
+	return { valid: true };
+}
+
+async function loadTodoFile(filePath: string): Promise<TodoFile | null> {
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return null;
+	try {
+		const text = await file.text();
+		const data = JSON.parse(text) as TodoFile;
+		if (!data || !Array.isArray(data.todos)) return null;
+		return data;
+	} catch (error) {
+		logger.warn("Failed to read todo file", { path: filePath, error: String(error) });
+		return null;
+	}
+}
+
+function formatTodoSummary(todos: TodoItem[]): string {
+	if (todos.length === 0) return "Todo list cleared.";
+	const completed = todos.filter(t => t.status === "completed").length;
+	const inProgress = todos.filter(t => t.status === "in_progress").length;
+	const pending = todos.filter(t => t.status === "pending").length;
+	return `Saved ${todos.length} todos (${pending} pending, ${inProgress} in progress, ${completed} completed).`;
+}
+
+function formatTodoLine(item: TodoItem, uiTheme: Theme, prefix: string): string {
+	const checkbox = uiTheme.checkbox;
+	switch (item.status) {
+		case "completed":
+			return uiTheme.fg("success", `${prefix}${checkbox.checked} ${chalk.strikethrough(item.content)}`);
+		case "in_progress":
+			return uiTheme.fg("accent", `${prefix}${checkbox.unchecked} ${item.content}`);
+		default:
+			return uiTheme.fg("dim", `${prefix}${checkbox.unchecked} ${item.content}`);
+	}
+}
+
+// =============================================================================
+// Tool Class
+// =============================================================================
+
+export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWriteToolDetails> {
+	readonly name = "todo_write";
+	readonly label = "Todo Write";
+	readonly description: string;
+	readonly parameters = todoWriteSchema;
+	readonly concurrency = "exclusive";
+
+	constructor(private readonly session: ToolSession) {
+		this.description = renderPromptTemplate(todoWriteDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: TodoWriteParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<TodoWriteToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<TodoWriteToolDetails>> {
+		const todos = normalizeTodos(params.todos ?? []);
+		const validation = validateSequentialTodos(todos);
+		if (!validation.valid) {
+			throw new Error(validation.error ?? "Todos must be completed sequentially.");
+		}
+		const updatedAt = Date.now();
+
+		const sessionFile = this.session.getSessionFile();
+		if (!sessionFile) {
+			return {
+				content: [{ type: "text", text: formatTodoSummary(todos) }],
+				details: { todos, updatedAt, storage: "memory" },
+			};
+		}
+
+		const todoPath = path.join(sessionFile.slice(0, -6), TODO_FILE_NAME);
+		const existing = await loadTodoFile(todoPath);
+		const storedTodos = existing?.todos ?? [];
+		const merged = todos.length > 0 ? todos : [];
+		const fileData: TodoFile = { updatedAt, todos: merged };
+
+		try {
+			await Bun.write(todoPath, JSON.stringify(fileData, null, 2));
+		} catch (error) {
+			logger.error("Failed to write todo file", { path: todoPath, error: String(error) });
+			return {
+				content: [{ type: "text", text: "Failed to save todos." }],
+				details: { todos: storedTodos, updatedAt, storage: "session" },
+			};
+		}
+
+		return {
+			content: [{ type: "text", text: formatTodoSummary(merged) }],
+			details: { todos: merged, updatedAt, storage: "session" },
+		};
+	}
+}
+
+// =============================================================================
+// TUI Renderer
+// =============================================================================
+
+interface TodoWriteRenderArgs {
+	todos?: Array<{ id?: string; content?: string; status?: string }>;
+}
+
+export const todoWriteToolRenderer = {
+	renderCall(args: TodoWriteRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const count = args.todos?.length ?? 0;
+		const meta = count > 0 ? [`${count} items`] : ["empty"];
+		const text = renderStatusLine({ icon: "pending", title: "Todo Write", meta }, uiTheme);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: TodoWriteToolDetails },
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		_args?: TodoWriteRenderArgs,
+	): Component {
+		const todos = result.details?.todos ?? [];
+		const header = renderStatusLine(
+			{ icon: "success", title: "Todo Write", meta: [`${todos.length} items`] },
+			uiTheme,
+		);
+		if (todos.length === 0) {
+			const fallback = result.content?.find(c => c.type === "text")?.text ?? "No todos";
+			return new Text(`${header}\n${uiTheme.fg("dim", fallback)}`, 0, 0);
+		}
+
+		const { expanded } = options;
+		const treeLines = renderTreeList(
+			{
+				items: todos,
+				expanded,
+				maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
+				itemType: "todo",
+				renderItem: todo => formatTodoLine(todo, uiTheme, ""),
+			},
+			uiTheme,
+		);
+		const text = [header, ...treeLines].join("\n");
+		return new Text(text, 0, 0);
+	},
+	mergeCallAndResult: true,
+};

package/src/tools/tool-errors.ts

@@ -0,0 +1,92 @@
+/**
+ * Standardized error types for tool execution.
+ *
+ * Tools should throw these instead of returning error text.
+ * The agent loop catches and renders them appropriately.
+ */
+
+/**
+ * Base error for tool execution failures.
+ * Override render() for custom LLM-facing formatting.
+ */
+export class ToolError extends Error {
+	constructor(
+		message: string,
+		readonly context?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = "ToolError";
+	}
+
+	/** Render error for LLM consumption. Override for custom formatting. */
+	render(): string {
+		return this.message;
+	}
+}
+
+/**
+ * Error entry for MultiError.
+ */
+export interface ErrorEntry {
+	message: string;
+	context?: string;
+}
+
+/**
+ * Error with multiple entries (e.g., multiple validation failures, batch errors).
+ */
+export class MultiError extends ToolError {
+	constructor(readonly errors: ErrorEntry[]) {
+		super(errors.map(e => e.message).join("; "));
+		this.name = "MultiError";
+	}
+
+	render(): string {
+		if (this.errors.length === 1) {
+			const e = this.errors[0];
+			return e.context ? `${e.context}: ${e.message}` : e.message;
+		}
+		return this.errors.map(e => (e.context ? `${e.context}: ${e.message}` : e.message)).join("\n");
+	}
+
+	static from(errors: Array<string | ErrorEntry>): MultiError {
+		return new MultiError(errors.map(e => (typeof e === "string" ? { message: e } : e)));
+	}
+}
+
+/**
+ * Error thrown when a tool operation is aborted (e.g., via AbortSignal).
+ */
+export class ToolAbortError extends Error {
+	static readonly MESSAGE = "Operation aborted";
+
+	constructor(message: string = ToolAbortError.MESSAGE) {
+		super(message);
+		this.name = "ToolAbortError";
+	}
+}
+
+/**
+ * Throw ToolAbortError if the signal is aborted.
+ * Use this instead of signal?.throwIfAborted() to get consistent error types.
+ */
+export function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) {
+		const reason = signal.reason instanceof Error ? signal.reason : undefined;
+		throw reason instanceof ToolAbortError ? reason : new ToolAbortError();
+	}
+}
+
+/**
+ * Render an error for LLM consumption.
+ * Handles ToolError.render() and falls back to message/string.
+ */
+export function renderError(e: unknown): string {
+	if (e instanceof ToolError) {
+		return e.render();
+	}
+	if (e instanceof Error) {
+		return e.message;
+	}
+	return String(e);
+}

package/src/tools/tool-result.ts

@@ -0,0 +1,86 @@
+import type { AgentToolResult } from "@nghyane/arcane-agent";
+import type { ImageContent, TextContent } from "@nghyane/arcane-ai";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
+import type { OutputMeta, TruncationOptions, TruncationSummaryOptions, TruncationTextOptions } from "./output-meta";
+import { outputMeta } from "./output-meta";
+
+type ToolContent = Array<TextContent | ImageContent>;
+
+type DetailsWithMeta = { meta?: OutputMeta };
+
+export class ToolResultBuilder<TDetails extends DetailsWithMeta> {
+	#details: TDetails;
+	#meta = outputMeta();
+	#content: ToolContent = [];
+
+	constructor(details?: TDetails) {
+		this.#details = details ?? ({} as TDetails);
+	}
+
+	text(text: string): this {
+		this.#content = [{ type: "text", text }];
+		return this;
+	}
+
+	content(content: ToolContent): this {
+		this.#content = content;
+		return this;
+	}
+
+	truncation(result: TruncationResult, options: TruncationOptions): this {
+		this.#meta.truncation(result, options);
+		return this;
+	}
+
+	truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this {
+		this.#meta.truncationFromSummary(summary, options);
+		return this;
+	}
+
+	truncationFromText(text: string, options: TruncationTextOptions): this {
+		this.#meta.truncationFromText(text, options);
+		return this;
+	}
+
+	limits(limits: { matchLimit?: number; resultLimit?: number; headLimit?: number; columnMax?: number }): this {
+		this.#meta.limits(limits);
+		return this;
+	}
+
+	sourceUrl(value: string): this {
+		this.#meta.sourceUrl(value);
+		return this;
+	}
+
+	sourcePath(value: string): this {
+		this.#meta.sourcePath(value);
+		return this;
+	}
+
+	sourceInternal(value: string): this {
+		this.#meta.sourceInternal(value);
+		return this;
+	}
+
+	diagnostics(summary: string, messages: string[]): this {
+		this.#meta.diagnostics(summary, messages);
+		return this;
+	}
+
+	done(): AgentToolResult<TDetails> {
+		const meta = this.#meta.get();
+		if (meta) {
+			this.#details.meta = meta;
+		}
+		const hasDetails = Object.entries(this.#details).some(([, value]) => value !== undefined);
+
+		return {
+			content: this.#content,
+			details: hasDetails ? this.#details : undefined,
+		};
+	}
+}
+
+export function toolResult<TDetails extends DetailsWithMeta>(details?: TDetails): ToolResultBuilder<TDetails> {
+	return new ToolResultBuilder(details);
+}