From 398ee1ef064afd1a92bd4fd4143daaf86da06bd6 Mon Sep 17 00:00:00 2001 From: Linus Rath <139418639+rathlinus@users.noreply.github.com> Date: Mon, 2 Nov 2026 22:07:32 +0100 Subject: [PATCH] feat: let plugins read a whole conversation --- lib/__tests__/plugin-host-thread.test.ts | 114 ++++++++++++++++++++++ lib/plugin-sandbox/assistant/b.runtime.ts | 7 ++ lib/plugin-sandbox/assistant/b.ts | 40 +++++++- lib/plugin-sandbox/assistant/b.types.ts | 2 + 4 files changed, 159 insertions(+), 4 deletions(-) create mode 100644 lib/__tests__/plugin-host-thread.test.ts diff --git a/lib/__tests__/plugin-host-thread.test.ts b/lib/__tests__/plugin-host-thread.test.ts new file mode 100644 index 000000000..4181cb2d1 --- /dev/null +++ b/lib/__tests__/plugin-host-thread.test.ts @@ -0,0 +1,114 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { InstalledPlugin, EmailReadView } from '../plugin-types'; +import type { IJMAPClient } from '../jmap/client-interface'; +import type { Email, Mailbox } from '../jmap/types'; +import { useAuthStore } from '@/stores/auth-store'; +import { useEmailStore } from '@/stores/email-store'; + +vi.mock('@/stores/toast-store', () => ({ + toast: { success: vi.fn(), error: vi.fn(), info: vi.fn(), warning: vi.fn() }, +})); + +import { dispatchApiCall, PERM_PER_METHOD } from '../plugin-sandbox/host-api'; +import { resetPluginRateLimits } from '../plugin-sandbox/host-api-input'; +import { snapshotHostFeatures } from '../plugin-sandbox/host-features'; +import { withAssistantRuntime } from '../plugin-sandbox/assistant/runtime'; + +function plugin(perms: string[], id = 'ai-assistant'): InstalledPlugin { + return { + id, name: 'AI Assistant', version: '2.2.0', author: 'test', description: '', + type: 'hook', permissions: perms, grantedPermissions: perms, entrypoint: 'index.js', + enabled: true, status: 'running', settings: {}, + }; +} + +const ASSISTANT = plugin(['email:read']); +const call = (p: InstalledPlugin, ...args: unknown[]) => dispatchApiCall(p, 'email.getThread', args) as Promise; + +const mail = (id: string, hoursAfter: number, subject: string, threadId = 't1'): Email => ({ + id, threadId, mailboxIds: { inbox: true }, keywords: {}, subject, from: [{ name: 'Bob', email: 'bob@example.org' }], + receivedAt: new Date(Date.UTC(2026, 9, 1, hoursAfter)).toISOString(), + textBody: [{ partId: '1', blobId: `b-${id}`, size: 1, type: 'text/plain' }], + bodyValues: { 1: { value: `${subject} body` } }, +} as unknown as Email); + +// The server lists a thread's messages in its own order; the API sorts them. +const THREAD = [mail('m3', 30, 'Re: Re: Report'), mail('m1', 10, 'Report'), mail('m2', 20, 'Re: Report')]; + +let client: Record>; + +beforeEach(() => { + resetPluginRateLimits(); + client = { + getEmail: vi.fn(async (id: string, accountId?: string) => { + if (accountId === 'shared-acc') return id === 's1' ? mail('s1', 1, 'Team news', 'ts') : null; + return THREAD.find((e) => e.id === id) ?? (id === 'lonely' ? mail('lonely', 5, 'Alone', 'tl') : null); + }), + getThreadEmails: vi.fn(async (threadId: string, accountId?: string) => { + if (threadId === 't1' && !accountId) return THREAD; + if (threadId === 'ts' && accountId === 'shared-acc') return [mail('s2', 2, 'Re: Team news', 'ts'), mail('s1', 1, 'Team news', 'ts')]; + if (threadId === 'big') return Array.from({ length: 60 }, (_, i) => mail(`b${i}`, i, `Part ${i}`, 'big')); + return []; + }), + getAccountId: vi.fn(() => 'acc1'), + getMailboxes: vi.fn(async () => [{ id: 'shared-inbox', name: 'Team', isShared: true, accountId: 'shared-acc' } as unknown as Mailbox]), + }; + useAuthStore.setState({ client: client as unknown as IJMAPClient }); + useEmailStore.setState({ selectedEmail: null, emails: [], mailboxes: [], selectedMailbox: '' }); +}); + +afterEach(() => { + useAuthStore.setState({ client: null }); +}); + +describe('api.email.getThread', () => { + it('is behind email:read, offered in the runtime and announced in the host features', async () => { + expect(PERM_PER_METHOD['email.getThread']).toBe('email:read'); + await expect(call(plugin(['email:blob-read']), 'm2')).rejects.toThrow(/lacks permission "email:read"/); + expect(client.getThreadEmails).not.toHaveBeenCalled(); + expect(snapshotHostFeatures()).toMatchObject({ threads: true }); + const calls: unknown[][] = []; + const api = withAssistantRuntime({} as { email?: { getThread?: (...a: unknown[]) => unknown } }, async (method, args) => { calls.push([method, args]); return []; }); + await api.email?.getThread?.('m2'); + expect(calls).toEqual([['email.getThread', ['m2', undefined]]]); + }); + + it('returns every message of the conversation, oldest first, with their text', async () => { + const thread = await call(ASSISTANT, 'm2'); + expect(thread.map((e) => [e.id, e.subject, e.text, e.accountId])).toEqual([ + ['m1', 'Report', 'Report body', 'acc1'], + ['m2', 'Re: Report', 'Re: Report body', 'acc1'], + ['m3', 'Re: Re: Report', 'Re: Re: Report body', 'acc1'], + ]); + expect(client.getThreadEmails).toHaveBeenCalledWith('t1', undefined); + }); + + it('reads a shared account\'s conversation from that account', async () => { + const thread = await call(ASSISTANT, 's1', { accountId: 'shared-acc' }); + expect(thread.map((e) => [e.id, e.accountId])).toEqual([['s1', 'shared-acc'], ['s2', 'shared-acc']]); + expect(client.getThreadEmails).toHaveBeenCalledWith('ts', 'shared-acc'); + }); + + it('refuses an account this login does not show, and a missing message', async () => { + await expect(call(ASSISTANT, 'm2', { accountId: 'stranger' })).rejects.toThrow(/no message with id "m2"/); + await expect(call(ASSISTANT, 'nope')).rejects.toThrow(/no message with id "nope"/); + expect(client.getThreadEmails).not.toHaveBeenCalled(); + }); + + it('gives the message alone when the server lists no thread, and at most the newest 50', async () => { + expect((await call(ASSISTANT, 'lonely')).map((e) => e.id)).toEqual(['lonely']); + client.getEmail.mockResolvedValueOnce(mail('b59', 59, 'Part 59', 'big')); + const big = await call(ASSISTANT, 'b59'); + expect(big).toHaveLength(50); + expect(big[0].id).toBe('b10'); + expect(big[49].id).toBe('b59'); + }); + + it('checks its options and allows 60 reads a minute', async () => { + await expect(call(ASSISTANT, 'm2', { threadId: 't1' })).rejects.toThrow(/unknown property "threadId"/); + await expect(call(ASSISTANT, 42)).rejects.toThrow(/emailId must be a string/); + resetPluginRateLimits(); + for (let i = 0; i < 60; i++) await call(ASSISTANT, 'm1'); + await expect(call(ASSISTANT, 'm1')).rejects.toThrow(/too many reads/); + }); +}); diff --git a/lib/plugin-sandbox/assistant/b.runtime.ts b/lib/plugin-sandbox/assistant/b.runtime.ts index 9973d9a35..44699cdb4 100644 --- a/lib/plugin-sandbox/assistant/b.runtime.ts +++ b/lib/plugin-sandbox/assistant/b.runtime.ts @@ -1,6 +1,7 @@ // Area b of the assistant's host APIs, inside the plugin sandbox (see README.md). import type { CallApi, RuntimeAdditions } from './runtime'; +import type { EmailReadView } from '../../plugin-types'; import type { AttachmentImageOptions, AttachmentImageView, AttachmentTextOptions, AttachmentTextView } from './b.types'; /** Reads that download and unpack a file get the network timeout. */ @@ -25,6 +26,12 @@ export function runtime(callApi: CallApi): RuntimeAdditions { */ getAttachmentImage: (emailId: string, blobId: string, options?: AttachmentImageOptions) => callApi('email.getAttachmentImage', [emailId, blobId, options], READ_TIMEOUT_MS) as Promise, + /** + * Every message of the conversation a message belongs to, oldest + * first, at most the newest 50 (email:read, 60 a minute). + */ + getThread: (emailId: string, options?: { accountId?: string }) => + callApi('email.getThread', [emailId, options], READ_TIMEOUT_MS) as Promise, }, }; } diff --git a/lib/plugin-sandbox/assistant/b.ts b/lib/plugin-sandbox/assistant/b.ts index 08cdd5617..b82138693 100644 --- a/lib/plugin-sandbox/assistant/b.ts +++ b/lib/plugin-sandbox/assistant/b.ts @@ -1,8 +1,8 @@ // Area b of the assistant's host APIs, host side (see README.md): more -// context for the assistant. The text of an attachment, and an image -// attachment shrunk to what a model needs. +// context for the assistant. The text of an attachment, an image +// attachment shrunk to what a model needs, and a whole conversation. -import type { InstalledPlugin, Permission } from '../../plugin-types'; +import type { EmailReadView, InstalledPlugin, Permission } from '../../plugin-types'; import type { IJMAPClient } from '../../jmap/client-interface'; import type { Attachment, Email } from '../../jmap/types'; import { NOT_MINE } from './not-mine'; @@ -13,17 +13,23 @@ import { readBoolean, readId, readInteger, readObject, sessionClient, withinRate import { DEFAULT_TEXT_CHARS, MAX_TEXT_CHARS, MAX_TEXT_SOURCE_BYTES, extractText, textFormatOf } from '@/lib/attachment-text'; import { DEFAULT_IMAGE_SIDE, MAX_IMAGE_SIDE, MIN_IMAGE_SIDE, shrinkImage, toBase64 } from '@/lib/image-shrink'; import { readPhotoExif } from '@/lib/exif'; +import { emailToReadView } from '@/lib/plugin-projection'; /** Method → permission, joined into PERM_PER_METHOD. */ export const PERMS: Readonly> = { 'email.getAttachmentText': 'email:blob-read', 'email.getAttachmentImage': 'email:blob-read', + 'email.getThread': 'email:read', }; /** Attachment reads (text) a plugin may make per minute. */ export const MAX_ATTACHMENT_TEXT_PER_MINUTE = 30; /** Attachment reads (images) a plugin may make per minute. */ export const MAX_ATTACHMENT_IMAGE_PER_MINUTE = 30; +/** Conversations a plugin may read per minute. */ +export const MAX_THREADS_PER_MINUTE = 60; +/** Most messages api.email.getThread returns (the newest of a longer conversation). */ +export const MAX_THREAD_MESSAGES = 50; interface FoundAttachment { client: IJMAPClient; @@ -133,16 +139,42 @@ export async function doEmailGetAttachmentImage( }; } +/** + * Every message of the conversation `emailId` belongs to, oldest first, as + * read views (at most the newest MAX_THREAD_MESSAGES). The message is found + * the way api.email.get finds it, and the conversation is read from the + * same account. + */ +export async function doEmailGetThread(plugin: InstalledPlugin, emailIdArg: unknown, optionsArg?: unknown): Promise { + const method = 'email.getThread'; + const emailId = readId(emailIdArg, method, 'emailId'); + const opts = readObject(optionsArg, method, 'options', ['accountId'], true); + if (!withinRate(method, plugin.id, MAX_THREADS_PER_MINUTE)) throw new Error(`${method}: too many reads, try again in a minute`); + const client = sessionClient(method); + const found = await readNamedEmail(client, emailId, method, opts.accountId); + if (!found) throw new Error(`${method}: no message with id "${emailId}"`); + const accountId = found.accountId ?? client.getAccountId(); + const emails = found.email.threadId ? await client.getThreadEmails(found.email.threadId, found.accountId) : []; + // A server that knows no thread for it: the message on its own. + const list = emails.length ? emails : [found.email]; + return list + .slice() + .sort((a, b) => String(a.receivedAt ?? '').localeCompare(String(b.receivedAt ?? ''))) + .slice(-MAX_THREAD_MESSAGES) + .map((email) => emailToReadView(email, accountId)); +} + /** Runs a method of this area; NOT_MINE for any other. */ export async function dispatch(plugin: InstalledPlugin, method: string, args: unknown[]): Promise { switch (method) { case 'email.getAttachmentText': return doEmailGetAttachmentText(plugin, args[0], args[1], args[2]); case 'email.getAttachmentImage': return doEmailGetAttachmentImage(plugin, args[0], args[1], args[2]); + case 'email.getThread': return doEmailGetThread(plugin, args[0], args[1]); default: return NOT_MINE; } } /** This area's flags in api.host.features, right now. */ export function features(): AreaHostFeaturesB { - return { attachmentText: true, attachmentImages: true }; + return { attachmentText: true, attachmentImages: true, threads: true }; } diff --git a/lib/plugin-sandbox/assistant/b.types.ts b/lib/plugin-sandbox/assistant/b.types.ts index 72c3f5516..4e60c2923 100644 --- a/lib/plugin-sandbox/assistant/b.types.ts +++ b/lib/plugin-sandbox/assistant/b.types.ts @@ -10,6 +10,8 @@ export interface AreaHostFeaturesB { attachmentText?: boolean; /** api.email.getAttachmentImage: an image attachment, shrunk for a model. */ attachmentImages?: boolean; + /** api.email.getThread: every message of a conversation. */ + threads?: boolean; } /** What EmailReadView.attachments adds for an image the message shows inline. */