@dxos/pipeline-email 0.0.0

package/src/pipeline.test.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { EffectEx } from '@dxos/effect';
+import { type RDF } from '@dxos/pipeline-rdf';
+import { mockAiService } from '@dxos/pipeline-rdf/testing';
+import { Message, Organization, Person } from '@dxos/types';
+
+import { EmailPipeline } from './pipeline';
+import { type FactIndexer } from './stages';
+import { Thread } from './types';
+
+// `mockAiService`'s `generateText` always answers `''` (only `generateObject` echoes the payload), so
+// summarize degrades to its empty-summary default and extract-contacts derives no LLM contacts here;
+// this asserts the assembly WIRING (messages flow, stats tally, threads group) over a real ECHO db.
+// Summary/contact/fact CONTENT is covered by the stage-specific suites.
+
+describe('email pipeline (canonical assembly)', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('EmailPipeline.run: summarize → extract-contacts → stats → extract-facts → threads', async ({ expect }) => {
+    const { db } = await builder.createDatabase({
+      types: [Person.Person, Organization.Organization, Thread],
+    });
+
+    const messages = [
+      makeMessage('<m-1@enron.com>', 'alice@enron.com', 'Q2 report', 'I will send the Q2 report by Friday.'),
+      makeMessage('<m-2@enron.com>', 'bob@enron.com', 'Q2 report', 'Thanks, looking forward to it.'),
+    ];
+
+    // Fact persistence is proven by stages/extract-facts.test.ts; here the indexer is a no-op.
+    const indexFacts: FactIndexer = async () => [] as RDF.Fact[];
+
+    const result = await EffectEx.runPromise(
+      EmailPipeline.run(messages, {
+        db,
+        indexFacts,
+        ownerEmail: 'alice@enron.com',
+        now: '2001-05-20T10:00:00.000Z',
+      }).pipe(Effect.provide(mockAiService({}))),
+    );
+
+    // All messages flowed through the stream and were collected in order.
+    expect(result.messages).toHaveLength(2);
+    // stats tallied each message that flowed through.
+    expect(result.stats.total).toBe(2);
+    expect(result.stats.from.get('alice@enron.com')).toBe(1);
+    expect(result.stats.from.get('bob@enron.com')).toBe(1);
+    // summarize recorded a result per message (content empty: see note above).
+    expect(result.summaries).toHaveLength(2);
+    // Both messages share a subject/thread, so they group into a single thread persisted to the db.
+    expect(result.threads).toHaveLength(1);
+    expect(result.threads[0].messageIds).toHaveLength(2);
+  });
+});
+
+const makeMessage = (messageId: string, email: string, subject: string, text: string): Message.Message =>
+  Message.make({
+    created: '2001-05-14T10:00:00.000Z',
+    sender: { email },
+    blocks: [{ _tag: 'text', text }],
+    properties: { messageId, subject },
+  });

package/src/pipeline.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { type AiService } from '@dxos/ai';
+import { type Database } from '@dxos/echo';
+import { Pipeline } from '@dxos/pipeline';
+import { Message } from '@dxos/types';
+
+import { buildThreads } from './internal/threads';
+import {
+  EmailPipelineCtx,
+  type FactIndexer,
+  type Stats,
+  type Summary,
+  emptyStats,
+  extractContactsStage,
+  extractFactsStage,
+  statsStage,
+  summarizeStage,
+} from './stages';
+import { type Thread } from './types';
+
+export type EmailPipelineOptions = {
+  /** ECHO space database: extract-contacts persists Person/Organization, threads are added here. */
+  readonly db: Database.Database;
+  /** Persists one message's facts to the fact substrate (a closure over a `FactStore`). */
+  readonly indexFacts: FactIndexer;
+  /** The space owner's email, used to orient thread state (awaiting-mine / awaiting-theirs). */
+  readonly ownerEmail: string;
+  /** Wall clock used to derive thread staleness; injected so the assembly stays deterministic. */
+  readonly now: string;
+};
+
+export type EmailPipelineResult = {
+  readonly messages: Message.Message[];
+  readonly stats: Stats;
+  readonly summaries: ReadonlyArray<{ messageId: string; summary: Summary }>;
+  readonly threads: Thread[];
+};
+
+export const EmailPipeline = {
+  /**
+   * Default assembly of the email stages over a batch of messages: summarize → extract-contacts →
+   * stats → extract-facts stream through with back pressure, then {@link buildThreads} groups the
+   * collected messages into canonical threads. Contacts and threads are persisted to `db`; the fact
+   * substrate is populated via `indexFacts`. Requires an `AiService` (summarize); the shared
+   * {@link EmailPipelineCtx} is constructed and provided internally.
+   */
+  run: (
+    messages: readonly Message.Message[],
+    options: EmailPipelineOptions,
+  ): Effect.Effect<EmailPipelineResult, never, AiService.AiService> =>
+    Effect.gen(function* () {
+      const stats = emptyStats();
+      const summaries: Array<{ messageId: string; summary: Summary }> = [];
+      const collected: Message.Message[] = [];
+      yield* Stream.fromIterable(messages).pipe(
+        summarizeStage,
+        extractContactsStage,
+        statsStage,
+        extractFactsStage(options.indexFacts),
+        Pipeline.run({ sink: (message) => Effect.sync(() => collected.push(message)) }),
+        Effect.provideService(EmailPipelineCtx, { db: options.db, stats, summaries }),
+      );
+
+      const threads = buildThreads(collected, { ownerEmail: options.ownerEmail, now: options.now });
+      for (const thread of threads) {
+        options.db.add(thread);
+      }
+      return { messages: collected, stats, summaries, threads };
+    }),
+};

