@lostgradient/cinder 0.8.0 → 0.11.0

package/src/components/approval-card/approval-card.types.ts

@@ -2,6 +2,9 @@ import type { HTMLAttributes } from 'svelte/elements';
 
 export type ApprovalToolRisk = 'low' | 'medium' | 'high';
 
+/** Heading level rendered for the card title. Section headings render one level deeper. */
+export type ApprovalCardHeadingLevel = 2 | 3 | 4 | 5 | 6;
+
 /** @schemaObject */
 export type ApprovalTool = {
   /** Human-readable tool name requesting approval. */
@@ -28,7 +31,7 @@ export type ApprovalCommandOperation = {
   kind: 'command';
   /** Shell command for command approvals. */
   command: string;
-  /** File paths that the operation may read or write. */
+  /** File paths that the operation may read or write. Duplicate paths are collapsed for display. */
   filesTouched?: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -42,7 +45,7 @@ export type ApprovalCommandOperation = {
 export type ApprovalFileWriteOperation = {
   /** Operation family being approved. */
   kind: 'file-write';
-  /** File paths that the operation may read or write. File-write approvals require at least one path. */
+  /** File paths that the operation may read or write. File-write approvals require at least one path. Duplicate paths are collapsed for display. */
   filesTouched: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -56,7 +59,7 @@ export type ApprovalFileWriteOperation = {
 export type ApprovalPatchOperation = {
   /** Operation family being approved. */
   kind: 'patch';
-  /** File paths that the operation may read or write. */
+  /** File paths that the operation may read or write. Duplicate paths are collapsed for display. */
   filesTouched?: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -72,7 +75,7 @@ export type ApprovalPatchOperation = {
 export type ApprovalOtherOperation = {
   /** Operation family being approved. */
   kind: 'other';
-  /** File paths that the operation may read or write. */
+  /** File paths that the operation may read or write. Duplicate paths are collapsed for display. */
   filesTouched?: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -117,18 +120,8 @@ export type ApprovalResolution = {
 };
 
 export type ApprovalCardCallbacks = {
-  /** Called for approve, approve-with-edits, deny, and cancel with the complete resolution payload. */
+  /** Called for approve, approve-with-edits, deny, and dismiss with the complete resolution payload. */
   onresolve?: (resolution: ApprovalResolution) => void;
-  /** Called when the approver accepts the operation as presented. */
-  onapprove?: () => void;
-  /** Called with parsed JSON arguments when the approver accepts edited arguments. */
-  onapprovewithedits?: (editedArgs: unknown) => void;
-  /** Called when the approver denies the operation. */
-  ondeny?: () => void;
-  /** Called when the approver asks the host application to remember the decision. */
-  onremember?: () => void;
-  /** Called when the approver cancels the approval prompt. */
-  oncancel?: () => void;
 };
 
 /** Props for the ApprovalCard component. */
@@ -154,6 +147,8 @@ export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'chi
     state: ApprovalState;
     /** Whether approving with edited JSON arguments is available. Default `false`. */
     editableArgs?: boolean;
+    /** Heading level for the card title; section headings render one level deeper. Default `3`. */
+    headingLevel?: ApprovalCardHeadingLevel;
     /** Additional CSS classes applied to the root element. */
     class?: string;
   };
@@ -161,8 +156,8 @@ export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'chi
 /**
  * Cinder-specific schema surface for ApprovalCard.
  *
- * Callback props are documented but marked unsupported because functions cannot
- * be represented as JSON Schema controls.
+ * The resolution callback is documented but marked unsupported because
+ * functions cannot be represented as JSON Schema controls.
  */
 export type ApprovalCardSchemaProps = {
   /** Tool requesting approval. */
@@ -185,18 +180,10 @@ export type ApprovalCardSchemaProps = {
   state: ApprovalState;
   /** Whether approving with edited JSON arguments is available. Default `false`. */
   editableArgs?: boolean;
-  /** Called when the approver accepts the operation as presented. */
-  onapprove?: () => void;
-  /** Called for approve, approve-with-edits, deny, and cancel with the complete resolution payload. */
+  /** Heading level for the card title; section headings render one level deeper. Default `3`. */
+  headingLevel?: ApprovalCardHeadingLevel;
+  /** Called for approve, approve-with-edits, deny, and dismiss with the complete resolution payload. */
   onresolve?: (resolution: ApprovalResolution) => void;
-  /** Called with parsed JSON arguments when the approver accepts edited arguments. */
-  onapprovewithedits?: (editedArgs: unknown) => void;
-  /** Called when the approver denies the operation. */
-  ondeny?: () => void;
-  /** Called when the approver asks the host application to remember the decision. */
-  onremember?: () => void;
-  /** Called when the approver cancels the approval prompt. */
-  oncancel?: () => void;
   /** Additional CSS classes applied to the root element. */
   class?: string;
 };

package/src/components/approval-card/index.ts

@@ -4,6 +4,7 @@ import ApprovalCard from './approval-card.svelte';
 export default ApprovalCard;
 export type {
   ApprovalCardCallbacks,
+  ApprovalCardHeadingLevel,
   ApprovalCardProps,
   ApprovalCardSchemaProps,
   ApprovalOperation,

package/src/components/card/card.css

@@ -95,6 +95,11 @@
     padding: 0;
   }
 
+  .cinder-card[data-cinder-padding='none'] > .cinder-card__header,
+  .cinder-card[data-cinder-padding='none'] > .cinder-card__footer {
+    padding: 0;
+  }
+
   .cinder-card[data-cinder-variant='well'] > .cinder-card__body {
     background: var(--cinder-surface-inset);
   }

package/src/components/card/card.schema.json

@@ -28,7 +28,7 @@
     },
     "padding": {
       "enum": ["none", "default"],
-      "description": "Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image)."
+      "description": "Region padding. `none` removes body, header, and footer padding for flush or full-bleed content (e.g. an image)."
     },
     "headingLevel": {
       "enum": [2, 3, 4, 5, 6],

package/src/components/card/card.schema.ts

@@ -32,7 +32,7 @@ const schema = {
     padding: {
       enum: ['none', 'default'],
       description:
-        'Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image).',
+        'Region padding. `none` removes body, header, and footer padding for flush or full-bleed content (e.g. an image).',
     },
     headingLevel: {
       enum: [2, 3, 4, 5, 6],

package/src/components/card/card.svelte

@@ -37,6 +37,7 @@ const labelAttributes = $derived(hasGeneratedHeader
   data-cinder-variant={variant}
   data-cinder-tone={tone}
   data-cinder-edge-to-edge-mobile={edgeToEdgeOnMobile ? '' : undefined}
+  data-cinder-padding={padding}
   {...labelAttributes}
 >
   {#if header}

package/src/components/card/card.types.ts

@@ -3,7 +3,7 @@ import type { HTMLAttributes } from 'svelte/elements';
 export type CardVariant = 'card' | 'well';
 export type CardTone = 'default' | 'muted';
 export type CardSurfaceTone = 'default' | 'danger';
-/** Controls body padding. `none` removes all padding for flush/full-bleed content. Future values like `compact` may be added. */
+/** Controls region padding. `none` removes body, header, and footer padding for flush/full-bleed content. Future values like `compact` may be added. */
 export type CardPadding = 'default' | 'none';
 /** Heading level for the generated card title, so the document outline stays correct. */
 export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
@@ -19,7 +19,7 @@ type CardBase = HTMLAttributes<HTMLDivElement> & {
   footerTone?: CardTone;
   /** Remove side borders/radius and bleed to the viewport edge on narrow screens. */
   edgeToEdgeOnMobile?: boolean;
-  /** Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image). */
+  /** Region padding. `none` removes body, header, and footer padding for flush or full-bleed content (e.g. an image). */
   padding?: CardPadding;
 };
 /** Basic card with no generated header. */

package/src/components/chat/builders.ts

@@ -1,33 +1,464 @@
 /**
  * Conversation builders for the Chat component.
  *
- * Chat renders a {@link ConversationHistory} snapshot. These are thin aliases
- * over the published `conversationalist` builders so examples, demos, tests, and
- * simple apps construct the same transcript shape Chat consumes.
+ * Chat renders a {@link ConversationHistory} snapshot. These helpers construct
+ * the published Conversationalist shape without importing the package runtime
+ * into Cinder's browser graph.
  */
 
-import {
-  appendAssistantMessage as appendConversationalistAssistantMessage,
-  appendMessages as appendConversationalistMessages,
-  appendUserMessage as appendConversationalistUserMessage,
-  createConversationHistory,
-} from 'conversationalist';
+import type {
+  ConversationEnvironment,
+  ConversationHistory,
+  ConversationStatus,
+  JSONValue,
+  Message,
+  MessageInput,
+  MultiModalContent,
+  TokenUsage,
+  ToolCall,
+  ToolResult,
+} from './conversation-model.ts';
 
-import type { ConversationHistory, MessageInput } from './conversation-model.ts';
+type CreateConversationOptions = {
+  id?: string;
+  title?: string;
+  status?: ConversationStatus;
+  metadata?: Record<string, JSONValue>;
+};
+
+type ConversationEnvironmentInput = Partial<ConversationEnvironment>;
+type MessageContentInput = MessageInput['content'] | MultiModalContent;
+type LooseMessageInput = Omit<MessageInput, 'content'> & { content: MessageContentInput };
+
+const MESSAGE_ROLES = new Set([
+  'user',
+  'assistant',
+  'system',
+  'developer',
+  'tool-call',
+  'tool-result',
+  'snapshot',
+]);
+const CONVERSATION_STATUSES = new Set<ConversationStatus>(['active', 'archived', 'deleted']);
+
+function createId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `message-${Date.now()}-${Math.random()}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isJsonObject(value: unknown): value is Record<string, JSONValue> {
+  if (!isRecord(value) || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isJsonValue(value: unknown): value is JSONValue {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'string':
+    case 'boolean':
+      return true;
+    case 'number':
+      return Number.isFinite(value);
+    case 'object':
+      if (Array.isArray(value)) return value.every(isJsonValue);
+      return isJsonObject(value) && Object.values(value).every(isJsonValue);
+    default:
+      return false;
+  }
+}
+
+function assertJsonObject(
+  value: unknown,
+  label: string,
+): asserts value is Record<string, JSONValue> {
+  if (!isJsonObject(value) || !Object.values(value).every(isJsonValue)) {
+    throw new Error(`${label} must be a JSON-compatible object`);
+  }
+}
+
+function isConversationEnvironmentParameter(value: unknown): value is ConversationEnvironmentInput {
+  if (!isRecord(value) || 'role' in value) return false;
+  return (
+    typeof value['now'] === 'function' ||
+    typeof value['randomId'] === 'function' ||
+    typeof value['estimateTokens'] === 'function' ||
+    (Array.isArray(value['plugins']) &&
+      value['plugins'].every((plugin) => typeof plugin === 'function'))
+  );
+}
+
+function isRoleHelperEnvironmentParameter(value: unknown): value is ConversationEnvironmentInput {
+  if (!isRecord(value) || 'role' in value) return false;
+  return (
+    typeof value['now'] === 'function' ||
+    typeof value['randomId'] === 'function' ||
+    typeof value['estimateTokens'] === 'function' ||
+    (Array.isArray(value['plugins']) &&
+      value['plugins'].length > 0 &&
+      value['plugins'].every((plugin) => typeof plugin === 'function'))
+  );
+}
+
+function isMultiModalContentPart(value: unknown): value is MultiModalContent {
+  if (!isJsonObject(value) || typeof value['type'] !== 'string') return false;
+  if (!Object.values(value).every(isJsonValue)) return false;
+  switch (value['type']) {
+    case 'text':
+      return typeof value['text'] === 'string';
+    case 'image':
+      return typeof value['url'] === 'string';
+    case 'thinking':
+      return typeof value['thinking'] === 'string';
+    case 'redacted_thinking':
+      return typeof value['data'] === 'string';
+    case 'server_tool_use':
+      return typeof value['id'] === 'string' && typeof value['name'] === 'string';
+    case 'web_search_tool_result':
+      return typeof value['tool_use_id'] === 'string' && 'content' in value;
+    case 'container_upload':
+      return typeof value['file_id'] === 'string';
+    default:
+      return false;
+  }
+}
+
+function isMessageContentInput(value: unknown): value is MessageContentInput {
+  return (
+    typeof value === 'string' ||
+    (Array.isArray(value) && value.every(isMultiModalContentPart)) ||
+    isMultiModalContentPart(value)
+  );
+}
+
+function isLooseMessageInput(value: unknown): value is LooseMessageInput {
+  return (
+    isRecord(value) &&
+    typeof value['role'] === 'string' &&
+    MESSAGE_ROLES.has(value['role']) &&
+    isMessageContentInput(value['content']) &&
+    (value['hidden'] === undefined || typeof value['hidden'] === 'boolean') &&
+    (value['goalCompleted'] === undefined || typeof value['goalCompleted'] === 'boolean')
+  );
+}
+
+function isMetadataRecord(value: unknown): value is Record<string, JSONValue> {
+  return isJsonObject(value);
+}
+
+function resolveEnvironment(environment?: ConversationEnvironmentInput): {
+  now: () => string;
+  randomId: () => string;
+  plugins: NonNullable<ConversationEnvironmentInput['plugins']>;
+} {
+  const plugins = environment?.plugins ?? [];
+  if (!Array.isArray(plugins) || plugins.some((plugin) => typeof plugin !== 'function')) {
+    throw new Error('conversation environment plugins must be functions');
+  }
+  return {
+    now: environment?.now ?? (() => new Date().toISOString()),
+    randomId: environment?.randomId ?? createId,
+    plugins: [...plugins],
+  };
+}
+
+function cloneStructuredValue<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function cloneMetadata(metadata: Record<string, JSONValue> | undefined): Record<string, JSONValue> {
+  if (metadata === undefined) return {};
+  assertJsonObject(metadata, 'metadata');
+  return cloneStructuredValue(metadata);
+}
+
+function normalizeContent(content: MessageContentInput): MessageInput['content'] {
+  if (typeof content === 'string') return content;
+  return Array.isArray(content) ? cloneStructuredValue(content) : [cloneStructuredValue(content)];
+}
+
+function cloneTokenUsage(tokenUsage: TokenUsage): TokenUsage {
+  assertJsonObject(tokenUsage, 'tokenUsage');
+  const values = Object.values(tokenUsage);
+  if (values.some((value) => typeof value !== 'number')) {
+    throw new Error('tokenUsage values must be numbers');
+  }
+  if (
+    values.some((value) => typeof value === 'number' && (!Number.isInteger(value) || value < 0))
+  ) {
+    throw new Error('tokenUsage values must be non-negative integers');
+  }
+  return cloneStructuredValue(tokenUsage);
+}
+
+function cloneToolCall(toolCall: ToolCall): ToolCall {
+  assertJsonObject(toolCall, 'toolCall');
+  if (
+    typeof toolCall.id !== 'string' ||
+    typeof toolCall.name !== 'string' ||
+    !('arguments' in toolCall) ||
+    !isJsonValue(toolCall.arguments)
+  ) {
+    throw new Error('toolCall must include string id, string name, and JSON arguments');
+  }
+  return cloneStructuredValue(toolCall);
+}
+
+function cloneToolResult(toolResult: ToolResult): ToolResult {
+  assertJsonObject(toolResult, 'toolResult');
+  if (
+    typeof toolResult.callId !== 'string' ||
+    !['success', 'error', 'action_required'].includes(String(toolResult.outcome)) ||
+    !('content' in toolResult) ||
+    !isJsonValue(toolResult.content)
+  ) {
+    throw new Error('toolResult must include string callId, valid outcome, and JSON content');
+  }
+  return cloneStructuredValue(toolResult);
+}
+
+function getOrderedMessages(conversation: ConversationHistory): Message[] {
+  return conversation.ids
+    .map((id) => conversation.messages[id])
+    .filter((message): message is Message => message !== undefined);
+}
+
+function buildToolCallIds(messages: ReadonlyArray<Message>): Set<string> {
+  const toolCallIds = new Set<string>();
+  for (const message of messages) {
+    if (message.role === 'tool-call' && message.toolCall !== undefined) {
+      if (toolCallIds.has(message.toolCall.id)) {
+        throw new Error(`duplicate toolCall.id in conversation: ${message.toolCall.id}`);
+      }
+      toolCallIds.add(message.toolCall.id);
+    }
+  }
+  return toolCallIds;
+}
+
+function assertValidToolMessage(input: LooseMessageInput, toolCallIds: Set<string>): void {
+  if (input.role === 'tool-result' && input.toolResult !== undefined) {
+    if (!toolCallIds.has(input.toolResult.callId)) {
+      throw new Error(`tool result references non-existent tool-call: ${input.toolResult.callId}`);
+    }
+  }
+  if (input.role === 'tool-call' && input.toolCall !== undefined) {
+    if (toolCallIds.has(input.toolCall.id)) {
+      throw new Error(`duplicate toolCall.id in conversation: ${input.toolCall.id}`);
+    }
+    toolCallIds.add(input.toolCall.id);
+  }
+}
 
 /** Creates a new empty conversation snapshot. */
-const createConversation = createConversationHistory;
+function createConversation(
+  options: CreateConversationOptions = {},
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory {
+  const resolvedEnvironment = resolveEnvironment(environment);
+  const createdAt = resolvedEnvironment.now();
+  const conversationId = options.id ?? resolvedEnvironment.randomId();
+  if (typeof conversationId !== 'string') {
+    throw new Error('conversation id must be a string');
+  }
+  if (typeof createdAt !== 'string') {
+    throw new Error('conversation timestamp must be a string');
+  }
+  if (options.title !== undefined && typeof options.title !== 'string') {
+    throw new Error('conversation title must be a string');
+  }
+  if (options.status !== undefined && !CONVERSATION_STATUSES.has(options.status)) {
+    throw new Error('conversation status must be active, archived, or deleted');
+  }
+  return {
+    schemaVersion: 4,
+    id: conversationId,
+    ...(options.title !== undefined ? { title: options.title } : {}),
+    status: options.status ?? 'active',
+    metadata: cloneMetadata(options.metadata),
+    ids: [],
+    messages: {},
+    createdAt,
+    updatedAt: createdAt,
+  };
+}
+
+function materializeMessage(
+  input: LooseMessageInput,
+  position: number,
+  createdAt: string,
+  id: string,
+): Message {
+  return {
+    id,
+    role: input.role,
+    content: normalizeContent(input.content),
+    position,
+    createdAt,
+    metadata: cloneMetadata(input.metadata),
+    hidden: input.hidden ?? false,
+    ...(input.toolCall !== undefined ? { toolCall: cloneToolCall(input.toolCall) } : {}),
+    ...(input.toolResult !== undefined ? { toolResult: cloneToolResult(input.toolResult) } : {}),
+    ...(input.tokenUsage !== undefined ? { tokenUsage: cloneTokenUsage(input.tokenUsage) } : {}),
+    ...(input.role === 'assistant' && input.goalCompleted !== undefined
+      ? { goalCompleted: input.goalCompleted }
+      : {}),
+  };
+}
+
+function partitionAppendArguments(args: unknown[]): {
+  inputs: LooseMessageInput[];
+  environment?: ConversationEnvironmentInput;
+} {
+  const filteredArguments = args.at(-1) === undefined ? args.slice(0, -1) : args;
+  if (filteredArguments.some((argument) => argument === undefined)) {
+    throw new Error(
+      'appendMessages expected MessageInput arguments before the optional environment',
+    );
+  }
+  const lastArgument = filteredArguments.at(-1);
+  const inputArguments = isConversationEnvironmentParameter(lastArgument)
+    ? filteredArguments.slice(0, -1)
+    : filteredArguments;
+  const inputs: LooseMessageInput[] = [];
+  for (const argument of inputArguments) {
+    if (!isLooseMessageInput(argument)) {
+      throw new Error(
+        'appendMessages expected MessageInput arguments before the optional environment',
+      );
+    }
+    inputs.push(argument);
+  }
+  if (isConversationEnvironmentParameter(lastArgument)) {
+    return { inputs, environment: lastArgument };
+  }
+  return { inputs };
+}
 
 /** Appends one or more messages, preserving the previous no-op identity contract. */
 function appendMessages(
   conversation: ConversationHistory,
   ...inputs: MessageInput[]
+): ConversationHistory;
+function appendMessages(
+  conversation: ConversationHistory,
+  ...inputsAndEnvironment: [...MessageInput[], ConversationEnvironmentInput | undefined]
+): ConversationHistory;
+function appendMessages(
+  conversation: ConversationHistory,
+  ...args: unknown[]
 ): ConversationHistory {
+  const { inputs, environment } = partitionAppendArguments(args);
   if (inputs.length === 0) return conversation;
-  return appendConversationalistMessages(conversation, ...inputs);
+  const resolvedEnvironment = resolveEnvironment(environment);
+  const updatedAt = resolvedEnvironment.now();
+  if (typeof updatedAt !== 'string') {
+    throw new Error('conversation timestamp must be a string');
+  }
+  const nextIds = [...conversation.ids];
+  const nextMessages = { ...conversation.messages };
+  const toolCallIds = buildToolCallIds(getOrderedMessages(conversation));
+
+  inputs.forEach((input, index) => {
+    const normalizedInput: MessageInput = { ...input, content: normalizeContent(input.content) };
+    const processedInput = resolvedEnvironment.plugins.reduce(
+      (current, plugin) => plugin(current),
+      normalizedInput,
+    );
+    if (!isLooseMessageInput(processedInput)) {
+      throw new Error('conversation plugin returned an invalid MessageInput');
+    }
+    assertValidToolMessage(processedInput, toolCallIds);
+    const messageId = resolvedEnvironment.randomId();
+    if (typeof messageId !== 'string') {
+      throw new Error('generated message id must be a string');
+    }
+    if (nextMessages[messageId] !== undefined || nextIds.includes(messageId)) {
+      throw new Error(`duplicate message id in conversation: ${messageId}`);
+    }
+    const message = materializeMessage(
+      processedInput,
+      conversation.ids.length + index,
+      updatedAt,
+      messageId,
+    );
+    nextIds.push(message.id);
+    nextMessages[message.id] = message;
+  });
+
+  return {
+    ...conversation,
+    ids: nextIds,
+    messages: nextMessages,
+    updatedAt,
+  };
 }
 
-const appendUserMessage = appendConversationalistUserMessage;
-const appendAssistantMessage = appendConversationalistAssistantMessage;
+function appendUserMessage(
+  conversation: ConversationHistory,
+  content: MessageInput['content'],
+  metadata?: Record<string, JSONValue>,
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory;
+function appendUserMessage(
+  conversation: ConversationHistory,
+  content: MessageInput['content'],
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory;
+function appendUserMessage(
+  conversation: ConversationHistory,
+  content: MessageInput['content'],
+  metadataOrEnvironment?: Record<string, JSONValue> | ConversationEnvironmentInput,
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory {
+  const metadata = resolveRoleHelperMetadata(metadataOrEnvironment, environment);
+  const resolvedEnvironment =
+    environment ??
+    (isRoleHelperEnvironmentParameter(metadataOrEnvironment) ? metadataOrEnvironment : undefined);
+  return appendMessages(conversation, { role: 'user', content, metadata }, resolvedEnvironment);
+}
+
+function appendAssistantMessage(
+  conversation: ConversationHistory,
+  content: MessageInput['content'],
+  metadata?: Record<string, JSONValue>,
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory;
+function appendAssistantMessage(
+  conversation: ConversationHistory,
+  content: MessageInput['content'],
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory;
+function appendAssistantMessage(
+  conversation: ConversationHistory,
+  content: MessageInput['content'],
+  metadataOrEnvironment?: Record<string, JSONValue> | ConversationEnvironmentInput,
+  environment?: ConversationEnvironmentInput,
+): ConversationHistory {
+  const metadata = resolveRoleHelperMetadata(metadataOrEnvironment, environment);
+  const resolvedEnvironment =
+    environment ??
+    (isRoleHelperEnvironmentParameter(metadataOrEnvironment) ? metadataOrEnvironment : undefined);
+  return appendMessages(
+    conversation,
+    { role: 'assistant', content, metadata },
+    resolvedEnvironment,
+  );
+}
+
+function resolveRoleHelperMetadata(
+  metadataOrEnvironment: Record<string, JSONValue> | ConversationEnvironmentInput | undefined,
+  environment: ConversationEnvironmentInput | undefined,
+): Record<string, JSONValue> | undefined {
+  if (metadataOrEnvironment === undefined) return undefined;
+  if (environment === undefined && isRoleHelperEnvironmentParameter(metadataOrEnvironment)) {
+    return undefined;
+  }
+  if (isMetadataRecord(metadataOrEnvironment)) return metadataOrEnvironment;
+  throw new Error('metadata must be a JSON-compatible object');
+}
 
 export { appendAssistantMessage, appendMessages, appendUserMessage, createConversation };