/**
 * Pluggable memory provider. Builtin curated files use `BuiltinMemoryStore` + `curated_memory`;
 * external providers add instructions, prefetch/sync, and optional tools.
 */

import type { AgentTool } from '@earendil-works/pi-agent-core';

export interface MemoryProviderInitOptions {
  workspace?: string;
  agentWorkspace?: string;
  sessionId?: string;
  [key: string]: unknown;
}

export interface MemoryProvider {
  readonly name: string;

  isAvailable(): boolean;

  initialize(sessionId: string, options?: MemoryProviderInitOptions): Promise<void> | void;

  /** Static text merged into system prompt (external providers only; builtin uses curated snapshot separately). */
  systemPromptBlock(): string;

  prefetch(query: string, options?: { sessionId?: string }): Promise<string>;

  queuePrefetch(query: string, options?: { sessionId?: string }): void;

  syncTurn(userContent: string, assistantContent: string, options?: { sessionId?: string }): void;

  getToolSchemas(): AgentTool[];

  /** JSON string result for tool calls routed by name (when not using inline AgentTool.execute only). */
  handleToolCall(toolName: string, args: Record<string, unknown>): Promise<string>;

  shutdown(): Promise<void> | void;

  onTurnStart?(turnNumber: number, message: string, metadata?: Record<string, unknown>): void;
  onSessionEnd?(messages: unknown[]): void;
  onPreCompress?(messages: unknown[]): string;
  onMemoryWrite?(action: 'add' | 'replace' | 'remove', target: 'memory' | 'user', content: string): void;
}