package/src/stages/context.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+
+import { type Database } from '@dxos/echo';
+
+/** Summary produced by the summarize stage. */
+export type Summary = { readonly summary: string; readonly isSpam: boolean; readonly keywords: readonly string[] };
+
+/** Running tallies produced by the stats stage (mutable accumulator). */
+export type Stats = { from: Map<string, number>; to: Map<string, number>; total: number; spam: number };
+
+/** Per-message summary result keyed by messageId (for a summary view). */
+export type SummaryResult = { readonly summaries: ReadonlyArray<{ messageId: string; summary: Summary }> };
+
+export const emptyStats = (): Stats => ({ from: new Map(), to: new Map(), total: 0, spam: 0 });
+
+/**
+ * Shared context threaded through the email stages via Effect's Requirements channel. `db` is the
+ * ECHO space database (browser-safe); `stats` and `summaries` are mutable accumulators read after
+ * the run. Callers provide it once at the pipeline edge (`Effect.provide`).
+ */
+export class EmailPipelineCtx extends Context.Tag('@dxos/pipeline-email/EmailPipelineCtx')<
+  EmailPipelineCtx,
+  {
+    readonly db: Database.Database;
+    readonly stats: Stats;
+    readonly summaries: Array<{ messageId: string; summary: Summary }>;
+  }
+>() {}

package/src/stages/extract-contacts.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { extractContact } from '@dxos/extractor-lib';
+import { Stage } from '@dxos/pipeline';
+import { Message } from '@dxos/types';
+
+import { EmailPipelineCtx } from './context';
+
+/** Extract a Person (+ Organization) from the sender and persist to the ECHO space; pass message through. */
+export const extractContactsStage: Stage.Stage<Message.Message, Message.Message, never, EmailPipelineCtx> = Stage.map(
+  'extract-contacts',
+  (message) =>
+    Effect.gen(function* () {
+      const { db } = yield* EmailPipelineCtx;
+      const result = yield* extractContact({ db, source: message });
+      for (const object of result.created) {
+        db.add(object);
+      }
+      return message;
+    }),
+);

