@nghyane/arcane 0.1.0

package/src/tools/output-meta.ts

@@ -0,0 +1,459 @@
+/**
+ * Structured metadata for tool outputs.
+ *
+ * Tools populate details.meta using the fluent OutputMetaBuilder.
+ * The tool wrapper automatically formats and appends notices at message boundary.
+ */
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolExecFn,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@nghyane/arcane-agent";
+import type { ImageContent, TextContent } from "@nghyane/arcane-ai";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
+import { formatBytes } from "../session/streaming-output";
+import { renderError } from "./tool-errors";
+
+/**
+ * Truncation metadata for the output notice.
+ */
+export interface TruncationMeta {
+	direction: "head" | "tail";
+	truncatedBy: "lines" | "bytes";
+	totalLines: number;
+	totalBytes: number;
+	outputLines: number;
+	outputBytes: number;
+	maxBytes?: number;
+	/** Line range shown (1-indexed, inclusive) */
+	shownRange?: { start: number; end: number };
+	/** Artifact ID if full output was saved */
+	artifactId?: string;
+	/** Next offset for pagination (head truncation only) */
+	nextOffset?: number;
+}
+
+/**
+ * Source resolution info for the output.
+ */
+export type SourceMeta =
+	| { type: "path"; value: string }
+	| { type: "url"; value: string }
+	| { type: "internal"; value: string };
+
+/**
+ * LSP diagnostic info (for edit/write tools).
+ */
+export interface DiagnosticMeta {
+	summary: string;
+	messages: string[];
+}
+
+/**
+ * Limit-specific notices.
+ */
+export interface LimitsMeta {
+	matchLimit?: { reached: number; suggestion: number };
+	resultLimit?: { reached: number; suggestion: number };
+	headLimit?: { reached: number; suggestion: number };
+	columnTruncated?: { maxColumn: number };
+}
+
+/**
+ * Structured metadata for tool outputs.
+ */
+export interface OutputMeta {
+	truncation?: TruncationMeta;
+	source?: SourceMeta;
+	diagnostics?: DiagnosticMeta;
+	limits?: LimitsMeta;
+}
+
+// =============================================================================
+// OutputMetaBuilder - Fluent API for building OutputMeta
+// =============================================================================
+
+export interface TruncationOptions {
+	direction: "head" | "tail";
+	startLine?: number;
+	totalFileLines?: number;
+	artifactId?: string;
+}
+
+export interface TruncationSummaryOptions {
+	direction: "head" | "tail";
+	startLine?: number;
+	totalFileLines?: number;
+}
+
+export interface TruncationTextOptions {
+	direction: "head" | "tail";
+	totalLines?: number;
+	totalBytes?: number;
+	maxBytes?: number;
+}
+
+/**
+ * Fluent builder for OutputMeta.
+ *
+ * @example
+ * ```ts
+ * details.meta = outputMeta()
+ *   .truncation(truncation, { direction: "head" })
+ *   .matchLimit(limitReached ? effectiveLimit : 0)
+ *   .columnTruncated(linesTruncated ? DEFAULT_MAX_COLUMN : 0)
+ *   .get();
+ * ```
+ */
+export class OutputMetaBuilder {
+	#meta: OutputMeta = {};
+
+	/** Add truncation info from TruncationResult. No-op if not truncated. */
+	truncation(result: TruncationResult, options: TruncationOptions): this {
+		if (!result.truncated) return this;
+
+		const { direction, startLine = 1, totalFileLines, artifactId } = options;
+
+		let shownStart: number;
+		let shownEnd: number;
+
+		if (direction === "tail") {
+			shownStart = result.totalLines - result.outputLines + 1;
+			shownEnd = result.totalLines;
+		} else {
+			shownStart = startLine;
+			shownEnd = startLine + result.outputLines - 1;
+		}
+
+		this.#meta.truncation = {
+			direction,
+			truncatedBy: result.truncatedBy!,
+			totalLines: totalFileLines ?? result.totalLines,
+			totalBytes: result.totalBytes,
+			outputLines: result.outputLines,
+			outputBytes: result.outputBytes,
+			maxBytes: result.maxBytes,
+			shownRange: { start: shownStart, end: shownEnd },
+			artifactId,
+			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
+		};
+
+		return this;
+	}
+
+	/** Add truncation info from OutputSummary. No-op if not truncated. */
+	truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this {
+		if (!summary.truncated) return this;
+
+		const { direction, startLine = 1, totalFileLines } = options;
+		const totalLines = totalFileLines ?? summary.totalLines;
+		const truncatedBy: "lines" | "bytes" =
+			summary.outputBytes < summary.totalBytes
+				? "bytes"
+				: summary.outputLines < summary.totalLines
+					? "lines"
+					: "bytes";
+
+		let shownStart: number;
+		let shownEnd: number;
+
+		if (direction === "tail") {
+			shownStart = totalLines - summary.outputLines + 1;
+			shownEnd = totalLines;
+		} else {
+			shownStart = startLine;
+			shownEnd = startLine + summary.outputLines - 1;
+		}
+
+		this.#meta.truncation = {
+			direction,
+			truncatedBy,
+			totalLines,
+			totalBytes: summary.totalBytes,
+			outputLines: summary.outputLines,
+			outputBytes: summary.outputBytes,
+			shownRange: { start: shownStart, end: shownEnd },
+			artifactId: summary.artifactId,
+			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
+		};
+
+		return this;
+	}
+
+	/** Add truncation info from truncated output text. No-op if truncation not detected. */
+	truncationFromText(text: string, options: TruncationTextOptions): this {
+		const outputLines = text.length > 0 ? text.split("\n").length : 0;
+		const outputBytes = Buffer.byteLength(text, "utf-8");
+		const totalLines = options.totalLines ?? outputLines;
+		const totalBytes = options.totalBytes ?? outputBytes;
+
+		const truncated = totalLines > outputLines || totalBytes > outputBytes || false;
+		if (!truncated) return this;
+
+		const truncatedBy: "lines" | "bytes" =
+			options.maxBytes && outputBytes >= options.maxBytes
+				? "bytes"
+				: totalBytes > outputBytes
+					? "bytes"
+					: totalLines > outputLines
+						? "lines"
+						: "bytes";
+
+		let shownStart: number;
+		let shownEnd: number;
+
+		if (options.direction === "tail") {
+			shownStart = totalLines - outputLines + 1;
+			shownEnd = totalLines;
+		} else {
+			shownStart = 1;
+			shownEnd = outputLines;
+		}
+
+		this.#meta.truncation = {
+			direction: options.direction,
+			truncatedBy,
+			totalLines,
+			totalBytes,
+			outputLines,
+			outputBytes,
+			maxBytes: options.maxBytes,
+			shownRange: { start: shownStart, end: shownEnd },
+			nextOffset: options.direction === "head" ? shownEnd + 1 : undefined,
+		};
+
+		return this;
+	}
+
+	/** Add match limit notice. No-op if reached <= 0. */
+	matchLimit(reached: number, suggestion = reached * 2): this {
+		if (reached <= 0) return this;
+		this.#meta.limits = { ...this.#meta.limits, matchLimit: { reached, suggestion } };
+		return this;
+	}
+
+	/** Add limit notices in one call. */
+	limits(limits: { matchLimit?: number; resultLimit?: number; headLimit?: number; columnMax?: number }): this {
+		if (limits.matchLimit !== undefined) {
+			this.matchLimit(limits.matchLimit);
+		}
+		if (limits.resultLimit !== undefined) {
+			this.resultLimit(limits.resultLimit);
+		}
+		if (limits.headLimit !== undefined) {
+			this.headLimit(limits.headLimit);
+		}
+		if (limits.columnMax !== undefined) {
+			this.columnTruncated(limits.columnMax);
+		}
+		return this;
+	}
+
+	/** Add result limit notice. No-op if reached <= 0. */
+	resultLimit(reached: number, suggestion = reached * 2): this {
+		if (reached <= 0) return this;
+		this.#meta.limits = { ...this.#meta.limits, resultLimit: { reached, suggestion } };
+		return this;
+	}
+
+	/** Add limit notice for head truncation. No-op if reached <= 0. */
+	headLimit(reached: number, suggestion = reached * 2): this {
+		if (reached <= 0) return this;
+		this.#meta.limits = { ...this.#meta.limits, headLimit: { reached, suggestion } };
+		return this;
+	}
+
+	/** Add column truncation notice. No-op if maxColumn <= 0. */
+	columnTruncated(maxColumn: number): this {
+		if (maxColumn <= 0) return this;
+		this.#meta.limits = { ...this.#meta.limits, columnTruncated: { maxColumn } };
+		return this;
+	}
+
+	/** Add source path info. */
+	sourcePath(value: string): this {
+		this.#meta.source = { type: "path", value };
+		return this;
+	}
+
+	/** Add source URL info. */
+	sourceUrl(value: string): this {
+		this.#meta.source = { type: "url", value };
+		return this;
+	}
+
+	/** Add internal URL source info (skill://, agent://, artifact://). */
+	sourceInternal(value: string): this {
+		this.#meta.source = { type: "internal", value };
+		return this;
+	}
+
+	/** Add LSP diagnostics. No-op if no messages. */
+	diagnostics(summary: string, messages: string[]): this {
+		if (messages.length === 0) return this;
+		this.#meta.diagnostics = { summary, messages };
+		return this;
+	}
+
+	/** Get the built OutputMeta, or undefined if empty. */
+	get(): OutputMeta | undefined {
+		return Object.keys(this.#meta).length > 0 ? this.#meta : undefined;
+	}
+}
+
+/** Create a new OutputMetaBuilder. */
+export function outputMeta(): OutputMetaBuilder {
+	return new OutputMetaBuilder();
+}
+
+// =============================================================================
+// Notice formatting
+// =============================================================================
+
+/**
+ * Format notices from OutputMeta for LLM consumption.
+ * Returns empty string if no notices needed.
+ */
+export function formatOutputNotice(meta: OutputMeta | undefined): string {
+	if (!meta) return "";
+
+	const parts: string[] = [];
+
+	// Truncation notice
+	if (meta.truncation) {
+		const t = meta.truncation;
+		const range = t.shownRange;
+		let notice: string;
+
+		if (range && range.end >= range.start) {
+			notice = `Showing lines ${range.start}-${range.end} of ${t.totalLines}`;
+		} else {
+			notice = `Showing ${t.outputLines} of ${t.totalLines} lines`;
+		}
+
+		if (t.truncatedBy === "bytes") {
+			const maxBytes = t.maxBytes ?? t.outputBytes;
+			notice += ` (${formatBytes(maxBytes)} limit)`;
+		}
+
+		if (t.nextOffset != null) {
+			notice += `. Use offset=${t.nextOffset} to continue`;
+		}
+		if (t.artifactId != null) {
+			notice += `. Full: artifact://${t.artifactId}`;
+		}
+
+		parts.push(notice);
+	}
+
+	// Limit notices
+	if (meta.limits?.matchLimit) {
+		const l = meta.limits.matchLimit;
+		parts.push(`${l.reached} matches limit reached. Use limit=${l.suggestion} for more`);
+	}
+	if (meta.limits?.resultLimit) {
+		const l = meta.limits.resultLimit;
+		parts.push(`${l.reached} results limit reached. Use limit=${l.suggestion} for more`);
+	}
+	if (meta.limits?.headLimit) {
+		const l = meta.limits.headLimit;
+		parts.push(`${l.reached} results limit reached. Use limit=${l.suggestion} for more`);
+	}
+	if (meta.limits?.columnTruncated) {
+		parts.push(`Some lines truncated to ${meta.limits.columnTruncated.maxColumn} chars`);
+	}
+
+	// Diagnostics
+	let diagnosticsNotice = "";
+	if (meta.diagnostics && meta.diagnostics.messages.length > 0) {
+		const d = meta.diagnostics;
+		diagnosticsNotice = `\n\nLSP Diagnostics (${d.summary}):\n  ${d.messages.join("\n  ")}`;
+	}
+
+	const notice = parts.length ? `\n\n[${parts.join(". ")}]` : "";
+	return notice + diagnosticsNotice;
+}
+
+// =============================================================================
+// Tool wrapper
+// =============================================================================
+
+/**
+ * Append output notice to tool result content if meta is present.
+ */
+function appendOutputNotice(
+	content: Array<{ type: string; text?: string }>,
+	meta: OutputMeta | undefined,
+): Array<{ type: string; text?: string }> {
+	const notice = formatOutputNotice(meta);
+	if (!notice) return content;
+
+	const result = [...content];
+	for (let i = result.length - 1; i >= 0; i--) {
+		if (result[i].type === "text" && result[i].text != null) {
+			result[i] = { ...result[i], text: result[i].text + notice };
+			return result;
+		}
+	}
+
+	result.push({ type: "text", text: notice.trim() });
+	return result;
+}
+
+const kUnwrappedExecute = Symbol("OutputMeta.UnwrappedExecute");
+
+async function wrappedExecute(
+	this: AgentTool & { [kUnwrappedExecute]: AgentToolExecFn },
+	toolCallId: string,
+	params: any,
+	signal?: AbortSignal,
+	onUpdate?: AgentToolUpdateCallback,
+	context?: AgentToolContext,
+): Promise<AgentToolResult> {
+	const originalExecute = this[kUnwrappedExecute];
+
+	try {
+		// Append notices from meta
+		const result = await originalExecute.call(this, toolCallId, params, signal, onUpdate, context);
+		const meta = (result.details as { meta?: OutputMeta } | undefined)?.meta;
+		if (meta) {
+			return {
+				...result,
+				content: appendOutputNotice(result.content, meta) as (TextContent | ImageContent)[],
+			};
+		}
+		return result;
+	} catch (e) {
+		// Re-throw with formatted message so agent-loop sets isError flag
+		throw new Error(renderError(e));
+	}
+}
+
+/**
+ * Wrap a tool to:
+ * 1. Automatically append output notices based on details.meta
+ * 2. Handle ToolError rendering
+ */
+export function wrapToolWithMetaNotice<T extends AgentTool<any, any, any>>(tool: T): T {
+	if (kUnwrappedExecute in tool) {
+		return tool;
+	}
+
+	const originalExecute = tool.execute;
+
+	return Object.defineProperties(tool, {
+		[kUnwrappedExecute]: {
+			value: originalExecute,
+			enumerable: false,
+			configurable: true,
+		},
+		execute: {
+			value: wrappedExecute,
+			enumerable: false,
+			configurable: true,
+			writable: true,
+		},
+	});
+}

