@dxos/assistant 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/session/Harness.ts

@@ -0,0 +1,241 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as RpcClient from '@effect/rpc/RpcClient';
+import * as Context from 'effect/Context';
+import * as DateTime from 'effect/DateTime';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import type * as Runtime from 'effect/Runtime';
+import type * as Scope from 'effect/Scope';
+
+import { LayerSpec, Process, ServiceNotAvailableError } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Annotation, Database, EID, Feed, Filter, Obj, type URI } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { BaseError } from '@dxos/errors';
+import { type ContentBlock, Message } from '@dxos/types';
+
+import * as AiContext from './AiContext';
+import { type HarnessControlRpcs } from './harness-control';
+import { SessionLoader } from './SessionLoader';
+
+export interface Service {
+  /** The conversation {@link AiContext.Binder} (Tier A). */
+  binder: Effect.Effect<AiContext.Binder, NotSupportedError>;
+  /** The conversation message history (Tier A). */
+  history: Effect.Effect<Message.Message[], NotSupportedError>;
+  /** Objects bound to the conversation that match the filter (Tier A). */
+  queryContext<T extends Obj.Unknown>(filter: Filter.Filter<T>): Effect.Effect<T[], NotSupportedError>;
+  /** Enqueue a message into the owning host's input queue (Tier B). */
+  enqueueMessage(options: EnqueueMessageOptions): Effect.Effect<void, NotSupportedError>;
+  /** Schedule a self-wake on the owning host (Tier B). */
+  setAlarm(options: SetAlarmOptions): Effect.Effect<void, NotSupportedError>;
+}
+
+/**
+ * Provides access to the controlling harness for tools and operations that are executed by the agent.
+ *
+ * Replaces AiContextService and AiSessionService.
+ */
+export class HarnessService extends Context.Tag('@dxos/assistant/HarnessService')<HarnessService, Service>() {}
+
+/**
+ * Acess current context binder.
+ */
+export const binder: Effect.Effect<AiContext.Binder, NotSupportedError, HarnessService> = Effect.flatMap(
+  HarnessService,
+  (service) => service.binder,
+);
+
+/**
+ * Query the context using a filter.
+ */
+export const queryContext = <T extends Obj.Unknown>(
+  filter: Filter.Filter<T>,
+): Effect.Effect<T[], NotSupportedError, HarnessService> =>
+  Effect.flatMap(HarnessService, (service) => service.queryContext(filter));
+
+interface EnqueueMessageOptions {
+  content: ContentBlock.Any[];
+
+  // TODO(dmaretskyi): Order: 'first' | 'last'
+}
+
+/**
+ * Query the session history.
+ */
+export const history: Effect.Effect<Message.Message[], NotSupportedError, HarnessService> = Effect.flatMap(
+  HarnessService,
+  (service) => service.history,
+);
+
+/**
+ * Enqueue a message to the harness.
+ */
+export const enqueueMessage = (
+  options: EnqueueMessageOptions,
+): Effect.Effect<void, NotSupportedError, HarnessService> =>
+  Effect.flatMap(HarnessService, (service) => service.enqueueMessage(options));
+
+interface SetAlarmOptions {
+  at: DateTime.DateTime;
+  /**
+   * Message to send when the alarm fires.
+   */
+  message: string | null;
+}
+
+export const setAlarm = (options: SetAlarmOptions): Effect.Effect<void, NotSupportedError, HarnessService> =>
+  Effect.flatMap(HarnessService, (service) => service.setAlarm(options));
+
+/**
+ * Binds skills and/or objects to the conversation context.
+ */
+export const bindContext = ({
+  skills,
+  objects,
+}: AiContext.BindingProps): Effect.Effect<void, NotSupportedError, HarnessService> =>
+  Effect.gen(function* () {
+    const sessionBinder = yield* binder;
+    yield* Effect.promise(() => sessionBinder.bind({ skills, objects }));
+  });
+
+export class NotSupportedError extends BaseError.extend('NotSupportedError', 'Operation not supported') {}
+
+/**
+ * Process-affinity {@link LayerSpec} that materialises {@link HarnessService} from the resolution
+ * context's `conversation` DXN. Merges the former `AiContext.Service` (Tier A) with live host
+ * dispatch (Tier B).
+ */
+export const layerSpec: LayerSpec.LayerSpec = LayerSpec.make(
+  {
+    affinity: 'process',
+    requires: [Database.Service, ProcessManager.Service],
+    provides: [HarnessService],
+  },
+  (context) =>
+    Layer.scoped(
+      HarnessService,
+      Effect.gen(function* () {
+        if (!context.conversation) {
+          // LayerSpec.make requires a never-failing layer (error channel = never), so typed failure
+          // is not possible here. Die with ServiceNotAvailableError to signal a programming error
+          // (missing 'conversation' in spawn environment) that callers cannot recover from.
+          return yield* Effect.die(
+            new ServiceNotAvailableError(HarnessService.key, {
+              message: `Service not available: ${HarnessService.key} — process spawn is missing 'conversation' in environment (set via Operation.withInvocationOptions or ProcessManager.spawn environment)`,
+            }),
+          );
+        }
+        const conversation = context.conversation;
+        const processManager = yield* ProcessManager.Service;
+        const runtime = yield* Effect.runtime<Database.Service>();
+        return yield* make({ conversation, processManager, runtime });
+      }),
+    ),
+);
+
+interface MakeOptions {
+  conversation: URI.URI;
+  processManager: Context.Tag.Service<ProcessManager.Service>;
+  runtime: Runtime.Runtime<Database.Service>;
+}
+
+/**
+ * Builds the {@link Service} for a conversation-scoped resolution context. Tier A resolves the
+ * conversation feed / {@link AiContext.Binder} once; Tier B looks up the owning host process lazily per call
+ * and dispatches over its `Handle.rpc` control surface (raising {@link NotSupportedError} when no
+ * live host owns the conversation).
+ */
+export const make = ({
+  conversation,
+  processManager,
+  runtime,
+}: MakeOptions): Effect.Effect<Service, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const feed = yield* Database.resolve(EID.parse(conversation), Feed.Feed).pipe(
+      Effect.provide(runtime),
+      Effect.orDie,
+    );
+    const boundBinder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+    return makeService({
+      feed,
+      runtime,
+      binder: boundBinder,
+      owningHost: lookupOwningHost(processManager, conversation),
+    });
+  });
+
+interface FromBinderOptions {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Database.Service>;
+  binder: AiContext.Binder;
+}
+
+/**
+ * Builds the {@link Service} from a {@link AiContext.Binder} already opened for the conversation (e.g. the
+ * agent's own turn fiber, which has no `ProcessManager.Service` in scope). Tier A is fully served;
+ * Tier B raises {@link NotSupportedError} since the live-host control surface is not reachable here.
+ */
+export const fromBinder = ({ feed, runtime, binder }: FromBinderOptions): Service =>
+  makeService({ feed, runtime, binder, owningHost: Effect.fail(new NotSupportedError()) });
+
+interface MakeServiceOptions {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Database.Service>;
+  binder: AiContext.Binder;
+  owningHost: Effect.Effect<RpcClient.RpcClient<HarnessControlRpcs>, NotSupportedError>;
+}
+
+const makeService = ({ feed, runtime, binder, owningHost }: MakeServiceOptions): Service => ({
+  binder: Effect.succeed(binder),
+  history: Effect.gen(function* () {
+    const messages = yield* Feed.query(feed, Filter.type(Message.Message)).run;
+    return yield* new SessionLoader().reifyHistory(feed, messages);
+  }).pipe(Effect.provide(runtime)),
+  queryContext: <T extends Obj.Unknown>(filter: Filter.Filter<T>) =>
+    Effect.sync(() => {
+      const match = Filter.toPredicate(filter);
+      return binder.getObjects().filter(match);
+    }),
+  enqueueMessage: ({ content }) => owningHost.pipe(Effect.flatMap((rpc) => rpc.enqueueMessage({ content }))),
+  setAlarm: ({ at, message }) =>
+    owningHost.pipe(Effect.flatMap((rpc) => rpc.setAlarm({ at: DateTime.toUtc(at), message }))),
+});
+
+/**
+ * Resolves the live host owning `conversation` per call (so a process replacement — e.g. a model
+ * switch — is never captured stale) and exposes its `HarnessControl` RPC client.
+ */
+const lookupOwningHost = (
+  processManager: Context.Tag.Service<ProcessManager.Service>,
+  conversation: URI.URI,
+): Effect.Effect<RpcClient.RpcClient<HarnessControlRpcs>, NotSupportedError> =>
+  Effect.gen(function* () {
+    const processes = yield* processManager.list({ target: conversation });
+    const host = processes.find(
+      (process) =>
+        !isTerminalProcess(process.status.state) &&
+        Option.getOrElse(
+          Annotation.getDictionary(process.params.annotations, Process.HarnessHostAnnotation),
+          () => false,
+        ),
+    );
+    if (!host) {
+      return yield* Effect.fail(new NotSupportedError());
+    }
+    // The host is discovered by annotation, but the HarnessControl RPC contract is fixed at the
+    // spawn site (agent-process declares it as its `rpcs`); narrow the variance-erased
+    // `RpcClient<any>` to that contract so the dispatch below is typed. No typed path exists here:
+    // the host handle carries `RpcClient<any>` (design spec §4.4) and the concrete definition lives
+    // in `@dxos/functions-runtime`, which depends on this package — importing it would cycle.
+    return host.rpc as unknown as RpcClient.RpcClient<HarnessControlRpcs>;
+  });
+
+const isTerminalProcess = (state: Process.State): boolean =>
+  state === Process.State.SUCCEEDED || state === Process.State.FAILED || state === Process.State.TERMINATED;

