@dxos/plugin-assistant 0.9.0 → 0.9.1-staging.ee54ba693a

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

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { Collection, Filter, Obj, Order, Query, Type } from '@dxos/echo';
+import { HiddenAnnotation, getTypeAnnotation } from '@dxos/echo/Annotation';
+import { Kind as EntityKind } from '@dxos/echo/Entity';
+import { log } from '@dxos/log';
+
+import { AssistantCapabilities, AssistantOperation } from '#types';
+
+const MODEL = 'com.anthropic.model.claude-haiku-4-5.default';
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const RECENT_LIMIT = 20;
+const MAX_PROMPTS = 3;
+
+// Onboarding documents added by the system at identity creation — exclude them so a
+// brand-new personal space (containing only the welcome doc) still uses fallback prompts.
+const ONBOARDING_DOCUMENT_LABELS = new Set(['Welcome to Composer']);
+
+const handler: Operation.WithHandler<typeof AssistantOperation.GenerateHomeSuggestions> =
+  AssistantOperation.GenerateHomeSuggestions.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ db }) {
+        const spaceId = db.spaceId;
+
+        // Cache check: return early if a fresh result exists.
+        const cache = yield* Capabilities.getAtomValue(AssistantCapabilities.HomeSuggestionsCache);
+        const entry = cache[spaceId];
+        if (entry && Date.now() - entry.generatedAt < CACHE_TTL_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) => getTypeAnnotation(Type.getSchema(type))?.kind !== EntityKind.Relation)
+          .filter((type) => !HiddenAnnotation.get(Type.getSchema(type)).pipe(Option.getOrElse(() => false)))
+          .filter((type) => Type.getTypename(type) !== collectionTypename);
+
+        let prompts: string[] = [];
+
+        if (types.length > 0) {
+          const objects = yield* Effect.promise(() =>
+            db
+              .query(
+                Query.select(Filter.or(...types.map((type) => Filter.type(type))))
+                  .orderBy(Order.updated('desc'))
+                  .limit(RECENT_LIMIT),
+              )
+              .run(),
+          );
+
+          const items = objects
+            .filter(Obj.isObject)
+            .filter((obj) => !Obj.isDeleted(obj))
+            .filter((obj) => !ONBOARDING_DOCUMENT_LABELS.has(Obj.getLabel(obj) ?? ''))
+            .flatMap((obj): { label: string; typename: string }[] => {
+              const label = Obj.getLabel(obj);
+              const typename = Obj.getTypename(obj);
+              return label && typename ? [{ label, typename }] : [];
+            });
+
+          if (items.length > 0) {
+            prompts = yield* generateSuggestions(items);
+          }
+        }
+
+        const validPrompts = prompts.map((p) => p.trim()).filter((p) => p.length > 0);
+
+        if (validPrompts.length > 0) {
+          yield* Capabilities.updateAtomValue(AssistantCapabilities.HomeSuggestionsCache, (current) => ({
+            ...current,
+            [spaceId]: { generatedAt: Date.now(), prompts: validPrompts },
+          }));
+        }
+
+        return { prompts: validPrompts };
+      }),
+    ),
+  );
+
+const generateSuggestions = (items: { label: string; typename: string }[]) =>
+  Effect.scoped(
+    LanguageModel.generateObject({
+      schema: Schema.Struct({ prompts: Schema.Array(Schema.String) }),
+      prompt: [
+        'Generate exactly 3 short, imperative, specific starter prompts for an AI assistant with access to this workspace.',
+        'Each prompt must be one sentence, at most 10 words, with no markdown or numbering.',
+        '',
+        'Recent workspace objects:',
+        ...items.map(({ label, typename }) => `- ${label} (${typename})`),
+      ].join('\n'),
+    }),
+  ).pipe(
+    Effect.map(({ value }) => [...value.prompts.slice(0, MAX_PROMPTS)]),
+    Effect.catchAll((err) => {
+      log.warn('generate-home-suggestions: LLM call failed', { err });
+      return Effect.succeed<string[]>([]);
+    }),
+    Effect.provide(AiService.model(MODEL)),
+  );
+
+export default handler;

