@dxos/assistant 0.8.4-main.e8ec1fe → 0.8.4-main.ef1bc66f44

package/src/functions.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"@anthropic/claude-opus-4-0","stream":true,"tools":[{"name":"read-name","description":"Reads the name of an organization.","inputSchema":{"type":"object","required":["org"],"properties":{"org":{"type":"string","description":"The ID of the referenced object. Formats accepted:\n- DXN (dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4). DXNs can be prepended with an @ symbol for compatibility with in-text references.\n- space ID, object ID tuple (spaceID:objectID)\n- Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is the name of the organization? 01JGFJJZ00G0WKQSJGMAKCNT89","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01FqHQGxFVdQKeMXjodHavsF","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The user is asking for the name of","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" an organization an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"d has provided what","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" appears to be an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID: 01JGFJ","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"JZ00G0WK","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"QSJGMAKCNT89","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n\nI","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" need to use the read-name function","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" to get the name of this organization.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" According","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" to the function description, I can","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" pass","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" just","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" the object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID if","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" it's assume","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"d to be in the current space.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n\nLet me call","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" the function with this","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EokECkYICxgCKkDkOVtqWk3+YJ1nk31yy/hYUygSTbpQxoD7UKl2RqwyS+tJSV2rou35JEFIl30ogJZiohCBXqY0IZ3YO1SwhWq1EgztHHPI5rGjH4gehN8aDBh3BbEfM6OCraoAQiIwDSGtzFCbT7K+yTBtmtri6uuGvPwNGmRshKURPnFRCjdAf0gj1Jwge4pmIYnlGpRGKvACF4kjtsTHsn8f7ktuuzSEpVNaC6d5VYA6/Fm5ZFaiQPn0/F4fQXy1PNEyo4007gP21Ate8+98CCtlfkOnEE53hElq58doXrVOzpL+uH5b6PBPtM9f1+L9cKjhTPV6djIcewwHTTSJDTM6fr9c82f9u5EDvzNe1QODqlqCiVtNsjWCYOWNZUqILdl0TQ43Hzjf2T+WN6ARHfd3mGVsAtg8vcBM8D4mPvThsTnoswYIeB6Y5aDAA+Xu32jGRmJGclevuy25lJFZG8lAhOXJOdiP88zTG5XCN5ED3GLo2rjKBnQzwGpzg1M0ARKkrNzuLbNZ31uk36ayo+1T381Ld0yIQAX/ZUrLNZ8ovJ1sIHW18hmnyec69+4qWuy//NBWlAfyFOQnQfXM1f2XO5AFBrSILGtHxWM1+KINm1Xh68gHZpjjpyM5g8zl61nDLGxNq3OBugM7NSghygmGPmy2DlxU147cVzOHh7ZXh8fFxBfZlW0YAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"I","metadata":{}},{"type":"text-delta","id":"1","delta":"'ll look","metadata":{}},{"type":"text-delta","id":"1","delta":" up the name of that","metadata":{}},{"type":"text-delta","id":"1","delta":" organization for you.","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"tool-params-start","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"{\"or","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"g\": \"01JGFJJ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"Z00G0WKQ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"SJGM","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"AKCNT89\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","metadata":{}},{"type":"tool-call","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","providerExecuted":false,"metadata":{},"params":{"org":"dxn:echo:@:01JGFJJZ00G0WKQSJGMAKCNT89"}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":729,"outputTokens":187,"totalTokens":916},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":729,"output_tokens":8,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-0","stream":true,"tools":[{"name":"read-name","description":"Reads the name of an organization.","inputSchema":{"type":"object","required":["org"],"properties":{"org":{"type":"string","description":"The ID of the referenced object. Formats accepted:\n- DXN (dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4). DXNs can be prepended with an @ symbol for compatibility with in-text references.\n- space ID, object ID tuple (spaceID:objectID)\n- Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is the name of the organization? 01JGFJJZ00G0WKQSJGMAKCNT89","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user is asking for the name of an organization and has provided what appears to be an object ID: 01JGFJJZ00G0WKQSJGMAKCNT89\n\nI need to use the read-name function to get the name of this organization. According to the function description, I can pass just the object ID if it's assumed to be in the current space.\n\nLet me call the function with this ID.","options":{}},{"type":"text","text":"I'll look up the name of that organization for you.","options":{}},{"type":"tool-call","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","params":{"org":"01JGFJJZ00G0WKQSJGMAKCNT89"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","isFailure":false,"result":"BlueYard","providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01X5xvtDymPG7tTUMLZz3eAD","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"The name of the organization with","metadata":{}},{"type":"text-delta","id":"0","delta":" ID 01JGFJJ","metadata":{}},{"type":"text-delta","id":"0","delta":"Z00G0WKQ","metadata":{}},{"type":"text-delta","id":"0","delta":"SJGMAKCNT89 is","metadata":{}},{"type":"text-delta","id":"0","delta":" **BlueYard**.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":801,"outputTokens":39,"totalTokens":840},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":801,"output_tokens":6,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/functions.test.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { ConsolePrinter } from '@dxos/ai';
+import { MemoizedAiService } from '@dxos/ai/testing';
+import { AiSession, GenerationObserver, createToolkit } from '@dxos/assistant';
+import { Blueprint } from '@dxos/blueprints';
+import { Database, Obj, Type } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { defineFunction } from '@dxos/functions';
+import { ObjectId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { AssistantTestLayer } from './testing';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const readName = defineFunction({
+  key: 'dxos.org/function/read-name',
+  name: 'Read Name',
+  description: 'Reads the name of an organization.',
+  inputSchema: Schema.Struct({
+    org: Type.Ref(Organization.Organization),
+  }),
+  outputSchema: Schema.String,
+  handler: Effect.fnUntraced(function* ({ data }) {
+    const org = yield* Database.load(data.org);
+    return org.name ?? '<no org>';
+  }),
+});
+
+const blueprint = Blueprint.make({
+  key: 'dxos.org/blueprint/test',
+  name: 'Test blueprint',
+  tools: Blueprint.toolDefinitions({ functions: [readName] }),
+});
+
+const TestLayer = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  functions: [readName],
+  types: [Organization.Organization],
+});
+
+describe('Research', () => {
+  it.effect(
+    'call a function with a ref input',
+    Effect.fnUntraced(
+      function* (_) {
+        const org = yield* Database.add(
+          Obj.make(Organization.Organization, {
+            name: 'BlueYard',
+            website: 'https://blueyard.com',
+          }),
+        );
+        yield* Database.flush({ indexes: true });
+        yield* new AiSession().run({
+          prompt: `What is the name of the organization? ${org.id}`,
+          toolkit: yield* createToolkit({
+            blueprints: [blueprint],
+          }),
+          observer: GenerationObserver.fromPrinter(new ConsolePrinter()),
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
+});

package/src/session/GenericToolkit.ts

@@ -4,6 +4,7 @@
 
 import type * as Tool from '@effect/ai/Tool';
 import * as Toolkit from '@effect/ai/Toolkit';
+import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Pipeable from 'effect/Pipeable';
@@ -83,6 +84,11 @@ export const make = <Tools extends Record<string, Tool.Any>, E, R>(
   };
 };
 
+/**
+ * Empty generic toolkit.
+ */
+export const empty = make(Toolkit.empty, Layer.empty);
+
 /**
  * Merges multiple portable toolkits into a single portable toolkit.
  */
@@ -113,6 +119,7 @@ export type GenericTools<R = never> = Record<
       readonly parameters: AnyStructSchemaNoContext;
       readonly success: Schema.Schema.AnyNoContext;
       readonly failure: typeof Schema.Never;
+      readonly failureMode: Tool.FailureMode;
     },
     R
   >
@@ -128,3 +135,26 @@ export interface AnyStructSchemaNoContext extends Pipeable.Pipeable {
   readonly fields: Schema.Struct.Fields;
   readonly annotations: any;
 }
+
+/**
+ * Provides a generic toolkit to the agent.
+ */
+export class Provider extends Context.Tag('@dxos/assistant/GenericToolkit.Provider')<
+  Provider,
+  {
+    readonly getToolkit: () => GenericToolkit;
+  }
+>() {}
+
+/**
+ * Layer for providing a generic toolkit to the agent.
+ */
+export const providerLayer = (toolkit: GenericToolkit) =>
+  Layer.succeed(Provider, {
+    getToolkit: () => toolkit,
+  });
+
+/**
+ * Layer for providing an empty generic toolkit to the agent.
+ */
+export const providerEmpty = providerLayer(empty);

package/src/session/artifact-diff.ts

@@ -4,8 +4,8 @@
 
 import * as Context from 'effect/Context';
 
-import { type ObjectId } from '@dxos/echo/internal';
 import { type ObjectVersion } from '@dxos/echo-db';
+import { type ObjectId } from '@dxos/keys';
 
 /**
  * Resolves artifact ids to their versions.

package/src/session/format.test.ts

@@ -2,60 +2,123 @@
 // Copyright 2025 DXOS.org
 //
 
-import { beforeAll, describe, it } from '@effect/vitest';
+import { describe, expect, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
 
 import { Blueprint, Template } from '@dxos/blueprints';
-import { Obj } from '@dxos/echo';
-import { type EchoDatabase } from '@dxos/echo-db';
-import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { Database, Obj, Query } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { defineFunction } from '@dxos/functions';
 import { Text } from '@dxos/schema';
 import { Organization } from '@dxos/types';
 import { trim } from '@dxos/util';
 
 import { createSystemPrompt } from '../templates/system';
+import { AssistantTestLayer } from '../testing';
 
 import { formatSystemPrompt } from './format';
 
-describe('format', () => {
-  let db: EchoDatabase;
-  beforeAll(async () => {
-    const builder = await new EchoTestBuilder().open();
-    ({ db } = await builder.createDatabase({
-      types: [Text.Text, Organization.Organization, Blueprint.Blueprint],
-    }));
-  });
+const organizationListFunction = defineFunction({
+  key: 'dxos.org/function/organization-list',
+  name: 'Organization List',
+  description: 'List organizations',
+  inputSchema: Schema.Struct({}),
+  outputSchema: Schema.Array(Schema.String),
+  handler: Effect.fnUntraced(function* () {
+    const organizations = yield* Database.runQuery(Query.type(Organization.Organization));
+    return organizations.map((organization) => organization.name);
+  }),
+});
+
+const TestLayer = AssistantTestLayer({
+  types: [Text.Text, Organization.Organization, Blueprint.Blueprint],
+  functions: [organizationListFunction],
+});
 
+describe('format', () => {
   it.effect(
     'should format',
-    Effect.fn(function* () {
-      const object = db.add(
-        Obj.make(Organization.Organization, {
-          name: 'Test',
-          website: 'https://www.test.com',
-        }),
-      );
-
-      const blueprint = db.add(
-        Blueprint.make({
-          key: 'example.com/blueprint/test',
-          name: 'Test',
-          instructions: Template.make({
-            source: trim`
-              Test
-              This is the test blueprint.
-            `,
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        const object = db.add(
+          Obj.make(Organization.Organization, {
+            name: 'Test',
+            website: 'https://www.test.com',
+          }),
+        );
+
+        const blueprint = db.add(
+          Blueprint.make({
+            key: 'example.com/blueprint/test',
+            name: 'Test',
+            instructions: Template.make({
+              source: trim`
+                Test
+                This is the test blueprint.
+              `,
+            }),
+          }),
+        );
+
+        const output = yield* formatSystemPrompt({
+          system: createSystemPrompt({}),
+          blueprints: [blueprint],
+          objects: [object],
+        });
+
+        console.log(output);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'should format with function input',
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        const object = db.add(
+          Obj.make(Organization.Organization, {
+            name: 'Test Org',
+            website: 'https://www.test.com',
+          }),
+        );
+
+        const blueprint = db.add(
+          Blueprint.make({
+            key: 'example.com/blueprint/test',
+            name: 'Test',
+            instructions: Template.make({
+              source: trim`
+                Organization List:
+                {{#each organizations}}
+                  - {{this}}
+                {{/each}}
+                `,
+              inputs: [
+                {
+                  name: 'organizations',
+                  kind: 'function',
+                  function: organizationListFunction.key,
+                },
+              ],
+            }),
           }),
-        }),
-      );
+        );
 
-      const output = yield* formatSystemPrompt({
-        system: createSystemPrompt({}),
-        blueprints: [blueprint, blueprint],
-        objects: [object, object],
-      });
+        const output = yield* formatSystemPrompt({
+          system: createSystemPrompt({}),
+          blueprints: [blueprint],
+          objects: [object],
+        });
 
-      console.log(output);
-    }),
+        expect(output).to.include('Test Org');
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
   );
 });

package/src/session/format.ts

@@ -2,15 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Array from 'effect/Array';
 import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
 
 import { Template } from '@dxos/blueprints';
 import { Obj } from '@dxos/echo';
-import { type ObjectId } from '@dxos/echo/internal';
-import { DatabaseService, ObjectVersion } from '@dxos/echo-db';
+import { ObjectVersion } from '@dxos/echo-db';
+import { type ObjectId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { type ContentBlock, Message } from '@dxos/types';
 import { trim } from '@dxos/util';
@@ -18,7 +17,7 @@ import { trim } from '@dxos/util';
 import { AiAssistantError } from '../errors';
 
 import { ArtifactDiffResolver } from './artifact-diff';
-import { type AiSessionRunError, type AiSessionRunParams } from './session';
+import { type AiSessionRunError, type AiSessionRunProps } from './session';
 
 /**
  * Formats the system prompt.
@@ -28,20 +27,20 @@ export const formatSystemPrompt = ({
   system,
   blueprints = [],
   objects = [],
-}: Pick<AiSessionRunParams<any>, 'system' | 'blueprints' | 'objects'>) =>
+}: Pick<AiSessionRunProps<any>, 'system' | 'blueprints' | 'objects'>) =>
   Effect.gen(function* () {
     const blueprintDefs = yield* Function.pipe(
       blueprints,
       Effect.forEach((blueprint) => Effect.succeed(blueprint.instructions)),
-      Effect.flatMap(Effect.forEach((template) => DatabaseService.loadOption(template.source))),
-      Effect.map(Array.filter(Option.isSome)),
-      Effect.map(
-        Array.map(
-          (template) => trim`
+      Effect.flatMap(
+        Effect.forEach((template) =>
+          Effect.gen(function* () {
+            return trim`
             <blueprint>
-              ${Template.process(template.value.content)}
+              ${yield* Template.processTemplate(template)}
             </blueprint>
-          `,
+          `;
+          }),
         ),
       ),
       Effect.map((blueprints) =>
@@ -76,7 +75,7 @@ export const formatSystemPrompt = ({
 export const formatUserPrompt = ({
   prompt,
   history = [],
-}: Pick<AiSessionRunParams<any>, 'prompt' | 'history'>): Effect.Effect<Message.Message, AiSessionRunError> =>
+}: Pick<AiSessionRunProps<any>, 'prompt' | 'history'>): Effect.Effect<Message.Message, AiSessionRunError> =>
   Effect.gen(function* () {
     const blocks: ContentBlock.Any[] = [];
 

package/src/session/index.ts

@@ -7,5 +7,6 @@ export * from './observer';
 export * from './session';
 export * from './toolkit';
 export * from './version-pin';
+export * from './format';
 
 export * as GenericToolkit from './GenericToolkit';

package/src/session/observer.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+import type * as Tool from '@effect/ai/Tool';
 import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 
@@ -11,7 +12,8 @@ import { type Message } from '@dxos/types';
 /**
  * Live observer of the generation process.
  */
-export interface GenerationObserver extends AiParser.ParseResponseCallbacks {
+export interface GenerationObserver<Tools extends Record<string, Tool.Any> = any>
+  extends AiParser.ParseResponseCallbacks<Tools> {
   /**
    * Complete messages fired during the session, both from the model and from the user.
    * This message will contain all message blocks emitted through the `onBlock` callback.