@dxos/plugin-assistant 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

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

@@ -0,0 +1,247 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import {
+  AgentHandlers,
+  AgentPrompt,
+  DatabaseBlueprint,
+  DatabaseHandlers,
+  WebSearchBlueprint,
+  WebSearchHandlers,
+  WebSearchToolkitOpaque,
+} from '@dxos/assistant-toolkit';
+import { Blueprint, Routine, Trace, Trigger, Operation } from '@dxos/compute';
+import { ExampleHandlers, Reply } from '@dxos/compute/testing';
+import { Database, Feed, Filter, Obj, Query, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AgentService } from '@dxos/functions-runtime';
+import { FeedTraceSink, TriggerDispatcher } from '@dxos/functions-runtime';
+import { AssistantTestLayerWithTriggers } from '@dxos/functions-runtime/testing';
+import { ObjectId } from '@dxos/keys';
+import { dbg } from '@dxos/log';
+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".
+            │  ●  [function] List schemas - Success
+            │  ●  [function] Create object - Success
+            │  ●  [function] Add to context - Success
+            ◆──╯  [atom] Agent completed request
+            ●  │  [atom] Agent processing request...
+            │  ●  [user] Create a person named "John Connor".
+            │  ●  [function] Create object - Success
+            │  ●  [function] Add to context - Success
+            ◆──╯  [atom] 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?
+              │  ●  [function] List schemas - Success
+              │  ●  [function] Query - Success
+              │  ●  [function] Query - Success
+              ◆──╯  [atom] 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.
+                │  ●  [function] List schemas - Success
+                ◆──╯  [atom] Agent completed request
+                ●  │  [atom] Agent processing request...
+                │  ●  [user] Create an organization called "DXOS" and a person named "Alice".
+                │  ●  [function] Create object - Success
+                │  ●  [function] Create object - Success
+                ◆──╯  [atom] Agent completed request
+                ●  │  [atom] Agent processing request...
+                │  ●  [user] Search for all organizations and persons.
+                │  ●  [function] Query - Success
+                │  ●  [function] Query - Success
+                ◆──╯  [atom] 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(
+            Routine.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(`
+                  "
+                  ●     [function] Run Routine
+                  ├──●  [user] Research the given topic, or object.
+                  ◆──╯  [function] Run Routine - Success
+                  "
+                `);
+        },
+        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(`
+                  "
+                  ●  [function] Reply - Success
+                  ●  [function] Reply - Success
+                  ●  [function] Reply - Success
+                  "
+                `);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+      { timeout: 120_000 },
+    );
+  });
+});

package/src/testing.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Eager re-export of `AssistantPlugin`. See `@dxos/plugin-testing/src/core.ts`
+// for the rationale.
+export * from './AssistantPlugin';

package/src/translations.ts

@@ -2,107 +2,187 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Blueprint } from '@dxos/blueprints';
+import { Chat, Agent, McpServer } from '@dxos/assistant-toolkit';
+import { Blueprint, Routine } from '@dxos/compute';
 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/translations';
+import { translations as formTranslations } from '@dxos/react-ui-form/translations';
 
-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',
       },
-      // 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',
+      [Type.getTypename(Routine.Routine)]: {
+        'typename.label': 'Routine',
+        'typename.label_zero': 'Routines',
+        'typename.label_one': 'Routine',
+        'typename.label_other': 'Routines',
+        'object-name.placeholder': 'New routine',
+        'add-object.label': 'Add routine',
+        'rename-object.label': 'Rename routine',
+        'delete-object.label': 'Delete routine',
+        'object-deleted.label': 'Routine 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',
+      [Sequence.Sequence.typename]: {
+        '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',
+      },
+      [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',
+        'import-compute-operations.label': 'Import compute operations',
+        'toggle-trace-panel-debug.label': 'Toggle trace panel debug view',
+
+        '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',
+
+        'toolkit.label': 'Toolkit',
+        'stats.label': 'Stats',
+        'summary.label': 'Summary',
+        'thinking.label': 'Thinking',
 
-        'sequence logs label': 'Logs',
+        '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',
 
-        'assistant dialog title': 'Assistant',
-        'open assistant label': 'Open assistant',
+        'options.blueprints.title': 'Skills',
+        'options.mcp.title': 'MCP',
+        'options.chat-model.title': 'Models',
+        'remove-object.label': 'Remove object',
 
-        'no tools': 'No tools are configured',
-        'no results': 'No results',
+        'chat-view.title': 'View',
+        'chat-view.normal.label': 'Normal',
+        'chat-view.summary.label': 'Summary',
+        'chat-view.thinking.label': 'Thinking',
+        'chat-view.debug.label': 'Debug',
+        '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)',
+        'mcp-server-error.label': 'MCP server unavailable',
 
-        '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',
-        'chat update name label': 'Update AI Chat name',
+        'debug.button': 'Debug',
+        'online-switch.label': 'Online',
+        'run-prompt.label': 'Run prompt',
+        'routine-running.label': 'Running…',
+        'typename.label': 'Typename',
+        'branch-thread.menu': 'Branch chat',
+        'chat-toolbar.title': 'Chat toolbar',
 
-        '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',
+        'inputs.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,62 +2,25 @@
 // Copyright 2024 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
+// @import-as-namespace
 
-import { Obj, Ref, Type } from '@dxos/echo';
-import { FormAnnotation, LabelAnnotation } from '@dxos/echo/internal';
-import { Queue } from '@dxos/echo-db';
+// Re-export Chat schema for backward compatibility.
+import { Chat as ChatModule } from '@dxos/assistant-toolkit';
+export const Chat = ChatModule.Chat;
+export type Chat = ChatModule.Chat;
 
-import { LLM_PROVIDERS } from './defs';
+// 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;
 
-/**
- * AI chat.
- */
-export const Chat = Schema.Struct({
-  name: Schema.String.pipe(Schema.optional),
-  queue: Type.Ref(Queue).pipe(FormAnnotation.set(false)),
-  // TODO(dmaretskyi): Eventually this and the message queue will be the same.
-  traceQueue: Type.Ref(Queue).pipe(FormAnnotation.set(false), Schema.optional),
-}).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/assistant/Chat',
-    version: '0.2.0',
-  }),
-  LabelAnnotation.set(['name']),
-);
+export const ChatViews = SettingsModule.ChatViews;
+export const ChatView = SettingsModule.ChatView;
+export type ChatView = SettingsModule.ChatView;
 
-export interface Chat extends Schema.Schema.Type<typeof Chat> {}
+export const ModelProviders = SettingsModule.ModelProviders;
+export const ModelProvider = SettingsModule.ModelProvider;
+export type ModelProvider = SettingsModule.ModelProvider;
 
-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>;
+export const ModelDefaults = SettingsModule.ModelDefaults;
+export type ModelDefaults = SettingsModule.ModelDefaults;

package/src/types/AssistantCapabilities.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+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 * as Assistant from './Assistant';
+
+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/AssistantEvents.ts

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