@dxos/assistant 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-main.bc674ce",
+  "version": "0.8.4-main.bcb3aa67d6",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,20 +16,17 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "default": "./dist/lib/neutral/index.mjs"
     },
     "./extraction": {
       "source": "./src/extraction/index.ts",
       "types": "./dist/types/src/extraction/index.d.ts",
-      "browser": "./dist/lib/browser/extraction/index.mjs",
-      "node": "./dist/lib/node-esm/extraction/index.mjs"
+      "default": "./dist/lib/neutral/extraction/index.mjs"
     },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
-      "browser": "./dist/lib/browser/testing/index.mjs",
-      "node": "./dist/lib/node-esm/testing/index.mjs"
+      "default": "./dist/lib/neutral/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -49,39 +46,42 @@
   ],
   "dependencies": {
     "@automerge/automerge": "3.2.3",
-    "@effect-atom/atom-react": "^0.4.6",
-    "@effect/ai": "0.32.1",
-    "@effect/experimental": "0.57.11",
-    "@effect/platform": "0.93.6",
+    "@effect-atom/atom": "^0.5.1",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/ai": "0.33.2",
+    "@effect/experimental": "0.58.0",
+    "@effect/platform": "0.94.4",
     "@xenova/transformers": "^2.17.2",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/ai": "0.8.4-main.bc674ce",
-    "@dxos/blueprints": "0.8.4-main.bc674ce",
-    "@dxos/context": "0.8.4-main.bc674ce",
-    "@dxos/async": "0.8.4-main.bc674ce",
-    "@dxos/echo": "0.8.4-main.bc674ce",
-    "@dxos/debug": "0.8.4-main.bc674ce",
-    "@dxos/echo-db": "0.8.4-main.bc674ce",
-    "@dxos/echo-protocol": "0.8.4-main.bc674ce",
-    "@dxos/effect": "0.8.4-main.bc674ce",
-    "@dxos/functions": "0.8.4-main.bc674ce",
-    "@dxos/errors": "0.8.4-main.bc674ce",
-    "@dxos/functions-runtime": "0.8.4-main.bc674ce",
-    "@dxos/graph": "0.8.4-main.bc674ce",
-    "@dxos/invariant": "0.8.4-main.bc674ce",
-    "@dxos/keys": "0.8.4-main.bc674ce",
-    "@dxos/log": "0.8.4-main.bc674ce",
-    "@dxos/schema": "0.8.4-main.bc674ce",
-    "@dxos/node-std": "0.8.4-main.bc674ce",
-    "@dxos/types": "0.8.4-main.bc674ce",
-    "@dxos/util": "0.8.4-main.bc674ce"
+    "@dxos/ai": "0.8.4-main.bcb3aa67d6",
+    "@dxos/async": "0.8.4-main.bcb3aa67d6",
+    "@dxos/blueprints": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo-db": "0.8.4-main.bcb3aa67d6",
+    "@dxos/debug": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo-protocol": "0.8.4-main.bcb3aa67d6",
+    "@dxos/errors": "0.8.4-main.bcb3aa67d6",
+    "@dxos/effect": "0.8.4-main.bcb3aa67d6",
+    "@dxos/functions-runtime": "0.8.4-main.bcb3aa67d6",
+    "@dxos/graph": "0.8.4-main.bcb3aa67d6",
+    "@dxos/functions": "0.8.4-main.bcb3aa67d6",
+    "@dxos/invariant": "0.8.4-main.bcb3aa67d6",
+    "@dxos/keys": "0.8.4-main.bcb3aa67d6",
+    "@dxos/node-std": "0.8.4-main.bcb3aa67d6",
+    "@dxos/mcp-client": "0.8.4-main.bcb3aa67d6",
+    "@dxos/log": "0.8.4-main.bcb3aa67d6",
+    "@dxos/operation": "0.8.4-main.bcb3aa67d6",
+    "@dxos/schema": "0.8.4-main.bcb3aa67d6",
+    "@dxos/context": "0.8.4-main.bcb3aa67d6",
+    "@dxos/types": "0.8.4-main.bcb3aa67d6",
+    "@dxos/util": "0.8.4-main.bcb3aa67d6"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "effect": "3.19.11"
+    "effect": "3.20.0"
   },
   "peerDependencies": {
-    "effect": "3.19.11"
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/conversation/context.test.ts

@@ -30,7 +30,7 @@ describe('AiContextBinder', () => {
 
     const TestSchema = Schema.Struct({}).pipe(
       Type.object({
-        typename: 'dxos.org/type/Example',
+        typename: 'org.dxos.type.example',
         version: '0.1.0',
       }),
     );

package/src/conversation/context.ts

@@ -5,15 +5,17 @@
 import { Atom, Registry } from '@effect-atom/atom-react';
 import * as EArray from 'effect/Array';
 import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 import * as Schema from 'effect/Schema';
 
 import { Blueprint } from '@dxos/blueprints';
 import { Resource } from '@dxos/context';
-import { DXN, Obj, Query, type Ref, Type } from '@dxos/echo';
+import { DXN, Obj, Query, Ref, Type } from '@dxos/echo';
 import { type Queue } from '@dxos/echo-db';
+import { assertArgument } from '@dxos/invariant';
 import { log } from '@dxos/log';
-import { ComplexSet, isTruthy } from '@dxos/util';
+import { ComplexSet, isNonNullable } from '@dxos/util';
 
 /**
  * Thread message that binds or unbinds contextual objects to a conversation.
@@ -21,17 +23,17 @@ import { ComplexSet, isTruthy } from '@dxos/util';
 // TODO(burdon): Move to @dxos/schema ContentBlock?
 export const ContextBinding = Schema.Struct({
   blueprints: Schema.Struct({
-    added: Schema.Array(Type.Ref(Blueprint.Blueprint)),
-    removed: Schema.Array(Type.Ref(Blueprint.Blueprint)),
+    added: Schema.Array(Ref.Ref(Blueprint.Blueprint)),
+    removed: Schema.Array(Ref.Ref(Blueprint.Blueprint)),
   }),
 
   objects: Schema.Struct({
-    added: Schema.Array(Type.Ref(Type.Obj)),
-    removed: Schema.Array(Type.Ref(Type.Obj)),
+    added: Schema.Array(Ref.Ref(Obj.Unknown)),
+    removed: Schema.Array(Ref.Ref(Obj.Unknown)),
   }),
 }).pipe(
   Type.object({
-    typename: 'dxos.org/type/ContextBinding',
+    typename: 'org.dxos.type.contextBinding',
     version: '0.1.0',
   }),
 );
@@ -74,6 +76,7 @@ export class AiContextBinder extends Resource {
 
   constructor(options: AiContextBinderOptions) {
     super();
+    assertArgument(options.queue, 'options.queue', 'Queue is required');
     this._queue = options.queue;
     this._registry = options.registry ?? Registry.make();
   }
@@ -146,16 +149,30 @@ export class AiContextBinder extends Resource {
     // Resolve references (loading them first if needed).
     const currentBlueprints = this._registry.get(this._blueprints);
     const currentObjects = this._registry.get(this._objects);
-    const newBlueprints = await this._resolve(bindings.blueprints, currentBlueprints);
-    const newObjects = await this._resolve(bindings.objects, currentObjects);
+    const resolvedBlueprints = await this._resolve(bindings.blueprints, currentBlueprints);
+    const resolvedObjects = await this._resolve(bindings.objects, currentObjects);
+
+    // Filter current state to only items still in the reduced binding set,
+    // then merge in newly resolved items. This ensures unbind events are respected.
+    const reducedBlueprintDxns = new ComplexSet<DXN>(
+      DXN.hash,
+      [...bindings.blueprints].map((ref) => ref.dxn),
+    );
+    const reducedObjectDxns = new ComplexSet<DXN>(
+      DXN.hash,
+      [...bindings.objects].map((ref) => ref.dxn),
+    );
+    const filteredBlueprints = currentBlueprints.filter((obj) => reducedBlueprintDxns.has(Obj.getDXN(obj)));
+    const filteredObjects = currentObjects.filter((obj) => reducedObjectDxns.has(Obj.getDXN(obj)));
+    const mergedBlueprints = this._mergeInto(filteredBlueprints, resolvedBlueprints);
+    const mergedObjects = this._mergeInto(filteredObjects, resolvedObjects);
 
-    // Atomic updates - subscribers notified automatically.
-    this._registry.set(this._blueprints, newBlueprints);
-    this._registry.set(this._objects, newObjects);
+    this._registry.set(this._blueprints, mergedBlueprints);
+    this._registry.set(this._objects, mergedObjects);
 
     log('updated bindings', {
-      blueprints: newBlueprints.length,
-      objects: newObjects.length,
+      blueprints: mergedBlueprints.length,
+      objects: mergedObjects.length,
     });
   }
 
@@ -199,6 +216,24 @@ export class AiContextBinder extends Resource {
       return;
     }
 
+    // Immediately update atom state so removals are reflected before the queue round-trips.
+    const removedBlueprintDxns = (blueprints ?? []).map((ref) => ref.dxn);
+    const removedObjectDxns = (objects ?? []).map((ref) => ref.dxn);
+    if (removedBlueprintDxns.length > 0) {
+      const current = this._registry.get(this._blueprints);
+      this._registry.set(
+        this._blueprints,
+        current.filter((obj) => !removedBlueprintDxns.some((dxn) => DXN.equalsEchoId(Obj.getDXN(obj), dxn))),
+      );
+    }
+    if (removedObjectDxns.length > 0) {
+      const current = this._registry.get(this._objects);
+      this._registry.set(
+        this._objects,
+        current.filter((obj) => !removedObjectDxns.some((dxn) => DXN.equalsEchoId(Obj.getDXN(obj), dxn))),
+      );
+    }
+
     log('unbind', { blueprints: blueprints?.length, objects: objects?.length });
     await this._queue.append([
       Obj.make(ContextBinding, {
@@ -271,14 +306,30 @@ export class AiContextBinder extends Resource {
     );
   }
 
+  /**
+   * Merge resolved items into the current set, adding only items not already present (by DXN).
+   */
+  private _mergeInto<T extends Obj.Unknown>(current: T[], resolved: T[]): T[] {
+    const seen = new Set(current.map((obj) => Obj.getDXN(obj).toString()));
+    const merged = [...current];
+    for (const obj of resolved) {
+      const dxn = Obj.getDXN(obj).toString();
+      if (!seen.has(dxn)) {
+        seen.add(dxn);
+        merged.push(obj);
+      }
+    }
+    return merged;
+  }
+
   /**
    * Resolve references to objects, loading them first if needed and falling back to existing objects.
    */
-  private async _resolve<T>(refs: Iterable<Ref.Ref<T>>, current: T[]): Promise<T[]> {
+  private async _resolve<T extends Obj.Unknown>(refs: Iterable<Ref.Ref<T>>, current: T[]): Promise<T[]> {
     const refArray = [...refs];
 
     // Load all refs that need loading.
-    await Promise.all(refArray.map((ref) => ref.load()));
+    await Promise.all(refArray.map((ref) => ref.tryLoad()));
 
     return refArray
       .map((ref) => {
@@ -291,7 +342,7 @@ export class AiContextBinder extends Resource {
         // Fallback to existing object.
         return target ?? current.find((obj) => Obj.getDXN(obj as any).toString() === ref.dxn.toString());
       })
-      .filter(isTruthy);
+      .filter(isNonNullable);
   }
 }
 
@@ -300,4 +351,19 @@ export class AiContextService extends Context.Tag('@dxos/assistant/AiContextServ
   {
     binder: AiContextBinder;
   }
->() {}
+>() {
+  static bindContext = ({ blueprints, objects }: BindingProps): Effect.Effect<void, never, AiContextService> =>
+    Effect.gen(function* () {
+      const { binder } = yield* AiContextService;
+      yield* Effect.promise(() => binder.bind({ blueprints, objects }));
+    });
+
+  static findObjects = <T extends Type.AnyEntity>(
+    type: T,
+  ): Effect.Effect<Schema.Schema.Type<T>[], never, AiContextService> => {
+    return Effect.gen(function* () {
+      const { binder } = yield* AiContextService;
+      return binder.getObjects().filter(Obj.instanceOf(type));
+    });
+  };
+}

package/src/conversation/conversation.ts

@@ -2,16 +2,29 @@
 // Copyright 2025 DXOS.org
 //
 
+import type * as Tool from '@effect/ai/Tool';
 import type * as Toolkit from '@effect/ai/Toolkit';
 import type { Registry } from '@effect-atom/atom-react';
+import * as Array from 'effect/Array';
+import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
 
+import { type ToolExecutionService, type ToolResolverService } from '@dxos/ai';
+import { type GenericToolkit } from '@dxos/ai';
+import { type Blueprint } from '@dxos/blueprints';
 import { Resource } from '@dxos/context';
 import { Obj } from '@dxos/echo';
 import { type Queue } from '@dxos/echo-db';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
+import { McpToolkit } from '@dxos/mcp-client';
 import { Message } from '@dxos/types';
+import * as Record from 'effect/Record';
 
 import {
   AiSession,
@@ -19,22 +32,29 @@ import {
   type AiSessionRunRequirements,
   type GenerationObserver,
   createToolkit,
+  formatSystemPrompt,
 } from '../session';
 
 import { AiContextBinder, AiContextService, type ContextBinding } from './context';
 
-export interface AiConversationRunProps {
+export interface AiConversationRunProps<Tools extends Record<string, Tool.Any>> {
   prompt: string;
   system?: string;
   observer?: GenerationObserver;
+  toolkit?: Toolkit.Toolkit<Tools>;
 }
 
 export type AiConversationOptions = {
   queue: Queue<Message.Message | ContextBinding>;
-  toolkit?: Toolkit.Any;
   registry?: Registry.Registry;
 };
 
+// TODO(dmaretskyi): Take from model characteristics. opus has 200k max tokens.
+/**
+ * Summarization threshold in tokens.
+ */
+const SUMMARY_THRESHOLD = 80_000;
+
 /**
  * Durable conversation state (initiated by users and agents) backed by a Queue.
  * Executes tools based on AI responses and supports cancellation of in-progress requests.
@@ -50,7 +70,6 @@ export class AiConversation extends Resource {
   public constructor(options: AiConversationOptions) {
     super();
     this._queue = options.queue;
-    this._toolkit = options.toolkit;
     invariant(this._queue);
     this._binder = new AiContextBinder({ queue: this._queue, registry: options.registry });
   }
@@ -76,50 +95,172 @@ export class AiConversation extends Resource {
     return queueItems.filter(Obj.instanceOf(Message.Message));
   }
 
+  getTools(): Effect.Effect<Record<string, Tool.Any>, never, ToolExecutionService | ToolResolverService> {
+    return Effect.gen(this, function* () {
+      const blueprints = this.context.getBlueprints();
+      const tookit = yield* createToolkit({ toolkit: this._toolkit, blueprints });
+      return tookit.tools;
+    }).pipe(Effect.orDie);
+  }
+
   /**
    * Creates a new cancelable request effect.
    */
-  public createRequest(
-    params: AiConversationRunProps,
-  ): Effect.Effect<Message.Message[], AiSessionRunError, AiSessionRunRequirements> {
-    const self = this;
-    return Effect.gen(function* () {
-      const history = yield* Effect.promise(() => self.getHistory());
-
-      // Create toolkit.
-      const blueprints = self.context.getBlueprints();
-      const toolkit = yield* createToolkit({
-        toolkit: self._toolkit,
-        blueprints,
-      });
-
-      // Context objects.
-      const objects = self.context.getObjects();
+  public createRequest<Tools extends Record<string, Tool.Any> = {}>(
+    params: AiConversationRunProps<Tools>,
+  ): Effect.Effect<Message.Message[], AiSessionRunError, AiSessionRunRequirements | Tool.HandlersFor<Tools>> {
+    return Effect.gen(this, function* () {
+      const history = yield* Effect.promise(() => this.getHistory());
+      const blueprints = this.context.getBlueprints();
+      const objects = this.context.getObjects();
 
       log('run', {
         history: history.length,
         blueprints: blueprints.length,
-        tools: Object.keys(toolkit.tools).length,
         objects: objects.length,
       });
 
-      // Process request.
-      const session = new AiSession();
-      const messages = yield* session.run({ history, blueprints, toolkit, objects, ...params }).pipe(
-        Effect.provideService(AiContextService, {
-          binder: self.context,
-        }),
-      );
+      const session = new AiSession({
+        summarizationThreshold: SUMMARY_THRESHOLD,
+        observer: params.observer,
+        onOutput: (message) => Effect.promise(() => this._queue.append([message])),
+      });
+
+      yield* session.begin({
+        history,
+        blueprints,
+        objects,
+        prompt: params.prompt,
+        system: params.system,
+      });
+
+      // Turn loop: recompute toolkit and system prompt between turns to pick up dynamically enabled blueprints.
+      do {
+        const currentBlueprints = this.context.getBlueprints();
+        const mcps = yield* connectMcpServers(currentBlueprints);
+        const toolkit = yield* createToolkit({
+          toolkit: params.toolkit,
+          blueprints: currentBlueprints,
+          genericToolkits: mcps,
+        });
+        log('toolkit', { tools: Record.keys(toolkit.tools) });
+        const system = yield* formatSystemPrompt({
+          system: params.system,
+          blueprints: currentBlueprints,
+          objects: this.context.getObjects(),
+        }).pipe(Effect.orDie);
+
+        const { done } = yield* session.runAgentTurn({
+          system,
+          toolkit,
+        });
+
+        if (done) {
+          break;
+        }
+
+        yield* session.runTools({ toolkit });
+      } while (true);
 
       log('result', {
-        messages: messages.length,
+        messages: session.pending.length,
         duration: session.duration,
         toolCalls: session.toolCalls,
       });
 
-      // Append to queue.
-      yield* Effect.promise(() => self._queue.append(messages));
-      return messages;
-    });
+      return [...session.pending];
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          Layer.succeed(AiContextService, {
+            binder: this.context,
+          }),
+          Layer.succeed(AiConversationService, this),
+        ),
+      ),
+    );
   }
 }
+
+/**
+ * Gives access to the ai conversation.
+ */
+export class AiConversationService extends Context.Tag('@dxos/assistant/AiConversationService')<
+  AiConversationService,
+  AiConversation
+>() {
+  /**
+   * Create a new conversation layer from options.
+   */
+  static layer = (options: AiConversationOptions): Layer.Layer<AiConversationService | AiContextService> =>
+    aiContextFromConversation.pipe(
+      Layer.provideMerge(
+        Layer.scoped(
+          AiConversationService,
+          Effect.gen(function* () {
+            const conversation = yield* acquireReleaseResource(() => new AiConversation(options));
+            return conversation;
+          }),
+        ),
+      ),
+    );
+
+  /**
+   * Create a new conversation with a new queue.
+   */
+  static layerNewQueue = (
+    options?: Omit<AiConversationOptions, 'queue'>,
+  ): Layer.Layer<AiConversationService | AiContextService, never, QueueService> =>
+    Layer.unwrapScoped(
+      Effect.gen(function* () {
+        return AiConversationService.layer({
+          ...options,
+          queue: yield* QueueService.createQueue<Message.Message | ContextBinding>(),
+        });
+      }),
+    );
+
+  /**
+   * Run a prompt in the current conversation.
+   */
+  static run = <Tools extends Record<string, Tool.Any> = {}>(
+    params: AiConversationRunProps<Tools>,
+  ): Effect.Effect<
+    Message.Message[],
+    AiSessionRunError,
+    AiSessionRunRequirements | Tool.HandlersFor<Tools> | AiConversationService
+  > =>
+    Effect.gen(function* () {
+      const conversation = yield* AiConversationService;
+      return yield* conversation.createRequest(params);
+    });
+}
+
+const aiContextFromConversation = Layer.effect(
+  AiContextService,
+  Effect.gen(function* () {
+    const conversation = yield* AiConversationService;
+    return {
+      binder: conversation.context,
+    };
+  }),
+);
+
+const connectMcpServers = (
+  blueprints: readonly Blueprint.Blueprint[],
+): Effect.Effect<GenericToolkit.GenericToolkit[]> =>
+  pipe(
+    blueprints,
+    Array.flatMap((_) => _.mcpServers ?? []),
+    Effect.forEach(({ url, protocol }) =>
+      McpToolkit.make({ url, kind: protocol }).pipe(
+        // NOTE: Type-inference fails here without explicit void return.
+        Effect.tap((toolkit): void =>
+          log.info('Connected to MCP server', { url, tools: Object.keys(toolkit.toolkit.tools).length }),
+        ),
+        Effect.tapDefect((error) => Effect.sync(() => log.warn('Failed to connect to MCP server', { error }))),
+        Effect.either,
+      ),
+    ),
+    Effect.map(Array.filterMap((_) => Either.getRight(_))),
+  );

package/src/diff.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { createDocAccessor } from '@dxos/echo-db';
 import { EchoTestBuilder } from '@dxos/echo-db/testing';
@@ -12,10 +12,17 @@ import { trim } from '@dxos/util';
 import { applyDiffs } from './diff';
 
 describe('diff', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
   it('should apply diffs', async () => {
-    const builder = new EchoTestBuilder();
-    const { db, graph } = await builder.createDatabase();
-    await graph.schemaRegistry.register([Text.Text]);
+    const { db } = await builder.createDatabase({ types: [Text.Text] });
 
     const document = trim`
       # Hello World
@@ -24,7 +31,7 @@ describe('diff', () => {
       But not this one.
     `;
 
-    const text = db.add(Text.make(document));
+    const text = db.add(Text.make({ content: document }));
     const accessor = createDocAccessor(text, ['content']);
     const result = applyDiffs(accessor, [
       `- There'z a typo in this sentence.`,
@@ -40,4 +47,28 @@ describe('diff', () => {
       But not this one.
     `);
   });
+
+  it('should apply diffs that append content at the end', async () => {
+    const { db } = await builder.createDatabase({ types: [Text.Text] });
+
+    const document = '# Shopping list';
+
+    const text = db.add(Text.make({ content: document }));
+    const accessor = createDocAccessor(text, ['content']);
+    const result = applyDiffs(accessor, ['- # Shopping list', '+ # Shopping list\n- Milk']);
+
+    expect(result).toBe('# Shopping list\n- Milk');
+  });
+
+  it('should append text to an empty document', async () => {
+    const builder = new EchoTestBuilder();
+    const { db, graph } = await builder.createDatabase();
+    await graph.schemaRegistry.register([Text.Text]);
+
+    const text = db.add(Text.make({ content: '' }));
+    const accessor = createDocAccessor(text, ['content']);
+    const result = applyDiffs(accessor, ['+ # Shopping list']);
+
+    expect(result).toBe('# Shopping list');
+  });
 });

package/src/diff.ts

@@ -47,9 +47,10 @@ export const reduceDiffs = (diffs: readonly string[]): Diff[] => {
         }
         return acc;
       }
+      default: {
+        throw new Error(`Invalid diff format: each line must start with "- " or "+ ", got: ${JSON.stringify(diff)}`);
+      }
     }
-
-    return acc;
   }, []);
 };
 
@@ -65,7 +66,11 @@ export const computeDiffsWithCursors = <T>(accessor: DocAccessor<T>, diffs: read
     .filter(isNonNullable);
 };
 
-export const applyDiffs = <T>(accessor: DocAccessor<T>, diffs: readonly string[]): string => {
+export const applyDiffs = <T>(
+  accessor: DocAccessor<T>,
+  diffs: readonly string[],
+  { errorOnNotFound = false }: { errorOnNotFound?: boolean } = {},
+): string => {
   for (const diff of reduceDiffs(diffs)) {
     accessor.handle.change((doc: Doc<T>) => {
       const text = DocAccessor.getValue<string>(accessor);
@@ -75,7 +80,11 @@ export const applyDiffs = <T>(accessor: DocAccessor<T>, diffs: readonly string[]
         // NOTE: This only replaces the first match.
         A.splice(doc, accessor.path as A.Prop[], idx, diff.match.length, diff.replace);
       } else {
-        log.warn('diff not found', diff);
+        if (errorOnNotFound) {
+          throw new Error(`Diff not found: ${diff.match}`);
+        } else {
+          log.warn('diff not found', diff);
+        }
       }
     });
   }