@nghyane/arcane 0.1.12 → 0.1.14

package/src/tools/notebook.ts

@@ -5,24 +5,18 @@ import { Text } from "@nghyane/arcane-tui";
 import { untilAborted } from "@nghyane/arcane-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 type { Theme } from "../theme/theme";
+import { renderStatusLine } from "../tui";
+import { formatCount, formatErrorMessage, shortenPath } from "../ui/render-utils";
 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)",
-		}),
-	),
+	action: StringEnum(["edit", "insert", "delete"], { description: "Operation to perform on notebook cell" }),
+	notebook_path: Type.String({ description: "Path to the notebook file" }),
+	cell_index: Type.Number({ description: "Zero-based cell index" }),
+	content: Type.Optional(Type.String({ description: "Cell content (for edit/insert)" })),
+	cell_type: Type.Optional(StringEnum(["code", "markdown"], { description: "Cell type (default: code)" })),
 });
 
 export interface NotebookToolDetails {
@@ -59,7 +53,7 @@ function splitIntoLines(content: string): string[] {
 
 type NotebookParams = Static<typeof notebookSchema>;
 
-export class NotebookTool implements AgentTool<typeof notebookSchema, NotebookToolDetails> {
+export class NotebookTool implements AgentTool<typeof notebookSchema, NotebookToolDetails, Theme> {
 	readonly name = "notebook";
 	readonly label = "Notebook";
 	readonly description =
@@ -183,26 +177,7 @@ export class NotebookTool implements AgentTool<typeof notebookSchema, NotebookTo
 			};
 		});
 	}
-}
-
-// =============================================================================
-// 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;
@@ -217,71 +192,44 @@ export const notebookToolRenderer = {
 			uiTheme,
 		);
 		return new Text(text, 0, 0);
-	},
+	}
 
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: NotebookToolDetails },
-		options: RenderResultOptions,
+		_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({ icon: "error", title: "Notebook", description: notebookPath }, uiTheme);
-			return new Text([header, formatErrorMessage(content.text, uiTheme)].join("\n"), 0, 0);
+			return new Text(formatErrorMessage(content.text, uiTheme), 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 lineCount = details?.cellSource?.length ?? 0;
 		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,
-				);
+		const description = notebookPath ? shortenPath(notebookPath) : "notebook";
+		const meta: string[] = [];
+		if (cellType) meta.push(cellType);
+		if (cellIndex !== undefined) meta.push(`cell ${cellIndex}`);
+		if (lineCount > 0) meta.push(formatCount("line", lineCount));
+		return new Text(
+			renderStatusLine({ icon: "success", title: `Notebook ${action}`, description, meta }, uiTheme),
+			0,
+			0,
+		);
+	}
+}
 
-				cached = { key, lines };
-				return lines;
-			},
-			invalidate: () => {
-				cached = undefined;
-			},
-		};
-	},
-	mergeCallAndResult: true,
-};
+interface NotebookRenderArgs {
+	action: string;
+	notebookPath?: string;
+	notebook_path?: string;
+	cellNumber?: number;
+	cell_index?: number;
+	cellType?: string;
+	cell_type?: string;
+	content?: string;
+}

package/src/tools/oracle.ts

@@ -1,40 +1,40 @@
 import { Type } from "@sinclair/typebox";
-import oracleDescription from "../prompts/tools/oracle.md" with { type: "text" };
-import { createSubagentTool } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent-tool";
 
 const schema = Type.Object({
-	task: Type.String({
-		description:
-			"The task or question for the Oracle. Be specific about what kind of guidance, review, or planning you need.",
-	}),
-	context: Type.Optional(
-		Type.String({
-			description: "Background about the current situation, what you've tried, or relevant information.",
-		}),
-	),
-	files: Type.Optional(
-		Type.Array(Type.String(), {
-			description: "File paths the Oracle should examine as part of its analysis.",
-		}),
-	),
+	task: Type.String({ description: "Question or task for the oracle to reason about" }),
+	context: Type.Optional(Type.String({ description: "Additional context or constraints" })),
+	files: Type.Optional(Type.Array(Type.String(), { description: "File paths for the oracle to examine" })),
 });
 
 function buildTask(p: Record<string, unknown>): string {
-	let task = p.task as string;
-	if (p.context) task += `\n\n## Context\n${p.context}`;
+	const parts: string[] = [p.task as string];
+	if (p.context) parts.push(`\nContext: ${p.context}`);
 	const files = p.files as string[] | undefined;
-	if (files?.length) task += `\n\n## Files to examine\n${files.map(f => `- ${f}`).join("\n")}`;
-	return task;
+	if (files?.length) parts.push(`\nFiles to examine:\n${files.map(f => `- ${f}`).join("\n")}`);
+	return parts.join("\n");
 }
 
