@dxos/assistant 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/src/session/request.ts

@@ -0,0 +1,347 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as AiError from '@effect/ai/AiError';
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Array from 'effect/Array';
+import * as Chunk from 'effect/Chunk';
+import * as Effect from 'effect/Effect';
+import { pipe } from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Stream from 'effect/Stream';
+
+import {
+  AiParser,
+  AiPreprocessor,
+  AiSummarizer,
+  type AiToolNotFoundError,
+  callTool,
+  type OpaqueToolkit,
+  type PromptPreprocessingError,
+  type ToolExecutionService,
+  type ToolResolverService,
+  withoutToolCallParising,
+} from '@dxos/ai';
+import { type Blueprint, Trace, Operation, OperationRegistry } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { ContentBlock, Message } from '@dxos/types';
+
+import { type AiAssistantError } from '../errors';
+import { CompleteBlock, PartialBlock } from '../tracing';
+import { formatSystemPrompt, formatUserPrompt } from './format';
+import { GenerationObserver } from './observer';
+
+export type AiRequestRunError = AiError.AiError | PromptPreprocessingError | AiToolNotFoundError | AiAssistantError;
+
+export type AiRequestRunRequirements =
+  | LanguageModel.LanguageModel
+  | ToolExecutionService
+  | ToolResolverService
+  | Database.Service
+  | Operation.Service
+  | OperationRegistry.Service
+  | Trace.TraceService;
+
+export type AiRequestOptions = {
+  /**
+   * Summarize before executing the prompt if the existing history exceeds this threshold.
+   */
+  summarizationThreshold?: number;
+
+  // TODO(dmaretskyi): Plan to phase out in favor of TracingService and the return type being a stream.
+  observer?: GenerationObserver;
+  /**
+   * Callback for when a message is received from the user, model, or tool.
+   * This is useful for streaming the output to a queue.
+   */
+  onOutput?: (message: Message.Message) => Effect.Effect<void, never, never>;
+};
+
+export type AiRequestRunProps<R = never> = {
+  prompt: string | ContentBlock.Any[];
+  // TODO(wittjosiah): Rename to systemPrompt.
+  system?: string;
+  history?: Message.Message[];
+  objects?: Obj.Unknown[];
+  blueprints?: readonly Blueprint.Blueprint[];
+  toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+};
+
+export type AiRequestBeginProps = {
+  prompt: string | ContentBlock.Any[];
+  system?: string;
+  history?: Message.Message[];
+  objects?: Obj.Unknown[];
+  blueprints?: readonly Blueprint.Blueprint[];
+};
+
+export type AiRequestTurnProps<R = never> = {
+  system: string;
+  toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+};
+
+export type AiRequestTurnResult = {
+  messages: Message.Message[];
+  done: boolean;
+};
+
+/**
+ * Contains message history, tools, current context.
+ * Current context means the state of the app, time of day, and other contextual information.
+ * It makes requests to the model, its a state machine.
+ * It keeps track of the current goal.
+ * It manages the context window.
+ * Tracks the success criteria of reaching the goal, exposing metrics (stretch).
+ * Could be run locally in the app or remotely.
+ * Could be personal or shared.
+ */
+export class AiRequest {
+  /** Prevents concurrent execution of session. */
+  private readonly _semaphore = Effect.runSync(Effect.makeSemaphore(1));
+
+  private readonly _observer: GenerationObserver;
+  private readonly _onOutput: (message: Message.Message) => Effect.Effect<void, never, never>;
+
+  /** Message history from queue. */
+  // TODO(burdon): Evolve into supporting a git-like graph of messages.
+  private _history: Message.Message[] = [];
+
+  /** Pending messages for this session (incl. the current prompt). */
+  private _pending: Message.Message[] = [];
+
+  private _started = 0;
+  private _ended = 0;
+  private _toolCalls = 0;
+
+  constructor(private readonly _options: AiRequestOptions = {}) {
+    this._observer = _options.observer ?? GenerationObserver.noop();
+    this._onOutput = _options.onOutput ?? (() => Effect.void);
+  }
+
+  get duration(): number {
+    return this._ended - this._started;
+  }
+
+  get toolCalls(): number {
+    return this._toolCalls;
+  }
+
+  get pending(): readonly Message.Message[] {
+    return this._pending;
+  }
+
+  private _submitMessage = (message: Message.Message): Effect.Effect<Message.Message, never, Trace.TraceService> =>
+    Effect.gen(this, function* () {
+      this._pending.push(message);
+      yield* this._observer.onMessage(message);
+      for (const block of message.blocks) {
+        log('write complete block', {
+          messageId: message.id,
+          role: message.sender.role!,
+          block: JSON.stringify(block),
+        });
+        yield* Trace.write(CompleteBlock, {
+          messageId: message.id,
+          role: message.sender.role!,
+          block,
+        });
+      }
+      yield* this._onOutput(message);
+      return message;
+    });
+
+  getToolCalls = () =>
+    pipe(
+      [...this._history, ...this._pending],
+      Array.reverse,
+      Array.takeWhile((_) => _.sender.role === 'assistant'),
+      Array.flatMap((_) => _.blocks.filter(ContentBlock.is('toolCall')).map((block) => ({ block, message: _ }))),
+      Array.filter((_) => !_.block.providerExecuted),
+      Array.reverse,
+    );
+
+  /**
+   * Initialize a session: set up history, perform summarization if needed, and submit the user prompt.
+   * Must be called before `runTurn()`.
+   */
+  begin = ({
+    prompt,
+    system,
+    history = [],
+    blueprints = [],
+    objects = [],
+  }: AiRequestBeginProps): Effect.Effect<void, AiRequestRunError, AiRequestRunRequirements> =>
+    Effect.gen(this, function* () {
+      this._started = Date.now();
+      this._history = [...history];
+      this._pending = [];
+
+      const systemPrompt = yield* formatSystemPrompt({ system, blueprints, objects }).pipe(Effect.orDie);
+
+      if (this._options.summarizationThreshold !== undefined) {
+        const tokenCount = yield* AiPreprocessor.estimateTokens(
+          yield* AiPreprocessor.preprocessPrompt([...this._history], {
+            system: systemPrompt,
+          }),
+        );
+        if (tokenCount > this._options.summarizationThreshold) {
+          const summary = yield* AiSummarizer.summarize([...this._history]);
+          yield* this._submitMessage(summary);
+        }
+      }
+
+      yield* this._submitMessage(yield* formatUserPrompt({ prompt, history }));
+    }).pipe(Effect.withSpan('AiRequest.begin'));
+
+  /**
+   * Execute a single turn: one LLM generation followed by tool execution.
+   * The toolkit and system prompt can be updated between turns to reflect context changes (e.g. dynamically enabled blueprints).
+   */
+  runAgentTurn = <const R = never>({
+    system,
+    toolkit: opaqueToolkit,
+  }: AiRequestTurnProps<R>): Effect.Effect<AiRequestTurnResult, AiRequestRunError, AiRequestRunRequirements | R> =>
+    Effect.gen(this, function* () {
+      log.info('request', {
+        system: { snippet: createSnippet(system), length: system.length },
+        pending: this._pending.length,
+        history: this._history.length,
+      });
+
+      const prompt = yield* AiPreprocessor.preprocessPrompt([...this._history, ...this._pending], {
+        system,
+        cacheControl: 'ephemeral',
+      });
+
+      const toolkit = opaqueToolkit ? yield* opaqueToolkit.handlers : undefined;
+
+      const observer = this._observer;
+      let currentMessageId: Obj.ID | null = null;
+
+      const messages = yield* LanguageModel.streamText({
+        prompt,
+        toolkit,
+        disableToolCallResolution: true,
+      }).pipe(
+        withoutToolCallParising,
+        AiParser.parseResponse({
+          emitPartial: true,
+          onBegin: () => observer.onBegin(),
+          onBlock: (block) => observer.onBlock(block),
+          onPart: (part) => observer.onPart(part as any),
+          onEnd: (summary) => observer.onEnd(summary),
+        }),
+        Stream.mapEffect(
+          (block) =>
+            Effect.gen(this, function* () {
+              if (block.pending) {
+                currentMessageId ??= Obj.ID.random();
+                log('emit ephemeral message', { id: currentMessageId, type: block._tag });
+                yield* Trace.write(PartialBlock, {
+                  messageId: currentMessageId,
+                  role: 'assistant',
+                  block,
+                });
+                return Option.none();
+              } else {
+                currentMessageId ??= Obj.ID.random();
+                const id = currentMessageId;
+                currentMessageId = null;
+                log('emit complete message', { id, type: block._tag });
+                const message = Obj.make(Message.Message, {
+                  id,
+                  created: new Date().toISOString(),
+                  sender: { role: 'assistant' },
+                  blocks: [block],
+                });
+                return Option.some(yield* this._submitMessage(message));
+              }
+            }),
+          { concurrency: 1, unordered: false },
+        ),
+        Stream.filterMap((_) => _),
+        Stream.runCollect,
+        Effect.map(Chunk.toArray),
+      );
+      log.info('messages', { messages });
+
+      const toolCalls = this.getToolCalls();
+
+      if (toolCalls.length === 0) {
+        this._ended = Date.now();
+        return { messages, done: true };
+      } else if (!toolkit) {
+        throw new Error('No toolkit provided');
+      }
+
+      return { messages, done: false };
+    }).pipe(Effect.withSpan('AiRequest.runAgentTurn'));
+
+  runTools = <const R = never>({
+    toolkit: opaqueToolkit,
+  }: {
+    toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+  }): Effect.Effect<void, AiRequestRunError, AiRequestRunRequirements | R> =>
+    Effect.gen(this, function* () {
+      const toolkit = opaqueToolkit ? yield* opaqueToolkit.handlers : undefined;
+      const toolCalls = this.getToolCalls();
+      const toolResults = yield* Effect.forEach(toolCalls, ({ block, message }) => {
+        if (!toolkit) {
+          throw new Error('No toolkit provided');
+        }
+        return callTool(toolkit, block);
+      });
+
+      yield* this._submitMessage(
+        Obj.make(Message.Message, {
+          created: new Date().toISOString(),
+          sender: { role: 'tool' },
+          blocks: toolResults,
+        }),
+      );
+
+      this._toolCalls += toolResults.length;
+    }).pipe(Effect.withSpan('AiRequest.runTools'));
+
+  /**
+   * Run a full conversation turn loop. Equivalent to calling `begin()` then `runTurn()` in a loop.
+   */
+  run = <const R = never>({
+    prompt,
+    system: systemTemplate,
+    history = [],
+    objects = [],
+    blueprints = [],
+    toolkit,
+  }: AiRequestRunProps<R>): Effect.Effect<Message.Message[], AiRequestRunError, AiRequestRunRequirements | R> =>
+    Effect.gen(this, function* () {
+      yield* this.begin({ prompt, system: systemTemplate, history, objects, blueprints });
+
+      const system = yield* formatSystemPrompt({ system: systemTemplate, blueprints, objects }).pipe(Effect.orDie);
+
+      do {
+        const { done } = yield* this.runAgentTurn({ system, toolkit });
+        if (done) {
+          break;
+        }
+        yield* this.runTools({ toolkit });
+      } while (true);
+
+      log('done', { pending: this._pending.length, duration: this.duration, tools: this._toolCalls });
+      return this._pending;
+    }).pipe(this._semaphore.withPermits(1), Effect.withSpan('AiRequest.run'));
+}
+
+const createSnippet = (text: string, len = 32) =>
+  text.length <= len * 2 ? text : [text.slice(0, len), '...', text.slice(-len)].join('');
+
+// TODO(dmaretskyi): Extract as a general util.
+const logDump = (message: string, data: unknown) => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { writeFileSync } = require('node:fs');
+  const path = `/tmp/log-data-${Date.now()}.json`;
+  writeFileSync(path, JSON.stringify(data, null, 2));
+  log.info(message, { path });
+};

