@dxos/assistant 0.8.4-main.b97322e → 0.8.4-main.bc2380dfbc

package/src/session/AiSession.ts

@@ -0,0 +1,324 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Registry } from '@effect-atom/atom-react';
+import * as Array from 'effect/Array';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Record from 'effect/Record';
+import * as Runtime from 'effect/Runtime';
+
+import { type OpaqueToolkit, type ToolExecutionService, type ToolResolverService } from '@dxos/ai';
+import { type Blueprint, type OperationRegistry, McpServer, Operation, Trace } from '@dxos/compute';
+import { Resource } from '@dxos/context';
+import { Database, Feed, Filter, Obj } from '@dxos/echo';
+import { acquireReleaseResource } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { McpToolkit } from '@dxos/mcp-client';
+import { Message, type ContentBlock } from '@dxos/types';
+
+import { ToolExecutionServices } from '../functions';
+import { AiRequest, type GenerationObserver, formatSystemPrompt } from '../request';
+import { McpServerError } from '../util';
+import * as AiContext from './AiContext';
+import { createToolkit } from './toolkit';
+
+export type RunProps<R = never> = {
+  prompt: string | ContentBlock.Any[];
+  system?: string;
+  observer?: GenerationObserver;
+  toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+
+  /**
+   * Space-level MCP servers to connect alongside blueprint-defined ones.
+   */
+  mcpServers?: readonly McpServer.McpServer[];
+};
+
+export type Options = {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Feed.FeedService>;
+  registry?: Registry.Registry;
+};
+
+/**
+ * Summarization threshold in tokens.
+ */
+// TODO(dmaretskyi): Take from model characteristics. opus has 200k max tokens.
+const SUMMARY_THRESHOLD = 80_000;
+
+/**
+ * Durable conversation state (initiated by users and agents) backed by a Feed.
+ * Executes tools based on AI responses and supports cancellation of in-progress requests.
+ */
+export class Session extends Resource {
+  /**
+   * Blueprints and objects bound to the session.
+   */
+  private readonly _binder: AiContext.Binder;
+  private readonly _feed: Feed.Feed;
+  private readonly _runtime: Runtime.Runtime<Feed.FeedService>;
+
+  public constructor(options: Options) {
+    super();
+    this._feed = options.feed;
+    this._runtime = options.runtime;
+    invariant(this._feed);
+    invariant(this._runtime);
+    this._binder = new AiContext.Binder({
+      feed: this._feed,
+      runtime: this._runtime,
+      registry: options.registry,
+    });
+  }
+
+  protected override async _open(): Promise<void> {
+    await this._binder.open(this._ctx);
+  }
+
+  public get feed() {
+    return this._feed;
+  }
+
+  public get context() {
+    return this._binder;
+  }
+
+  public async getHistory(): Promise<Message.Message[]> {
+    const queryResult = await Runtime.runPromise(this._runtime)(Feed.query(this._feed, Filter.type(Message.Message)));
+    const items = await queryResult.run();
+    return items.filter(Obj.instanceOf(Message.Message));
+  }
+
+  getTools(): Effect.Effect<
+    Record<string, import('@effect/ai/Tool').Any>,
+    never,
+    ToolExecutionService | ToolResolverService
+  > {
+    return Effect.gen(this, function* () {
+      const toolkit = yield* createToolkit({ blueprints: this.context.getBlueprints() });
+      return toolkit.toolkit.tools;
+    }).pipe(Effect.orDie);
+  }
+
+  /**
+   * Not provided by default, since users might want to override them.
+   */
+  makeToolExecutionServices(): Layer.Layer<
+    ToolExecutionService | ToolResolverService,
+    never,
+    OpaqueToolkit.OpaqueToolkitProvider | Operation.Service | OperationRegistry.Service
+  > {
+    return ToolExecutionServices.pipe(
+      Layer.provide(Operation.withInvocationOptions({ conversation: Obj.getDXN(this._feed).toString() })),
+    );
+  }
+
+  /**
+   * Creates a new cancelable request effect.
+   */
+  public createRequest<R = never>(
+    params: RunProps<R>,
+  ): Effect.Effect<Message.Message[], AiRequest.RunError, AiRequest.RunRequirements | R> {
+    return Effect.gen(this, function* () {
+      const history = yield* Effect.promise(() => this.getHistory());
+      const blueprints = this.context.getBlueprints();
+      const objects = this.context.getObjects();
+
+      log('run', {
+        history: history.length,
+        blueprints: blueprints.length,
+        objects: objects.length,
+      });
+
+      const request = new AiRequest.Request({
+        summarizationThreshold: SUMMARY_THRESHOLD,
+        observer: params.observer,
+        onOutput: (message) =>
+          Effect.promise(() => Runtime.runPromise(this._runtime)(Feed.append(this._feed, [message]))),
+      });
+
+      yield* request.begin({
+        history,
+        blueprints,
+        objects,
+        prompt: params.prompt,
+        system: params.system,
+      });
+
+      // Turn loop: recompute toolkit and system prompt between turns to pick up dynamically enabled blueprints.
+      do {
+        yield* Effect.promise(() => this.context.sync());
+        const currentBlueprints = this.context.getBlueprints();
+        const mcps = yield* connectMcpServers(currentBlueprints, params.mcpServers);
+        const toolkit = yield* createToolkit({
+          toolkit: params.toolkit,
+          blueprints: currentBlueprints,
+          opaqueToolkits: mcps,
+        });
+
+        log('toolkit', { tools: Record.keys(toolkit.toolkit.tools) });
+        const system = yield* formatSystemPrompt({
+          system: params.system,
+          blueprints: currentBlueprints,
+          objects: this.context.getObjects(),
+        }).pipe(Effect.orDie);
+
+        const { done } = yield* request.runAgentTurn({ system, toolkit });
+        if (done) {
+          break;
+        }
+
+        yield* request.runTools({ toolkit });
+      } while (true);
+
+      log('result', {
+        messages: request.pending.length,
+        duration: request.duration,
+        toolCalls: request.toolCalls,
+      });
+
+      return [...request.pending];
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          Layer.succeed(AiContext.Service, {
+            binder: this.context,
+          }),
+          Layer.succeed(Service, this),
+          Operation.withInvocationOptions({ conversation: Obj.getDXN(this._feed).toString() }),
+        ),
+      ),
+      Effect.withSpan('AiSession.createRequest'),
+    );
+  }
+}
+
+/**
+ * Gives access to the ai session.
+ */
+export class Service extends Context.Tag('@dxos/assistant/AiSessionService')<Service, Session>() {
+  /**
+   * Create a new session layer from options.
+   */
+  static layer = (options: Options): Layer.Layer<Service | AiContext.Service> =>
+    aiContextFromSession.pipe(
+      Layer.provideMerge(
+        Layer.scoped(
+          Service,
+          Effect.gen(function* () {
+            const session = yield* acquireReleaseResource(() => new Session(options));
+            return session;
+          }),
+        ),
+      ),
+    );
+
+  /**
+   * Create a new session with a new feed.
+   */
+  static layerNewFeed = (
+    options?: Omit<Options, 'feed' | 'runtime'>,
+  ): Layer.Layer<Service | AiContext.Service, never, Database.Service | Feed.FeedService> =>
+    Layer.unwrapScoped(
+      Effect.gen(function* () {
+        const feed = yield* Database.add(Feed.make());
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        return Service.layer({ ...options, feed, runtime });
+      }),
+    );
+
+  /**
+   * Run a prompt in the current session.
+   */
+  static run = <R = never>(
+    params: RunProps<R>,
+  ): Effect.Effect<Message.Message[], AiRequest.RunError, AiRequest.RunRequirements | Service | R> =>
+    Effect.gen(function* () {
+      const session = yield* Service;
+      return yield* session.createRequest(params);
+    });
+}
+
+const aiContextFromSession = Layer.effect(
+  AiContext.Service,
+  Effect.gen(function* () {
+    const session = yield* Service;
+    return {
+      binder: session.context,
+    };
+  }),
+);
+
+const connectMcpServers = (
+  blueprints: readonly Blueprint.Blueprint[],
+  spaceMcpServers: readonly McpServer.McpServer[] = [],
+): Effect.Effect<OpaqueToolkit.OpaqueToolkit[], never, Trace.TraceService> => {
+  const blueprintServers: McpToolkit.McpToolkitOptions[] = pipe(
+    blueprints,
+    Array.flatMap((_) => _.mcpServers ?? []),
+    Array.map(({ url, protocol, apiKey }) => ({ url, protocol, apiKey })),
+  );
+  const spaceServers: McpToolkit.McpToolkitOptions[] = spaceMcpServers.map(({ url, protocol, apiKey }) => ({
+    url,
+    protocol,
+    apiKey,
+  }));
+  const allServers = [...blueprintServers, ...spaceServers];
+
+  return pipe(
+    allServers,
+    Effect.forEach((options) =>
+      McpToolkit.make(options).pipe(
+        // NOTE: Type-inference fails here without explicit void return.
+        Effect.tap((toolkit): void =>
+          log.info('Connected to MCP server', { url: options.url, tools: Object.keys(toolkit.toolkit.tools).length }),
+        ),
+        // Surface typed connection failures via ephemeral trace + warn log, then drop the server.
+        Effect.tapError((error) =>
+          Effect.gen(function* () {
+            log.warn('Failed to connect to MCP server', {
+              url: error.url,
+              protocol: error.protocol,
+              message: error.message,
+            });
+            yield* Trace.write(McpServerError, {
+              url: error.url,
+              protocol: error.protocol,
+              message: error.message,
+            });
+          }),
+        ),
+        // Catch unexpected defects too (e.g. malformed tool schemas) so a single broken
+        // server can never abort the whole turn — surface them through the same channel.
+        Effect.catchAllDefect((defect) =>
+          Effect.gen(function* () {
+            const message = defect instanceof Error ? defect.message : String(defect);
+            log.warn('Unexpected MCP defect', { url: options.url, message });
+            yield* Trace.write(McpServerError, {
+              url: options.url,
+              protocol: options.protocol,
+              message: `Unexpected MCP failure: ${message}`,
+            });
+            return yield* Effect.fail(
+              new McpToolkit.McpConnectionError({
+                url: options.url,
+                protocol: options.protocol,
+                message,
+              }),
+            );
+          }),
+        ),
+        Effect.either,
+      ),
+    ),
+    Effect.map(Array.filterMap((_) => Either.getRight(_))),
+  );
+};