package/src/operations/index.ts

@@ -8,6 +8,7 @@ export const AssistantOperationHandlerSet = OperationHandlerSet.lazy(
   () => import('./create-chat'),
   () => import('./ensure-companion-chat'),
   () => import('./fork-chat'),
+  () => import('./generate-home-suggestions'),
   () => import('./resolve-navigation-targets'),
   () => import('./run-prompt-in-new-chat'),
   () => import('./set-current-chat'),

package/src/operations/prompt.node.test.ts

@@ -6,15 +6,15 @@ import * as Array from 'effect/Array';
 import * as Effect from 'effect/Effect';
 import { describe, test } from 'vitest';
 
-import { AgentPrompt, Chat } from '@dxos/assistant-toolkit';
-import { Operation, Routine, ServiceResolver } from '@dxos/compute';
+import { Chat, RunInstructions } from '@dxos/assistant-toolkit';
+import { Instructions, Operation, ServiceResolver } from '@dxos/compute';
 import { Database, Feed, Filter, Ref } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
 import { EntityId } from '@dxos/keys';
-import { AutomationPlugin } from '@dxos/plugin-automation/plugin';
 import { ClientCapabilities } from '@dxos/plugin-client';
 import { ClientPlugin } from '@dxos/plugin-client/plugin';
 import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { RoutinePlugin } from '@dxos/plugin-routine/plugin';
 import { createComposerTestApp } from '@dxos/plugin-testing/harness';
 import { Message } from '@dxos/types';
 
@@ -23,14 +23,14 @@ import { AssistantPlugin } from '#plugin';
 EntityId.dangerouslyDisableRandomness();
 
 describe('Agent prompt (composer plugin harness)', () => {
-  // Hits AutomationPlugin compute runtime (plugin handlers, AiServiceLayer, blueprints).
+  // Hits RoutinePlugin compute runtime (plugin handlers, AiServiceLayer, skills).
   // Requires reachable edge AI (see repo DX_EDGE_AI_SERVICE_URL); not memoized like AssistantTestLayer tests.
   test(
     'chat mode appends assistant messages to the chat queue',
     { tags: ['llm'], timeout: 60_000 },
     async ({ expect }) => {
       await using harness = await createComposerTestApp({
-        plugins: [ClientPlugin({}), AssistantPlugin(), AutomationPlugin()],
+        plugins: [ClientPlugin({}), AssistantPlugin(), RoutinePlugin()],
       });
 
       const { personalSpace } = await EffectEx.runAndForwardErrors(
@@ -41,40 +41,37 @@ describe('Agent prompt (composer plugin harness)', () => {
         Effect.gen(function* () {
           const feed = yield* Database.add(Feed.make());
 
-          const messageCountBefore = yield* Feed.runQuery(feed, Filter.type(Message.Message)).pipe(
+          const messageCountBefore = yield* Feed.query(feed, Filter.type(Message.Message)).run.pipe(
             Effect.map(Array.length),
           );
 
           const chat = yield* Database.add(Chat.make({ feed: Ref.make(feed) }));
-          const prompt = yield* Database.add(
-            Routine.make({
+          const instructions = yield* Database.add(
+            Instructions.make({
               name: 'chat-mode-test',
-              instructions: 'Reply with a single word: ack.',
-              blueprints: [],
-              context: [],
+              text: 'Reply with a single word: ack.',
+              skills: [],
             }),
           );
           yield* Database.flush();
 
           const result = yield* Operation.invoke(
-            AgentPrompt,
+            RunInstructions,
             {
-              prompt: Ref.make(prompt),
+              instructions: Ref.make(instructions),
               input: {},
               chat: Ref.make(chat),
             },
             { spaceId: personalSpace.id },
           );
 
-          const messageCountAfter = yield* Feed.runQuery(feed, Filter.type(Message.Message)).pipe(
+          const messageCountAfter = yield* Feed.query(feed, Filter.type(Message.Message)).run.pipe(
             Effect.map(Array.length),
           );
 
           expect(messageCountAfter).toBeGreaterThan(messageCountBefore);
           expect(result).toBe('ack');
-        }).pipe(
-          Effect.provide(ServiceResolver.provide({ space: personalSpace.id }, Database.Service, Feed.FeedService)),
-        ),
+        }).pipe(Effect.provide(ServiceResolver.provide({ space: personalSpace.id }, Database.Service))),
         { timeout: 30_000 },
       );
     },

package/src/operations/resolve-navigation-targets.ts

@@ -5,27 +5,40 @@
 import * as Effect from 'effect/Effect';
 
 import { Capability } from '@dxos/app-framework';
-import { AppCapabilities } from '@dxos/app-toolkit';
+import { AppCapabilities, AppSpace } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
-// Value-side `DXN` re-export keeps the inferred `default` export's `.d.ts` portable —
-// `AssistantOperation.ResolveNavigationTargets` references `DXN.Schema` and the emitter
-// would otherwise emit an unresolvable type-only reference.
-import { DXN as _DXNReference } from '@dxos/keys';
-export { _DXNReference };
+import { Database, EID } from '@dxos/echo';
+import { ClientCapabilities } from '@dxos/plugin-client';
 
 import { AssistantOperation } from '#types';
 
-export default AssistantOperation.ResolveNavigationTargets.pipe(
-  Operation.withHandler(
-    Effect.fn(function* ({ query }) {
-      const capabilities = yield* Capability.Service;
+const handler: Operation.WithHandler<typeof AssistantOperation.ResolveNavigationTargets> =
+  AssistantOperation.ResolveNavigationTargets.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ query }) {
+        const capabilities = yield* Capability.Service;
+        const client = yield* Capability.get(ClientCapabilities.Client).pipe(
+          Effect.catchAll(() => Effect.succeed(undefined)),
+        );
 
-      // Delegate to contributed resolvers.
-      const resolvers = capabilities.getAll(AppCapabilities.NavigationTargetResolver);
-      const results = yield* Effect.forEach(resolvers, (resolver) =>
-        resolver(query as AppCapabilities.NavigationQuery).pipe(Effect.catchAll(() => Effect.succeed([]))),
-      );
-      return { targets: results.flat() };
-    }),
-  ),
-);
+        // Object resolvers read the space database to derive a navigation path, but the agent tool
+        // runtime does not bind Database.Service. Derive it from the queried object URI's space (or
+        // the active space for space-less URIs) so resolution works for object URIs.
+        const eid = query?.uri ? EID.tryParse(query.uri) : undefined;
+        const spaceId = eid ? EID.getSpaceId(eid) : undefined;
+        const space = client
+          ? ((spaceId ? client.spaces.get(spaceId) : undefined) ?? AppSpace.getActiveSpace(client, capabilities))
+          : undefined;
+
+        // Delegate to contributed resolvers.
+        const resolvers = capabilities.getAll(AppCapabilities.NavigationTargetResolver);
+        const resolve = Effect.forEach(resolvers, (resolver) =>
+          resolver(query).pipe(Effect.catchAll(() => Effect.succeed([]))),
+        );
+        const results = yield* space ? resolve.pipe(Effect.provide(Database.layer(space.db))) : resolve;
+        return { targets: results.flat() };
+      }),
+    ),
+  );
+
+export default handler;

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

@@ -5,35 +5,35 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { getObjectPathFromObject, LayoutOperation } from '@dxos/app-toolkit';
+import { LayoutOperation } from '@dxos/app-toolkit';
 import { AiContext } from '@dxos/assistant';
-import { AgentPrompt } from '@dxos/assistant-toolkit';
-import { Blueprint, Operation, Routine, Template } from '@dxos/compute';
-import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
-import { createFeedServiceLayer } from '@dxos/echo-client';
+import { RunInstructions } from '@dxos/assistant-toolkit';
+import { Instructions, Operation, Skill, Template } from '@dxos/compute';
+import { Database, Filter, Obj, Ref } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { ClientCapabilities } from '@dxos/plugin-client';
+import { RoutineOperation } from '@dxos/plugin-routine/types';
 import { Text } from '@dxos/schema';
 
 import { AssistantCapabilities, AssistantOperation } from '#types';
 
-const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInNewChat> =
-  AssistantOperation.RunPromptInNewChat.pipe(
+import { getChatPath } from '../paths';
+
+const handler: Operation.WithHandler<typeof RoutineOperation.RunPromptInNewChat> =
+  RoutineOperation.RunPromptInNewChat.pipe(
     Operation.withHandler(
       Effect.fnUntraced(
-        function* ({ db, prompt, objects, blueprints, background }) {
+        function* ({ db, instructions, objects, skills, background }) {
           const registry = yield* Capability.get(Capabilities.AtomRegistry);
           const { object: chat } = yield* Operation.invoke(AssistantOperation.CreateChat, { db });
 
-          if ((objects && objects.length > 0) || (blueprints && blueprints.length > 0)) {
-            const feedTarget = chat.feed.target;
-            invariant(feedTarget, 'Chat feed not found.');
+          if ((objects && objects.length > 0) || (skills && skills.length > 0)) {
+            const feedTarget = yield* Database.load(chat.feed);
             const client = yield* Capability.get(ClientCapabilities.Client);
             const space = client.spaces.get(db.spaceId);
             invariant(space, 'Space not found.');
-            const feedServiceLayer = createFeedServiceLayer(space.queues);
-            const runtime = yield* Effect.runtime<Feed.FeedService>().pipe(Effect.provide(feedServiceLayer));
+            const runtime = yield* Effect.runtime<Database.Service>().pipe(Effect.provide(Database.layer(space.db)));
             const binder = new AiContext.Binder({ feed: feedTarget, runtime, registry });
             yield* Effect.promise(() =>
               binder.use(async (b: AiContext.Binder) => {
@@ -43,14 +43,14 @@ const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInNewCha
                   bindingProps.objects = objects.map((obj) => Ref.make(obj));
                 }
 
-                if (blueprints && blueprints.length > 0) {
-                  const allBlueprints = await db.query(Filter.type(Blueprint.Blueprint)).run();
-                  const matchedBlueprints = allBlueprints.filter((blueprint) => {
-                    const blueprintKey = Obj.getMeta(blueprint).key;
-                    return blueprintKey !== undefined && blueprints.includes(blueprintKey);
+                if (skills && skills.length > 0) {
+                  const allSkills = await db.query(Filter.type(Skill.Skill)).run();
+                  const matchedSkills = allSkills.filter((skill) => {
+                    const skillKey = Obj.getMeta(skill).key;
+                    return skillKey !== undefined && skills.includes(skillKey);
                   });
-                  if (matchedBlueprints.length > 0) {
-                    bindingProps.blueprints = matchedBlueprints.map((blueprint) => Ref.make(blueprint));
+                  if (matchedSkills.length > 0) {
+                    bindingProps.skills = matchedSkills.map((skill) => Ref.make(skill));
                   }
                 }
 
@@ -60,21 +60,20 @@ const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInNewCha
           }
 
           if (background) {
-            const promptRef =
-              typeof prompt === 'string'
+            const instructionsRef =
+              typeof instructions === 'string'
                 ? Ref.make(
-                    Routine.make({
-                      instructions: prompt,
-                      blueprints: [],
-                      context: [],
+                    Instructions.make({
+                      text: instructions,
+                      skills: [],
                     }),
                   )
-                : prompt;
+                : instructions;
             yield* Database.flush();
             yield* Operation.invoke(
-              AgentPrompt,
+              RunInstructions,
               {
-                prompt: promptRef,
+                instructions: instructionsRef,
                 input: {},
                 chat: Ref.make(chat),
               },
@@ -88,14 +87,14 @@ const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInNewCha
             return { object: chat };
           }
 
-          const chatPath = getObjectPathFromObject(chat);
+          const chatPath = getChatPath(db.spaceId, chat.id);
           const pendingPromptText =
-            typeof prompt === 'string'
-              ? prompt
+            typeof instructions === 'string'
+              ? instructions
               : yield* Effect.gen(function* () {
-                  const promptObj = yield* Effect.promise(() => prompt.load());
-                  const source = yield* Effect.promise(() => promptObj.instructions.load());
-                  invariant(Obj.instanceOf(Text.Text, source), 'Prompt instructions must be Text.');
+                  const instructionsObj = yield* Effect.promise(() => instructions.load());
+                  const source = yield* Effect.promise(() => instructionsObj.text.load());
+                  invariant(Obj.instanceOf(Text.Text, source), 'Prompt text must be Text.');
                   return Template.process(source.content ?? '');
                 });
           yield* Capabilities.updateAtomValue(AssistantCapabilities.State, (current) => ({

package/src/operations/update-chat-name.ts

@@ -40,7 +40,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.UpdateChatName> =
           );
         } else {
           const feed = yield* Database.load(chat.feed);
-          const history = yield* Feed.runQuery(feed, Filter.type(Message.Message));
+          const history = yield* Feed.query(feed, Filter.type(Message.Message)).run;
           log.info('history', { history: history.length });
           const historyPrompt = yield* AiPreprocessor.preprocessPrompt(history, {
             system,
@@ -57,7 +57,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.UpdateChatName> =
         });
         log.info('chat name updated', { chat, newName: chat.name });
       },
-      Effect.provide(AiService.model('ai.claude.model.claude-haiku-4-5')),
+      Effect.provide(AiService.model('com.anthropic.model.claude-haiku-4-5.default')),
     ),
   ),
 );

package/src/paths.ts

@@ -2,9 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import { createTypeSectionPaths } from '@dxos/app-toolkit';
+import { Paths } from '@dxos/app-toolkit';
 import { Chat } from '@dxos/assistant-toolkit';
 
-const { getSectionPath: getChatsPath, getObjectPath: getChatPath } = createTypeSectionPaths(Chat.Chat);
+const { getSectionPath: getChatsPath, getObjectPath: getChatPath } = Paths.createTypeSectionPaths(Chat.Chat, {
+  groupId: Paths.GroupSegments.ai,
+});
 
-export { getChatsPath, getChatPath };
+export { getChatPath, getChatsPath };

package/src/plugin.workerd.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { AssistantPlugin, default } from './AssistantPlugin.workerd';

package/src/processor/presets.ts

@@ -2,71 +2,48 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
-
-import { type ModelName } from '@dxos/ai';
-
-const ModelProviders = ['dxos-local', 'dxos-remote', 'lm-studio', 'ollama'] as const;
-
-const ModelProvider = Schema.Literal(...ModelProviders);
-type ModelProvider = Schema.Schema.Type<typeof ModelProvider>;
+import { Model, Provider } from '@dxos/ai';
+import { DXN } from '@dxos/keys';
 
+/**
+ * A chat preset: a model offered for a provider, with a display label. Derived from the {@link Model}
+ * catalog — see {@link presetsForProvider}.
+ */
 export type AiServicePreset = {
   id: string;
-  provider: ModelProvider;
-  model: ModelName;
-  label?: string;
+  provider: DXN.DXN;
+  model: DXN.DXN;
+  /** Provider-specific back-end name (e.g. an Ollama pull tag); used to match installed models. */
+  backend: string;
+  label: string;
 };
 
-const createModelLabel = (model: ModelName) => {
-  const parts = model.split('.');
-  return parts[parts.length - 1];
+/** Presets for a provider: every model the provider serves (the catalog filtered by provider). */
+export const presetsForProvider = (provider: DXN.DXN): AiServicePreset[] =>
+  Model.forProvider(provider).map((model) => ({
+    id: model.id,
+    provider,
+    model: model.id,
+    backend: model.backend,
+    label: model.label,
+  }));
+
+/**
+ * Reconcile a stored provider DXN with the runtime: map the bundled sidecar (`built-in`) and an
+ * external server (`ollama`) onto whichever is actually available — they are environment-exclusive
+ * (the sidecar exists only on desktop). Defaults to `edge` when unset or unparseable.
+ */
+export const resolveProvider = (provider: string | undefined, hasBuiltIn: boolean): DXN.DXN => {
+  const resolved = (provider ? DXN.tryMake(provider) : undefined) ?? Provider.edge.id;
+  if (resolved === Provider.ollama.id && hasBuiltIn) {
+    return Provider.builtIn.id;
+  }
+  if (resolved === Provider.builtIn.id && !hasBuiltIn) {
+    return Provider.ollama.id;
+  }
+  return resolved;
 };
 
-// TODO(burdon): Users should be able to create and edit presets.
-export const AiServicePresets: AiServicePreset[] = [
-  // Sonnet is first so it is the default selection.
-  {
-    provider: 'dxos-remote' as const,
-    model: 'ai.claude.model.claude-sonnet-4-6' as const,
-    label: 'Claude Sonnet',
-  },
-  {
-    provider: 'dxos-remote' as const,
-    model: 'ai.claude.model.claude-opus-4-8' as const,
-    label: 'Claude Opus',
-  },
-  {
-    provider: 'dxos-remote' as const,
-    model: 'ai.claude.model.claude-haiku-4-5' as const,
-    label: 'Claude Haiku',
-  },
-  {
-    provider: 'ollama' as const,
-    model: 'ai.ollama.model.gpt-oss:20b' as const,
-  },
-  {
-    provider: 'ollama' as const,
-    model: 'ai.ollama.model.gemma4:latest' as const,
-  },
-  {
-    provider: 'lm-studio' as const,
-    model: 'ai.google.model.gemma-3-27b' as const,
-  },
-  {
-    provider: 'lm-studio' as const,
-    model: 'ai.meta.model.llama-3.2-3b-instruct' as const,
-  },
-  {
-    model: 'ai.ollama.model.deepseek-r1:latest' as const,
-    provider: 'dxos-local' as const,
-  },
-].map(
-  ({ model, provider, label }, i) =>
-    ({
-      id: `preset-${i}`,
-      provider,
-      model,
-      label: label ?? createModelLabel(model),
-    }) satisfies AiServicePreset,
-);
+/** The {@link Settings.modelDefaults} key for a provider (`built-in` shares the `ollama` key). */
+export const defaultsKeyForProvider = (provider: DXN.DXN): 'edge' | 'ollama' | 'lmstudio' =>
+  provider === Provider.edge.id ? 'edge' : provider === Provider.lmStudio.id ? 'lmstudio' : 'ollama';

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

@@ -2,20 +2,24 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as AiError from '@effect/ai/AiError';
 import { describe, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as Option from 'effect/Option';
+import { test } from 'vitest';
 
 import { Capabilities } from '@dxos/app-framework';
 import { AiSession } from '@dxos/assistant';
 import { Chat } from '@dxos/assistant-toolkit';
 import { Database, Feed } from '@dxos/echo';
+import { UsageQuotaExceededError } from '@dxos/edge-client';
 import { EffectEx } from '@dxos/effect';
 import { TestHelpers } from '@dxos/effect/testing';
 import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 
-import { AiChatProcessor } from './processor';
+import { AiChatProcessor, AiUsageQuotaError, parseError } from './processor';
 
 const TestLayer = AssistantTestLayer({ tracing: 'noop', types: [Chat.Chat, Feed.Feed] });
 
@@ -26,7 +30,7 @@ describe('Chat processor', () => {
       function* ({ expect }) {
         const feed = Feed.make();
         yield* Database.add(feed);
-        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const runtime = yield* Effect.runtime<Database.Service>();
         const session = yield* EffectEx.acquireReleaseResource(() => new AiSession.Session({ feed, runtime }));
         const managedRuntime = ManagedRuntime.make(Layer.empty) as unknown as Capabilities.ProcessManagerRuntime;
         const processor = new AiChatProcessor(session, managedRuntime, feed, Layer.empty as any);
@@ -38,3 +42,69 @@ describe('Chat processor', () => {
     ),
   );
 });
+
+describe('parseError', () => {
+  const QUOTA_MESSAGE = 'You have reached your AI usage limit for this period.';
+
+  // The agent runs in a separate process; on failure the cause is rendered to a string via
+  // `Cause.pretty` (which drops nested causes) before it reaches parseError. EDGE rejects an
+  // over-quota request with 429, which `@effect/ai` surfaces as an HttpResponseError whose message
+  // embeds the status — this is the exact string the chat receives.
+  test('detects an EDGE 429 in the pretty-printed process failure (string)', ({ expect }) => {
+    const err =
+      'HttpResponseError: StatusCode: An HTTP response error occurred. (429 POST http://edge.internal/v1/messages)\nResponse Body: {"error":{"message":"You have exceeded your usage quota."}}';
+    const result = parseError(err);
+    expect(result.message).toBe(QUOTA_MESSAGE);
+    // Tagged so the chat toast can offer a usage-dashboard link for this case only.
+    expect(result).toBeInstanceOf(AiUsageQuotaError);
+  });
+
+  test('detects a typed 429 HttpResponseError by status (direct path)', ({ expect }) => {
+    const err = new AiError.HttpResponseError({
+      module: 'AnthropicClient',
+      method: 'streamText',
+      reason: 'StatusCode',
+      request: {
+        method: 'POST',
+        url: 'http://edge.internal/v1/messages',
+        urlParams: [],
+        hash: Option.none(),
+        headers: {},
+      },
+      response: { status: 429, headers: {} },
+      body: JSON.stringify({ error: { message: 'You have exceeded your usage quota.' } }),
+    });
+    expect(parseError(err).message).toBe(QUOTA_MESSAGE);
+  });
+
+  test('surfaces a live UsageQuotaExceededError message from the cause chain (direct path)', ({ expect }) => {
+    const err = new Error('request failed', {
+      cause: new UsageQuotaExceededError({ message: 'You have exceeded your usage quota.' }),
+    });
+    expect(parseError(err).message).toBe('You have exceeded your usage quota.');
+  });
+
+  test('preserves the original error as the cause', ({ expect }) => {
+    const err = 'HttpResponseError: StatusCode: ... (429 POST http://edge.internal/v1/messages)';
+    expect(parseError(err).cause).toBe(err);
+  });
+
+  test('still surfaces the unavailable model from a string', ({ expect }) => {
+    const err = "UnknownError: ChatCompletionsClient.streamText: model 'gemma3:27b' not found";
+    expect(parseError(err).message).toBe('The model is not available: gemma3:27b');
+  });
+
+  test('passes through a non-quota AiError description', ({ expect }) => {
+    const err = new AiError.UnknownError({
+      module: 'ChatCompletionsClient',
+      method: 'streamText',
+      description: 'Connection refused',
+    });
+    expect(parseError(err).message).toBe('Connection refused');
+  });
+
+  test('falls back to a generic message for unrecognized errors', ({ expect }) => {
+    expect(parseError('something unexpected blew up').message).toBe('An unexpected error occurred.');
+    expect(parseError(new Error('boom')).message).toBe('An unexpected error occurred.');
+  });
+});