@dxos/plugin-assistant 0.10.0 → 0.11.0

package/src/processor/processor.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom, Registry as AtomRegistry } from '@effect-atom/atom-react';
+import { Atom, Registry as AtomRegistry } from '@effect-atom/atom';
 import * as AiError from '@effect/ai/AiError';
 import * as Cause from 'effect/Cause';
 import * as Effect from 'effect/Effect';
@@ -25,8 +25,15 @@ import {
   formatSystemPrompt,
 } from '@dxos/assistant';
 import { type Chat } from '@dxos/assistant-toolkit';
-import { AgentService, type Credential, Operation, type ServiceNotAvailableError, Trace } from '@dxos/compute';
-import { type Database, Feed, Obj, Ref, type Registry } from '@dxos/echo';
+import {
+  AgentService,
+  type Credential,
+  type Instructions,
+  Operation,
+  type ServiceNotAvailableError,
+  Trace,
+} from '@dxos/compute';
+import { Database, Feed, Obj, Ref, type Registry } from '@dxos/echo';
 import { UsageQuotaExceededError } from '@dxos/edge-client';
 import { EffectEx } from '@dxos/effect';
 import { DXN } from '@dxos/keys';
@@ -36,6 +43,7 @@ import { Message } from '@dxos/types';
 import { AssistantOperation } from '#types';
 
 import { findInCause } from '../util/error-cause';
+import { type ProcessorRequestContext, createPromptContent } from './prompt';
 
 /**
  * @deprecated Services type for the old direct-conversation processor path.
@@ -83,6 +91,8 @@ export type ProcessorRequestOptions = {};
 
 export type ProcessorRequest = {
   message: string;
+  /** Ephemeral context (e.g. companion-document selection) captured at submit time. */
+  context?: ProcessorRequestContext;
   options?: ProcessorRequestOptions;
 };
 
