docs(client): document trajectory conversation assembly

packages/client/ui-trajectory/src/client/trajectory-assistant-definition.ts

@@ -255,17 +255,17 @@ function assistantRequest(
     ...(state.retry === undefined
       ? {}
       : {
-          error: state.retry.message,
-          retry: state.retry.retry,
-          ...(state.retry.maxRetries === undefined ? {} : { maxRetries: state.retry.maxRetries }),
-          retryDelayMs: state.retry.delayMs,
-        }),
+        error: state.retry.message,
+        retry: state.retry.retry,
+        ...(state.retry.maxRetries === undefined ? {} : { maxRetries: state.retry.maxRetries }),
+        retryDelayMs: state.retry.delayMs,
+      }),
     ...(node === undefined || node.interrupted === true
       ? {}
       : {
-          resultSeq: node.seq,
-          ...(node.provenance === undefined ? {} : { provenance: node.provenance }),
-        }),
+        resultSeq: node.seq,
+        ...(node.provenance === undefined ? {} : { provenance: node.provenance }),
+      }),
     ...(state.usage === undefined ? {} : { usage: state.usage }),
   }
 }
@@ -383,14 +383,18 @@ const trajectoryTurnEndDefinition: ConversationNodeDefinition<TurnEndState> = {
   buildViewNode: context => context.state === undefined
     ? null
     : trajectoryNode(context, context.state.seq, {
-        kind: 'turn-end',
-        turn: context.state.turn,
-        time: context.state.time,
-        ...(context.state.error === undefined ? {} : { error: context.state.error }),
-      }),
+      kind: 'turn-end',
+      turn: context.state.turn,
+      time: context.state.time,
+      ...(context.state.error === undefined ? {} : { error: context.state.error }),
+    }),
 }
 
-/** Register the Trajectory Assistant lifecycle. */
+/**
+ * Register the Trajectory Assistant lifecycle.
+ *
+ * @param ctx - Plugin context receiving the Definitions.
+ */
 export function registerTrajectoryAssistantDefinition(ctx: Context): void {
   ctx.conversationEvents.register(trajectoryAssistantDefinition)
   ctx.conversationEvents.register(trajectoryTurnEndDefinition)

packages/client/ui-trajectory/src/client/trajectory-compaction-definition.ts

@@ -61,18 +61,18 @@ function requestFromState(
     ...(summary?.type !== 'compact/summary'
       ? {}
       : {
-          resultSeq: summary.seq,
-          summary: summary.data.summary,
-          ...(summary.data.rawOutput === undefined ? {} : { rawOutput: summary.data.rawOutput }),
-          provenance: { provider: summary.data.provider, model: summary.data.model },
-          requestConfig: {
-            provider: summary.data.provider,
-            model: summary.data.model,
-            purpose: 'compaction',
-            ...(summary.data.maxTokens === undefined ? {} : { maxTokens: summary.data.maxTokens }),
-          },
-          ...(summary.data.usage === undefined ? {} : { usage: summary.data.usage }),
-        }),
+        resultSeq: summary.seq,
+        summary: summary.data.summary,
+        ...(summary.data.rawOutput === undefined ? {} : { rawOutput: summary.data.rawOutput }),
+        provenance: { provider: summary.data.provider, model: summary.data.model },
+        requestConfig: {
+          provider: summary.data.provider,
+          model: summary.data.model,
+          purpose: 'compaction',
+          ...(summary.data.maxTokens === undefined ? {} : { maxTokens: summary.data.maxTokens }),
+        },
+        ...(summary.data.usage === undefined ? {} : { usage: summary.data.usage }),
+      }),
     ...(checkpoint?.type === 'user/message' ? { replacementSeq: checkpoint.seq } : {}),
   }
 }
@@ -126,13 +126,17 @@ const trajectorySessionEndDefinition: ConversationNodeDefinition<SessionEndState
   buildViewNode: context => context.state === undefined
     ? null
     : trajectoryNode(context, context.state.seq, {
-        kind: 'session-end',
-        seq: context.state.seq,
-        time: context.state.time,
-      }),
+      kind: 'session-end',
+      seq: context.state.seq,
+      time: context.state.time,
+    }),
 }
 
