@dxos/plugin-assistant 0.8.4-main.406dc2a → 0.8.4-main.422d1c7879

package/src/testing/trace-timeline.test.ts

@@ -0,0 +1,246 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AgentService } from '@dxos/assistant';
+import {
+  AgentHandlers,
+  AgentPrompt,
+  DatabaseBlueprint,
+  DatabaseHandlers,
+  WebSearchBlueprint,
+  WebSearchHandlers,
+  WebSearchToolkitOpaque,
+} from '@dxos/assistant-toolkit';
+import { AssistantTestLayerWithTriggers } from '@dxos/assistant/testing';
+import { Blueprint, Prompt } from '@dxos/blueprints';
+import { Database, Feed, Filter, Obj, Query, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { ExampleHandlers, Reply, Trace, Trigger } from '@dxos/functions';
+import { FeedTraceSink, TriggerDispatcher } from '@dxos/functions-runtime';
+import { ObjectId } from '@dxos/keys';
+import { dbg } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+import { renderTimelineAscii } from '@dxos/react-ui-components';
+import { Organization, Person } from '@dxos/types';
+
+import { buildExecutionGraph } from '../containers/TracePanel/execution-graph';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const queryTraceMessages = Effect.gen(function* () {
+  yield* FeedTraceSink.flush();
+  yield* Database.flush();
+  const feed = yield* FeedTraceSink.getOrCreateTraceFeed();
+  return yield* Database.runQuery(Query.select(Filter.type(Trace.Message)).from(feed));
+});
+
+const TestLayer = AssistantTestLayerWithTriggers({
+  types: [Organization.Organization, Person.Person],
+  blueprints: [DatabaseBlueprint.make(), WebSearchBlueprint.make()],
+  operationHandlers: [DatabaseHandlers, AgentHandlers, WebSearchHandlers, ExampleHandlers],
+  toolkits: [WebSearchToolkitOpaque],
+  tracing: 'feed',
+  aiServicePreset: 'edge-remote',
+});
+
+describe('Trace timeline', () => {
+  describe('Agent', () => {
+    it.effect(
+      'create objects via AgentService',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const agent = yield* AgentService.createSession({
+            blueprints: [DatabaseBlueprint.make()],
+          });
+          yield* agent.submitPrompt('Create an organization called "Cyberdyne Systems".');
+          yield* agent.waitForCompletion();
+
+          yield* agent.submitPrompt('Create a person named "John Connor".');
+          yield* agent.waitForCompletion();
+
+          const messages = yield* queryTraceMessages;
+          dbg(messages.flatMap(({ meta, events }) => events.map((event) => ({ ...meta, ...event }))));
+          const { commits, branches } = buildExecutionGraph({ traceMessages: messages });
+          dbg(branches);
+          const graph = renderTimelineAscii(commits, branches);
+          expect(`\n${graph}\n`).toMatchInlineSnapshot(`
+            "
+            ●     [atom] Agent processing request...
+            ├──●  [user] Create an organization called "Cyberdyne Systems".
+            │  ●  [check-circle] list-schemas - Success
+            │  ●  [check-circle] create-object - Success
+            │  ●  [check-circle] add-to-context - Success
+            ◆──╯  [check-circle] Agent completed request
+            ●  │  [atom] Agent processing request...
+            │  ●  [user] Create a person named "John Connor".
+            │  ●  [check-circle] create-object - Success
+            │  ●  [check-circle] add-to-context - Success
+            ◆──╯  [check-circle] Agent completed request
+            "
+          `);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+      { timeout: 120_000 },
+    );
+
+    it.effect(
+      'invoke prompt and query schema',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const agent = yield* AgentService.createSession({
+            blueprints: [DatabaseBlueprint.make()],
+          });
+          yield* Database.add(Obj.make(Organization.Organization, { name: 'Acme Corp' }));
+          yield* Database.add(Obj.make(Organization.Organization, { name: 'Globex Industries' }));
+          yield* agent.submitPrompt('Search for all organizations. How many are there?');
+          yield* agent.waitForCompletion();
+
+          const messages = yield* queryTraceMessages;
+          const { commits, branches } = buildExecutionGraph({ traceMessages: messages });
+          const graph = renderTimelineAscii(commits, branches);
+          expect(`\n${graph}\n`).toMatchInlineSnapshot(`
+            "
+            ●     [atom] Agent processing request...
+            ├──●  [user] Search for all organizations. How many are there?
+            │  ●  [check-circle] list-schemas - Success
+            │  ●  [check-circle] query - Success
+            │  ●  [check-circle] query - Success
+            ◆──╯  [check-circle] Agent completed request
+            "
+          `);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+      { timeout: 120_000 },
+    );
+
+    it.effect(
+      'sequential prompts in a session',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const agent = yield* AgentService.createSession({
+            blueprints: [DatabaseBlueprint.make()],
+          });
+          yield* agent.submitPrompt('List all available schemas. Tell me what typenames are available.');
+          yield* agent.waitForCompletion();
+
+          yield* agent.submitPrompt('Create an organization called "DXOS" and a person named "Alice".');
+          yield* agent.waitForCompletion();
+
+          yield* agent.submitPrompt('Search for all organizations and persons.');
+          yield* agent.waitForCompletion();
+
+          const messages = yield* queryTraceMessages;
+          const { commits, branches } = buildExecutionGraph({ traceMessages: messages });
+          const graph = renderTimelineAscii(commits, branches);
+          expect(`\n${graph}\n`).toMatchInlineSnapshot(`
+            "
+            ●     [atom] Agent processing request...
+            ├──●  [user] List all available schemas. Tell me what typenames are available.
+            │  ●  [check-circle] list-schemas - Success
+            ◆──╯  [check-circle] Agent completed request
+            ●  │  [atom] Agent processing request...
+            │  ●  [user] Create an organization called "DXOS" and a person named "Alice".
+            │  ●  [check-circle] create-object - Success
+            │  ●  [check-circle] create-object - Success
+            ◆──╯  [check-circle] Agent completed request
+            ●  │  [atom] Agent processing request...
+            │  ●  [user] Search for all organizations and persons.
+            │  ●  [check-circle] query - Success
+            │  ●  [check-circle] query - Success
+            ◆──╯  [check-circle] Agent completed request
+            "
+          `);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+      { timeout: 180_000 },
+    );
+  });
+
+  describe('Triggers', () => {
+    it.effect(
+      'prompt trigger',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const feed = yield* Database.add(Feed.make());
+          yield* Feed.append(feed, [
+            Obj.make(Organization.Organization, {
+              name: 'DXOS',
+            }),
+          ]);
+          const prompt = yield* Database.add(
+            Prompt.make({
+              name: 'Research',
+              instructions: 'Research the given topic, or object.',
+              blueprints: [Ref.make(yield* Blueprint.upsert(WebSearchBlueprint.key))],
+            }),
+          );
+          yield* Database.add(
+            Trigger.make({
+              function: Ref.make(Operation.serialize(AgentPrompt)),
+              enabled: true,
+              spec: Trigger.specFeed(feed),
+              input: {
+                prompt: Ref.make(prompt),
+                input: '{{event.item}}',
+              },
+            }),
+          );
+
+          const dispatcher = yield* TriggerDispatcher;
+          yield* dispatcher
+            .invokeScheduledTriggers({ kinds: ['queue'], untilExhausted: true })
+            .pipe(Effect.flatMap(Effect.forEach((result) => result.result)));
+
+          const messages = yield* queryTraceMessages;
+          const { commits, branches } = buildExecutionGraph({ traceMessages: messages });
+          const graph = renderTimelineAscii(commits, branches);
+          expect(`\n${graph}\n`).toMatchInlineSnapshot(`
+            "
+            ●  [check-circle] Agent
+            "
+          `);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+      { timeout: 120_000 },
+    );
+  });
+
+  describe('Operations', () => {
+    it.effect(
+      'operation',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          yield* Operation.invoke(Reply, { data: 'test-1' });
+          yield* Operation.invoke(Reply, { data: 'test-2' });
+          yield* Operation.invoke(Reply, { data: 'test-3' });
+
+          const messages = yield* queryTraceMessages;
+          const { commits, branches } = buildExecutionGraph({ traceMessages: messages });
+          const graph = renderTimelineAscii(commits, branches);
+          expect(`\n${graph}\n`).toMatchInlineSnapshot(`
+            "
+            ●  [check-circle] Reply
+            ●  [check-circle] Reply
+            ●  [check-circle] Reply
+            "
+          `);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+      { timeout: 120_000 },
+    );
+  });
+});

package/src/translations.ts

@@ -2,106 +2,190 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Blueprint } from '@dxos/blueprints';
+import { Chat, Agent, McpServer } from '@dxos/assistant-toolkit';
+import { Blueprint, Prompt } from '@dxos/blueprints';
 import { Sequence } from '@dxos/conductor';
