@oh-my-pi/pi-coding-agent 16.3.0 → 16.3.3

package/src/hindsight/client.ts

@@ -8,10 +8,12 @@
  * tests to spy on.
  */
 
+import { isTimeoutError, withTimeoutSignal } from "../utils/fetch-timeout";
 import type { HindsightConfig } from "./config";
 
 const USER_AGENT = "oh-my-pi-coding-agent";
 const DEFAULT_USER_AGENT = USER_AGENT;
+const HINDSIGHT_REQUEST_TIMEOUT_MS = 30_000;
 
 export type Budget = "low" | "mid" | "high" | string;
 export type TagsMatch = "any" | "all" | "any_strict" | "all_strict";
@@ -24,6 +26,11 @@ export interface HindsightApiOptions {
 	userAgent?: string;
 }
 
+/** Caller cancellation shared by Hindsight request option bags. */
+export interface HindsightRequestOptions {
+	signal?: AbortSignal;
+}
+
 export interface RecallResult {
 	id?: string;
 	text: string;
@@ -77,7 +84,7 @@ export interface MemoryItemInput {
 	updateMode?: UpdateMode;
 }
 
-export interface RetainOptions {
+export interface RetainOptions extends HindsightRequestOptions {
 	timestamp?: Date | string;
 	context?: string;
 	metadata?: Record<string, string>;
@@ -87,7 +94,7 @@ export interface RetainOptions {
 	updateMode?: UpdateMode;
 }
 
-export interface RetainBatchOptions {
+export interface RetainBatchOptions extends HindsightRequestOptions {
 	/** Document id applied to every item that doesn't carry its own. */
 	documentId?: string;
 	/** Tags attached to the resulting document(s), not individual items. */
@@ -95,7 +102,7 @@ export interface RetainBatchOptions {
 	async?: boolean;
 }
 
-export interface RecallOptions {
+export interface RecallOptions extends HindsightRequestOptions {
 	types?: string[];
 	maxTokens?: number;
 	budget?: Budget;
@@ -103,19 +110,19 @@ export interface RecallOptions {
 	tagsMatch?: TagsMatch;
 }
 
-export interface ReflectOptions {
+export interface ReflectOptions extends HindsightRequestOptions {
 	context?: string;
 	budget?: Budget;
 	tags?: string[];
 	tagsMatch?: TagsMatch;
 }
 
-export interface CreateBankOptions {
+export interface CreateBankOptions extends HindsightRequestOptions {
 	reflectMission?: string;
 	retainMission?: string;
 }
 
-export interface ListMemoriesOptions {
+export interface ListMemoriesOptions extends HindsightRequestOptions {
 	limit?: number;
 	offset?: number;
 	type?: string;
@@ -123,12 +130,12 @@ export interface ListMemoriesOptions {
 	consolidationState?: ConsolidationState;
 }
 
-export interface ListDocumentsOptions {
+export interface ListDocumentsOptions extends HindsightRequestOptions {
 	limit?: number;
 	offset?: number;
 }
 
-export interface UpdateDocumentOptions {
+export interface UpdateDocumentOptions extends HindsightRequestOptions {
 	tags?: string[];
 }
 
@@ -166,7 +173,7 @@ export interface MentalModelHistoryEntry {
 	[key: string]: unknown;
 }
 
-export interface CreateMentalModelOptions {
+export interface CreateMentalModelOptions extends HindsightRequestOptions {
 	id?: string;
 	tags?: string[];
 	maxTokens?: number;
@@ -183,11 +190,11 @@ export interface RefreshMentalModelResponse {
 	[key: string]: unknown;
 }
 
-export interface ListMentalModelsOptions {
+export interface ListMentalModelsOptions extends HindsightRequestOptions {
 	detail?: MentalModelDetail;
 }
 
-export interface GetMentalModelOptions {
+export interface GetMentalModelOptions extends HindsightRequestOptions {
 	detail?: MentalModelDetail;
 }
 
@@ -208,6 +215,7 @@ interface RequestOptions {
 	query?: Record<string, unknown>;
 	/** Return null instead of throwing on a 404 response. */
 	allow404?: boolean;
+	signal?: AbortSignal;
 }
 
 export class HindsightApi {
@@ -240,7 +248,10 @@ export class HindsightApi {
 			"POST",
 			`/v1/default/banks/${encodeURIComponent(bankId)}/memories`,
 			"retain",
-			{ body: { items: [item], async: options?.async } },
+			{
+				body: { items: [item], async: options?.async },
+				signal: options?.signal,
+			},
 		);
 	}
 
@@ -270,6 +281,7 @@ export class HindsightApi {
 					document_tags: options?.documentTags,
 					async: options?.async,
 				},
+				signal: options?.signal,
 			},
 		);
 	}
@@ -288,6 +300,7 @@ export class HindsightApi {
 					tags: options?.tags,
 					tags_match: options?.tagsMatch,
 				},
+				signal: options?.signal,
 			},
 		);
 	}
@@ -305,6 +318,7 @@ export class HindsightApi {
 					tags: options?.tags,
 					tags_match: options?.tagsMatch,
 				},
+				signal: options?.signal,
 			},
 		);
 	}
@@ -319,6 +333,7 @@ export class HindsightApi {
 					reflect_mission: options.reflectMission,
 					retain_mission: options.retainMission,
 				},
+				signal: options.signal,
 			},
 		);
 	}
@@ -340,6 +355,7 @@ export class HindsightApi {
 					limit: options?.limit,
 					offset: options?.offset,
 				},
+				signal: options?.signal,
 			},
 		);
 	}
@@ -350,7 +366,7 @@ export class HindsightApi {
 			"GET",
 			`/v1/default/banks/${encodeURIComponent(bankId)}/documents`,
 			"listDocuments",
-			{ query: { limit: options?.limit, offset: options?.offset } },
+			{ query: { limit: options?.limit, offset: options?.offset }, signal: options?.signal },
 		);
 	}
 
@@ -370,7 +386,7 @@ export class HindsightApi {
 			"PATCH",
 			`/v1/default/banks/${encodeURIComponent(bankId)}/documents/${encodeURIComponent(documentId)}`,
 			"updateDocument",
-			{ body: { tags: options.tags } },
+			{ body: { tags: options.tags }, signal: options.signal },
 		);
 	}
 
