@dxos/plugin-assistant 0.8.4-staging.60fe92afc8 → 0.9.1-main.c7dcc2e112

package/src/meta.ts

@@ -4,40 +4,12 @@
 
 import { Plugin } from '@dxos/app-framework';
 import { DXN } from '@dxos/keys';
-import { trim } from '@dxos/util';
 
-export const meta = Plugin.makeMeta({
-  key: DXN.make('org.dxos.plugin.assistant'),
-  name: 'Assistant',
-  author: 'DXOS',
-  description: trim`
-    AssistantPlugin brings a conversational AI assistant into DXOS Composer, letting users chat naturally
-    with objects in their spaces. Every Chat is a first-class ECHO object — messages are persisted,
-    replicated across peers in real time, and can be bound to any document or collection as a companion
-    panel that appears alongside the primary view.
+import config from '../dx.config';
 
-    AI capabilities are delivered through a flexible multi-provider model layer. Users can route requests
-    to the DXOS Edge service, a locally running Ollama instance, or LM Studio, and switch providers at
-    any time in Settings. Each provider can be configured with a preferred model, and the runtime
-    automatically falls back when a provider is unavailable.
+export const meta = Plugin.getMetaFromConfig(config);
 
-    Blueprints give every chat a specialised identity. Built-in blueprints cover general assistance,
-    web browsing, database interaction, web search, Discord and Linear integration, autonomous agents,
-    planning, memory, automation, and a wizard for authoring new blueprints. Binding a blueprint
-    changes the system instructions and the tool set exposed to the model in a single step.
-
-    Tool execution runs through the DXOS compute runtime so every AI action — opening a document,
-    searching the web, querying a database — produces a structured execution trace. The optional
-    TracePanel visualises that trace as a commit graph or raw JSON, giving developers full observability
-    into what the model did and why.
-  `,
-  icon: 'ph--sparkle--regular',
-  iconHue: 'sky',
-  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-assistant',
-  spec: 'PLUGIN.mdl',
-});
-
-export const ASSISTANT_DIALOG = DXN.make(`${meta.id}.assistantDialog`);
+export const ASSISTANT_DIALOG = DXN.make(`${meta.profile.key}.assistantDialog`);
 
 /** Companion variant identifier for the assistant chat panel. */
 export const ASSISTANT_COMPANION_VARIANT = 'assistant-chat';

package/src/operations/create-chat.ts

@@ -33,7 +33,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.CreateChat> = Ass
       // Dynamic import to avoid circular dependency with the barrel that also exports BlueprintManagerHandlers.
       const { BlueprintManagerBlueprint } = yield* Effect.promise(() => import('@dxos/assistant-toolkit'));
 
-      const feedServiceLayer = createFeedServiceLayer(space.queues);
+      const feedServiceLayer = createFeedServiceLayer(space.db);
       const runtime = yield* Effect.runtime<Feed.FeedService>().pipe(Effect.provide(feedServiceLayer));
       const binder = new AiContext.Binder({ feed, runtime, registry });
 

package/src/operations/fork-chat.ts

@@ -5,7 +5,7 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { getObjectPathFromObject, LayoutOperation } from '@dxos/app-toolkit';
+import { Paths, LayoutOperation } from '@dxos/app-toolkit';
 import { AiContext, SessionLink } from '@dxos/assistant';
 import { Chat } from '@dxos/assistant-toolkit';
 import { Operation } from '@dxos/compute';
@@ -29,7 +29,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.ForkChat> = Assis
       const space = client.spaces.get(db.spaceId);
       invariant(space, 'Space not found.');
 
-      const feedServiceLayer = createFeedServiceLayer(space.queues);
+      const feedServiceLayer = createFeedServiceLayer(space.db);
 
       const messages = yield* Feed.runQuery(sourceFeed, Filter.type(Message.Message)).pipe(
         Effect.provide(feedServiceLayer),
@@ -100,7 +100,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.ForkChat> = Assis
         );
       } else {
         // Navigate to the forked chat as a standalone plank.
-        const chatPath = getObjectPathFromObject(newChat);
+        const chatPath = Paths.getObjectPathFromObject(newChat);
         yield* Operation.invoke(LayoutOperation.Open, { subject: [chatPath] });
       }
 

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

@@ -5,7 +5,7 @@
 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';
@@ -18,6 +18,8 @@ import { Text } from '@dxos/schema';
 
 import { AssistantCapabilities, AssistantOperation } from '#types';
 
+import { getChatPath } from '../paths';
+
 const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInNewChat> =
   AssistantOperation.RunPromptInNewChat.pipe(
     Operation.withHandler(
@@ -32,7 +34,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.RunPromptInNewCha
             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 feedServiceLayer = createFeedServiceLayer(space.db);
             const runtime = yield* Effect.runtime<Feed.FeedService>().pipe(Effect.provide(feedServiceLayer));
             const binder = new AiContext.Binder({ feed: feedTarget, runtime, registry });
             yield* Effect.promise(() =>
@@ -88,7 +90,7 @@ 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

package/src/paths.ts

@@ -2,9 +2,9 @@
 // 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);
 
 export { getChatsPath, getChatPath };

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] });
 