package/src/stages/extract-facts-commit.test.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Stream from 'effect/Stream';
+import { describe, test } from 'vitest';
+
+import { EffectEx } from '@dxos/effect';
+import { Pipeline } from '@dxos/pipeline';
+import { type RDF } from '@dxos/pipeline-rdf';
+import { captureSink } from '@dxos/pipeline/testing';
+import { Message } from '@dxos/types';
+
+import { type FactExtractor, type FactUnit, extractFactsUnitStage } from './extract-facts-commit';
+
+const ALICE_FACT: RDF.Fact = {
+  id: 'fact-1',
+  assertion: {
+    subject: { entity: 'alice' },
+    predicate: 'travelsTo',
+    object: { entity: 'paris' },
+    validFrom: '2026-06-12',
+    quote: "I think I'm probably going to Paris next week",
+  },
+  factuality: { value: 'PR+', polarity: '+', confidence: 0.6, nature: 'epistemic' },
+  attribution: {
+    agent: 'alice',
+    source: 'dxn:queue:...:msg-1',
+    generatedAtTime: '2026-06-06T00:00:00.000Z',
+  },
+  recordedAt: '2026-06-06T12:00:00.000Z',
+  extractor: { id: 'default', model: 'ai.claude.model.claude-haiku-4-5', version: '1' },
+  sourceHash: 'abc123',
+};
+
+const makeMessage = () =>
+  Message.make({
+    created: '2001-05-14T10:00:00.000Z',
+    sender: { email: 'alice@enron.com' },
+    blocks: [{ _tag: 'text', text: 'I will send the Q2 report by Friday.' }],
+    properties: { messageId: '<m-1@enron.com>', subject: 'Q2 report' },
+  });
+
+describe('extractFactsUnitStage', () => {
+  test('emits one FactUnit with the extracted facts and no persistence side effect', async ({ expect }) => {
+    const message = makeMessage();
+    const extract: FactExtractor = () => Promise.resolve([ALICE_FACT]);
+
+    const { sink, items } = captureSink<FactUnit>();
+    await EffectEx.runPromise(
+      Stream.fromIterable([message]).pipe(extractFactsUnitStage(extract), Pipeline.run({ sink })),
+    );
+
+    expect(items).toHaveLength(1);
+    expect(items[0].facts).toEqual([ALICE_FACT]);
+    expect(typeof items[0].key).toBe('number');
+    expect(typeof items[0].foreignId).toBe('string');
+    expect(items[0].foreignId).toBe('<m-1@enron.com>');
+  });
+
+  test('degrades to an empty fact list when extraction rejects', async ({ expect }) => {
+    const message = makeMessage();
+    const extract: FactExtractor = () => Promise.reject(new Error('extraction failed'));
+
+    const { sink, items } = captureSink<FactUnit>();
+    await EffectEx.runPromise(
+      Stream.fromIterable([message]).pipe(extractFactsUnitStage(extract), Pipeline.run({ sink })),
+    );
+
+    expect(items).toHaveLength(1);
+    expect(items[0].facts).toEqual([]);
+    expect(typeof items[0].key).toBe('number');
+    expect(typeof items[0].foreignId).toBe('string');
+  });
+});

package/src/stages/extract-facts-commit.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Stage } from '@dxos/pipeline';
+import { type RDF } from '@dxos/pipeline-rdf';
+import { Message } from '@dxos/types';
+
+import { messageSource } from './facts';
+
+// Extract one message's facts WITHOUT persisting them. Distinct from `FactIndexer`, whose closure
+// also writes to the store: here persistence is the sink's responsibility, so a page of facts can
+// commit atomically with the cursor advance. Same signature, different contract.
+export type FactExtractor = (message: Message.Message) => Promise<RDF.Fact[]>;
+
+// Terminal unit for the cursored fact pipeline: extracted facts plus the keys the sink needs to
+// dedup and advance the cursor.
+export type FactUnit = {
+  readonly facts: RDF.Fact[];
+  /** Stable per-message id (`messageSource`); the dedup foreign id. */
+  readonly foreignId: string;
+  /** Monotonic cursor key. */
+  readonly key: number;
+};
+
+// Facts-returning variant of `extractFactsStage`: returns the extracted facts as a `FactUnit`
+// instead of persisting them in-stage, so the sink can write a page atomically with the cursor
+// advance. Extraction degrades to no facts on failure (advisory layer) but logs first, matching
+// `extractFactsStage`'s degradation, so the loss stays observable.
+export const extractFactsUnitStage = (extract: FactExtractor): Stage.Stage<Message.Message, FactUnit> =>
+  Stage.map('extract-facts-unit', (message) =>
+    Effect.tryPromise(() => extract(message)).pipe(
+      Effect.tapError((error) => Effect.logWarning('extract-facts-unit failed; degrading to no facts', error)),
+      Effect.orElse(() => Effect.succeed<RDF.Fact[]>([])),
+      Effect.map((facts): FactUnit => ({ facts, foreignId: messageSource(message), key: keyOf(message) })),
+    ),
+  );
+
+// NOTE(workaround): `message.created` is the incremental cursor key because ECHO's native feed
+// cursor is unimplemented (`Feed.cursor` is stubbed). Replace with the native queue sequence when
+// available.
+const keyOf = (message: Message.Message): number => Date.parse(message.created);

