@moxxy/sdk 0.43.0 → 0.45.0

package/src/attachment-payload.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest';
+
+import { assertDefined } from './assert.js';
+
+import {
+  ATTACHMENT_READ_CHUNK_CHARS,
+  CLIENT_INLINE_ATTACHMENT_CHARS,
+  CLIENT_INLINE_EVENT_CHARS,
+  HISTORY_PAGE_MAX_CHARS,
+  attachmentBytes,
+  eventForClient,
+  findAttachment,
+  historyPageForClient,
+  listAttachments,
+  readAttachmentChunk,
+  restoredAttachmentRef,
+} from './attachment-payload.js';
+import type { MoxxyEvent, UserPromptAttachment, UserPromptEvent } from './events.js';
+
+function prompt(attachments: ReadonlyArray<UserPromptAttachment>): UserPromptEvent {
+  return {
+    type: 'user_prompt',
+    seq: 7,
+    ts: 0,
+    turnId: 't1',
+    text: 'look at these',
+    attachments,
+  } as unknown as UserPromptEvent;
+}
+
+const base64Of = (chars: number): string => 'A'.repeat(chars);
+
+function firstAttachment(event: UserPromptEvent): UserPromptAttachment {
+  const first = event.attachments?.[0];
+  assertDefined(first, 'first attachment');
+  return first;
+}
+
+describe('eventForClient', () => {
+  it('leaves an event without large attachments untouched (same object)', () => {
+    const event = prompt([{ kind: 'image', content: base64Of(1000), mediaType: 'image/png', name: 'a.png' }]);
+    expect(eventForClient(event)).toBe(event);
+    const chunk = { type: 'assistant_chunk', seq: 1, ts: 0, turnId: 't1', delta: 'hi' } as unknown as MoxxyEvent;
+    expect(eventForClient(chunk)).toBe(chunk);
+  });
+
+  it('replaces the bytes of a large attachment with its size, keeping name and type', () => {
+    const big = base64Of(CLIENT_INLINE_ATTACHMENT_CHARS + 4);
+    const event = prompt([{ kind: 'document', content: big, mediaType: 'application/pdf', name: 'scan.pdf' }]);
+    const slim = eventForClient(event) as UserPromptEvent;
+    expect(slim).not.toBe(event);
+    expect(slim.attachments).toEqual([
+      { kind: 'document', content: '', mediaType: 'application/pdf', name: 'scan.pdf', omittedBytes: attachmentBytes(firstAttachment(event)) },
+    ]);
+    // The original event keeps its bytes — the runner's log is never changed.
+    expect(firstAttachment(event).content).toBe(big);
+  });
+
+  it('caps the bytes one event carries even when each attachment is small', () => {
+    const each = Math.floor(CLIENT_INLINE_ATTACHMENT_CHARS * 0.9);
+    const count = Math.ceil(CLIENT_INLINE_EVENT_CHARS / each) + 1;
+    const event = prompt(
+      Array.from({ length: count }, (_, i) => ({ kind: 'image' as const, content: base64Of(each), mediaType: 'image/png', name: `${i}.png` })),
+    );
+    const slim = eventForClient(event) as UserPromptEvent;
+    const sent = slim.attachments ?? [];
+    const inline = sent.reduce((n, a) => n + a.content.length, 0);
+    expect(inline).toBeLessThanOrEqual(CLIENT_INLINE_EVENT_CHARS);
+    expect(firstAttachment(slim).content.length).toBe(each);
+    expect(sent.at(-1)?.omittedBytes).toBeGreaterThan(0);
+  });
+});
+
+describe('attachmentBytes', () => {
+  it('decodes base64 length for binary kinds and reports the omitted size when present', () => {
+    expect(attachmentBytes({ kind: 'image', content: 'QUJD', mediaType: 'image/png' })).toBe(3);
+    expect(attachmentBytes({ kind: 'image', content: 'QUI=', mediaType: 'image/png' })).toBe(2);
+    expect(attachmentBytes({ kind: 'file', content: 'hello' })).toBe(5);
+    expect(attachmentBytes({ kind: 'document', content: '', omittedBytes: 1234 })).toBe(1234);
+  });
+});
+
+describe('readAttachmentChunk', () => {
+  it('returns one bounded slice and the total, so a client can rebuild the content', () => {
+    const content = base64Of(ATTACHMENT_READ_CHUNK_CHARS * 2 + 10);
+    const event = prompt([{ kind: 'document', content, mediaType: 'application/pdf' }]);
+    let rebuilt = '';
+    let offset = 0;
+    for (;;) {
+      const chunk = readAttachmentChunk(event, 0, offset);
+      expect(chunk.total).toBe(content.length);
+      expect(chunk.data.length).toBeLessThanOrEqual(ATTACHMENT_READ_CHUNK_CHARS);
+      rebuilt += chunk.data;
+      offset += chunk.data.length;
+      if (offset >= chunk.total) break;
+    }
+    expect(rebuilt).toBe(content);
+  });
+
+  it('throws for an event or index that has no such attachment', () => {
+    const chunk = { type: 'assistant_chunk', seq: 1, ts: 0, turnId: 't1', delta: 'hi' } as unknown as MoxxyEvent;
+    expect(() => readAttachmentChunk(chunk, 0, 0)).toThrow(/no attachments/);
+    expect(() => readAttachmentChunk(prompt([]), 0, 0)).toThrow(/no attachment 0/);
+  });
+});
+
+describe('historyPageForClient', () => {
+  const text = (seq: number, chars: number): MoxxyEvent =>
+    ({ type: 'assistant_message', seq, ts: 0, turnId: 't1', content: 'x'.repeat(chars) }) as unknown as MoxxyEvent;
+
+  it('passes a small page through with its cursor', () => {
+    const page = { events: [text(3, 10), text(4, 10)], prevCursor: 3 };
+    expect(historyPageForClient(page)).toEqual(page);
+  });
+
+  it('drops the oldest events until the page fits, pointing the cursor at the oldest kept', () => {
+    const quarter = Math.floor(HISTORY_PAGE_MAX_CHARS / 4);
+    const page = historyPageForClient({
+      events: [0, 1, 2, 3, 4, 5].map((seq) => text(seq, quarter)),
+      prevCursor: null,
+    });
+    expect(page.events.map((e) => e.seq)).toEqual([3, 4, 5]);
+    expect(page.prevCursor).toBe(3);
+  });
+
+  it('always keeps the newest event so paging advances', () => {
+    const page = historyPageForClient({
+      events: [text(8, 10), text(9, HISTORY_PAGE_MAX_CHARS * 2)],
+      prevCursor: 8,
+    });
+    expect(page.events.map((e) => e.seq)).toEqual([9]);
+    expect(page.prevCursor).toBe(9);
+  });
+});
+
+describe('finding an earlier attachment', () => {
+  const at = (seq: number, attachments: ReadonlyArray<UserPromptAttachment>): MoxxyEvent =>
+    ({ ...prompt(attachments), seq }) as MoxxyEvent;
+  const events = [
+    at(2, [{ kind: 'document', content: 'OLD', mediaType: 'application/pdf', name: 'umowa.pdf' }]),
+    at(5, [
+      { kind: 'image', content: 'IMG', mediaType: 'image/png', name: 'shot.png' },
+      { kind: 'document', content: 'NEW', mediaType: 'application/pdf', name: 'Umowa.pdf' },
+    ]),
+  ];
+
+  it('finds one by its key or, newest first, by its name whatever the case', () => {
+    expect(findAttachment(events, '2:0')).toMatchObject({ seq: 2, index: 0, attachment: { content: 'OLD' } });
+    expect(findAttachment(events, 'umowa.pdf')).toMatchObject({ seq: 5, index: 1, attachment: { content: 'NEW' } });
+    expect(findAttachment(events, 'shot.png')).toMatchObject({ seq: 5, index: 0 });
+    expect(findAttachment(events, 'missing.pdf')).toBeNull();
+    expect(findAttachment(events, '9:0')).toBeNull();
+  });
+
+  it('lists every attachment of the conversation by key and name', () => {
+    expect(listAttachments(events)).toEqual(['2:0 umowa.pdf', '5:0 shot.png', '5:1 Umowa.pdf']);
+  });
+
+  it('reads the reference out of a restoring recall result, and nothing out of anything else', () => {
+    expect(restoredAttachmentRef({ forModel: 'restored', restoredAttachment: { seq: 2, index: 0 } })).toEqual({ seq: 2, index: 0 });
+    expect(restoredAttachmentRef('text')).toBeNull();
+    expect(restoredAttachmentRef({ restoredAttachment: { seq: '2', index: 0 } })).toBeNull();
+    expect(restoredAttachmentRef(null)).toBeNull();
+  });
+});

