@ottocode/server 0.1.264 → 0.1.266

package/src/runtime/agent/registry.ts

@@ -3,26 +3,7 @@ import type { ProviderName } from '@ottocode/sdk';
 import { catalog } from '@ottocode/sdk';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-// Embed default agent prompts; only user overrides read from disk.
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-import AGENT_BUILD from '@ottocode/sdk/prompts/agents/build.txt' with {
-	type: 'text',
-};
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-import AGENT_PLAN from '@ottocode/sdk/prompts/agents/plan.txt' with {
-	type: 'text',
-};
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-import AGENT_GENERAL from '@ottocode/sdk/prompts/agents/general.txt' with {
-	type: 'text',
-};
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-import AGENT_INIT from '@ottocode/sdk/prompts/agents/init.txt' with {
-	type: 'text',
-};
-import AGENT_RESEARCH from '@ottocode/sdk/prompts/agents/research.txt' with {
-	type: 'text',
-};
+import { resolveAgentPrompt } from './registry-prompts.ts';
 
 export type AgentConfig = {
 	name: string;
@@ -291,109 +272,11 @@ export async function resolveAgentConfig(
 	}
 	const agents = await loadAgentsConfig(projectRoot);
 	const entry = agents[name];
-	let prompt = '';
-	let promptSource: string = 'none';
-
-	// Override files: project first, then global
-	const globalAgentsDir = getGlobalAgentsDir();
-	const localDirTxt = `${projectRoot}/.otto/agents/${name}/agent.txt`.replace(
-		/\\/g,
-		'/',
-	);
-	const localDirMd = `${projectRoot}/.otto/agents/${name}/agent.md`.replace(
-		/\\/g,
-		'/',
-	);
-	const localFlatTxt = `${projectRoot}/.otto/agents/${name}.txt`.replace(
-		/\\/g,
-		'/',
-	);
-	const localFlatMd = `${projectRoot}/.otto/agents/${name}.md`.replace(
-		/\\/g,
-		'/',
-	);
-	const globalDirTxt = `${globalAgentsDir}/${name}/agent.txt`.replace(
-		/\\/g,
-		'/',
-	);
-	const globalDirMd = `${globalAgentsDir}/${name}/agent.md`.replace(/\\/g, '/');
-	const globalFlatTxt = `${globalAgentsDir}/${name}.txt`.replace(/\\/g, '/');
-	const globalFlatMd = `${globalAgentsDir}/${name}.md`.replace(/\\/g, '/');
-	const files = [
-		localDirMd,
-		localFlatMd,
-		localDirTxt,
-		localFlatTxt,
-		globalDirMd,
-		globalFlatMd,
-		globalDirTxt,
-		globalFlatTxt,
-	];
-	for (const p of files) {
-		try {
-			const f = Bun.file(p);
-			if (await f.exists()) {
-				const text = await f.text();
-				if (text.trim()) {
-					prompt = text;
-					promptSource = `file:${p}`;
-					break;
-				}
-			}
-		} catch {}
-	}
-
-	// If agents.json provides a 'prompt' field, accept inline content or a relative/absolute path
-	if (entry?.prompt) {
-		const p = entry.prompt.trim();
-		if (
-			/[.](md|txt)$/i.test(p) ||
-			p.startsWith('.') ||
-			p.startsWith('/') ||
-			p.startsWith('~/')
-		) {
-			const candidates: string[] = [];
-			if (p.startsWith('~/')) {
-				const home = process.env.HOME || process.env.USERPROFILE || '';
-				candidates.push(`${home}/${p.slice(2)}`);
-			} else if (p.startsWith('/')) candidates.push(p);
-			else candidates.push(`${projectRoot}/${p}`.replace(/\\/g, '/'));
-			for (const candidate of candidates) {
-				const pf = Bun.file(candidate);
-				if (await pf.exists()) {
-					const t = await pf.text();
-					if (t.trim()) {
-						prompt = t;
-						promptSource = `agents.json:file:${candidate}`;
-						break;
-					}
-				}
-			}
-		} else {
-			prompt = p;
-			promptSource = 'agents.json:inline';
-		}
-	}
-
-	// Fallback: use embedded defaults (plan/build/general); else default to build
-	if (!prompt) {
-		const byName = (n: string): string | undefined => {
-			if (n === 'build') return AGENT_BUILD;
-			if (n === 'plan') return AGENT_PLAN;
-			if (n === 'general') return AGENT_GENERAL;
-			if (n === 'init') return AGENT_INIT;
-			if (n === 'research') return AGENT_RESEARCH;
-			return undefined;
-		};
-		const candidate = byName(name)?.trim();
-		if (candidate?.length) {
-			prompt = candidate;
-			promptSource = `fallback:embedded:${name}.txt`;
-		} else {
-			prompt = (AGENT_BUILD || '').trim();
-			promptSource = 'fallback:embedded:build.txt';
-		}
-	}
+	const { prompt } = await resolveAgentPrompt({
+		projectRoot,
+		name,
+		entryPrompt: entry?.prompt,
+	});
 
 	// Default tool access per agent if not explicitly configured
 	let tools = Array.isArray(entry?.tools)
@@ -411,7 +294,6 @@ export async function resolveAgentConfig(
 	const deduped = Array.from(new Set([...tools, ...baseToolSet]));
 	const provider = normalizeProvider(entry?.provider);
 	const model = normalizeModel(entry?.model);
-	void promptSource;
 	return {
 		name,
 		prompt,

package/src/runtime/agent/runner-errors.ts

@@ -0,0 +1,116 @@
+import type { getDb } from '@ottocode/database';
+import { sessions } from '@ottocode/database/schema';
+import { eq } from 'drizzle-orm';
+import { publish } from '../../events/bus.ts';
+import { toErrorPayload } from '../errors/handling.ts';
+import {
+	pruneSession,
+	shouldAutoCompactBeforeOverflow,
+} from '../message/compaction.ts';
+import type {
+	completeAssistantMessage,
+	updateMessageTokensIncremental,
+	updateSessionTokensIncremental,
+} from '../session/db-operations.ts';
+import type { RunOpts } from '../session/queue.ts';
+
+type CompleteAssistantMessage = typeof completeAssistantMessage;
+type UpdateSessionTokensIncremental = typeof updateSessionTokensIncremental;
+type UpdateMessageTokensIncremental = typeof updateMessageTokensIncremental;
+
+export async function shouldPreemptivelyAutoCompact(
+	db: Awaited<ReturnType<typeof getDb>>,
+	opts: RunOpts,
+	threshold: number | null | undefined,
+): Promise<boolean> {
+	const sessionRows = await db
+		.select({ currentContextTokens: sessions.currentContextTokens })
+		.from(sessions)
+		.where(eq(sessions.id, opts.sessionId))
+		.limit(1);
+
+	return shouldAutoCompactBeforeOverflow({
+		autoCompactThresholdTokens: threshold,
+		currentContextTokens: sessionRows[0]?.currentContextTokens ?? 0,
+		estimatedInputTokens: opts.estimatedInputTokens ?? 0,
+		isCompactCommand: opts.isCompactCommand,
+		compactionRetries: opts.compactionRetries,
+	});
+}
+
+function isPromptTooLongError(err: unknown): boolean {
+	const errorMessage = err instanceof Error ? err.message : String(err);
+	const errorCode = (err as { code?: string })?.code ?? '';
+	const responseBody = (err as { responseBody?: string })?.responseBody ?? '';
+	const apiErrorType = (err as { apiErrorType?: string })?.apiErrorType ?? '';
+	const combinedError = `${errorMessage} ${responseBody}`.toLowerCase();
+
+	return (
+		combinedError.includes('prompt is too long') ||
+		combinedError.includes('maximum context length') ||
+		combinedError.includes('too many tokens') ||
+		combinedError.includes('context_length_exceeded') ||
+		combinedError.includes('request too large') ||
+		combinedError.includes('exceeds the model') ||
+		combinedError.includes('input is too long') ||
+		errorCode === 'context_length_exceeded' ||
+		apiErrorType === 'invalid_request_error'
+	);
+}
+
+export async function handleRunnerError(args: {
+	err: unknown;
+	opts: RunOpts;
+	db: Awaited<ReturnType<typeof getDb>>;
+	completeAssistantMessage: CompleteAssistantMessage;
+	updateSessionTokensIncremental: UpdateSessionTokensIncremental;
+	updateMessageTokensIncremental: UpdateMessageTokensIncremental;
+}): Promise<'handled' | 'rethrow'> {
+	const { err, opts, db } = args;
+	const payload = toErrorPayload(err);
+
+	if (isPromptTooLongError(err) && !opts.isCompactCommand) {
+		try {
+			const pruneResult = await pruneSession(db, opts.sessionId);
+			void pruneResult;
+
+			publish({
+				type: 'error',
+				sessionId: opts.sessionId,
+				payload: {
+					...payload,
+					message: `Context too large. Auto-compacted old tool results. Please retry your message.`,
+					name: 'ContextOverflow',
+				},
+			});
+
+			try {
+				await args.completeAssistantMessage({}, opts, db);
+			} catch {}
+			return 'handled';
+		} catch {}
+	}
+
+	publish({
+		type: 'error',
+		sessionId: opts.sessionId,
+		payload,
+	});
+
+	try {
+		await args.updateSessionTokensIncremental(
+			{ inputTokens: 0, outputTokens: 0 },
+			undefined,
+			opts,
+			db,
+		);
+		await args.updateMessageTokensIncremental(
+			{ inputTokens: 0, outputTokens: 0 },
+			undefined,
+			opts,
+			db,
+		);
+		await args.completeAssistantMessage({}, opts, db);
+	} catch {}
+	return 'rethrow';
+}

package/src/runtime/agent/runner-reminders.ts

@@ -0,0 +1,45 @@
+export type RunnerMessage = {
+	role: string;
+	content: string | Array<unknown>;
+};
+
+export function appendRunnerReminderMessages(args: {
+	messages: RunnerMessage[];
+	isFirstMessage: boolean;
+	isOpenAIOAuth: boolean;
+	continuationCount?: number;
+}): void {
+	const { messages, isFirstMessage, isOpenAIOAuth, continuationCount } = args;
+
+	if (!isFirstMessage) {
+		messages.push(
+			isOpenAIOAuth
+				? {
+						role: 'system',
+						content:
+							'[system-reminder] Continuing an existing session. Execute directly, use tools as needed, and call `finish` at the end. For simple questions, your answer IS the response — do not add a "Summary:" recap.',
+					}
+				: {
+						role: 'user',
+						content:
+							'<system-reminder>Continuing an existing session. Answer or complete the work directly, then call `finish`. For simple questions, your answer IS the response — do NOT add a labeled "Summary:" line or recap trivial replies.</system-reminder>',
+					},
+		);
+	}
+
+	if ((continuationCount ?? 0) <= 0) return;
+
+	messages.push(
+		isOpenAIOAuth
+			? {
+					role: 'system',
+					content:
+						'[system-reminder] Your previous response stopped mid-task. Resume from where you left off and complete the actual work — not a plan-only update.',
+				}
+			: {
+					role: 'user',
+					content:
+						'<system-reminder>Your previous response stopped before calling `finish`. Resume from where you left off, do the actual work (no plan-only updates), then stream a summary and call `finish`.</system-reminder>',
+				},
+	);
+}

package/src/runtime/agent/runner-setup-model.ts

@@ -0,0 +1,75 @@
+import { wrapLanguageModel } from 'ai';
+import { devToolsMiddleware } from '@ai-sdk/devtools';
+import type { OttoConfig } from '@ottocode/sdk';
+import { isDevtoolsEnabled } from '../debug/state.ts';
+import { resolveModel } from '../provider/index.ts';
+import { buildReasoningConfig } from '../provider/reasoning.ts';
+import type { RunOpts } from '../session/queue.ts';
+import { mergeProviderOptions } from './runner-setup-tools.ts';
+import { nowMs } from './runner-setup-utils.ts';
+
+export async function resolveRunnerModel(args: {
+	opts: RunOpts;
+	cfg: OttoConfig;
+}): Promise<{
+	model:
+		| Awaited<ReturnType<typeof resolveModel>>
+		| ReturnType<typeof wrapLanguageModel>;
+	resolveModelMs: number;
+}> {
+	const resolveModelStartedAt = nowMs();
+	const model = await resolveModel(
+		args.opts.provider,
+		args.opts.model,
+		args.cfg,
+		{
+			sessionId: args.opts.sessionId,
+			messageId: args.opts.assistantMessageId,
+			reasoningText: args.opts.reasoningText,
+		},
+	);
+	const resolveModelMs = nowMs() - resolveModelStartedAt;
+	const wrappedModel = isDevtoolsEnabled()
+		? wrapLanguageModel({
+				// biome-ignore lint/suspicious/noExplicitAny: OpenRouter provider uses v2 spec
+				model: model as any,
+				middleware: devToolsMiddleware(),
+			})
+		: model;
+
+	return { model: wrappedModel, resolveModelMs };
+}
+
+export function buildRunnerProviderOptions(args: {
+	cfg: OttoConfig;
+	opts: RunOpts;
+	adaptedProviderOptions: Record<string, unknown>;
+	maxOutputTokens: number | undefined;
+}): {
+	providerOptions: Record<string, unknown>;
+	effectiveMaxOutputTokens: number | undefined;
+} {
+	const providerOptions = { ...args.adaptedProviderOptions };
+
+	if (args.opts.provider === 'copilot') {
+		providerOptions.openai = {
+			...((providerOptions.openai as Record<string, unknown>) || {}),
+			store: false,
+		};
+	}
+
+	const reasoningConfig = buildReasoningConfig({
+		cfg: args.cfg,
+		provider: args.opts.provider,
+		model: args.opts.model,
+		reasoningText: args.opts.reasoningText,
+		reasoningLevel: args.opts.reasoningLevel,
+		maxOutputTokens: args.maxOutputTokens,
+	});
+	mergeProviderOptions(providerOptions, reasoningConfig.providerOptions);
+
+	return {
+		providerOptions,
+		effectiveMaxOutputTokens: reasoningConfig.effectiveMaxOutputTokens,
+	};
+}

package/src/runtime/agent/runner-setup-prompt.ts

@@ -0,0 +1,185 @@
+import {
+	getConfiguredProviderFamily,
+	getSessionSystemPromptPath,
+	logger,
+	type OttoConfig,
+} from '@ottocode/sdk';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { composeSystemPrompt } from '../prompt/builder.ts';
+import { isDebugEnabled } from '../debug/state.ts';
+import { getMaxOutputTokens } from '../utils/token.ts';
+import { getCompactionSystemPrompt } from '../message/compaction.ts';
+import { adaptRunnerCall, detectOAuth } from '../provider/oauth-adapter.ts';
+import type { RunOpts } from '../session/queue.ts';
+import { nowMs } from './runner-setup-utils.ts';
+
+export type RunnerPromptSetup = {
+	system: string;
+	systemComponents: string[];
+	additionalSystemMessages: Array<{ role: 'system' | 'user'; content: string }>;
+	maxOutputTokens: number | undefined;
+	providerOptions: Record<string, unknown>;
+	needsSpoof: boolean;
+	isOpenAIOAuth: boolean;
+	effectiveSystemPrompt: string;
+	composeSystemPromptMs: number;
+};
+
+export async function buildRunnerPrompt(args: {
+	opts: RunOpts;
+	cfg: OttoConfig;
+	agentPrompt: string;
+	contextSummary?: string;
+	historyLength: number;
+	isFirstMessage: boolean;
+}): Promise<RunnerPromptSetup> {
+	const { opts, cfg, agentPrompt, contextSummary } = args;
+	const composeSystemPromptStartedAt = nowMs();
+	const { getAuth } = await import('@ottocode/sdk');
+	const auth = await getAuth(opts.provider, cfg.projectRoot);
+	const oauth = detectOAuth(opts.provider, auth);
+
+	const composed = await composeSystemPrompt({
+		provider: opts.provider,
+		model: opts.model,
+		promptFamily: getConfiguredProviderFamily(cfg, opts.provider, opts.model),
+		skillSettings: cfg.skills,
+		projectRoot: cfg.projectRoot,
+		agentPrompt,
+		oneShot: opts.oneShot,
+		guidedMode: cfg.defaults.guidedMode,
+		spoofPrompt: undefined,
+		includeProjectTree: false,
+		userContext: opts.userContext,
+		contextSummary,
+		isOpenAIOAuth: oauth.isOpenAIOAuth,
+	});
+
+	const rawMaxOutputTokens = getMaxOutputTokens(opts.provider, opts.model);
+	const adapted = adaptRunnerCall(oauth, composed, {
+		provider: opts.provider,
+		rawMaxOutputTokens,
+	});
+
+	const { system } = adapted;
+	const { systemComponents, additionalSystemMessages } = adapted;
+	const openAIProviderOptions = adapted.providerOptions.openai as
+		| Record<string, unknown>
+		| undefined;
+	const openAIInstructions =
+		typeof openAIProviderOptions?.instructions === 'string'
+			? openAIProviderOptions.instructions
+			: '';
+	const effectiveSystemPrompt = system || openAIInstructions || composed.prompt;
+	const promptMode = oauth.isOpenAIOAuth
+		? 'openai-oauth'
+		: oauth.needsSpoof
+			? 'spoof'
+			: 'standard';
+	const composeSystemPromptMs = nowMs() - composeSystemPromptStartedAt;
+
+	logger.debug('[prompt] system prompt assembled', {
+		sessionId: opts.sessionId,
+		messageId: opts.assistantMessageId,
+		agent: opts.agent,
+		provider: opts.provider,
+		model: opts.model,
+		promptMode,
+		components: systemComponents,
+		systemLength: effectiveSystemPrompt.length,
+		historyMessages: args.historyLength,
+		additionalSystemMessages: additionalSystemMessages.length,
+		isFirstMessage: args.isFirstMessage,
+		isOpenAIOAuth: oauth.isOpenAIOAuth,
+		needsSpoof: oauth.needsSpoof,
+	});
+	logger.debug('[prompt] detailed prompt context', {
+		sessionId: opts.sessionId,
+		messageId: opts.assistantMessageId,
+		debugDetail: true,
+		agentPromptLength: agentPrompt.length,
+		contextSummaryLength: contextSummary?.length ?? 0,
+		userContextLength: opts.userContext?.length ?? 0,
+		oneShot: Boolean(opts.oneShot),
+		guidedMode: Boolean(cfg.defaults.guidedMode),
+		isOpenAIOAuth: oauth.isOpenAIOAuth,
+		needsSpoof: oauth.needsSpoof,
+		promptMode,
+		rawSystemLength: system.length,
+		openAIInstructionsLength: openAIInstructions.length,
+		effectiveSystemPromptLength: effectiveSystemPrompt.length,
+		systemComponents,
+		additionalSystemMessageRoles: additionalSystemMessages.map(
+			(message) => message.role,
+		),
+	});
+	await writeDebugSystemPrompt({
+		opts,
+		effectiveSystemPrompt,
+		promptMode,
+	});
+
+	return {
+		system,
+		systemComponents,
+		additionalSystemMessages,
+		maxOutputTokens: adapted.maxOutputTokens,
+		providerOptions: adapted.providerOptions,
+		needsSpoof: oauth.needsSpoof,
+		isOpenAIOAuth: oauth.isOpenAIOAuth,
+		effectiveSystemPrompt,
+		composeSystemPromptMs,
+	};
+}
+
+async function writeDebugSystemPrompt(args: {
+	opts: RunOpts;
+	effectiveSystemPrompt: string;
+	promptMode: string;
+}): Promise<void> {
+	const { opts, effectiveSystemPrompt, promptMode } = args;
+	if (!effectiveSystemPrompt || !isDebugEnabled()) return;
+
+	const systemPromptPath = getSessionSystemPromptPath(opts.sessionId);
+	try {
+		await mkdir(dirname(systemPromptPath), { recursive: true });
+		await Bun.write(systemPromptPath, effectiveSystemPrompt);
+		logger.debug('[prompt] wrote system prompt file', {
+			sessionId: opts.sessionId,
+			messageId: opts.assistantMessageId,
+			path: systemPromptPath,
+			debugDetail: true,
+			promptMode,
+			effectiveSystemPromptLength: effectiveSystemPrompt.length,
+		});
+	} catch (error) {
+		logger.warn('[prompt] failed to write system prompt file', {
+			sessionId: opts.sessionId,
+			messageId: opts.assistantMessageId,
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
+}
+
+export function appendRunnerPromptMessages(args: {
+	opts: RunOpts;
+	additionalSystemMessages: Array<{ role: 'system' | 'user'; content: string }>;
+}): void {
+	const { opts, additionalSystemMessages } = args;
+	if (opts.isCompactCommand && opts.compactionContext) {
+		const compactPrompt = getCompactionSystemPrompt();
+		additionalSystemMessages.push({
+			role: 'system',
+			content: compactPrompt,
+		});
+		additionalSystemMessages.push({
+			role: 'user',
+			content: `Please summarize this conversation:\n\n<conversation-to-summarize>\n${opts.compactionContext}\n</conversation-to-summarize>`,
+		});
+	}
+
+	if (opts.additionalPromptMessages?.length) {
+		additionalSystemMessages.push(...opts.additionalPromptMessages);
+	}
+}

package/src/runtime/agent/runner-setup-tools.ts

@@ -0,0 +1,103 @@
+import {
+	getConfiguredProviderFamily,
+	getModelFamily,
+	type OttoConfig,
+} from '@ottocode/sdk';
+import type { DiscoveredTool } from '@ottocode/sdk';
+import type { RunOpts } from '../session/queue.ts';
+
+const EDITING_TOOL_NAMES = [
+	'edit',
+	'multiedit',
+	'write',
+	'copy_into',
+	'apply_patch',
+];
+const MODEL_FAMILY_EDIT_TOOL_POLICY_AGENTS = new Set([
+	'build',
+	'general',
+	'init',
+]);
+
+function normalizeToolName(toolName: string): string {
+	return toolName === 'bash' ? 'shell' : toolName;
+}
+
+export function normalizeToolNames(toolNames: string[]): string[] {
+	return Array.from(new Set(toolNames.map(normalizeToolName)));
+}
+
+export function mergeProviderOptions(
+	base: Record<string, unknown>,
+	incoming: Record<string, unknown>,
+): Record<string, unknown> {
+	for (const [key, value] of Object.entries(incoming)) {
+		const existing = base[key];
+		if (
+			existing &&
+			typeof existing === 'object' &&
+			!Array.isArray(existing) &&
+			value &&
+			typeof value === 'object' &&
+			!Array.isArray(value)
+		) {
+			base[key] = {
+				...(existing as Record<string, unknown>),
+				...(value as Record<string, unknown>),
+			};
+			continue;
+		}
+
+		base[key] = value;
+	}
+
+	return base;
+}
+
+export function applyModelFamilyEditToolPolicy(
+	agent: string,
+	tools: string[],
+	provider: RunOpts['provider'],
+	model: string,
+	cfg?: OttoConfig,
+): string[] {
+	tools = normalizeToolNames(tools);
+	if (!MODEL_FAMILY_EDIT_TOOL_POLICY_AGENTS.has(agent)) return tools;
+
+	const family = cfg
+		? getConfiguredProviderFamily(cfg, provider, model)
+		: getModelFamily(provider, model);
+	const next = tools.filter(
+		(toolName) => !EDITING_TOOL_NAMES.includes(toolName),
+	);
+	const preferredEditingTools =
+		family === 'anthropic' || family === 'openai'
+			? ['write', 'copy_into', 'apply_patch']
+			: ['write', 'edit', 'multiedit', 'copy_into'];
+
+	return Array.from(new Set([...next, ...preferredEditingTools]));
+}
+
+export function buildAllowedTools(args: {
+	agentName: string;
+	agentTools: string[];
+	provider: RunOpts['provider'];
+	model: string;
+	cfg: OttoConfig;
+	allTools: DiscoveredTool[];
+}): DiscoveredTool[] {
+	const allowedToolNames = applyModelFamilyEditToolPolicy(
+		args.agentName,
+		args.agentTools,
+		args.provider,
+		args.model,
+		args.cfg,
+	);
+	const allowedNames = new Set([
+		...normalizeToolNames(allowedToolNames),
+		'finish',
+	]);
+	return args.allTools.filter(
+		(tool) => allowedNames.has(tool.name) || tool.name === 'load_mcp_tools',
+	);
+}

package/src/runtime/agent/runner-setup-utils.ts

@@ -0,0 +1,21 @@
+export type TimedResult<T> = {
+	value: T;
+	durationMs: number;
+};
+
+export function nowMs(): number {
+	const perf = globalThis.performance;
+	if (perf && typeof perf.now === 'function') return perf.now();
+	return Date.now();
+}
+
+export async function timePromise<T>(
+	promise: Promise<T>,
+): Promise<TimedResult<T>> {
+	const startedAt = nowMs();
+	const value = await promise;
+	return {
+		value,
+		durationMs: nowMs() - startedAt,
+	};
+}