package/src/stages/extract-facts.test.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as Stream from 'effect/Stream';
+import { describe, test } from 'vitest';
+
+import { EffectEx } from '@dxos/effect';
+import { Pipeline } from '@dxos/pipeline';
+import { FactPipeline, FactStore, type RDF } from '@dxos/pipeline-rdf';
+import { mockAiService } from '@dxos/pipeline-rdf/testing';
+import { captureSink } from '@dxos/pipeline/testing';
+import { Message } from '@dxos/types';
+
+import { type FactIndexer, extractFactsStage } from './extract-facts';
+import { EMAIL_EXTRACT_OPTIONS, messageToDocument } from './facts';
+
+// One fact per message from the mock LLM; proves the stage persists into the store.
+const LLM_OUTPUT = {
+  facts: [
+    {
+      subject: 'alice@enron.com',
+      predicate: 'will send',
+      object: 'Q2 report',
+      validTo: '2001-05-18',
+      factuality: 'CT+',
+      polarity: '+',
+      quote: 'I will send the Q2 report by Friday.',
+    },
+  ],
+};
+
+describe('extractFactsStage', () => {
+  test('extracts and persists a fact per message into the store', async ({ expect }) => {
+    const runtime = ManagedRuntime.make(FactStore.layerMemory.pipe(Layer.provideMerge(mockAiService(LLM_OUTPUT))));
+    const indexFacts: FactIndexer = (message) =>
+      runtime.runPromise(FactPipeline.run([messageToDocument(message)], EMAIL_EXTRACT_OPTIONS));
+
+    const message = Message.make({
+      created: '2001-05-14T10:00:00.000Z',
+      sender: { email: 'alice@enron.com' },
+      blocks: [{ _tag: 'text', text: 'I will send the Q2 report by Friday.' }],
+      properties: { messageId: '<m-1@enron.com>', subject: 'Q2 report' },
+    });
+
+    const { sink, items } = captureSink<Message.Message>();
+    await EffectEx.runPromise(
+      Stream.fromIterable([message]).pipe(extractFactsStage(indexFacts), Pipeline.run({ sink })),
+    );
+
+    // The Message passes through unchanged.
+    expect(items).toHaveLength(1);
+
+    // The fact was persisted; read it back from the same store.
+    const facts: RDF.Fact[] = await runtime.runPromise(
+      Effect.gen(function* () {
+        const store = yield* FactStore;
+        return yield* store.query({});
+      }),
+    );
+    await runtime.dispose();
+
+    expect(facts.length).toBeGreaterThan(0);
+    const { object } = facts[0].assertion;
+    // Extraction always produces an entity-ref Term (never a literal), so `label` is present here.
+    expect('entity' in object).toBe(true);
+    expect('entity' in object && object.label).toBe('Q2 report');
+    expect(facts[0].factuality.value).toBe('CT+');
+    expect(facts[0].attribution.source).toBe('<m-1@enron.com>');
+  });
+});

package/src/stages/extract-facts.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Stage } from '@dxos/pipeline';
+import { type RDF } from '@dxos/pipeline-rdf';
+import { Message } from '@dxos/types';
+
+// Extract + persist one message's facts, returning them. The store/AI-bound work is a Promise closure
+// so the stage's Effect stays R = never (a failed extraction must not fail the pipeline run).
+export type FactIndexer = (message: Message.Message) => Promise<RDF.Fact[]>;
+
+// Message-layer stage: index each message into the fact substrate, passing the Message through
+// unchanged. Extraction degrades to no facts on failure (advisory layer) but logs first, so the
+// degradation stays observable. A factory over `indexFacts` (like the pipeline's `logStage(label)`)
+// keeps the module decoupled from any test-level Context.
+export const extractFactsStage = (indexFacts: FactIndexer): Stage.Stage<Message.Message, Message.Message> =>
+  Stage.map('extract-facts', (message) =>
+    Effect.tryPromise(() => indexFacts(message)).pipe(
+      Effect.tapError((error) => Effect.logWarning('extract-facts failed; degrading to no facts', error)),
+      Effect.orElse(() => Effect.succeed<RDF.Fact[]>([])),
+      Effect.as(message),
+    ),
+  );