package/src/attachment-payload.ts

@@ -0,0 +1,187 @@
+import type { MoxxyEvent, UserPromptAttachment } from './events.js';
+
+/**
+ * Attachment bytes travel two very different roads. The model needs them in
+ * full; a client that only DRAWS the conversation (desktop, a channel
+ * bot) does not, and pushing a scanned 30 MB PDF through the client link on
+ * every reconnect is what once wedged a chat in a reconnect loop. So the runner
+ * sends clients {@link eventForClient} — large payloads swapped for their size —
+ * and a client that wants the bytes (an image preview) reads them back in
+ * bounded slices with {@link readAttachmentChunk}. The log itself never changes.
+ */
+
+/**
+ * The most attachment payload (base64 characters) one model request carries.
+ * Every request resends the whole conversation, so without a cap a chat with a
+ * few scanned PDFs outgrows the provider's request limit (Anthropic: 32 MB) and
+ * EVERY later turn fails. The newest attachments go in full; older ones that no
+ * longer fit become a note naming them.
+ */
+export const MODEL_ATTACHMENT_BUDGET_CHARS = 20 * 1024 * 1024;
+
+/** One attachment's payload above this travels to clients by size only. */
+export const CLIENT_INLINE_ATTACHMENT_CHARS = 512 * 1024;
+/** All of one event's inline attachment payloads together stay under this. */
+export const CLIENT_INLINE_EVENT_CHARS = 1024 * 1024;
+/** The largest slice one attachment read returns. */
+export const ATTACHMENT_READ_CHUNK_CHARS = 1024 * 1024;
+
+/** Whether `content` is base64 bytes rather than text. Raw audio carries a media type; a transcript does not. */
+function isBase64Payload(att: UserPromptAttachment): boolean {
+  return att.kind === 'image' || att.kind === 'document' || (att.kind === 'audio' && att.mediaType !== undefined);
+}
+
+/** The attachment's size in bytes — its real size even on a client copy whose bytes were left out. */
+export function attachmentBytes(att: UserPromptAttachment): number {
+  if (att.omittedBytes !== undefined) return att.omittedBytes;
+  if (!isBase64Payload(att)) return att.content.length;
+  const padding = att.content.endsWith('==') ? 2 : att.content.endsWith('=') ? 1 : 0;
+  return Math.max(0, Math.floor((att.content.length * 3) / 4) - padding);
+}
+
+/**
+ * The copy of `event` a client receives: every attachment payload too large for
+ * the client link becomes `content: ''` plus `omittedBytes`. Returns `event`
+ * itself when nothing had to change, so the common case allocates nothing.
+ */
+export function eventForClient(event: MoxxyEvent): MoxxyEvent {
+  if (event.type !== 'user_prompt' || !event.attachments || event.attachments.length === 0) return event;
+  let room = CLIENT_INLINE_EVENT_CHARS;
+  let changed = false;
+  const attachments = event.attachments.map((att) => {
+    const size = att.content.length;
+    if (size <= CLIENT_INLINE_ATTACHMENT_CHARS && size <= room) {
+      room -= size;
+      return att;
+    }
+    changed = true;
+    return { ...att, content: '', omittedBytes: attachmentBytes(att) };
+  });
+  return changed ? { ...event, attachments } : event;
+}
+
+/**
+ * The most one history page may weigh on the wire, in JSON characters. Paging
+ * counts events, and a few hundred events with screenshots or attachments can
+ * add up to tens of megabytes — one frame the client has to swallow whole.
+ */
+export const HISTORY_PAGE_MAX_CHARS = 4 * 1024 * 1024;
+
+/** One newest-first history page: ascending events plus the cursor to the next older page. */
+export interface HistoryPage {
+  readonly events: ReadonlyArray<MoxxyEvent>;
+  readonly prevCursor: number | null;
+}
+
+/**
+ * The page as a client receives it: every event in its client form, and the
+ * oldest events dropped until the page fits {@link HISTORY_PAGE_MAX_CHARS}. The
+ * newest event always stays, so paging always advances; the dropped events
+ * come back on the next older page.
+ */
+export function historyPageForClient(page: HistoryPage): HistoryPage {
+  const events = page.events.map(eventForClient);
+  let room = HISTORY_PAGE_MAX_CHARS;
+  let start = events.length;
+  while (start > 0) {
+    const event = events[start - 1];
+    if (event === undefined) break;
+    const size = JSON.stringify(event).length + 1;
+    if (size > room && start < events.length) break;
+    room -= size;
+    start -= 1;
+  }
+  if (start === 0) return { events, prevCursor: page.prevCursor };
+  const kept = events.slice(start);
+  const oldest = kept[0];
+  return { events: kept, prevCursor: oldest === undefined ? page.prevCursor : oldest.seq };
+}
+
+/** One slice of an attachment's `content`, starting at `offset` (in characters). */
+export interface AttachmentChunk {
+  readonly data: string;
+  /** The full `content` length, so the reader knows when it has everything. */
+  readonly total: number;
+}
+
+/**
+ * Slice attachment `index` of `event`. Slices start on a multiple of four
+ * characters when `offset` does, so base64 slices decode on their own too.
+ */
+export function readAttachmentChunk(event: MoxxyEvent, index: number, offset: number): AttachmentChunk {
+  if (event.type !== 'user_prompt' || !event.attachments) {
+    throw new Error(`event ${event.seq} has no attachments`);
+  }
+  const att = event.attachments[index];
+  if (!att) throw new Error(`event ${event.seq} has no attachment ${index}`);
+  const start = Math.max(0, Math.floor(offset));
+  return { data: att.content.slice(start, start + ATTACHMENT_READ_CHUNK_CHARS), total: att.content.length };
+}
+
+/** How an attachment is named across the conversation: `seq:index` of the prompt that carried it. */
+export function attachmentKey(seq: number, index: number): string {
+  return `${seq}:${index}`;
+}
+
+/** One attachment found in the log, with where it sits. */
+export interface FoundAttachment {
+  readonly seq: number;
+  readonly index: number;
+  readonly attachment: UserPromptAttachment;
+}
+
+function* attachmentsNewestFirst(events: ReadonlyArray<MoxxyEvent>): Generator<FoundAttachment> {
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const e = events[i];
+    if (!e || e.type !== 'user_prompt' || !e.attachments) continue;
+    for (let index = e.attachments.length - 1; index >= 0; index -= 1) {
+      const attachment = e.attachments[index];
+      if (attachment) yield { seq: e.seq, index, attachment };
+    }
+  }
+}
+
+/**
+ * The attachment `query` names: its key (`seq:index`) or its file name, the
+ * newest one of that name, whatever the case. Null when none matches.
+ */
+export function findAttachment(events: ReadonlyArray<MoxxyEvent>, query: string): FoundAttachment | null {
+  const wanted = query.trim();
+  const byKey = /^(\d+):(\d+)$/u.exec(wanted);
+  const name = wanted.toLowerCase();
+  for (const found of attachmentsNewestFirst(events)) {
+    if (byKey) {
+      if (found.seq === Number(byKey[1]) && found.index === Number(byKey[2])) return found;
+    } else if (found.attachment.name?.toLowerCase() === name) {
+      return found;
+    }
+  }
+  return null;
+}
+
+/** Every attachment of the conversation, oldest first, as `seq:index name`. */
+export function listAttachments(events: ReadonlyArray<MoxxyEvent>): string[] {
+  return [...attachmentsNewestFirst(events)]
+    .reverse()
+    .map(({ seq, index, attachment }) => `${attachmentKey(seq, index)} ${attachment.name ?? attachment.kind}`);
+}
+
+/**
+ * What `recall({ attachment })` returns for an image or a document: a pointer,
+ * not the bytes, which stay once in the log. The projection puts the
+ * attachment itself beside this result, so the model sees the original again
+ * even after its turn was summarized away.
+ */
+export interface RestoredAttachmentOutput {
+  readonly forModel: string;
+  readonly restoredAttachment: { readonly seq: number; readonly index: number };
+}
+
+/** The attachment a recall result restores, or null for any other output. */
+export function restoredAttachmentRef(output: unknown): { seq: number; index: number } | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const ref = (output as { restoredAttachment?: unknown }).restoredAttachment;
+  if (typeof ref !== 'object' || ref === null) return null;
+  const { seq, index } = ref as { seq?: unknown; index?: unknown };
+  return typeof seq === 'number' && typeof index === 'number' ? { seq, index } : null;
+}

