@dxos/plugin-assistant 0.13.0 → 0.14.0

package/src/operations/analyze-turn.test.ts

@@ -0,0 +1,194 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { beforeEach, describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Atom from 'effect/reactivity/Atom';
+import * as AtomRegistry from 'effect/reactivity/AtomRegistry';
+
+import { AgentService } from '@dxos/agent-runtime';
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { ScriptedLanguageModel } from '@dxos/ai/testing';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as CapabilityManager from '@dxos/app-framework/CapabilityManager';
+import * as Chat from '@dxos/assistant/Chat';
+import { ProcessManager } from '@dxos/compute-runtime';
+import * as Process from '@dxos/compute/Process';
+import * as Skill from '@dxos/compute/Skill';
+import { Feed, Obj } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { DXN, EntityId } from '@dxos/keys';
+import * as Observability from '@dxos/observability/Observability';
+import * as ObservabilityCapabilities from '@dxos/plugin-observability/ObservabilityCapabilities';
+import { Message } from '@dxos/types';
+
+import { AssistantOperationHandlerSet } from '#operations';
+import { TurnReviewSkill } from '#skills';
+import { type Assistant, AssistantCapabilities } from '#types';
+
+import { REVIEW_SYSTEM_PROMPT, STRUGGLE_EVENT, type TurnVerdict } from '../review/turn-review.ts';
+
+EntityId.dangerouslyDisableRandomness();
+
+const VERDICT: TurnVerdict = {
+  struggled: true,
+  cause: 'tool_faulty',
+  severity: 'medium',
+  summary: 'The search tool rejected a valid query.',
+  tools: ['search'],
+};
+
+type Captured = {
+  events: { event: string; attributes?: Record<string, unknown> }[];
+  uploads: { ndjson: string; kind: string }[];
+};
+
+let captured: Captured = { events: [], uploads: [] };
+let telemetryEnabled = true;
+
+/** A real {@link Observability} over one recording extension, so the handler sees the production API. */
+const observability = Effect.runSync(
+  Function.pipe(
+    Observability.make(),
+    Observability.addExtension(
+      Effect.succeed({
+        get enabled() {
+          return telemetryEnabled;
+        },
+        apis: [
+          {
+            kind: 'events',
+            isAvailable: () => Effect.succeed(true),
+            captureEvent: (event, attributes) => void captured.events.push({ event, attributes }),
+          },
+          {
+            kind: 'support',
+            isAvailable: () => Effect.succeed(true),
+            uploadLogs: async () => undefined,
+            uploadNdjson: async (ndjson, kind) => {
+              captured.uploads.push({ ndjson, kind });
+              return 'trajectories/2026-10-06/test.ndjson.gz';
+            },
+            sessionContext: () => undefined,
+            flushLogs: async () => {},
+          },
+        ],
+      }),
+    ),
+  ),
+);
+
+// One manager for the file: the test layer resolves `Capability.Service` before a test body runs, so
+// each test varies the state the manager holds rather than the manager itself.
+const registry = AtomRegistry.make();
+const settingsAtom = Atom.make<Assistant.Settings>({}).pipe(Atom.keepAlive);
+const manager = CapabilityManager.make({ registry });
+manager.contribute({ module: 'test', interface: Capabilities.AtomRegistry, implementation: registry });
+manager.contribute({ module: 'test', interface: AssistantCapabilities.Settings, implementation: settingsAtom });
+manager.contribute({
+  module: 'test',
+  interface: ObservabilityCapabilities.Observability,
+  implementation: observability,
+});
+
+const setup = ({ reportStruggles, telemetry }: { reportStruggles: boolean; telemetry: boolean }) => {
+  registry.set(settingsAtom, { reportStruggles, codeMode: true });
+  telemetryEnabled = telemetry;
+};
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: AssistantOperationHandlerSet,
+  types: [Chat.Chat, Feed.Feed, Message.Message, Skill.Skill],
+  skills: [TurnReviewSkill.make()],
+  // The reviewer gets the verdict; the conversational turn gets a plain reply.
+  aiService: ScriptedLanguageModel.scriptedAiService((request) => ({
+    parts: [
+      ScriptedLanguageModel.text(
+        request.system.includes(REVIEW_SYSTEM_PROMPT) ? JSON.stringify(VERDICT) : 'I could not search your notes.',
+      ),
+    ],
+  })),
+  extraServices: Layer.succeed(Capability.Service, manager),
+});
+
+const MODEL = DXN.make('com.anthropic.model.claude-sonnet-5.default');
+
+/** Runs one turn with the turn-review skill bound and waits for the agent process, hooks included, to finish. */
+const runTurn = Effect.fnUntraced(function* () {
+  const session = yield* AgentService.createSession({ skills: [TurnReviewSkill.make()], model: MODEL });
+  yield* session.submitPrompt('Find my notes.');
+  yield* session.waitForCompletion();
+  const processManager = yield* ProcessManager.ProcessManagerService;
+  // The agent process finishes only after its background hooks, so its exit is the review's.
+  const handles = yield* processManager.list({ target: Obj.getURI(session.chat) });
+  expect(handles.length).toBeGreaterThan(0);
+  yield* Effect.promise(async () => {
+    await expect
+      .poll(() => handles.every((handle) => handle.status.state === Process.State.SUCCEEDED), { timeout: 10_000 })
+      .toBe(true);
+  });
+});
+
+describe('AnalyzeTurn', () => {
+  beforeEach(() => {
+    captured = { events: [], uploads: [] };
+  });
+
+  it.effect(
+    'reports a prompting or tooling struggle with its trajectory',
+    Effect.fnUntraced(
+      function* (_) {
+        setup({ reportStruggles: true, telemetry: true });
+        yield* runTurn();
+
+        expect(captured.uploads).toHaveLength(1);
+        expect(captured.uploads[0].kind).toBe('trajectory');
+        const [header, ...messages] = captured.uploads[0].ndjson.split('\n').map((line) => JSON.parse(line));
+        expect(header).toMatchObject({ type: 'header', verdict: { cause: 'tool_faulty' } });
+        expect(messages.length).toBeGreaterThan(0);
+        expect(messages.every((message) => message.type === 'message')).toBe(true);
+        expect(captured.events).toHaveLength(1);
+        expect(captured.events[0].event).toBe(STRUGGLE_EVENT);
+        expect(captured.events[0].attributes).toMatchObject({
+          model: 'dxn:com.anthropic.model.claude-sonnet-5.default',
+          code_mode: true,
+          cause: 'tool_faulty',
+          cause_group: 'tooling',
+          trajectory_key: 'trajectories/2026-10-06/test.ndjson.gz',
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'does nothing unless the user opted in',
+    Effect.fnUntraced(
+      function* (_) {
+        setup({ reportStruggles: false, telemetry: true });
+        yield* runTurn();
+        expect(captured).toEqual({ events: [], uploads: [] });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'does nothing while telemetry is off',
+    Effect.fnUntraced(
+      function* (_) {
+        setup({ reportStruggles: true, telemetry: false });
+        yield* runTurn();
+        expect(captured).toEqual({ events: [], uploads: [] });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/operations/analyze-turn.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { AiService } from '@dxos/ai';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as Harness from '@dxos/assistant/Harness';
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Obj } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { contentCaptureAllowed } from '@dxos/observability/AiObservability';
+import * as ObservabilityCapabilities from '@dxos/plugin-observability/ObservabilityCapabilities';
+
+import { TurnReviewSkill } from '#skills';
+import { AssistantCapabilities } from '#types';
+
+import {
+  REVIEW_MODEL,
+  REVIEW_SYSTEM_PROMPT,
+  STRUGGLE_EVENT,
+  type TrajectoryHeader,
+  TurnVerdict,
+  formatReviewPrompt,
+  isReportable,
+  toStruggleEventProperties,
+  toTrajectoryNdjson,
+} from '../review/turn-review.ts';
+
+// Never fails: it runs as a background hook after the user's turn, so a review that cannot complete
+// is only logged.
+const handler: Operation.WithHandler<typeof TurnReviewSkill.AnalyzeTurn> = TurnReviewSkill.AnalyzeTurn.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(
+      function* () {
+        const settings = Option.getOrUndefined(yield* Capabilities.getAtomValueOption(AssistantCapabilities.Settings));
+        const observability = Option.getOrUndefined(
+          yield* Capability.getOption(ObservabilityCapabilities.Observability),
+        );
+        // Both opt-ins are re-read here: the skill stays bound to a chat after the user opts out.
+        if (!settings?.reportStruggles || !observability?.enabled) {
+          return;
+        }
+
+        const chat = yield* Harness.getChat;
+        const spaceId = Obj.getDatabase(chat)?.spaceId;
+        if (!spaceId || !contentCaptureAllowed(spaceId)) {
+          return;
+        }
+
+        const history = yield* Harness.history;
+        if (history.length === 0) {
+          return;
+        }
+
+        const { value: verdict } = yield* LanguageModel.generateObject({
+          schema: TurnVerdict,
+          objectName: 'turn_verdict',
+          prompt: Prompt.setSystem(Prompt.make(formatReviewPrompt(history)), REVIEW_SYSTEM_PROMPT),
+        }).pipe(Effect.provide(AiService.languageModel(REVIEW_MODEL)));
+        log.info('turn reviewed', { chat: chat.id, struggled: verdict.struggled, cause: verdict.cause });
+        if (!isReportable(verdict)) {
+          return;
+        }
+
+        const binder = yield* Harness.binder;
+        const feed = yield* Database.load(chat.feed);
+        const header: TrajectoryHeader = {
+          sessionId: Obj.getURI(feed, { prefer: 'absolute' }),
+          model: chat.session?.model,
+          codeMode: settings.codeMode ?? false,
+          skills: binder
+            .getSkills()
+            .filter((skill) => Obj.getMeta(skill).key !== TurnReviewSkill.key)
+            .map((skill) => skill.name),
+          verdict,
+        };
+        const trajectoryKey = yield* Effect.promise(() =>
+          observability.support.uploadNdjson(toTrajectoryNdjson(header, history), 'trajectory'),
+        );
+        observability.events.captureEvent(
+          STRUGGLE_EVENT,
+          toStruggleEventProperties({ ...header, history, trajectoryKey }),
+        );
+      },
+      Effect.catchCause((cause) => Effect.sync(() => log.warn('turn review failed', { cause }))),
+    ),
+  ),
+);
+
+export default handler;

package/src/operations/create-chat.ts

@@ -8,18 +8,14 @@ import * as Capabilities from '@dxos/app-framework/Capabilities';
 import * as Capability from '@dxos/app-framework/Capability';
 import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
 import { AiContext } from '@dxos/assistant';
-import * as AlarmSkill from '@dxos/assistant-toolkit/AlarmSkill';
-import * as ChatContextSkill from '@dxos/assistant-toolkit/ChatContextSkill';
-import * as PlanningSkill from '@dxos/assistant-toolkit/PlanningSkill';
 import * as Chat from '@dxos/assistant/Chat';
 import * as Operation from '@dxos/compute/Operation';
-import * as Skill from '@dxos/compute/Skill';
 import { Database, Feed, Ref } from '@dxos/echo';
-import * as DatabaseSkill from '@dxos/plugin-space/DatabaseSkill';
 
-import { AssistantSkill, PluginManagerSkill } from '#skills';
 import { AssistantOperation } from '#types';
 
+import { bindChatDefaults, contributesPluginManager } from '../util/default-skills.ts';
+
 const handler: Operation.WithHandler<typeof AssistantOperation.CreateChat> = AssistantOperation.CreateChat.pipe(
   Operation.withHandler(
     Effect.fnUntraced(function* ({ name, instructions }) {
@@ -33,39 +29,11 @@ const handler: Operation.WithHandler<typeof AssistantOperation.CreateChat> = Ass
       const feed = db.add(Feed.make());
       const chat = Chat.make({ name, feed: Ref.make(feed), instructions });
 
-      // Dynamic import to avoid circular dependency with the barrel that also exports SkillManagerHandlers.
-      const { SkillManagerSkill } = yield* Effect.promise(() => import('@dxos/assistant-toolkit'));
-
-      // Only an extensible host contributes the plugin-manager skill, since its tools resolve to the
-      // registry plugin's handlers; binding it elsewhere would bind a skill that cannot run.
-      const contributed = yield* Capability.getAll(AppCapabilities.SkillDefinition);
-      const pluginManagerContributed = contributed.some(({ key }) => key === PluginManagerSkill.key);
+      const pluginManager = contributesPluginManager(yield* Capability.getAll(AppCapabilities.SkillDefinition));
 
       const runtime = yield* Effect.context<Database.Service>();
       const binder = new AiContext.Binder({ feed, runtime, registry });
-
-      // Bind default skills via registry refs — no DB clone needed since the ECHO ref
-      // resolver already spans the hypergraph registry.
-      yield* Effect.promise(() =>
-        binder.use((b: AiContext.Binder) =>
-          b.bind({
-            skills: [
-              AssistantSkill,
-              DatabaseSkill,
-              ChatContextSkill,
-              SkillManagerSkill,
-              AlarmSkill,
-              // Bound by default rather than agent-enabled: the conversation's checklist is durable
-              // and invisible to the model, so a chat without this skill cannot read or update the
-              // tasks it is already carrying — and a model that enables it mid-turn has already
-              // answered a task question from nothing.
-              PlanningSkill,
-              ...(pluginManagerContributed ? [PluginManagerSkill] : []),
-            ].map(({ key }) => Ref.fromURI(Skill.registryURI(key))),
-            objects: [Ref.make(chat)],
-          }),
-        ),
-      );
+      yield* Effect.promise(() => binder.use((b: AiContext.Binder) => bindChatDefaults(b, { chat, pluginManager })));
 
       return { object: chat };
     }),

package/src/operations/generate-home-suggestions.test.ts

@@ -122,11 +122,10 @@ describe('GenerateHomeSuggestions', () => {
   );
 
   it.effect(
-    'a changed set reuses cached prompts within the refresh interval',
+    'cached prompts are reused within the refresh interval whatever the recent set is',
     Effect.fnUntraced(
       function* (_) {
         const { db } = yield* Database.Service;
-        yield* addNotes(5);
         const stored = ['Refine the proposal', 'Review the schedule', 'Draft a summary'];
         testRegistry.set(testCacheAtom, {
           [db.spaceId]: { generatedAt: Date.now() - HOUR_MS / 2, prompts: stored, fingerprint: 'another set' },

package/src/operations/generate-home-suggestions.ts

@@ -3,6 +3,7 @@
 //
 
 import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Array from 'effect/Array';
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
@@ -44,14 +45,24 @@ const handler: Operation.WithHandler<typeof AssistantOperation.GenerateHomeSugge
         const { db } = yield* Database.Service;
         const spaceId = db.spaceId;
 
+        const cache = yield* Capabilities.getAtomValue(AssistantCapabilities.HomeSuggestionsCache);
+        const entry = cache[spaceId];
+        const age = entry ? Date.now() - entry.generatedAt : Infinity;
+        if (entry && age < MIN_REFRESH_MS) {
+          return { prompts: [...entry.prompts] };
+        }
+
         // Build the recent-objects filter (mirrors SpaceHomeRecent).
         const schemas = yield* Capability.getAll(AppCapabilities.Schema);
         const collectionTypename = Type.getTypename(Collection.Collection);
-        const types = schemas
-          .flat()
-          .filter(Type.isType)
-          .filter((type) => TypeOptions.isUserType(type))
-          .filter((type) => Type.getTypename(type) !== collectionTypename);
+        const types = Array.dedupeWith(
+          schemas
+            .flat()
+            .filter(Type.isType)
+            .filter((type) => TypeOptions.isUserType(type))
+            .filter((type) => Type.getTypename(type) !== collectionTypename),
+          (a, b) => Type.getURI(a) === Type.getURI(b),
+        );
         if (types.length === 0) {
           return { prompts: [] };
         }
@@ -85,10 +96,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.GenerateHomeSugge
           .map(({ label, typename }) => `${typename}:${label}`)
           .sort()
           .join('\n');
-        const cache = yield* Capabilities.getAtomValue(AssistantCapabilities.HomeSuggestionsCache);
-        const entry = cache[spaceId];
-        const age = entry ? Date.now() - entry.generatedAt : Infinity;
-        if (entry && (age < MIN_REFRESH_MS || (entry.fingerprint === fingerprint && age < CACHE_TTL_MS))) {
+        if (entry && entry.fingerprint === fingerprint && age < CACHE_TTL_MS) {
           return { prompts: [...entry.prompts] };
         }
 

package/src/operations/index.ts

@@ -6,6 +6,7 @@ import * as Operation from '@dxos/compute/Operation';
 import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
 import * as RoutineOperation from '@dxos/plugin-routine/RoutineOperation';
 
+import { TurnReviewSkill } from '#skills';
 import { AssistantOperation } from '#types';
 
 export const AssistantOperationHandlerSet = OperationHandlerSet.lazy([
@@ -23,4 +24,5 @@ export const AssistantOperationHandlerSet = OperationHandlerSet.lazy([
   AssistantOperation.SetCurrentChat.pipe(Operation.lazyHandler(() => import('./set-current-chat.ts'))),
   AssistantOperation.SetTracePanelDebug.pipe(Operation.lazyHandler(() => import('./set-trace-panel-debug.ts'))),
   AssistantOperation.UpdateChatName.pipe(Operation.lazyHandler(() => import('./update-chat-name.ts'))),
+  TurnReviewSkill.AnalyzeTurn.pipe(Operation.lazyHandler(() => import('./analyze-turn.ts'))),
 ]);

package/src/operations/run-prompt-in-chat.ts

@@ -8,6 +8,7 @@ import * as Option from 'effect/Option';
 import * as Capabilities from '@dxos/app-framework/Capabilities';
 import * as Capability from '@dxos/app-framework/Capability';
 import * as Plugin from '@dxos/app-framework/Plugin';
+import * as Agent from '@dxos/assistant/Agent';
 import * as Chat from '@dxos/assistant/Chat';
 import * as AgentService from '@dxos/compute/AgentService';
 import * as Operation from '@dxos/compute/Operation';
@@ -17,8 +18,8 @@ import { ContentBlock } from '@dxos/types';
 
 import { AssistantCapabilities, AssistantEvents, AssistantOperation } from '#types';
 
+import { defaultPreset, providerForModel } from '../chat-model/index.ts';
 import { ChatNotSpecifiedError } from '../errors.ts';
-import { defaultPreset, providerForModel } from '../processor/index.ts';
 
 const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInChat> =
   AssistantOperation.RunPromptInChat.pipe(
@@ -62,7 +63,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInChat>
         const model = chat.session?.model ?? preset?.model;
         const session = yield* AgentService.getSession(chat, {
           provider: model ? providerForModel(model, preset?.provider) : preset?.provider,
-          location: chat.remote ? 'edge' : 'local',
+          location: Agent.chatLocation(chat),
         });
         // A plain string is submitted as-is so the default path keeps its existing shape; a stated
         // disposition needs the block form, which is the only place it can be carried.

package/src/review/turn-review.test.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Message } from '@dxos/types';
+
+import {
+  type TurnVerdict,
+  causeGroup,
+  formatReviewPrompt,
+  isReportable,
+  splitTurn,
+  toStruggleEventProperties,
+  toTrajectoryNdjson,
+} from './turn-review.ts';
+
+const text = (created: string, sender: 'user' | 'assistant', value: string) =>
+  Message.make({ created, sender, blocks: [{ _tag: 'text', text: value }] });
+
+const HISTORY = [
+  text('2026-10-06T09:00:00.000Z', 'user', 'earlier question'),
+  text('2026-10-06T09:00:05.000Z', 'assistant', 'earlier answer'),
+  text('2026-10-06T10:00:00.000Z', 'user', 'latest question'),
+  Message.make({
+    created: '2026-10-06T10:00:02.000Z',
+    sender: 'assistant',
+    blocks: [
+      { _tag: 'toolCall', toolCallId: '1', name: 'search', input: '{}', providerExecuted: false },
+      { _tag: 'toolResult', toolCallId: '1', name: 'search', error: 'boom', providerExecuted: false },
+    ],
+  }),
+];
+
+const VERDICT: TurnVerdict = {
+  struggled: true,
+  cause: 'system_prompt_missing',
+  severity: 'high',
+  summary: 'The agent did not know how to find notes.',
+  tools: [],
+};
+
+describe('turn review', () => {
+  test('the turn starts at the last user message', ({ expect }) => {
+    const { context, turn } = splitTurn(HISTORY);
+    expect(context).toHaveLength(2);
+    expect(turn).toHaveLength(2);
+  });
+
+  test('only prompting and tooling causes are reported', ({ expect }) => {
+    expect(causeGroup('system_prompt_wrong')).toBe('system_prompt');
+    expect(causeGroup('tool_missing')).toBe('tooling');
+    expect(isReportable(VERDICT)).toBe(true);
+    expect(isReportable({ ...VERDICT, cause: 'model' })).toBe(false);
+    expect(isReportable({ ...VERDICT, struggled: false })).toBe(false);
+  });
+
+  test('the prompt marks the latest turn', ({ expect }) => {
+    const [before, after] = formatReviewPrompt(HISTORY).split('<latest_turn>');
+    expect(before).toContain('earlier question');
+    expect(after).toContain('latest question');
+    expect(after).toContain('[tool error search] boom');
+  });
+
+  test('trajectory and event carry the turn metadata', ({ expect }) => {
+    const header = {
+      sessionId: 'echo://space/feed',
+      model: 'dxn:com.anthropic.model.claude-sonnet-5.default',
+      codeMode: false,
+      skills: ['Markdown', 'Tables'],
+      verdict: VERDICT,
+    };
+    const lines = toTrajectoryNdjson(header, HISTORY)
+      .split('\n')
+      .map((line) => JSON.parse(line));
+    expect(lines).toHaveLength(1 + HISTORY.length);
+    expect(lines[0]).toMatchObject({ type: 'header', skills: ['Markdown', 'Tables'] });
+
+    expect(toStruggleEventProperties({ ...header, history: HISTORY, trajectoryKey: 'k' })).toMatchObject({
+      $ai_session_id: 'echo://space/feed',
+      model: 'dxn:com.anthropic.model.claude-sonnet-5.default',
+      code_mode: false,
+      skills: 'Markdown,Tables',
+      cause_group: 'system_prompt',
+      turn_message_count: 2,
+      turn_tool_call_count: 1,
+      turn_tool_error_count: 1,
+      trajectory_key: 'k',
+    });
+  });
+});