@poncho-ai/harness 0.37.2 → 0.39.0

package/src/orchestrator/subagents.ts

@@ -0,0 +1,27 @@
+import type { AgentHarness } from "../harness.js";
+import type { Conversation } from "../state.js";
+
+// ── Types ──
+
+export type ActiveSubagentRun = {
+  abortController: AbortController;
+  harness: AgentHarness;
+  parentConversationId: string;
+};
+
+export type PendingSubagentApproval = {
+  resolve: (decidedApprovals: NonNullable<Conversation["pendingApprovals"]>) => void;
+  childHarness: AgentHarness;
+  checkpoint: NonNullable<Conversation["pendingApprovals"]>[number];
+  childConversationId: string;
+  parentConversationId: string;
+};
+
+// ── Constants ──
+
+/** root -> L1 -> L2 = 3 levels; L2 cannot spawn further */
+export const MAX_SUBAGENT_NESTING = 3;
+export const MAX_CONCURRENT_SUBAGENTS = 2;
+export const MAX_SUBAGENT_CALLBACK_COUNT = 20;
+export const CALLBACK_LOCK_STALE_MS = 5 * 60 * 1000;
+export const STALE_SUBAGENT_THRESHOLD_MS = 5 * 60 * 1000;

package/src/orchestrator/turn.ts

