@dxos/assistant 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,12 +16,12 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "default": "./dist/lib/neutral/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./extraction": {
       "source": "./src/extraction/index.ts",
       "types": "./dist/types/src/extraction/index.d.ts",
-      "default": "./dist/lib/neutral/extraction/index.mjs"
+      "import": "./dist/lib/extraction.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -39,28 +39,28 @@
     "@effect/rpc": "0.75.1",
     "@xenova/transformers": "^2.17.2",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/async": "0.10.0",
-    "@dxos/ai": "0.10.0",
-    "@dxos/compute-runtime": "0.10.0",
-    "@dxos/context": "0.10.0",
-    "@dxos/compute": "0.10.0",
-    "@dxos/debug": "0.10.0",
-    "@dxos/echo": "0.10.0",
-    "@dxos/echo-client": "0.10.0",
-    "@dxos/echo-doc": "0.10.0",
-    "@dxos/echo-protocol": "0.10.0",
-    "@dxos/effect": "0.10.0",
-    "@dxos/errors": "0.10.0",
-    "@dxos/functions": "0.10.0",
-    "@dxos/graph": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/keys": "0.10.0",
-    "@dxos/log": "0.10.0",
-    "@dxos/mcp-client": "0.10.0",
-    "@dxos/schema": "0.10.0",
-    "@dxos/util": "0.10.0",
-    "@dxos/node-std": "0.10.0",
-    "@dxos/types": "0.10.0"
+    "@dxos/compute": "0.11.1",
+    "@dxos/compute-runtime": "0.11.1",
+    "@dxos/context": "0.11.1",
+    "@dxos/ai": "0.11.1",
+    "@dxos/async": "0.11.1",
+    "@dxos/debug": "0.11.1",
+    "@dxos/echo": "0.11.1",
+    "@dxos/echo-client": "0.11.1",
+    "@dxos/echo-doc": "0.11.1",
+    "@dxos/echo-protocol": "0.11.1",
+    "@dxos/graph": "0.11.1",
+    "@dxos/effect": "0.11.1",
+    "@dxos/invariant": "0.11.1",
+    "@dxos/keys": "0.11.1",
+    "@dxos/log": "0.11.1",
+    "@dxos/errors": "0.11.1",
+    "@dxos/mcp-client": "0.11.1",
+    "@dxos/types": "0.11.1",
+    "@dxos/node-std": "0.11.1",
+    "@dxos/schema": "0.11.1",
+    "@dxos/util": "0.11.1",
+    "@dxos/protocols": "0.11.1"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",

package/src/extraction/quotes.test.ts

@@ -17,7 +17,7 @@ describe('insertReferences', () => {
     };
 
     expect(insertReferences('This is a computational irreducibility test.', quotes)).toBe(
-      'This is a [computational irreducibility](echo:/01JTG9JW11XGWJZ32AW8ET93D1) test.',
+      'This is a [computational irreducibility](echo:///01JTG9JW11XGWJZ32AW8ET93D1) test.',
     );
     expect(
       insertReferences(
@@ -25,7 +25,7 @@ describe('insertReferences', () => {
         quotes,
       ),
     ).toBe(
-      "And what I'd like to talk today about is Steven Wolfram's concept of a [computational irreducibility](echo:/01JTG9JW11XGWJZ32AW8ET93D1).",
+      "And what I'd like to talk today about is Steven Wolfram's concept of a [computational irreducibility](echo:///01JTG9JW11XGWJZ32AW8ET93D1).",
     );
   });
 
@@ -40,7 +40,7 @@ describe('insertReferences', () => {
     // "Sarah Johnson" is linked as a whole (processed first); the standalone "Sarah" is linked
     // separately; the "Sarah" inside the first link is left untouched (no nested `[[..](..)](..)`).
     expect(insertReferences('Sarah Johnson spoke. Later Sarah left.', quotes)).toBe(
-      '[Sarah Johnson](echo:/01JTG9JW11XGWJZ32AW8ET93D1) spoke. Later [Sarah](echo:/01JTG9JW11XGWJZ32AW8ET93D1) left.',
+      '[Sarah Johnson](echo:///01JTG9JW11XGWJZ32AW8ET93D1) spoke. Later [Sarah](echo:///01JTG9JW11XGWJZ32AW8ET93D1) left.',
     );
   });
 
@@ -48,7 +48,7 @@ describe('insertReferences', () => {
     const quotes = { references: [{ quote: 'Amco', id: '01JTG9JW11XGWJZ32AW8ET93D1' }] };
 
     expect(insertReferences('Amco and Amco again.', quotes)).toBe(
-      '[Amco](echo:/01JTG9JW11XGWJZ32AW8ET93D1) and [Amco](echo:/01JTG9JW11XGWJZ32AW8ET93D1) again.',
+      '[Amco](echo:///01JTG9JW11XGWJZ32AW8ET93D1) and [Amco](echo:///01JTG9JW11XGWJZ32AW8ET93D1) again.',
     );
   });
 });