@@ -399,7 +415,7 @@ export class HindsightApi {
 			"GET",
 			`/v1/default/banks/${encodeURIComponent(bankId)}/mental-models`,
 			"listMentalModels",
-			{ query: { detail: options?.detail ?? "content" } },
+			{ query: { detail: options?.detail ?? "content" }, signal: options?.signal },
 		);
 	}
 
@@ -413,7 +429,7 @@ export class HindsightApi {
 			"GET",
 			`/v1/default/banks/${encodeURIComponent(bankId)}/mental-models/${encodeURIComponent(mentalModelId)}`,
 			"getMentalModel",
-			{ query: { detail: options?.detail ?? "content" }, allow404: true },
+			{ query: { detail: options?.detail ?? "content" }, allow404: true, signal: options?.signal },
 		);
 	}
 
@@ -441,6 +457,7 @@ export class HindsightApi {
 					max_tokens: options?.maxTokens,
 					trigger: options?.trigger,
 				},
+				signal: options?.signal,
 			},
 		);
 	}
@@ -489,7 +506,11 @@ export class HindsightApi {
 			if (qs) url += `?${qs}`;
 		}
 
-		const init: RequestInit = { method, headers: this.#headers };
+		const init: RequestInit = {
+			method,
+			headers: this.#headers,
+			signal: withTimeoutSignal(HINDSIGHT_REQUEST_TIMEOUT_MS, opts?.signal),
+		};
 		if (opts?.body !== undefined) {
 			init.body = JSON.stringify(pruneUndefined(opts.body));
 		}
@@ -498,11 +519,10 @@ export class HindsightApi {
 		try {
 			response = await fetch(url, init);
 		} catch (err) {
-			throw new HindsightError(
-				`${operation} request failed: ${err instanceof Error ? err.message : String(err)}`,
-				undefined,
-				err,
-			);
+			const message = isTimeoutError(err)
+				? `${operation} request timed out after 30s`
+				: `${operation} request failed: ${err instanceof Error ? err.message : String(err)}`;
+			throw new HindsightError(message, undefined, err);
 		}
 
 		if (opts?.allow404 && response.status === 404) {