package/src/tools/output-utils.ts

@@ -0,0 +1,63 @@
+import { ArtifactManager } from "../session/artifacts";
+import type { ToolSession } from ".";
+
+export interface TailBuffer {
+	append(chunk: string): void;
+	text(): string;
+	bytes(): number;
+}
+
+export function createTailBuffer(maxBytes: number): TailBuffer {
+	let buffer = "";
+	let bufferBytes = 0;
+
+	const append = (text: string) => {
+		if (!text) return;
+		const chunkBytes = Buffer.byteLength(text, "utf-8");
+		buffer += text;
+		bufferBytes += chunkBytes;
+
+		if (bufferBytes > maxBytes) {
+			const buf = Buffer.from(buffer, "utf-8");
+			let start = Math.max(0, buf.length - maxBytes);
+			while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+				start++;
+			}
+			buffer = buf.subarray(start).toString("utf-8");
+			bufferBytes = Buffer.byteLength(buffer, "utf-8");
+		}
+	};
+
+	return {
+		append,
+		text: () => buffer,
+		bytes: () => bufferBytes,
+	};
+}
+
+export function getArtifactManager(session: ToolSession): ArtifactManager | null {
+	if (session.artifactManager) {
+		return session.artifactManager;
+	}
+	const sessionFile = session.getSessionFile();
+	if (!sessionFile) {
+		return null;
+	}
+	const manager = new ArtifactManager(sessionFile);
+	session.artifactManager = manager;
+	return manager;
+}
+
+export async function allocateOutputArtifact(
+	session: ToolSession,
+	toolType: string,
+): Promise<{ artifactPath?: string; artifactId?: string }> {
+	const manager = getArtifactManager(session);
+	if (!manager) return {};
+	try {
+		const allocation = await manager.allocatePath(toolType);
+		return { artifactPath: allocation.path, artifactId: allocation.id };
+	} catch {
+		return {};
+	}
+}