package/src/session/SessionLink.ts

@@ -13,11 +13,11 @@ import { DXN, Feed, Obj, Ref, Type } from '@dxos/echo';
  * When present in a feed, the messages from the referenced feed up to and including
  * `messageId` are prepended to the conversation history before each turn.
  */
-export const SessionLink = Schema.Struct({
-  /** Reference to the feed of the source session. */
-  feedRef: Ref.Ref(Feed.Feed),
-  /** Messages from the source feed up to and including this message ID are injected. */
-  messageId: Obj.ID,
-}).pipe(Type.makeObject(DXN.make('org.dxos.type.sessionLink', '0.1.0')));
-
-export type SessionLink = Type.InstanceType<typeof SessionLink>;
+export class SessionLink extends Type.makeObject<SessionLink>(DXN.make('org.dxos.type.sessionLink', '0.1.0'))(
+  Schema.Struct({
+    /** Reference to the feed of the source session. */
+    feedRef: Ref.Ref(Feed.Feed),
+    /** Messages from the source feed up to and including this message ID are injected. */
+    messageId: Obj.ID,
+  }),
+) {}

package/src/session/SessionLoader.ts

@@ -4,7 +4,7 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Feed, Filter, Obj } from '@dxos/echo';
+import { Database, Feed, Filter, Obj } from '@dxos/echo';
 import { Message } from '@dxos/types';
 
 import * as SessionLink from './SessionLink';
