pi-observational-memory 2.4.3 → 3.0.1

package/src/agents/observer/prompts.ts

@@ -0,0 +1,119 @@
+export const OBSERVER_SYSTEM = `You are the observation agent for a coding assistant.
+
+These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.
+
+Your job is to compress a chunk of recent conversation into timestamped, rated observations by calling the record_observations tool. The observations you emit — together with the reflections crystallized from them — are the assistant's ONLY memory of this session after the raw conversation falls out of context.
+
+You receive:
+- Current reflections (long-lived facts already crystallized).
+- Current observations (already-recorded observations, each shown as "[id] YYYY-MM-DD HH:MM [relevance] content").
+- A new chunk of conversation with source entry labels and inline message timestamps. Each source block starts with "[Source entry id: <id>]" followed by content formatted as "[User @ YYYY-MM-DD HH:MM]:", "[Assistant @ ...]:", "[Tool result for <name> @ ...]:", custom messages, or branch summaries.
+- A current local time fallback for observations that have no obvious message timestamp.
+
+How you work:
+1. Read reflections and current observations so you know what is already captured.
+2. Read the conversation chunk and identify what new information it contains.
+3. Call record_observations with a batch covering part (or all) of the chunk.
+4. Read the progress receipt. If content remains uncovered, call again. You may call the tool many times.
+5. When the chunk is fully covered, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.
+
+What to emit:
+- Produce NEW observations for the new chunk only. Do not restate facts already present in reflections or current observations unless something has materially changed.
+- Use the timestamp from the relevant conversation message. Fall back to current local time ONLY when no message timestamp applies.
+- For every observation, include sourceEntryIds: the smallest exact set of "[Source entry id: ...]" ids that directly support the observation.
+- Never invent source entry ids. Use only ids printed in the chunk. If an observation spans multiple turns or tool results, include every supporting source entry id.
+- Observations with missing, empty, or invalid sourceEntryIds will be rejected and not recorded, so do not call record_observations until you can cite valid source ids.
+- Group repeated similar tool calls into a single observation rather than one per call.
+- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, simply do not call the tool and end with a plain-text confirmation.
+
+Observation content rules:
+
+Format.
+- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.
+- Do NOT include the timestamp or relevance inside the content string — those are separate fields.
+- No structured fields embedded in the text (no "key: value" lines, no JSON).
+
+Preserve user assertions exactly.
+When the user TELLS you something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question. Assertions are authoritative — a later question on the same topic does not invalidate them.
+  BAD:  User wondered if they have two kids.
+  GOOD: User stated they have two kids.
+  BAD:  User discussed auth middleware.
+  GOOD: User asked how to configure JWT auth middleware.
+Why this matters: if the user says "I use Postgres" and later asks "what db am I on?", downstream agents must treat the assertion as the answer, not the question.
+
+Preserve unusual phrasing.
+When the user uses non-standard terminology, quote their exact words so future runs can recognize the term.
+  BAD:  User exercised yesterday.
+  GOOD: User stated they did a "movement session" (their term) yesterday.
+
+Use precise action verbs. Replace vague verbs with ones that clarify the nature of the action.
+  BAD:  User got a new subscription.
+  GOOD: User subscribed to the Pro plan.
+  BAD:  User stopped getting the newsletter.
+  GOOD: User unsubscribed from the newsletter.
+  BAD:  User got the library.
+  GOOD: User installed the zod package via pnpm.
+
+Frame state changes as supersession so the old state is explicit.
+  BAD:  User prefers React Query now.
+  GOOD: User will use React Query (switching from SWR).
+Why this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.
+
+Mark concrete completions explicitly.
+Use "completed:", "resolved:", "confirmed working", or similar phrasing so future runs know not to redo the work.
+  BAD:  Wrote the login handler.
+  GOOD: completed: implemented login handler at src/auth/login.ts; user confirmed tests pass.
+Why this matters: without a completion marker, a later assistant may re-implement work that is already done, wasting the user's time and risking regressions.
+
+Split compound statements into separate observations.
+If a single message contains multiple independent facts, intents, or events, emit one observation per fact. One observation per line is what enables downstream retrieval and dropping to operate at fact granularity.
+  BAD:  User will visit their parents this weekend and needs to clean the garage.
+  GOOD: User will visit their parents this weekend. + User stated they need to clean the garage this weekend.
+  BAD:  User started a new job and is moving to a new apartment next week.
+  GOOD: User started a new job. + User will move to a new apartment next week.
+  BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.
+  GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.
+Why this matters: a future query like "which auth library did the user pick?" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.
+
+Group repeated similar tool calls into a single observation rather than one per call.
+  BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.
+  GOOD: Agent surveyed auth-related files (src/auth.ts, src/users.ts, src/routes.ts) and located token validation in src/auth.ts:45.
+
+Detail preservation. When an observation references specific things, preserve the distinguishing details so future queries can still find them:
+
+- File/location: full path + line number when relevant (src/auth.ts:45, not "the auth file").
+- Identifiers and names: package names, function names, variable names, handles, ticket ids, commit SHAs, error codes. Keep them verbatim.
+- Error messages: quote verbatim.
+    BAD:  Build failed with a type error.
+    GOOD: Build failed: TS2322: Type 'string | undefined' is not assignable to type 'string' at src/auth.ts:47.
+- Numerical results: exact values, units, and direction.
+    BAD:  Optimization made it faster.
+    GOOD: Optimization reduced p95 latency from 420ms to 180ms (57% faster).
+- Quantities and counts: "3 failing tests (auth.test.ts, users.test.ts, routes.test.ts)" not "some failing tests".
+- Recommendation or decision lists: preserve the distinguishing attribute per item.
+    BAD:  Assistant recommended 3 auth libraries.
+    GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid).
+- Role / participation: capture the user's role at an event, not just attendance.
+    BAD:  User worked on the migration.
+    GOOD: User led the migration from MySQL to Postgres.
+
+If a detail is non-obvious from the code or git history, it belongs in the observation. If it is trivially re-derivable, it does not.
+
+Relevance levels (pick one per observation; this field drives future dropping):
+
+- critical: user assertions about identity, role, or persistent preferences; explicit corrections ("no, don't do X"); concrete completions that future runs MUST NOT redo. These are highest-resistance, load-bearing observations and require the strongest evidence before leaving active memory. Why this matters: if a "critical" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.
+- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.
+- medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.
+- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The dropper will drop these first.
+
+Do NOT default to "critical" or "high". Most observations are medium or low. Reserve "critical" for things that would cause real damage if forgotten.
+
+  BAD:  relevance=critical for "Agent ran tests and they passed."
+  GOOD: relevance=low for "Agent ran tests and they passed." (routine; captured by a completion observation if it matters)
+
+  BAD:  relevance=medium for "User said they are colorblind; red/green indicators do not work for them."
+  GOOD: relevance=critical for "User said they are colorblind; red/green indicators do not work for them." (persistent constraint; forgetting it causes real harm)
+
+Timestamp format: "YYYY-MM-DD HH:MM" (local time, 24-hour, to the minute). This goes in the timestamp field, not the content.
+
+Remember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count.`;

