@oh-my-pi/pi-coding-agent 14.6.1 → 14.6.3

package/src/hindsight/client.ts

@@ -0,0 +1,445 @@
+/**
+ * Minimal fetch-based client for the Hindsight HTTP API.
+ *
+ * Replaces the `@vectorize-io/hindsight-client` SDK with hand-rolled fetch
+ * calls so we depend on nothing more than the API endpoints we actually use:
+ * `retain`, `retainBatch`, `recall`, `reflect`, bank + document management,
+ * and bulk listing. Centralising construction here keeps a single seam for
+ * tests to spy on.
+ */
+
+import type { HindsightConfig } from "./config";
+
+const USER_AGENT = "oh-my-pi-coding-agent";
+const DEFAULT_USER_AGENT = USER_AGENT;
+
+export type Budget = "low" | "mid" | "high" | string;
+export type TagsMatch = "any" | "all" | "any_strict" | "all_strict";
+export type UpdateMode = "replace" | "append";
+export type ConsolidationState = "failed" | "pending" | "done";
+
+export interface HindsightApiOptions {
+	baseUrl: string;
+	apiKey?: string;
+	userAgent?: string;
+}
+
+export interface RecallResult {
+	id?: string;
+	text: string;
+	type?: string | null;
+	mentioned_at?: string | null;
+	[key: string]: unknown;
+}
+
+export interface RecallResponse {
+	results: RecallResult[];
+	[key: string]: unknown;
+}
+
+export interface ReflectResponse {
+	text?: string;
+	[key: string]: unknown;
+}
+
+export interface RetainResponse {
+	[key: string]: unknown;
+}
+
+export interface BankProfileResponse {
+	[key: string]: unknown;
+}
+
+export interface ListMemoriesResponse {
+	[key: string]: unknown;
+}
+
+export interface DocumentResponse {
+	[key: string]: unknown;
+}
+
+export interface ListDocumentsResponse {
+	[key: string]: unknown;
+}
+
+/** Mirrors the shape accepted by `POST /v1/default/banks/{bank_id}/memories`. */
+export interface MemoryItemInput {
+	content: string;
+	timestamp?: Date | string;
+	context?: string;
+	metadata?: Record<string, string>;
+	documentId?: string;
+	tags?: string[];
+	/** Scoping policy for observations derived from this item. */
+	observationScopes?: "per_tag" | "combined" | "all_combinations" | string[][];
+	/** Per-item extraction strategy override. */
+	strategy?: string;
+	updateMode?: UpdateMode;
+}
+
+export interface RetainOptions {
+	timestamp?: Date | string;
+	context?: string;
+	metadata?: Record<string, string>;
+	documentId?: string;
+	async?: boolean;
+	tags?: string[];
+	updateMode?: UpdateMode;
+}
+
+export interface RetainBatchOptions {
+	/** Document id applied to every item that doesn't carry its own. */
+	documentId?: string;
+	/** Tags attached to the resulting document(s), not individual items. */
+	documentTags?: string[];
+	async?: boolean;
+}
+
+export interface RecallOptions {
+	types?: string[];
+	maxTokens?: number;
+	budget?: Budget;
+	tags?: string[];
+	tagsMatch?: TagsMatch;
+}
+
+export interface ReflectOptions {
+	context?: string;
+	budget?: Budget;
+	tags?: string[];
+	tagsMatch?: TagsMatch;
+}
+
+export interface CreateBankOptions {
+	reflectMission?: string;
+	retainMission?: string;
+}
+
+export interface ListMemoriesOptions {
+	limit?: number;
+	offset?: number;
+	type?: string;
+	q?: string;
+	consolidationState?: ConsolidationState;
+}
+
+export interface ListDocumentsOptions {
+	limit?: number;
+	offset?: number;
+}
+
+export interface UpdateDocumentOptions {
+	tags?: string[];
+}
+
+export class HindsightError extends Error {
+	statusCode?: number;
+	details?: unknown;
+
+	constructor(message: string, statusCode?: number, details?: unknown) {
+		super(message);
+		this.name = "HindsightError";
+		this.statusCode = statusCode;
+		this.details = details;
+	}
+}
+
+interface RequestOptions {
+	body?: Record<string, unknown>;
+	query?: Record<string, unknown>;
+	/** Return null instead of throwing on a 404 response. */
+	allow404?: boolean;
+}
+
+export class HindsightApi {
+	#baseUrl: string;
+	#headers: Record<string, string>;
+
+	constructor(options: HindsightApiOptions) {
+		this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.#headers = {
+			"User-Agent": options.userAgent ?? DEFAULT_USER_AGENT,
+			"Content-Type": "application/json",
+		};
+		if (options.apiKey) {
+			this.#headers.Authorization = `Bearer ${options.apiKey}`;
+		}
+	}
+
+	async retain(bankId: string, content: string, options?: RetainOptions): Promise<RetainResponse> {
+		const item = buildMemoryItem({
+			content,
+			timestamp: options?.timestamp,
+			context: options?.context,
+			metadata: options?.metadata,
+			documentId: options?.documentId,
+			tags: options?.tags,
+			updateMode: options?.updateMode,
+		});
+
+		return this.#request<RetainResponse>(
+			"POST",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/memories`,
+			"retain",
+			{ body: { items: [item], async: options?.async } },
+		);
+	}
+
+	/**
+	 * Retain multiple memories in a single request. Mirrors the official
+	 * client's `retainBatch` — items hit `POST /memories` together so the
+	 * server can dedupe and consolidate as a batch instead of N round-trips.
+	 *
+	 * Per-item `documentId` wins; `options.documentId` only fills the gaps.
+	 */
+	async retainBatch(bankId: string, items: MemoryItemInput[], options?: RetainBatchOptions): Promise<RetainResponse> {
+		const processed = items.map(item => {
+			const built = buildMemoryItem(item);
+			if (built.document_id === undefined && options?.documentId !== undefined) {
+				built.document_id = options.documentId;
+			}
+			return built;
+		});
+
+		return this.#request<RetainResponse>(
+			"POST",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/memories`,
+			"retainBatch",
+			{
+				body: {
+					items: processed,
+					document_tags: options?.documentTags,
+					async: options?.async,
+				},
+			},
+		);
+	}
+
+	async recall(bankId: string, query: string, options?: RecallOptions): Promise<RecallResponse> {
+		return this.#request<RecallResponse>(
+			"POST",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/memories/recall`,
+			"recall",
+			{
+				body: {
+					query,
+					types: options?.types,
+					max_tokens: options?.maxTokens,
+					budget: options?.budget ?? "mid",
+					tags: options?.tags,
+					tags_match: options?.tagsMatch,
+				},
+			},
+		);
+	}
+
+	async reflect(bankId: string, query: string, options?: ReflectOptions): Promise<ReflectResponse> {
+		return this.#request<ReflectResponse>(
+			"POST",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/reflect`,
+			"reflect",
+			{
+				body: {
+					query,
+					context: options?.context,
+					budget: options?.budget ?? "low",
+					tags: options?.tags,
+					tags_match: options?.tagsMatch,
+				},
+			},
+		);
+	}
+
+	async createBank(bankId: string, options: CreateBankOptions = {}): Promise<BankProfileResponse> {
+		return this.#request<BankProfileResponse>(
+			"PUT",
+			`/v1/default/banks/${encodeURIComponent(bankId)}`,
+			"createBank",
+			{
+				body: {
+					reflect_mission: options.reflectMission,
+					retain_mission: options.retainMission,
+				},
+			},
+		);
+	}
+
+	/**
+	 * Bulk-list memory units in a bank with optional filters and pagination.
+	 * Endpoint: `GET /v1/default/banks/{bank_id}/memories/list`.
+	 */
+	async listMemories(bankId: string, options?: ListMemoriesOptions): Promise<ListMemoriesResponse> {
+		return this.#request<ListMemoriesResponse>(
+			"GET",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/memories/list`,
+			"listMemories",
+			{
+				query: {
+					type: options?.type,
+					q: options?.q,
+					consolidation_state: options?.consolidationState,
+					limit: options?.limit,
+					offset: options?.offset,
+				},
+			},
+		);
+	}
+
+	/** Bulk-list documents in a bank. */
+	async listDocuments(bankId: string, options?: ListDocumentsOptions): Promise<ListDocumentsResponse> {
+		return this.#request<ListDocumentsResponse>(
+			"GET",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/documents`,
+			"listDocuments",
+			{ query: { limit: options?.limit, offset: options?.offset } },
+		);
+	}
+
+	/** Fetch a document. Returns `null` on 404 instead of throwing. */
+	async getDocument(bankId: string, documentId: string): Promise<DocumentResponse | null> {
+		return this.#request<DocumentResponse | null>(
+			"GET",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/documents/${encodeURIComponent(documentId)}`,
+			"getDocument",
+			{ allow404: true },
+		);
+	}
+
+	/** Update a document's mutable fields (currently just tags). */
+	async updateDocument(bankId: string, documentId: string, options: UpdateDocumentOptions): Promise<DocumentResponse> {
+		return this.#request<DocumentResponse>(
+			"PATCH",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/documents/${encodeURIComponent(documentId)}`,
+			"updateDocument",
+			{ body: { tags: options.tags } },
+		);
+	}
+
+	/**
+	 * Delete a document and every memory derived from it. Returns `true` on
+	 * success, `false` if the document was already gone (404).
+	 */
+	async deleteDocument(bankId: string, documentId: string): Promise<boolean> {
+		const result = await this.#request<{ __deleted: boolean } | null>(
+			"DELETE",
+			`/v1/default/banks/${encodeURIComponent(bankId)}/documents/${encodeURIComponent(documentId)}`,
+			"deleteDocument",
+			{ allow404: true },
+		);
+		return result !== null;
+	}
+
+	async #request<T>(method: string, path: string, operation: string, opts?: RequestOptions): Promise<T> {
+		let url = `${this.#baseUrl}${path}`;
+		if (opts?.query) {
+			const qs = buildQueryString(opts.query);
+			if (qs) url += `?${qs}`;
+		}
+
+		const init: RequestInit = { method, headers: this.#headers };
+		if (opts?.body !== undefined) {
+			init.body = JSON.stringify(pruneUndefined(opts.body));
+		}
+
+		let response: Response;
+		try {
+			response = await fetch(url, init);
+		} catch (err) {
+			throw new HindsightError(
+				`${operation} request failed: ${err instanceof Error ? err.message : String(err)}`,
+				undefined,
+				err,
+			);
+		}
+
+		if (opts?.allow404 && response.status === 404) {
+			return null as T;
+		}
+
+		const text = await response.text();
+		const parsed = text ? safeJsonParse(text) : null;
+
+		if (!response.ok) {
+			const details =
+				(parsed && typeof parsed === "object"
+					? ((parsed as { detail?: unknown; message?: unknown }).detail ??
+						(parsed as { message?: unknown }).message)
+					: undefined) ??
+				parsed ??
+				text;
+			throw new HindsightError(
+				`${operation} failed: ${typeof details === "string" ? details : JSON.stringify(details)}`,
+				response.status,
+				details,
+			);
+		}
+
+		return (parsed ?? {}) as T;
+	}
+}
+
+interface BuiltMemoryItem {
+	content: string;
+	timestamp?: string;
+	context?: string;
+	metadata?: Record<string, string>;
+	document_id?: string;
+	tags?: string[];
+	observation_scopes?: "per_tag" | "combined" | "all_combinations" | string[][];
+	strategy?: string;
+	update_mode?: UpdateMode;
+}
+
+function buildMemoryItem(item: MemoryItemInput): BuiltMemoryItem {
+	const out: BuiltMemoryItem = { content: item.content };
+	if (item.timestamp !== undefined) {
+		out.timestamp = item.timestamp instanceof Date ? item.timestamp.toISOString() : item.timestamp;
+	}
+	if (item.context !== undefined) out.context = item.context;
+	if (item.metadata !== undefined) out.metadata = item.metadata;
+	if (item.documentId !== undefined) out.document_id = item.documentId;
+	if (item.tags !== undefined) out.tags = item.tags;
+	if (item.observationScopes !== undefined) out.observation_scopes = item.observationScopes;
+	if (item.strategy !== undefined) out.strategy = item.strategy;
+	if (item.updateMode !== undefined) out.update_mode = item.updateMode;
+	return out;
+}
+
+function buildQueryString(query: Record<string, unknown>): string {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value === undefined || value === null) continue;
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				if (item === undefined || item === null) continue;
+				params.append(key, String(item));
+			}
+		} else {
+			params.set(key, String(value));
+		}
+	}
+	return params.toString();
+}
+
+function pruneUndefined(obj: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const [k, v] of Object.entries(obj)) {
+		if (v !== undefined) out[k] = v;
+	}
+	return out;
+}
+
+function safeJsonParse(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+export function createHindsightClient(config: HindsightConfig & { hindsightApiUrl: string }): HindsightApi {
+	return new HindsightApi({
+		baseUrl: config.hindsightApiUrl,
+		apiKey: config.hindsightApiToken ?? undefined,
+		userAgent: USER_AGENT,
+	});
+}

package/src/hindsight/config.ts

@@ -0,0 +1,165 @@
+/**
+ * Resolved Hindsight runtime configuration.
+ *
+ * Source of truth precedence (last wins):
+ *   1. Built-in defaults
+ *   2. Settings (`hindsight.*` schema entries via `Settings.get(...)`)
+ *   3. `HINDSIGHT_*` environment variables
+ *
+ * Env wins because operators frequently override per-shell (CI, prod) without
+ * touching the persisted settings file.
+ */
+
+import { logger } from "@oh-my-pi/pi-utils";
+import type { Settings } from "../config/settings";
+
+export type HindsightScoping = "global" | "per-project" | "per-project-tagged";
+
+export interface HindsightConfig {
+	hindsightApiUrl: string | null;
+	hindsightApiToken: string | null;
+
+	bankId: string | null;
+	bankIdPrefix: string;
+	scoping: HindsightScoping;
+	bankMission: string;
+	retainMission: string | null;
+
+	autoRecall: boolean;
+	autoRetain: boolean;
+
+	retainMode: "full-session" | "last-turn";
+	retainEveryNTurns: number;
+	retainOverlapTurns: number;
+	retainContext: string;
+
+	recallBudget: "low" | "mid" | "high";
+	recallMaxTokens: number;
+	recallTypes: string[];
+	recallContextTurns: number;
+	recallMaxQueryChars: number;
+	recallPromptPreamble: string;
+
+	debug: boolean;
+}
+
+const VALID_RETAIN_MODES: HindsightConfig["retainMode"][] = ["full-session", "last-turn"];
+const VALID_BUDGETS: HindsightConfig["recallBudget"][] = ["low", "mid", "high"];
+const VALID_SCOPINGS: HindsightScoping[] = ["global", "per-project", "per-project-tagged"];
+
+const DEFAULT_PREAMBLE =
+	"Relevant memories from past conversations (prioritize recent when conflicting). " +
+	"Only use memories that are directly useful to continue this conversation; ignore the rest:";
+
+/** Coerce an env var value into a boolean using the OpenCode plugin's semantics. */
+function envBool(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	return ["true", "1", "yes"].includes(value.toLowerCase());
+}
+
+/** Coerce an env var value into an int, returning undefined for non-numeric input. */
+function envInt(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const n = Number.parseInt(value, 10);
+	return Number.isFinite(n) ? n : undefined;
+}
+
+function envString(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function pickBudget(value: unknown): HindsightConfig["recallBudget"] | undefined {
+	return typeof value === "string" && (VALID_BUDGETS as string[]).includes(value)
+		? (value as HindsightConfig["recallBudget"])
+		: undefined;
+}
+
+function pickRetainMode(value: unknown): HindsightConfig["retainMode"] | undefined {
+	return typeof value === "string" && (VALID_RETAIN_MODES as string[]).includes(value)
+		? (value as HindsightConfig["retainMode"])
+		: undefined;
+}
+
+function pickScoping(value: unknown): HindsightScoping | undefined {
+	return typeof value === "string" && (VALID_SCOPINGS as string[]).includes(value)
+		? (value as HindsightScoping)
+		: undefined;
+}
+
+/**
+ * Load the resolved Hindsight config.
+ *
+ * Pure (no I/O) aside from reading from `process.env` and the supplied
+ * Settings instance. Tests can pass `Settings.isolated({...})` and stub
+ * `process.env` per case.
+ */
+export function loadHindsightConfig(settings: Settings, env: NodeJS.ProcessEnv = process.env): HindsightConfig {
+	const apiUrlEnv = envString(env.HINDSIGHT_API_URL);
+	const apiTokenEnv = envString(env.HINDSIGHT_API_TOKEN);
+	const bankIdEnv = envString(env.HINDSIGHT_BANK_ID);
+	const bankMissionEnv = envString(env.HINDSIGHT_BANK_MISSION);
+	const retainModeEnv = pickRetainMode(env.HINDSIGHT_RETAIN_MODE);
+	const recallBudgetEnv = pickBudget(env.HINDSIGHT_RECALL_BUDGET);
+	const autoRecallEnv = envBool(env.HINDSIGHT_AUTO_RECALL);
+	const autoRetainEnv = envBool(env.HINDSIGHT_AUTO_RETAIN);
+	const scopingEnv = pickScoping(env.HINDSIGHT_SCOPING);
+	const debugEnv = envBool(env.HINDSIGHT_DEBUG);
+	const recallMaxTokensEnv = envInt(env.HINDSIGHT_RECALL_MAX_TOKENS);
+	const recallContextTurnsEnv = envInt(env.HINDSIGHT_RECALL_CONTEXT_TURNS);
+	const recallMaxQueryCharsEnv = envInt(env.HINDSIGHT_RECALL_MAX_QUERY_CHARS);
+	const retainEveryNTurnsEnv = envInt(env.HINDSIGHT_RETAIN_EVERY_N_TURNS);
+
+	// Read from settings (each falls back to its schema default).
+	const settingsRetainMode = pickRetainMode(settings.get("hindsight.retainMode"));
+	if (settings.get("hindsight.retainMode") && !settingsRetainMode) {
+		logger.warn("Hindsight: invalid retainMode setting, falling back to full-session", {
+			value: settings.get("hindsight.retainMode"),
+		});
+	}
+	const settingsRecallBudget = pickBudget(settings.get("hindsight.recallBudget"));
+	const settingsScoping = pickScoping(settings.get("hindsight.scoping"));
+	if (settings.get("hindsight.scoping") && !settingsScoping) {
+		logger.warn("Hindsight: invalid scoping setting, falling back to per-project-tagged", {
+			value: settings.get("hindsight.scoping"),
+		});
+	}
+
+	const config: HindsightConfig = {
+		hindsightApiUrl: apiUrlEnv ?? settings.get("hindsight.apiUrl") ?? null,
+		hindsightApiToken: apiTokenEnv ?? settings.get("hindsight.apiToken") ?? null,
+
+		bankId: bankIdEnv ?? settings.get("hindsight.bankId") ?? null,
+		bankIdPrefix: settings.get("hindsight.bankIdPrefix") ?? "",
+		scoping: scopingEnv ?? settingsScoping ?? "per-project-tagged",
+		bankMission: bankMissionEnv ?? settings.get("hindsight.bankMission") ?? "",
+		retainMission: settings.get("hindsight.retainMission") ?? null,
+
+		autoRecall: autoRecallEnv ?? settings.get("hindsight.autoRecall"),
+		autoRetain: autoRetainEnv ?? settings.get("hindsight.autoRetain"),
+
+		retainMode: retainModeEnv ?? settingsRetainMode ?? "full-session",
+		retainEveryNTurns: retainEveryNTurnsEnv ?? settings.get("hindsight.retainEveryNTurns"),
+		retainOverlapTurns: settings.get("hindsight.retainOverlapTurns"),
+		retainContext: settings.get("hindsight.retainContext") ?? "omp",
+
+		recallBudget: recallBudgetEnv ?? settingsRecallBudget ?? "mid",
+		recallMaxTokens: recallMaxTokensEnv ?? settings.get("hindsight.recallMaxTokens"),
+		recallTypes: settings.get("hindsight.recallTypes") as string[],
+		recallContextTurns: recallContextTurnsEnv ?? settings.get("hindsight.recallContextTurns"),
+		recallMaxQueryChars: recallMaxQueryCharsEnv ?? settings.get("hindsight.recallMaxQueryChars"),
+		recallPromptPreamble: DEFAULT_PREAMBLE,
+
+		debug: debugEnv ?? settings.get("hindsight.debug"),
+	};
+
+	return config;
+}
+
+/** Whether the caller has enough config to talk to a Hindsight server. */
+export function isHindsightConfigured(
+	config: HindsightConfig,
+): config is HindsightConfig & { hindsightApiUrl: string } {
+	return typeof config.hindsightApiUrl === "string" && config.hindsightApiUrl.length > 0;
+}