conversationalist 0.0.10 → 0.0.11

package/dist/markdown/index.js

@@ -5001,6 +5001,263 @@ class EventEmission {
   }
 }
 
+// src/errors.ts
+class ConversationalistError extends Error {
+  code;
+  context;
+  cause;
+  constructor(code, message, options2) {
+    super(message);
+    this.name = "ConversationalistError";
+    this.code = code;
+    this.context = options2?.context;
+    this.cause = options2?.cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ConversationalistError);
+    }
+  }
+  toDetailedString() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.context && Object.keys(this.context).length > 0) {
+      parts.push(`Context: ${JSON.stringify(this.context, null, 2)}`);
+    }
+    if (this.cause) {
+      parts.push(`Caused by: ${this.cause.message}`);
+    }
+    return parts.join(`
+`);
+  }
+}
+function createInvalidPositionError(expected, actual) {
+  return new ConversationalistError("error:invalid-position", `invalid position: expected ${expected}, got ${actual}`, { context: { expected, actual } });
+}
+function createInvalidToolReferenceError(callId) {
+  return new ConversationalistError("error:invalid-tool-reference", `tool result references non-existent tool-use: ${callId}`, { context: { callId } });
+}
+function createSerializationError(message, cause) {
+  return new ConversationalistError("error:serialization", message, { cause });
+}
+function createValidationError(message, context, cause) {
+  return new ConversationalistError("error:validation", message, { context, cause });
+}
+function createIntegrityError(message, context) {
+  return new ConversationalistError("error:integrity", message, { context });
+}
+
+// src/schemas.ts
+import { z } from "zod";
+var isPlainObject = (value) => {
+  if (!value || typeof value !== "object")
+    return false;
+  const prototype = Reflect.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+function toMultiModalContent(value) {
+  const result = { type: value.type };
+  if (value.text !== undefined)
+    result.text = value.text;
+  if (value.url !== undefined)
+    result.url = value.url;
+  if (value.mimeType !== undefined)
+    result.mimeType = value.mimeType;
+  return result;
+}
+var jsonValueSchema = z.lazy(() => {
+  const jsonObjectSchema = z.preprocess((value, ctx) => {
+    if (!isPlainObject(value)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "expected a plain object"
+      });
+      return z.NEVER;
+    }
+    return value;
+  }, z.record(z.string(), jsonValueSchema));
+  return z.union([
+    z.string(),
+    z.number().refine((value) => Number.isFinite(value), {
+      message: "expected a finite number"
+    }),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    jsonObjectSchema
+  ]);
+});
+var multiModalContentSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("text"),
+    text: z.string()
+  }),
+  z.object({
+    type: z.literal("image"),
+    url: z.string().url(),
+    mimeType: z.string().optional(),
+    text: z.string().optional()
+  })
+]).transform(toMultiModalContent);
+var messageRoleSchema = z.enum([
+  "user",
+  "assistant",
+  "system",
+  "developer",
+  "tool-use",
+  "tool-result",
+  "snapshot"
+]);
+var toolCallSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  arguments: jsonValueSchema
+}).strict();
+var toolResultSchema = z.object({
+  callId: z.string(),
+  outcome: z.enum(["success", "error"]),
+  content: jsonValueSchema
+}).strict();
+var tokenUsageSchema = z.object({
+  prompt: z.number().int().min(0),
+  completion: z.number().int().min(0),
+  total: z.number().int().min(0)
+});
+var messageInputSchema = z.object({
+  role: messageRoleSchema,
+  content: z.union([z.string(), z.array(multiModalContentSchema)]),
+  metadata: z.record(z.string(), jsonValueSchema).optional(),
+  hidden: z.boolean().optional(),
+  toolCall: toolCallSchema.optional(),
+  toolResult: toolResultSchema.optional(),
+  tokenUsage: tokenUsageSchema.optional(),
+  goalCompleted: z.boolean().optional()
+}).strict();
+var messageSchema = z.object({
+  id: z.string(),
+  role: messageRoleSchema,
+  content: z.union([z.string(), z.array(multiModalContentSchema)]),
+  position: z.number().int().min(0),
+  createdAt: z.string(),
+  metadata: z.record(z.string(), jsonValueSchema),
+  hidden: z.boolean(),
+  toolCall: toolCallSchema.optional(),
+  toolResult: toolResultSchema.optional(),
+  tokenUsage: tokenUsageSchema.optional(),
+  goalCompleted: z.boolean().optional()
+}).strict();
+var conversationStatusSchema = z.enum([
+  "active",
+  "archived",
+  "deleted"
+]);
+var conversationShape = {
+  schemaVersion: z.number().int().min(1),
+  id: z.string(),
+  title: z.string().optional(),
+  status: conversationStatusSchema,
+  metadata: z.record(z.string(), jsonValueSchema),
+  ids: z.array(z.string()),
+  messages: z.record(z.string(), messageSchema),
+  createdAt: z.string(),
+  updatedAt: z.string()
+};
+var conversationSchema = z.object(conversationShape).strict();
+
+// src/conversation/integrity.ts
+function validateConversationIntegrity(conversation) {
+  const issues = [];
+  const seenIds = new Set;
+  conversation.ids.forEach((id, index) => {
+    if (seenIds.has(id)) {
+      issues.push({
+        code: "integrity:duplicate-message-id",
+        message: `duplicate message id in ids: ${id}`,
+        data: { id, position: index }
+      });
+    } else {
+      seenIds.add(id);
+    }
+    if (!conversation.messages[id]) {
+      issues.push({
+        code: "integrity:missing-message",
+        message: `missing message for id ${id}`,
+        data: { id, position: index }
+      });
+    }
+  });
+  for (const id of Object.keys(conversation.messages)) {
+    if (!seenIds.has(id)) {
+      issues.push({
+        code: "integrity:unlisted-message",
+        message: `message ${id} is not listed in ids`,
+        data: { id }
+      });
+    }
+  }
+  const toolUses = new Map;
+  conversation.ids.forEach((id, index) => {
+    const message = conversation.messages[id];
+    if (!message)
+      return;
+    if (message.role === "tool-use" && message.toolCall) {
+      if (toolUses.has(message.toolCall.id)) {
+        issues.push({
+          code: "integrity:duplicate-tool-call",
+          message: `duplicate toolCall.id ${message.toolCall.id}`,
+          data: { toolCallId: message.toolCall.id, messageId: message.id }
+        });
+      } else {
+        toolUses.set(message.toolCall.id, { position: index, messageId: message.id });
+      }
+    }
+  });
+  conversation.ids.forEach((id, index) => {
+    const message = conversation.messages[id];
+    if (!message)
+      return;
+    if (message.role === "tool-result" && message.toolResult) {
+      const toolUse = toolUses.get(message.toolResult.callId);
+      if (!toolUse) {
+        issues.push({
+          code: "integrity:orphan-tool-result",
+          message: `tool-result references missing tool-use ${message.toolResult.callId}`,
+          data: { callId: message.toolResult.callId, messageId: message.id }
+        });
+      } else if (toolUse.position >= index) {
+        issues.push({
+          code: "integrity:tool-result-before-call",
+          message: `tool-result ${message.toolResult.callId} occurs before tool-use`,
+          data: {
+            callId: message.toolResult.callId,
+            messageId: message.id,
+            toolUseMessageId: toolUse.messageId
+          }
+        });
+      }
+    }
+  });
+  return issues;
+}
+function assertConversationIntegrity(conversation) {
+  const issues = validateConversationIntegrity(conversation);
+  if (issues.length === 0)
+    return;
+  throw createIntegrityError("conversation integrity check failed", { issues });
+}
+
+// src/conversation/validation.ts
+function assertConversationSafe(conversation) {
+  const parsed = conversationSchema.safeParse(conversation);
+  if (!parsed.success) {
+    throw createValidationError("conversation failed schema validation", {
+      issues: parsed.error.issues
+    });
+  }
+  assertConversationIntegrity(conversation);
+}
+function ensureConversationSafe(conversation) {
+  assertConversationSafe(conversation);
+  return conversation;
+}
+
 // src/utilities/content.ts
 function normalizeContent(content) {
   if (content === undefined)
@@ -5165,6 +5422,92 @@ var cloneMessageWithPosition = (message, position, content) => {
   }
   return createMessage(baseMessage);
 };