package/src/session/toolkit.ts

@@ -2,41 +2,46 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type AiTool, AiToolkit } from '@effect/ai';
-import { type Context, Effect } from 'effect';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 
-import { ToolExecutionService, type ToolId, ToolResolverService } from '@dxos/ai';
-import { type Blueprint } from '@dxos/blueprints';
-import { isNotFalsy } from '@dxos/util';
+import { type AiToolNotFoundError, OpaqueToolkit, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { type Blueprint } from '@dxos/compute';
+import { isTruthy } from '@dxos/util';
 
-export type ToolkitParams<Tools extends AiTool.Any> = {
-  toolkit?: AiToolkit.AiToolkit<Tools>;
-  toolIds?: ToolId[];
-  blueprints?: Blueprint.Blueprint[];
+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 = <Tools extends AiTool.Any>({
-  toolkit: toolkitParam,
-  toolIds = [],
+export const createToolkit = ({
+  toolkit: toolkitProp,
   blueprints = [],
-}: ToolkitParams<Tools>) =>
+  opaqueToolkits = [],
+}: CreateToolkitProps): Effect.Effect<
+  OpaqueToolkit.OpaqueToolkit,
+  AiToolNotFoundError,
+  ToolResolverService | ToolExecutionService
+> =>
   Effect.gen(function* () {
-    const blueprintToolkit = yield* ToolResolverService.resolveToolkit([
-      ...blueprints.flatMap(({ tools }) => tools),
-      ...toolIds,
-    ]);
+    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
+    const blueprintToolHandler = yield* blueprintToolkit.toContext(ToolExecutionService.handlersFor(blueprintToolkit));
+    const opaqueToolkit = OpaqueToolkit.merge(...opaqueToolkits);
 
-    const blueprintToolkitHandler: Context.Context<AiTool.ToHandler<AiTool.Any>> = yield* blueprintToolkit.toContext(
-      ToolExecutionService.handlersFor(blueprintToolkit),
+    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,
     );
-
-    const toolkit = AiToolkit.merge(...[toolkitParam, blueprintToolkit].filter(isNotFalsy));
-    return yield* toolkit.pipe(Effect.provide(blueprintToolkitHandler)) as Effect.Effect<
-      AiToolkit.ToHandler<any>,
-      never,
-      AiTool.ToHandler<Tools>
-    >;
-  });
+    return OpaqueToolkit.make(mergedToolkit, combinedHandlerLayer as any) as OpaqueToolkit.OpaqueToolkit;
+  }) as Effect.Effect<OpaqueToolkit.OpaqueToolkit, AiToolNotFoundError, ToolResolverService | ToolExecutionService>;

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 ObjectVersion } from '@dxos/echo-db';
-import { getVersion } from '@dxos/echo-db';
-import { type AnyEchoObject, ObjectId } from '@dxos/echo-schema';
-import { type ContentBlock } from '@dxos/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>;
@@ -27,11 +27,11 @@ export interface VersionPin extends Schema.Schema.Type<typeof VersionPinSchema>
 
 export const VersionPin: typeof VersionPinSchema & {
   DISPOSITION: 'version-pin';
-  fromObject: (object: AnyEchoObject) => VersionPin;
+  fromObject: (object: Obj.Unknown) => VersionPin;
   createBlock: (pin: VersionPin) => ContentBlock.Any;
 } = class extends VersionPinSchema {
   static readonly DISPOSITION = 'version-pin';
-  static fromObject(object: AnyEchoObject): VersionPin {
+  static fromObject(object: Obj.Unknown): VersionPin {
     return VersionPin.make({
       objectId: object.id,
       version: getVersion(object),

package/src/templates/{format.tpl → instructions/format.tpl}

@@ -45,16 +45,13 @@ You can reply with a block reference for objects if you have the DXN. For exampl
 
 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>
 
-## Toolkit
-
-If the user asks for a list of tools, then just emit a single self-closing <toolkit/> tag instead of listing the tools.
-
 ## 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

@@ -5,10 +5,10 @@
 import defaultsDeep from 'lodash.defaultsdeep';
 
 import { type ModelCapabilities } from '@dxos/ai';
-import { Template } from '@dxos/blueprints';
+import { Template } from '@dxos/compute';
 
-import FORMAT from './format.tpl?raw';
-import SYSTEM from './system.tpl?raw';
+import FORMAT from './instructions/format.tpl?raw';
+import SYSTEM from './instructions/system.tpl?raw';
 
 /**
  * System template variables.
@@ -29,13 +29,14 @@ export const createSystemPrompt = (options: Partial<SystemPromptOptions> = {}) =
     }),
   );
 
+/**
+ * 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 = {
-  /** Editable system prompt.*/
   system: Template.make({
-    /**
-     * NOTE: We are forbidden from accessing randomness at model level in cloudflare, so we have to have pre-generated ids.
-     */
-    id: '01K2J2FZWH39F55CS7B26GP1Q3',
+    id: SYSTEM_ID,
     source: SYSTEM,
   }),
 };

package/src/tracing.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Trace } from '@dxos/compute';
+import { Obj } from '@dxos/echo';
+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,
+});
+
+/**
+ * Emitted when an MCP server connection fails for a request turn.
+ * Ephemeral so that misconfigured/unreachable servers don't pollute the durable feed,
+ * but can still be surfaced to the user via the live ephemeral event stream.
+ */
+export const McpServerError = Trace.EventType('assistant.mcpServerError', {
+  schema: Schema.Struct({
+    url: Schema.String,
+    protocol: Schema.Literal('sse', 'http'),
+    message: Schema.String,
+  }),
+  isEphemeral: true,
+});