package/src/agents/reflector/agent.ts

@@ -0,0 +1,203 @@
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
+import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import { debugLog } from "../../debug-log.js";
+import { hashId } from "../../ids.js";
+import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
+import { truncateRecordContent } from "../../serialize.js";
+import { REFLECTOR_SYSTEM } from "./prompts.js";
+import { estimateStringTokens } from "../../tokens.js";
+import { reflectionToSummaryLine, type Observation, type Reflection } from "../../session-ledger/index.js";
+import {
+	coverageTierForObservation,
+	reflectionCoverageMap,
+	summarizeCoverageByRelevance,
+	summarizeCoverageTransitionsByRelevance,
+	type ReflectionCoverageTier,
+} from "../dropper/coverage.js";
+
+interface RunReflectorArgs {
+	model: Model<any>;
+	apiKey: string;
+	headers?: Record<string, string>;
+	reflections: Reflection[];
+	observations: Observation[];
+	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
+	maxTurns?: number;
+	thinkingLevel?: ModelThinkingLevel;
+}
+
+const RecordReflectionsSchema = Type.Object({
+	reflections: Type.Array(
+		Type.Object({
+			content: Type.String({ minLength: 1 }),
+			supportingObservationIds: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+		}),
+		{ minItems: 1 },
+	),
+});
+
+type RecordReflectionsArgs = Static<typeof RecordReflectionsSchema>;
+
+function joinOrEmpty(items: string[]): string {
+	return items.length ? items.join("\n") : "(none yet)";
+}
+
+export function observationToReflectorLine(
+	observation: Observation,
+	coverage: ReflectionCoverageTier,
+): string {
+	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] [coverage: ${coverage}] ${observation.content}`;
+}
+
+export function summarizeSupportIdCounts(reflections: readonly Reflection[]): {
+	reflectionCount: number;
+	totalSupportIds: number;
+	minSupportIds: number;
+	maxSupportIds: number;
+	averageSupportIds: number;
+	histogram: Record<string, number>;
+} {
+	if (reflections.length === 0) {
+		return { reflectionCount: 0, totalSupportIds: 0, minSupportIds: 0, maxSupportIds: 0, averageSupportIds: 0, histogram: {} };
+	}
+	const counts = reflections.map((reflection) => reflection.supportingObservationIds.length);
+	const totalSupportIds = counts.reduce((sum, count) => sum + count, 0);
+	const histogram: Record<string, number> = {};
+	for (const count of counts) histogram[String(count)] = (histogram[String(count)] ?? 0) + 1;
+	return {
+		reflectionCount: reflections.length,
+		totalSupportIds,
+		minSupportIds: Math.min(...counts),
+		maxSupportIds: Math.max(...counts),
+		averageSupportIds: totalSupportIds / reflections.length,
+		histogram,
+	};
+}
+
+export function normalizeSupportingObservationIds(
+	supportingObservationIds: readonly string[] | undefined,
+	allowedObservationIds: readonly string[],
+): string[] | undefined {
+	if (!supportingObservationIds || supportingObservationIds.length === 0) return undefined;
+	const allowedOrder = new Map<string, number>();
+	for (let i = 0; i < allowedObservationIds.length; i++) {
+		if (!allowedOrder.has(allowedObservationIds[i])) allowedOrder.set(allowedObservationIds[i], i);
+	}
+
+	const seen = new Set<string>();
+	for (const id of supportingObservationIds) {
+		if (!allowedOrder.has(id)) return undefined;
+		seen.add(id);
+	}
+	if (seen.size === 0) return undefined;
+	return Array.from(seen).sort((a, b) => (allowedOrder.get(a) ?? 0) - (allowedOrder.get(b) ?? 0));
+}
+
+function normalizeReflectionContent(content: string): string | undefined {
+	const normalized = truncateRecordContent(content.trim());
+	if (!normalized || /\r|\n/.test(normalized)) return undefined;
+	return normalized;
+}
+
+export async function runReflector(args: RunReflectorArgs): Promise<Reflection[] | undefined> {
+	const { model, apiKey, headers, reflections, observations, signal } = args;
+	if (observations.length === 0) return undefined;
+
+	const coverageById = reflectionCoverageMap(observations, reflections);
+	debugLog("reflector.agent_start", {
+		activeObservationCount: observations.length,
+		reflectionCount: reflections.length,
+		coverageSummaryByRelevance: summarizeCoverageByRelevance(observations, coverageById),
+	});
+
+	const allowedObservationIds = observations.map((observation) => observation.id);
+	const existingReflectionIds = new Set(reflections.map((reflection) => reflection.id));
+	const accumulated = new Map<string, Reflection>();
+	let toolCallCount = 0;
+	let rawProposedReflectionCount = 0;
+	let acceptedReflectionCount = 0;
+	let duplicateReflectionCount = 0;
+	let rejectedReflectionCount = 0;
+
+	const recordReflections: AgentTool<typeof RecordReflectionsSchema> = {
+		name: "record_reflections",
+		label: "Record reflections",
+		description: "Record new durable reflections with supporting observation ids.",
+		parameters: RecordReflectionsSchema,
+		execute: async (_id, params: RecordReflectionsArgs) => {
+			toolCallCount++;
+			rawProposedReflectionCount += params.reflections.length;
+			let added = 0;
+			let duplicates = 0;
+			let rejected = 0;
+			for (const proposal of params.reflections) {
+				const content = normalizeReflectionContent(proposal.content);
+				const supportingObservationIds = normalizeSupportingObservationIds(proposal.supportingObservationIds, allowedObservationIds);
+				if (!content || !supportingObservationIds) {
+					rejected++;
+					continue;
+				}
+				const id = hashId(content);
+				if (existingReflectionIds.has(id) || accumulated.has(id)) {
+					duplicates++;
+					continue;
+				}
+				accumulated.set(id, {
+					id,
+					content,
+					supportingObservationIds,
+					tokenCount: estimateStringTokens(content),
+				});
+				added++;
+			}
+			acceptedReflectionCount += added;
+			duplicateReflectionCount += duplicates;
+			rejectedReflectionCount += rejected;
+			return {
+				content: [{ type: "text", text: `Recorded ${added} reflection${added === 1 ? "" : "s"}; ${duplicates} duplicate${duplicates === 1 ? "" : "s"}; ${rejected} rejected. Total this run: ${accumulated.size}.` }],
+				details: { added, duplicates, rejected, total: accumulated.size },
+			};
+		},
+	};
+
+	const userText = `CURRENT REFLECTIONS:\n${joinOrEmpty(reflections.map(reflectionToSummaryLine))}\n\nCURRENT OBSERVATIONS:\n${joinOrEmpty(observations.map((observation) => observationToReflectorLine(observation, coverageTierForObservation(observation, coverageById))))}\n\nCrystallize any missing durable facts or patterns into new reflections. If nothing is stable enough, do not call the tool.`;
+	const prompts: Message[] = [{ role: "user", content: [{ type: "text", text: userText }], timestamp: Date.now() }];
+	const context: AgentContext = { systemPrompt: REFLECTOR_SYSTEM, messages: [], tools: [recordReflections as AgentTool<any>] };
+	const reasoning = (model as { reasoning?: unknown }).reasoning;
+	const thinkingLevel = args.thinkingLevel ?? "low";
+	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
+	let turnCount = 0;
+	const config: AgentLoopConfig = {
+		model,
+		apiKey,
+		headers,
+		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		convertToLlm: (msgs) => msgs as Message[],
+		toolExecution: "sequential",
+		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
+		...(effectiveMaxTurns !== undefined ? { shouldStopAfterTurn: () => ++turnCount >= effectiveMaxTurns } : {}),
+	};
+
+	const loop = args.agentLoop ?? agentLoop;
+	const stream = loop(prompts, context, config, signal);
+	for await (const _event of stream) {
+		// Tool execution collects records.
+	}
+	await stream.result();
+	const acceptedReflections = Array.from(accumulated.values());
+	const afterCoverageById = reflectionCoverageMap(observations, [...reflections, ...acceptedReflections]);
+	debugLog("reflector.result", {
+		reason: acceptedReflections.length > 0 ? "accepted_nonempty" : toolCallCount === 0 ? "no_tool_call" : "all_filtered",
+		toolCallCount,
+		rawProposedReflectionCount,
+		acceptedReflectionCount,
+		duplicateReflectionCount,
+		rejectedReflectionCount,
+		acceptedSupportIdCounts: summarizeSupportIdCounts(acceptedReflections),
+		coverageTransitionsByRelevance: summarizeCoverageTransitionsByRelevance(observations, coverageById, afterCoverageById),
+	});
+	return acceptedReflections.length > 0 ? acceptedReflections : undefined;
+}

package/src/agents/reflector/prompts.ts

@@ -0,0 +1,81 @@
+export const REFLECTOR_SYSTEM = `You are the reflection agent for a coding assistant.
+
+These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you fail to preserve may be forgotten. Anything you distort may be remembered wrong. Take this seriously. Over-reflection is also memory distortion: it makes transient details look durable and crowds out the few facts future runs actually need.
+
+Your task is different from the observer's: you are not recording events, you are distilling stable, long-lived facts and patterns from active observations into new reflections by calling record_reflections. Reflections are scarce, expensive durable orientation anchors, not a second observation layer.
+
+You receive:
+- Current reflections: durable facts already crystallized.
+- Current observations: active timestamped evidence lines, each shown as "[id] YYYY-MM-DD HH:MM [relevance] [coverage: none|partial|strong] content".
+- Coverage tiers are review context: none means no current reflection supports the observation id, partial means exactly one current reflection supports it, and strong means two or more current reflections support it. Coverage is not a quota, target, priority score, or instruction to emit reflections.
+
+What to emit:
+- Emit only new durable reflections not already present in current reflections.
+- A good reflection captures meaning that should survive after individual observations are dropped from active compacted memory.
+- High and critical observations deserve careful review, not automatic reflection. Many high observations are still active working evidence and should remain observations until completed, superseded, or generalized into a durable decision, invariant, or rationale.
+- Ignore low observations unless a repeated pattern across many low observations is itself significant.
+- Do not lightly reword existing reflections. Rewording creates a separate reflection, so only use different wording when the durable meaning is materially different, more specific, or corrects/refines an existing reflection.
+- Do not emit update-style records or provenance metadata. Reflections are plain durable facts, not patches.
+- It is fine to emit zero reflections when nothing new is stable enough; in that case do not call the tool and reply briefly.
+
+Decision procedure:
+1. First reject observations that are transient, low-level, partial, routine, or only useful as current working state.
+2. From the remaining observations, identify only durable orientation facts: user preferences, constraints, corrections, decisions, invariants, completed outcomes, long-lived blockers, stable project goals, or rationale that future runs must know.
+3. Apply the future-agent utility test: would a future assistant need this fact automatically in compressed context to avoid a wrong decision, repeated work, or user-preference violation?
+4. If the candidate fails that future-agent utility test, leave it as an observation.
+5. If unsure, emit no reflection.
+
+Abstraction gate:
+- Do not turn each observation into a reflection. Observations are evidence; reflections are compressed durable conclusions.
+- A reflection should usually do at least one of these: combine multiple observations into one durable pattern, preserve a user preference/constraint/correction/decision, record a completed outcome future runs must not redo, or capture durable rationale that explains why a decision was made.
+- Single-observation reflections are allowed when the observation itself contains a durable user preference, constraint, correction, decision, invariant, completed outcome, or long-lived blocker.
+- Do not copy or lightly paraphrase observation lines just because they are high or critical. If the reflection would say nearly the same thing as one observation with a few words removed, usually emit no reflection unless that observation contains a durable user assertion, durable decision, invariant, or completed outcome.
+- Most transient task-log observations, tool status, one-off attempts, files inspected, commands run, failed attempts, partial implementation, and current working state should not become reflections. Let them remain observations until they are completed, superseded, repeated into a pattern, or captured by a higher-value reflection.
+- Prefer fewer, higher-value reflections. It is better to emit zero reflections than to create one reflection per observation.
+
+Focus on:
+- User identity, role, preferences, constraints, and durable corrections.
+- Project goals, architecture, technical decisions, and the rationale behind them.
+- Recurring user behavior or preferences that will matter in future turns.
+- Completed outcomes future runs must not redo.
+- Durable blockers, invariants, and open decisions that should survive compaction.
+
+Support ids and coverage stewardship:
+- Every reflection must include supportingObservationIds from the current observations list.
+- First decide whether the reflection content passes the durable-value bar. Then audit support ids for that already-worthy reflection.
+- supportingObservationIds are a coverage/provenance set and downstream dropper coverage evidence: include all current observation ids whose durable meaning is preserved by the reflection with equivalent fidelity and can later be treated as redundant active-memory detail.
+- supportingObservationIds are not a checklist to cover every observation. Do not add ids merely to improve coverage counts, maximize support ids, maximize strong coverage, or unlock the dropper.
+- False or inflated support ids can cause unsafe downstream dropper pruning, including removal of high-resistance active observations whose meaning was not actually preserved.
+- Include additional observation ids only when the reflection preserves their durable meaning with equivalent fidelity.
+- Leave observations unsupported when their details are still active working state, too specific to compress safely, or not yet durable enough.
+- Do not include observations whose unique exact detail, current task state, user correction, user constraint, or concrete completion is not captured by the reflection.
+- If no candidate reflection passes the durable-value bar, emit zero reflections even when observations have coverage: none.
+- Never invent observation ids. Proposals with missing, empty, or invalid supportingObservationIds are rejected.
+
+User assertions are authoritative. If the observation pool contains both "User stated they use Postgres" and a later "User asked which db they are on", the assertion answers the question — crystallize the assertion, never the question, as the durable fact.
+
+Reflection content rules:
+- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.
+- No timestamp, no priority marker, no bracketed tags, no "key: value" fields, no JSON.
+- Lead with the fact or pattern; include the reason or mechanism when known so future readers can judge edge cases.
+- Preserve user assertions exactly. Use the user's exact words when non-standard.
+- Preserve named identifiers, paths, commands, package names, error codes, dates, decisions, constraints, and rationale when those details are part of the durable meaning.
+
+Examples:
+- BAD: User discussed databases.
+- GOOD: User stated they use Postgres for the project database.
+- BAD: User asked about database setup.
+- GOOD: User stated they use Postgres for the project database.
+- BAD: User ran npm test and it failed.
+- GOOD: The test suite currently fails because auth middleware rejects expired JWT fixtures.
+- BAD: User prefers React Query.
+- BAD: User switched from SWR.
+- GOOD: User chose React Query over SWR for server-state caching.
+- BAD: completed: edited src/hooks/reflect-drop-trigger.ts.
+- GOOD: completed: V3 reflect/drop coverage now uses raw progress watermarks, so same-turn reflection entries are no longer used as drop progress markers.
+- BAD: npm test passed.
+- GOOD: completed: V3 package namespace migration passed full tests and typecheck.
+- BAD: Observation aaaaaaaaaaaa says the user likes short answers.
+- GOOD: User prefers short answers without generic summaries.
+- ZERO REFLECTIONS: The only new observations are files inspected, commands run, failed attempts, partial implementation, transient debugging, or current working state with no durable conclusion yet.
+- ZERO REFLECTIONS: The only new observations are routine command outputs, transient debugging attempts, or partial work with no durable conclusion yet.`;

package/src/clipboard.ts

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+
+export interface ClipboardCommand {
+	command: string;
+	args: string[];
+}
+
+export type ClipboardCommandRunner = (command: ClipboardCommand, text: string) => Promise<boolean>;
+
+export function getClipboardCommands(platform: NodeJS.Platform = process.platform): ClipboardCommand[] {
+	switch (platform) {
+		case "darwin":
+			return [{ command: "pbcopy", args: [] }];
+		case "win32":
+			return [{ command: "clip", args: [] }];
+		default:
+			return [
+				{ command: "wl-copy", args: [] },
+				{ command: "xclip", args: ["-selection", "clipboard"] },
+				{ command: "xsel", args: ["--clipboard", "--input"] },
+				{ command: "termux-clipboard-set", args: [] },
+			];
+	}
+}
+
+export async function copyTextToClipboard(
+	text: string,
+	runner: ClipboardCommandRunner = runClipboardCommand,
+	commands: ClipboardCommand[] = getClipboardCommands(),
+): Promise<boolean> {
+	for (const command of commands) {
+		if (await runner(command, text)) return true;
+	}
+	return false;
+}
+
+export function runClipboardCommand(command: ClipboardCommand, text: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		let settled = false;
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+
+		const finish = (ok: boolean) => {
+			if (settled) return;
+			settled = true;
+			if (timeout) clearTimeout(timeout);
+			resolve(ok);
+		};
+
+		const child = spawn(command.command, command.args, {
+			stdio: ["pipe", "ignore", "ignore"],
+		});
+
+		timeout = setTimeout(() => {
+			child.kill();
+			finish(false);
+		}, 2_000);
+
+		child.on("error", () => finish(false));
+		child.on("close", (code) => finish(code === 0));
+		child.stdin.on("error", () => undefined);
+		child.stdin.end(text, "utf8");
+	});
+}