+var createMessageBlock = (message, estimator) => ({
+  messages: [message],
+  minPosition: message.position,
+  maxPosition: message.position,
+  tokenCount: estimator(message)
+});
+var buildMessageBlocks = (messages, estimator, preserveToolPairs) => {
+  if (!preserveToolPairs) {
+    const blocks2 = messages.map((message) => createMessageBlock(message, estimator));
+    const messageToBlock2 = new Map;
+    for (const block of blocks2) {
+      const message = block.messages[0];
+      if (message) {
+        messageToBlock2.set(message.id, block);
+      }
+    }
+    return { blocks: blocks2, messageToBlock: messageToBlock2 };
+  }
+  const blocks = [];
+  const toolUses = new Map;
+  for (const message of messages) {
+    if (message.role === "tool-use" && message.toolCall) {
+      const block = createMessageBlock(message, estimator);
+      toolUses.set(message.toolCall.id, block);
+      blocks.push(block);
+      continue;
+    }
+    if (message.role === "tool-result" && message.toolResult) {
+      const existing = toolUses.get(message.toolResult.callId);
+      if (existing) {
+        existing.messages.push(message);
+        existing.maxPosition = Math.max(existing.maxPosition, message.position);
+        existing.tokenCount += estimator(message);
+        continue;
+      }
+      const orphanBlock = createMessageBlock(message, estimator);
+      orphanBlock.orphanToolResult = true;
+      blocks.push(orphanBlock);
+      continue;
+    }
+    blocks.push(createMessageBlock(message, estimator));
+  }
+  const filteredBlocks = blocks.filter((block) => !block.orphanToolResult);
+  const messageToBlock = new Map;
+  for (const block of filteredBlocks) {
+    for (const message of block.messages) {
+      messageToBlock.set(message.id, block);
+    }
+  }
+  return { blocks: filteredBlocks, messageToBlock };
+};
+var collectBlocksForMessages = (messages, messageToBlock) => {
+  const blocks = [];
+  const seen = new Set;
+  for (const message of messages) {
+    const block = messageToBlock.get(message.id);
+    if (block && !seen.has(block)) {
+      seen.add(block);
+      blocks.push(block);
+    }
+  }
+  return blocks;
+};
+var collectMessagesFromBlocks = (blocks) => {
+  const messages = [];
+  const seen = new Set;
+  for (const block of blocks) {
+    for (const message of block.messages) {
+      if (!seen.has(message.id)) {
+        seen.add(message.id);
+        messages.push(message);
+      }
+    }
+  }
+  messages.sort((a, b) => a.position - b.position);
+  return messages;
+};
+var ensureTruncationSafe = (conversation, preserveToolPairs, operation) => {
+  try {
+    return ensureConversationSafe(conversation);
+  } catch (error2) {
+    if (!preserveToolPairs && error2 instanceof ConversationalistError && error2.code === "error:integrity")
+      throw createIntegrityError(`${operation} produced invalid tool linkage; use preserveToolPairs: true to keep tool interactions intact`, { preserveToolPairs, issues: error2.context?.["issues"] });
+    throw error2;
+  }
+};
 function estimateConversationTokens(conversation, estimateTokens, environment) {
   let estimator = estimateTokens;
   let env = environment;
@@ -5177,6 +5520,7 @@ function estimateConversationTokens(conversation, estimateTokens, environment) {
   return getOrderedMessages(conversation).reduce((total, message) => total + finalEstimator(message), 0);
 }
 function truncateToTokenLimit(conversation, maxTokens, optionsOrEstimator, environment) {
+  assertConversationSafe(conversation);
   let options2 = {};
   let env = environment;
   if (typeof optionsOrEstimator === "function") {
@@ -5198,54 +5542,56 @@ function truncateToTokenLimit(conversation, maxTokens, optionsOrEstimator, envir
   const estimator = options2.estimateTokens ?? resolvedEnvironment.estimateTokens;
   const preserveSystem = options2.preserveSystemMessages ?? true;
   const preserveLastN = options2.preserveLastN ?? 0;
+  const preserveToolPairs = options2.preserveToolPairs ?? true;
   const currentTokens = estimateConversationTokens(conversation, estimator, resolvedEnvironment);
   if (currentTokens <= maxTokens) {
     return conversation;
   }
   const now = resolvedEnvironment.now();
   const orderedMessages = getOrderedMessages(conversation);
+  const { blocks, messageToBlock } = buildMessageBlocks(orderedMessages, estimator, preserveToolPairs);
   const systemMessages = preserveSystem ? orderedMessages.filter((m) => m.role === "system") : [];
   const nonSystemMessages = orderedMessages.filter((m) => m.role !== "system");
   const protectedMessages = preserveLastN > 0 ? nonSystemMessages.slice(-preserveLastN) : [];
-  const removableMessages = preserveLastN > 0 ? nonSystemMessages.slice(0, -preserveLastN) : nonSystemMessages;
-  const systemTokens = systemMessages.reduce((sum, m) => sum + estimator(m), 0);
-  const protectedTokens = protectedMessages.reduce((sum, m) => sum + estimator(m), 0);
+  const systemBlocks = collectBlocksForMessages(systemMessages, messageToBlock);
+  const protectedBlocks = collectBlocksForMessages(protectedMessages, messageToBlock);
+  const lockedBlocks = new Set([...systemBlocks, ...protectedBlocks]);
+  const removableBlocks = blocks.filter((block) => !lockedBlocks.has(block));
+  const systemTokens = systemBlocks.reduce((sum, block) => sum + block.tokenCount, 0);
+  const protectedTokens = protectedBlocks.reduce((sum, block) => sum + block.tokenCount, 0);
   const availableTokens = maxTokens - systemTokens - protectedTokens;
+  let selectedBlocks = [];
   if (availableTokens <= 0) {
-    const allMessages2 = [...systemMessages, ...protectedMessages];
-    const renumbered2 = allMessages2.map((message, index) => cloneMessageWithPosition(message, index, copyContent(message.content)));
-    return toReadonly({
-      ...conversation,
-      ids: renumbered2.map((message) => message.id),
-      messages: toIdRecord(renumbered2),
-      updatedAt: now
-    });
-  }
-  const keptRemovable = [];
-  let usedTokens = 0;
-  for (let i = removableMessages.length - 1;i >= 0; i--) {
-    const message = removableMessages[i];
-    const messageTokens = estimator(message);
-    if (usedTokens + messageTokens <= availableTokens) {
-      keptRemovable.unshift(message);
-      usedTokens += messageTokens;
-    } else {
-      break;
+    selectedBlocks = [...systemBlocks, ...protectedBlocks];
+  } else {
+    const sortedRemovable = [...removableBlocks].sort((a, b) => a.maxPosition - b.maxPosition);
+    const keptRemovable = [];
+    let usedTokens = 0;
+    for (let i = sortedRemovable.length - 1;i >= 0; i--) {
+      const block = sortedRemovable[i];
+      if (usedTokens + block.tokenCount <= availableTokens) {
+        keptRemovable.unshift(block);
+        usedTokens += block.tokenCount;
+      } else {
+        break;
+      }
     }
+    selectedBlocks = [...systemBlocks, ...keptRemovable, ...protectedBlocks];
   }
-  const allMessages = [...systemMessages, ...keptRemovable, ...protectedMessages];
-  allMessages.sort((a, b) => a.position - b.position);
+  const allMessages = collectMessagesFromBlocks(selectedBlocks);
   const renumbered = allMessages.map((message, index) => cloneMessageWithPosition(message, index, copyContent(message.content)));
-  return toReadonly({
+  const next2 = toReadonly({
     ...conversation,
     ids: renumbered.map((message) => message.id),
     messages: toIdRecord(renumbered),
     updatedAt: now
   });
+  return ensureTruncationSafe(next2, preserveToolPairs, "truncateToTokenLimit");
 }
 function getRecentMessages(conversation, count, options2) {
   const includeHidden = options2?.includeHidden ?? false;
   const includeSystem = options2?.includeSystem ?? false;
+  const preserveToolPairs = options2?.preserveToolPairs ?? true;
   const filtered = getOrderedMessages(conversation).filter((m) => {
     if (!includeHidden && m.hidden)
       return false;
@@ -5253,66 +5599,58 @@ function getRecentMessages(conversation, count, options2) {
       return false;
     return true;
   });
-  return filtered.slice(-count);
+  if (!preserveToolPairs) {
+    return filtered.slice(-count);
+  }
+  const { messageToBlock } = buildMessageBlocks(filtered, () => 0, preserveToolPairs);
+  const tail = filtered.slice(-count);
+  const blocks = collectBlocksForMessages(tail, messageToBlock);
+  return collectMessagesFromBlocks(blocks);
 }
 function truncateFromPosition(conversation, position, options2, environment) {
+  assertConversationSafe(conversation);
   const preserveSystem = options2?.preserveSystemMessages ?? true;
+  const preserveToolPairs = options2?.preserveToolPairs ?? true;
   const resolvedEnvironment = resolveConversationEnvironment(environment);
   const now = resolvedEnvironment.now();
   const ordered = getOrderedMessages(conversation);
+  const { messageToBlock } = buildMessageBlocks(ordered, () => 0, preserveToolPairs);
   const systemMessages = preserveSystem ? ordered.filter((m) => m.role === "system" && m.position < position) : [];
   const keptMessages = ordered.filter((m) => m.position >= position);
-  const allMessages = [...systemMessages, ...keptMessages];
+  const systemBlocks = collectBlocksForMessages(systemMessages, messageToBlock);
+  const keptBlocks = collectBlocksForMessages(keptMessages, messageToBlock);
+  const allMessages = collectMessagesFromBlocks([...systemBlocks, ...keptBlocks]);
   const renumbered = allMessages.map((message, index) => cloneMessageWithPosition(message, index, copyContent(message.content)));
-  return toReadonly({
+  const next2 = toReadonly({
     ...conversation,
     ids: renumbered.map((message) => message.id),
     messages: toIdRecord(renumbered),
     updatedAt: now
   });
-}
-
-// src/errors.ts
-class ConversationalistError extends Error {
-  code;
-  context;
-  cause;
-  constructor(code, message, options2) {
-    super(message);
-    this.name = "ConversationalistError";
-    this.code = code;
-    this.context = options2?.context;
-    this.cause = options2?.cause;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, ConversationalistError);
-    }
-  }
-  toDetailedString() {
-    const parts = [`[${this.code}] ${this.message}`];
-    if (this.context && Object.keys(this.context).length > 0) {
-      parts.push(`Context: ${JSON.stringify(this.context, null, 2)}`);
-    }
-    if (this.cause) {
-      parts.push(`Caused by: ${this.cause.message}`);
-    }
-    return parts.join(`
-`);
-  }
-}
-function createInvalidPositionError(expected, actual) {
-  return new ConversationalistError("error:invalid-position", `invalid position: expected ${expected}, got ${actual}`, { context: { expected, actual } });
-}
-function createInvalidToolReferenceError(callId) {
-  return new ConversationalistError("error:invalid-tool-reference", `tool result references non-existent tool-use: ${callId}`, { context: { callId } });
-}
-function createSerializationError(message, cause) {
-  return new ConversationalistError("error:serialization", message, { cause });
+  return ensureTruncationSafe(next2, preserveToolPairs, "truncateFromPosition");
 }
 
 // src/types.ts
 var CURRENT_SCHEMA_VERSION = 3;
 
-// src/conversation.ts
+// src/conversation/create.ts
+function createConversation(options2, environment) {
+  const resolvedEnvironment = resolveConversationEnvironment(environment);
+  const now = resolvedEnvironment.now();
+  const conv = {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    id: options2?.id ?? resolvedEnvironment.randomId(),
+    title: options2?.title,
+    status: options2?.status ?? "active",
+    metadata: { ...options2?.metadata ?? {} },
+    ids: [],
+    messages: {},
+    createdAt: now,
+    updatedAt: now
+  };
+  return ensureConversationSafe(toReadonly(conv));
+}
+// src/conversation/tool-tracking.ts
 var buildToolUseIndex = (messages) => messages.reduce((index, message) => {
   if (message.role === "tool-use" && message.toolCall) {
     index.set(message.toolCall.id, { name: message.toolCall.name });
@@ -5329,44 +5667,34 @@ var assertToolReference = (index, callId) => {
     throw createInvalidToolReferenceError(callId);
   }
 };
+
+// src/conversation/append.ts
 function partitionAppendArgs(args) {
-  if (args.length === 0) {
+  const filtered = args.filter((arg) => arg !== undefined);
+  if (filtered.length === 0) {
     return { inputs: [] };
   }
-  const last = args[args.length - 1];
+  const last = filtered[filtered.length - 1];
   if (isConversationEnvironmentParameter(last)) {
     return {
-      inputs: args.slice(0, -1),
+      inputs: filtered.slice(0, -1),
       environment: last
     };
   }
-  return { inputs: args };
-}
-function createConversation(options2, environment) {
-  const resolvedEnvironment = resolveConversationEnvironment(environment);
-  const now = resolvedEnvironment.now();
-  const conv = {
-    schemaVersion: CURRENT_SCHEMA_VERSION,
-    id: options2?.id ?? resolvedEnvironment.randomId(),
-    title: options2?.title,
-    status: options2?.status ?? "active",
-    metadata: { ...options2?.metadata ?? {} },
-    ids: [],
-    messages: {},
-    createdAt: now,
-    updatedAt: now
-  };
-  return toReadonly(conv);
+  return { inputs: filtered };
 }
 function appendMessages(conversation, ...args) {
+  return appendMessagesInternal(conversation, args, true);
+}
+var appendMessagesInternal = (conversation, args, validate) => {
   const { inputs, environment } = partitionAppendArgs(args);
   const resolvedEnvironment = resolveConversationEnvironment(environment);
   const now = resolvedEnvironment.now();
   const startPosition = conversation.ids.length;
-  const initialToolUses = buildToolUseIndex(getOrderedMessages(conversation));
+  const initialToolUses = validate ? buildToolUseIndex(getOrderedMessages(conversation)) : new Map;
   const { messages } = inputs.reduce((state, input, index) => {
     const processedInput = resolvedEnvironment.plugins.reduce((acc, plugin) => plugin(acc), input);
-    if (processedInput.role === "tool-result" && processedInput.toolResult) {
+    if (validate && processedInput.role === "tool-result" && processedInput.toolResult) {
       assertToolReference(state.toolUses, processedInput.toolResult.callId);
     }
     const normalizedContent = normalizeContent(processedInput.content);
@@ -5393,7 +5721,16 @@ function appendMessages(conversation, ...args) {
     } else {
       message = createMessage(baseMessage);
     }
-    const toolUses = processedInput.role === "tool-use" && processedInput.toolCall ? registerToolUse(state.toolUses, processedInput.toolCall) : state.toolUses;
+    let toolUses = state.toolUses;
+    if (processedInput.role === "tool-use" && processedInput.toolCall) {
+      if (validate && state.toolUses.has(processedInput.toolCall.id)) {
+        throw createIntegrityError("duplicate toolCall.id in conversation", {
+          toolCallId: processedInput.toolCall.id,
+          messageId: baseMessage.id
+        });
+      }
+      toolUses = validate ? registerToolUse(state.toolUses, processedInput.toolCall) : state.toolUses;
+    }
     return {
       toolUses,
       messages: [...state.messages, message]
@@ -5406,17 +5743,25 @@ function appendMessages(conversation, ...args) {
     messages: { ...conversation.messages, ...toIdRecord(messages) },
     updatedAt: now
   };
-  return toReadonly(next2);
-}
+  const readonly = toReadonly(next2);
+  return validate ? ensureConversationSafe(readonly) : readonly;
+};
 function appendUserMessage(conversation, content, metadata, environment) {
-  return environment ? appendMessages(conversation, { role: "user", content, metadata }, environment) : appendMessages(conversation, { role: "user", content, metadata });
+  const resolvedEnvironment = isConversationEnvironmentParameter(metadata) ? metadata : environment;
+  const resolvedMetadata = isConversationEnvironmentParameter(metadata) ? undefined : metadata;
+  return appendMessages(conversation, { role: "user", content, metadata: resolvedMetadata }, resolvedEnvironment);
 }
 function appendAssistantMessage(conversation, content, metadata, environment) {
-  return environment ? appendMessages(conversation, { role: "assistant", content, metadata }, environment) : appendMessages(conversation, { role: "assistant", content, metadata });
+  const resolvedEnvironment = isConversationEnvironmentParameter(metadata) ? metadata : environment;
+  const resolvedMetadata = isConversationEnvironmentParameter(metadata) ? undefined : metadata;
+  return appendMessages(conversation, { role: "assistant", content, metadata: resolvedMetadata }, resolvedEnvironment);
 }
 function appendSystemMessage(conversation, content, metadata, environment) {
-  return environment ? appendMessages(conversation, { role: "system", content, metadata }, environment) : appendMessages(conversation, { role: "system", content, metadata });
+  const resolvedEnvironment = isConversationEnvironmentParameter(metadata) ? metadata : environment;
+  const resolvedMetadata = isConversationEnvironmentParameter(metadata) ? undefined : metadata;
+  return appendMessages(conversation, { role: "system", content, metadata: resolvedMetadata }, resolvedEnvironment);
 }
+// src/conversation/query.ts
 function getMessages(conversation, options2) {
   const includeHidden = options2?.includeHidden ?? false;
   const ordered = getOrderedMessages(conversation);
@@ -5450,6 +5795,7 @@ function getStatistics(conversation) {
   }, { byRole: {}, hidden: 0, withImages: 0 });
   return { total: ordered.length, ...stats };
 }
+// src/conversation/system-messages.ts
 function hasSystemMessage(conversation) {
   return getOrderedMessages(conversation).some((m) => m.role === "system");
 }
@@ -5460,7 +5806,8 @@ function getSystemMessages(conversation) {
   return getOrderedMessages(conversation).filter((m) => m.role === "system");
 }
 function prependSystemMessage(conversation, content, metadata, environment) {
-  const resolvedEnvironment = resolveConversationEnvironment(environment);
+  const resolvedEnvironment = resolveConversationEnvironment(isConversationEnvironmentParameter(metadata) ? metadata : environment);
+  const resolvedMetadata = isConversationEnvironmentParameter(metadata) ? undefined : metadata;
   const now = resolvedEnvironment.now();
   const newMessage = createMessage({
     id: resolvedEnvironment.randomId(),
@@ -5468,7 +5815,7 @@ function prependSystemMessage(conversation, content, metadata, environment) {
     content,
     position: 0,
     createdAt: now,
-    metadata: { ...metadata ?? {} },
+    metadata: { ...resolvedMetadata ?? {} },
     hidden: false,
     toolCall: undefined,
     toolResult: undefined,
@@ -5487,20 +5834,21 @@ function prependSystemMessage(conversation, content, metadata, environment) {
     toolResult: message.toolResult,
     tokenUsage: message.tokenUsage
   }));
-  return toReadonly({
+  return ensureConversationSafe(toReadonly({
     ...conversation,
     ids: [newMessage.id, ...ordered.map((message) => message.id)],
     messages: toIdRecord([newMessage, ...renumberedMessages]),
     updatedAt: now
-  });
+  }));
 }
 function replaceSystemMessage(conversation, content, metadata, environment) {
-  const resolvedEnvironment = resolveConversationEnvironment(environment);
+  const resolvedEnvironment = resolveConversationEnvironment(isConversationEnvironmentParameter(metadata) ? metadata : environment);
+  const resolvedMetadata = isConversationEnvironmentParameter(metadata) ? undefined : metadata;
   const now = resolvedEnvironment.now();
   const ordered = getOrderedMessages(conversation);
   const firstSystemIndex = ordered.findIndex((m) => m.role === "system");
   if (firstSystemIndex === -1) {
-    return prependSystemMessage(conversation, content, metadata, resolvedEnvironment);
+    return prependSystemMessage(conversation, content, resolvedMetadata, resolvedEnvironment);
   }
   const original = ordered[firstSystemIndex];
   const replaced = createMessage({
@@ -5509,7 +5857,7 @@ function replaceSystemMessage(conversation, content, metadata, environment) {
     content,
     position: original.position,
     createdAt: original.createdAt,
-    metadata: { ...metadata ?? original.metadata },
+    metadata: { ...resolvedMetadata ?? original.metadata },
     hidden: original.hidden,
     toolCall: undefined,
     toolResult: undefined,
@@ -5521,13 +5869,13 @@ function replaceSystemMessage(conversation, content, metadata, environment) {
     messages: { ...conversation.messages, [replaced.id]: replaced },
     updatedAt: now
   };
-  return toReadonly(next2);
+  return ensureConversationSafe(toReadonly(next2));
 }
 function collapseSystemMessages(conversation, environment) {
   const ordered = getOrderedMessages(conversation);
   const systemMessages = ordered.filter((m) => m.role === "system");
   if (systemMessages.length <= 1) {
-    return conversation;
+    return ensureConversationSafe(conversation);
   }
   const resolvedEnvironment = resolveConversationEnvironment(environment);
   const now = resolvedEnvironment.now();
@@ -5583,9 +5931,42 @@ function collapseSystemMessages(conversation, environment) {
     messages: toIdRecord(renumbered),
     updatedAt: now
   };
-  return toReadonly(next2);
+  return ensureConversationSafe(toReadonly(next2));
 }
-function redactMessageAtPosition(conversation, position, placeholder = "[REDACTED]", environment) {
+// src/utilities/tool-results.ts
+function copyToolResult(toolResult) {
+  return { ...toolResult };
+}
+function redactToolResult(toolResult, placeholder) {
+  return { ...toolResult, content: placeholder };
+}
+
+// src/conversation/modify.ts
+var isRedactMessageOptions = (value) => {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return "placeholder" in candidate || "redactToolArguments" in candidate || "redactToolResults" in candidate || "clearToolMetadata" in candidate;
+};
+function redactMessageAtPosition(conversation, position, placeholderOrOptions, environment) {
+  let placeholder = "[REDACTED]";
+  let options2 = {};
+  let env = environment;
+  if (typeof placeholderOrOptions === "string") {
+    placeholder = placeholderOrOptions;
+  } else if (placeholderOrOptions) {
+    if (!environment && isConversationEnvironmentParameter(placeholderOrOptions)) {
+      env = placeholderOrOptions;
+    } else if (isRedactMessageOptions(placeholderOrOptions)) {
+      options2 = placeholderOrOptions;
+      if (options2.placeholder) {
+        placeholder = options2.placeholder;
+      }
+    }
+  }
+  const redactToolArguments = options2.redactToolArguments ?? true;
+  const redactToolResults = options2.redactToolResults ?? true;
+  const clearToolMetadata = options2.clearToolMetadata ?? false;
   if (position < 0 || position >= conversation.ids.length) {
     throw createInvalidPositionError(conversation.ids.length - 1, position);
   }
@@ -5594,6 +5975,22 @@ function redactMessageAtPosition(conversation, position, placeholder = "[REDACTE
   if (!original) {
     throw createInvalidPositionError(conversation.ids.length - 1, position);
   }
+  let toolCall = original.toolCall ? { ...original.toolCall } : undefined;
+  let toolResult = original.toolResult ? { ...original.toolResult } : undefined;
+  if (clearToolMetadata) {
+    toolCall = undefined;
+    toolResult = undefined;
+  } else {
+    if (original.role === "tool-use" && toolCall) {
+      toolCall = {
+        ...toolCall,
+        arguments: redactToolArguments ? placeholder : toolCall.arguments
+      };
+    }
+    if (original.role === "tool-result" && toolResult) {
+      toolResult = redactToolResults ? redactToolResult(toolResult, placeholder) : { ...toolResult };
+    }
+  }
   const redacted = createMessage({
     id: original.id,
     role: original.role,
@@ -5602,11 +5999,11 @@ function redactMessageAtPosition(conversation, position, placeholder = "[REDACTE
     createdAt: original.createdAt,
     metadata: { ...original.metadata },
     hidden: original.hidden,
-    toolCall: undefined,
-    toolResult: undefined,
-    tokenUsage: undefined
+    toolCall,
+    toolResult,
+    tokenUsage: original.tokenUsage ? { ...original.tokenUsage } : undefined
   });
-  const resolvedEnvironment = resolveConversationEnvironment(environment);
+  const resolvedEnvironment = resolveConversationEnvironment(env);
   const now = resolvedEnvironment.now();
   const next2 = {
     ...conversation,
@@ -5614,70 +6011,62 @@ function redactMessageAtPosition(conversation, position, placeholder = "[REDACTE
     messages: { ...conversation.messages, [redacted.id]: redacted },
     updatedAt: now
   };
-  return toReadonly(next2);
+  return ensureConversationSafe(toReadonly(next2));
 }
-function migrateConversation(json) {
-  if (typeof json !== "object" || json === null || Array.isArray(json)) {
-    return {
-      schemaVersion: CURRENT_SCHEMA_VERSION,
-      id: "",
-      status: "active",
-      metadata: {},
-      ids: [],
-      messages: {},
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString()
-    };
-  }
-  const data = json;
-  const rawMessages = data.messages;
-  let messages = {};
-  let ids = [];
-  const rawIds = data.ids;
-  const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
-  if (Array.isArray(rawMessages)) {
-    const rawMessageArray = rawMessages;
-    ids = rawMessageArray.map((message) => message.id);
-    messages = Object.fromEntries(rawMessageArray.map((message) => [message.id, message]));
-  } else if (rawMessages && typeof rawMessages === "object") {
-    messages = { ...rawMessages };
-    if (isStringArray(rawIds) && rawIds.length > 0) {
-      ids = [...rawIds];
-    } else {
-      ids = Object.values(messages).sort((a, b) => a.position - b.position).map((message) => message.id);
-    }
-  }
-  if (ids.length > 0) {
-    ids = ids.filter((id) => (id in messages));
-    const missing = Object.keys(messages).filter((id) => !ids.includes(id));
-    if (missing.length > 0) {
-      const sortedMissing = missing.sort((a, b) => (messages[a]?.position ?? 0) - (messages[b]?.position ?? 0));
-      ids = [...ids, ...sortedMissing];
-    }
-  }
-  if (!("schemaVersion" in json)) {
+// src/conversation/serialization.ts
+function normalizeToolResult(toolResult) {
+  if (!toolResult)
+    return;
+  return {
+    callId: toolResult.callId,
+    outcome: toolResult.outcome,
+    content: toolResult.content
+  };
+}
+function normalizeMessage(message) {
+  const base = {
+    id: message.id,
+    role: message.role,
+    content: message.content,
+    position: message.position,
+    createdAt: message.createdAt,
+    metadata: message.metadata,
+    hidden: message.hidden,
+    toolCall: message.toolCall ? { ...message.toolCall } : undefined,
+    toolResult: normalizeToolResult(message.toolResult),
+    tokenUsage: message.tokenUsage ? { ...message.tokenUsage } : undefined
+  };
+  if (isAssistantMessage(message)) {
     return {
-      ...data,
-      schemaVersion: CURRENT_SCHEMA_VERSION,
-      ids,
-      messages
+      ...base,
+      role: "assistant",
+      goalCompleted: message.goalCompleted
     };
   }
-  return { ...data, ids, messages };
+  return base;
 }
 function deserializeConversation(json) {
-  const migrated = migrateConversation(json);
+  const parsed = conversationSchema.safeParse(json);
+  if (!parsed.success) {
+    throw createSerializationError("failed to deserialize conversation: invalid data");
+  }
+  const data = parsed.data;
   try {
-    const orderedMessages = migrated.ids.map((id, index) => {
-      const message = migrated.messages[id];
+    const messageIds = new Set(Object.keys(data.messages));
+    const orderedMessages = data.ids.map((id, index) => {
+      const message = data.messages[id];
       if (!message) {
         throw createSerializationError(`missing message for id ${id}`);
       }
       if (message.position !== index) {
         throw createInvalidPositionError(index, message.position);
       }
-      return message;
+      messageIds.delete(id);
+      return normalizeMessage(message);
     });
+    if (messageIds.size > 0) {
+      throw createSerializationError(`messages not listed in ids: ${[...messageIds].join(", ")}`);
+    }
     orderedMessages.reduce((state, message) => {
       if (message.role === "tool-use" && message.toolCall) {
         return {
@@ -5689,24 +6078,28 @@ function deserializeConversation(json) {
       }
       return state;
     }, { toolUses: new Map });
-    const messageInstances = orderedMessages.map((m) => createMessage(m));
+    const messageInstances = orderedMessages.map((message) => createMessage(message));
     const conv = {
-      schemaVersion: migrated.schemaVersion,
-      id: migrated.id,
-      title: migrated.title,
-      status: migrated.status,
-      metadata: { ...migrated.metadata },
+      schemaVersion: data.schemaVersion,
+      id: data.id,
+      title: data.title,
+      status: data.status,
+      metadata: { ...data.metadata },
       ids: orderedMessages.map((message) => message.id),
       messages: toIdRecord(messageInstances),
-      createdAt: migrated.createdAt,
-      updatedAt: migrated.updatedAt
+      createdAt: data.createdAt,
+      updatedAt: data.updatedAt
     };
-    return toReadonly(conv);
+    const readonly = toReadonly(conv);
+    assertConversationIntegrity(readonly);
+    return readonly;
   } catch (error2) {
     throw createSerializationError(`failed to deserialize conversation: ${error2 instanceof Error ? error2.message : String(error2)}`, error2);
   }
 }
+// src/conversation/transform.ts
 function toChatMessages(conversation) {
+  assertConversationSafe(conversation);
   const roleMap = {
     user: "user",
     assistant: "assistant",
@@ -5728,7 +6121,6 @@ function toChatMessages(conversation) {
   }
   return result;
 }
-
 // src/streaming.ts
 var STREAMING_KEY = "__streaming";
 var cloneMessage = (original, overrides = {}) => {
@@ -5761,7 +6153,8 @@ function getStreamingMessage(conversation) {
   return getOrderedMessages(conversation).find(isStreamingMessage);
 }
 function appendStreamingMessage(conversation, role, metadata, environment) {
-  const resolvedEnvironment = resolveConversationEnvironment(environment);
+  const resolvedEnvironment = resolveConversationEnvironment(isConversationEnvironmentParameter(metadata) ? metadata : environment);
+  const resolvedMetadata = isConversationEnvironmentParameter(metadata) ? undefined : metadata;
   const now = resolvedEnvironment.now();
   const messageId = resolvedEnvironment.randomId();
   const newMessage = createMessage({
@@ -5770,7 +6163,7 @@ function appendStreamingMessage(conversation, role, metadata, environment) {
     content: "",
     position: conversation.ids.length,
     createdAt: now,
-    metadata: { ...metadata ?? {}, [STREAMING_KEY]: true },
+    metadata: { ...resolvedMetadata ?? {}, [STREAMING_KEY]: true },
     hidden: false,
     toolCall: undefined,
     toolResult: undefined,
@@ -5782,14 +6175,14 @@ function appendStreamingMessage(conversation, role, metadata, environment) {
     messages: { ...conversation.messages, [messageId]: newMessage },
     updatedAt: now
   });
-  return { conversation: updatedConversation, messageId };
+  return { conversation: ensureConversationSafe(updatedConversation), messageId };
 }
 function updateStreamingMessage(conversation, messageId, content, environment) {
   const resolvedEnvironment = resolveConversationEnvironment(environment);
   const now = resolvedEnvironment.now();
   const original = conversation.messages[messageId];
   if (!original) {
-    return conversation;
+    return ensureConversationSafe(conversation);
   }
   const overrides = {
     content: typeof content === "string" ? content : [...content]
@@ -5798,44 +6191,45 @@ function updateStreamingMessage(conversation, messageId, content, environment) {
     overrides.tokenUsage = { ...original.tokenUsage };
   }
   const updated = cloneMessage(original, overrides);
-  return toReadonly({
+  return ensureConversationSafe(toReadonly({
     ...conversation,
     ids: [...conversation.ids],
     messages: { ...conversation.messages, [updated.id]: updated },
     updatedAt: now
-  });
+  }));
 }
 function finalizeStreamingMessage(conversation, messageId, options2, environment) {
-  const resolvedEnvironment = resolveConversationEnvironment(environment);
+  const resolvedEnvironment = resolveConversationEnvironment(isConversationEnvironmentParameter(options2) ? options2 : environment);
+  const resolvedOptions = isConversationEnvironmentParameter(options2) ? undefined : options2;
   const now = resolvedEnvironment.now();
   const original = conversation.messages[messageId];
   if (!original) {
-    return conversation;
+    return ensureConversationSafe(conversation);
   }
   const { [STREAMING_KEY]: _, ...restMetadata } = original.metadata;
   const finalMetadata = {
     ...restMetadata,
-    ...options2?.metadata ?? {}
+    ...resolvedOptions?.metadata ?? {}
   };
   const finalizeOverrides = {
     metadata: finalMetadata
   };
-  if (options2?.tokenUsage) {
-    finalizeOverrides.tokenUsage = { ...options2.tokenUsage };
+  if (resolvedOptions?.tokenUsage) {
+    finalizeOverrides.tokenUsage = { ...resolvedOptions.tokenUsage };
   }
   const updated = cloneMessage(original, finalizeOverrides);
-  return toReadonly({
+  return ensureConversationSafe(toReadonly({
     ...conversation,
     ids: [...conversation.ids],
     messages: { ...conversation.messages, [updated.id]: updated },
     updatedAt: now
-  });
+  }));
 }
 function cancelStreamingMessage(conversation, messageId, environment) {
   const resolvedEnvironment = resolveConversationEnvironment(environment);
   const now = resolvedEnvironment.now();
   if (!conversation.messages[messageId]) {
-    return conversation;
+    return ensureConversationSafe(conversation);
   }
   const messages = getOrderedMessages(conversation).filter((m) => m.id !== messageId).map((message, index) => message.position === index ? message : (() => {
     const overrides = {
@@ -5846,12 +6240,12 @@ function cancelStreamingMessage(conversation, messageId, environment) {
     }
     return cloneMessage(message, overrides);
   })());
-  return toReadonly({
+  return ensureConversationSafe(toReadonly({
     ...conversation,
     ids: messages.map((message) => message.id),
     messages: toIdRecord(messages),
     updatedAt: now
-  });
+  }));
 }
 
 // src/history.ts
@@ -5863,8 +6257,9 @@ class ConversationHistory extends EventTarget {
     super();
     this.environment = resolveConversationEnvironment(environment);
     this.events = createEventTarget();
+    const safeInitial = ensureConversationSafe(initial);
     this.currentNode = {
-      conversation: initial,
+      conversation: safeInitial,
       parent: null,
       children: []
     };
@@ -6062,8 +6457,8 @@ class ConversationHistory extends EventTarget {
   collapseSystemMessages() {
     this.push(collapseSystemMessages(this.current, this.env));
   }
-  redactMessageAtPosition(position, placeholder) {
-    this.push(redactMessageAtPosition(this.current, position, placeholder, this.env));
+  redactMessageAtPosition(position, placeholderOrOptions) {
+    this.push(redactMessageAtPosition(this.current, position, placeholderOrOptions, this.env));
   }
   truncateFromPosition(position, options2) {
     this.push(truncateFromPosition(this.current, position, options2, this.env));
@@ -6169,23 +6564,6 @@ function isConversation(value) {
 
 // src/utilities/markdown.ts
 var import_gray_matter = __toESM(require_gray_matter(), 1);
-
-// src/utilities/tool-results.ts
-function copyToolResult(toolResult) {
-  return { ...toolResult };
-}
-function redactToolResult(toolResult, placeholder) {
-  const result = { ...toolResult, content: placeholder };
-  if (result.result !== undefined) {
-    result.result = placeholder;
-  }
-  if (result.error !== undefined) {
-    result.error = placeholder;
-  }
-  return result;
-}
-
-// src/utilities/markdown.ts
 var ROLE_LABELS = {
   user: "User",
   assistant: "Assistant",
@@ -6195,7 +6573,6 @@ var ROLE_LABELS = {
   "tool-result": "Tool Result",
   snapshot: "Snapshot"
 };
-var ROLE_DISPLAY_NAMES = ROLE_LABELS;
 var LABEL_TO_ROLE = {
   User: "user",
   Assistant: "assistant",
@@ -6205,7 +6582,6 @@ var LABEL_TO_ROLE = {
   "Tool Result": "tool-result",
   Snapshot: "snapshot"
 };
-var DISPLAY_NAME_TO_ROLE = LABEL_TO_ROLE;
 function getRoleLabel(role) {
   return ROLE_LABELS[role];
 }
@@ -6288,6 +6664,7 @@ function formatMessageContent(message) {
 `);
 }
 function toMarkdown(conversation, options2 = {}) {
+  assertConversationSafe(conversation);
   const resolved = resolveMarkdownOptions(options2);
   const prepared = prepareConversationForMarkdown(conversation, resolved);
   if (resolved.includeMetadata) {
@@ -6298,7 +6675,7 @@ function toMarkdown(conversation, options2 = {}) {
 function toMarkdownSimple(conversation) {
   const sections = [];
   for (const message of getOrderedMessages(conversation)) {
-    const roleName = ROLE_DISPLAY_NAMES[message.role];
+    const roleName = ROLE_LABELS[message.role];
     const header = `### ${roleName}`;
     const content = formatMessageContent(message);
     sections.push(`${header}
@@ -6349,7 +6726,7 @@ function toMarkdownWithMetadata(conversation, _options) {
   }
   const messageSections = [];
   for (const message of getOrderedMessages(conversation)) {
-    const roleName = ROLE_DISPLAY_NAMES[message.role];
+    const roleName = ROLE_LABELS[message.role];
     const header = `### ${roleName} (${message.id})`;
     const content = formatMessageContent(message);
     messageSections.push(`${header}
@@ -6374,10 +6751,13 @@ function generateId() {
 function fromMarkdown(markdown) {
   const trimmed = markdown.trim();
   const hasFrontmatter = trimmed.startsWith("---");
-  if (hasFrontmatter) {
-    return parseMarkdownWithMetadata(trimmed);
+  const conversation = hasFrontmatter ? parseMarkdownWithMetadata(trimmed) : parseMarkdownSimple(trimmed);
+  try {
+    assertConversationSafe(conversation);
+  } catch (error2) {
+    throw new MarkdownParseError(`Invalid markdown conversation: ${error2 instanceof Error ? error2.message : String(error2)}`);
   }
-  return parseMarkdownSimple(trimmed);
+  return conversation;
 }
 function parseMarkdownWithMetadata(trimmed) {
   let parsed;
@@ -6396,7 +6776,7 @@ function parseMarkdownWithMetadata(trimmed) {
   let match;
   while ((match = messagePattern.exec(body)) !== null) {
     const [, roleDisplay, messageId, contentBody] = match;
-    const role = DISPLAY_NAME_TO_ROLE[roleDisplay];
+    const role = LABEL_TO_ROLE[roleDisplay];
     if (!role) {
       throw new MarkdownParseError(`Unknown role: ${roleDisplay}`);
     }
@@ -6453,7 +6833,7 @@ function parseMarkdownSimple(body) {
   let position = 0;
   while ((match = messagePattern.exec(body)) !== null) {
     const [, roleDisplay, contentBody] = match;
-    const role = DISPLAY_NAME_TO_ROLE[roleDisplay];
+    const role = LABEL_TO_ROLE[roleDisplay];
     if (!role) {
       throw new MarkdownParseError(`Unknown role: ${roleDisplay}`);
     }
@@ -6502,4 +6882,4 @@ export {
   LABEL_TO_ROLE
 };
 
-//# debugId=C64E71F05A5A314564756E2164756E21
+//# debugId=C9F3624DCBE2A76564756E2164756E21