vellum 0.2.1 → 0.2.7

package/src/__tests__/scheduler-recurrence.test.ts

@@ -0,0 +1,329 @@
+import { describe, test, expect, beforeEach, afterAll, mock } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = mkdtempSync(join(tmpdir(), 'scheduler-recurrence-test-'));
+
+mock.module('../util/platform.js', () => ({
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+  migrateToDataLayout: () => {},
+  migrateToWorkspaceLayout: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+import { initializeDb, getDb, resetDb } from '../memory/db.js';
+import { createTask } from '../tasks/task-store.js';
+import {
+  createSchedule,
+  getSchedule,
+  getScheduleRuns,
+} from '../schedule/schedule-store.js';
+import { startScheduler } from '../schedule/scheduler.js';
+
+initializeDb();
+
+/** Access the underlying bun:sqlite Database for raw parameterized queries. */
+function getRawDb(): import('bun:sqlite').Database {
+  return (getDb() as unknown as { $client: import('bun:sqlite').Database }).$client;
+}
+
+/** Force a schedule to be due by setting next_run_at in the past. */
+function forceScheduleDue(scheduleId: string): void {
+  getRawDb().run('UPDATE cron_jobs SET next_run_at = ? WHERE id = ?', [Date.now() - 1000, scheduleId]);
+}
+
+afterAll(() => {
+  resetDb();
+  try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
+});
+
+// Build an RRULE expression anchored at the given start date, recurring every minute.
+// This ensures the rule always has future occurrences relative to the test clock.
+function buildEveryMinuteRrule(dtstart: Date = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const ds = `${dtstart.getUTCFullYear()}${pad(dtstart.getUTCMonth() + 1)}${pad(dtstart.getUTCDate())}T${pad(dtstart.getUTCHours())}${pad(dtstart.getUTCMinutes())}${pad(dtstart.getUTCSeconds())}Z`;
+  return `DTSTART:${ds}\nRRULE:FREQ=MINUTELY;INTERVAL=1`;
+}
+
+// Build an RRULE expression that ended in the past (UNTIL already passed).
+function buildEndedRrule(): string {
+  const past = new Date(Date.now() - 86_400_000 * 30); // 30 days ago
+  const until = new Date(Date.now() - 86_400_000); // 1 day ago
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const ds = `${past.getUTCFullYear()}${pad(past.getUTCMonth() + 1)}${pad(past.getUTCDate())}T000000Z`;
+  const us = `${until.getUTCFullYear()}${pad(until.getUTCMonth() + 1)}${pad(until.getUTCDate())}T235959Z`;
+  return `DTSTART:${ds}\nRRULE:FREQ=DAILY;INTERVAL=1;UNTIL=${us}`;
+}
+
+// ── RRULE schedule fires through the scheduler ──────────────────────
+
+describe('scheduler RRULE execution', () => {
+  beforeEach(() => {
+    const db = getDb();
+    db.run('DELETE FROM cron_runs');
+    db.run('DELETE FROM cron_jobs');
+    db.run('DELETE FROM task_runs');
+    db.run('DELETE FROM tasks');
+    db.run('DELETE FROM messages');
+    db.run('DELETE FROM conversations');
+  });
+
+  test('RRULE schedule fires and creates cron_runs entry', async () => {
+    const rruleExpr = buildEveryMinuteRrule();
+    const schedule = createSchedule({
+      name: 'RRULE Test',
+      cronExpression: rruleExpr,
+      message: 'Hello from RRULE',
+      syntax: 'rrule',
+      expression: rruleExpr,
+    });
+
+    // Verify it was stored with rrule syntax
+    const stored = getSchedule(schedule.id);
+    expect(stored).not.toBeNull();
+    expect(stored!.syntax).toBe('rrule');
+
+    // Force it to be due
+    forceScheduleDue(schedule.id);
+
+    const processedMessages: { conversationId: string; message: string }[] = [];
+    const processMessage = async (conversationId: string, message: string) => {
+      processedMessages.push({ conversationId, message });
+    };
+
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    // processMessage should have been called with the RRULE message
+    expect(processedMessages.some(m => m.message === 'Hello from RRULE')).toBe(true);
+
+    // A cron_runs entry should have been created
+    const runs = getScheduleRuns(schedule.id);
+    expect(runs.length).toBeGreaterThanOrEqual(1);
+    expect(runs[0].status).toBe('ok');
+  });
+
+  test('RRULE run_task:<id> triggers task runner', async () => {
+    const task = createTask({
+      title: 'RRULE Task',
+      template: 'Execute RRULE task',
+    });
+
+    const rruleExpr = buildEveryMinuteRrule();
+    const schedule = createSchedule({
+      name: 'RRULE Task Schedule',
+      cronExpression: rruleExpr,
+      message: `run_task:${task.id}`,
+      syntax: 'rrule',
+      expression: rruleExpr,
+    });
+
+    forceScheduleDue(schedule.id);
+
+    const directCalls: { conversationId: string; message: string }[] = [];
+    const processMessage = async (conversationId: string, message: string) => {
+      directCalls.push({ conversationId, message });
+    };
+
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    // runTask renders the template, so processMessage gets the template text
+    const runTaskCalls = directCalls.filter(c => c.message === 'Execute RRULE task');
+    const rawCalls = directCalls.filter(c => c.message.startsWith('run_task:'));
+
+    expect(runTaskCalls.length).toBe(1);
+    expect(rawCalls.length).toBe(0);
+
+    // A cron_runs entry should exist
+    const runs = getScheduleRuns(schedule.id);
+    expect(runs.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test('ended RRULE (UNTIL in past) is not repeatedly claimed', async () => {
+    const endedExpr = buildEndedRrule();
+
+    // Insert directly via raw SQL because createSchedule would throw when
+    // computing nextRunAt for an already-ended RRULE. This simulates a
+    // schedule that was valid when created but has since expired.
+    const id = crypto.randomUUID();
+    const now = Date.now();
+    getRawDb().run(
+      `INSERT INTO cron_jobs (id, name, enabled, cron_expression, schedule_syntax, timezone, message, next_run_at, last_run_at, last_status, retry_count, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, 'Ended RRULE', 1, endedExpr, 'rrule', null, 'Should not fire', now - 1000, null, null, 0, 'agent', now, now],
+    );
+
+    const processedMessages: string[] = [];
+    const processMessage = async (_conversationId: string, message: string) => {
+      processedMessages.push(message);
+    };
+
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    // The ended RRULE should NOT have fired
+    expect(processedMessages).not.toContain('Should not fire');
+
+    // No runs should have been created
+    const runs = getScheduleRuns(id);
+    expect(runs.length).toBe(0);
+  });
+
+  test('existing cron schedule behavior is unchanged', async () => {
+    const schedule = createSchedule({
+      name: 'Cron Schedule',
+      cronExpression: '* * * * *',
+      message: 'Cron message',
+    });
+
+    // Verify it defaults to cron syntax
+    const stored = getSchedule(schedule.id);
+    expect(stored).not.toBeNull();
+    expect(stored!.syntax).toBe('cron');
+
+    forceScheduleDue(schedule.id);
+
+    const processedMessages: { conversationId: string; message: string }[] = [];
+    const processMessage = async (conversationId: string, message: string) => {
+      processedMessages.push({ conversationId, message });
+    };
+
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    // processMessage should have been called with the cron message
+    expect(processedMessages.some(m => m.message === 'Cron message')).toBe(true);
+
+    // A cron_runs entry should have been created
+    const runs = getScheduleRuns(schedule.id);
+    expect(runs.length).toBeGreaterThanOrEqual(1);
+    expect(runs[0].status).toBe('ok');
+  });
+
+  test('RRULE set with EXDATE skips excluded occurrence and advances to next valid date', async () => {
+    // Build an RRULE set that fires every minute but excludes the next immediate occurrence.
+    // The scheduler should skip the excluded date and advance to the one after.
+    const now = new Date();
+    const pad = (n: number) => String(n).padStart(2, '0');
+
+    // DTSTART one hour ago so there are plenty of past occurrences
+    const pastDate = new Date(now.getTime() - 3_600_000);
+    const ds = `${pastDate.getUTCFullYear()}${pad(pastDate.getUTCMonth() + 1)}${pad(pastDate.getUTCDate())}T${pad(pastDate.getUTCHours())}${pad(pastDate.getUTCMinutes())}${pad(pastDate.getUTCSeconds())}Z`;
+
+    // Exclude the current minute's occurrence
+    const currentMinuteDate = new Date(now);
+    currentMinuteDate.setUTCSeconds(0);
+    currentMinuteDate.setUTCMilliseconds(0);
+    // Round to the previous minute boundary relative to dtstart
+    const exDate = `${currentMinuteDate.getUTCFullYear()}${pad(currentMinuteDate.getUTCMonth() + 1)}${pad(currentMinuteDate.getUTCDate())}T${pad(currentMinuteDate.getUTCHours())}${pad(currentMinuteDate.getUTCMinutes())}00Z`;
+
+    const expression = `DTSTART:${ds}\nRRULE:FREQ=MINUTELY;INTERVAL=1\nEXDATE:${exDate}`;
+
+    const schedule = createSchedule({
+      name: 'RRULE set EXDATE test',
+      cronExpression: expression,
+      message: 'Set exclusion test',
+      syntax: 'rrule',
+      expression,
+    });
+
+    // Force the schedule to be due
+    forceScheduleDue(schedule.id);
+
+    const processedMessages: string[] = [];
+    const processMessage = async (_conversationId: string, message: string) => {
+      processedMessages.push(message);
+    };
+
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    // The schedule should have been claimed and nextRunAt advanced
+    const after = getSchedule(schedule.id);
+    expect(after).not.toBeNull();
+    expect(after!.lastRunAt).not.toBeNull();
+    // nextRunAt should be in the future (not the excluded date)
+    expect(after!.nextRunAt).toBeGreaterThan(Date.now() - 5000);
+  });
+
+  test('RRULE set schedule fires and creates cron_runs entry', async () => {
+    const expression = [
+      'DTSTART:20250101T000000Z',
+      'RRULE:FREQ=MINUTELY;INTERVAL=1',
+      'EXDATE:20250101T000100Z',
+    ].join('\n');
+
+    const schedule = createSchedule({
+      name: 'Set schedule fire test',
+      cronExpression: expression,
+      message: 'Set fire test',
+      syntax: 'rrule',
+      expression,
+    });
+
+    forceScheduleDue(schedule.id);
+
+    const processedMessages: string[] = [];
+    const processMessage = async (_conversationId: string, message: string) => {
+      processedMessages.push(message);
+    };
+
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    expect(processedMessages).toContain('Set fire test');
+
+    const runs = getScheduleRuns(schedule.id);
+    expect(runs.length).toBeGreaterThanOrEqual(1);
+    expect(runs[0].status).toBe('ok');
+  });
+
+  test('RRULE schedule advances nextRunAt after firing', async () => {
+    const rruleExpr = buildEveryMinuteRrule();
+    const schedule = createSchedule({
+      name: 'Advancing RRULE',
+      cronExpression: rruleExpr,
+      message: 'Advance test',
+      syntax: 'rrule',
+      expression: rruleExpr,
+    });
+
+    const originalNextRunAt = getSchedule(schedule.id)!.nextRunAt;
+    forceScheduleDue(schedule.id);
+    const forcedDueAt = getSchedule(schedule.id)!.nextRunAt;
+
+    const processMessage = async () => {};
+    const scheduler = startScheduler(processMessage, () => {}, () => {});
+    await new Promise(resolve => setTimeout(resolve, 500));
+    scheduler.stop();
+
+    const after = getSchedule(schedule.id);
+    expect(after).not.toBeNull();
+    // nextRunAt must have moved forward from the forced-due value
+    expect(after!.nextRunAt).toBeGreaterThan(forcedDueAt);
+    // It should be at or near the original computed value (within a few seconds tolerance)
+    expect(Math.abs(after!.nextRunAt - originalNextRunAt)).toBeLessThan(5000);
+    expect(after!.lastRunAt).not.toBeNull();
+  });
+});

package/src/__tests__/server-history-render.test.ts

@@ -24,12 +24,12 @@ mock.module('../util/logger.js', () => ({
   }),
 }));
 
-import { initializeDb, getDb } from '../memory/db.js';
+import { initializeDb, getDb, resetDb } from '../memory/db.js';
 import { renderHistoryContent, mergeToolResults } from '../daemon/handlers.js';
 import {
   uploadAttachment,
   linkAttachmentToMessage,
-  getAttachmentsForMessageUnscoped,
+  getAttachmentsForMessage,
 } from '../memory/attachments-store.js';
 import {
   createConversation,
@@ -39,6 +39,7 @@ import {
 initializeDb();
 
 afterAll(() => {
+  resetDb();
   try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
 });
 
@@ -370,7 +371,7 @@ describe('mergeToolResults', () => {
   });
 });
 
-describe('getAttachmentsForMessageUnscoped', () => {
+describe('getAttachmentsForMessage', () => {
   beforeEach(() => {
     const db = getDb();
     db.run('DELETE FROM message_attachments');
@@ -387,10 +388,10 @@ describe('getAttachmentsForMessageUnscoped', () => {
 
   test('returns attachments linked to a message', () => {
     const msgId = createMessage('assistant', 'Here is a chart');
-    const stored = uploadAttachment('ast-1', 'chart.png', 'image/png', 'iVBOR');
+    const stored = uploadAttachment('chart.png', 'image/png', 'iVBOR');
     linkAttachmentToMessage(msgId, stored.id, 0);
 
-    const result = getAttachmentsForMessageUnscoped(msgId);
+    const result = getAttachmentsForMessage(msgId);
     expect(result).toHaveLength(1);
     expect(result[0].id).toBe(stored.id);
     expect(result[0].originalFilename).toBe('chart.png');
@@ -399,32 +400,32 @@ describe('getAttachmentsForMessageUnscoped', () => {
   });
 
   test('returns empty array when no attachments are linked', () => {
-    expect(getAttachmentsForMessageUnscoped('msg-nonexistent')).toEqual([]);
+    expect(getAttachmentsForMessage('msg-nonexistent')).toEqual([]);
   });
 
   test('returns multiple attachments in position order', () => {
     const msgId = createMessage('assistant', 'Two files');
-    const a1 = uploadAttachment('ast-1', 'first.txt', 'text/plain', 'AAAA');
-    const a2 = uploadAttachment('ast-1', 'second.txt', 'text/plain', 'BBBB');
+    const a1 = uploadAttachment('first.txt', 'text/plain', 'AAAA');
+    const a2 = uploadAttachment('second.txt', 'text/plain', 'BBBB');
 
     linkAttachmentToMessage(msgId, a2.id, 1);
     linkAttachmentToMessage(msgId, a1.id, 0);
 
-    const result = getAttachmentsForMessageUnscoped(msgId);
+    const result = getAttachmentsForMessage(msgId);
     expect(result).toHaveLength(2);
     expect(result[0].originalFilename).toBe('first.txt');
     expect(result[1].originalFilename).toBe('second.txt');
   });
 
-  test('works across different assistantIds', () => {
+  test('returns all attachments linked to a message', () => {
     const msgId = createMessage('assistant', 'Mixed');
-    const a1 = uploadAttachment('ast-A', 'a.png', 'image/png', 'AAAA');
-    const a2 = uploadAttachment('ast-B', 'b.png', 'image/png', 'BBBB');
+    const a1 = uploadAttachment('a.png', 'image/png', 'AAAA');
+    const a2 = uploadAttachment('b.png', 'image/png', 'BBBB');
 
     linkAttachmentToMessage(msgId, a1.id, 0);
     linkAttachmentToMessage(msgId, a2.id, 1);
 
-    const result = getAttachmentsForMessageUnscoped(msgId);
+    const result = getAttachmentsForMessage(msgId);
     expect(result).toHaveLength(2);
   });
 });

package/src/__tests__/session-conflict-gate.test.ts

@@ -39,8 +39,18 @@ let resolverResult: {
 
 const persistedMessages: Array<{ id: string; role: string; content: string; createdAt: number }> = [];
 
+function makeMockLogger(): Record<string, unknown> {
+  const logger: Record<string, unknown> = {};
+  logger.child = () => logger;
+  logger.debug = () => {};
+  logger.info = () => {};
+  logger.warn = () => {};
+  logger.error = () => {};
+  return logger;
+}
+
 mock.module('../util/logger.js', () => ({
-  getLogger: () => new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+  getLogger: () => makeMockLogger(),
 }));
 
 mock.module('../util/platform.js', () => ({
@@ -305,7 +315,7 @@ describe('Session conflict soft gate', () => {
     await session.processMessage('Should I use React or Vue here?', [], (event) => events.push(event));
 
     expect(runCalls).toHaveLength(0);
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-relevant']);
     const clarificationEvent = events.find((event) => event.type === 'assistant_text_delta');
     expect(clarificationEvent).toBeDefined();
@@ -315,7 +325,7 @@ describe('Session conflict soft gate', () => {
     expect(events.some((event) => event.type === 'message_complete')).toBe(true);
   });
 
-  test('irrelevant unresolved conflict asks once and continues with normal answer flow', async () => {
+  test('irrelevant unresolved conflict does not inject side-question into normal answer flow', async () => {
     pendingConflicts = [{
       id: 'conflict-irrelevant',
       scopeId: 'default',
@@ -332,13 +342,6 @@ describe('Session conflict soft gate', () => {
       existingStatement: 'Use Postgres as the default database.',
       candidateStatement: 'Use MySQL as the default database.',
     }];
-    resolverResult = {
-      resolution: 'keep_existing',
-      strategy: 'heuristic',
-      resolvedStatement: null,
-      explanation: 'Resolved by accident.',
-    };
-
     const session = makeSession();
     await session.loadFromDb();
 
@@ -349,10 +352,10 @@ describe('Session conflict soft gate', () => {
     const injectedUser = runCalls[0][runCalls[0].length - 1];
     expect(injectedUser.role).toBe('user');
     const injectedText = extractText(injectedUser);
-    expect(injectedText).toContain('Memory clarification request');
-    expect(injectedText).toContain('Should I assume Postgres or MySQL?');
+    expect(injectedText).not.toContain('Memory clarification request');
+    expect(injectedText).not.toContain('Should I assume Postgres or MySQL?');
     expect(resolverCallCount).toBe(0);
-    expect(markAskedCalls).toEqual(['conflict-irrelevant']);
+    expect(markAskedCalls).toEqual([]);
     expect(events.some((event) => event.type === 'message_complete')).toBe(true);
   });
 
@@ -379,7 +382,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn asks the clarification and records it as asked.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-followup']);
 
     resolverResult = {
@@ -392,7 +395,7 @@ describe('Session conflict soft gate', () => {
     // Follow-up reply does not overlap statement tokens but should still resolve.
     await session.processMessage('Keep the new one.', [], () => {});
 
-    expect(resolverCallCount).toBe(2);
+    expect(resolverCallCount).toBe(1);
     expect(markAskedCalls).toEqual(['conflict-followup']);
     expect(runCalls).toHaveLength(1);
   });
@@ -420,7 +423,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn asks the clarification.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-concise']);
 
     resolverResult = {
@@ -433,7 +436,7 @@ describe('Session conflict soft gate', () => {
     // Short directional reply with no action verb should still resolve.
     await session.processMessage('both', [], () => {});
 
-    expect(resolverCallCount).toBe(2);
+    expect(resolverCallCount).toBe(1);
     expect(runCalls).toHaveLength(1);
   });
 
@@ -460,7 +463,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn: relevant question triggers clarification ask.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-unrelated']);
 
     // Second turn: unrelated question containing the cue word "new" should NOT
@@ -473,8 +476,8 @@ describe('Session conflict soft gate', () => {
     };
     await session.processMessage("What's new in Bun?", [], () => {});
 
-    // The resolver should NOT have been called again for this unrelated question.
-    expect(resolverCallCount).toBe(1);
+    // The resolver should NOT have been called for this unrelated question.
+    expect(resolverCallCount).toBe(0);
     // Normal agent loop should still run.
     expect(runCalls).toHaveLength(1);
   });
@@ -502,7 +505,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn: triggers clarification ask.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-unrelated-no-qmark']);
 
     resolverResult = {
@@ -516,11 +519,11 @@ describe('Session conflict soft gate', () => {
     // Should NOT resolve the conflict.
     await session.processMessage('I started a new project today', [], () => {});
 
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(runCalls).toHaveLength(1);
   });
 
-  test('cooldown prevents repeated asks on subsequent turns', async () => {
+  test('irrelevant conflicts remain silent across subsequent turns', async () => {
     pendingConflicts = [{
       id: 'conflict-cooldown',
       scopeId: 'default',
@@ -547,9 +550,9 @@ describe('Session conflict soft gate', () => {
     expect(runCalls).toHaveLength(2);
     const firstUserText = extractText(runCalls[0][runCalls[0].length - 1]);
     const secondUserText = extractText(runCalls[1][runCalls[1].length - 1]);
-    expect(firstUserText).toContain('Memory clarification request');
+    expect(firstUserText).not.toContain('Memory clarification request');
     expect(secondUserText).not.toContain('Memory clarification request');
-    expect(markAskedCalls).toEqual(['conflict-cooldown']);
+    expect(markAskedCalls).toEqual([]);
   });
 
   test('passes session scopeId through to conflict store queries', async () => {

package/src/__tests__/session-error.test.ts

@@ -117,6 +117,34 @@ describe('classifySessionError', () => {
     }
   });
 
+  describe('timeout errors (generic, not network/gateway)', () => {
+    const cases = [
+      'timeout',
+      'deadline exceeded',
+      'request timed out',
+    ];
+
+    for (const msg of cases) {
+      it(`classifies "${msg}" as PROVIDER_API with timeout message`, () => {
+        const result = classifySessionError(new Error(msg), baseCtx);
+        expect(result.code).toBe('PROVIDER_API');
+        expect(result.userMessage).toContain('took too long');
+        expect(result.retryable).toBe(true);
+      });
+    }
+
+    it('does not steal "connection timeout" from PROVIDER_NETWORK', () => {
+      const result = classifySessionError(new Error('connection timeout'), baseCtx);
+      expect(result.code).toBe('PROVIDER_NETWORK');
+    });
+
+    it('does not steal "Gateway timeout" from PROVIDER_API', () => {
+      const result = classifySessionError(new Error('Gateway timeout'), baseCtx);
+      expect(result.code).toBe('PROVIDER_API');
+      expect(result.userMessage).toContain('returned an error');
+    });
+  });
+
   describe('context-too-large errors', () => {
     const cases = [
       'context_length_exceeded',