@@ -0,0 +1,367 @@
+import type { AgentEvent, Message } from "@poncho-ai/sdk";
+import type { Conversation } from "../state.js";
+import type { AgentHarness } from "../harness.js";
+import { isMessageArray } from "./history.js";
+
+// ── Types ──
+
+export type StoredApproval = NonNullable<Conversation["pendingApprovals"]>[number];
+export type PendingToolCall = { id: string; name: string; input: Record<string, unknown> };
+export type ApprovalEventItem = {
+  approvalId: string;
+  tool: string;
+  toolCallId?: string;
+  input: Record<string, unknown>;
+};
+
+export type TurnSection = { type: "text" | "tools"; content: string | string[] };
+
+export type TurnDraftState = {
+  assistantResponse: string;
+  toolTimeline: string[];
+  sections: TurnSection[];
+  currentTools: string[];
+  currentText: string;
+};
+
+export type ExecuteTurnResult = {
+  latestRunId: string;
+  runCancelled: boolean;
+  runContinuation: boolean;
+  runContinuationMessages?: Message[];
+  runHarnessMessages?: Message[];
+  runContextTokens: number;
+  runContextWindow: number;
+  runSteps: number;
+  runMaxSteps?: number;
+  draft: TurnDraftState;
+};
+
+export type TurnResultMetadata = {
+  latestRunId: string;
+  contextTokens: number;
+  contextWindow: number;
+  continuation?: boolean;
+  continuationMessages?: Message[];
+  harnessMessages?: Message[];
+  toolResultArchive?: Conversation["_toolResultArchive"];
+};
+
+// ── Draft helpers ──
+
+export const createTurnDraftState = (): TurnDraftState => ({
+  assistantResponse: "",
+  toolTimeline: [],
+  sections: [],
+  currentTools: [],
+  currentText: "",
+});
+
+export const cloneSections = (sections: TurnSection[]): TurnSection[] =>
+  sections.map((section) => ({
+    type: section.type,
+    content: Array.isArray(section.content) ? [...section.content] : section.content,
+  }));
+
+export const flushTurnDraft = (draft: TurnDraftState): void => {
+  if (draft.currentTools.length > 0) {
+    draft.sections.push({ type: "tools", content: draft.currentTools });
+    draft.currentTools = [];
+  }
+  if (draft.currentText.length > 0) {
+    draft.sections.push({ type: "text", content: draft.currentText });
+    draft.currentText = "";
+  }
+};
+
+// ── Event processing ──
+
+/** Build enriched tool:completed text with input details (bash command, URL, etc.) */
+export const buildToolCompletedText = (event: AgentEvent & { type: "tool:completed" }): string => {
+  const input = event.input as Record<string, unknown> | undefined;
+  const output = event.output as Record<string, unknown> | undefined;
+
+  const meta: string[] = [`${event.duration}ms`];
+  let detail = "";
+
+  if (event.tool === "bash" && input && typeof input.command === "string") {
+    detail = input.command;
+  } else if (event.tool === "web_search") {
+    const q = (input?.query as string) || (output?.query as string) || "";
+    if (q) detail = `"${q.length > 60 ? q.slice(0, 57) + "..." : q}"`;
+  } else if (event.tool === "web_fetch") {
+    const u = (input?.url as string) || (output?.url as string) || "";
+    if (u) detail = u;
+  } else if (event.tool === "spawn_subagent") {
+    if (input && typeof input.task === "string") detail = input.task;
+  } else if (input) {
+    // Generic: pick the first short string value from input
+    for (const [, v] of Object.entries(input)) {
+      if (typeof v === "string" && v.length > 0) {
+        detail = v.length > 80 ? v.slice(0, 77) + "..." : v;
+        break;
+      }
+    }
+  }
+  if (detail) {
+    detail = detail.replace(/\n/g, " ");
+    meta.push(detail);
+  }
+
+  let text = `- done \`${event.tool}\`` + (meta.length > 0 ? ` (${meta.join(", ")})` : "");
+
+  if (event.tool === "spawn_subagent" && output?.subagentId) {
+    text += ` [subagent:${output.subagentId}]`;
+  }
+  if (event.tool === "bash" && typeof output?.exitCode === "number" && output.exitCode !== 0) {
+    text += ` \u2014 exit ${output.exitCode}`;
+  }
+  if (event.tool === "web_search" && Array.isArray(output?.results)) {
+    text += ` \u2014 ${(output.results as unknown[]).length} result${(output.results as unknown[]).length !== 1 ? "s" : ""}`;
+  }
+
+  return text;
+};
+
+export const recordStandardTurnEvent = (draft: TurnDraftState, event: AgentEvent): void => {
+  if (event.type === "model:chunk") {
+    if (draft.currentTools.length > 0) {
+      draft.sections.push({ type: "tools", content: draft.currentTools });
+      draft.currentTools = [];
+      if (draft.assistantResponse.length > 0 && !/\s$/.test(draft.assistantResponse)) {
+        draft.assistantResponse += " ";
+      }
+    }
+    draft.assistantResponse += event.content;
+    draft.currentText += event.content;
+    return;
+  }
+  if (event.type === "tool:started") {
+    if (draft.currentText.length > 0) {
+      draft.sections.push({ type: "text", content: draft.currentText });
+      draft.currentText = "";
+    }
+    const input = event.input as Record<string, unknown> | undefined;
+    let startDetail = "";
+    if (event.tool === "bash" && input && typeof input.command === "string") {
+      startDetail = input.command;
+    } else if (event.tool === "web_fetch" && input && typeof input.url === "string") {
+      startDetail = input.url;
+    } else if (event.tool === "web_search" && input && typeof input.query === "string") {
+      startDetail = `"${input.query}"`;
+    } else if (input) {
+      for (const [, v] of Object.entries(input)) {
+        if (typeof v === "string" && v.length > 0) {
+          startDetail = v.length > 80 ? v.slice(0, 77) + "..." : v;
+          break;
+        }
+      }
+    }
+    if (startDetail) startDetail = startDetail.replace(/\n/g, " ");
+    const toolText = `- start \`${event.tool}\`` + (startDetail ? ` (${startDetail})` : "");
+    draft.toolTimeline.push(toolText);
+    draft.currentTools.push(toolText);
+    return;
+  }
+  if (event.type === "tool:completed") {
+    const toolText = buildToolCompletedText(event);
+    draft.toolTimeline.push(toolText);
+    draft.currentTools.push(toolText);
+    return;
+  }
+  if (event.type === "tool:error") {
+    const toolText = `- error \`${event.tool}\`: ${event.error}`;
+    draft.toolTimeline.push(toolText);
+    draft.currentTools.push(toolText);
+  }
+};
+
+export const buildAssistantMetadata = (
+  draft: TurnDraftState,
+  sectionsOverride?: TurnSection[],
+  opts?: { id?: string; timestamp?: number },
+): Message["metadata"] | undefined => {
+  const sections = sectionsOverride ?? cloneSections(draft.sections);
+  const hasContent = draft.toolTimeline.length > 0 || sections.length > 0;
+  if (!hasContent && !opts?.id) return undefined;
+  const meta: Message["metadata"] = {};
+  if (opts?.id) meta.id = opts.id;
+  if (opts?.timestamp) meta.timestamp = opts.timestamp;
+  if (draft.toolTimeline.length > 0) meta.toolActivity = [...draft.toolTimeline];
+  if (sections.length > 0) meta.sections = sections;
+  return meta;
+};
+
+// ── Turn executor ──
+
+export const executeConversationTurn = async ({
+  harness,
+  runInput,
+  events,
+  initialContextTokens = 0,
+  initialContextWindow = 0,
+  onEvent,
+}: {
+  harness: AgentHarness;
+  runInput?: Parameters<AgentHarness["runWithTelemetry"]>[0];
+  events?: AsyncIterable<AgentEvent>;
+  initialContextTokens?: number;
+  initialContextWindow?: number;
+  onEvent?: (event: AgentEvent, draft: TurnDraftState) => void | Promise<void>;
+}): Promise<ExecuteTurnResult> => {
+  const draft = createTurnDraftState();
+  let latestRunId = "";
+  let runCancelled = false;
+  let runContinuation = false;
+  let runContinuationMessages: Message[] | undefined;
+  let runHarnessMessages: Message[] | undefined;
+  let runContextTokens = initialContextTokens;
+  let runContextWindow = initialContextWindow;
+  let runSteps = 0;
+  let runMaxSteps: number | undefined;
+
+  const source = events ?? harness.runWithTelemetry(runInput!);
+  for await (const event of source) {
+    recordStandardTurnEvent(draft, event);
+    if (event.type === "run:started") {
+      latestRunId = event.runId;
+    }
+    if (event.type === "run:cancelled") {
+      runCancelled = true;
+    }
+    if (event.type === "run:completed") {
+      runContinuation = event.result.continuation === true;
+      runContinuationMessages = event.result.continuationMessages;
+      runHarnessMessages = event.result.continuationMessages;
+      runContextTokens = event.result.contextTokens ?? runContextTokens;
+      runContextWindow = event.result.contextWindow ?? runContextWindow;
+      runSteps = event.result.steps;
+      if (typeof event.result.maxSteps === "number") {
+        runMaxSteps = event.result.maxSteps;
+      }
+      if (draft.assistantResponse.length === 0 && event.result.response) {
+        draft.assistantResponse = event.result.response;
+      }
+    }
+    if (event.type === "run:error") {
+      draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
+    }
+    if (onEvent) {
+      await onEvent(event, draft);
+    }
+  }
+
+  return {
+    latestRunId,
+    runCancelled,
+    runContinuation,
+    runContinuationMessages,
+    runHarnessMessages,
+    runContextTokens,
+    runContextWindow,
+    runSteps,
+    runMaxSteps,
+    draft,
+  };
+};
+
+// ── Approval checkpoint helpers ──
+
+const normalizePendingToolCalls = (value: unknown): PendingToolCall[] => {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((entry): entry is PendingToolCall => {
+      if (!entry || typeof entry !== "object") return false;
+      const row = entry as Record<string, unknown>;
+      return (
+        typeof row.id === "string" &&
+        typeof row.name === "string" &&
+        typeof row.input === "object" &&
+        row.input !== null
+      );
+    })
+    .map((entry) => ({ id: entry.id, name: entry.name, input: entry.input }));
+};
+
+export const normalizeApprovalCheckpoint = (
+  approval: StoredApproval,
+  fallbackMessages: Message[],
+): StoredApproval => ({
+  ...approval,
+  checkpointMessages: isMessageArray(approval.checkpointMessages) ? approval.checkpointMessages : [...fallbackMessages],
+  baseMessageCount: typeof approval.baseMessageCount === "number" && approval.baseMessageCount >= 0
+    ? approval.baseMessageCount
+    : 0,
+  pendingToolCalls: normalizePendingToolCalls(approval.pendingToolCalls),
+});
+
+export const buildApprovalCheckpoints = ({
+  approvals,
+  runId,
+  checkpointMessages,
+  baseMessageCount,
+  pendingToolCalls,
+}: {
+  approvals: ApprovalEventItem[];
+  runId: string;
+  checkpointMessages: Message[];
+  baseMessageCount: number;
+  pendingToolCalls: PendingToolCall[];
+}): NonNullable<Conversation["pendingApprovals"]> =>
+  approvals.map((approval) => ({
+    approvalId: approval.approvalId,
+    runId,
+    tool: approval.tool,
+    toolCallId: approval.toolCallId,
+    input: approval.input,
+    checkpointMessages,
+    baseMessageCount,
+    pendingToolCalls,
+  }));
+
+// ── Turn metadata persistence ──
+
+export const applyTurnMetadata = (
+  conv: Conversation,
+  meta: TurnResultMetadata,
+  opts: {
+    clearContinuation?: boolean;
+    clearApprovals?: boolean;
+    setIdle?: boolean;
+    shouldRebuildCanonical?: boolean;
+  } = {},
+): void => {
+  const {
+    clearContinuation = true,
+    clearApprovals = true,
+    setIdle = true,
+    shouldRebuildCanonical = false,
+  } = opts;
+
+  if (meta.continuation && meta.continuationMessages) {
+    conv._continuationMessages = meta.continuationMessages;
+  } else if (clearContinuation) {
+    conv._continuationMessages = undefined;
+    conv._continuationCount = undefined;
+  }
+
+  if (meta.harnessMessages) {
+    conv._harnessMessages = meta.harnessMessages;
+  } else if (shouldRebuildCanonical) {
+    conv._harnessMessages = conv.messages;
+  }
+
+  if (meta.toolResultArchive !== undefined) {
+    conv._toolResultArchive = meta.toolResultArchive;
+  }
+
+  conv.runtimeRunId = meta.latestRunId || conv.runtimeRunId;
+
+  if (clearApprovals) conv.pendingApprovals = [];
+  if (setIdle) conv.runStatus = "idle";
+
+  if (meta.contextTokens > 0) conv.contextTokens = meta.contextTokens;
+  if (meta.contextWindow > 0) conv.contextWindow = meta.contextWindow;
+
+  conv.updatedAt = Date.now();
+};

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
 // ---------------------------------------------------------------------------