package/src/request/AiRequest.test.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { OpaqueToolkit, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { ScriptedLanguageModel } from '@dxos/ai/testing';
+import { Trace } from '@dxos/compute';
+import { operationServiceLayerNoop } from '@dxos/compute/testing';
+import { TestDatabaseLayer } from '@dxos/echo-client/testing';
+import { registryLayerNoop } from '@dxos/echo/testing';
+import { ContentBlock, type Message } from '@dxos/types';
+
+import * as AiRequest from './AiRequest';
+
+const { text, toolCall, scriptedLanguageModelLayer } = ScriptedLanguageModel;
+
+// Real handler, so a scripted tool call drives a genuine tool-call → result → continue cycle.
+const TestToolkit = Toolkit.make(
+  Tool.make('Echo', {
+    description: 'Returns its input value verbatim.',
+    parameters: {
+      value: Schema.String.annotations({ description: 'The value to echo.' }),
+    },
+    success: Schema.Struct({ value: Schema.String }),
+    failure: Schema.Never,
+  }),
+);
+
+const toolkit = OpaqueToolkit.make(
+  TestToolkit,
+  TestToolkit.toLayer({
+    Echo: ({ value }) => Effect.succeed({ value }),
+  }),
+);
+
+// `RunRequirements` types several services `run()` never yields on this path, hence the noops below.
+const testLayer = (turns: readonly ScriptedLanguageModel.ScriptedTurn[]) =>
+  Layer.mergeAll(
+    scriptedLanguageModelLayer(turns),
+    ToolExecutionService.layerEmpty,
+    ToolResolverService.layerEmpty,
+    TestDatabaseLayer(),
+    registryLayerNoop,
+    operationServiceLayerNoop,
+    Trace.testTraceService().pipe(Layer.provide(Trace.layerNoop)),
+  );
+
+// Lower-level counterpart to `scripted-loop.test.ts` (`@dxos/agent-runtime`): same loop shapes, no `AssistantTestLayer`.
+describe('AiRequest.Request.run (scripted model)', () => {
+  it.effect('completes in one turn when the model emits no tool calls', () =>
+    Effect.gen(function* () {
+      const request = new AiRequest.Request();
+      const messages = yield* request.run({ prompt: 'Say hi.', history: [] });
+
+      expect(textOf(messages)).toContain('Hi there.');
+      expect(request.toolCalls).toEqual(0);
+    }).pipe(Effect.provide(testLayer([{ parts: [text('Hi there.')] }]))),
+  );
+
+  it.effect('executes a tool call, feeds the result back, then stops', () =>
+    Effect.gen(function* () {
+      const request = new AiRequest.Request();
+      const messages = yield* request.run({ toolkit, prompt: 'Echo hello.', history: [] });
+
+      expect(toolResultsOf(messages)).toHaveLength(1);
+      expect(textOf(messages)).toContain('Echoed the value.');
+      expect(request.toolCalls).toEqual(1);
+    }).pipe(
+      Effect.provide(
+        testLayer([{ parts: [toolCall('Echo', { value: 'hello' })] }, { parts: [text('Echoed the value.')] }]),
+      ),
+    ),
+  );
+
+  it.effect('iterates until the model stops, feeding each tool result back', () =>
+    Effect.gen(function* () {
+      const request = new AiRequest.Request();
+      const messages = yield* request.run({ toolkit, prompt: 'Echo twice.', history: [] });
+
+      expect(toolResultsOf(messages)).toHaveLength(2);
+      expect(textOf(messages)).toContain('All done.');
+      expect(request.toolCalls).toEqual(2);
+    }).pipe(
+      Effect.provide(
+        testLayer([
+          { parts: [toolCall('Echo', { value: 'first' })] },
+          { parts: [toolCall('Echo', { value: 'second' })] },
+          { parts: [text('All done.')] },
+        ]),
+      ),
+    ),
+  );
+});
+
+const textOf = (messages: readonly Message.Message[]): string =>
+  messages
+    .flatMap((message) => message.blocks)
+    .filter(ContentBlock.is('text'))
+    .map((block) => block.text)
+    .join('');
+
+const toolResultsOf = (messages: readonly Message.Message[]) =>
+  messages.flatMap((message) => message.blocks).filter(ContentBlock.is('toolResult'));

package/src/request/AiRequest.ts

@@ -26,7 +26,7 @@ import {
   callTool,
   withoutToolCallParising,
 } from '@dxos/ai';
-import { Operation, type Skill, Trace } from '@dxos/compute';
+import { type Instructions, Operation, type Skill, Trace } from '@dxos/compute';
 import { Database, Obj, Registry } from '@dxos/echo';
 import { log } from '@dxos/log';
 import { ContentBlock, Message } from '@dxos/types';
@@ -76,6 +76,8 @@ export type RunProps<R = never> = {
   history?: Message.Message[];
   objects?: Obj.Unknown[];
   skills?: readonly Skill.Skill[];
+  /** Rendered inline into the system prompt; passed explicitly rather than inferred from `objects`. */
+  instructions?: readonly Instructions.Instructions[];
   toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
 };
 
@@ -85,6 +87,7 @@ export type BeginProps = {
   history?: Message.Message[];
   objects?: Obj.Unknown[];
   skills?: readonly Skill.Skill[];
+  instructions?: readonly Instructions.Instructions[];
 };
 
 export type TurnProps<R = never> = {
@@ -191,13 +194,14 @@ export class Request {
     history = [],
     skills = [],
     objects = [],
+    instructions = [],
   }: BeginProps): Effect.Effect<void, RunError, RunRequirements> =>
     Effect.gen(this, function* () {
       this._started = Date.now();
       this._history = [...history];
       this._pending = [];
 
-      const systemPrompt = yield* formatSystemPrompt({ system, skills, objects }).pipe(Effect.orDie);
+      const systemPrompt = yield* formatSystemPrompt({ system, skills, objects, instructions }).pipe(Effect.orDie);
 
       if (this._options.summarizationThreshold !== undefined) {
         const tokenCount = yield* AiPreprocessor.estimateTokens(
@@ -345,12 +349,15 @@ export class Request {
     history = [],
     objects = [],
     skills = [],
+    instructions = [],
     toolkit,
   }: RunProps<R>): Effect.Effect<Message.Message[], RunError, RunRequirements | R> =>
     Effect.gen(this, function* () {
-      yield* this.begin({ prompt, system: systemTemplate, history, objects, skills });
+      yield* this.begin({ prompt, system: systemTemplate, history, objects, skills, instructions });
 
-      const system = yield* formatSystemPrompt({ system: systemTemplate, skills, objects }).pipe(Effect.orDie);
+      const system = yield* formatSystemPrompt({ system: systemTemplate, skills, objects, instructions }).pipe(
+        Effect.orDie,
+      );
 
       do {
         const { done, finishReason } = yield* this.runAgentTurn({ system, toolkit });

package/src/request/format.test.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Instructions, Project } from '@dxos/compute';
+import { operationServiceLayerNoop } from '@dxos/compute/testing';
+import { Database, Obj, Ref, URI } from '@dxos/echo';
+import { TestDatabaseLayer } from '@dxos/echo-client/testing';
+import { registryLayerNoop } from '@dxos/echo/testing';
+import { Text } from '@dxos/schema';
+
+import { formatSystemPrompt } from './format';
+
+const testLayer = () =>
+  Layer.mergeAll(
+    TestDatabaseLayer({ types: [Instructions.Instructions, Project.Project, Text.Text] }),
+    registryLayerNoop,
+    operationServiceLayerNoop,
+  );
+
+describe('formatSystemPrompt', () => {
+  it.effect('renders Instructions inline (text + commands), not as object stubs', () =>
+    Effect.gen(function* () {
+      const instructions = yield* Database.add(
+        Instructions.make({
+          name: 'Instructions',
+          text: 'Answer like a pirate.',
+          commands: [
+            { sentinel: '$track', description: 'Track a follow-up', prompt: 'Append the item to the task list.' },
+          ],
+        }),
+      );
+
+      const prompt = yield* formatSystemPrompt({ system: 'Base prompt.', instructions: [instructions] });
+      expect(prompt).toContain('Base prompt.');
+      expect(prompt).toContain('## Instructions');
+      expect(prompt).toContain('Answer like a pirate.');
+      expect(prompt).toContain('`$track` (Track a follow-up): Append the item to the task list.');
+      // The instructions must not degrade to a load-it-yourself context stub.
+      expect(prompt).not.toContain('## Context Objects');
+    }).pipe(Effect.provide(testLayer())),
+  );
+
+  it.effect('degrades to a commands-only block when the text ref is broken', () =>
+    Effect.gen(function* () {
+      const instructions = yield* Database.add(
+        Instructions.make({
+          name: 'Instructions',
+          text: 'unreachable',
+          commands: [{ sentinel: '$go', prompt: 'Go.' }],
+        }),
+      );
+      yield* Database.flush();
+      Obj.update(instructions, (instructions) => {
+        instructions.text = Ref.fromURI(URI.make('dxn:echo:@:missing-text'));
+      });
+
+      const prompt = yield* formatSystemPrompt({ instructions: [instructions] });
+      expect(prompt).toContain('## Instructions');
+      expect(prompt).toContain('`$go`: Go.');
+      expect(prompt).not.toContain('unreachable');
+    }).pipe(Effect.provide(testLayer())),
+  );
+
+  it.effect('treats a bound Instructions object as an ordinary context stub', () =>
+    Effect.gen(function* () {
+      // Steering is declared by the `instructions` parameter, so a bound Instructions object is
+      // subject matter (e.g. "help me edit these") rather than something the session must obey.
+      const instructions = yield* Database.add(Instructions.make({ name: 'Draft', text: 'Answer like a pirate.' }));
+      const prompt = yield* formatSystemPrompt({ objects: [instructions] });
+      expect(prompt).toContain('## Context Objects');
+      expect(prompt).toContain('<label>Draft</label>');
+      expect(prompt).not.toContain('## Instructions');
+      expect(prompt).not.toContain('Answer like a pirate.');
+    }).pipe(Effect.provide(testLayer())),
+  );
+
+  it.effect('keeps non-instructions objects as context stubs, carrying their label', () =>
+    Effect.gen(function* () {
+      const doc = yield* Database.add(Text.make({ content: 'plain object' }));
+      const project = yield* Database.add(Project.make({ name: 'Voyage' }));
+      const prompt = yield* formatSystemPrompt({ objects: [doc, project] });
+      expect(prompt).toContain('## Context Objects');
+      expect(prompt).toContain(Obj.getURI(doc));
+      expect(prompt).toContain('<label>Voyage</label>');
+      expect(prompt).not.toContain('## Instructions');
+    }).pipe(Effect.provide(testLayer())),
+  );
+});

package/src/request/format.ts

@@ -7,7 +7,7 @@ import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
 
 import { type FunctionNotFoundError, type Operation, Template } from '@dxos/compute';
-import { type Database, Obj, type Registry } from '@dxos/echo';
+import { Database, Obj, type Registry } from '@dxos/echo';
 import { ObjectVersion } from '@dxos/echo-client';
 import { type EntityNotFoundError } from '@dxos/echo/Err';
 import { type EntityId } from '@dxos/keys';
@@ -27,7 +27,8 @@ export const formatSystemPrompt = ({
   system,
   skills = [],
   objects = [],
-}: Pick<AiRequest.RunProps, 'system' | 'skills' | 'objects'>): Effect.Effect<
+  instructions = [],
+}: Pick<AiRequest.RunProps, 'system' | 'skills' | 'objects' | 'instructions'>): Effect.Effect<
   string,
   FunctionNotFoundError | EntityNotFoundError,
   Database.Service | Registry.Service | Operation.Service
@@ -50,21 +51,57 @@ export const formatSystemPrompt = ({
       Effect.map((skills) => (skills.length > 0 ? ['## Skills Definitions', ...skills].join('\n\n') : undefined)),
     );
 
+    // Instructions steer the session, so their text (and sentinel commands) belongs in the system
+    // prompt itself — a context-object stub would force the model to tool-load them and follow nothing.
+    const instructionDefs = yield* Function.pipe(
+      instructions,
+      Effect.forEach((instructions) =>
+        Effect.gen(function* () {
+          // A broken text ref degrades to commands-only rather than failing the whole prompt.
+          const text = yield* Database.load(instructions.text).pipe(
+            Effect.map((doc) => doc.content.trim()),
+            Effect.catchTag('EntityNotFoundError', () => Effect.succeed('')),
+          );
+          const commands = (instructions.commands ?? []).map(
+            ({ sentinel, description, prompt }) =>
+              `- \`${sentinel}\`${description ? ` (${description})` : ''}: ${prompt}`,
+          );
+          const parts = [text];
+          if (commands.length > 0) {
+            parts.push(
+              ['When the user message contains one of these sentinel commands, follow its prompt:', ...commands].join(
+                '\n',
+              ),
+            );
+          }
+          return `<instructions>\n${parts.filter(Boolean).join('\n\n')}\n</instructions>`;
+        }),
+      ),
+      Effect.map((defs) => (defs.length > 0 ? ['## Instructions', ...defs].join('\n\n') : undefined)),
+    );
+
     const objectDefs = yield* Function.pipe(
       objects,
-      Effect.forEach((object) =>
-        Effect.succeed(trim`
-          <object>
-            <dxn>${Obj.getURI(object)}</dxn>
-            <typename>${Obj.getTypename(object)}</typename>
-          </object>
-        `),
-      ),
+      Effect.forEach((object) => {
+        // Carry the label so the model only tool-loads an object when it needs the contents,
+        // not just to learn what the reference is.
+        const label = Obj.getLabel(object);
+        return Effect.succeed(
+          trim`
+            <object>
+              <dxn>${Obj.getURI(object)}</dxn>
+              <typename>${Obj.getTypename(object)}</typename>${label ? `\n  <label>${label}</label>` : ''}
+            </object>
+          `,
+        );
+      }),
       Effect.map((objects) => (objects.length > 0 ? ['## Context Objects', ...objects].join('\n\n') : undefined)),
     );
 
     return yield* Function.pipe(
-      Effect.succeed([system, skillDefs, objectDefs].filter((def): def is string => def !== undefined)),
+      Effect.succeed(
+        [system, instructionDefs, skillDefs, objectDefs].filter((def): def is string => def !== undefined),
+      ),
       Effect.map((parts) => parts.join('\n\n')),
     );
   }).pipe(Effect.withSpan('formatSystemPrompt'));

package/src/session/AiContext.ts

@@ -4,7 +4,7 @@
 
 // @import-as-namespace
 
-import { Atom, Registry as AtomRegistry } from '@effect-atom/atom-react';
+import { Atom, Registry as AtomRegistry } from '@effect-atom/atom';
 import * as EArray from 'effect/Array';
 import * as Function from 'effect/Function';
 import * as Runtime from 'effect/Runtime';

package/src/session/AiSession.test.ts

@@ -108,4 +108,128 @@ describe('AiSession.Session.getHistory', () => {
       expect(result.map((msg) => msg.id)).toEqual([forkMsg.id]);
     }).pipe(Effect.provide(TestLayer)),
   );
+
+  // Soft fork: the continuation names an earlier message as its lineage parent, so everything appended
+  // between the two is unreachable and must not reach the model.
+  it.effect('excludes turns a soft fork left unreachable', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const feed = db.add(Feed.make());
+
+      const prompt1 = makeMessage('first question');
+      const answer1 = makeMessage('first answer', 'assistant');
+      const prompt2 = makeMessage('abandoned question');
+      const answer2 = makeMessage('abandoned answer', 'assistant');
+      yield* Feed.append(feed, [prompt1, answer1, prompt2, answer2]);
+
+      // Continue from the first answer rather than the tip.
+      const retry = makeMessage('better question');
+      yield* Feed.append(feed, [retry], { parent: answer1 });
+
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const session = new AiSession.Session({ feed, runtime });
+
+      const result = yield* Effect.promise(() => session.getHistory());
+
+      expect(result.map((msg) => msg.id)).toEqual([prompt1.id, answer1.id, retry.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('returns the whole feed when nothing has been forked', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const feed = db.add(Feed.make());
+
+      const messages = [makeMessage('one'), makeMessage('two', 'assistant'), makeMessage('three')];
+      yield* Feed.append(feed, messages);
+
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const session = new AiSession.Session({ feed, runtime });
+
+      const result = yield* Effect.promise(() => session.getHistory());
+
+      expect(result.map((msg) => msg.id)).toEqual(messages.map((msg) => msg.id));
+    }).pipe(Effect.provide(TestLayer)),
+  );
+});
+
+//
+// Fork point (soft fork write side).
+//
+// The rewind decision is made in the UI but the continuation is appended by the agent's process, which
+// resolves the feed and never sees the chat. The feed carries the pending intent; the session consumes it
+// on the turn's first message, turning the fork into lineage.
+//
+
+describe('AiSession.Session rewind', () => {
+  const TestLayer = TestDatabaseLayer({ types: [Feed.Feed, Message.Message, SessionLink.SessionLink] });
+
+  it.effect("parents the turn's first message to what precedes the rewind", () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const feed = db.add(Feed.make());
+
+      const first = makeMessage('first');
+      const answer = makeMessage('answer', 'assistant');
+      const abandoned = makeMessage('abandoned');
+      yield* Feed.append(feed, [first, answer, abandoned]);
+
+      Obj.update(feed, (feed) => {
+        feed.rewindFrom = abandoned.id;
+      });
+
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const session = new AiSession.Session({ feed, runtime });
+
+      // `rewindFrom` names the earliest discarded message, so the continuation parents to the one
+      // before it. Stands in for the request loop: `onOutput` is the single funnel every persisted
+      // message passes through, and the retry is this turn's first.
+      const retry = makeMessage('retry');
+      yield* Effect.promise(() => session.appendTurnMessage(retry));
+
+      expect(Feed.getParent(retry)).toBe(answer.id);
+      // Consumed: a second message in the same turn chains implicitly, not onto the parent again.
+      expect(feed.rewindFrom).toBeUndefined();
+
+      const followUp = makeMessage('follow up', 'assistant');
+      yield* Effect.promise(() => session.appendTurnMessage(followUp));
+      expect(Feed.getParent(followUp)).toBeUndefined();
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('leaves messages unparented when no rewind is pending', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const feed = db.add(Feed.make());
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const session = new AiSession.Session({ feed, runtime });
+
+      const message = makeMessage('plain');
+      yield* Effect.promise(() => session.appendTurnMessage(message));
+      expect(Feed.getParent(message)).toBeUndefined();
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('the resolved history follows the fork once the continuation lands', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const feed = db.add(Feed.make());
+
+      const first = makeMessage('first');
+      const answer = makeMessage('answer', 'assistant');
+      const abandoned = makeMessage('abandoned');
+      yield* Feed.append(feed, [first, answer, abandoned]);
+      Obj.update(feed, (feed) => {
+        feed.rewindFrom = abandoned.id;
+      });
+
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const session = new AiSession.Session({ feed, runtime });
+      const retry = makeMessage('retry');
+      yield* Effect.promise(() => session.appendTurnMessage(retry));
+
+      const history = yield* Effect.promise(() => session.getHistory());
+      expect(history.map((message) => message.id)).toEqual([first.id, answer.id, retry.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
 });