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

package/src/AssistantPlugin.test.ts

@@ -0,0 +1,213 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import { type TestContext } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { AiService } from '@dxos/ai';
+import { TestAiService } from '@dxos/ai/testing';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+import {
+  AgentPrompt,
+  AgentWizardBlueprint,
+  BlueprintManagerBlueprint,
+  DatabaseBlueprint,
+} from '@dxos/assistant-toolkit';
+import { Blueprint, Operation, Routine, ServiceResolver } from '@dxos/compute';
+import { Database, Feed, Ref, Registry } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { TestContextService } from '@dxos/effect/testing';
+import { AgentService } from '@dxos/functions-runtime';
+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 { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { AssistantPlugin } from '#plugin';
+
+import { AssistantBlueprint } from './blueprints/assistant';
+import { meta } from './meta';
+
+EntityId.dangerouslyDisableRandomness();
+
+const moduleId = (name: string) => `${meta.id}.module.${name}`;
+
+describe('AssistantPlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [ClientPlugin({}), AssistantPlugin()],
+    });
+
+    // After autoStart: AppGraphBuilder, CreateObject, schema, OperationHandler all auto-cascade.
+    expect(harness.manager.getActive()).toEqual(
+      expect.arrayContaining([moduleId('AppGraphBuilder'), moduleId('CreateObject'), moduleId('schema')]),
+    );
+
+    // AssistantPlugin fires SetupArtifactDefinition itself, so it can test its own blueprint.
+    await harness.fire(AppActivationEvents.SetupArtifactDefinition);
+    expect(harness.manager.getActive()).toContain(moduleId('BlueprintDefinition'));
+
+    // OperationHandler auto-cascades from ProcessManagerPlugin.
+    expect(harness.manager.getActive()).toContain(moduleId('OperationHandler'));
+
+    // Process-manager layer specs must activate on SetupProcessManager.
+    expect(harness.manager.getActive()).toContain(moduleId('AiService'));
+    expect(harness.manager.getActive()).toContain(moduleId('AiContext'));
+    expect(harness.manager.getActive()).toContain(moduleId('AgentRuntime'));
+
+    // Space-affinity LayerSpec — resolution requires a space context.
+    const { personalSpace } = await EffectEx.runAndForwardErrors(
+      initializeIdentity(harness.get(ClientCapabilities.Client)),
+    );
+    await harness.runPromise(
+      Effect.gen(function* () {
+        const aiService = yield* AiService.AiService;
+        expect(aiService).toBeDefined();
+      }).pipe(Effect.provide(ServiceResolver.provide({ space: personalSpace.id }, AiService.AiService))),
+    );
+  });
+
+  test('can memoize ai-service requests', async (ctx) => {
+    const { expect } = ctx;
+    await using harness = await createComposerTestApp({
+      plugins: [
+        ClientPlugin({}),
+        AssistantPlugin({
+          aiServiceMiddleware: await makeMemoizedAiServiceMiddleware(ctx),
+        }),
+      ],
+    });
+
+    const { personalSpace } = await EffectEx.runAndForwardErrors(
+      initializeIdentity(harness.get(ClientCapabilities.Client)),
+    );
+    await harness.runPromise(
+      Effect.gen(function* () {
+        const { text } = yield* LanguageModel.generateText({
+          prompt: 'What is the capital of France?',
+        });
+        expect(text.toLocaleLowerCase()).toContain('paris');
+      }).pipe(
+        Effect.provide(
+          AiService.model('ai.claude.model.claude-haiku-4-5').pipe(
+            Layer.provideMerge(ServiceResolver.provide({ space: personalSpace.id }, AiService.AiService)),
+          ),
+        ),
+      ),
+    );
+  });
+
+  test('can run memoized routine', { timeout: 120_000 }, async (ctx) => {
+    const { expect } = ctx;
+    await using harness = await createComposerTestApp({
+      plugins: [
+        ClientPlugin({}),
+        AssistantPlugin({
+          aiServiceMiddleware: await makeMemoizedAiServiceMiddleware(ctx),
+        }),
+        AutomationPlugin(),
+      ],
+    });
+
+    await harness.fire(AppActivationEvents.SetupArtifactDefinition);
+
+    const { personalSpace } = await EffectEx.runAndForwardErrors(
+      initializeIdentity(harness.get(ClientCapabilities.Client)),
+    );
+
+    await harness.runPromise(
+      Effect.gen(function* () {
+        const routine = yield* Database.add(
+          Routine.make({
+            name: 'capital-test',
+            instructions:
+              'Call completeJob with success set to a JSON object { "capital": "<lowercase country capital>" } for the country in input.',
+            input: Schema.Struct({
+              country: Schema.String,
+            }),
+            output: Schema.Struct({
+              capital: Schema.String,
+            }),
+          }),
+        );
+        yield* Database.flush();
+
+        const result = yield* Operation.invoke(
+          AgentPrompt,
+          {
+            prompt: Ref.make(routine),
+            input: {
+              country: 'France',
+            },
+            model: 'ai.claude.model.claude-haiku-4-5',
+          },
+          { spaceId: personalSpace.id },
+        );
+        expect(result).toEqual({ capital: 'paris' });
+      }).pipe(Effect.provide(ServiceResolver.provide({ space: personalSpace.id }, Database.Service, Feed.FeedService))),
+    );
+  });
+
+  test('smoke test for agent service with standard blueprints', { timeout: 120_000 }, async (ctx) => {
+    const { expect } = ctx;
+    await using harness = await createComposerTestApp({
+      plugins: [
+        ClientPlugin({}),
+        AssistantPlugin({
+          aiServiceMiddleware: await makeMemoizedAiServiceMiddleware(ctx),
+        }),
+        AutomationPlugin(),
+      ],
+    });
+
+    await harness.fire(AppActivationEvents.SetupArtifactDefinition);
+
+    const { personalSpace } = await initializeIdentity(harness.get(ClientCapabilities.Client)).pipe(
+      EffectEx.runAndForwardErrors,
+    );
+
+    await harness.runPromise(
+      Effect.gen(function* () {
+        const blueprints = yield* Effect.forEach(
+          [DatabaseBlueprint, AssistantBlueprint, BlueprintManagerBlueprint, AgentWizardBlueprint],
+          (_) => Blueprint.resolve(_.key),
+        );
+
+        const agent = yield* AgentService.createSession({
+          blueprints,
+        });
+        yield* agent.submitPrompt('Hello');
+        yield* agent.waitForCompletion();
+      }).pipe(
+        Effect.provide(
+          ServiceResolver.provide(
+            { space: personalSpace.id },
+            Database.Service,
+            Feed.FeedService,
+            AgentService.AgentService,
+            Registry.Service,
+          ),
+        ),
+      ),
+    );
+  });
+});
+
+const makeMemoizedAiServiceMiddleware = (
+  ctx: TestContext,
+): Promise<(_upstream: AiService.Service) => AiService.Service> =>
+  AiService.AiService.pipe(
+    Effect.provide(
+      TestAiService({ preset: 'direct' }).pipe(Layer.provideMerge(Layer.succeed(TestContextService, ctx))),
+    ),
+    // Ignoring actual AI service the plugin contructs and using our own.
+    Effect.map((service) => (_upstream: AiService.Service) => service),
+    Effect.runPromise,
+  );

