@dxos/assistant 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/session/toolkit.ts

@@ -7,12 +7,12 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 
 import { type AiToolNotFoundError, OpaqueToolkit, ToolExecutionService, ToolResolverService } from '@dxos/ai';
-import { type Blueprint } from '@dxos/compute';
+import { type Skill } from '@dxos/compute';
 import { isTruthy } from '@dxos/util';
 
 export type CreateToolkitProps = {
   toolkit?: OpaqueToolkit.Any;
-  blueprints?: readonly Blueprint.Blueprint[];
+  skills?: readonly Skill.Skill[];
   /**
    * Self-contained with handlers toolkits.
    */
@@ -20,11 +20,11 @@ export type CreateToolkitProps = {
 };
 
 /**
- * Build a combined toolkit from the blueprint tools and the provided toolkit.
+ * Build a combined toolkit from the skill tools and the provided toolkit.
  */
 export const createToolkit = ({
   toolkit: toolkitProp,
-  blueprints = [],
+  skills = [],
   opaqueToolkits = [],
 }: CreateToolkitProps): Effect.Effect<
   OpaqueToolkit.OpaqueToolkit,
@@ -32,14 +32,14 @@ export const createToolkit = ({
   ToolResolverService | ToolExecutionService
 > =>
   Effect.gen(function* () {
-    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
-    const blueprintToolHandler = yield* blueprintToolkit.toContext(ToolExecutionService.handlersFor(blueprintToolkit));
+    const skillToolkit = yield* ToolResolverService.resolveToolkit(skills.flatMap(({ tools }) => tools));
+    const skillToolHandler = yield* skillToolkit.toContext(ToolExecutionService.handlersFor(skillToolkit));
     const opaqueToolkit = OpaqueToolkit.merge(...opaqueToolkits);
 
-    const toolkitDefs = [toolkitProp?.toolkit, blueprintToolkit, opaqueToolkit.toolkit].filter(isTruthy);
+    const toolkitDefs = [toolkitProp?.toolkit, skillToolkit, opaqueToolkit.toolkit].filter(isTruthy);
     const mergedToolkit = Toolkit.merge(...toolkitDefs);
     const combinedHandlerLayer = Layer.mergeAll(
-      Layer.succeedContext(blueprintToolHandler),
+      Layer.succeedContext(skillToolHandler),
       toolkitProp?.layer ?? OpaqueToolkit.empty.layer,
       opaqueToolkit.layer,
     );

package/src/templates/instructions/format.tpl

@@ -2,10 +2,10 @@
 
 ## Input Formats
 
-### Blueprints
+### Skills
 
-You may be provided with Blueprint definitions that include specific instructions and tools for a given set of tasks.
-Blue print instructions will be enclosed in a <blueprint> tag.
+You may be provided with Skill definitions that include specific instructions and tools for a given set of tasks.
+Blue print instructions will be enclosed in a <skill> tag.
 
 ### Context objects
 

package/src/templates/instructions/system.tpl

@@ -12,20 +12,20 @@
 ## Planning
 
 - Analyze the structure and type of the content in the user's message.
-- Determine if you complete the task using the available blueprint definitions?
-- If you can't complete the task using the available blueprint definitions, query the list of available blueprint definitions using the appropriate tool.
-- Identify which blueprint definitions are relevant to the user's request.
+- Determine if you complete the task using the available skill definitions?
+- If you can't complete the task using the available skill definitions, query the list of available skill definitions using the appropriate tool.
+- Identify which skill definitions are relevant to the user's request.
 - Evaluate the potential benefits of creating an artifact vs. normal processing for each identified element.
 - Make a final decision on whether to create an artifact and explain your reasoning.
-- Are the required blueprint definitions already available?
-- If not, select which blueprint definition(s) will be the most relevant and require them using the require_artifact_definitions tool.
+- Are the required skill definitions already available?
+- If not, select which skill definition(s) will be the most relevant and require them using the require_artifact_definitions tool.
 - The require'd artifact tools will be available for use after require.
 - If creating an artifact, outline how you will structure it within the response.
 - Decide if the artifact needs to be shown to the user.
 - Call the show tool to show the artifact to the user.
 - Your reasoning must include: whether to use artifacts or not, to create one or query, whether to show the artifact to the user, and how to structure the response.
 
-## Blueprints and Artifacts
+## Skills and Artifacts
 
 - Determine if the interaction involves an artifact. Prefer artifacts for tables, lists, spreadsheets, kanbans, games, images, and other structured data.
 - Determine if the user is explicitly talking about creating a new artifact, or wants to use an existing artifact.
@@ -45,12 +45,10 @@
 
 ## Navigation
 
-- When the user asks to open, go to, navigate to, or show a specific document, page, or object, use the navigation tools instead of loading content inline.
-- First, call the Resolve navigation targets tool to find the navigation path for the requested item.
-  - Without arguments, it returns available pages that can be navigated to.
-  - With a DXN in the query, it resolves that specific object to a navigation path.
-- If you know the object's DXN (e.g. from a database query or context objects), pass it in the query to get the exact navigation path.
-- Then, call the Open tool with the resolved navigation path(s) in the subject array to navigate the user to that item.
+- When the user asks to open, go to, navigate to, or show a specific document, page, or object, use the navigation tools instead of loading content inline. Navigation is always two steps: first resolve a navigation path with Resolve navigation targets, then open that path with Open.
+- The Open tool accepts navigation **paths** only. Never pass an object DXN, URI, or id to Open — pass only a `path` returned by Resolve navigation targets. Passing anything else will fail to navigate.
+- To open a specific object: call Resolve navigation targets with the object's URI in the `query.uri` field — use the value from the object's `<dxn>` tag in context (which may be an `echo:` EID or a `dxn:` DXN), then pass the returned target's `path` to Open.
+- To navigate to a page (not a specific object): call Resolve navigation targets without arguments to list the available pages, then pass the chosen target's `path` to Open.
 - Do not respond with the document's content when the user asks to open it — open it in the main content area instead.
 - If multiple targets match, present the options to the user and let them choose which to open.
 

package/src/templates/system.ts

@@ -4,8 +4,12 @@
 
 import defaultsDeep from 'lodash.defaultsdeep';
 
-import { type ModelCapabilities } from '@dxos/ai';
+import { Model } from '@dxos/ai';
 import { Template } from '@dxos/compute';
+// Text is referenced in the inferred type of 'templates' (via Template.make → Template.Template.source → Ref.Ref(Text.Text));
+// the import lets TypeScript name it in the emitted .d.ts.
+// eslint-disable-next-line unused-imports/no-unused-imports
+import { type Text } from '@dxos/schema';
 
 import FORMAT from './instructions/format.tpl?raw';
 import SYSTEM from './instructions/system.tpl?raw';
@@ -13,7 +17,7 @@ import SYSTEM from './instructions/system.tpl?raw';
 /**
  * System template variables.
  */
-export type SystemPromptOptions = ModelCapabilities & {
+export type SystemPromptOptions = Model.Capabilities & {
   DATETIME: string;
 };
 

package/src/util/artifact.ts

@@ -88,8 +88,15 @@ type ArtifactURI = Schema.Schema.Type<typeof ArtifactURI>;
  * Schema that decodes ECHO reference object from an LLM-friendly input.
  */
 export const RefFromLLM = Schema.transform(ArtifactURI, Ref.Ref(Obj.Unknown), {
-  decode: (fromA, fromI) => EncodedReference.fromURI(ArtifactURI.toEchoURI(fromA)),
-  encode: (toI, toA) => EncodedReference.toURI(toI),
+  decode: (fromA) => {
+    const eid = ArtifactURI.toEchoURI(fromA);
+    // Normalize to local form: strip any space authority so the ref resolves within the current
+    // space context. The AI commonly sends echo://SPACE/ENTITY format (mirroring what it sees in
+    // the database context), but cross-space resolution is not yet supported and the space ID
+    // encoded in the URI is always the current space anyway.
+    return EncodedReference.fromURI(EID.toLocal(eid));
+  },
+  encode: (toI) => EncodedReference.toURI(toI),
   strict: false,
 }).annotations({
   description: ArtifactURI.ast.annotations.description as string,

package/src/util/diff.test.ts

@@ -4,8 +4,8 @@
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
-import { createDocAccessor } from '@dxos/echo-client';
 import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { Doc } from '@dxos/echo-doc';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
@@ -32,7 +32,7 @@ describe('diff', () => {
     `;
 
     const text = db.add(Text.make({ content: document }));
-    const accessor = createDocAccessor(text, ['content']);
+    const accessor = Doc.createAccessor(text, ['content']);
     const result = applyDiffs(accessor, [
       `- There'z a typo in this sentence.`,
       `+ There is a typo in this sentence.`,
@@ -54,7 +54,7 @@ describe('diff', () => {
     const document = '# Shopping list';
 
     const text = db.add(Text.make({ content: document }));
-    const accessor = createDocAccessor(text, ['content']);
+    const accessor = Doc.createAccessor(text, ['content']);
     const result = applyDiffs(accessor, ['- # Shopping list', '+ # Shopping list\n- Milk']);
 
     expect(result).toBe('# Shopping list\n- Milk');
@@ -66,7 +66,7 @@ describe('diff', () => {
     graph.registry.add([Text.Text]);
 
     const text = db.add(Text.make({ content: '' }));
-    const accessor = createDocAccessor(text, ['content']);
+    const accessor = Doc.createAccessor(text, ['content']);
     const result = applyDiffs(accessor, ['+ # Shopping list']);
 
     expect(result).toBe('# Shopping list');

package/src/util/diff.ts

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { next as A, type Doc } from '@automerge/automerge';
+import { next as A, type Doc as AutomergeDoc } from '@automerge/automerge';
 
-import { DocAccessor, toCursorRange } from '@dxos/echo-client';
+import { toCursorRange } from '@dxos/echo-client';
+import { Doc } from '@dxos/echo-doc';
 import { log } from '@dxos/log';
 import { isNonNullable } from '@dxos/util';
 
@@ -54,10 +55,13 @@ export const reduceDiffs = (diffs: readonly string[]): Diff[] => {
   }, []);
 };
 
-export const computeDiffsWithCursors = <T>(accessor: DocAccessor<T>, diffs: readonly string[]) => {
+/**
+ * Resolves text diffs against the accessor's current value into cursor-anchored replacements.
+ */
+export const computeDiffsWithCursors = <T>(accessor: Doc.Accessor<T>, diffs: readonly string[]) => {
   return reduceDiffs(diffs)
     .map((diff) => {
-      const text = DocAccessor.getValue<string>(accessor);
+      const text = Doc.getValue<string>(accessor);
       const idx = text.indexOf(diff.match);
       if (idx !== -1) {
         return { cursor: toCursorRange(accessor, idx, idx + diff.match.length), text: diff.replace };
@@ -66,14 +70,17 @@ export const computeDiffsWithCursors = <T>(accessor: DocAccessor<T>, diffs: read
     .filter(isNonNullable);
 };
 
+/**
+ * Applies text diffs to the accessor-backed document and returns the resulting string.
+ */
 export const applyDiffs = <T>(
-  accessor: DocAccessor<T>,
+  accessor: Doc.Accessor<T>,
   diffs: readonly string[],
   { errorOnNotFound = false }: { errorOnNotFound?: boolean } = {},
 ): string => {
   for (const diff of reduceDiffs(diffs)) {
-    accessor.handle.change((doc: Doc<T>) => {
-      const text = DocAccessor.getValue<string>(accessor);
+    accessor.handle.change((doc: AutomergeDoc<T>) => {
+      const text = Doc.getValue<string>(accessor);
       const idx = text.indexOf(diff.match);
       if (idx !== -1) {
         // TODO(burdon): Replace smallest substring.
@@ -89,5 +96,5 @@ export const applyDiffs = <T>(
     });
   }
 
-  return DocAccessor.getValue<string>(accessor);
+  return Doc.getValue<string>(accessor);
 };

package/src/util/tracing.ts

@@ -6,7 +6,7 @@ import * as Schema from 'effect/Schema';
 
 import { Trace } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
-import { ContentBlock, Actor } from '@dxos/types';
+import { Actor, ContentBlock } from '@dxos/types';
 
 /**
  * Partial content block emitted.