package/src/auto-approve.test.ts

@@ -1,11 +1,12 @@
 import { describe, expect, it } from 'vitest';
-import { AUTO_APPROVE_PLUGIN_ID, AUTO_APPROVE_SUBTYPE, autoApproveFromEvents, autoApproveSwitch } from './auto-approve.js';
+import { AUTO_APPROVE_PLUGIN_ID, AUTO_APPROVE_SUBTYPE, autoApproveFromAgent, autoApproveFromEvents, autoApproveRecorded, autoApproveSwitch } from './auto-approve.js';
 import type { MoxxyEvent } from './events.js';
 
 let seq = 0;
 const base = () => ({ id: `e${seq}`, seq: seq++, ts: 0, sessionId: 's', turnId: 't' }) as const;
 const switched = (enabled: unknown): MoxxyEvent =>
   ({ ...base(), type: 'plugin_event', source: 'user', pluginId: AUTO_APPROVE_PLUGIN_ID, subtype: AUTO_APPROVE_SUBTYPE, payload: { enabled } }) as unknown as MoxxyEvent;
+const fromSystem = (enabled: boolean): MoxxyEvent => ({ ...switched(enabled), source: 'system' }) as MoxxyEvent;
 const prompt = (): MoxxyEvent => ({ ...base(), type: 'user_prompt', source: 'user', text: 'hi' }) as unknown as MoxxyEvent;
 const otherPlugin = (): MoxxyEvent =>
   ({ ...base(), type: 'plugin_event', source: 'plugin', pluginId: 'x', subtype: AUTO_APPROVE_SUBTYPE, payload: { enabled: true } }) as unknown as MoxxyEvent;