@@ -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.');
+  });
+});

package/src/processor/processor.ts

@@ -26,6 +26,7 @@ import {
 import { type Chat } from '@dxos/assistant-toolkit';
 import { type Credential, Operation, type ServiceNotAvailableError, Trace } from '@dxos/compute';
 import { type Database, Feed, Obj, Ref, type Registry } from '@dxos/echo';
+import { UsageQuotaExceededError } from '@dxos/edge-client';
 import { EffectEx } from '@dxos/effect';
 import { AgentService } from '@dxos/functions-runtime';
 import { log } from '@dxos/log';
@@ -33,6 +34,8 @@ import { Message } from '@dxos/types';
 
 import { AssistantOperation } from '#types';
 
+import { findInCause } from '../util/error-cause';
+
 /**
  * @deprecated Services type for the old direct-conversation processor path.
  * Retained for backward compatibility with CLI and update-name.
@@ -80,14 +83,57 @@ export type ProcessorRequest = {
   options?: ProcessorRequestOptions;
 };
 
+/** User-facing message shown when an AI request is rejected for exceeding the account usage quota (HTTP 429). */
+const QUOTA_EXCEEDED_MESSAGE = 'You have reached your AI usage limit for this period.';
+
+/** An actionable next-step a chat error surfaces in its toast; the label key is resolved by the chat UI. */
+export type ChatErrorAction = { readonly labelKey: string };
+
+/**
+ * Display error for an over-quota (HTTP 429) rejection. Declares an {@link action} so the chat toast can
+ * offer a usage-dashboard link declaratively — the UI renders whatever action an error declares rather
+ * than branching on the error type.
+ */
+export class AiUsageQuotaError extends Error {
+  readonly action: ChatErrorAction = { labelKey: 'view-usage.label' };
+}
+
+/**
+ * Matches an over-quota rejection (EDGE responds 429) in error text. The typed
+ * {@link UsageQuotaExceededError} is wrapped deep in the cause chain and does not survive the
+ * agent-process boundary — the failure is rendered to a string via `Cause.pretty`, which drops
+ * nested causes — so detection also relies on the HTTP 429 that `@effect/ai`'s
+ * {@link AiError.HttpResponseError} embeds in its message (e.g. "... (429 POST ...)").
+ */
+const QUOTA_PATTERN = /\b429\b|rate.?limit|too many requests|usage quota|quota exceeded/i;
+
+/** Whether an error denotes an over-quota (HTTP 429) rejection, detected by typed status or message text. */
+const isQuotaError = (err: unknown): boolean => {
+  if (AiError.isAiError(err)) {
+    if (err._tag === 'HttpResponseError' && err.response.status === 429) {
+      return true;
+    }
+    return QUOTA_PATTERN.test(err.description ?? err.message);
+  }
+  return typeof err === 'string' && QUOTA_PATTERN.test(err);
+};
+
 /**
  * Maps a failure from the agent fiber to an error suitable for display.
- * {@link AiError}s originate from the AI service and are actionable by the user
+ * An over-quota (HTTP 429) rejection is surfaced as an actionable usage-limit message; the typed
+ * {@link UsageQuotaExceededError} only survives on the direct path, so {@link isQuotaError} also
+ * recognizes the stringified 429 the chat receives across the agent-process boundary.
+ * Other {@link AiError}s originate from the AI service and are actionable by the user
  * (e.g., "model 'x' not found", "Connection refused"), so their detail is propagated.
  * Any other failure is treated as an internal/unexpected error and reported generically
  * to avoid leaking implementation detail.
  */
-const parseError = (err: unknown): Error => {
+export const parseError = (err: unknown): Error => {
+  const quotaError = findInCause(err, UsageQuotaExceededError.is);
+  if (quotaError || isQuotaError(err)) {
+    return new AiUsageQuotaError(quotaError?.message?.trim() || QUOTA_EXCEEDED_MESSAGE, { cause: err });
+  }
+
   let message: string | undefined;
   if (AiError.isAiError(err)) {
     message = err.description?.trim() || err.message;
@@ -263,6 +309,7 @@ export class AiChatProcessor {
       const exit = await this._runtime.runPromise(Fiber.await(this.#requestFiber));
       if (Exit.isFailure(exit)) {
         if (Cause.isInterruptedOnly(exit.cause)) {
+          this.#discardStreaming();
           return;
         }
 
@@ -300,6 +347,7 @@ export class AiChatProcessor {
     );
 
     this.#requestFiber = undefined;
+    this.#discardStreaming();
     this.#registry.set(this.active, false);
   }
 
@@ -390,6 +438,14 @@ export class AiChatProcessor {
     });
   }
 
+  /**
+   * Drop in-flight streaming messages (cancel/interrupt — partial blocks are discarded).
+   */
+  #discardStreaming() {
+    this.#registry.set(this.#streaming, []);
+    this.#finalizedIds.clear();
+  }
+
   /**
    * Move remaining streaming messages to pending (called when agent completes).
    */