package/src/AssistantPlugin.ts

@@ -0,0 +1,158 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { ActivationEvent, ActivationEvents, Capability, Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { AiContext } from '@dxos/assistant';
+import { Agent, Chat, McpServer, Memory, Plan } from '@dxos/assistant-toolkit';
+import { Blueprint, Routine } from '@dxos/compute';
+import { Sequence } from '@dxos/conductor';
+import { Feed } from '@dxos/echo';
+import { ClientEvents } from '@dxos/plugin-client';
+import { DeckEvents } from '@dxos/plugin-deck';
+import { MarkdownEvents } from '@dxos/plugin-markdown';
+import { Text } from '@dxos/schema';
+import { HasSubject, Message } from '@dxos/types';
+
+import {
+  AgentHydrator,
+  AgentRuntime,
+  AiContext as AiContextCapability,
+  AiService,
+  IntegrationProvider,
+  AppGraphBuilder,
+  AutomationTemplates,
+  AssistantState,
+  BlueprintDefinition,
+  CompanionChatProvisioner,
+  CreateObject,
+  EdgeModelResolver,
+  LocalModelResolver,
+  MarkdownExtension,
+  Migrations,
+  OperationHandler,
+  ReactSurface,
+  Settings,
+  Toolkit,
+} from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { AssistantEvents, type AssistantPluginOptions } from '#types';
+
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../PLUGIN.mdl?raw';
+
+const StateReady = AppActivationEvents.createStateEvent(meta.id);
+
+export const AssistantPlugin = Plugin.define<AssistantPluginOptions | void>(meta)
+  .pipe(
+    AppPlugin.addAppGraphModule({ activate: AppGraphBuilder }),
+    AppPlugin.addBlueprintDefinitionModule({ activate: BlueprintDefinition }),
+    AppPlugin.addCreateObjectModule({ activate: CreateObject }),
+    AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+    AppPlugin.addSchemaModule({
+      schema: [
+        Chat.Chat,
+        Chat.CompanionTo,
+        Blueprint.Blueprint,
+        AiContext.Binding,
+        Feed.Feed,
+        HasSubject.HasSubject,
+        Message.Message,
+        Routine.Routine,
+        Agent.Agent,
+        McpServer.McpServer,
+        Plan.Plan,
+        Sequence.Sequence,
+        Memory.Memory,
+        Text.Text,
+      ],
+    }),
+    AppPlugin.addSettingsModule({ activate: Settings }),
+    AppPlugin.addSurfaceModule({
+      activate: ReactSurface,
+      firesBeforeActivation: [AppActivationEvents.SetupArtifactDefinition],
+    }),
+    AppPlugin.addTranslationsModule({ translations }),
+    Plugin.addModule({
+      id: 'automation-templates',
+      activatesOn: AppActivationEvents.SetupSchema,
+      activate: AutomationTemplates,
+    }),
+    Plugin.addModule({
+      id: 'markdown',
+      activatesOn: MarkdownEvents.SetupExtensions,
+      activate: MarkdownExtension,
+    }),
+    Plugin.addModule({
+      // TODO(wittjosiah): Does not integrate with settings store.
+      //   Should this be a different event?
+      //   Should settings store be renamed to be more generic?
+      activatesOn: AppActivationEvents.SetupSettings,
+      firesAfterActivation: [StateReady],
+      activate: AssistantState,
+    }),
+    Plugin.addModule({
+      activatesOn: AssistantEvents.SetupAiServiceProviders,
+      activate: EdgeModelResolver,
+    }),
+    Plugin.addModule({
+      activatesOn: AssistantEvents.SetupAiServiceProviders,
+      activate: LocalModelResolver,
+    }),
+    Plugin.addModule((options) => ({
+      id: Capability.getModuleTag(AiService),
+      firesBeforeActivation: [AssistantEvents.SetupAiServiceProviders],
+      // TODO(dmaretskyi): This should activate lazily when the AI chat is used.
+      activatesOn: ActivationEvents.SetupProcessManager,
+      activate: () => AiService(options),
+    })),
+    Plugin.addModule({
+      // Process-affinity `AiContext.Service` LayerSpec — needed so operations
+      // dispatched as their own processes (e.g. via `Operation.invoke` from
+      // `AiSession.createRequest` or `TriggerDispatcher`) can resolve
+      // conversation-scoped services without an inline `Effect.provideService`
+      // upstream. See `capabilities/ai-context.ts` for the rationale.
+      activatesOn: ActivationEvents.SetupProcessManager,
+      activate: AiContextCapability,
+    }),
+    Plugin.addModule({
+      activatesOn: ActivationEvents.SetupProcessManager,
+      activate: AgentRuntime,
+    }),
+  )
+  .pipe(
+    Plugin.addModule({
+      // TODO(wittjosiah): Use a different event.
+      activatesOn: ActivationEvents.Startup,
+      activate: Toolkit,
+    }),
+    Plugin.addModule({
+      activatesOn: ActivationEvents.ProcessManagerReady,
+      activate: AgentHydrator,
+    }),
+    Plugin.addModule({
+      activatesOn: ActivationEvent.allOf(
+        ActivationEvents.ProcessManagerReady,
+        AppActivationEvents.AppGraphReady,
+        DeckEvents.StateReady,
+        StateReady,
+      ),
+      activate: CompanionChatProvisioner,
+    }),
+    Plugin.addModule({
+      activatesOn: ClientEvents.SetupMigration,
+      activate: Migrations,
+    }),
+    Plugin.addModule({
+      activatesOn: AppActivationEvents.SetupIntegrationProviders,
+      activate: IntegrationProvider,
+    }),
+    AppPlugin.addPluginAssetModule({
+      asset: { pluginId: meta.id, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+    }),
+    Plugin.make,
+  );
+
+export default AssistantPlugin;

package/src/AssistantPlugin.workerd.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { AiContext } from '@dxos/assistant';
+import { Agent, Chat, McpServer, Memory, Plan } from '@dxos/assistant-toolkit';
+import { Blueprint, Routine } from '@dxos/compute';
+import { Sequence } from '@dxos/conductor';
+import { Feed } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { HasSubject, Message } from '@dxos/types';
+
+import { OperationHandler } from '#capabilities';
+import { meta } from '#meta';
+
+export const AssistantPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({
+    schema: [
+      Chat.Chat,
+      Chat.CompanionTo,
+      Blueprint.Blueprint,
+      AiContext.Binding,
+      Feed.Feed,
+      HasSubject.HasSubject,
+      Message.Message,
+      Routine.Routine,
+      Agent.Agent,
+      McpServer.McpServer,
+      Plan.Plan,
+      Sequence.Sequence,
+      Memory.Memory,
+      Text.Text,
+    ],
+  }),
+  Plugin.make,
+);
+
+export default AssistantPlugin;

package/src/blueprints/assistant/blueprint.node.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 { 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';
+
+import AssistantBlueprint from './blueprint';
+
+EntityId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  operationHandlers: DatabaseHandlers,
+  types: [Organization.Organization, Blueprint.Blueprint, Feed.Feed],
+  blueprints: [AssistantBlueprint.make(), DatabaseBlueprint.make()],
+  tracing: 'pretty',
+});
+
+describe('Assistant Blueprint', () => {
+  // TODO(dmaretskyi): Regenerate memoized conversation with ALLOW_LLM_GENERATION=1.
+  it.effect.skip(
+    'works with Database blueprint to create objects',
+    Effect.fnUntraced(
+      function* (_) {
+        const agent = yield* AgentService.createSession({
+          blueprints: [AssistantBlueprint.make(), DatabaseBlueprint.make()],
+        });
+        yield* agent.submitPrompt('Create a new organization called "Test Corp".');
+        yield* agent.waitForCompletion();
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+});

package/src/blueprints/assistant/blueprint.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { templates } from '@dxos/assistant';
+import { Blueprint } from '@dxos/compute';
+
+import { AssistantOperation } from '#types';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.assistant';
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Assistant',
+    tools: Blueprint.toolDefinitions({
+      // TODO(wittjosiah): LayoutOperation.Open requires Capability.Service which is only available
+      //   via the compute-runtime layer (plugin-automation). 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,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/assistant/index.ts

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

package/src/{components/Timeline → blueprints}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './Timeline';
+export * from './assistant';

package/src/capabilities/agent-hydrator.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { ServiceResolver } from '@dxos/compute';
+import { AgentService } from '@dxos/functions-runtime';
+import { log } from '@dxos/log';
+
+//
+// Capability Module
+//
+// Rehydrates durable agent processes once {@link ActivationEvents.ProcessManagerReady} fires.
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const runtime = yield* Capability.get(Capabilities.ProcessManagerRuntime);
+
+    runtime.runFork(
+      Effect.gen(function* () {
+        const service = yield* AgentService.AgentService;
+        yield* service.hydrate();
+      }).pipe(
+        Effect.provide(ServiceResolver.provide({}, AgentService.AgentService)),
+        Effect.catchAllCause((cause) =>
+          Effect.sync(() => log.warn('agent hydrate failed', { cause: Cause.pretty(cause) })),
+        ),
+      ),
+    );
+
+    return Capability.contributes(Capabilities.Null, null);
+  }),
+);

package/src/capabilities/agent-service.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayerSpec } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { AgentService } from '@dxos/functions-runtime';
+import { AutomationCapabilities } from '@dxos/plugin-automation';
+
+//
+// Capability Module
+//
+// Owns the application-affinity {@link AgentService} layer for process-backed agents.
+//
+
+const AgentServiceSpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [ProcessManager.ProcessManagerService, Capability.Service],
+    provides: [AgentService.AgentService],
+  },
+  () =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        // Optional supervisor behaviour, contributed by a plugin that knows the agent/plan model.
+        const strategies = yield* Capability.getAll(AutomationCapabilities.AgentDelegationStrategy);
+        return AgentService.layer({ delegationStrategy: strategies[0] });
+      }),
+    ),
+);
+
+export default Capability.makeModule(() =>
+  Effect.succeed([Capability.contributes(Capabilities.LayerSpec, AgentServiceSpec)]),
+);