@@ -21,9 +21,9 @@ export class SessionLoader {
   reifyHistory(
     feed: Feed.Feed,
     messages: Message.Message[],
-  ): Effect.Effect<Message.Message[], never, Feed.FeedService> {
+  ): Effect.Effect<Message.Message[], never, Database.Service> {
     return Effect.gen(function* () {
-      const links = yield* Feed.runQuery(feed, Filter.type(SessionLink.SessionLink));
+      const links = yield* Feed.query(feed, Filter.type(SessionLink.SessionLink)).run;
       const sessionLinks = links.filter(Obj.instanceOf(SessionLink.SessionLink));
 
       const link = sessionLinks[0];
@@ -36,7 +36,7 @@ export class SessionLoader {
         return messages;
       }
 
-      const sourceMessages = yield* Feed.runQuery(sourceFeed, Filter.type(Message.Message));
+      const sourceMessages = yield* Feed.query(sourceFeed, Filter.type(Message.Message)).run;
       const filtered = sourceMessages.filter(Obj.instanceOf(Message.Message));
 
       // Sort by creation timestamp so history is in chronological order.

package/src/session/SkillHooks.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+
+import { Operation, Skill } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+
+/**
+ * Tag of the lifecycle point a hook fires at, matching {@link Skill.HookSpec}.
+ */
+export type HookPhase = 'begin-request' | 'end-request';
+
+/**
+ * Invokes a resolved operation with the hook's templated input. Begin and end hooks fire in
+ * different contexts (the agent's turn fiber vs. a child process with Tier B reachable), so the
+ * invocation strategy is supplied by the caller rather than fixed here. `R` carries the invoker's
+ * own requirements (e.g. `Operation.Service`) up into {@link runHooks}.
+ */
+export type HookInvoker<R> = (
+  operation: Operation.Definition.Any,
+  input: Record<string, unknown>,
+) => Effect.Effect<void, never, R>;
+
+/**
+ * Runs every {@link Skill.Hook} on `skills` whose spec matches `phase`. Each hook resolves its
+ * `function` ref to a {@link Operation.PersistentOperation}, deserializes it to a definition, and
+ * invokes it with the templated `input` via `invoke`. Hooks without a function ref are skipped.
+ *
+ * Hook failures are isolated: a throwing hook logs and is swallowed so one skill's hook cannot
+ * abort the request lifecycle (or the sibling hooks).
+ */
+export const runHooks = <R>({
+  skills,
+  phase,
+  invoke,
+}: {
+  skills: readonly Skill.Skill[];
+  phase: HookPhase;
+  invoke: HookInvoker<R>;
+}): Effect.Effect<void, never, Database.Service | R> =>
+  Effect.gen(function* () {
+    for (const skill of skills) {
+      for (const hook of skill.hooks ?? []) {
+        if (hook.spec._tag !== phase) {
+          continue;
+        }
+        if (!hook.function) {
+          continue;
+        }
+
+        yield* Effect.gen(function* () {
+          const record = yield* Database.load(hook.function!);
+          invariant(Obj.instanceOf(Operation.PersistentOperation, record), 'Hook function must be an operation.');
+          const operation = Operation.deserialize(record);
+          // Hooks carry no event payload (the spec is a bare tag), so the input template is passed
+          // through verbatim — the hook's operation reads any conversation state it needs itself.
+          yield* invoke(operation, { ...hook.input });
+        }).pipe(
+          Effect.catchAllCause((cause) =>
+            Effect.sync(() => log.warn('skill hook failed', { phase, skill: Skill.getKey(skill), cause })),
+          ),
+        );
+      }
+    }
+  });

package/src/session/harness-control.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Rpc from '@effect/rpc/Rpc';
+import * as RpcGroup from '@effect/rpc/RpcGroup';
+import * as Schema from 'effect/Schema';
+
+import { ContentBlock } from '@dxos/types';
+
+/**
+ * Typed control surface on the live host process that owns a conversation's harness.
+ *
+ * The same group is declared as the agent process's `rpcs` (so its handlers run on the host's
+ * server fiber with the live `AlarmManager`/`inputQueue` in scope) and used by {@link HarnessService}
+ * Tier B to dispatch over the discovered host's `Handle.rpc` — keeping both ends on one contract.
+ */
+export const HarnessControl = RpcGroup.make(
+  Rpc.make('setAlarm', {
+    payload: Schema.Struct({ at: Schema.DateTimeUtc, message: Schema.NullOr(Schema.String) }),
+    success: Schema.Void,
+  }),
+  Rpc.make('enqueueMessage', {
+    payload: Schema.Struct({ content: Schema.Array(ContentBlock.Any) }),
+    success: Schema.Void,
+  }),
+);
+
+/** Union of the RPCs declared in {@link HarnessControl}. */
+export type HarnessControlRpcs = RpcGroup.Rpcs<typeof HarnessControl>;

package/src/session/index.ts

@@ -6,5 +6,8 @@ export * from './toolkit';
 
 export * as AiContext from './AiContext';
 export * as AiSession from './AiSession';
+export * as Harness from './Harness';
+export * as SkillHooks from './SkillHooks';
+export { HarnessControl, type HarnessControlRpcs } from './harness-control';
 export { SessionLoader } from './SessionLoader';
 export * as SessionLink from './SessionLink';

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.

package/dist/types/src/functions/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/functions/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAC"}