package/src/stages/facts.test.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Message } from '@dxos/types';
+
+import { EMAIL_EXTRACTION_RULES, messageSource, messageToDocument } from './facts';
+
+describe('messageToDocument', () => {
+  test('maps a Message onto an ExtractDocument', ({ expect }) => {
+    const message = Message.make({
+      created: '2001-05-14T10:00:00.000Z',
+      sender: { email: 'alice@enron.com' },
+      blocks: [{ _tag: 'text', text: 'Please send the Q2 report by Friday.' }],
+      properties: { messageId: '<m-1@enron.com>', subject: 'Q2 report' },
+    });
+
+    const doc = messageToDocument(message);
+    expect(doc.text).toBe('Please send the Q2 report by Friday.');
+    expect(doc.source).toBe('<m-1@enron.com>');
+    expect(doc.author).toBe('alice@enron.com');
+    expect(doc.date).toBe('2001-05-14T10:00:00.000Z');
+  });
+
+  test('messageSource falls back to sender+created when no messageId', ({ expect }) => {
+    const message = Message.make({
+      created: '2001-05-14T10:00:00.000Z',
+      sender: { email: 'bob@enron.com' },
+      blocks: [{ _tag: 'text', text: 'hi' }],
+    });
+    expect(messageSource(message)).toBe('bob@enron.com:2001-05-14T10:00:00.000Z');
+  });
+
+  test('email rules extend the base rules with email-specific guidance', ({ expect }) => {
+    expect(EMAIL_EXTRACTION_RULES.length).toBeGreaterThan(0);
+    expect(EMAIL_EXTRACTION_RULES.some((rule) => /commitment|deadline|action/i.test(rule))).toBe(true);
+  });
+});

package/src/stages/facts.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type RDF } from '@dxos/pipeline-rdf';
+import { Message } from '@dxos/types';
+
+// Email-specific extraction guidance appended after the pipeline-rdf DEFAULT_EXTRACTION_RULES.
+// Kept atomic so the two rule sets compose without forking the base prompt.
+export const EMAIL_EXTRACTION_RULES: readonly string[] = [
+  'Treat a request or promise as a commitment: "please send X by Friday" => subject (the owner), predicate "owes"/"will send", object X, validTo the deadline.',
+  'A deadline or due date becomes validTo on the relevant assertion (ISO date when known).',
+  'Attribute first-person statements ("I will…", "we can…") to the message sender as subject.',
+];
+
+export const EMAIL_EXTRACT_OPTIONS: RDF.ExtractOptions = {
+  rules: EMAIL_EXTRACTION_RULES,
+};
+
+// Stable per-message identifier used as the fact `source` and the incremental cursor key. Prefer the
+// RFC message-id header (present in the Enron dataset); fall back to sender+timestamp so every message
+// has a deterministic source even when the header is absent.
+export const messageSource = (message: Message.Message): string => {
+  const messageId = message.properties?.messageId;
+  if (typeof messageId === 'string' && messageId.length > 0) {
+    return messageId;
+  }
+
+  return `${message.sender.email ?? 'unknown'}:${message.created}`;
+};
+
+export const messageToDocument = (message: Message.Message): RDF.ExtractDocument => ({
+  text: Message.extractText(message),
+  source: messageSource(message),
+  ...(message.sender.email ? { author: message.sender.email } : {}),
+  date: message.created,
+});

package/src/stages/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './context';
+export * from './extract-contacts';
+export * from './extract-facts';
+export * from './extract-facts-commit';
+export * from './facts';
+export * from './stats';
+export * from './summarize';

package/src/stages/stats.test.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Stream from 'effect/Stream';
+import { describe, test } from 'vitest';
+
+import { EffectEx } from '@dxos/effect';
+import { Pipeline } from '@dxos/pipeline';
+import { Message } from '@dxos/types';
+
+import { EmailPipelineCtx, emptyStats } from './context';
+import { statsStage } from './stats';
+
+describe('statsStage', () => {
+  test('tallies senders and spam across the stream', async ({ expect }) => {
+    const stats = emptyStats();
+    // Test-only stub: statsStage never touches `db`.
+    const ctx = Layer.succeed(EmailPipelineCtx, { db: {} as any, stats, summaries: [] });
+    const messages = [
+      Message.make({
+        created: '2001-05-14T10:00:00.000Z',
+        sender: { email: 'a@x.com' },
+        blocks: [],
+        properties: { spam: true },
+      }),
+      Message.make({ created: '2001-05-14T11:00:00.000Z', sender: { email: 'a@x.com' }, blocks: [] }),
+    ];
+    await EffectEx.runPromise(
+      Stream.fromIterable(messages).pipe(statsStage, Pipeline.run({ sink: () => Effect.void }), Effect.provide(ctx)),
+    );
+    expect(stats.total).toBe(2);
+    expect(stats.spam).toBe(1);
+    expect(stats.from.get('a@x.com')).toBe(2);
+  });
+});

