@poncho-ai/harness 0.37.1 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/harness.ts

@@ -333,6 +333,39 @@ const hasUntruncatedToolResults = (messages: Message[]): boolean => {
   return false;
 };
 
+/**
+ * Finds the last ModelMessage index that's safe to place a prompt cache
+ * breakpoint at — i.e. the last index before any untruncated tool-result.
+ *
+ * Untruncated tool-results from a prior run will be truncated on the next
+ * run, which would invalidate any cache write covering them. Placing the
+ * breakpoint just before them lets us cache only the stable prefix (system
+ * prompt + earlier turns) while still reading it back next turn.
+ *
+ * Returns `messages.length - 1` when there are no untruncated tool-results
+ * (normal tail-of-history caching).
+ */
+const findLastStableCacheIndex = (messages: ModelMessage[]): number => {
+  for (let i = 0; i < messages.length; i += 1) {
+    const msg = messages[i]!;
+    if (msg.role !== "tool") continue;
+    if (!Array.isArray(msg.content)) continue;
+    for (const part of msg.content) {
+      if (!part || typeof part !== "object") continue;
+      const p = part as { type?: string; output?: { type?: string; value?: unknown } };
+      if (p.type !== "tool-result" || !p.output) continue;
+      // JSON outputs bypass truncation (only text content is truncated).
+      if (p.output.type === "json") return i - 1;
+      if (p.output.type === "text" && typeof p.output.value === "string") {
+        if (!p.output.value.startsWith(TOOL_RESULT_TRUNCATED_PREFIX)) {
+          return i - 1;
+        }
+      }
+    }
+  }
+  return messages.length - 1;
+};
+
 const DEVELOPMENT_MODE_CONTEXT = `## Development Mode Context
 
 You are running locally in development mode. Treat this as an editable agent workspace.
@@ -1444,9 +1477,10 @@ export class AgentHarness {
     );
     // Register VFS tools
     this.registerIfMissing(createBashTool(this.bashManager));
-    this.registerIfMissing(createReadFileTool(engine));
-    this.registerIfMissing(createEditFileTool(engine));
-    this.registerIfMissing(createWriteFileTool(engine));
+    const getFs = (tenantId: string) => this.bashManager!.getFs(tenantId);
+    this.registerIfMissing(createReadFileTool(getFs));
+    this.registerIfMissing(createEditFileTool(getFs));
+    this.registerIfMissing(createWriteFileTool(getFs));
 
     // --- Isolate (V8 sandboxed code execution) ---
     if (config?.isolate) {
@@ -1799,16 +1833,15 @@ export class AgentHarness {
       );
     }
     const hasFullToolResults = hasUntruncatedToolResults(messages);
-    const enablePromptCache = !hasFullToolResults;
-    if (!enablePromptCache) {
+    if (hasFullToolResults) {
       console.info(
-        `[poncho][cost] Prompt cache write disabled for run "${runId}" ` +
-        `(untruncated tool results present in history).`,
+        `[poncho][cost] Prompt cache breakpoint will be placed before untruncated ` +
+        `tool results for run "${runId}" (stable prefix only).`,
       );
     } else {
       console.info(
-        `[poncho][cost] Prompt cache write enabled for run "${runId}" ` +
-        `(history has no untruncated tool results).`,
+        `[poncho][cost] Prompt cache breakpoint will be placed at history tail ` +
+        `for run "${runId}" (no untruncated tool results).`,
       );
     }
     const inputMessageCount = messages.length;
@@ -1917,8 +1950,17 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
       const promptWithSkills = this.skillContextWindow
         ? `${agentPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}${fsContext}${isolateContext}`
         : `${agentPrompt}${developmentContext}${browserContext}${fsContext}${isolateContext}`;
+      // Quantize to the hour so the system prompt is stable across runs
+      // within the same hour. Including a per-millisecond timestamp would
+      // invalidate the prompt cache on every run, since the system prompt
+      // is the first block the cache tries to match.
+      const hourlyTime = (() => {
+        const d = new Date();
+        d.setUTCMinutes(0, 0, 0);
+        return d.toISOString();
+      })();
       const timeContext = this.reminderStore
-        ? `\n\nCurrent UTC time: ${new Date().toISOString()}`
+        ? `\n\nCurrent UTC time (hour precision): ${hourlyTime}`
         : "";
       return `${promptWithSkills}${memoryContext}${todoContext}${timeContext}`;
     };
@@ -2452,9 +2494,17 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
 
         const temperature = agent.frontmatter.model?.temperature ?? 0.2;
         const maxTokens = agent.frontmatter.model?.maxTokens;
-        const cachedMessages = enablePromptCache
-          ? addPromptCacheBreakpoints(coreMessages, modelInstance)
-          : coreMessages;
+        // Place the breakpoint before any untruncated tool-result so we
+        // cache only the stable prefix when prior-run tool results are
+        // still full-fidelity. Otherwise cache at the history tail.
+        const breakpointIndex = hasFullToolResults
+          ? findLastStableCacheIndex(coreMessages)
+          : coreMessages.length - 1;
+        const cachedMessages = addPromptCacheBreakpoints(
+          coreMessages,
+          modelInstance,
+          breakpointIndex,
+        );
 
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
 

package/src/prompt-cache.ts

@@ -17,23 +17,32 @@ function isAnthropicModel(model: LanguageModel): boolean {
  * explicit opt-in (Anthropic). For providers with automatic caching
  * (OpenAI), messages are returned unchanged.
  *
- * For Anthropic, marks the last message with ephemeral cache control so the
- * conversation prefix is incrementally cached across steps.
+ * For Anthropic, marks the target message with ephemeral cache control so
+ * the conversation prefix is incrementally cached across steps. When
+ * `targetIndex` is omitted, the last message is used (default behavior).
+ * Callers that want to cache only a stable prefix (e.g. skipping tool
+ * results that will be truncated next turn) can pass an earlier index.
  */
 export function addPromptCacheBreakpoints(
   messages: ModelMessage[],
   model: LanguageModel,
+  targetIndex?: number,
 ): ModelMessage[] {
   if (messages.length === 0 || !isAnthropicModel(model)) {
     return messages;
   }
 
+  const index = targetIndex ?? messages.length - 1;
+  if (index < 0 || index >= messages.length) {
+    return messages;
+  }
+
   const cacheDirective = {
     anthropic: { cacheControl: { type: "ephemeral" as const } },
   };
 
-  return messages.map((message, index) => {
-    if (index === messages.length - 1) {
+  return messages.map((message, i) => {
+    if (i === index) {
       return {
         ...message,
         providerOptions: {

package/src/reminder-store.ts

@@ -6,6 +6,22 @@ import type { StateConfig } from "./state.js";
 
 export type ReminderStatus = "pending" | "fired" | "cancelled";
 
+export type RecurrenceType = "daily" | "weekly" | "monthly" | "cron";
+
+export interface Recurrence {
+  type: RecurrenceType;
+  /** Repeat every N units (e.g. every 2 days). Defaults to 1. */
+  interval?: number;
+  /** For weekly: which days (0=Sun … 6=Sat). */
+  daysOfWeek?: number[];
+  /** For type "cron": a 5-field cron expression. */
+  expression?: string;
+  /** Stop recurring after this epoch-ms timestamp. */
+  endsAt?: number;
+  /** Stop recurring after this many total firings. */
+  maxOccurrences?: number;
+}
+
 export interface Reminder {
   id: string;
   task: string;
@@ -16,18 +32,24 @@ export interface Reminder {
   conversationId: string;
   ownerId?: string;
   tenantId?: string | null;
+  recurrence?: Recurrence | null;
+  occurrenceCount?: number;
+}
+
+export interface ReminderCreateInput {
+  task: string;
+  scheduledAt: number;
+  timezone?: string;
+  conversationId: string;
+  ownerId?: string;
+  tenantId?: string | null;
+  recurrence?: Recurrence | null;
 }
 
 export interface ReminderStore {
   list(): Promise<Reminder[]>;
-  create(input: {
-    task: string;
-    scheduledAt: number;
-    timezone?: string;
-    conversationId: string;
-    ownerId?: string;
-    tenantId?: string | null;
-  }): Promise<Reminder>;
+  create(input: ReminderCreateInput): Promise<Reminder>;
+  update(id: string, fields: { scheduledAt?: number; occurrenceCount?: number; status?: ReminderStatus }): Promise<Reminder>;
   cancel(id: string): Promise<Reminder>;
   delete(id: string): Promise<void>;
 }
@@ -63,14 +85,7 @@ class InMemoryReminderStore implements ReminderStore {
     return [...this.reminders];
   }
 
-  async create(input: {
-    task: string;
-    scheduledAt: number;
-    timezone?: string;
-    conversationId: string;
-    ownerId?: string;
-    tenantId?: string | null;
-  }): Promise<Reminder> {
+  async create(input: ReminderCreateInput): Promise<Reminder> {
     const reminder: Reminder = {
       id: generateId(),
       task: input.task,
@@ -81,12 +96,23 @@ class InMemoryReminderStore implements ReminderStore {
       conversationId: input.conversationId,
       ownerId: input.ownerId,
       tenantId: input.tenantId,
+      recurrence: input.recurrence ?? null,
+      occurrenceCount: 0,
     };
     this.reminders = pruneStale(this.reminders);
     this.reminders.push(reminder);
     return reminder;
   }
 
+  async update(id: string, fields: { scheduledAt?: number; occurrenceCount?: number; status?: ReminderStatus }): Promise<Reminder> {
+    const reminder = this.reminders.find((r) => r.id === id);
+    if (!reminder) throw new Error(`Reminder "${id}" not found`);
+    if (fields.scheduledAt !== undefined) reminder.scheduledAt = fields.scheduledAt;
+    if (fields.occurrenceCount !== undefined) reminder.occurrenceCount = fields.occurrenceCount;
+    if (fields.status !== undefined) reminder.status = fields.status;
+    return reminder;
+  }
+
   async cancel(id: string): Promise<Reminder> {
     const reminder = this.reminders.find((r) => r.id === id);
     if (!reminder) throw new Error(`Reminder "${id}" not found`);
@@ -102,6 +128,147 @@ class InMemoryReminderStore implements ReminderStore {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Recurrence helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a reminder's current scheduledAt and its recurrence config, compute the
+ * next fire time. Returns null if the recurrence is exhausted (maxOccurrences
+ * reached or endsAt passed).
+ */
+export const computeNextOccurrence = (reminder: Reminder): number | null => {
+  const rec = reminder.recurrence;
+  if (!rec) return null;
+
+  const fired = (reminder.occurrenceCount ?? 0) + 1;
+  if (rec.maxOccurrences && fired >= rec.maxOccurrences) return null;
+
+  const interval = rec.interval ?? 1;
+  const prev = reminder.scheduledAt;
+  let next: number;
+
+  switch (rec.type) {
+    case "daily": {
+      next = prev + interval * 24 * 60 * 60 * 1000;
+      break;
+    }
+    case "weekly": {
+      if (rec.daysOfWeek && rec.daysOfWeek.length > 0) {
+        // Advance to next matching day-of-week
+        const d = new Date(prev);
+        const days = [...rec.daysOfWeek].sort((a, b) => a - b);
+        const currentDay = d.getUTCDay();
+        // Find the next day in the list that is strictly after currentDay
+        let nextDay = days.find((day) => day > currentDay);
+        if (nextDay !== undefined) {
+          // Same week
+          const delta = nextDay - currentDay;
+          next = prev + delta * 24 * 60 * 60 * 1000;
+        } else {
+          // Wrap to next week (+ interval weeks if interval > 1)
+          const delta = (7 * interval) - currentDay + days[0];
+          next = prev + delta * 24 * 60 * 60 * 1000;
+        }
+      } else {
+        // No specific days — just advance by N weeks
+        next = prev + interval * 7 * 24 * 60 * 60 * 1000;
+      }
+      break;
+    }
+    case "monthly": {
+      const d = new Date(prev);
+      d.setUTCMonth(d.getUTCMonth() + interval);
+      next = d.getTime();
+      break;
+    }
+    case "cron": {
+      // Minimal cron: parse 5-field expression and find the next matching
+      // minute after `prev`. We support basic values, ranges, steps and *.
+      if (!rec.expression) return null;
+      const parsed = parseCronExpression(rec.expression);
+      if (!parsed) return null;
+      next = nextCronOccurrence(prev, parsed);
+      if (next <= prev) return null; // safety
+      break;
+    }
+    default:
+      return null;
+  }
+
+  if (rec.endsAt && next > rec.endsAt) return null;
+  return next;
+};
+
+// ---------------------------------------------------------------------------
+// Minimal cron parser (5-field: min hour dom month dow)
+// ---------------------------------------------------------------------------
+
+interface CronFields {
+  minutes: Set<number>;
+  hours: Set<number>;
+  daysOfMonth: Set<number>;
+  months: Set<number>;
+  daysOfWeek: Set<number>;
+}
+
+const expandField = (field: string, min: number, max: number): Set<number> | null => {
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const stepMatch = part.match(/^(.+)\/(\d+)$/);
+    const step = stepMatch ? parseInt(stepMatch[2], 10) : 1;
+    const range = stepMatch ? stepMatch[1] : part;
+
+    if (range === "*") {
+      for (let i = min; i <= max; i += step) values.add(i);
+    } else if (range.includes("-")) {
+      const [lo, hi] = range.split("-").map(Number);
+      if (isNaN(lo) || isNaN(hi)) return null;
+      for (let i = lo; i <= hi; i += step) values.add(i);
+    } else {
+      const n = parseInt(range, 10);
+      if (isNaN(n)) return null;
+      values.add(n);
+    }
+  }
+  return values;
+};
+
+const parseCronExpression = (expr: string): CronFields | null => {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return null;
+  const minutes = expandField(parts[0], 0, 59);
+  const hours = expandField(parts[1], 0, 23);
+  const daysOfMonth = expandField(parts[2], 1, 31);
+  const months = expandField(parts[3], 1, 12);
+  const daysOfWeek = expandField(parts[4], 0, 6);
+  if (!minutes || !hours || !daysOfMonth || !months || !daysOfWeek) return null;
+  return { minutes, hours, daysOfMonth, months, daysOfWeek };
+};
+
+const nextCronOccurrence = (afterMs: number, fields: CronFields): number => {
+  // Start from the minute after `afterMs`
+  const d = new Date(afterMs);
+  d.setUTCSeconds(0, 0);
+  d.setUTCMinutes(d.getUTCMinutes() + 1);
+
+  // Cap search to ~1 year to avoid infinite loops
+  const limit = afterMs + 366 * 24 * 60 * 60 * 1000;
+  while (d.getTime() < limit) {
+    if (
+      fields.months.has(d.getUTCMonth() + 1) &&
+      fields.daysOfMonth.has(d.getUTCDate()) &&
+      fields.daysOfWeek.has(d.getUTCDay()) &&
+      fields.hours.has(d.getUTCHours()) &&
+      fields.minutes.has(d.getUTCMinutes())
+    ) {
+      return d.getTime();
+    }
+    d.setUTCMinutes(d.getUTCMinutes() + 1);
+  }
+  return afterMs; // no match within a year — treat as exhausted
+};
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------

package/src/reminder-tools.ts

@@ -1,16 +1,18 @@
 import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
-import type { ReminderStore, ReminderStatus } from "./reminder-store.js";
+import type { ReminderStore, ReminderStatus, Recurrence, RecurrenceType } from "./reminder-store.js";
 
 const VALID_STATUSES: ReminderStatus[] = ["pending", "cancelled"];
+const VALID_RECURRENCE_TYPES: RecurrenceType[] = ["daily", "weekly", "monthly", "cron"];
 
 export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
   defineTool({
     name: "set_reminder",
     description:
-      "Set a one-time reminder that will fire at the specified date and time. " +
+      "Set a reminder that will fire at the specified date and time. " +
       "Use this when the user asks to be reminded about something. " +
       "The datetime must be an ISO 8601 string in the future. " +
-      "When the reminder fires, the task message will be delivered to the user.",
+      "When the reminder fires, the task message will be delivered to the user. " +
+      "Supports optional recurrence for recurring reminders (daily, weekly, monthly, or cron).",
     inputSchema: {
       type: "object",
       properties: {
@@ -21,13 +23,54 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
         datetime: {
           type: "string",
           description:
-            "ISO 8601 datetime for when the reminder should fire (e.g. '2026-03-23T09:00:00Z')",
+            "ISO 8601 datetime for when the reminder should first fire (e.g. '2026-03-23T09:00:00Z')",
         },
         timezone: {
           type: "string",
           description:
             "IANA timezone for interpreting the datetime if it lacks an offset (e.g. 'America/New_York'). Defaults to UTC.",
         },
+        recurrence: {
+          type: "object",
+          description:
+            "Optional. Set this to make the reminder repeat. Omit for a one-time reminder.",
+          properties: {
+            type: {
+              type: "string",
+              enum: VALID_RECURRENCE_TYPES,
+              description:
+                "How often to repeat: 'daily', 'weekly', 'monthly', or 'cron'.",
+            },
+            interval: {
+              type: "number",
+              description:
+                "Repeat every N units (e.g. 2 = every 2 days/weeks/months). Defaults to 1.",
+            },
+            daysOfWeek: {
+              type: "array",
+              items: { type: "number" },
+              description:
+                "For weekly: which days to fire (0=Sunday, 1=Monday, ..., 6=Saturday).",
+            },
+            expression: {
+              type: "string",
+              description:
+                "For type 'cron': a 5-field cron expression (e.g. '0 9 * * 1-5' for weekdays at 9am).",
+            },
+            endsAt: {
+              type: "string",
+              description:
+                "ISO 8601 datetime after which the recurrence should stop.",
+            },
+            maxOccurrences: {
+              type: "number",
+              description:
+                "Maximum number of times the reminder should fire before stopping.",
+            },
+          },
+          required: ["type"],
+          additionalProperties: false,
+        },
       },
       required: ["task", "datetime"],
       additionalProperties: false,
@@ -78,6 +121,50 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
         throw new Error("Reminder datetime must be in the future");
       }
 
+      // Parse recurrence if provided
+      let recurrence: Recurrence | null = null;
+      if (input.recurrence && typeof input.recurrence === "object") {
+        const rec = input.recurrence as Record<string, unknown>;
+        const recType = rec.type as string;
+        if (!VALID_RECURRENCE_TYPES.includes(recType as RecurrenceType)) {
+          throw new Error(`Invalid recurrence type: "${recType}". Must be one of: ${VALID_RECURRENCE_TYPES.join(", ")}`);
+        }
+        recurrence = { type: recType as RecurrenceType };
+        if (rec.interval !== undefined) {
+          const interval = Number(rec.interval);
+          if (!Number.isInteger(interval) || interval < 1) {
+            throw new Error("recurrence.interval must be a positive integer");
+          }
+          recurrence.interval = interval;
+        }
+        if (rec.daysOfWeek !== undefined) {
+          if (!Array.isArray(rec.daysOfWeek)) throw new Error("recurrence.daysOfWeek must be an array");
+          const days = (rec.daysOfWeek as unknown[]).map(Number);
+          if (days.some((d) => !Number.isInteger(d) || d < 0 || d > 6)) {
+            throw new Error("recurrence.daysOfWeek values must be integers 0-6");
+          }
+          recurrence.daysOfWeek = days;
+        }
+        if (rec.expression !== undefined) {
+          if (typeof rec.expression !== "string") throw new Error("recurrence.expression must be a string");
+          recurrence.expression = rec.expression;
+        }
+        if (rec.endsAt !== undefined) {
+          const endsAtDate = new Date(rec.endsAt as string);
+          if (isNaN(endsAtDate.getTime())) {
+            throw new Error(`Invalid recurrence.endsAt: "${rec.endsAt}"`);
+          }
+          recurrence.endsAt = endsAtDate.getTime();
+        }
+        if (rec.maxOccurrences !== undefined) {
+          const max = Number(rec.maxOccurrences);
+          if (!Number.isInteger(max) || max < 1) {
+            throw new Error("recurrence.maxOccurrences must be a positive integer");
+          }
+          recurrence.maxOccurrences = max;
+        }
+      }
+
       const conversationId = context.conversationId || context.runId;
       const reminder = await store.create({
         task,
@@ -85,6 +172,7 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
         timezone,
         conversationId,
         tenantId: context.tenantId,
+        recurrence,
       });
 
       return {
@@ -95,6 +183,8 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
           scheduledAt: new Date(reminder.scheduledAt).toISOString(),
           timezone: reminder.timezone ?? "UTC",
           status: reminder.status,
+          recurrence: reminder.recurrence ?? undefined,
+          occurrenceCount: reminder.occurrenceCount ?? 0,
         },
       };
     },
@@ -105,7 +195,8 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
     description:
       "List reminders for this agent. Returns all reminders by default; " +
       "use the status filter to show only pending or cancelled ones. " +
-      "Fired reminders are automatically deleted after delivery.",
+      "Fired one-time reminders are automatically deleted after delivery. " +
+      "Recurring reminders stay active and show their recurrence config and fire count.",
     inputSchema: {
       type: "object",
       properties: {
@@ -135,6 +226,8 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
           timezone: r.timezone ?? "UTC",
           status: r.status,
           createdAt: new Date(r.createdAt).toISOString(),
+          recurrence: r.recurrence ?? undefined,
+          occurrenceCount: r.occurrenceCount ?? 0,
         })),
         count: reminders.length,
       };
@@ -143,7 +236,10 @@ export const createReminderTools = (store: ReminderStore): ToolDefinition[] => [
 
   defineTool({
     name: "cancel_reminder",
-    description: "Cancel a pending reminder by its ID.",
+    description:
+      "Cancel a pending reminder by its ID. " +
+      "This works for both one-time and recurring reminders — " +
+      "cancelling a recurring reminder stops all future occurrences.",
     inputSchema: {
       type: "object",
       properties: {

package/src/state.ts

@@ -77,11 +77,23 @@ export interface Conversation {
   updatedAt: number;
 }
 
+export interface ConversationCreateInit {
+  parentConversationId?: string;
+  subagentMeta?: Conversation["subagentMeta"];
+  messages?: Message[];
+  channelMeta?: Conversation["channelMeta"];
+}
+
 export interface ConversationStore {
   list(ownerId?: string, tenantId?: string | null): Promise<Conversation[]>;
   listSummaries(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
   get(conversationId: string): Promise<Conversation | undefined>;
-  create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
+  create(
+    ownerId?: string,
+    title?: string,
+    tenantId?: string | null,
+    init?: ConversationCreateInit,
+  ): Promise<Conversation>;
   update(conversation: Conversation): Promise<void>;
   rename(conversationId: string, title: string): Promise<Conversation | undefined>;
   delete(conversationId: string): Promise<boolean>;
@@ -197,16 +209,30 @@ export class InMemoryConversationStore implements ConversationStore {
     return this.conversations.get(conversationId);
   }
 
-  async create(ownerId = DEFAULT_OWNER, title?: string, tenantId: string | null = null): Promise<Conversation> {
+  async create(
+    ownerId = DEFAULT_OWNER,
+    title?: string,
+    tenantId: string | null = null,
+    init?: ConversationCreateInit,
+  ): Promise<Conversation> {
     const now = Date.now();
     const conversation: Conversation = {
       conversationId: globalThis.crypto?.randomUUID?.() ?? `${now}-${Math.random()}`,
       title: normalizeTitle(title),
-      messages: [],
+      messages: init?.messages ?? [],
       ownerId,
       tenantId,
       createdAt: now,
       updatedAt: now,
+      ...(init?.parentConversationId !== undefined
+        ? { parentConversationId: init.parentConversationId }
+        : {}),
+      ...(init?.subagentMeta !== undefined
+        ? { subagentMeta: init.subagentMeta }
+        : {}),
+      ...(init?.channelMeta !== undefined
+        ? { channelMeta: init.channelMeta }
+        : {}),
     };
     this.conversations.set(conversation.conversationId, conversation);
     return conversation;

package/src/storage/engine.ts

@@ -1,11 +1,12 @@
 import type {
   Conversation,
+  ConversationCreateInit,
   ConversationSummary,
   PendingSubagentResult,
 } from "../state.js";
 import type { MainMemory } from "../memory.js";
 import type { TodoItem } from "../todo-tools.js";
-import type { Reminder } from "../reminder-store.js";
+import type { Reminder, ReminderCreateInput, ReminderStatus } from "../reminder-store.js";
 
 // ---------------------------------------------------------------------------
 // VFS types
@@ -40,7 +41,12 @@ export interface StorageEngine {
   conversations: {
     list(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
     get(conversationId: string): Promise<Conversation | undefined>;
-    create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
+    create(
+      ownerId?: string,
+      title?: string,
+      tenantId?: string | null,
+      init?: ConversationCreateInit,
+    ): Promise<Conversation>;
     update(conversation: Conversation): Promise<void>;
     rename(conversationId: string, title: string): Promise<Conversation | undefined>;
     delete(conversationId: string): Promise<boolean>;
@@ -67,14 +73,8 @@ export interface StorageEngine {
   // --- Reminders (replaces ReminderStore) ---
   reminders: {
     list(tenantId?: string | null): Promise<Reminder[]>;
-    create(input: {
-      task: string;
-      scheduledAt: number;
-      timezone?: string;
-      conversationId: string;
-      ownerId?: string;
-      tenantId?: string | null;
-    }): Promise<Reminder>;
+    create(input: ReminderCreateInput): Promise<Reminder>;
+    update(id: string, fields: { scheduledAt?: number; occurrenceCount?: number; status?: ReminderStatus }): Promise<Reminder>;
     cancel(id: string): Promise<Reminder>;
     delete(id: string): Promise<void>;
   };