feat: bootstrap BoxBrain framework

src/persona.ts

@@ -0,0 +1,306 @@
+import { InMemoryMemoryStore } from './memory';
+import {
+  addUtcDays,
+  buildAvailabilitySnapshot,
+  createMonthlyScheduleEntries,
+  createTenMinuteDailySchedule,
+  scheduleTargetDay,
+  startOfUtcDay,
+  toIso,
+} from './schedule';
+import {
+  buildMandatoryConversationContext,
+  conversationInstruction,
+  formatMessageHistory,
+  memoryExtractionInstruction,
+} from './conversation';
+import type {
+  BoxBrainMemoryStore,
+  DateTimeInput,
+  DebugEvent,
+  FactDraft,
+  MemorySpace,
+  OutgoingMessageDraft,
+  PersonaMessage,
+  PersonaOptions,
+  ScheduleEntry,
+  ScheduledAvailabilitySnapshot,
+} from './types';
+
+interface CreateMode {
+  type: 'create';
+  displayName: string;
+  seedMessage: string;
+}
+
+interface LoadMode {
+  type: 'load';
+  spaceId: string;
+}
+
+type Mode = CreateMode | LoadMode;
+
+function defaultInitialFact(displayName: string, seedMessage: string): FactDraft {
+  return {
+    statement: `${displayName} is a BoxBrain persona initialized from this seed: ${seedMessage}`,
+    topics: ['persona', displayName],
+    source: 'boxbrain.persona.initialization',
+    confidence: 1,
+    metadata: { boxbrainType: 'persona-initial-fact' },
+  };
+}
+
+function ensureDraft(draft: OutgoingMessageDraft): OutgoingMessageDraft {
+  return {
+    messages: draft.messages.map((message) => message.trim()).filter(Boolean),
+    ...(draft.reasoning === undefined ? {} : { reasoning: draft.reasoning }),
+  };
+}
+
+export class Persona {
+  private readonly memory: BoxBrainMemoryStore;
+  private readonly options: PersonaOptions;
+  private readonly mode: Mode;
+  private readonly readyPromise: Promise<MemorySpace>;
+  private availabilitySnapshot?: ScheduledAvailabilitySnapshot;
+
+  constructor(displayName: string, seedMessage: string, options?: PersonaOptions);
+  constructor(spaceId: string, options?: PersonaOptions);
+  constructor(first: string, second?: string | PersonaOptions, third?: PersonaOptions) {
+    if (typeof second === 'string') {
+      this.mode = { type: 'create', displayName: first, seedMessage: second };
+      this.options = third ?? {};
+    } else {
+      this.mode = { type: 'load', spaceId: first };
+      this.options = second ?? {};
+    }
+    this.memory = this.options.memory ?? new InMemoryMemoryStore();
+    this.readyPromise = this.initialize();
+  }
+
+  async ready(): Promise<MemorySpace> {
+    return this.readyPromise;
+  }
+
+  async createDailySchedule(datetime: DateTimeInput, message: string): Promise<ScheduleEntry[]> {
+    const persona = await this.ready();
+    const targetDay = scheduleTargetDay(datetime);
+    const entries = createTenMinuteDailySchedule({ persona, targetDay, message });
+    await this.emit('persona.schedule.daily.generated', { targetDay: targetDay.toISOString(), count: entries.length, message });
+    await this.memory.saveScheduleEntries(persona.id, entries);
+    await this.refreshAvailability(datetime);
+    return entries;
+  }
+
+  async createMonthlySchedule(datetime: DateTimeInput, message: string): Promise<ScheduleEntry[]> {
+    const persona = await this.ready();
+    const entries = createMonthlyScheduleEntries({ persona, fromDay: datetime, message });
+    await this.emit('persona.schedule.monthly.generated', { count: entries.length, message });
+    await this.memory.saveScheduleEntries(persona.id, entries);
+    await this.refreshAvailability(datetime);
+    return entries;
+  }
+
+  async deleteSchedulesBefore(cutoffExclusive: DateTimeInput): Promise<number> {
+    const persona = await this.ready();
+    const cutoff = toIso(cutoffExclusive);
+    const deleted = await this.memory.deleteScheduleEntriesBefore(persona.id, cutoff);
+    await this.memory.addFact(persona.id, {
+      statement: `Schedules before ${cutoff} were deleted or marked inactive.`,
+      topics: ['persona.schedule.deleted', 'schedule', cutoff.slice(0, 10)],
+      source: 'boxbrain.schedule.prune',
+      metadata: { boxbrainType: 'schedule-deletion', cutoffExclusive: cutoff, deleted },
+    });
+    await this.emit('persona.schedule.deleted', { cutoffExclusive: cutoff, deleted });
+    return deleted;
+  }
+
+  async deleteSchedulesOlderThan(datetime: DateTimeInput): Promise<number> {
+    return this.deleteSchedulesBefore(datetime);
+  }
+
+  async getTodayScheduledAvailability(datetime: DateTimeInput): Promise<ScheduledAvailabilitySnapshot> {
+    if (!this.availabilitySnapshot) {
+      await this.refreshAvailability(datetime);
+    }
+    const snapshot = this.availabilitySnapshot;
+    if (!snapshot) throw new Error('Availability snapshot was not initialized.');
+
+    const today = startOfUtcDay(datetime).toISOString();
+    if (snapshot.windowStartAt !== today) {
+      await this.refreshAvailability(datetime);
+    }
+
+    const refreshed = this.availabilitySnapshot;
+    if (!refreshed) throw new Error('Availability snapshot was not initialized.');
+    return refreshed;
+  }
+
+  async sendMessage(input: {
+    datetime: DateTimeInput;
+    messageHistory: PersonaMessage[];
+    getLatestMessageHistory?: () => Promise<PersonaMessage[]>;
+  }): Promise<OutgoingMessageDraft> {
+    const persona = await this.ready();
+    if (!this.options.models?.conversation) {
+      throw new Error('sendMessage requires options.models.conversation.');
+    }
+    const availability = await this.getTodayScheduledAvailability(input.datetime);
+    const context = await buildMandatoryConversationContext({
+      persona,
+      now: input.datetime,
+      memory: this.memory,
+      messages: input.messageHistory,
+      availability,
+    });
+    await this.emit('persona.conversation.context.loaded', {
+      factCount: context.personaAndUserFacts.length,
+      scheduleEntryCount: context.scheduleEntries.length,
+    });
+
+    const userMessage = [...input.messageHistory].reverse().find((message) => message.sender === 'user')?.content;
+    let draft = ensureDraft(await this.options.models.conversation.generateReply({
+      persona,
+      now: toIso(input.datetime),
+      mode: 'reply',
+      context,
+      ...(userMessage === undefined ? {} : { userMessage }),
+      instruction: conversationInstruction(),
+    }));
+
+    if (input.getLatestMessageHistory && this.options.models.rewrite) {
+      const latest = await input.getLatestMessageHistory();
+      if (latest.length > input.messageHistory.length) {
+        const latestContext = await buildMandatoryConversationContext({
+          persona,
+          now: input.datetime,
+          memory: this.memory,
+          messages: latest,
+          availability,
+        });
+        const decision = await this.options.models.rewrite.decide({
+          persona,
+          now: toIso(input.datetime),
+          previousHistory: input.messageHistory,
+          latestHistory: latest,
+          draft,
+          context: latestContext,
+        });
+        await this.emit('persona.conversation.rewrite.checked', { rewrite: decision.rewrite, reason: decision.reason ?? null });
+        if (decision.rewrite) {
+          draft = ensureDraft(decision.draft ?? await this.options.models.conversation.generateReply({
+            persona,
+            now: toIso(input.datetime),
+            mode: 'reply',
+            context: latestContext,
+            instruction: conversationInstruction(),
+          }));
+        }
+      }
+    }
+
+    await this.emit('persona.conversation.reply.generated', { messageCount: draft.messages.length });
+    return draft;
+  }
+
+  async startConversation(input: {
+    datetime: DateTimeInput;
+    messageHistory: PersonaMessage[];
+  }): Promise<OutgoingMessageDraft> {
+    const persona = await this.ready();
+    if (!this.options.models?.conversation) {
+      throw new Error('startConversation requires options.models.conversation.');
+    }
+    const availability = await this.getTodayScheduledAvailability(input.datetime);
+    const context = await buildMandatoryConversationContext({
+      persona,
+      now: input.datetime,
+      memory: this.memory,
+      messages: input.messageHistory,
+      availability,
+    });
+    const draft = ensureDraft(await this.options.models.conversation.generateReply({
+      persona,
+      now: toIso(input.datetime),
+      mode: 'start-conversation',
+      context,
+      instruction: conversationInstruction(),
+    }));
+    await this.emit('persona.conversation.started', { messageCount: draft.messages.length });
+    return draft;
+  }
+
+  async sleepMemory(input: {
+    datetime: DateTimeInput;
+    messageHistory: PersonaMessage[];
+  }): Promise<FactDraft[]> {
+    const persona = await this.ready();
+    if (!this.options.models?.memoryExtraction) {
+      throw new Error('sleepMemory requires options.models.memoryExtraction.');
+    }
+    const contextFacts = await this.memory.findFacts(persona.id, ['persona', persona.displayName, 'user']);
+    const drafts = await this.options.models.memoryExtraction.extract({
+      persona,
+      now: toIso(input.datetime),
+      formattedMessageHistory: formatMessageHistory({ personaName: persona.displayName, messages: input.messageHistory }),
+      contextFacts,
+      instruction: memoryExtractionInstruction(toIso(input.datetime)),
+    });
+    for (const draft of drafts) {
+      await this.memory.addFact(persona.id, {
+        ...draft,
+        topics: [...draft.topics, 'sleepMemory'],
+        source: draft.source ?? 'boxbrain.sleepMemory',
+      });
+    }
+    await this.emit('persona.memory.sleep.persisted', { factCount: drafts.length });
+    return drafts;
+  }
+
+  private async initialize(): Promise<MemorySpace> {
+    const now = toIso(this.options.now ?? new Date());
+    if (this.mode.type === 'load') {
+      const existing = await this.memory.getSpace(this.mode.spaceId);
+      if (!existing) throw new Error(`Persona space not found: ${this.mode.spaceId}`);
+      await this.emit('persona.loaded', { displayName: existing.displayName });
+      await this.refreshAvailability(now, existing);
+      return existing;
+    }
+
+    const space = await this.memory.createSpace({ displayName: this.mode.displayName, seedMessage: this.mode.seedMessage, now });
+    const modelFacts = this.options.models?.initialization
+      ? await this.options.models.initialization.extractInitialFacts({
+        displayName: this.mode.displayName,
+        seedMessage: this.mode.seedMessage,
+        now,
+      })
+      : undefined;
+    const facts = modelFacts ?? [defaultInitialFact(this.mode.displayName, this.mode.seedMessage)];
+    for (const fact of facts) {
+      await this.memory.addFact(space.id, fact);
+    }
+    await this.emit('persona.initialized', { displayName: space.displayName, factCount: facts.length }, space.id);
+    await this.refreshAvailability(now, space);
+    return space;
+  }
+
+  private async refreshAvailability(datetime: DateTimeInput, knownPersona?: MemorySpace): Promise<void> {
+    const persona = knownPersona ?? await this.ready();
+    const start = startOfUtcDay(datetime);
+    const end = addUtcDays(start, 2);
+    const entries = await this.memory.listScheduleEntries(persona.id, start.toISOString(), end.toISOString());
+    this.availabilitySnapshot = buildAvailabilitySnapshot({ now: datetime, entries });
+    await this.emit('persona.availability.refreshed', { rangeCount: this.availabilitySnapshot.ranges.length }, persona.id);
+  }
+
+  private async emit(name: string, data?: Record<string, unknown>, explicitSpaceId?: string): Promise<void> {
+    if (!this.options.debug) return;
+    const event: DebugEvent = {
+      name,
+      time: new Date().toISOString(),
+      ...(explicitSpaceId === undefined ? {} : { spaceId: explicitSpaceId }),
+      ...(data === undefined ? {} : { data }),
+    };
+    await this.options.debug(event);
+  }
+}