@poncho-ai/harness 0.31.3 → 0.32.0

package/package.json

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

package/src/config.ts

@@ -134,6 +134,12 @@ export interface PonchoConfig extends McpConfig {
     lambda?: Record<string, unknown>;
     fly?: Record<string, unknown>;
   };
+  /** One-off reminders. When enabled, the agent gets set_reminder / list_reminders / cancel_reminder tools. */
+  reminders?: {
+    enabled?: boolean;
+    /** Cron expression controlling how often the reminder poll runs (local and serverless). Default: every 10 minutes. */
+    pollSchedule?: string;
+  };
   /** Set to `false` to disable the built-in web UI (headless / API-only mode). */
   webUi?: false;
   /** Enable browser automation tools. Set `true` for defaults, or provide config. */

package/src/harness.ts

@@ -24,6 +24,8 @@ import {
   type MemoryStore,
 } from "./memory.js";
 import { createTodoStore, createTodoTools, type TodoItem, type TodoStore } from "./todo-tools.js";
+import { createReminderStore, type ReminderStore } from "./reminder-store.js";
+import { createReminderTools } from "./reminder-tools.js";
 import { LocalMcpBridge } from "./mcp.js";
 import { createModelProvider, getModelContextWindow, type ModelProviderFactory, type ProviderConfig } from "./model-factory.js";
 import { buildSkillContextWindow, loadSkillMetadata } from "./skill-context.js";
@@ -638,6 +640,7 @@ export class AgentHarness {
   private skillContextWindow = "";
   private memoryStore?: MemoryStore;
   private todoStore?: TodoStore;
+  reminderStore?: ReminderStore;
   private loadedConfig?: PonchoConfig;
   private loadedSkills: SkillMetadata[] = [];
   private skillFingerprint = "";
@@ -1332,6 +1335,15 @@ export class AgentHarness {
       }
     }
 