+import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
+import { translations as componentsTranslations } from '@dxos/react-ui-components';
+import { translations as formTranslations } from '@dxos/react-ui-form';
 
-import { meta } from './meta';
-import { Assistant } from './types';
+import { meta } from '#meta';
 
 // TODO(burdon): Standardize translation names.
-export const translations = [
+export const translations: Resource[] = [
+  ...componentsTranslations,
+  ...formTranslations,
   {
     'en-US': {
       // TODO(burdon): From assistant.
       [Blueprint.Blueprint.typename]: {
-        'typename label': 'Blueprint',
-        'typename label_zero': 'Blueprints',
-        'typename label_one': 'Blueprint',
-        'typename label_other': 'Blueprints',
-        'object name placeholder': 'New blueprint',
-        'rename object label': 'Rename blueprint',
-        'delete object label': 'Delete blueprint',
+        'typename.label': 'Blueprint',
+        'typename.label_zero': 'Blueprints',
+        'typename.label_one': 'Blueprint',
+        'typename.label_other': 'Blueprints',
+        'object-name.placeholder': 'New blueprint',
+        'add-object.label': 'Add blueprint',
+        'rename-object.label': 'Rename blueprint',
+        'delete-object.label': 'Delete blueprint',
+        'object-deleted.label': 'Blueprint deleted',
+      },
+      [Type.getTypename(Prompt.Prompt)]: {
+        'typename.label': 'Prompt',
+        'typename.label_zero': 'Prompts',
+        'typename.label_one': 'Prompt',
+        'typename.label_other': 'Prompts',
+        'object-name.placeholder': 'New prompt',
+        'add-object.label': 'Add prompt',
+        'rename-object.label': 'Rename prompt',
+        'delete-object.label': 'Delete prompt',
+        'object-deleted.label': 'Prompt deleted',
       },
       // TODO(burdon): From conductor.
       [Sequence.typename]: {
-        'typename label': 'Sequence',
-        'typename label_zero': 'Sequences',
-        'typename label_one': 'Sequence',
-        'typename label_other': 'Sequences',
-        'object name placeholder': 'New sequence',
-        'rename object label': 'Rename sequence',
-        'delete object label': 'Delete sequence',
+        'typename.label': 'Sequence',
+        'typename.label_zero': 'Sequences',
+        'typename.label_one': 'Sequence',
+        'typename.label_other': 'Sequences',
+        'object-name.placeholder': 'New sequence',
+        'add-object.label': 'Add sequence',
+        'rename-object.label': 'Rename sequence',
+        'delete-object.label': 'Delete sequence',
+        'object-deleted.label': 'Sequence deleted',
+      },
+      [Chat.Chat.typename]: {
+        'typename.label': 'AI Chat',
+        'object-name.placeholder': 'New AI Chat',
+        'add-object.label': 'Add AI chat',
+        'rename-object.label': 'Rename AI Chat',
+        'delete-object.label': 'Delete AI Chat',
+        'object-deleted.label': 'AI Chat deleted',
       },
-      [Assistant.Chat.typename]: {
-        'typename label': 'AI Chat',
-        'object name placeholder': 'New AI Chat',
-        'rename object label': 'Rename AI Chat',
-        'delete object label': 'Delete AI Chat',
+      [McpServer.McpServer.typename]: {
+        'typename.label': 'MCP Server',
+        'typename.label_zero': 'MCP Servers',
+        'typename.label_one': 'MCP Server',
+        'typename.label_other': 'MCP Servers',
+      },
+      [Agent.Agent.typename]: {
+        'typename.label': 'Agent',
+        'typename.label_zero': 'Agents',
+        'typename.label_one': 'Agent',
+        'typename.label_other': 'Agents',
+        'object-name.placeholder': 'New agent',
+        'add-object.label': 'Add agent',
+        'rename-object.label': 'Rename agent',
+        'delete-object.label': 'Delete agent',
+        'object-deleted.label': 'Agent deleted',
       },
       // TODO(burdon): Reconcile with react-ui-chat.
       [meta.id]: {
-        'templates label': 'Templates',
-        'open ambient chat label': 'Open Assistant',
-        'assistant chat label': 'Assistant',
-        'plugin name': 'Assistant',
-        'settings title': 'Assistant settings',
-        'object placeholder': 'New prompt',
-        'create object label': 'Create prompt',
-        'create trigger label': 'Create trigger',
-        'create stack section label': 'Create prompt',
-        'command placeholder': 'Enter slash command...',
-        'template placeholder': 'Enter template...',
-        'value placeholder': 'Enter value...',
-        'prompt rules label': 'Prompt Rules',
-        'typename placeholder': 'Enter typename of objects which this template is for',
-        'description placeholder': 'Enter description of when this template should be used',
-        'select preset template placeholder': 'Select preset',
-        'service registry label': 'Service Registry',
-        'type filter placeholder': 'Type',
-        'any type filter label': 'Any',
-        'no blueprint message': 'No active blueprints',
-        'calling tool label': 'Calling tool...',
-        'calling label': 'Calling',
-        'error label': 'Error',
+        'templates.label': 'Templates',
+        'open-ambient-chat.label': 'Open Assistant',
+        'assistant-chat.label': 'Assistant',
+        'plugin.name': 'Assistant',
+        'settings.title': 'Assistant settings',
+        'object.placeholder': 'New prompt',
+        'create-object.label': 'Create prompt',
+        'create-trigger.label': 'Create trigger',
+        'create-stack-section.label': 'Create prompt',
+        'command.placeholder': 'Enter slash command...',
+        'template.placeholder': 'Enter template...',
+        'value.placeholder': 'Enter value...',
+        'prompt-rules.label': 'Prompt Rules',
+        'typename.placeholder': 'Enter typename of objects which this template is for',
+        'description.placeholder': 'Enter description of when this template should be used',
+        'select-preset-template.placeholder': 'Select preset',
+        'service-registry.label': 'Service Registry',
+        'type-filter.placeholder': 'Type',
+        'any-type-filter.label': 'Any',
+        'no-blueprint.message': 'No active blueprints',
+        'tool-call.label': 'Calling',
+        'tool-result.label': 'Success',
+        'tool-error.label': 'Tool call failed',
+
+        'invocations.label': 'Invocations',
+        'trace.label': 'Trace',
+
+        'assistant-dialog.title': 'Assistant',
+        'open-assistant.label': 'Open assistant',
+        'reset-blueprints.label': 'Reset blueprints',
+
+        'no-results.message': 'No results',
+
+        'cancel.button': 'Cancel',
+        'save.button': 'Save',
+        'new-thread.button': 'New Chat',
+        'rename-thread.button': 'Rename Chat',
+        'chat-history.label': 'Chat History',
+        'chat-update-name.label': 'Update AI Chat name',
 
-        'sequence logs label': 'Logs',
+        'toolkit.label': 'Toolkit',
+        'stats.label': 'Stats',
+        'summary.label': 'Summary',
+        'thinking.label': 'Thinking',
 
-        'assistant dialog title': 'Assistant',
-        'open assistant label': 'Open assistant',
+        'search.placeholder': 'Search...',
+        'prompt.placeholder': 'Enter question or command...',
+        'context-objects.button': 'Add to context',
+        'context-settings.button': 'Chat settings',
+        'microphone.button': 'Click to speak',
+        'cancel-processing.button': 'Stop processing',
+        'blueprints-in-context.title': 'Blueprints',
+        'objects-in-context.title': 'Content',
+        'remove-object-in-context.label': 'Remove document',
+        'chat-model.title': 'Models',
+        'mcp-servers.title': 'MCP',
+        'mcp-server-add.label': 'Add MCP server',
+        'mcp-server-remove.label': 'Remove MCP server',
+        'mcp-server-name.label': 'Server name',
+        'mcp-server-name.placeholder': 'Name',
+        'mcp-server-url.label': 'Server URL',
+        'mcp-server-url.placeholder': 'https://...',
+        'mcp-server-protocol.label': 'Protocol',
+        'mcp-server-api-key.label': 'API key',
+        'mcp-server-api-key.placeholder': 'API key (optional)',
 
-        'no tools': 'No tools are configured',
-        'no results': 'No results',
+        'debug.button': 'Debug',
+        'online-switch.label': 'Online',
+        'run-prompt.label': 'Run prompt',
+        'typename.label': 'Typename',
+        'branch-thread.menu': 'Branch chat',
+        'chat-toolbar.title': 'Chat toolbar',
 
-        'button retry': 'Retry',
-        'button suggestion': 'Assistant suggestion',
-        'button select option': 'Select option',
-        'button cancel': 'Cancel',
-        'button save': 'Save',
-        'button run': 'Run',
-        'button new thread': 'New Chat',
-        'chat history label': 'Chat History',
+        'settings.default.label': 'Default',
+        'settings.custom-prompts.label': 'Use custom prompts',
+        'settings.custom-prompts.description': 'Allow the assistant to use custom prompts defined in your spaces.',
+        'settings.llm-provider.label': 'LLM provider',
+        'settings.llm-provider.description': 'Select which language model service to use for AI responses.',
+        'settings.edge-llm-model.label': 'Remote language model',
+        'settings.edge-llm-model.description': 'Choose the remote language model used for AI requests.',
+        'settings.ollama-llm-model.label': 'Ollama language model',
+        'settings.ollama-llm-model.description': 'Choose the locally hosted Ollama model for AI requests.',
+        'settings.default-llm-model.label': 'Default language model',
 
-        'toolkit label': 'Toolkit',
-        'summary label': 'Summary',
+        // Trigger status
+        'trigger-status-disabled.label': 'Triggers disabled',
+        'trigger-status-idle.label': 'Triggers idle',
+        'trigger-status-edge.label': 'Triggers will run on EDGE',
+        'trigger-status-running.label': 'Trigger running',
+        'trigger-status-error.label': 'Trigger error',
+        'trigger-runtime.label': 'Auto trigger execution',
+        'trigger-last-invocation.label': 'Last run',
+        'trigger-duration.label': 'Duration',
 
-        'search placeholder': 'Search...',
-        'prompt placeholder': 'Enter question or command...',
-        'button context objects': 'Add to context',
-        'button context settings': 'Chat settings',
-        'button microphone': 'Click to speak',
-        'button cancel processing': 'Stop processing',
-        'blueprints in context title': 'Blueprints',
-        'objects in context title': 'Content',
-        'remove object in context label': 'Remove document',
-        'chat model title': 'Model',
+        // AgentArticle.
+        'project-empty-spec.message': 'Open the Properties companion to configure the agent.',
+        'project-empty-spec.description': 'Open the Assistant companion to interact with the agent.',
+        'artifacts.label': 'Artifacts',
+        'input-queue.label': 'Inputs',
 
-        'settings default label': 'Default',
-        'settings custom prompts label': 'Use custom prompts',
-        'settings llm provider label': 'LLM provider',
-        'settings edge llm model label': 'Remote language model',
-        'settings ollama llm model label': 'Ollama language model',
+        // AgentProperties.
+        'instructions.label': 'Instructions',
+        'instructions.placeholder': 'Enter instructions, goals, and constraints for the assistant.',
+        'reset-history.button': 'Reset',
+        'subscriptions.label': 'Subscriptions',
       },
     },
   },
-] as const satisfies Resource[];
+];

package/src/types/Assistant.ts

@@ -2,63 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
+import { Chat as ChatModule } from '@dxos/assistant-toolkit';
 
-import { Obj, Ref, Type } from '@dxos/echo';
-import { LabelAnnotation } from '@dxos/echo/internal';
-import { Queue } from '@dxos/echo-db';
+// Re-export Chat schema for backward compatibility.
+export const Chat = ChatModule.Chat;
+export type Chat = ChatModule.Chat;
 
-import { LLM_PROVIDERS } from './defs';
-
-/**
- * AI chat.
- */
-export const Chat = Schema.Struct({
-  id: Type.ObjectId,
-  name: Schema.optional(Schema.String),
-  queue: Type.Ref(Queue),
-  // TODO(dmaretskyi): Eventually this and the message queue will be the same.
-  traceQueue: Schema.optional(Type.Ref(Queue)),
-}).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/assistant/Chat',
-    version: '0.2.0',
-  }),
-  LabelAnnotation.set(['name']),
-);
-
-export interface Chat extends Schema.Schema.Type<typeof Chat> {}
-
-export const makeChat = ({ name, queue }: { name?: string; queue: Queue }) =>
-  Obj.make(Chat, { name, queue: Ref.fromDXN(queue.dxn) });
-
-/**
- * Relation between a Chat and companion objects (e.g., artifacts).
- */
-export const CompanionTo = Schema.Struct({
-  id: Type.ObjectId,
-}).pipe(
-  Type.Relation({
-    typename: 'dxos.org/relation/assistant/CompanionTo',
-    version: '0.1.0',
-    source: Chat,
-    target: Type.Expando,
-  }),
-);
-
-export interface CompanionTo extends Schema.Schema.Type<typeof CompanionTo> {}
-
-/**
- * Plugin settings.
- */
-export const Settings = Schema.mutable(
-  Schema.Struct({
-    llmProvider: Schema.optional(Schema.Literal(...LLM_PROVIDERS)),
-    edgeModel: Schema.optional(Schema.String),
-    ollamaModel: Schema.optional(Schema.String),
-    lmstudioModel: Schema.optional(Schema.String),
-    customPrompts: Schema.optional(Schema.Boolean),
-  }),
-);
-
-export type Settings = Schema.Schema.Type<typeof Settings>;
+// Re-export Settings as merged const/type (not as namespace).
+import * as SettingsModule from './Settings';
+export const Settings = SettingsModule.Settings;
+export type Settings = SettingsModule.Settings;

