pi-mono-all 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# pi-mono-all
+
+## 1.0.0
+
+### Major Changes
+
+- Add the all-in-one pi package and bundle the shared pi-common workspace package into distributed packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - pi-mono-figma@0.2.1
+  - pi-mono-linear@0.2.1

package/LICENCE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Emanuel Casco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/node_modules/pi-common/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "pi-common",
+  "version": "0.1.1",
+  "description": "Shared utilities for pi integration extensions",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./src/index.ts",
+    "./auth": "./src/auth.ts",
+    "./auth-config": "./src/auth-config.ts",
+    "./http-client": "./src/http-client.ts",
+    "./rate-limiter": "./src/rate-limiter.ts",
+    "./cache": "./src/cache.ts",
+    "./errors": "./src/errors.ts",
+    "./tool-result": "./src/tool-result.ts"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/node_modules/pi-common/src/auth-config.ts

@@ -0,0 +1,290 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Key, matchesKey } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { ApiError } from "./errors.js";
+import { MissingAuthTokenError, readAuthToken, setAuthTokenOverride, type ReadAuthTokenOptions } from "./auth.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface AuthConfiguratorOptions extends ReadAuthTokenOptions {
+	service: string;
+	displayName: string;
+	commandName: string;
+	toolName: string;
+	tokenUrl?: string;
+	scopeInstructions: readonly string[];
+}
+
+interface ConfigureAuthParams {
+	force?: boolean;
+}
+
+const ConfigureAuthParamsSchema = Type.Object({
+	force: Type.Optional(Type.Boolean({ description: "Prompt even if a token is already configured. Defaults to false." })),
+});
+
+export function registerAuthConfigurator(pi: ExtensionAPI, options: AuthConfiguratorOptions): void {
+	pi.registerCommand(options.commandName, {
+		description: `Configure ${options.displayName} authentication token securely`,
+		handler: async (args, ctx) => {
+			const force = args.trim().split(/\s+/).includes("--force") || args.trim() === "force";
+			try {
+				const result = await configureAuthToken(ctx, options, { force });
+				ctx.ui.notify(result.message, "info");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: options.toolName,
+		label: `${options.displayName} Auth`,
+		description: `Securely prompt the user for a ${options.displayName} token and store it without exposing it to the model. Use only when auth is missing/expired/invalid, or when the user asks to update the token.`,
+		parameters: ConfigureAuthParamsSchema,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await configureAuthToken(ctx, options, { force: params.force });
+			return {
+				content: [{ type: "text", text: result.message }],
+				details: {
+					service: options.service,
+					stored: result.stored,
+					authPath: options.authPath.join("."),
+					envName: options.envName,
+					envWasSet: result.envWasSet,
+				},
+			};
+		},
+	});
+}
+
+export async function runWithAuthRetry<T>(
+	ctx: ExtensionContext,
+	options: AuthConfiguratorOptions,
+	operation: () => Promise<T>,
+): Promise<T> {
+	try {
+		return await operation();
+	} catch (error) {
+		if (!isAuthError(error)) throw error;
+		if (!ctx.hasUI) throw error;
+		await configureAuthToken(ctx, options, { force: true });
+		return operation();
+	}
+}
+
+export async function configureAuthToken(
+	ctx: ExtensionContext | ExtensionCommandContext,
+	options: AuthConfiguratorOptions,
+	params: ConfigureAuthParams = {},
+): Promise<{ stored: boolean; message: string; envWasSet: boolean }> {
+	if (!params.force) {
+		try {
+			await readAuthToken(options);
+			return {
+				stored: false,
+				envWasSet: Boolean(process.env[options.envName]?.trim()),
+				message: `${options.displayName} token is already configured. Use /${options.commandName} --force to replace it.`,
+			};
+		} catch (error) {
+			if (!(error instanceof MissingAuthTokenError)) throw error;
+		}
+	}
+
+	if (!ctx.hasUI) {
+		throw new Error(`${options.displayName} auth setup requires interactive UI.`);
+	}
+
+	const token = await promptSecret(ctx, `${options.displayName} token`);
+	if (!token) throw new Error(`${options.displayName} token setup cancelled.`);
+
+	await writeAuthToken({ authFile: options.authFile, authPath: options.authPath, token });
+	setAuthTokenOverride(options, token);
+
+	const envWasSet = Boolean(process.env[options.envName]?.trim());
+	const envNote = envWasSet
+		? ` ${options.envName} is set and normally takes precedence; this pi session will use the new token, but update your environment for future sessions.`
+		: "";
+
+	return {
+		stored: true,
+		envWasSet,
+		message: `${options.displayName} token stored in ~/.pi/agent/auth.json at ${options.authPath.join(".")}.${envNote}`,
+	};
+}
+
+export async function writeAuthToken(options: { authPath: readonly string[]; token: string; authFile?: string }): Promise<void> {
+	const authFile = options.authFile ?? resolve(homedir(), ".pi", "agent", "auth.json");
+	await mkdir(dirname(authFile), { recursive: true });
+	await safeChmod(dirname(authFile), 0o700);
+
+	let auth: unknown = {};
+	try {
+		auth = JSON.parse(await readFile(authFile, "utf8")) as unknown;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+
+	const next = auth && typeof auth === "object" ? (auth as Record<string, unknown>) : {};
+	setPath(next, options.authPath, options.token);
+	await writeFile(authFile, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+	await safeChmod(authFile, 0o600);
+}
+
+export function isAuthError(error: unknown): boolean {
+	if (error instanceof MissingAuthTokenError) return true;
+	if (error instanceof ApiError && (error.status === 401 || error.status === 403)) return true;
+	const message = error instanceof Error ? error.message : String(error);
+	return /token expired|invalid token|missing token|no .*token|unauthorized|forbidden|authentication|api key/i.test(message);
+}
+
+async function promptSecret(ctx: ExtensionContext | ExtensionCommandContext, title: string): Promise<string | null> {
+	return ctx.ui.custom<string | null>((tui, _theme, _keybindings, done) => {
+		let value = "";
+		let cached: string[] | undefined;
+
+		function refresh(): void {
+			cached = undefined;
+			tui.requestRender();
+		}
+
+		function row(content: string, contentWidth: number): string {
+			const safe = content.length > contentWidth ? content.slice(0, contentWidth) : content;
+			return `│ ${safe.padEnd(contentWidth)} │`;
+		}
+
+		function maskedInput(contentWidth: number): string {
+			if (value.length === 0) return "> ▌";
+
+			const inputChromeWidth = 3; // "> " + cursor.
+			const availableMaskWidth = Math.max(1, contentWidth - inputChromeWidth);
+			const suffix = value.length > availableMaskWidth ? ` ${value.length} chars` : "";
+			const bulletCount = Math.max(1, Math.min(value.length, availableMaskWidth - suffix.length));
+			return `> ${"•".repeat(bulletCount)}${suffix}▌`;
+		}
+
+		return {
+			render(width: number): string[] {
+				if (cached) return cached;
+				const boxWidth = Math.max(4, Math.min(width, 48));
+				const contentWidth = Math.max(0, boxWidth - 4);
+				const border = `┌${"─".repeat(Math.max(0, boxWidth - 2))}┐`;
+				const bottom = `└${"─".repeat(Math.max(0, boxWidth - 2))}┘`;
+				const lines = [border, row(title, contentWidth), row(maskedInput(contentWidth), contentWidth), bottom];
+				cached = lines;
+				return cached;
+			},
+			handleInput(data: string): void {
+				if (matchesKey(data, Key.escape)) {
+					done(null);
+					return;
+				}
+				if (matchesKey(data, Key.enter)) {
+					done(value.trim() || null);
+					return;
+				}
+				if (matchesKey(data, Key.backspace)) {
+					value = value.slice(0, -1);
+					refresh();
+					return;
+				}
+				if (data === "\u0015") {
+					value = "";
+					refresh();
+					return;
+				}
+				if (data === "\u0016") {
+					void readClipboardText().then((text) => {
+						const sanitized = sanitizeSecretInput(text);
+						if (sanitized) {
+							value += sanitized;
+							refresh();
+						}
+					});
+					return;
+				}
+
+				const sanitized = sanitizeSecretInput(data);
+				if (sanitized) {
+					value += sanitized;
+					refresh();
+				}
+			},
+			invalidate(): void {
+				cached = undefined;
+			},
+		};
+	}, {
+		overlay: true,
+		overlayOptions: {
+			width: 48,
+			minWidth: 32,
+			maxHeight: 4,
+			margin: 1,
+		},
+	});
+}
+
+function sanitizeSecretInput(data: string): string {
+	if (!data) return "";
+
+	// Bracketed paste: ESC [ 200 ~ pasted text ESC [ 201 ~
+	if (data.includes("\u001b[200~") || data.includes("\u001b[201~")) {
+		return data.replace(/\u001b\[200~/g, "").replace(/\u001b\[201~/g, "").replace(/[\r\n\t]/g, "").trim();
+	}
+
+	// Ignore non-paste escape sequences such as arrows and modified keys.
+	if (data.startsWith("\u001b")) return "";
+
+	return data.replace(/[\x00-\x1f\x7f]/g, "").trim();
+}
+
+async function readClipboardText(): Promise<string> {
+	try {
+		if (process.platform === "darwin") return (await execFileAsync("pbpaste", [])).stdout;
+		if (process.platform === "win32") {
+			return (await execFileAsync("powershell.exe", ["-NoProfile", "-Command", "Get-Clipboard"])).stdout;
+		}
+
+		for (const [command, args] of [
+			["wl-paste", ["--no-newline"]],
+			["xclip", ["-selection", "clipboard", "-out"]],
+			["xsel", ["--clipboard", "--output"]],
+		] as const) {
+			try {
+				return (await execFileAsync(command, args)).stdout;
+			} catch {
+				// Try next clipboard provider.
+			}
+		}
+	} catch {
+		// Clipboard access is best-effort; normal terminal paste can still work.
+	}
+	return "";
+}
+
+function setPath(target: Record<string, unknown>, path: readonly string[], value: string): void {
+	let current = target;
+	for (const [index, segment] of path.entries()) {
+		if (index === path.length - 1) {
+			current[segment] = value;
+			return;
+		}
+		const next = current[segment];
+		if (!next || typeof next !== "object" || Array.isArray(next)) current[segment] = {};
+		current = current[segment] as Record<string, unknown>;
+	}
+}
+
+async function safeChmod(path: string, mode: number): Promise<void> {
+	try {
+		await chmod(path, mode);
+	} catch (error) {
+		if (process.platform !== "win32") throw error;
+	}
+}

package/node_modules/pi-common/src/auth.ts

@@ -0,0 +1,63 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export interface ReadAuthTokenOptions {
+	envName: string;
+	authPath: readonly string[];
+	authFile?: string;
+}
+
+const authTokenOverrides = new Map<string, string>();
+
+export function setAuthTokenOverride(options: ReadAuthTokenOptions, token: string): void {
+	authTokenOverrides.set(authTokenKey(options), token);
+}
+
+export function clearAuthTokenOverride(options: ReadAuthTokenOptions): void {
+	authTokenOverrides.delete(authTokenKey(options));
+}
+
+export class MissingAuthTokenError extends Error {
+	constructor(public readonly envName: string, public readonly authPath: readonly string[]) {
+		super(
+			`No auth token found. Set ${envName} or store it in ~/.pi/agent/auth.json at ${authPath.join(".")}`,
+		);
+		this.name = "MissingAuthTokenError";
+	}
+}
+
+export async function readAuthToken(options: ReadAuthTokenOptions): Promise<string> {
+	const override = authTokenOverrides.get(authTokenKey(options));
+	if (override) return override;
+
+	const envValue = process.env[options.envName]?.trim();
+	if (envValue) return envValue;
+
+	const authFile = options.authFile ?? resolve(homedir(), ".pi", "agent", "auth.json");
+	try {
+		const raw = await readFile(authFile, "utf8");
+		const parsed = JSON.parse(raw) as unknown;
+		const value = getPath(parsed, options.authPath);
+		if (typeof value === "string" && value.trim()) return value.trim();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			throw error;
+		}
+	}
+
+	throw new MissingAuthTokenError(options.envName, options.authPath);
+}
+
+function getPath(value: unknown, path: readonly string[]): unknown {
+	let current = value;
+	for (const segment of path) {
+		if (!current || typeof current !== "object" || !(segment in current)) return undefined;
+		current = (current as Record<string, unknown>)[segment];
+	}
+	return current;
+}
+
+function authTokenKey(options: ReadAuthTokenOptions): string {
+	return `${options.envName}:${options.authPath.join(".")}:${options.authFile ?? "default"}`;
+}

package/node_modules/pi-common/src/cache.ts

@@ -0,0 +1,60 @@
+export interface CacheEntry<T> {
+	value: T;
+	expiresAt: number;
+}
+
+export interface TtlCacheOptions {
+	defaultTtlMs: number;
+	maxEntries?: number;
+}
+
+export class TtlCache<T> {
+	private readonly entries = new Map<string, CacheEntry<T>>();
+
+	constructor(private readonly options: TtlCacheOptions) {}
+
+	get(key: string): T | undefined {
+		const entry = this.entries.get(key);
+		if (!entry) return undefined;
+		if (entry.expiresAt <= Date.now()) {
+			this.entries.delete(key);
+			return undefined;
+		}
+		return entry.value;
+	}
+
+	set(key: string, value: T, ttlMs = this.options.defaultTtlMs): void {
+		this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
+		this.evictOverflow();
+	}
+
+	delete(key: string): void {
+		this.entries.delete(key);
+	}
+
+	clear(): void {
+		this.entries.clear();
+	}
+
+	getOrSet(key: string, load: () => Promise<T>, ttlMs = this.options.defaultTtlMs): Promise<T> {
+		const cached = this.get(key);
+		if (cached !== undefined) return Promise.resolve(cached);
+		return load().then((value) => {
+			this.set(key, value, ttlMs);
+			return value;
+		});
+	}
+
+	private evictOverflow(): void {
+		const maxEntries = this.options.maxEntries;
+		if (!maxEntries || this.entries.size <= maxEntries) return;
+		const overflow = this.entries.size - maxEntries;
+		for (const key of Array.from(this.entries.keys()).slice(0, overflow)) {
+			this.entries.delete(key);
+		}
+	}
+}
+
+export function createTtlCache<T>(options: TtlCacheOptions): TtlCache<T> {
+	return new TtlCache<T>(options);
+}

package/node_modules/pi-common/src/errors.ts

@@ -0,0 +1,47 @@
+export interface NormalizedApiError {
+	name: string;
+	message: string;
+	status?: number;
+	service?: string;
+	code?: string;
+	details?: unknown;
+}
+
+export class ApiError extends Error {
+	constructor(
+		message: string,
+		public readonly status?: number,
+		public readonly details?: unknown,
+		public readonly service?: string,
+		public readonly code?: string,
+	) {
+		super(message);
+		this.name = "ApiError";
+	}
+}
+
+export function normalizeApiError(error: unknown, service?: string): NormalizedApiError {
+	if (error instanceof ApiError) {
+		return {
+			name: error.name,
+			message: error.message,
+			status: error.status,
+			service: error.service ?? service,
+			code: error.code,
+			details: error.details,
+		};
+	}
+
+	if (error instanceof Error) {
+		return { name: error.name, message: error.message, service };
+	}
+
+	return { name: "Error", message: String(error), service };
+}
+
+export function errorMessage(error: unknown, service?: string): string {
+	const normalized = normalizeApiError(error, service);
+	const prefix = normalized.service ? `${normalized.service} API error` : "API error";
+	const status = normalized.status ? ` (${normalized.status})` : "";
+	return `${prefix}${status}: ${normalized.message}`;
+}

package/node_modules/pi-common/src/http-client.ts

@@ -0,0 +1,118 @@
+import { ApiError } from "./errors.js";
+
+type HeadersInput = ConstructorParameters<typeof Headers>[0];
+
+export interface HttpClientOptions {
+	baseUrl?: string;
+	timeoutMs?: number;
+	headers?: HeadersInput | (() => HeadersInput | Promise<HeadersInput>);
+	service?: string;
+}
+
+export interface RequestJsonOptions extends Omit<RequestInit, "body" | "headers"> {
+	body?: unknown;
+	headers?: HeadersInput;
+	timeoutMs?: number;
+}
+
+export interface HttpClient {
+	request<T = unknown>(path: string, options?: RequestJsonOptions): Promise<T>;
+	get<T = unknown>(path: string, options?: RequestJsonOptions): Promise<T>;
+	post<T = unknown>(path: string, body?: unknown, options?: RequestJsonOptions): Promise<T>;
+	download(url: string, options?: RequestJsonOptions): Promise<ArrayBuffer>;
+}
+
+export function createHttpClient(options: HttpClientOptions = {}): HttpClient {
+	async function mergedHeaders(extra?: HeadersInput): Promise<Headers> {
+		const headers = new Headers(
+			typeof options.headers === "function" ? await options.headers() : (options.headers ?? undefined),
+		);
+		if (extra) {
+			new Headers(extra).forEach((value, key) => headers.set(key, value));
+		}
+		return headers;
+	}
+
+	async function request<T = unknown>(path: string, requestOptions: RequestJsonOptions = {}): Promise<T> {
+		const url = buildUrl(options.baseUrl, path);
+		const { body, headers: extraHeaders, timeoutMs, ...initOptions } = requestOptions;
+		const headers = await mergedHeaders(extraHeaders);
+		const init: RequestInit = { ...initOptions, headers };
+
+		if (body !== undefined) {
+			if (!headers.has("content-type")) headers.set("content-type", "application/json");
+			init.body = typeof body === "string" ? body : JSON.stringify(body);
+		}
+
+		const response = await fetchWithTimeout(url, init, timeoutMs ?? options.timeoutMs);
+		return parseResponse<T>(response, options.service);
+	}
+
+	async function download(url: string, requestOptions: RequestJsonOptions = {}): Promise<ArrayBuffer> {
+		const { body: _body, headers: _headers, timeoutMs, ...initOptions } = requestOptions;
+		const response = await fetchWithTimeout(url, initOptions, timeoutMs ?? options.timeoutMs);
+		if (!response.ok) {
+			throw new ApiError(response.statusText || `HTTP ${response.status}`, response.status, await safeBody(response), options.service);
+		}
+		return response.arrayBuffer();
+	}
+
+	return {
+		request,
+		get: (path, requestOptions) => request(path, { ...requestOptions, method: "GET" }),
+		post: (path, body, requestOptions) => request(path, { ...requestOptions, method: "POST", body }),
+		download,
+	};
+}
+
+function buildUrl(baseUrl: string | undefined, path: string): string {
+	if (/^https?:\/\//i.test(path)) return path;
+	if (!baseUrl) return path;
+	return `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+}
+
+async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs = 30_000): Promise<Response> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(new Error(`Request timed out after ${timeoutMs}ms`)), timeoutMs);
+	const upstream = init.signal;
+	const abort = () => controller.abort(upstream?.reason);
+	upstream?.addEventListener("abort", abort, { once: true });
+
+	try {
+		return await fetch(url, { ...init, signal: controller.signal });
+	} finally {
+		clearTimeout(timeout);
+		upstream?.removeEventListener("abort", abort);
+	}
+}
+
+async function parseResponse<T>(response: Response, service?: string): Promise<T> {
+	const body = await safeBody(response);
+	if (!response.ok) {
+		throw new ApiError(extractErrorMessage(body) ?? response.statusText ?? `HTTP ${response.status}`, response.status, body, service);
+	}
+	return body as T;
+}
+
+async function safeBody(response: Response): Promise<unknown> {
+	const text = await response.text();
+	if (!text) return undefined;
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		return text;
+	}
+}
+
+function extractErrorMessage(body: unknown): string | undefined {
+	if (!body || typeof body !== "object") return undefined;
+	const record = body as Record<string, unknown>;
+	if (typeof record.message === "string") return record.message;
+	if (typeof record.err === "string") return record.err;
+	const errors = record.errors;
+	if (Array.isArray(errors) && errors.length > 0) {
+		const first = errors[0] as Record<string, unknown>;
+		if (typeof first.message === "string") return first.message;
+	}
+	return undefined;
+}

package/node_modules/pi-common/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./auth.js";
+export * from "./auth-config.js";
+export * from "./http-client.js";
+export * from "./rate-limiter.js";
+export * from "./cache.js";
+export * from "./errors.js";
+export * from "./tool-result.js";

package/node_modules/pi-common/src/rate-limiter.ts

@@ -0,0 +1,32 @@
+export interface RateLimiterOptions {
+	minIntervalMs: number;
+}
+
+export interface RateLimiter {
+	schedule<T>(operation: () => Promise<T>): Promise<T>;
+}
+
+export function createRateLimiter(options: RateLimiterOptions): RateLimiter {
+	let lastStart = 0;
+	let chain: Promise<unknown> = Promise.resolve();
+
+	return {
+		schedule<T>(operation: () => Promise<T>): Promise<T> {
+			const run = async (): Promise<T> => {
+				const now = Date.now();
+				const waitMs = Math.max(0, lastStart + options.minIntervalMs - now);
+				if (waitMs > 0) await sleep(waitMs);
+				lastStart = Date.now();
+				return operation();
+			};
+
+			const next = chain.then(run, run);
+			chain = next.catch(() => undefined);
+			return next;
+		},
+	};
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/node_modules/pi-common/src/tool-result.ts

@@ -0,0 +1,27 @@
+export interface ToolResultOptions {
+	maxChars?: number;
+}
+
+export interface ToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+}
+
+const DEFAULT_MAX_CHARS = 40_000;
+
+export function textToolResult(text: string, details: Record<string, unknown> = {}): ToolResult {
+	return { content: [{ type: "text", text }], details };
+}
+
+export function jsonToolResult(data: unknown, options: ToolResultOptions = {}): ToolResult {
+	const pretty = JSON.stringify(data, null, 2);
+	const maxChars = options.maxChars ?? DEFAULT_MAX_CHARS;
+	const truncated = pretty.length > maxChars;
+	const text = truncated
+		? `${pretty.slice(0, maxChars)}\n\n[truncated ${pretty.length - maxChars} characters; narrow the query or request specific IDs]`
+		: pretty;
+	return {
+		content: [{ type: "text", text }],
+		details: { truncated, characters: pretty.length },
+	};
+}