package/src/session/index.ts

@@ -2,5 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './session';
-export * from './version-pin';
+export * from './toolkit';
+
+export * as AiContext from './AiContext';
+export * as AiSession from './AiSession';

package/src/session/toolkit.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Toolkit from '@effect/ai/Toolkit';
+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 { isTruthy } from '@dxos/util';
+
+export type CreateToolkitProps = {
+  toolkit?: OpaqueToolkit.Any;
+  blueprints?: readonly Blueprint.Blueprint[];
+  /**
+   * Self-contained with handlers toolkits.
+   */
+  opaqueToolkits?: readonly OpaqueToolkit.Any[];
+};
+
+/**
+ * Build a combined toolkit from the blueprint tools and the provided toolkit.
+ */
+export const createToolkit = ({
+  toolkit: toolkitProp,
+  blueprints = [],
+  opaqueToolkits = [],
+}: CreateToolkitProps): Effect.Effect<
+  OpaqueToolkit.OpaqueToolkit,
+  AiToolNotFoundError,
+  ToolResolverService | ToolExecutionService
+> =>
+  Effect.gen(function* () {
+    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
+    const blueprintToolHandler = yield* blueprintToolkit.toContext(ToolExecutionService.handlersFor(blueprintToolkit));
+    const opaqueToolkit = OpaqueToolkit.merge(...opaqueToolkits);
+
+    const toolkitDefs = [toolkitProp?.toolkit, blueprintToolkit, opaqueToolkit.toolkit].filter(isTruthy);
+    const mergedToolkit = Toolkit.merge(...toolkitDefs);
+    const combinedHandlerLayer = Layer.mergeAll(
+      Layer.succeedContext(blueprintToolHandler),
+      toolkitProp?.layer ?? OpaqueToolkit.empty.layer,
+      opaqueToolkit.layer,
+    );
+    return OpaqueToolkit.make(mergedToolkit, combinedHandlerLayer as any) as OpaqueToolkit.OpaqueToolkit;
+  }) as Effect.Effect<OpaqueToolkit.OpaqueToolkit, AiToolNotFoundError, ToolResolverService | ToolExecutionService>;

package/src/templates/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './prompt';
+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,96 @@
+{{! 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
+
+- NEVER output narration text outside `<status>` tags or the final user-facing answer. Any progress update, transition sentence, or "let me…" lead-in MUST be wrapped in `<status>...</status>`. Violating this is an error.
+- 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.
+- After a `</status>` tag, the next output must be either another `<status>` tag, a tool call, or the final user-facing answer — never a transition sentence.
+
+<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>
+
+Do not do (transition sentence after a status tag, before tool calls):
+
+<incorrect_example>
+<status>Doing X</status>
+Let me start by doing X:
+// tool call
+</incorrect_example>
+
+- NEVER write a lead-in sentence before a tool call. Use a `<status>` tag instead.
+- 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/compute';
+
+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/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;

package/src/util/artifact.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, type Err, Obj, Ref, type Type } 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} />`;
+
+/**
+ * A model-friendly way to reference an object.
+ * Supports vairous formats that will be normalized to a DXN.
+ *
+ * @deprecated Use `Ref.Ref(XXX)` instead.
+ */
+// TODO(burdon): Rename RefFromLLM?
+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,
+});