package/src/types/Settings.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { LLM_PROVIDERS } from './defs';
+
+export const Settings = Schema.mutable(
+  Schema.Struct({
+    llmProvider: Schema.optional(Schema.Literal(...LLM_PROVIDERS)),
+    edgeModel: Schema.optional(Schema.String),
+    ollamaModel: Schema.optional(Schema.String),
+    lmstudioModel: Schema.optional(Schema.String),
+    customPrompts: Schema.optional(Schema.Boolean),
+  }),
+);
+
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}

package/src/types/capabilities.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { type Obj } from '@dxos/echo';
+
+import { meta } from '#meta';
+
+import { type Assistant } from './';
+
+export namespace AssistantCapabilities {
+  export const Settings = Capability.make<Atom.Writable<Assistant.Settings>>(`${meta.id}.capability.settings`);
+
+  export const StateSchema = Schema.mutable(
+    Schema.Struct({
+      /** Map of primary object dxn to current chat dxn. */
+      currentChat: Schema.Record({ key: Schema.String, value: Schema.UndefinedOr(Schema.String) }),
+      /** Map of chat object path to prompt text to auto-submit when the chat opens. */
+      pendingPrompts: Schema.Record({ key: Schema.String, value: Schema.UndefinedOr(Schema.String) }),
+    }),
+  );
+
+  export type AssistantState = Schema.Schema.Type<typeof StateSchema>;
+
+  export const State = Capability.make<Atom.Writable<AssistantState>>(`${meta.id}.capability.state`);
+
+  /** Session-scoped cache of transient (not yet persisted) companion chats keyed by companion DXN string. */
+  export const CompanionChatCache = Capability.make<Atom.Writable<Record<string, Obj.Unknown | undefined>>>(
+    `${meta.id}.capability.companion-chat-cache`,
+  );
+}

package/src/types/events.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ActivationEvent } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+export namespace AssistantEvents {
+  export const SetupAiServiceProviders = ActivationEvent.make(`${meta.id}.event.setup-ai-service-providers`);
+}