@@ -26,4 +27,15 @@ describe('auto-approve fold', () => {
     expect(autoApproveSwitch(otherPlugin())).toBeNull();
     expect(autoApproveSwitch(switched('yes'))).toBeNull();
   });
+
+  it('says whether the conversation recorded a switch at all, even one back to off', () => {
+    expect(autoApproveRecorded([prompt(), otherPlugin()])).toBe(false);
+    expect(autoApproveRecorded([switched(true), prompt(), switched(false)])).toBe(true);
+  });
+
+  it("says whether the switch in force is the agent's own setup Moxxy took on, not the person's choice", () => {
+    expect(autoApproveFromAgent([prompt()])).toBe(false);
+    expect(autoApproveFromAgent([fromSystem(true), prompt()])).toBe(true);
+    expect(autoApproveFromAgent([fromSystem(true), switched(false), switched(true)])).toBe(false);
+  });
 });

package/src/auto-approve.ts

@@ -9,6 +9,11 @@ import { asPluginId } from './ids.js';
  */
 export const AUTO_APPROVE_PLUGIN_ID = asPluginId('@moxxy/auto-approve');
 export const AUTO_APPROVE_SUBTYPE = 'auto_approve';
+/**
+ * An agent connection undid a change made outside Moxxy that let the agent act
+ * without asking: a note for the person, not a switch (the state stays as it was).
+ */
+export const AUTO_APPROVE_RESTORED_SUBTYPE = 'auto_approve_restored';
 
 /** The on/off an event records, or null when it isn't an auto-approve switch. */
 export function autoApproveSwitch(event: MoxxyEvent): boolean | null {
@@ -27,3 +32,17 @@ export function autoApproveFromEvents(events: ReadonlyArray<MoxxyEvent>): boolea
   }
   return false;
 }