@@ -246,10 +256,11 @@ export class AiChatProcessor {
       Effect.gen(this, function* () {
         const skills = this.context.getSkills();
         const objects = this.context.getObjects();
+        const instructions = yield* this.#getInstructions();
         // Tier A only: system-prompt formatting runs operations that read the conversation context;
         // the live-host Tier B control surface is not reachable from this fiber.
         const runtime = yield* Effect.runtime<Database.Service>();
-        return yield* formatSystemPrompt({ system: this._options.system, skills, objects }).pipe(
+        return yield* formatSystemPrompt({ system: this._options.system, skills, objects, instructions }).pipe(
           Effect.provideService(
             Harness.HarnessService,
             Harness.fromBinder({ feed: this._feed, runtime, binder: this.context }),
@@ -259,6 +270,22 @@ export class AiChatProcessor {
     );
   }
 
+  /**
+   * Resolves the chat's steering instructions, if any. The session is feed-centric and cannot reach
+   * its chat, so the ref is resolved here and handed down.
+   */
+  #getInstructions(): Effect.Effect<Instructions.Instructions[], never, Database.Service> {
+    return Effect.gen(this, function* () {
+      const instructionsRef = this._options.chat?.target?.instructions;
+      if (!instructionsRef) {
+        return [];
+      }
+
+      const instructions = yield* Database.load(instructionsRef).pipe(Effect.orElseSucceed(() => undefined));
+      return instructions ? [instructions] : [];
+    });
+  }
+
   /**
    * Initiates a new request via AgentService.
    */
@@ -283,6 +310,7 @@ export class AiChatProcessor {
         const session = yield* AgentService.getSession(this._feed, {
           model: this._options.model,
           provider: this._options.provider,
+          instructions: this._options.chat?.target?.instructions,
         });
         const ephemeralStream = session.subscribeEphemeral();
         yield* ephemeralStream.pipe(
@@ -301,7 +329,7 @@ export class AiChatProcessor {
         );
 
         log('chat processor submitting prompt', { length: requestProp.message.length });
-        yield* session.submitPrompt(requestProp.message);
+        yield* session.submitPrompt(createPromptContent(requestProp));
         log('chat processor submitPrompt returned, waiting for agent', {});
 
         // On the first message (no name yet), schedule rename immediately so it

package/src/processor/prompt.test.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { createPromptContent } from './prompt';
+
+describe('createPromptContent', () => {
+  test('returns the bare message when there is no context', ({ expect }) => {
+    expect(createPromptContent({ message: 'hello' })).toBe('hello');
+    expect(createPromptContent({ message: 'hello', context: {} })).toBe('hello');
+  });
+
+  test('prepends a synthetic selection block before the user prompt', ({ expect }) => {
+    const content = createPromptContent({
+      message: 'Summarize this.',
+      context: { selection: { anchors: ['a:b'], text: 'lorem ipsum' } },
+    });
+    if (typeof content === 'string') {
+      throw new Error('expected content blocks');
+    }
+    expect(content).toHaveLength(2);
+    const [selectionBlock, promptBlock] = content;
+    if (selectionBlock._tag !== 'text' || promptBlock._tag !== 'text') {
+      throw new Error('expected text blocks');
+    }
+    expect(selectionBlock.disposition).toBe('synthetic');
+    expect(selectionBlock.text).toContain('lorem ipsum');
+    expect(promptBlock.disposition).toBeUndefined();
+    expect(promptBlock.text).toBe('Summarize this.');
+  });
+
+  test('empty selection text falls back to the bare message', ({ expect }) => {
+    expect(createPromptContent({ message: 'hi', context: { selection: { anchors: [], text: '' } } })).toBe('hi');
+  });
+});

package/src/processor/prompt.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { ContentBlock } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+/** Ephemeral, per-request context captured at submit time (not part of the durable chat state). */
+export type ProcessorRequestContext = {
+  selection?: {
+    /** Anchor strings (`"${from}:${to}"` cursor pairs) the text was resolved from; enables future in-place actions. */
+    anchors: string[];
+    text: string;
+  };
+};
+
+/**
+ * Prompt content for a request: the bare message, or — when the request carries selection context —
+ * a synthetic block (system-generated user-turn content, hidden from the summary view) ahead of it.
+ */
+export const createPromptContent = (request: {
+  message: string;
+  context?: ProcessorRequestContext;
+}): string | ContentBlock.Any[] => {
+  const selection = request.context?.selection;
+  if (!selection?.text.length) {
+    return request.message;
+  }
+
+  return [
+    ContentBlock.Text.make({
+      disposition: 'synthetic',
+      text: trim`
+        The user's current selection in the document they are viewing:
+        <selection>
+        ${selection.text}
+        </selection>
+      `,
+    }),
+    ContentBlock.Text.make({ text: request.message }),
+  ];
+};

package/src/processor/streaming.node.test.ts

@@ -0,0 +1,196 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry as AtomRegistry } from '@effect-atom/atom';
+import { describe, it } from '@effect/vitest';
+import * as Context from 'effect/Context';
+import * as Deferred from 'effect/Deferred';
+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 { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { AiService, OpaqueToolkit } from '@dxos/ai';
+import { Capabilities, Capability, Plugin, PluginManager } from '@dxos/app-framework';
+import { AiSession, PartialBlock } from '@dxos/assistant';
+import { Chat } from '@dxos/assistant-toolkit';
+import { AgentService, Credential, Operation, ServiceResolver, Trace } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Database, Feed, Obj, Registry } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { TestHelpers } from '@dxos/effect/testing';
+import { type ContentBlock } from '@dxos/types';
+
+import { AiChatProcessor } from './processor';
+
+const TestLayer = AssistantTestLayer({ tracing: 'noop', types: [Chat.Chat, Feed.Feed] });
+
+/** Builds a trace event carrying an assistant text block (the payload `#handleEphemeralMessage` consumes). */
+const partialBlockEvent = (messageId: string, text: string, pending: boolean): Trace.Event => ({
+  timestamp: 0,
+  type: PartialBlock.key,
+  data: {
+    messageId,
+    role: 'assistant',
+    block: { _tag: 'text', text, ...(pending ? { pending } : {}) } satisfies ContentBlock.Text,
+  },
+});
+
+/** Wraps events in the trace envelope `subscribeEphemeral` delivers. */
+const traceMessage = (events: Trace.Event[]): Trace.Message =>
+  Obj.make(Trace.Message, { meta: {}, isEphemeral: true, events });
+
+/**
+ * Stub {@link AgentService.Session} whose ephemeral stream replays a scripted batch sequence.
+ * `waitForCompletion` resolves only after the stream has been fully delivered, mirroring the real
+ * session's turn-settles-after-streaming ordering.
+ */
+const makeStubSession = (
+  feed: Feed.Feed,
+  batches: Trace.Message[],
+): Effect.Effect<AgentService.Session, never, never> =>
+  Effect.gen(function* () {
+    const done = yield* Deferred.make<void>();
+    return {
+      feed,
+      getContext: () => Effect.succeed([]),
+      addContext: () => Effect.void,
+      submitPrompt: () => Effect.void,
+      waitForCompletion: () => Deferred.await(done),
+      terminate: () => Effect.void,
+      subscribeEphemeral: () => Stream.fromIterable(batches).pipe(Stream.ensuring(Deferred.succeed(done, undefined))),
+    };
+  });
+
+/**
+ * A sound {@link Capabilities.ProcessManagerRuntime} for tests: a `ManagedRuntime` over the
+ * assistant test layer's process services plus a bare `PluginManager` for the capability/plugin
+ * tags. Scoped so the runtime is disposed with the test.
+ */
+const makeTestRuntime = Effect.gen(function* () {
+  const services = yield* Effect.context<
+    | ProcessManager.Service
+    | Operation.Service
+    | ProcessManager.ProcessOperationInvoker.Service
+    | ServiceResolver.ServiceResolver
+  >();
+  const manager = PluginManager.make({
+    pluginLoader: (id: string) => Effect.dieMessage(`No plugins in test runtime: ${id}`),
+    plugins: [],
+  });
+  const runtime: Capabilities.ProcessManagerRuntime = ManagedRuntime.make(
+    Layer.mergeAll(
+      Layer.succeedContext(services),
+      Layer.succeed(Capability.Service, manager.capabilities),
+      Layer.succeed(Plugin.Service, manager),
+    ),
+  );
+  yield* Effect.addFinalizer(() =>
+    Effect.promise(() => (runtime as ManagedRuntime.ManagedRuntime<never, never>).dispose()),
+  );
+  return runtime;
+});
+
+describe('AiChatProcessor streaming', () => {
+  it.scoped(
+    'upserts partials, finalizes complete blocks, ignores late partials, and flushes on completion',
+    Effect.fn(
+      function* ({ expect }) {
+        const feed = yield* Database.add(Feed.make());
+        const runtime = yield* Effect.runtime<Database.Service>();
+        const session = yield* EffectEx.acquireReleaseResource(() => new AiSession.Session({ feed, runtime }));
+
+        // The scripted stream: a growing partial for m1, its finalization, a late (stale) partial
+        // for m1, and an m2 partial that never finalizes (flushed when the request completes).
+        const m1 = Obj.ID.random();
+        const m2 = Obj.ID.random();
+        const batches = [
+          traceMessage([partialBlockEvent(m1, 'Hel', true)]),
+          traceMessage([partialBlockEvent(m1, 'Hello', true)]),
+          traceMessage([partialBlockEvent(m1, 'Hello world.', false)]),
+          traceMessage([partialBlockEvent(m1, 'Hello world. (stale)', true)]),
+          traceMessage([partialBlockEvent(m2, 'Working…', true)]),
+        ];
+        const stubSession = yield* makeStubSession(feed, batches);
+        const stubAgentService: AgentService.Service = {
+          getSession: () => Effect.succeed(stubSession),
+          hydrate: () => Effect.void,
+        };
+
+        // The processor's space layer: the test layer's real services with the stub agent service
+        // swapped in.
+        const services = yield* Effect.context<
+          | Database.Service
+          | Credential.CredentialsService
+          | AiService.AiService
+          | Registry.Service
+          | OpaqueToolkit.OpaqueToolkitProvider
+        >();
+        const spaceLayer = Layer.mergeAll(
+          Layer.succeedContext(
+            Context.pick(
+              Database.Service,
+              Credential.CredentialsService,
+              AiService.AiService,
+              Registry.Service,
+              OpaqueToolkit.OpaqueToolkitProvider,
+            )(services),
+          ),
+          Layer.succeed(AgentService.AgentService, stubAgentService),
+        );
+
+        const observableRegistry = AtomRegistry.make();
+        const processorRuntime = yield* makeTestRuntime;
+        const processor = new AiChatProcessor(session, processorRuntime, feed, spaceLayer, { observableRegistry });
+
+        // Atoms only hold state while mounted (the UI mounts them via `useAtomValue`); subscribe
+        // with `immediate` before the request — a lazy subscription does not mount the atom graph
+        // until first read, so updates would be dropped — and collect snapshots so the in-flight
+        // progression is observable too.
+        const snapshots: string[][] = [];
+        const unsubscribers = [
+          observableRegistry.subscribe(
+            processor.messages,
+            (messages) =>
+              snapshots.push(
+                messages.map((message) => message.blocks.map((block) => (block as ContentBlock.Text).text).join('')),
+              ),
+            { immediate: true },
+          ),
+          observableRegistry.subscribe(processor.error, () => {}),
+          observableRegistry.subscribe(processor.active, () => {}),
+        ];
+        yield* Effect.addFinalizer(() => Effect.sync(() => unsubscribers.forEach((unsubscribe) => unsubscribe())));
+
+        yield* Effect.promise(() => processor.request({ message: 'Hello?' }));
+
+        // Surface any swallowed request failure before asserting on state.
+        const error = observableRegistry.get(processor.error);
+        expect(error._tag === 'Some' ? `${error.value.message}: ${error.value.cause}` : undefined).toBeUndefined();
+
+        // m1 was finalized exactly once (the late partial after finalization is dropped); m2's
+        // unfinalized partial was flushed into the pending list when the agent completed.
+        const messages = observableRegistry.get(processor.messages);
+        expect(messages.map(({ id }) => id)).toEqual([m1, m2]);
+        const texts = messages.map(({ blocks }) => blocks.map((block) => (block as ContentBlock.Text).text).join(''));
+        expect(texts).toEqual(['Hello world.', 'Working…']);
+
+        // The growing m1 partial was upserted in place (a single entry per snapshot), and the
+        // stale partial that arrived after finalization never surfaced. Transient two-phase
+        // artifacts (a brief [] on finalize, a brief duplicate on flush) are expected — the UI
+        // masks them via `Chat.Root`'s dedupe-by-id merge.
+        expect(snapshots).toContainEqual(['Hel']);
+        expect(snapshots).toContainEqual(['Hello']);
+        expect(snapshots.flat()).not.toContain('Hello world. (stale)');
+
+        // The request settled cleanly: nothing left streaming, no error, inactive.
+        expect(observableRegistry.get(processor.streaming)).toBe(false);
+        expect(observableRegistry.get(processor.active)).toBe(false);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/skills/assistant/skill.node.test.ts

@@ -5,12 +5,12 @@
 import { describe, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
+import { AgentService } from '@dxos/agent-runtime';
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
 import { DatabaseHandlers, DatabaseSkill } from '@dxos/assistant-toolkit';
 import { Skill } from '@dxos/compute';
 import { Feed } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
-import { AgentService } from '@dxos/functions-runtime';
-import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 import { EntityId } from '@dxos/keys';
 import { Organization } from '@dxos/types';
 

package/src/skills/assistant/skill.ts

@@ -2,12 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { LayoutOperation } from '@dxos/app-toolkit';
+import { LayoutOperation, NavigationOperation } from '@dxos/app-toolkit';
 import { templates } from '@dxos/assistant';
 import { Skill } from '@dxos/compute';
 
-import { AssistantOperation } from '#types';
-
 const SKILL_KEY = 'org.dxos.skill.assistant';
 
 const make = () =>
@@ -17,8 +15,8 @@ const make = () =>
     tools: Skill.toolDefinitions({
       // TODO(wittjosiah): LayoutOperation.Open requires Capability.Service which is only available
       //   via the compute-runtime layer (plugin-routine). Once Capability.Service is propagated
-      //   through LocalFunctionExecutionService, this will work without the compute-runtime dependency.
-      operations: [LayoutOperation.Open, AssistantOperation.ResolveNavigationTargets],
+      //   through the process operation runtime, this will work without the compute-runtime dependency.
+      operations: [LayoutOperation.Open, NavigationOperation.ResolveNavigationTargets],
     }),
     instructions: templates.system,
   });

package/src/templates/routine-templates.test.ts

@@ -5,10 +5,9 @@
 import * as Effect from 'effect/Effect';
 import { describe, test } from 'vitest';
 
-import { Instructions, Trigger } from '@dxos/compute';
+import { Instructions, Routine, Trigger } from '@dxos/compute';
 import { Database, Obj } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
-import { Routine } from '@dxos/plugin-routine';
 
 import { dailyDigest } from './daily-digest';
 import { researchBrief } from './research-brief';

package/src/templates/scaffold.ts

@@ -4,9 +4,9 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Instructions, Skill, Trigger } from '@dxos/compute';
+import { Instructions, type Routine, Skill, Trigger } from '@dxos/compute';
 import { Ref } from '@dxos/echo';
-import { Routine } from '@dxos/plugin-routine/types';
+import { makeRoutine } from '@dxos/plugin-routine';
 
 export type ScheduledRoutineOptions = {
   name: string;
@@ -30,7 +30,7 @@ export const makeScheduledRoutine = ({
 }: ScheduledRoutineOptions): Effect.Effect<Routine.Routine, never, never> => {
   const skills = skillKeys.map((key) => Ref.fromURI(Skill.registryURI(key)));
   return Effect.succeed(
-    Routine.make({
+    makeRoutine({
       name,
       instructions: Instructions.make({ name, text, skills }),
       trigger: Trigger.make({ spec: Trigger.specTimer(cron), enabled: false }),