-/** Register Trajectory compaction requests and session boundaries. */
+/**
+ * Register Trajectory compaction requests and session boundaries.
+ *
+ * @param ctx - Plugin context receiving the Definitions.
+ */
 export function registerTrajectoryCompactionDefinitions(ctx: Context): void {
   ctx.conversationEvents.register(trajectoryCompactionDefinition)
   ctx.conversationEvents.register(trajectorySessionEndDefinition)

packages/client/ui-trajectory/src/client/trajectory-definition-common.ts

@@ -5,14 +5,26 @@ import type {
   TrajectoryContribution, TrajectoryConversationViewNode,
 } from './trajectory-contract.ts'
 
-/** Resolve the best loaded Location for one target-local Context. */
+/**
+ * Resolve the best loaded Location for one target-local Context.
+ *
+ * @param context - Context whose loaded matches provide the Location.
+ * @returns The start Location, first-match Location, or unresolved fallback.
+ */
 export function trajectoryContextLocation(
   context: ConversationNodeContext,
 ): ConversationLocation {
   return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
 }
 
-/** Wrap one contribution in the Engine-owned target envelope. */
+/**
+ * Wrap one contribution in the Engine-owned target envelope.
+ *
+ * @param context - Context that owns the contribution identity.
+ * @param anchorSeq - Sequence used to order the contribution.
+ * @param data - Trajectory-specific contribution payload.
+ * @returns The contribution wrapped as a Trajectory view node.
+ */
 export function trajectoryNode(
   context: ConversationNodeContext,
   anchorSeq: number,

packages/client/ui-trajectory/src/client/trajectory-message-definitions.ts

@@ -86,20 +86,20 @@ const trajectoryMessageDefinition: ConversationNodeDefinition<MessageNode> = {
       ?.state.claimed.has(String(event.data.id)) === true
     return claimed
       ? {
-          kind: 'steering',
-          messageId: event.data.id,
-          seq: event.seq,
-          time: event.time,
-          content: event.data.content,
-          source: event.data.source,
-        }
+        kind: 'steering',
+        messageId: event.data.id,
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+      }
       : {
-          kind: 'user',
-          seq: event.seq,
-          time: event.time,
-          content: event.data.content,
-          source: event.data.source,
-        }
+        kind: 'user',
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+      }
   },
   update: context => context.state,
   buildViewNode: context => context.state === undefined
@@ -107,7 +107,11 @@ const trajectoryMessageDefinition: ConversationNodeDefinition<MessageNode> = {
     : trajectoryNode(context, context.state.seq, { kind: 'node', node: context.state }),
 }
 
-/** Register Trajectory-owned inbox classification and message records. */
+/**
+ * Register Trajectory-owned inbox classification and message records.
+ *
+ * @param ctx - Plugin context receiving the Definitions.
+ */
 export function registerTrajectoryMessageDefinitions(ctx: Context): void {
   ctx.conversationEvents.register(trajectoryInboxDefinition)
   ctx.conversationEvents.register(trajectoryMessageDefinition)

packages/client/ui-trajectory/src/client/trajectory-request-header-definition.ts

@@ -65,12 +65,16 @@ const trajectoryRequestHeaderDefinition: ConversationNodeDefinition<TrajectoryRe
   buildViewNode: context => context.state === undefined
     ? null
     : trajectoryNode(context, context.state.seq, {
-        kind: 'request-header',
-        header: context.state,
-      }),
+      kind: 'request-header',
+      header: context.state,
+    }),
 }
 
-/** Register Trajectory request-header facts. */
+/**
+ * Register Trajectory request-header facts.
+ *
+ * @param ctx - Plugin context receiving the Definition.
+ */
 export function registerTrajectoryRequestHeaderDefinition(ctx: Context): void {
   ctx.conversationEvents.register(trajectoryRequestHeaderDefinition)
 }

packages/client/ui-trajectory/src/client/trajectory-snapshot-builder.ts

@@ -50,11 +50,11 @@ function applyHeader(
   return header === undefined
     ? request
     : {
-        ...request,
-        prompt: header.prompt,
-        requestConfig: header.prompt.config,
-        ...(header.change === undefined ? {} : { promptChange: header.change }),
-      }
+      ...request,
+      prompt: header.prompt,
+      requestConfig: header.prompt.config,
+      ...(header.change === undefined ? {} : { promptChange: header.change }),
+    }
 }
 
 function withRequestConfig(
@@ -70,7 +70,7 @@ function captureSchemas(
   output: Map<string, ConversationPromptSnapshot['tools'][number]>,
 ): void {
   const name = 'kind' in block ? block.call?.name : block.name
-  const schema = name === undefined || name === null
+  const schema = name === undefined
     ? undefined
     : tools.find(candidate => candidate.name === name)
   if (schema !== undefined) output.set(block.callId, schema)
@@ -216,7 +216,11 @@ export const trajectoryViewDefinition: ConversationViewDefinition<
   create: () => new TrajectorySnapshotBuilder(),
 }
 
-/** Register the legacy-shape Trajectory target builder. */
+/**
+ * Register the stage-oriented Trajectory target builder.
+ *
+ * @param ctx - Plugin context receiving the view Definition.
+ */
 export function registerTrajectoryConversationView(ctx: Context): void {
   ctx.conversationViews.register(trajectoryViewDefinition)
 }

packages/client/ui-trajectory/src/client/trajectory-tool-definition.ts

@@ -244,7 +244,11 @@ const trajectoryToolDefinition: ConversationNodeDefinition<ToolState> = {
   },
 }
 
-/** Register the Trajectory Tool lifecycle. */
+/**
+ * Register the Trajectory Tool lifecycle.
+ *
+ * @param ctx - Plugin context receiving the Definition.
+ */
 export function registerTrajectoryToolDefinition(ctx: Context): void {
   ctx.conversationEvents.register(trajectoryToolDefinition)
 }