+
+/** Whether the conversation recorded any switch (the person's, or the agent's own setup Moxxy took on): until then its agent's own setup shows. */
+export function autoApproveRecorded(events: ReadonlyArray<MoxxyEvent>): boolean {
+  return events.some((event) => autoApproveSwitch(event) !== null);
+}
+
+/** Whether the switch in force is the agent's own setup Moxxy took on (recorded by the system), not the person's choice. */
+export function autoApproveFromAgent(events: ReadonlyArray<MoxxyEvent>): boolean {
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i];
+    if (event && autoApproveSwitch(event) !== null) return event.source !== 'user';
+  }
+  return false;
+}

package/src/channel-auth.ts

@@ -14,7 +14,7 @@
  *     cannot set an `Authorization` header (browser / React Native), so the
  *     secret stays out of the URL (query strings leak via logs and QR/stdout).
  *
- * Channels that expose a network surface (mobile WS bridge, HTTP, web) should
+ * Channels that expose a network surface (HTTP, web) should
  * resolve their token with the former and gate connections with the latter,
  * so the `channels.<name>.token` config + `MOXXY_<NAME>_TOKEN` env conventions
  * are uniform across every channel.
@@ -30,9 +30,9 @@ import { bearerTokenMatches } from './http-utils.js';
 export interface ChannelTokenOptions {
   /** Explicit token from channel config (`channels.<name>.token`). */
   readonly configured?: string;
-  /** Env var checked first, e.g. `MOXXY_MOBILE_TOKEN`. */
+  /** Env var checked first, e.g. `MOXXY_HTTP_TOKEN`. */
   readonly envVar?: string;
-  /** File to persist a generated token, e.g. `mobile-token`. */
+  /** File to persist a generated token, e.g. `http-token`. */
   readonly fileName: string;
   /** Directory the token file lives under. Defaults to the moxxy home dir;
    *  the desktop bridge passes its Electron `userData` dir here instead. */

package/src/channel.ts

@@ -241,7 +241,7 @@ export interface ChannelConnectStep {
   /**
    * Presentation of the channel's runtime connect value:
    * - `qr`: render a QR of the value plus the value itself (e.g. scan/open a
-   *   `t.me/<bot>` link, or a mobile pairing URL).
+   *   `t.me/<bot>` link).
    * - `url`: show the value as a copyable URL the user pastes elsewhere
    *   (Slack's Events Request URL).
    * - `instructions`: static `steps`, no runtime value.

package/src/client-session.ts

@@ -3,7 +3,8 @@ import type { CommandDef } from './command.js';
 import type { ModeDef } from './mode.js';
 import type { LLMProvider, ProviderDef } from './provider.js';
 import type { RequirementCheck, MoxxyRequirement } from './requirements.js';
-import type { SessionLike, SessionLogReader } from './session-like.js';
+import type { StandingAllowRule } from './permission.js';
+import type { SessionInfo, SessionLike, SessionLogReader } from './session-like.js';
 import type { Skill } from './skill.js';
 import type { ToolDef } from './tool.js';
 import type { Transcriber } from './transcriber.js';
@@ -80,7 +81,7 @@ export interface RequirementsClientView {
 }
 
 export interface PermissionsClientView {
-  addAllow(rule: { readonly name: string; readonly reason?: string }): Promise<void>;
+  addAllow(rule: StandingAllowRule): Promise<void>;
 }
 
 export interface ClientSession extends SessionLike {
@@ -99,4 +100,10 @@ export interface ClientSession extends SessionLike {
   /** Switch the conversation's auto-approve (read it from `getInfo().autoApprove`).
    *  Optional: a client of a runner without the shared switch has none. */
   setAutoApprove?(enabled: boolean): Promise<void>;
+  /** Stop one work the agent runs in the background (`AgentBackgroundWork.id`); `false` when it runs none such.
+   *  Optional: a client of a runner that cannot pass it on has none. */
+  stopBackgroundWork?(workId: string): Promise<boolean>;
+  /** Called with the new info when it changes outside a turn (e.g. an agent CLI
+   *  was found outdated); returns the unsubscribe. */
+  onInfoChanged?(listener: (info: SessionInfo) => void): () => void;
 }

package/src/computer-control.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod/v3';
 
 export const computerControlStateSchema = z.enum([
   'idle', 'background', 'foreground', 'waiting_for_focus',

package/src/conversation-history.test.ts

@@ -0,0 +1,184 @@
+/** The conversation as Moxxy keeps it: what a new agent session starts from, and what `recall` searches. */
+import { describe, expect, it } from 'vitest';
+import { conversationTurns, renderEarlierConversation, renderMissedTurns, searchConversation } from './conversation-history.js';
+import type { MoxxyEvent, MoxxyEventOfType, MoxxyEventType } from './events.js';
+import { asEventId, asSessionId, asToolCallId, asTurnId, type TurnId } from './ids.js';
+import type { EventLogReader } from './log.js';
+
+const sid = asSessionId('s1');
+
+function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {
+  return {
+    length: events.length,
+    at: (seq) => events[seq],
+    slice: (from = 0, to = events.length) => events.slice(from, to),
+    ofType: <T extends MoxxyEventType>(type: T): ReadonlyArray<MoxxyEventOfType<T>> =>
+      events.filter((e): e is MoxxyEventOfType<T> => e.type === type),
+    byTurn: (turnId: TurnId) => events.filter((e) => e.turnId === turnId),
+    toJSON: () => events,
+  };
+}
+
+/** A log built turn by turn: what the person said, what the agent did and answered. */
+function conversation(
+  turns: ReadonlyArray<{ said: string; reply?: string; tool?: { name: string; input: unknown }; checkpoint?: string; provider?: string }>,
+): MoxxyEvent[] {
+  const events: MoxxyEvent[] = [];
+  const push = (turnId: TurnId, partial: Record<string, unknown>) => {
+    const seq = events.length;
+    events.push({ id: asEventId(`e${seq}`), seq, ts: seq, sessionId: sid, turnId, ...partial } as MoxxyEvent);
+  };
+  turns.forEach((turn, index) => {
+    const turnId = asTurnId(`t${index + 1}`);
+    push(turnId, { type: 'user_prompt', source: 'user', text: turn.said });
+    if (turn.provider) push(turnId, { type: 'provider_request', source: 'system', provider: turn.provider, model: 'm' });
+    if (turn.tool) {
+      push(turnId, { type: 'tool_call_requested', source: 'model', callId: asToolCallId(`c${index}`), name: turn.tool.name, input: turn.tool.input });
+      push(turnId, { type: 'tool_result', source: 'tool', callId: asToolCallId(`c${index}`), ok: true, output: 'SECRET TOOL OUTPUT' });
+    }
+    if (turn.checkpoint) push(turnId, { type: 'user_prompt', source: 'system', text: turn.checkpoint, origin: { kind: 'checkpoint', name: 'x' } });
+    if (turn.reply) push(turnId, { type: 'assistant_message', source: 'model', content: turn.reply, stopReason: 'end_turn' });
+  });
+  return events;
+}
+
+describe('the turns of a conversation', () => {
+  it('reads each turn the person started: their words, the replies and the tools, never tool output or checkpoints', () => {
+    const log = reader(
+      conversation([
+        { said: 'Set the database to port 5433', tool: { name: 'Edit', input: { file_path: 'db/config.ts' } }, checkpoint: 'Continue.', reply: 'Done: 5433.' },
+        { said: 'Thanks' },
+      ]),
+    );
+
+    const turns = conversationTurns(log);
+
+    expect(turns.map((turn) => turn.number)).toEqual([1, 2]);
+    expect(turns[0]).toMatchObject({ said: ['Set the database to port 5433'], replies: ['Done: 5433.'], tools: ['Edit db/config.ts'] });
+    expect(turns[0]?.text).not.toContain('SECRET TOOL OUTPUT');
+    expect(turns[0]?.text).not.toContain('Continue.');
+  });
+});
+
+describe('what a new agent session gets of the conversation', () => {
+  it('is nothing on the first turn', () => {
+    const log = reader(conversation([{ said: 'Hello' }]));
+
+    expect(renderEarlierConversation(log, asTurnId('t1'))).toBeUndefined();
+  });
+
+  it('gives the earlier turns word for word, as history and not a request, and leaves out the turn running now', () => {
+    const log = reader(conversation([{ said: 'Use port 5433', reply: 'OK, 5433.' }, { said: 'What port did we pick?' }]));
+
+    const text = renderEarlierConversation(log, asTurnId('t2')) ?? '';
+
+    expect(text).toContain('not a new request');
+    expect(text).toContain('### Turn 1\nPerson: Use port 5433\nAgent: OK, 5433.');
+    expect(text).not.toContain('What port did we pick?');
+  });
+
+  it('keeps within its budget on a long conversation: the latest turns whole, a line for each older one', () => {
+    const turns = Array.from({ length: 300 }, (_, i) => ({ said: `Request ${i + 1}: ${'detail '.repeat(40)}`, reply: 'answer '.repeat(200) }));
+    turns[11] = { said: 'Set the database to port 5433', reply: 'Done.' };
+    const log = reader(conversation([...turns, { said: 'What port?' }]));
+
+    const text = renderEarlierConversation(log, asTurnId('t301'), 64_000) ?? '';
+
+    expect(text.length).toBeLessThan(66_000);
+    expect(text).toContain('### Turn 300');
+    expect(text).toContain('call recall before you answer');
+    expect(text).toContain('Never say you do not know, or offer to look, without searching first.');
+    expect(text).not.toContain('### Turn 12\n');
+    expect(text).toContain('- turn 1: Request 1');
+    expect(text).toMatch(/- turns \d+–\d+: not listed here; recall with a query finds them/);
+  });
+
+  it('cuts one turn too long for the budget and says how to read the rest', () => {
+    const log = reader(conversation([{ said: 'x'.repeat(50_000) }, { said: 'next' }]));
+
+    const text = renderEarlierConversation(log, asTurnId('t2'), 2_000) ?? '';
+
+    expect(text.length).toBeLessThan(2_600);
+    expect(text).toContain('recall({ turn: 1 })');
+  });
+});
+
+describe('what an agent coming back to the conversation gets of the turns it missed', () => {
+  it('is nothing when it never ran in this conversation: a new session of its own gets the whole conversation instead', () => {
+    const log = reader(conversation([{ said: 'Use port 5433', provider: 'codex-agent' }, { said: 'Which port?' }]));
+
+    expect(renderMissedTurns(log, 'claude-code', asTurnId('t2'))).toBeUndefined();
+  });
+
+  it('is nothing when it ran the turn before this one', () => {
+    const log = reader(conversation([{ said: 'Use port 5433', provider: 'claude-code' }, { said: 'Which port?', provider: 'claude-code' }]));
+
+    expect(renderMissedTurns(log, 'claude-code', asTurnId('t2'))).toBeUndefined();
+  });
+
+  it('gives, word for word and as history, only the turns another connection ran since its own last turn', () => {
+    const log = reader(
+      conversation([
+        { said: 'Use port 5433', reply: 'OK.', provider: 'claude-code' },
+        { said: 'Rename the table to orders', reply: 'Renamed it to orders.', provider: 'codex-agent' },
+        { said: 'And add an index', reply: 'Index added.', provider: 'anthropic' },
+        { said: 'What did Codex rename?', provider: 'claude-code' },
+      ]),
+    );
+
+    const text = renderMissedTurns(log, 'claude-code', asTurnId('t4')) ?? '';
+
+    expect(text).toContain('another connection');
+    expect(text).toContain('not a new request');
+    expect(text).toContain('### Turn 2\nPerson: Rename the table to orders\nAgent: Renamed it to orders.');
+    expect(text).toContain('### Turn 3\nPerson: And add an index\nAgent: Index added.');
+    expect(text).not.toContain('Use port 5433');
+    expect(text).not.toContain('What did Codex rename?');
+  });
+
+  it("ends by saying the record is over and the person's newest message comes next, so it is not taken for part of the record", () => {
+    const log = reader(
+      conversation([
+        { said: 'Use port 5433', reply: 'OK.', provider: 'claude-code' },
+        { said: 'Answer with OK', reply: 'OK', provider: 'codex-agent' },
+        { said: 'Create notes.txt', provider: 'claude-code' },
+      ]),
+    );
+
+    for (const text of [renderMissedTurns(log, 'claude-code', asTurnId('t3')), renderEarlierConversation(log, asTurnId('t3'))]) {
+      expect(text).toMatch(/End of Moxxy's record\. The person's newest message comes next: that is the request to act on\.$/);
+    }
+  });
+});
+
+describe('searching the conversation', () => {
+  const log = reader(
+    conversation([
+      { said: 'Ustawmy bazę na porcie 5433', reply: 'Zrobione.' },
+      { said: 'Add a login page', tool: { name: 'Write', input: { file_path: 'src/login.tsx', content: 'export function Login() {}' } }, reply: 'Added.' },
+      { said: 'jaki port bazy ustaliliśmy?' },
+    ]),
+  );
+
+  it('finds a turn by words in another form (port, porcie; bazy, bazę)', () => {
+    const [first] = searchConversation(log, 'port bazy', { exceptTurnId: asTurnId('t3') });
+
+    expect(first?.turn.number).toBe(1);
+    expect(first?.snippets.join(' ')).toContain('5433');
+  });
+
+  it('shows words that stand close together in one snippet', () => {
+    const [first] = searchConversation(log, 'baza port 5433', { exceptTurnId: asTurnId('t3') });
+
+    expect(first?.snippets).toHaveLength(1);
+  });
+
+  it('finds what a tool was given, such as a file it wrote', () => {
+    expect(searchConversation(log, 'login.tsx')[0]?.turn.number).toBe(2);
+  });
+
+  it('leaves out the turn asking and finds nothing for words never said', () => {
+    expect(searchConversation(log, 'ustaliliśmy', { exceptTurnId: asTurnId('t3') })).toEqual([]);
+    expect(searchConversation(log, 'kubernetes')).toEqual([]);
+  });
+});