package/src/capabilities/ai-context.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AiContext } from '@dxos/assistant';
+import { LayerSpec, ServiceNotAvailableError } from '@dxos/compute';
+import { Database, EID, Feed } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+
+//
+// Capability Module
+//
+// Contributes a process-affinity `LayerSpec` that materialises
+// {@link AiContext.Service} from the resolution context's `conversation` DXN.
+//
+
+const AiContextSpec = LayerSpec.make(
+  {
+    affinity: 'process',
+    requires: [Database.Service, Feed.FeedService],
+    provides: [AiContext.Service],
+  },
+  (context) =>
+    Layer.scoped(
+      AiContext.Service,
+      Effect.gen(function* () {
+        if (!context.conversation) {
+          return yield* Effect.die(
+            new ServiceNotAvailableError(AiContext.Service.key, {
+              message: `Service not available: ${AiContext.Service.key} — process spawn is missing 'conversation' in environment (set via Operation.withInvocationOptions or ProcessManager.spawn environment)`,
+            }),
+          );
+        }
+        const feed = yield* Database.resolve(EID.parse(context.conversation), Feed.Feed).pipe(Effect.orDie);
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const binder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+        return { binder };
+      }),
+    ),
+);
+
+export default Capability.makeModule(() =>
+  Effect.succeed([Capability.contributes(Capabilities.LayerSpec, AiContextSpec)]),
+);