-export const OracleTool = createSubagentTool({
+export const oracleConfig: SubagentConfig<typeof schema.properties> = {
 	name: "oracle",
 	label: "Oracle",
 	agent: "oracle",
 	schema,
-	descriptionTemplate: oracleDescription,
-	progressText: "Consulting oracle...",
+	progressText: "Analyzing...",
 	tmpPrefix: "arc-oracle-",
 	buildTask,
-	buildDescription: p => `Oracle: ${(p.task as string).slice(0, 60)}`,
-});
+	buildDescription: p => String(p.task ?? "").slice(0, 80),
+	buildContextLine: p => {
+		const parts: string[] = [];
+		if (p.context) parts.push(`Context: ${String(p.context).split("\n")[0].slice(0, 40)}`);
+		const files = p.files as string[] | undefined;
+		if (files?.length) parts.push(`${files.length} file${files.length > 1 ? "s" : ""}`);
+		return parts.length > 0 ? parts.join(" · ") : null;
+	},
+	toolDescription: [
+		"Senior engineering advisor with deep reasoning. Returns single comprehensive response — no follow-ups.",
+		"WHEN TO USE: Only for complex tasks requiring deep analysis, planning, or debugging across multiple files. Pass files for it to examine, context for background.",
+		"WHEN NOT TO USE: Simple questions answerable by reading code; tasks you can do directly.",
+		"Treat its response as advisory — do independent investigation after, then act.",
+	].join(" "),
+};

package/src/tools/output-meta.ts

@@ -46,7 +46,7 @@ export type SourceMeta =
 /**
  * LSP diagnostic info (for edit/write tools).
  */
-export interface DiagnosticMeta {
+interface DiagnosticMeta {
 	summary: string;
 	messages: string[];
 }
@@ -82,13 +82,13 @@ export interface TruncationOptions {
 	artifactId?: string;
 }
 
-export interface TruncationSummaryOptions {
+interface TruncationSummaryOptions {
 	direction: "head" | "tail";
 	startLine?: number;
 	totalFileLines?: number;
 }
 
-export interface TruncationTextOptions {
+interface TruncationTextOptions {
 	direction: "head" | "tail";
 	totalLines?: number;
 	totalBytes?: number;
@@ -107,7 +107,7 @@ export interface TruncationTextOptions {
  *   .get();
  * ```
  */
-export class OutputMetaBuilder {
+class OutputMetaBuilder {
 	#meta: OutputMeta = {};
 
 	/** Add truncation info from TruncationResult. No-op if not truncated. */
@@ -308,6 +308,91 @@ export function outputMeta(): OutputMetaBuilder {
 	return new OutputMetaBuilder();
 }
 
+// =============================================================================
+// ToolResultBuilder - Fluent API for building AgentToolResult with OutputMeta
+// =============================================================================
+
+type ToolContent = Array<TextContent | ImageContent>;
+
+type DetailsWithMeta = { meta?: OutputMeta };
+
+class ToolResultBuilder<TDetails extends DetailsWithMeta> {
+	#details: TDetails;
+	#meta = new OutputMetaBuilder();
+	#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);
+}
+
 // =============================================================================
 // Notice formatting
 // =============================================================================

package/src/tools/output-utils.ts

@@ -1,7 +1,7 @@
 import { ArtifactManager } from "../session/artifacts";
 import type { ToolSession } from ".";
 
-export interface TailBuffer {
+interface TailBuffer {
 	append(chunk: string): void;
 	text(): string;
 	bytes(): number;
@@ -35,7 +35,7 @@ export function createTailBuffer(maxBytes: number): TailBuffer {
 	};
 }
 
-export function getArtifactManager(session: ToolSession): ArtifactManager | null {
+function getArtifactManager(session: ToolSession): ArtifactManager | null {
 	if (session.artifactManager) {
 		return session.artifactManager;
 	}