@dxos/assistant 0.9.0 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -30,41 +30,44 @@
     "src"
   ],
   "dependencies": {
-    "@automerge/automerge": "3.3.0-fragments.1",
+    "@automerge/automerge": "3.3.0-fragments.2",
     "@effect-atom/atom": "^0.5.3",
     "@effect-atom/atom-react": "^0.5.0",
     "@effect/ai": "0.36.0",
     "@effect/experimental": "0.60.0",
-    "@effect/platform": "0.96.1",
+    "@effect/platform": "0.96.2",
+    "@effect/rpc": "0.75.1",
     "@xenova/transformers": "^2.17.2",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/async": "0.9.0",
-    "@dxos/compute": "0.9.0",
-    "@dxos/context": "0.9.0",
-    "@dxos/debug": "0.9.0",
-    "@dxos/echo": "0.9.0",
-    "@dxos/echo-client": "0.9.0",
-    "@dxos/echo-protocol": "0.9.0",
-    "@dxos/effect": "0.9.0",
-    "@dxos/errors": "0.9.0",
-    "@dxos/functions": "0.9.0",
-    "@dxos/graph": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/keys": "0.9.0",
-    "@dxos/mcp-client": "0.9.0",
-    "@dxos/node-std": "0.9.0",
-    "@dxos/schema": "0.9.0",
-    "@dxos/types": "0.9.0",
-    "@dxos/util": "0.9.0",
-    "@dxos/ai": "0.9.0"
+    "@dxos/ai": "0.9.1-staging.ee54ba693a",
+    "@dxos/async": "0.9.1-staging.ee54ba693a",
+    "@dxos/compute": "0.9.1-staging.ee54ba693a",
+    "@dxos/compute-runtime": "0.9.1-staging.ee54ba693a",
+    "@dxos/debug": "0.9.1-staging.ee54ba693a",
+    "@dxos/context": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo-doc": "0.9.1-staging.ee54ba693a",
+    "@dxos/effect": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo-protocol": "0.9.1-staging.ee54ba693a",
+    "@dxos/errors": "0.9.1-staging.ee54ba693a",
+    "@dxos/functions": "0.9.1-staging.ee54ba693a",
+    "@dxos/graph": "0.9.1-staging.ee54ba693a",
+    "@dxos/keys": "0.9.1-staging.ee54ba693a",
+    "@dxos/log": "0.9.1-staging.ee54ba693a",
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/mcp-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/node-std": "0.9.1-staging.ee54ba693a",
+    "@dxos/schema": "0.9.1-staging.ee54ba693a",
+    "@dxos/types": "0.9.1-staging.ee54ba693a",
+    "@dxos/util": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "effect": "3.21.3"
+    "effect": "3.21.4"
   },
   "peerDependencies": {
-    "effect": "3.21.3"
+    "effect": "3.21.4"
   },
   "publishConfig": {
     "access": "public"

package/src/extraction/extraction-llm-function/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './proper-noun-extraction';

package/src/extraction/extraction-llm-function/proper-noun-extraction.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { type Database, Obj } from '@dxos/echo';
+import { Message } from '@dxos/types';
+
+import { findReferences, insertReferences } from '../quotes';
+
+const EXTRACTION_MODEL = 'com.anthropic.model.claude-haiku-4-5.default';
+
+/**
+ * Proper nouns extracted from transcript text.
+ */
+export const ProperNouns = Schema.Struct({
+  properNouns: Schema.Array(Schema.String).annotations({
+    description: 'Proper nouns (names of people, organizations, places, products) mentioned in the text.',
+  }),
+});
+export type ProperNouns = Schema.Schema.Type<typeof ProperNouns>;
+
+/**
+ * Extracts proper nouns from transcript text using a small LLM (Haiku). Provides the LanguageModel
+ * internally so the residual requirement is just {@link AiService.AiService}.
+ */
+export const extractProperNouns = (text: string) =>
+  Effect.gen(function* () {
+    const { value } = yield* Effect.scoped(
+      LanguageModel.generateObject({
+        schema: ProperNouns,
+        prompt: [
+          'Extract every proper noun (people, organizations, places, products) mentioned in the transcript text below.',
+          'Return only the surface strings exactly as they appear. Exclude common nouns and pronouns.',
+          '',
+          'Transcript:',
+          text,
+        ].join('\n'),
+      }),
+    );
+
+    // Drop short tokens (e.g. "IT"): insertReferences replaces case-insensitive substrings, so a
+    // short noun would match inside unrelated words ("secur[IT]y") and corrupt neighbouring links.
+    return value.properNouns.map((noun) => noun.trim()).filter((noun) => noun.length >= 3);
+  }).pipe(Effect.provide(AiService.model(EXTRACTION_MODEL)));
+
+/**
+ * Enriches a transcript message: for each transcript block, extracts proper nouns, links them to
+ * objects in the space via full-text search, and rewrites the text with `[noun](dxn)` references.
+ * Requires {@link AiService.AiService}; takes the space database handle.
+ */
+export const enrichTranscriptMessage = (message: Message.Message, { db }: { db: Database.Database }) =>
+  Effect.gen(function* () {
+    const blocks = yield* Effect.forEach(message.blocks, (block) =>
+      Effect.gen(function* () {
+        if (block._tag !== 'transcript') {
+          return block;
+        }
+
+        const nouns = yield* extractProperNouns(block.text);
+        const references = yield* Effect.promise(() => findReferences([...nouns], db));
+        return { ...block, text: insertReferences(block.text, references) };
+      }),
+    );
+
+    // Preserve the message identity and metadata; enrichment only rewrites transcript block text.
+    return Obj.make(Message.Message, {
+      id: message.id,
+      sender: message.sender,
+      created: message.created,
+      properties: message.properties,
+      blocks,
+    });
+  });

package/src/extraction/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './extraction';
+export * from './extraction-llm-function';
 export * from './extraction-ner-function';
 export * from './quotes';

package/src/extraction/quotes.test.ts

@@ -2,9 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
-import { insertReferences } from './quotes';
+import { Obj } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { Organization, Person } from '@dxos/types';
+
+import { findReferences, insertReferences } from './quotes';
 
 describe('insertReferences', () => {
   test('should replace quotes with DXN references', () => {
@@ -24,4 +28,65 @@ describe('insertReferences', () => {
       "And what I'd like to talk today about is Steven Wolfram's concept of a [computational irreducibility](echo:/01JTG9JW11XGWJZ32AW8ET93D1).",
     );
   });
+
+  test('does not nest links when one quote is a substring of another', () => {
+    const quotes = {
+      references: [
+        { quote: 'Sarah', id: '01JTG9JW11XGWJZ32AW8ET93D1' },
+        { quote: 'Sarah Johnson', id: '01JTG9JW11XGWJZ32AW8ET93D1' },
+      ],
+    };
+
+    // "Sarah Johnson" is linked as a whole (processed first); the standalone "Sarah" is linked
+    // separately; the "Sarah" inside the first link is left untouched (no nested `[[..](..)](..)`).
+    expect(insertReferences('Sarah Johnson spoke. Later Sarah left.', quotes)).toBe(
+      '[Sarah Johnson](echo:/01JTG9JW11XGWJZ32AW8ET93D1) spoke. Later [Sarah](echo:/01JTG9JW11XGWJZ32AW8ET93D1) left.',
+    );
+  });
+
+  test('does not re-link a repeated quote inside an already-inserted link', () => {
+    const quotes = { references: [{ quote: 'Amco', id: '01JTG9JW11XGWJZ32AW8ET93D1' }] };
+
+    expect(insertReferences('Amco and Amco again.', quotes)).toBe(
+      '[Amco](echo:/01JTG9JW11XGWJZ32AW8ET93D1) and [Amco](echo:/01JTG9JW11XGWJZ32AW8ET93D1) again.',
+    );
+  });
+});
+
+describe('findReferences', () => {
+  let builder: EchoTestBuilder;
+
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('links nouns to objects via full-text search, including first-name tokens', async () => {
+    const { db } = await builder.createDatabase({ types: [Organization.Organization, Person.Person] });
+    const amco = db.add(Obj.make(Organization.Organization, { name: 'Amco' }));
+    const sarah = db.add(Obj.make(Person.Person, { fullName: 'Sarah Johnson' }));
+    await db.flush({ indexes: true });
+
+    const { references } = await findReferences(['Amco', 'Sarah', 'Nonexistent'], db);
+    const byQuote = new Map(references.map((reference) => [reference.quote, reference.id]));
+
+    expect(byQuote.get('Amco')).toEqual(amco.id);
+    // Full-text matches a single token within a multi-word field, so first-name mentions link to
+    // the full-name object — this is also what makes the overlap case in `insertReferences` real.
+    expect(byQuote.get('Sarah')).toEqual(sarah.id);
+    expect(byQuote.has('Nonexistent')).toBe(false);
+  });
+
+  test('deduplicates and trims nouns before lookup', async () => {
+    const { db } = await builder.createDatabase({ types: [Organization.Organization] });
+    db.add(Obj.make(Organization.Organization, { name: 'Amco' }));
+    await db.flush({ indexes: true });
+
+    const { references } = await findReferences(['Amco', 'Amco', '  Amco  ', ''], db);
+
+    expect(references.filter((reference) => reference.quote === 'Amco')).toHaveLength(1);
+  });
 });

package/src/extraction/quotes.ts

@@ -6,7 +6,6 @@ import * as Schema from 'effect/Schema';
 
 import { type Database, Filter, Query } from '@dxos/echo';
 import { EID, EntityId } from '@dxos/keys';
-import { log } from '@dxos/log';
 
 export const ReferencedQuotes = Schema.Struct({
   references: Schema.Array(
@@ -26,12 +25,30 @@ export const ReferencedQuotes = Schema.Struct({
 });
 export type ReferencedQuotes = Schema.Schema.Type<typeof ReferencedQuotes>;
 
-export const findQuotes = async (quotes: string[], db: Database.Database): Promise<ReferencedQuotes> => {
+export type FindReferencesOptions = {
+  /** Search backend. Full-text matches proper nouns precisely; vector matches semantically. */
+  searchKind?: 'full-text' | 'vector';
+};
+
+/**
+ * Finds the best-matching context object for each noun and returns it as a reference.
+ */
+export const findReferences = async (
+  nouns: string[],
+  db: Database.Database,
+  { searchKind = 'full-text' }: FindReferencesOptions = {},
+): Promise<ReferencedQuotes> => {
+  // Deduplicate and process longer nouns first: `insertReferences` rewrites case-insensitive
+  // substrings, so a repeated or shorter overlapping noun would re-replace already-linked text and
+  // produce nested/broken markdown links.
+  const normalizedNouns = Array.from(new Set(nouns.map((noun) => noun.trim()).filter((noun) => noun.length > 0))).sort(
+    (leftNoun, rightNoun) => rightNoun.length - leftNoun.length,
+  );
+
   const references = await Promise.all(
-    quotes.map(async (quote) => {
-      const objects = await db.query(Query.select(Filter.text(quote, { type: 'vector' }))).run();
-      log.info('found quotes in vector index', { objects, quote });
-      return objects.length > 0 ? [{ id: objects[0].id.toString(), quote }] : [];
+    normalizedNouns.map(async (noun) => {
+      const objects = await db.query(Query.select(Filter.text(noun, { type: searchKind }))).run();
+      return objects.length > 0 ? [{ id: objects[0].id.toString(), quote: noun }] : [];
     }),
   );
   return { references: references.flat() };
@@ -41,16 +58,33 @@ export const findQuotes = async (quotes: string[], db: Database.Database): Promi
  * Finds and replaces all quotes with DXNs references.
  */
 // TODO(dmaretskyi): Lookup and verifiy ids from provided context.
-export const insertReferences = (text: string, quotes: ReferencedQuotes) => {
-  for (const quote of quotes.references) {
-    if (!EntityId.isValid(quote.id)) {
-      continue;
-    }
+export const insertReferences = (text: string, quotes: ReferencedQuotes): string => {
+  // Process longer quotes first so e.g. "Sarah Johnson" is linked before "Sarah". Combined with the
+  // link-aware replacement below this stops a shorter or overlapping quote from rewriting text that
+  // is already part of an inserted link (which would produce nested `[[..](..)](..)` markdown).
+  const references = quotes.references
+    .filter((quote) => EntityId.isValid(quote.id))
+    .sort((left, right) => right.quote.length - left.quote.length);
 
-    // Use a case-insensitive regular expression to replace the quote.
+  for (const quote of references) {
+    // Case-insensitive match of the (regex-escaped) quote.
     const regex = new RegExp(quote.quote.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
-    text = text.replace(regex, `[${quote.quote}](${EID.make({ entityId: quote.id })})`);
+    text = replaceOutsideLinks(text, regex, `[${quote.quote}](${EID.make({ entityId: quote.id })})`);
   }
 
   return text;
 };
+
+const MARKDOWN_LINK = /\[[^\]]*\]\([^)]*\)/g;
+
+/** Applies a replacement to every span of `text` that is not already inside a `[label](url)` link. */
+const replaceOutsideLinks = (text: string, regex: RegExp, replacement: string): string => {
+  let result = '';
+  let plainStart = 0;
+  for (const link of text.matchAll(MARKDOWN_LINK)) {
+    const index = link.index ?? 0;
+    result += text.slice(plainStart, index).replace(regex, replacement) + link[0];
+    plainStart = index + link[0].length;
+  }
+  return result + text.slice(plainStart).replace(regex, replacement);
+};

package/src/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './functions';
+export * from './tool-runtime';
 export * from './request';
 export * from './session';
 export * from './templates';

package/src/request/AiRequest.ts

@@ -19,19 +19,19 @@ import {
   AiPreprocessor,
   AiSummarizer,
   type AiToolNotFoundError,
-  callTool,
   type OpaqueToolkit,
   type PromptPreprocessingError,
   type ToolExecutionService,
   type ToolResolverService,
+  callTool,
   withoutToolCallParising,
 } from '@dxos/ai';
-import { type Blueprint, Trace, Operation } from '@dxos/compute';
+import { Operation, type Skill, Trace } from '@dxos/compute';
 import { Database, Obj, Registry } from '@dxos/echo';
 import { log } from '@dxos/log';
 import { ContentBlock, Message } from '@dxos/types';
 
-import { getOperationFromTool } from '../functions/services';
+import { getOperationFromTool } from '../tool-runtime/services';
 import { type AiAssistantError, CompleteBlock, PartialBlock } from '../util';
 import { formatSystemPrompt, formatUserPrompt } from './format';
 import { GenerationObserver } from './observer';
@@ -60,6 +60,13 @@ export type Options = {
    * This is useful for streaming the output to a queue.
    */
   onOutput?: (message: Message.Message) => Effect.Effect<void, never, never>;
+
+  /**
+   * When false, turn messages are not appended to the feed or written as persisted trace blocks.
+   *
+   * @default true
+   */
+  persist?: boolean;
 };
 
 export type RunProps<R = never> = {
@@ -68,7 +75,7 @@ export type RunProps<R = never> = {
   system?: string;
   history?: Message.Message[];
   objects?: Obj.Unknown[];
-  blueprints?: readonly Blueprint.Blueprint[];
+  skills?: readonly Skill.Skill[];
   toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
 };
 
@@ -77,7 +84,7 @@ export type BeginProps = {
   system?: string;
   history?: Message.Message[];
   objects?: Obj.Unknown[];
-  blueprints?: readonly Blueprint.Blueprint[];
+  skills?: readonly Skill.Skill[];
 };
 
 export type TurnProps<R = never> = {
@@ -88,6 +95,12 @@ export type TurnProps<R = never> = {
 export type TurnResult = {
   messages: Message.Message[];
   done: boolean;
+  /**
+   * Provider finish reason for this turn. `pause` means the provider paused a server-tool turn
+   * mid-execution (e.g. Anthropic `pause_turn`) and the turn must be resumed by issuing another
+   * request without mutating the trailing assistant content.
+   */
+  finishReason?: ContentBlock.FinishReason;
 };
 
 /**
@@ -139,6 +152,9 @@ export class Request {
     Effect.gen(this, function* () {
       this._pending.push(message);
       yield* this._observer.onMessage(message);
+      if (this._options.persist === false) {
+        return message;
+      }
       for (const block of message.blocks) {
         log('write complete block', {
           messageId: message.id,
@@ -173,7 +189,7 @@ export class Request {
     prompt,
     system,
     history = [],
-    blueprints = [],
+    skills = [],
     objects = [],
   }: BeginProps): Effect.Effect<void, RunError, RunRequirements> =>
     Effect.gen(this, function* () {
@@ -181,7 +197,7 @@ export class Request {
       this._history = [...history];
       this._pending = [];
 
-      const systemPrompt = yield* formatSystemPrompt({ system, blueprints, objects }).pipe(Effect.orDie);
+      const systemPrompt = yield* formatSystemPrompt({ system, skills, objects }).pipe(Effect.orDie);
 
       if (this._options.summarizationThreshold !== undefined) {
         const tokenCount = yield* AiPreprocessor.estimateTokens(
@@ -200,7 +216,7 @@ export class Request {
 
   /**
    * Execute a single turn: one LLM generation followed by tool execution.
-   * The toolkit and system prompt can be updated between turns to reflect context changes (e.g. dynamically enabled blueprints).
+   * The toolkit and system prompt can be updated between turns to reflect context changes (e.g. dynamically enabled skills).
    */
   runAgentTurn = <const R = never>({
     system,
@@ -222,6 +238,7 @@ export class Request {
 
       const observer = this._observer;
       let currentMessageId: Obj.ID | null = null;
+      let finishReason: ContentBlock.FinishReason | undefined;
 
       const messages = yield* LanguageModel.streamText({
         prompt,
@@ -240,6 +257,9 @@ export class Request {
         Stream.mapEffect(
           (block) =>
             Effect.gen(this, function* () {
+              if (block._tag === 'stats' && block.finishReason !== undefined) {
+                finishReason = block.finishReason;
+              }
               if (block.pending) {
                 currentMessageId ??= Obj.ID.random();
                 log('emit ephemeral message', { id: currentMessageId, type: block._tag });
@@ -271,16 +291,23 @@ export class Request {
       );
       log('messages', { messages });
 
+      // A paused server-tool turn (e.g. Anthropic `pause_turn`) is not complete: the provider
+      // expects the assistant content to be resent so it can finish executing the server tool.
+      // No local tool execution is needed — just another request.
+      if (finishReason === 'pause') {
+        return { messages, done: false, finishReason };
+      }
+
       const toolCalls = this.getToolCalls();
 
       if (toolCalls.length === 0) {
         this._ended = Date.now();
-        return { messages, done: true };
+        return { messages, done: true, finishReason };
       } else if (!toolkit) {
         throw new Error('No toolkit provided');
       }
 
-      return { messages, done: false };
+      return { messages, done: false, finishReason };
     }).pipe(Effect.withSpan('AiRequest.runAgentTurn'));
 
   runTools = <const R = never>({
@@ -317,19 +344,23 @@ export class Request {
     system: systemTemplate,
     history = [],
     objects = [],
-    blueprints = [],
+    skills = [],
     toolkit,
   }: RunProps<R>): Effect.Effect<Message.Message[], RunError, RunRequirements | R> =>
     Effect.gen(this, function* () {
-      yield* this.begin({ prompt, system: systemTemplate, history, objects, blueprints });
+      yield* this.begin({ prompt, system: systemTemplate, history, objects, skills });
 
-      const system = yield* formatSystemPrompt({ system: systemTemplate, blueprints, objects }).pipe(Effect.orDie);
+      const system = yield* formatSystemPrompt({ system: systemTemplate, skills, objects }).pipe(Effect.orDie);
 
       do {
-        const { done } = yield* this.runAgentTurn({ system, toolkit });
+        const { done, finishReason } = yield* this.runAgentTurn({ system, toolkit });
         if (done) {
           break;
         }
+        // A paused server-tool turn resumes with another request and no local tool execution.
+        if (finishReason === 'pause') {
+          continue;
+        }
         yield* this.runTools({ toolkit });
       } while (true);
 

package/src/request/format.ts

@@ -25,31 +25,29 @@ import { ArtifactDiffResolver } from './artifact-diff';
 // TODO(burdon): Move to AiPreprocessor.
 export const formatSystemPrompt = ({
   system,
-  blueprints = [],
+  skills = [],
   objects = [],
-}: Pick<AiRequest.RunProps, 'system' | 'blueprints' | 'objects'>): Effect.Effect<
+}: Pick<AiRequest.RunProps, 'system' | 'skills' | 'objects'>): Effect.Effect<
   string,
   FunctionNotFoundError | EntityNotFoundError,
   Database.Service | Registry.Service | Operation.Service
 > =>
   Effect.gen(function* () {
-    const blueprintDefs = yield* Function.pipe(
-      blueprints,
-      Effect.forEach((blueprint) => Effect.succeed(blueprint.instructions)),
+    const skillDefs = yield* Function.pipe(
+      skills,
+      Effect.forEach((skill) => Effect.succeed(skill.instructions)),
       Effect.flatMap(
         Effect.forEach((template) =>
           Effect.gen(function* () {
             return trim`
-            <blueprint>
+            <skill>
               ${yield* Template.processTemplate(template)}
-            </blueprint>
+            </skill>
           `;
           }),
         ),
       ),
-      Effect.map((blueprints) =>
-        blueprints.length > 0 ? ['## Blueprints Definitions', ...blueprints].join('\n\n') : undefined,
-      ),
+      Effect.map((skills) => (skills.length > 0 ? ['## Skills Definitions', ...skills].join('\n\n') : undefined)),
     );
 
     const objectDefs = yield* Function.pipe(
@@ -66,7 +64,7 @@ export const formatSystemPrompt = ({
     );
 
     return yield* Function.pipe(
-      Effect.succeed([system, blueprintDefs, objectDefs].filter((def): def is string => def !== undefined)),
+      Effect.succeed([system, skillDefs, objectDefs].filter((def): def is string => def !== undefined)),
       Effect.map((parts) => parts.join('\n\n')),
     );
   }).pipe(Effect.withSpan('formatSystemPrompt'));