package/src/stages/stats.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Stage } from '@dxos/pipeline';
+import { Message } from '@dxos/types';
+
+import { EmailPipelineCtx } from './context';
+
+/** Pure-JS running tallies (senders, recipients, spam); pass message through. */
+export const statsStage: Stage.Stage<Message.Message, Message.Message, never, EmailPipelineCtx> = Stage.map(
+  'stats',
+  (message) =>
+    Effect.gen(function* () {
+      const { stats } = yield* EmailPipelineCtx;
+      stats.total += 1;
+      const sender = message.sender.email;
+      if (sender) {
+        stats.from.set(sender, (stats.from.get(sender) ?? 0) + 1);
+      }
+      const recipients = message.properties?.to;
+      if (Array.isArray(recipients)) {
+        for (const recipient of recipients) {
+          const address = String(recipient);
+          stats.to.set(address, (stats.to.get(address) ?? 0) + 1);
+        }
+      }
+      if (message.properties?.spam) {
+        stats.spam += 1;
+      }
+      return message;
+    }),
+);

package/src/stages/summarize.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AiService } from '@dxos/ai';
+import { Stage } from '@dxos/pipeline';
+import { ContentBlock, Message } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+import { EmailPipelineCtx, type Summary } from './context';
+
+const SUMMARIZE_MODEL = 'com.anthropic.model.claude-haiku-4-5.default';
+
+const SUMMARIZE_PROMPT = trim`
+  Summarize the following email in one sentence, decide whether it is spam, and list up to five keywords.
+  Respond with ONLY a JSON object of the form {"summary": string, "isSpam": boolean, "keywords": string[]}.
+`;
+
+// Local models often wrap JSON in prose; extract the first object and coerce leniently.
+const parseSummary = (raw: string): Summary => {
+  const match = raw.match(/\{[\s\S]*\}/);
+  if (!match) {
+    return { summary: '', isSpam: false, keywords: [] };
+  }
+  try {
+    const parsed = JSON.parse(match[0]);
+    const keywords = parsed.keywords;
+    return {
+      summary: typeof parsed.summary === 'string' ? parsed.summary : '',
+      isSpam: parsed.isSpam === true || parsed.spam === true || parsed.is_spam === true,
+      keywords: Array.isArray(keywords) ? keywords.map((keyword: unknown) => String(keyword)) : [],
+    };
+  } catch {
+    return { summary: '', isSpam: false, keywords: [] };
+  }
+};
+
+/** Summarize via AiService/LanguageModel; append a summary block and record spam/keywords + result. */
+export const summarizeStage: Stage.Stage<
+  Message.Message,
+  Message.Message,
+  never,
+  EmailPipelineCtx | AiService.AiService
+> = Stage.map('summarize', (message) =>
+  Effect.gen(function* () {
+    const ctx = yield* EmailPipelineCtx;
+    const text = Message.extractText(message);
+    // Resolve the LanguageModel layer locally from AiService so `LanguageModel` is discharged and the
+    // stage's requirement correctly reduces to `EmailPipelineCtx | AiService.AiService`.
+    // Bound the LLM call: `orElse` only recovers failures, so without a timeout a hung/slow provider
+    // would block the stage indefinitely. On timeout the effect fails, then `orElse` degrades to ''.
+    const raw = yield* LanguageModel.generateText({ prompt: `${SUMMARIZE_PROMPT}\n\n${text}` }).pipe(
+      Effect.provide(AiService.model(SUMMARIZE_MODEL).pipe(Layer.orDie)),
+      Effect.timeout('30 seconds'),
+      Effect.map((response) => response.text),
+      Effect.orElse(() => Effect.succeed('')),
+    );
+    const summary = parseSummary(raw);
+    const messageId = String(message.properties?.messageId ?? message.id);
+    ctx.summaries.push({ messageId, summary });
+    const summaryBlock: ContentBlock.Text = { _tag: 'text', text: summary.summary };
+    // Preserve the original id: `Message.make` mints a fresh one when omitted, which would break the
+    // `message.id` fallback used for `messageId` downstream.
+    return Message.make({
+      id: message.id,
+      created: message.created,
+      sender: message.sender,
+      blocks: [...message.blocks, summaryBlock],
+      properties: { ...message.properties, spam: summary.isSpam, keywords: summary.keywords },
+    });
+  }),
+);