+    if (config?.reminders?.enabled) {
+      this.reminderStore = createReminderStore(agentId, stateConfig, { workingDir: this.workingDir });
+      for (const tool of createReminderTools(this.reminderStore)) {
+        if (this.isToolEnabled(tool.name)) {
+          this.registerIfMissing(tool);
+        }
+      }
+    }
+
     if (config?.browser) {
       await this.initBrowserTools(config)
         .catch((e) => {
@@ -1839,7 +1851,10 @@ ${boundedMainMemory.trim()}`
       const promptWithSkills = this.skillContextWindow
         ? `${agentPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}`
         : `${agentPrompt}${developmentContext}${browserContext}`;
-      return `${promptWithSkills}${memoryContext}
+      const timeContext = this.reminderStore
+        ? `\n\nCurrent UTC time: ${new Date().toISOString()}`
+        : "";
+      return `${promptWithSkills}${memoryContext}${timeContext}
 
 ## Execution Integrity
 

package/src/index.ts

@@ -13,6 +13,8 @@ export * from "./schema-converter.js";
 export * from "./search-tools.js";
 export * from "./skill-context.js";
 export * from "./skill-tools.js";
+export * from "./reminder-store.js";
+export * from "./reminder-tools.js";
 export * from "./state.js";
 export * from "./upload-store.js";
 export * from "./telemetry.js";

package/src/reminder-store.ts

@@ -0,0 +1,334 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import type { StateConfig } from "./state.js";
+import {
+  ensureAgentIdentity,
+  getAgentStoreDirectory,
+  slugifyStorageComponent,
+  STORAGE_SCHEMA_VERSION,
+} from "./agent-identity.js";
+import { createRawKVStore, type RawKVStore } from "./kv-store.js";
+
+// ---------------------------------------------------------------------------
+// Data model
+// ---------------------------------------------------------------------------
+
+export type ReminderStatus = "pending" | "fired" | "cancelled";
+
+export interface Reminder {
+  id: string;
+  task: string;
+  scheduledAt: number;
+  timezone?: string;
+  status: ReminderStatus;
+  createdAt: number;
+  conversationId: string;
+  ownerId?: string;
+}
+
+export interface ReminderStore {
+  list(): Promise<Reminder[]>;
+  create(input: {
+    task: string;
+    scheduledAt: number;
+    timezone?: string;
+    conversationId: string;
+    ownerId?: string;
+  }): Promise<Reminder>;
+  cancel(id: string): Promise<Reminder>;
+  delete(id: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const REMINDERS_FILE = "reminders.json";
+const STALE_CANCELLED_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+const writeJsonAtomic = async (filePath: string, payload: unknown): Promise<void> => {
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  await writeFile(tmpPath, JSON.stringify(payload, null, 2), "utf8");
+  await rename(tmpPath, filePath);
+};
+
+const isValidReminder = (item: unknown): item is Reminder =>
+  typeof item === "object" &&
+  item !== null &&
+  typeof (item as Record<string, unknown>).id === "string" &&
+  typeof (item as Record<string, unknown>).task === "string" &&
+  typeof (item as Record<string, unknown>).scheduledAt === "number" &&
+  typeof (item as Record<string, unknown>).status === "string";
+
+const parseReminderList = (raw: unknown): Reminder[] => {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(isValidReminder);
+};
+
+/** Remove cancelled reminders older than 7 days. Fired reminders are deleted immediately on fire. */
+const pruneStale = (reminders: Reminder[]): Reminder[] => {
+  const cutoff = Date.now() - STALE_CANCELLED_MS;
+  return reminders.filter(
+    (r) => r.status === "pending" || r.createdAt > cutoff,
+  );
+};
+
+const generateId = (): string =>
+  (globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`).slice(0, 8);
+
+// ---------------------------------------------------------------------------
+// InMemoryReminderStore
+// ---------------------------------------------------------------------------
+
+class InMemoryReminderStore implements ReminderStore {
+  private reminders: Reminder[] = [];
+
+  async list(): Promise<Reminder[]> {
+    return [...this.reminders];
+  }
+
+  async create(input: {
+    task: string;
+    scheduledAt: number;
+    timezone?: string;
+    conversationId: string;
+    ownerId?: string;
+  }): Promise<Reminder> {
+    const reminder: Reminder = {
+      id: generateId(),
+      task: input.task,
+      scheduledAt: input.scheduledAt,
+      timezone: input.timezone,
+      status: "pending",
+      createdAt: Date.now(),
+      conversationId: input.conversationId,
+      ownerId: input.ownerId,
+    };
+    this.reminders = pruneStale(this.reminders);
+    this.reminders.push(reminder);
+    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`);
+    if (reminder.status !== "pending") {
+      throw new Error(`Reminder "${id}" is already ${reminder.status}`);
+    }
+    reminder.status = "cancelled";
+    return reminder;
+  }
+
+  async delete(id: string): Promise<void> {
+    this.reminders = this.reminders.filter((r) => r.id !== id);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FileReminderStore — single JSON file for all reminders
+// ---------------------------------------------------------------------------
+
+class FileReminderStore implements ReminderStore {
+  private readonly workingDir: string;
+  private filePath = "";
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  private async ensureFilePath(): Promise<string> {
+    if (this.filePath) return this.filePath;
+    const identity = await ensureAgentIdentity(this.workingDir);
+    this.filePath = resolve(getAgentStoreDirectory(identity), REMINDERS_FILE);
+    return this.filePath;
+  }
+
+  private async readAll(): Promise<Reminder[]> {
+    try {
+      const fp = await this.ensureFilePath();
+      const raw = await readFile(fp, "utf8");
+      return parseReminderList(JSON.parse(raw));
+    } catch {
+      return [];
+    }
+  }
+
+  private async writeAll(reminders: Reminder[]): Promise<void> {
+    const fp = await this.ensureFilePath();
+    await writeJsonAtomic(fp, reminders);
+  }
+
+  async list(): Promise<Reminder[]> {
+    return this.readAll();
+  }
+
+  async create(input: {
+    task: string;
+    scheduledAt: number;
+    timezone?: string;
+    conversationId: string;
+    ownerId?: string;
+  }): Promise<Reminder> {
+    const reminder: Reminder = {
+      id: generateId(),
+      task: input.task,
+      scheduledAt: input.scheduledAt,
+      timezone: input.timezone,
+      status: "pending",
+      createdAt: Date.now(),
+      conversationId: input.conversationId,
+      ownerId: input.ownerId,
+    };
+    let reminders = await this.readAll();
+    reminders = pruneStale(reminders);
+    reminders.push(reminder);
+    await this.writeAll(reminders);
+    return reminder;
+  }
+
+  async cancel(id: string): Promise<Reminder> {
+    const reminders = await this.readAll();
+    const reminder = reminders.find((r) => r.id === id);
+    if (!reminder) throw new Error(`Reminder "${id}" not found`);
+    if (reminder.status !== "pending") {
+      throw new Error(`Reminder "${id}" is already ${reminder.status}`);
+    }
+    reminder.status = "cancelled";
+    await this.writeAll(reminders);
+    return reminder;
+  }
+
+  async delete(id: string): Promise<void> {
+    const reminders = await this.readAll();
+    await this.writeAll(reminders.filter((r) => r.id !== id));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// KVBackedReminderStore — wraps any RawKVStore (Upstash, Redis, DynamoDB)
+// ---------------------------------------------------------------------------
+
+class KVBackedReminderStore implements ReminderStore {
+  private readonly kv: RawKVStore;
+  private readonly key: string;
+  private readonly ttl?: number;
+  private readonly memoryFallback = new InMemoryReminderStore();
+
+  constructor(kv: RawKVStore, key: string, ttl?: number) {
+    this.kv = kv;
+    this.key = key;
+    this.ttl = ttl;
+  }
+
+  private async readAll(): Promise<Reminder[]> {
+    try {
+      const raw = await this.kv.get(this.key);
+      if (!raw) return [];
+      return parseReminderList(JSON.parse(raw));
+    } catch {
+      return this.memoryFallback.list();
+    }
+  }
+
+  private async writeAll(reminders: Reminder[]): Promise<void> {
+    try {
+      const serialized = JSON.stringify(reminders);
+      if (typeof this.ttl === "number") {
+        await this.kv.setWithTtl(this.key, serialized, Math.max(1, this.ttl));
+      } else {
+        await this.kv.set(this.key, serialized);
+      }
+    } catch {
+      // KV write failed; operations already applied in-memory via caller
+    }
+  }
+
+  async list(): Promise<Reminder[]> {
+    return this.readAll();
+  }
+
+  async create(input: {
+    task: string;
+    scheduledAt: number;
+    timezone?: string;
+    conversationId: string;
+    ownerId?: string;
+  }): Promise<Reminder> {
+    let reminders: Reminder[];
+    try {
+      reminders = await this.readAll();
+    } catch {
+      return this.memoryFallback.create(input);
+    }
+    const reminder: Reminder = {
+      id: generateId(),
+      task: input.task,
+      scheduledAt: input.scheduledAt,
+      timezone: input.timezone,
+      status: "pending",
+      createdAt: Date.now(),
+      conversationId: input.conversationId,
+      ownerId: input.ownerId,
+    };
+    reminders = pruneStale(reminders);
+    reminders.push(reminder);
+    await this.writeAll(reminders);
+    return reminder;
+  }
+
+  async cancel(id: string): Promise<Reminder> {
+    let reminders: Reminder[];
+    try {
+      reminders = await this.readAll();
+    } catch {
+      return this.memoryFallback.cancel(id);
+    }
+    const reminder = reminders.find((r) => r.id === id);
+    if (!reminder) throw new Error(`Reminder "${id}" not found`);
+    if (reminder.status !== "pending") {
+      throw new Error(`Reminder "${id}" is already ${reminder.status}`);
+    }
+    reminder.status = "cancelled";
+    await this.writeAll(reminders);
+    return reminder;
+  }
+
+  async delete(id: string): Promise<void> {
+    let reminders: Reminder[];
+    try {
+      reminders = await this.readAll();
+    } catch {
+      return this.memoryFallback.delete(id);
+    }
+    await this.writeAll(reminders.filter((r) => r.id !== id));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export const createReminderStore = (
+  agentId: string,
+  config?: StateConfig,
+  options?: { workingDir?: string },
+): ReminderStore => {
+  const provider = config?.provider ?? "local";
+  const ttl = config?.ttl;
+  const workingDir = options?.workingDir ?? process.cwd();
+
+  if (provider === "local") {
+    return new FileReminderStore(workingDir);
+  }
+  if (provider === "memory") {
+    return new InMemoryReminderStore();
+  }
+
+  const kv = createRawKVStore(config);
+  if (kv) {
+    const key = `poncho:${STORAGE_SCHEMA_VERSION}:${slugifyStorageComponent(agentId)}:reminders`;
+    return new KVBackedReminderStore(kv, key, ttl);
+  }
+  return new InMemoryReminderStore();
+};

package/src/reminder-tools.ts

@@ -0,0 +1,168 @@
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+import type { ReminderStore, ReminderStatus } from "./reminder-store.js";
+
+const VALID_STATUSES: ReminderStatus[] = ["pending", "cancelled"];
+
+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. " +
+      "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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: "What to remind about",
+        },
+        datetime: {
+          type: "string",
+          description:
+            "ISO 8601 datetime for when the reminder should 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.",
+        },
+      },
+      required: ["task", "datetime"],
+      additionalProperties: false,
+    },
+    handler: async (input, context) => {
+      const task = typeof input.task === "string" ? input.task.trim() : "";
+      if (!task) throw new Error("task is required");
+
+      const datetimeStr = typeof input.datetime === "string" ? input.datetime.trim() : "";
+      if (!datetimeStr) throw new Error("datetime is required");
+
+      const timezone = typeof input.timezone === "string" ? input.timezone.trim() : undefined;
+
+      let scheduledAt: number;
+      if (timezone && !datetimeStr.includes("Z") && !/[+-]\d{2}:\d{2}$/.test(datetimeStr)) {
+        try {
+          const formatted = new Intl.DateTimeFormat("en-US", {
+            timeZone: timezone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+          }).format(new Date());
+          void formatted;
+        } catch {
+          throw new Error(`Invalid timezone: "${timezone}"`);
+        }
+        const baseDate = new Date(datetimeStr);
+        if (isNaN(baseDate.getTime())) {
+          throw new Error(`Invalid datetime: "${datetimeStr}"`);
+        }
+        const utcStr = baseDate.toLocaleString("en-US", { timeZone: "UTC" });
+        const tzStr = baseDate.toLocaleString("en-US", { timeZone: timezone });
+        const offsetMs = new Date(utcStr).getTime() - new Date(tzStr).getTime();
+        scheduledAt = baseDate.getTime() + offsetMs;
+      } else {
+        const parsed = new Date(datetimeStr);
+        if (isNaN(parsed.getTime())) {
+          throw new Error(`Invalid datetime: "${datetimeStr}"`);
+        }
+        scheduledAt = parsed.getTime();
+      }
+
+      if (scheduledAt <= Date.now()) {
+        throw new Error("Reminder datetime must be in the future");
+      }
+
+      const conversationId = context.conversationId || context.runId;
+      const reminder = await store.create({
+        task,
+        scheduledAt,
+        timezone,
+        conversationId,
+      });
+
+      return {
+        ok: true,
+        reminder: {
+          id: reminder.id,
+          task: reminder.task,
+          scheduledAt: new Date(reminder.scheduledAt).toISOString(),
+          timezone: reminder.timezone ?? "UTC",
+          status: reminder.status,
+        },
+      };
+    },
+  }),
+
+  defineTool({
+    name: "list_reminders",
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: VALID_STATUSES,
+          description: "Filter by status (omit to list all)",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      let reminders = await store.list();
+      const status = typeof input.status === "string" ? input.status : undefined;
+      if (status && VALID_STATUSES.includes(status as ReminderStatus)) {
+        reminders = reminders.filter((r) => r.status === status);
+      }
+      return {
+        reminders: reminders.map((r) => ({
+          id: r.id,
+          task: r.task,
+          scheduledAt: new Date(r.scheduledAt).toISOString(),
+          timezone: r.timezone ?? "UTC",
+          status: r.status,
+          createdAt: new Date(r.createdAt).toISOString(),
+        })),
+        count: reminders.length,
+      };
+    },
+  }),
+
+  defineTool({
+    name: "cancel_reminder",
+    description: "Cancel a pending reminder by its ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "ID of the reminder to cancel",
+        },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const id = typeof input.id === "string" ? input.id.trim() : "";
+      if (!id) throw new Error("id is required");
+      const cancelled = await store.cancel(id);
+      return {
+        ok: true,
+        reminder: {
+          id: cancelled.id,
+          task: cancelled.task,
+          scheduledAt: new Date(cancelled.scheduledAt).toISOString(),
+          status: cancelled.status,
+        },
+      };
+    },
+  }),
+];