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

package/src/processor/processor.ts

@@ -12,27 +12,31 @@ import * as Layer from 'effect/Layer';
 import * as Option from 'effect/Option';
 import * as Stream from 'effect/Stream';
 
-import { type AiService, DEFAULT_EDGE_MODEL, type ModelName, type ModelRegistry, type OpaqueToolkit } from '@dxos/ai';
+import { type AiService, Model, type OpaqueToolkit } from '@dxos/ai';
 import { Capabilities } from '@dxos/app-framework';
 import {
   AiContext,
   AiSession,
-  createSystemPrompt,
-  formatSystemPrompt,
+  Harness,
   McpServerError,
   PartialBlock,
   ToolExecutionServices,
+  createSystemPrompt,
+  formatSystemPrompt,
 } from '@dxos/assistant';
 import { type Chat } from '@dxos/assistant-toolkit';
-import { type Credential, Operation, type ServiceNotAvailableError, Trace } from '@dxos/compute';
+import { AgentService, 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 { DXN } from '@dxos/keys';
 import { log } from '@dxos/log';
 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.
@@ -50,7 +54,6 @@ export type AiChatServices =
  */
 export type SpaceServices =
   | Database.Service
-  | Feed.FeedService
   | Credential.CredentialsService
   | AiService.AiService
   | AgentService.AgentService
@@ -58,8 +61,11 @@ export type SpaceServices =
   | OpaqueToolkit.OpaqueToolkitProvider;
 
 export type AiChatProcessorOptions = {
-  model?: ModelName;
-  modelRegistry?: ModelRegistry;
+  model?: DXN.DXN;
+  // The selected provider, carried with the model so the agent process resolves the (provider, id)
+  // pair — the catalog's shared model ids are ambiguous without it.
+  provider?: DXN.DXN;
+  modelRegistry?: Model.Registry;
   registry?: Registry.Registry;
   observableRegistry?: AtomRegistry.Registry;
   /**
@@ -70,7 +76,7 @@ export type AiChatProcessorOptions = {
 };
 
 const defaultOptions: Partial<AiChatProcessorOptions> = {
-  model: DEFAULT_EDGE_MODEL,
+  model: Model.DEFAULT_EDGE,
 };
 
 export type ProcessorRequestOptions = {};
@@ -80,14 +86,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;
@@ -170,7 +219,7 @@ export class AiChatProcessor {
     }
   }
 
-  get context() {
+  get context(): AiContext.Binder {
     return this._conversation.context;
   }
 
@@ -195,14 +244,18 @@ export class AiChatProcessor {
   async getSystemPrompt(): Promise<string> {
     return this._runtime.runPromise(
       Effect.gen(this, function* () {
-        const blueprints = this.context.getBlueprints();
+        const skills = this.context.getSkills();
         const objects = this.context.getObjects();
-        return yield* formatSystemPrompt({ system: this._options.system, blueprints, objects });
-      }).pipe(
-        Effect.provideService(AiContext.Service, { binder: this.context }),
-        Effect.provide(this._spaceLayer),
-        Effect.orDie,
-      ),
+        // 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(
+          Effect.provideService(
+            Harness.HarnessService,
+            Harness.fromBinder({ feed: this._feed, runtime, binder: this.context }),
+          ),
+        );
+      }).pipe(Effect.provide(this._spaceLayer), Effect.orDie),
     );
   }
 
@@ -222,8 +275,15 @@ export class AiChatProcessor {
 
       const effect = Effect.gen(this, function* () {
         // NOTE: Gets or creates a session for the feed.
-        log.info('init agent session', { feed: Obj.getURI(this._feed), model: this._options.model });
-        const session = yield* AgentService.getSession(this._feed, { model: this._options.model });
+        log.info('init agent session', {
+          feed: Obj.getURI(this._feed),
+          model: this._options.model,
+          provider: this._options.provider,
+        });
+        const session = yield* AgentService.getSession(this._feed, {
+          model: this._options.model,
+          provider: this._options.provider,
+        });
         const ephemeralStream = session.subscribeEphemeral();
         yield* ephemeralStream.pipe(
           Stream.runForEach((message) =>
@@ -263,6 +323,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 +361,7 @@ export class AiChatProcessor {
     );
 
     this.#requestFiber = undefined;
+    this.#discardStreaming();
     this.#registry.set(this.active, false);
   }
 
@@ -390,6 +452,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).
    */

package/src/skills/assistant/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as AssistantSkill } from './skill';

package/src/{blueprints/assistant/blueprint.node.test.ts → skills/assistant/skill.node.test.ts}

@@ -5,8 +5,8 @@
 import { describe, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
-import { DatabaseBlueprint, DatabaseHandlers } from '@dxos/assistant-toolkit';
-import { Blueprint } from '@dxos/compute';
+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';
@@ -14,26 +14,26 @@ import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 import { EntityId } from '@dxos/keys';
 import { Organization } from '@dxos/types';
 
-import AssistantBlueprint from './blueprint';
+import AssistantSkill from './skill';
 
 EntityId.dangerouslyDisableRandomness();
 
 const TestLayer = AssistantTestLayer({
   aiServicePreset: 'edge-remote',
   operationHandlers: DatabaseHandlers,
-  types: [Organization.Organization, Blueprint.Blueprint, Feed.Feed],
-  blueprints: [AssistantBlueprint.make(), DatabaseBlueprint.make()],
+  types: [Organization.Organization, Skill.Skill, Feed.Feed],
+  skills: [AssistantSkill.make(), DatabaseSkill.make()],
   tracing: 'pretty',
 });
 
-describe('Assistant Blueprint', () => {
+describe('Assistant Skill', () => {
   // TODO(dmaretskyi): Regenerate memoized conversation with ALLOW_LLM_GENERATION=1.
   it.effect.skip(
-    'works with Database blueprint to create objects',
+    'works with Database skill to create objects',
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [AssistantBlueprint.make(), DatabaseBlueprint.make()],
+          skills: [AssistantSkill.make(), DatabaseSkill.make()],
         });
         yield* agent.submitPrompt('Create a new organization called "Test Corp".');
         yield* agent.waitForCompletion();

package/src/{blueprints/assistant/blueprint.ts → skills/assistant/skill.ts}

@@ -4,28 +4,28 @@
 
 import { LayoutOperation } from '@dxos/app-toolkit';
 import { templates } from '@dxos/assistant';
-import { Blueprint } from '@dxos/compute';
+import { Skill } from '@dxos/compute';
 
 import { AssistantOperation } from '#types';
 
-const BLUEPRINT_KEY = 'org.dxos.blueprint.assistant';
+const SKILL_KEY = 'org.dxos.skill.assistant';
 
 const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
+  Skill.make({
+    key: SKILL_KEY,
     name: 'Assistant',
-    tools: Blueprint.toolDefinitions({
+    tools: Skill.toolDefinitions({
       // TODO(wittjosiah): LayoutOperation.Open requires Capability.Service which is only available
-      //   via the compute-runtime layer (plugin-automation). Once Capability.Service is propagated
+      //   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],
     }),
     instructions: templates.system,
   });
 
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
   make,
 };
 
-export default blueprint;
+export default skill;

package/src/templates/daily-digest.ts

@@ -2,16 +2,12 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type AutomationCapabilities } from '@dxos/plugin-automation';
+import { type RoutineCapabilities } from '@dxos/plugin-routine';
 
-import { makeScheduledRoutineAutomation } from './scaffold';
+import { makeScheduledRoutine } from './scaffold';
 
 /** Inbox supplies new messages; database queries recent objects; markdown writes the digest document. */
-const BLUEPRINT_KEYS = [
-  'org.dxos.blueprint.inbox',
-  'org.dxos.blueprint.database',
-  'org.dxos.blueprint.markdown',
-] as const;
+const SKILL_KEYS = ['org.dxos.skill.inbox', 'org.dxos.skill.database', 'org.dxos.skill.markdown'] as const;
 
 /** Runs daily by default; the user edits the schedule and the scope by opening the trigger and routine. */
 const DEFAULT_CRON = '0 9 * * *';
@@ -23,15 +19,17 @@ Review new messages in the inbox and recently changed objects. Produce a short d
 highlight anything that needs attention, and write it to a markdown document titled with the current date.
 `;
 
-export const dailyDigest: AutomationCapabilities.Template = {
-  id: 'org.dxos.automation.dailyDigest',
+export const dailyDigest: RoutineCapabilities.Template = {
+  id: 'org.dxos.routine.dailyDigest',
   label: 'Daily Digest',
   icon: 'ph--list-bullets--regular',
+  // Scheduled space-level digest — not meaningful for a specific object companion.
+  appliesTo: (subject) => subject == null,
   scaffold: ({ name }) =>
-    makeScheduledRoutineAutomation({
+    makeScheduledRoutine({
       name: name ?? 'Daily Digest',
-      instructions: DEFAULT_INSTRUCTIONS,
-      blueprintKeys: BLUEPRINT_KEYS,
+      text: DEFAULT_INSTRUCTIONS,
+      skillKeys: SKILL_KEYS,
       cron: DEFAULT_CRON,
     }),
 };

package/src/templates/index.ts

@@ -2,10 +2,10 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type AutomationCapabilities } from '@dxos/plugin-automation';
+import { type RoutineCapabilities } from '@dxos/plugin-routine';
 
 import { dailyDigest } from './daily-digest';
 import { researchBrief } from './research-brief';
 
-/** Generic, subject-less automation templates contributed alongside plugin-automation's Blank. */
-export const automationTemplates: AutomationCapabilities.Template[] = [researchBrief, dailyDigest];
+/** Generic, subject-less routine templates contributed alongside plugin-routine's Blank. */
+export const routineTemplates: RoutineCapabilities.Template[] = [researchBrief, dailyDigest];

package/src/templates/research-brief.ts

@@ -2,16 +2,16 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type AutomationCapabilities } from '@dxos/plugin-automation';
+import { type RoutineCapabilities } from '@dxos/plugin-routine';
 
-import { makeScheduledRoutineAutomation } from './scaffold';
+import { makeScheduledRoutine } from './scaffold';
 
-/** The research blueprint drives the brief; web-search, markdown, and database tools support it. */
-const BLUEPRINT_KEYS = [
-  'org.dxos.blueprint.research',
-  'org.dxos.blueprint.webSearch',
-  'org.dxos.blueprint.markdown',
-  'org.dxos.blueprint.database',
+/** The research skill drives the brief; web-search, markdown, and database tools support it. */
+const SKILL_KEYS = [
+  'org.dxos.skill.research',
+  'org.dxos.skill.webSearch',
+  'org.dxos.skill.markdown',
+  'org.dxos.skill.database',
 ] as const;
 
 /** Runs weekly by default; the user edits the schedule and the topic by opening the trigger and routine. */
@@ -26,15 +26,17 @@ Gather current information with the web-search and research tools. Summarize the
 sources you used, and create a markdown document titled with the topic and the current date.
 `;
 
-export const researchBrief: AutomationCapabilities.Template = {
-  id: 'org.dxos.automation.researchBrief',
+export const researchBrief: RoutineCapabilities.Template = {
+  id: 'org.dxos.routine.researchBrief',
   label: 'Research Brief',
   icon: 'ph--newspaper--regular',
+  // Scheduled space-level research — not meaningful for a specific object companion.
+  appliesTo: (subject) => subject == null,
   scaffold: ({ name }) =>
-    makeScheduledRoutineAutomation({
+    makeScheduledRoutine({
       name: name ?? 'Research Brief',
-      instructions: DEFAULT_INSTRUCTIONS,
-      blueprintKeys: BLUEPRINT_KEYS,
+      text: DEFAULT_INSTRUCTIONS,
+      skillKeys: SKILL_KEYS,
       cron: DEFAULT_CRON,
     }),
 };

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

@@ -0,0 +1,55 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { describe, test } from 'vitest';
+
+import { Instructions, 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';
+
+const templates = [
+  { template: researchBrief, skillCount: 4 },
+  { template: dailyDigest, skillCount: 3 },
+];
+
+describe('scheduled routine templates', () => {
+  test('apply only in the global create dialog (no companion subject)', ({ expect }) => {
+    // These templates appear only in the global create dialog, not in object companions.
+    expect(dailyDigest.appliesTo?.(undefined)).toBe(true);
+    expect(researchBrief.appliesTo?.(undefined)).toBe(true);
+    expect(dailyDigest.appliesTo?.({} as Obj.Unknown)).toBe(false);
+    expect(researchBrief.appliesTo?.({} as Obj.Unknown)).toBe(false);
+  });
+
+  for (const { template, skillCount } of templates) {
+    test(`${template.label} scaffolds an in-memory routine draft graph with a disabled timer trigger and instructions`, async ({
+      expect,
+    }) => {
+      // Templates are in-memory (no DB calls); Database.notAvailable surfaces any accidental DB access.
+      const draft = await EffectEx.runPromise(template.scaffold({}).pipe(Effect.provide(Database.notAvailable)));
+
+      // The draft is a routine graph wired for an instructions action (spec → RunInstructions).
+      expect(Obj.instanceOf(Routine.Routine, draft)).toBe(true);
+      expect(draft.spec?.kind).toBe('instructions');
+
+      // Timer trigger, disabled by default, owned by the routine.
+      const trigger = draft.triggers[0]?.target;
+      expect(trigger != null && Obj.instanceOf(Trigger.Trigger, trigger)).toBe(true);
+      expect(trigger?.enabled).toBe(false);
+      expect(trigger?.spec?.kind).toBe('timer');
+
+      // The owned instructions is the routine's action (an instructions action), with the right skill set.
+      const instructions = Routine.instructionsRef(draft)?.target;
+      expect(Obj.instanceOf(Instructions.Instructions, instructions)).toBe(true);
+      expect(Obj.instanceOf(Instructions.Instructions, instructions) ? instructions.skills : []).toHaveLength(
+        skillCount,
+      );
+    });
+  }
+});

package/src/templates/scaffold.ts

@@ -3,72 +3,37 @@
 //
 
 import * as Effect from 'effect/Effect';
-import * as Schema from 'effect/Schema';
 
-import { AgentPrompt } from '@dxos/assistant-toolkit';
-import { Blueprint, Operation, Routine, Trigger } from '@dxos/compute';
-import { Database, Filter, Obj, Ref } from '@dxos/echo';
-import { Automation } from '@dxos/plugin-automation';
-
-/** Registry key of the persisted AgentPrompt ("Run Routine") operation a routine trigger dispatches. */
-const AGENT_PROMPT_KEY = 'org.dxos.function.prompt';
+import { Instructions, Skill, Trigger } from '@dxos/compute';
+import { Ref } from '@dxos/echo';
+import { Routine } from '@dxos/plugin-routine/types';
 
 export type ScheduledRoutineOptions = {
   name: string;
-  instructions: string;
-  blueprintKeys: readonly string[];
+  text: string;
+  skillKeys: readonly string[];
   cron: string;
 };
 
 /**
- * Scaffold a timer-driven automation: a Routine (instructions + blueprints) run by the shared AgentPrompt
- * operation on a cron schedule. The trigger starts disabled so the user can review the schedule and
- * instructions before activating, and is owned by the automation (cascade-deletes with it); the routine
- * stays independent, since it is edited separately and may be reused.
+ * Scaffold a timer-driven routine as an in-memory {@link Routine.Routine} draft graph. The caller's save
+ * flow (the companion's Save button) persists it; nothing is added to the database here, so the function is
+ * always safe to call without DB access.
+ *
+ * The trigger starts disabled so the user can review the schedule and instructions before activating.
  */
-export const makeScheduledRoutineAutomation = ({
+export const makeScheduledRoutine = ({
   name,
-  instructions,
-  blueprintKeys,
+  text,
+  skillKeys,
   cron,
-}: ScheduledRoutineOptions): Effect.Effect<Automation.Automation, Error, Database.Service> =>
-  Effect.gen(function* () {
-    const blueprints = blueprintKeys.map((key) => Ref.fromURI(Blueprint.registryURI(key)));
-    const routine = yield* Database.add(
-      Routine.make({
-        name,
-        instructions,
-        // No per-run input; the task lives in the instructions. Unknown (not Void) so the empty trigger
-        // input still validates.
-        input: Schema.Unknown,
-        output: Schema.Void,
-        blueprints,
-        context: [],
-      }),
-    );
-
-    // The trigger's `function` must reference an in-space PersistentOperation; reuse the space's AgentPrompt
-    // or persist it on first use.
-    const existingFns = yield* Database.query(
-      Filter.and(Filter.type(Operation.PersistentOperation), Filter.key(AGENT_PROMPT_KEY)),
-    ).run;
-    const agentPromptFn = existingFns[0] ?? (yield* Database.add(Operation.serialize(AgentPrompt)));
-
-    const trigger = yield* Database.add(
-      Obj.make(Trigger.Trigger, {
-        enabled: false,
-        function: Ref.make(agentPromptFn),
-        spec: Trigger.specTimer(cron),
-        input: { prompt: Ref.make(routine), input: {} },
-        concurrency: 1,
-      }),
-    );
-
-    const automation = Automation.make({
+}: ScheduledRoutineOptions): Effect.Effect<Routine.Routine, never, never> => {
+  const skills = skillKeys.map((key) => Ref.fromURI(Skill.registryURI(key)));
+  return Effect.succeed(
+    Routine.make({
       name,
-      runnable: Ref.make(agentPromptFn),
-      triggers: [Ref.make(trigger)],
-    });
-    Obj.setParent(trigger, automation);
-    return automation;
-  });
+      instructions: Instructions.make({ name, text, skills }),
+      trigger: Trigger.make({ spec: Trigger.specTimer(cron), enabled: false }),
+    }),
+  );
+};