package/src/tools/path-utils.ts

@@ -0,0 +1,116 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const NARROW_NO_BREAK_SPACE = "\u202F";
+
+function normalizeUnicodeSpaces(str: string): string {
+	return str.replace(UNICODE_SPACES, " ");
+}
+
+function tryMacOSScreenshotPath(filePath: string): string {
+	return filePath.replace(/ (AM|PM)\./g, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+
+function tryNFDVariant(filePath: string): string {
+	// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD
+	return filePath.normalize("NFD");
+}
+
+function tryCurlyQuoteVariant(filePath: string): string {
+	// macOS uses U+2019 (right single quotation mark) in screenshot names like "Capture d'écran"
+	// Users typically type U+0027 (straight apostrophe)
+	return filePath.replace(/'/g, "\u2019");
+}
+
+function fileExists(filePath: string): boolean {
+	try {
+		fs.accessSync(filePath, fs.constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function normalizeAtPrefix(filePath: string): string {
+	if (!filePath.startsWith("@")) return filePath;
+
+	const withoutAt = filePath.slice(1);
+
+	// We only treat a leading "@" as a shorthand for a small set of well-known
+	// syntaxes. This avoids mangling literal paths like "@my-file.txt".
+	if (
+		withoutAt.startsWith("/") ||
+		withoutAt === "~" ||
+		withoutAt.startsWith("~/") ||
+		// Windows absolute paths (drive letters / UNC / root-relative)
+		path.win32.isAbsolute(withoutAt) ||
+		// Internal URL shorthands
+		withoutAt.startsWith("agent://") ||
+		withoutAt.startsWith("artifact://") ||
+		withoutAt.startsWith("skill://") ||
+		withoutAt.startsWith("rule://")
+	) {
+		return withoutAt;
+	}
+
+	return filePath;
+}
+
+export function expandPath(filePath: string): string {
+	const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
+	if (normalized === "~") {
+		return os.homedir();
+	}
+	if (normalized.startsWith("~/")) {
+		return os.homedir() + normalized.slice(1);
+	}
+	return normalized;
+}
+
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath: string, cwd: string): string {
+	const expanded = expandPath(filePath);
+	if (path.isAbsolute(expanded)) {
+		return expanded;
+	}
+	return path.resolve(cwd, expanded);
+}
+
+export function resolveReadPath(filePath: string, cwd: string): string {
+	const resolved = resolveToCwd(filePath, cwd);
+
+	if (fileExists(resolved)) {
+		return resolved;
+	}
+
+	// Try macOS AM/PM variant (narrow no-break space before AM/PM)
+	const amPmVariant = tryMacOSScreenshotPath(resolved);
+	if (amPmVariant !== resolved && fileExists(amPmVariant)) {
+		return amPmVariant;
+	}
+
+	// Try NFD variant (macOS stores filenames in NFD form)
+	const nfdVariant = tryNFDVariant(resolved);
+	if (nfdVariant !== resolved && fileExists(nfdVariant)) {
+		return nfdVariant;
+	}
+
+	// Try curly quote variant (macOS uses U+2019 in screenshot names)
+	const curlyVariant = tryCurlyQuoteVariant(resolved);
+	if (curlyVariant !== resolved && fileExists(curlyVariant)) {
+		return curlyVariant;
+	}
+
+	// Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
+	const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+	if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {
+		return nfdCurlyVariant;
+	}
+
+	return resolved;
+}

package/src/tools/puppeteer/00_stealth_tampering.txt

@@ -0,0 +1,63 @@
+// Helper to generate native code string
+const makeNativeString = (name) =>
+  "function " + (name || "") + "() { [native code] }";
+
+// Patch toString for common fingerprinted functions
+const patchedFns = [
+  [window.alert, "alert"],
+  [window.prompt, "prompt"],
+  [window.confirm, "confirm"],
+  [window.fetch, "fetch"],
+  [window.XMLHttpRequest, "XMLHttpRequest"],
+  [window.WebSocket, "WebSocket"],
+  [window.localStorage?.getItem, "getItem"],
+  [window.localStorage?.setItem, "setItem"],
+  [window.navigator.geolocation?.getCurrentPosition, "getCurrentPosition"],
+  [window.navigator.geolocation?.watchPosition, "watchPosition"],
+  [window.CanvasRenderingContext2D?.prototype.getImageData, "getImageData"],
+  [window.HTMLCanvasElement?.prototype.toDataURL, "toDataURL"],
+  [window.HTMLCanvasElement?.prototype.toBlob, "toBlob"],
+];
+
+for (const [fn, name] of patchedFns) {
+  if (typeof fn === "function") {
+    const nativeStr = makeNativeString(name);
+    Object_defineProperty(fn, "toString", {
+      value: function toString() { return nativeStr; },
+      writable: false,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+}
+
+// Patch Object.getOwnPropertyDescriptor to return native-looking descriptors
+Object.getOwnPropertyDescriptor = function (obj, prop) {
+  const descriptor = Object_getOwnPropertyDescriptor.call(this, obj, prop);
+  if (!descriptor) return descriptor;
+
+  // Make patched descriptors look native
+  if (descriptor.get && typeof descriptor.get === "function") {
+    const getStr = makeNativeString("get " + String(prop));
+    Object_defineProperty(descriptor.get, "toString", {
+      value: function toString() { return getStr; },
+      writable: false,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+  if (descriptor.set && typeof descriptor.set === "function") {
+    const setStr = makeNativeString("set " + String(prop));
+    Object_defineProperty(descriptor.set, "toString", {
+      value: function toString() { return setStr; },
+      writable: false,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  return descriptor;
+};
+
+// Cleanup
+document.head.removeChild(iframe);