@dxos/assistant 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/session/version-pin.ts

@@ -2,12 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
-import { type MessageContentBlock } from '@dxos/ai';
-import { type ObjectVersion } from '@dxos/echo-db';
-import { getVersion } from '@dxos/echo-db';
-import { ObjectId, type BaseEchoObject } from '@dxos/echo-schema';
+import { type Obj } from '@dxos/echo';
+import { type ObjectVersion, getVersion } from '@dxos/echo-db';
+import { ObjectId } from '@dxos/keys';
+import { type ContentBlock } from '@dxos/types';
 
 // TODO(dmaretskyi): Extract.
 const ObjectVersionSchema = Schema.Unknown as Schema.Schema<ObjectVersion>;
@@ -15,7 +15,7 @@ const ObjectVersionSchema = Schema.Unknown as Schema.Schema<ObjectVersion>;
 const VersionPinSchema = Schema.Struct({
   // TODO(dmaretskyi): Use Ref when those support encoding.
   objectId: ObjectId,
-  // TODO(dmaretskyi): Could be opaque
+  // TODO(dmaretskyi): Could be opaque.
   version: ObjectVersionSchema,
 });
 
@@ -27,22 +27,22 @@ export interface VersionPin extends Schema.Schema.Type<typeof VersionPinSchema>
 
 export const VersionPin: typeof VersionPinSchema & {
   DISPOSITION: 'version-pin';
-  fromObject: (object: BaseEchoObject) => VersionPin;
-  createBlock: (pin: VersionPin) => MessageContentBlock;
+  fromObject: (object: Obj.Unknown) => VersionPin;
+  createBlock: (pin: VersionPin) => ContentBlock.Any;
 } = class extends VersionPinSchema {
   static readonly DISPOSITION = 'version-pin';
-  static fromObject(object: BaseEchoObject): VersionPin {
+  static fromObject(object: Obj.Unknown): VersionPin {
     return VersionPin.make({
       objectId: object.id,
       version: getVersion(object),
     });
   }
 
-  static createBlock(pin: VersionPin): MessageContentBlock {
+  static createBlock(pin: VersionPin): ContentBlock.Any {
     return {
-      type: 'json',
+      _tag: 'json',
       disposition: VersionPin.DISPOSITION,
-      json: JSON.stringify(pin),
+      data: JSON.stringify(pin),
     };
   }
 };

package/src/templates/index.ts

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

package/src/templates/instructions/format.tpl

@@ -0,0 +1,57 @@
+{{! System Core }}
+
+## Input Formats
+
+### Blueprints
+
+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.
+
+### Context objects
+
+You may be provided with references to objects that are relevant to the current prompt.
+Objects will be in the form of a <object> tag with a <dxn> element that is the unique key of the object required by many tools.
+The <typename> element is the type of the object.
+
+<object>
+  <dxn>object-id</dxn>
+  <typename>example.com/type/TypeName</typename>
+</object>
+
+## Response Formats
+
+It is very important to respond in the correct format.
+You response must be valid Markdown.
+In some cases you should respond with well-formed XML tags along with the content.
+Code snippets should use 2-space indents.
+
+{{#if cot}}
+Before responding, explain your reasoning and include your detailed chain-of-thought enclosed in a <cot> tag.
+The <cot> tag should be the first thing in your response.
+{{/if}}
+
+## Block references
+
+You can reply with a block reference for objects if you have the DXN. For example:
+
+<object>
+  <dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK464FSCKVQJAB2H662M</dxn>
+</object>
+<object>
+  <dxn>dxn:echo:@:01K24XPK464FSCKVQJAB2H662M</dxn>
+</object>
+
+### Suggestions
+
+Each suggestion must in the form of a proposed action enclosed in a <suggestion> tag.
+Example: <suggestion>Show on a map</suggestion>
+Do not use bullets when listing suggestions.
+
+### Multiple choice questions
+
+You may ask multiple choice questions by wrapping consise options inside <option> tags inside a well formed <select> tag.
+Example: <select><option>Yes</option><option>No</option></select>
+
+## Context
+
+The current date and time is {{DATETIME}}.

package/src/templates/instructions/system.tpl

@@ -0,0 +1,85 @@
+{{! System Prompt }}
+
+- You are a helpful assistant called Kai. 
+- Your name is Kai and you are powered by different language models.
+- You were created by DXOS and operate inside of Composer and on the DXOS EDGE network.
+- In your initial greeting state your name and make some suggestions based on the current context objects.
+- You are an advanced AI assistant capable of creating and managing artifacts from provided data and tools.
+- Your task is to process user commands and questions and decide how best to respond.
+- In general be concise and direct.
+- Follow all instructions carefully.
+
+## 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.
+- 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.
+- 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
+
+- 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.
+- If it is ambiguous, query for existing artifacts first and then decide.
+- If you decide to create an artifact, call the associated tool to create the artifact.
+- Artifacts are stored in the database. Tools are used to create and query artifacts.
+- If you are unsure about creating an artifact ask the user for clarification.
+- Artifacts are mutable objects that can change over the course of the conversation.
+- Always re-query the artifact using the tool (like query or inspect) to get the latest state of the artifact before answering the user.
+- You must never generate the id of the artifact; only recall the ids that are already in the history.
+- Artifacts are created by requiring the specific artifact using the require_artifact tool and creating it by calling the associated tool.
+- You can add suggested actions at the end of your response.
+- Suggested actions should be very concise and start with a verb and be phrased as a command to an agent -- not a question to the user.
+- Suggested actions must be in the form of a user instruction that you can follow.
+- Suggested actions could include actions that create artifacts.
+- After creating an artifact use a tool to add it to the chat context.
+
+## 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.
+- 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.
+
+## Response format
+
+- When updating the user about the progress of the work you are doing, put the update in a <status> XML tag.
+- Only when you need to show the result to the user or ask a question use a text block without status tags.
+
+<example>
+// reasoning...
+<status>Looking for emails from Depot</status>
+// tool call..
+<status>Found 2 emails from Depot.</status>
+<status>Loading email details</status>
+// tool call
+<status>Located mailbox</status>
+I found **2 emails from Depot**:
+</example>
+
+Do not do (no status tags):
+
+<incorrect_example>
+// reasoning...
+// tool call..
+I found 2 emails from Depot. Let me load their details:
+// tool call
+I found **2 emails from Depot**:
+</incorrect_example>
+
+- Avoid using plain text to tell the user what you are about to do; instead, use status blocks.
+- WRONG: Let me get...
+- CORRECT: <status>Getting...</status>

package/src/templates/system.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import defaultsDeep from 'lodash.defaultsdeep';
+
+import { type ModelCapabilities } from '@dxos/ai';
+import { Template } from '@dxos/blueprints';
+
+import FORMAT from './instructions/format.tpl?raw';
+import SYSTEM from './instructions/system.tpl?raw';
+
+/**
+ * System template variables.
+ */
+export type SystemPromptOptions = ModelCapabilities & {
+  DATETIME: string;
+};
+
+/**
+ * Base system prompt.
+ * NOTE: This contains protocol instructions that can not be dynamically edited.
+ */
+export const createSystemPrompt = (options: Partial<SystemPromptOptions> = {}) =>
+  Template.process<SystemPromptOptions>(
+    FORMAT,
+    defaultsDeep(options, {
+      DATETIME: new Date().toISOString(),
+    }),
+  );
+
+/**
+ * NOTE: We are forbidden from accessing randomness at model level in cloudflare, so we have to have pre-generated ids.
+ */
+const SYSTEM_ID = '01K2J2FZWH39F55CS7B26GP1Q3';
+
+export const templates = {
+  system: Template.make({
+    id: SYSTEM_ID,
+    source: SYSTEM,
+  }),
+};

package/src/testing/index.ts

@@ -1,11 +1,5 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import type { SearchResponse } from 'exa-js';
-
-import Search1 from './exa-search-1748337321991';
-import Search2 from './exa-search-1748337331526';
-import Search3 from './exa-search-1748337344119';
-
-export const SEARCH_RESULTS: SearchResponse<any>[] = [Search1, Search2, Search3];
+export * from './layer';

package/src/testing/layer.ts

@@ -0,0 +1,236 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom';
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import * as Array from 'effect/Array';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Match from 'effect/Match';
+
+import { AiService, ConsolePrinter, OpaqueToolkit, type ModelName } from '@dxos/ai';
+import { TestAiService } from '@dxos/ai/testing';
+import { Blueprint, Prompt } from '@dxos/blueprints';
+import { Database, DXN, Feed, Tag, Type } from '@dxos/echo';
+import { acquireReleaseResource } from '@dxos/effect';
+import type { TestContextService } from '@dxos/effect/testing';
+import {
+  CredentialsService,
+  QueueService,
+  type ServiceCredential,
+  ServiceNotAvailableError,
+  Trace,
+  Trigger,
+} from '@dxos/functions';
+import {
+  FeedTraceSink,
+  Process,
+  ProcessManager,
+  ServiceResolver,
+  TriggerDispatcher,
+  TriggerStateStore,
+} from '@dxos/functions-runtime';
+import { TestDatabaseLayer } from '@dxos/functions-runtime/testing';
+import { Operation, OperationHandlerSet, OperationRegistry } from '@dxos/operation';
+
+import { AiContextBinder, AiContextService, AiSession, AiSessionService } from '../conversation';
+import { AgentService } from '../service';
+import { CompleteBlock } from '../tracing';
+
+interface TestLayerOptions {
+  aiServicePreset?: 'direct' | 'edge-local' | 'edge-remote' | 'ollama';
+  model?: ModelName;
+  operationHandlers?: OperationHandlerSet.OperationHandlerSet | OperationHandlerSet.OperationHandlerSet[];
+  toolkits?: OpaqueToolkit.OpaqueToolkit[];
+  types?: Type.AnyEntity[];
+  blueprints?: Blueprint.Blueprint[];
+  credentials?: ServiceCredential[];
+  /**
+   * Tracing configuration.
+   * - `'feed'` persists trace events to a FeedTraceSink (queryable from the database).
+   * @default 'noop'
+   */
+  tracing?: 'noop' | 'console' | 'pretty' | 'feed';
+
+  disableLlmMemoization?: boolean;
+
+  /**
+   * Core system prompt for the agent.
+   */
+  systemPrompt?: string;
+}
+
+export type AssistantTestServices =
+  // Convinience
+  | LanguageModel.LanguageModel
+  | Feed.FeedService
+  | CredentialsService
+  | AgentService.AgentService
+  | AiService.AiService
+  | Database.Service
+  | QueueService
+  // Registries
+  | Blueprint.RegistryService
+  | OperationRegistry.Service
+  | OpaqueToolkit.OpaqueToolkitProvider
+  | Operation.Service
+  // Core
+  | ProcessManager.ProcessManagerService
+  | Process.ProcessMonitorService
+  | Registry.AtomRegistry
+  // Should those be here?
+  | OperationHandlerSet.OperationHandlerProvider
+  | KeyValueStore.KeyValueStore
+  | ServiceResolver.ServiceResolver
+  | Trace.TraceService
+  | Trace.TraceSink
+  | FeedTraceSink.FeedTraceSink;
+
+export const AssistantTestLayer = ({
+  aiServicePreset = 'direct',
+  model,
+  operationHandlers = [],
+  toolkits = [],
+  types = [],
+  credentials = [],
+  tracing = 'noop',
+  disableLlmMemoization = false,
+  blueprints = [],
+  systemPrompt,
+}: TestLayerOptions = {}): Layer.Layer<AssistantTestServices, never, TestContextService> => {
+  const resolvedModel: ModelName =
+    model ?? (aiServicePreset === 'ollama' ? 'gpt-oss:20b' : '@anthropic/claude-opus-4-6');
+  const toolkit = OpaqueToolkit.merge(...toolkits);
+  const operationHandlersSet = Array.isArray(operationHandlers)
+    ? OperationHandlerSet.merge(...operationHandlers)
+    : operationHandlers;
+  types.push(Blueprint.Blueprint, Prompt.Prompt, Operation.PersistentOperation, Feed.Feed, Trigger.Trigger, Tag.Tag);
+  types = Array.dedupeWith(types, (a, b) => Type.getTypename(a) === Type.getTypename(b));
+
+  return Layer.empty.pipe(
+    Layer.provideMerge(ProcessManager.ProcessOperationInvoker.layer),
+    Layer.provideMerge(Trace.testTraceService({ meta: { processName: 'test' } })),
+    Layer.provideMerge(AgentService.layer({ systemPrompt, model: resolvedModel })),
+    Layer.provideMerge(ProcessManager.layer({ idGenerator: ProcessManager.SequentialProcessIdGenerator })),
+    Layer.provideMerge(
+      // TODO(dmaretskyi): Refactor to be able to merge resovler layers, also consider service mesh achitecture.
+      Layer.effect(
+        ServiceResolver.ServiceResolver,
+        Effect.gen(function* () {
+          const services = yield* Effect.context<Database.Service | Feed.FeedService>().pipe(
+            Effect.map(Context.pick(Database.Service, Feed.FeedService)),
+            Effect.map(Layer.succeedContext),
+          );
+          // AiContextBinder.
+          return ServiceResolver.compose(
+            ServiceResolver.succeed(AiContextService, (context) =>
+              Effect.gen(function* () {
+                if (!context.conversation) {
+                  return yield* Effect.fail(new ServiceNotAvailableError(AiContextService.key));
+                }
+                const feed = yield* Database.resolve(DXN.parse(context.conversation), Feed.Feed).pipe(Effect.orDie);
+                const runtime = yield* Effect.runtime<Feed.FeedService>();
+                const binder = yield* acquireReleaseResource(
+                  () =>
+                    new AiContextBinder({
+                      feed,
+                      runtime,
+                    }),
+                );
+                return { binder };
+              }).pipe(Effect.provide(services)),
+            ),
+            // AiSessionService.
+            ServiceResolver.succeed(AiSessionService, (context) =>
+              Effect.gen(function* () {
+                if (!context.conversation) {
+                  return yield* Effect.fail(new ServiceNotAvailableError(AiSessionService.key));
+                }
+                const feed = yield* Database.resolve(DXN.parse(context.conversation), Feed.Feed).pipe(Effect.orDie);
+                const runtime = yield* Effect.runtime<Feed.FeedService>();
+                const session = yield* acquireReleaseResource(
+                  () =>
+                    new AiSession({
+                      feed,
+                      runtime,
+                    }),
+                );
+                return session;
+              }).pipe(Effect.provide(services)),
+            ),
+            yield* ServiceResolver.fromRequirements(
+              Database.Service,
+              OpaqueToolkit.OpaqueToolkitProvider,
+              Feed.FeedService,
+              AiService.AiService,
+              OperationRegistry.Service,
+              Blueprint.RegistryService,
+              QueueService,
+            ),
+          );
+        }),
+      ),
+    ),
+    Layer.provideMerge(Layer.mergeAll(OperationRegistry.layer, AiService.model(resolvedModel))),
+    Layer.provideMerge(
+      Match.value(tracing).pipe(
+        Match.when('noop', () => Layer.mergeAll(Trace.layerNoop, FeedTraceSink.layerNoop)),
+        Match.when('console', () => Layer.mergeAll(Trace.layerConsole, FeedTraceSink.layerNoop)),
+        Match.when('pretty', () => Layer.mergeAll(TraceSinkPretty(), FeedTraceSink.layerNoop)),
+        Match.when('feed', () => FeedTraceSink.layerLive),
+        Match.exhaustive,
+      ) as Layer.Layer<Trace.TraceSink | FeedTraceSink.FeedTraceSink>,
+    ),
+    Layer.provideMerge(
+      Layer.mergeAll(
+        TestAiService({ preset: aiServicePreset, disableMemoization: disableLlmMemoization }),
+        TestDatabaseLayer({
+          spaceKey: 'fixed',
+          types,
+        }),
+        CredentialsService.configuredLayer(credentials),
+      ),
+    ),
+    Layer.provideMerge(Layer.succeed(Blueprint.RegistryService, new Blueprint.Registry(blueprints))),
+    Layer.provideMerge(OpaqueToolkit.providerLayer(toolkit)),
+    Layer.provideMerge(OperationHandlerSet.provide(operationHandlersSet)),
+    Layer.provideMerge(KeyValueStore.layerMemory),
+    Layer.provideMerge(Registry.layer),
+    Layer.orDie,
+  );
+};
+
+interface TestLayerWithTriggersOptions extends TestLayerOptions {}
+
+export type AssistantTestServicesWithTriggers = AssistantTestServices | TriggerDispatcher | TriggerStateStore;
+
+export const AssistantTestLayerWithTriggers = (
+  options: TestLayerWithTriggersOptions,
+): Layer.Layer<AssistantTestServicesWithTriggers, never, TestContextService> =>
+  Layer.mergeAll(
+    AssistantTestLayer(options),
+    TriggerDispatcher.layer({ timeControl: 'manual', startingTime: new Date('2025-09-05T15:01:00.000Z') }).pipe(
+      Layer.provide(Registry.layer),
+    ),
+    TriggerStateStore.layerMemory,
+  ) as any;
+
+const TraceSinkPretty = () =>
+  Layer.succeed(Trace.TraceSink, {
+    write: (message) => {
+      for (const event of message.events) {
+        if (Trace.isOfType(CompleteBlock, event)) {
+          const tag = message.meta.processName ?? `[${message.meta.pid ?? 'unknown'}]`;
+          console.log(`[${tag}] ${event.data.role.toUpperCase()}`);
+          new ConsolePrinter({ tag }).printContentBlock(event.data.block);
+        } else if (Trace.isOfType(Process.SpawnedEvent, event)) {
+          console.log(`[${message.meta.pid}] Process spawned: ${message.meta.processName}`);
+        } else if (Trace.isOfType(Process.ExitedEvent, event)) {
+          console.log(`[${message.meta.pid}] Process exited: ${event.data.outcome}`);
+        }
+      }
+    },
+  });

package/src/tracing.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Obj } from '@dxos/echo';
+import { Trace } from '@dxos/functions';
+import { ContentBlock, Actor } from '@dxos/types';
+
+/**
+ * Partial content block emitted.
+ */
+export const PartialBlock = Trace.EventType('assistant.partialBlock', {
+  schema: Schema.Struct({
+    messageId: Obj.ID,
+    role: Actor.Role,
+    block: ContentBlock.Any,
+  }),
+  isEphemeral: true,
+});
+
+/**
+ * Complete content block emitted.
+ */
+export const CompleteBlock = Trace.EventType('assistant.completeBlock', {
+  schema: Schema.Struct({
+    messageId: Obj.ID,
+    role: Actor.Role,
+    block: ContentBlock.Any,
+  }),
+  isEphemeral: false,
+});
+
+export const AgentRequestBegin = Trace.EventType('assistant.agentRequestBegin', {
+  schema: Schema.Struct({}),
+  isEphemeral: false,
+});
+
+export const AgentRequestEnd = Trace.EventType('assistant.agentRequestEnd', {
+  schema: Schema.Struct({}),
+  isEphemeral: false,
+});

package/src/types/artifact.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { type Err, Obj, Ref, type Type } from '@dxos/echo';
+import { Database } from '@dxos/echo';
+import { EncodedReference } from '@dxos/echo-protocol';
+import { DXN, LOCAL_SPACE_TAG, type ObjectId, type SpaceId } from '@dxos/keys';
+import { trim } from '@dxos/util';
+
+/**
+ * @deprecated
+ */
+export const createArtifactElement = (id: ObjectId) => `<artifact id=${id} />`;
+
+// TODO(burdon): Rename RefFromLLM? -- yes -dm
+/**
+ * A model-friendly way to reference an object.
+ * Supports vairous formats that will be normalized to a DXN.
+ *
+ * @deprecated Use `Ref.Ref(XXX)` instead.
+ */
+export const ArtifactId: Schema.Schema<string> & {
+  toDXN: (reference: ArtifactId, owningSpaceId?: SpaceId) => DXN;
+  resolve: <S extends Type.AnyEntity>(
+    schema: S,
+    ref: ArtifactId,
+  ) => Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Database.Service>;
+} = class extends Schema.String.annotations({
+  // TODO(dmaretskyi): This section gets overriden.
+  description: trim`
+    The ID of the referenced object. Formats accepted:
+    - DXN (dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4). DXNs can be prepended with an @ symbol for compatibility with in-text references.
+    - space ID, object ID tuple (spaceID:objectID)
+    - Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)
+  `,
+  examples: [
+    'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+    '@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+    'BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+    '01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+  ],
+}) {
+  static toDXN(reference: ArtifactId, owningSpaceId?: SpaceId): DXN {
+    // Allow @dxn: prefix for compatibility with in-text references.
+    if (reference.startsWith('@dxn:')) {
+      return DXN.parse(reference.slice(1));
+    } else if (reference.startsWith('dxn:')) {
+      return DXN.parse(reference);
+    } else if (/^[A-Z0-9]+:[A-Z0-9]+$/.test(reference)) {
+      const [spaceId, objectId] = reference.split(':');
+      // This is a workaround because the current Filter API doesn't work with fully qualified Echo DXNs.
+      // We check if the space ID is the same as the owning space and then use LOCAL_SPACE_TAG for local references.
+      // TODO(dmaretskyi): Fix this in the Echo and Filter API to properly handle fully qualified DXNs.
+      return new DXN(DXN.kind.ECHO, [spaceId === owningSpaceId ? LOCAL_SPACE_TAG : spaceId, objectId]);
+    } else if (/^[A-Z0-9]+$/.test(reference)) {
+      return DXN.fromLocalObjectId(reference);
+    } else {
+      throw new Error(`Unable to parse object reference: ${reference}`);
+    }
+  }
+
+  /**
+   * Resolves an artifact ID to an object.
+   */
+  static resolve<S extends Type.AnyEntity>(
+    schema: S,
+    ref: ArtifactId,
+  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Database.Service> {
+    const dxn = ArtifactId.toDXN(ref);
+    return Database.resolve(dxn, schema);
+  }
+};
+
+export type ArtifactId = Schema.Schema.Type<typeof ArtifactId>;
+
+/**
+ * Schema that decodes ECHO reference object from an LLM-friendly input.
+ */
+export const RefFromLLM = Schema.transform(ArtifactId, Ref.Ref(Obj.Unknown), {
+  decode: (fromA, fromI) => EncodedReference.fromDXN(ArtifactId.toDXN(fromA)),
+  encode: (toI, toA) => EncodedReference.toDXN(toI).toString(),
+  strict: false,
+}).annotations({
+  description: ArtifactId.ast.annotations.description as string,
+});

package/src/types/index.ts

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

package/src/typings.d.ts

@@ -2,6 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}
+
 declare module '*.tpl?raw' {
   const content: string;
   export default content;