@poncho-ai/harness 0.12.0 → 0.13.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.12.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.13.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 158.98 KB
-ESM ⚡️ Build success in 59ms
+ESM dist/index.js 161.82 KB
+ESM ⚡️ Build success in 68ms
 DTS Build start
-DTS ⚡️ Build success in 4596ms
-DTS dist/index.d.ts 19.34 KB
+DTS ⚡️ Build success in 4388ms
+DTS dist/index.d.ts 19.54 KB

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @poncho-ai/harness
 
+## 0.13.0
+
+### Minor Changes
+
+- [#8](https://github.com/cesr/poncho-ai/pull/8) [`658bc54`](https://github.com/cesr/poncho-ai/commit/658bc54d391cb0b58aa678a2b86cd617eebdd8aa) Thanks [@cesr](https://github.com/cesr)! - Add cron job support for scheduled agent tasks. Define recurring jobs in AGENT.md frontmatter with schedule, task, and optional timezone. Includes in-process scheduler for local dev with hot-reload, HTTP endpoint for Vercel/serverless with self-continuation, Vercel scaffold generation with drift detection, and full tool activity tracking in cron conversations.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -13,6 +13,11 @@ interface AgentLimitsConfig {
     maxSteps?: number;
     timeout?: number;
 }
+interface CronJobConfig {
+    schedule: string;
+    task: string;
+    timezone?: string;
+}
 interface AgentFrontmatter {
     name: string;
     id?: string;
@@ -27,6 +32,7 @@ interface AgentFrontmatter {
         mcp?: string[];
         scripts?: string[];
     };
+    cron?: Record<string, CronJobConfig>;
 }
 interface ParsedAgent {
     frontmatter: AgentFrontmatter;
@@ -374,6 +380,7 @@ declare class AgentHarness {
     private registerConfiguredBuiltInTools;
     private shouldEnableWriteTool;
     constructor(options?: HarnessOptions);
+    get frontmatter(): AgentFrontmatter | undefined;
     private listActiveSkills;
     private getAgentMcpIntent;
     private getAgentScriptIntent;
@@ -547,4 +554,4 @@ declare class ToolDispatcher {
     executeBatch(calls: ToolCall[], context: ToolContext): Promise<ToolExecutionResult[]>;
 }
 
-export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type Conversation, type ConversationState, type ConversationStore, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type ModelProviderFactory, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PonchoConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type TelemetryConfig, TelemetryEmitter, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, createConversationStore, createDefaultTools, createMemoryStore, createMemoryTools, createModelProvider, createSkillTools, createStateStore, createUploadStore, createWriteTool, deriveUploadKey, ensureAgentIdentity, generateAgentId, getAgentStoreDirectory, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent };
+export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type Conversation, type ConversationState, type ConversationStore, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type ModelProviderFactory, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PonchoConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type TelemetryConfig, TelemetryEmitter, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, createConversationStore, createDefaultTools, createMemoryStore, createMemoryTools, createModelProvider, createSkillTools, createStateStore, createUploadStore, createWriteTool, deriveUploadKey, ensureAgentIdentity, generateAgentId, getAgentStoreDirectory, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent };

package/dist/index.js

@@ -67,6 +67,59 @@ var matchesSlashPattern = (value, pattern) => {
 var FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
 var asRecord = (value) => typeof value === "object" && value !== null ? value : {};
 var asNumberOrUndefined = (value) => typeof value === "number" ? value : void 0;
+var CRON_EXPRESSION_PATTERN = /^(\S+\s+){4}\S+$/;
+var validateCronExpression = (expr, path) => {
+  if (!CRON_EXPRESSION_PATTERN.test(expr.trim())) {
+    throw new Error(
+      `Invalid cron expression at ${path}: "${expr}". Expected 5-field cron format (minute hour day month weekday).`
+    );
+  }
+};
+var KNOWN_TIMEZONES = (() => {
+  try {
+    return new Set(Intl.supportedValuesOf("timeZone"));
+  } catch {
+    return null;
+  }
+})();
+var validateTimezone = (tz, path) => {
+  if (KNOWN_TIMEZONES && !KNOWN_TIMEZONES.has(tz)) {
+    throw new Error(
+      `Invalid timezone at ${path}: "${tz}". Expected an IANA timezone string (e.g. "America/New_York", "UTC").`
+    );
+  }
+};
+var parseCronJobs = (value) => {
+  const raw = asRecord(value);
+  const keys = Object.keys(raw);
+  if (keys.length === 0) return void 0;
+  const jobs = {};
+  for (const jobName of keys) {
+    const jobValue = asRecord(raw[jobName]);
+    const path = `AGENT.md frontmatter cron.${jobName}`;
+    if (typeof jobValue.schedule !== "string" || jobValue.schedule.trim() === "") {
+      throw new Error(
+        `Invalid ${path}: "schedule" is required and must be a non-empty string.`
+      );
+    }
+    if (typeof jobValue.task !== "string" || jobValue.task.trim() === "") {
+      throw new Error(
+        `Invalid ${path}: "task" is required and must be a non-empty string.`
+      );
+    }
+    validateCronExpression(jobValue.schedule, path);
+    const timezone = typeof jobValue.timezone === "string" && jobValue.timezone.trim() ? jobValue.timezone.trim() : void 0;
+    if (timezone) {
+      validateTimezone(timezone, path);
+    }
+    jobs[jobName] = {
+      schedule: jobValue.schedule.trim(),
+      task: jobValue.task,
+      timezone
+    };
+  }
+  return jobs;
+};
 var parseAgentMarkdown = (content) => {
   const match = content.match(FRONTMATTER_PATTERN);
   if (!match) {
@@ -144,7 +197,8 @@ var parseAgentMarkdown = (content) => {
     approvalRequired: approvalRequired.mcp.length > 0 || approvalRequired.scripts.length > 0 ? {
       mcp: approvalRequired.mcp.length > 0 ? approvalRequired.mcp : void 0,
       scripts: approvalRequired.scripts.length > 0 ? approvalRequired.scripts : void 0
-    } : void 0
+    } : void 0,
+    cron: parseCronJobs(parsed.cron)
   };
   return {
     frontmatter,
@@ -2559,6 +2613,25 @@ You can extend your own capabilities by creating custom JavaScript/TypeScript sc
   - Script entries outside \`./scripts/\` must also appear in \`allowed-tools\`.
 - Keep MCP server connection details (\`url\`, auth env vars) in \`poncho.config.js\` only.
 
+## Cron Jobs
+
+Users can define scheduled tasks in \`AGENT.md\` frontmatter:
+
+\`\`\`yaml
+cron:
+  daily-report:
+    schedule: "0 9 * * *"        # Standard 5-field cron expression
+    timezone: "America/New_York" # Optional IANA timezone (default: UTC)
+    task: "Generate the daily sales report"
+\`\`\`
+
+- Each cron job triggers an autonomous agent run with the specified task, creating a fresh conversation.
+- In \`poncho dev\`, jobs run via an in-process scheduler and appear in the web UI sidebar (prefixed with \`[cron]\`).
+- For Vercel: \`poncho build vercel\` generates \`vercel.json\` cron entries. Set \`CRON_SECRET\` = \`PONCHO_AUTH_TOKEN\`.
+- Jobs can also be triggered manually: \`GET /api/cron/<jobName>\`.
+- To carry context across cron runs, enable memory.
+- **IMPORTANT**: When adding a new cron job, always PRESERVE all existing cron jobs. Never remove or overwrite existing jobs unless the user explicitly asks you to replace or delete them. Read the full current \`cron:\` block before editing, and append the new job alongside the existing ones.
+
 ## When users ask about customization:
 
 - Explain and edit \`poncho.config.js\` for model/provider, storage+memory, auth, telemetry, and MCP settings.
@@ -2654,6 +2727,9 @@ var AgentHarness = class {
       this.dispatcher.registerMany(options.toolDefinitions);
     }
   }
+  get frontmatter() {
+    return this.parsedAgent?.frontmatter;
+  }
   listActiveSkills() {
     return [...this.activeSkillNames].sort();
   }

package/package.json

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

package/src/agent-parser.ts

@@ -22,6 +22,12 @@ export interface AgentLimitsConfig {
   timeout?: number;
 }
 
+export interface CronJobConfig {
+  schedule: string;
+  task: string;
+  timezone?: string;
+}
+
 export interface AgentFrontmatter {
   name: string;
   id?: string;
@@ -36,6 +42,7 @@ export interface AgentFrontmatter {
     mcp?: string[];
     scripts?: string[];
   };
+  cron?: Record<string, CronJobConfig>;
 }
 
 export interface ParsedAgent {
@@ -63,6 +70,74 @@ const asRecord = (value: unknown): Record<string, unknown> =>
 const asNumberOrUndefined = (value: unknown): number | undefined =>
   typeof value === "number" ? value : undefined;
 
+const CRON_EXPRESSION_PATTERN = /^(\S+\s+){4}\S+$/;
+
+const validateCronExpression = (expr: string, path: string): void => {
+  if (!CRON_EXPRESSION_PATTERN.test(expr.trim())) {
+    throw new Error(
+      `Invalid cron expression at ${path}: "${expr}". Expected 5-field cron format (minute hour day month weekday).`,
+    );
+  }
+};
+
+const KNOWN_TIMEZONES: Set<string> | null = (() => {
+  try {
+    return new Set(Intl.supportedValuesOf("timeZone"));
+  } catch {
+    return null;
+  }
+})();
+
+const validateTimezone = (tz: string, path: string): void => {
+  if (KNOWN_TIMEZONES && !KNOWN_TIMEZONES.has(tz)) {
+    throw new Error(
+      `Invalid timezone at ${path}: "${tz}". Expected an IANA timezone string (e.g. "America/New_York", "UTC").`,
+    );
+  }
+};
+
+const parseCronJobs = (
+  value: unknown,
+): Record<string, CronJobConfig> | undefined => {
+  const raw = asRecord(value);
+  const keys = Object.keys(raw);
+  if (keys.length === 0) return undefined;
+
+  const jobs: Record<string, CronJobConfig> = {};
+  for (const jobName of keys) {
+    const jobValue = asRecord(raw[jobName]);
+    const path = `AGENT.md frontmatter cron.${jobName}`;
+
+    if (typeof jobValue.schedule !== "string" || jobValue.schedule.trim() === "") {
+      throw new Error(
+        `Invalid ${path}: "schedule" is required and must be a non-empty string.`,
+      );
+    }
+    if (typeof jobValue.task !== "string" || jobValue.task.trim() === "") {
+      throw new Error(
+        `Invalid ${path}: "task" is required and must be a non-empty string.`,
+      );
+    }
+
+    validateCronExpression(jobValue.schedule, path);
+
+    const timezone =
+      typeof jobValue.timezone === "string" && jobValue.timezone.trim()
+        ? jobValue.timezone.trim()
+        : undefined;
+    if (timezone) {
+      validateTimezone(timezone, path);
+    }
+
+    jobs[jobName] = {
+      schedule: jobValue.schedule.trim(),
+      task: jobValue.task,
+      timezone,
+    };
+  }
+  return jobs;
+};
+
 export const parseAgentMarkdown = (content: string): ParsedAgent => {
   const match = content.match(FRONTMATTER_PATTERN);
 
@@ -175,6 +250,7 @@ export const parseAgentMarkdown = (content: string): ParsedAgent => {
                 : undefined,
           }
         : undefined,
+    cron: parseCronJobs(parsed.cron),
   };
 
   return {

package/src/harness.ts

@@ -13,7 +13,7 @@ import type {
 import { getTextContent } from "@poncho-ai/sdk";
 import type { UploadStore } from "./upload-store.js";
 import { PONCHO_UPLOAD_SCHEME, deriveUploadKey } from "./upload-store.js";
-import { parseAgentFile, renderAgentPrompt, type ParsedAgent } from "./agent-parser.js";
+import { parseAgentFile, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
 import { loadPonchoConfig, resolveMemoryConfig, type PonchoConfig } from "./config.js";
 import { createDefaultTools, createWriteTool } from "./default-tools.js";
 import {
@@ -236,6 +236,25 @@ You can extend your own capabilities by creating custom JavaScript/TypeScript sc
   - Script entries outside \`./scripts/\` must also appear in \`allowed-tools\`.
 - Keep MCP server connection details (\`url\`, auth env vars) in \`poncho.config.js\` only.
 
+## Cron Jobs
+
+Users can define scheduled tasks in \`AGENT.md\` frontmatter:
+
+\`\`\`yaml
+cron:
+  daily-report:
+    schedule: "0 9 * * *"        # Standard 5-field cron expression
+    timezone: "America/New_York" # Optional IANA timezone (default: UTC)
+    task: "Generate the daily sales report"
+\`\`\`
+
+- Each cron job triggers an autonomous agent run with the specified task, creating a fresh conversation.
+- In \`poncho dev\`, jobs run via an in-process scheduler and appear in the web UI sidebar (prefixed with \`[cron]\`).
+- For Vercel: \`poncho build vercel\` generates \`vercel.json\` cron entries. Set \`CRON_SECRET\` = \`PONCHO_AUTH_TOKEN\`.
+- Jobs can also be triggered manually: \`GET /api/cron/<jobName>\`.
+- To carry context across cron runs, enable memory.
+- **IMPORTANT**: When adding a new cron job, always PRESERVE all existing cron jobs. Never remove or overwrite existing jobs unless the user explicitly asks you to replace or delete them. Read the full current \`cron:\` block before editing, and append the new job alongside the existing ones.
+
 ## When users ask about customization:
 
 - Explain and edit \`poncho.config.js\` for model/provider, storage+memory, auth, telemetry, and MCP settings.
@@ -344,6 +363,10 @@ export class AgentHarness {
     }
   }
 
+  get frontmatter(): AgentFrontmatter | undefined {
+    return this.parsedAgent?.frontmatter;
+  }
+
   private listActiveSkills(): string[] {
     return [...this.activeSkillNames].sort();
   }

package/test/agent-parser.test.ts

@@ -37,6 +37,124 @@ Env: {{runtime.environment}}
     expect(prompt).toContain("Env: development");
   });
 
+  describe("cron jobs", () => {
+    it("parses cron jobs from frontmatter", () => {
+      const parsed = parseAgentMarkdown(`---
+name: test-agent
+cron:
+  daily-report:
+    schedule: "0 9 * * *"
+    task: "Generate the daily report"
+  health-check:
+    schedule: "*/30 * * * *"
+    timezone: "America/New_York"
+    task: "Check all APIs"
+---
+
+# Agent
+`);
+      expect(parsed.frontmatter.cron).toBeDefined();
+      expect(Object.keys(parsed.frontmatter.cron!)).toEqual([
+        "daily-report",
+        "health-check",
+      ]);
+      expect(parsed.frontmatter.cron!["daily-report"]).toEqual({
+        schedule: "0 9 * * *",
+        task: "Generate the daily report",
+        timezone: undefined,
+      });
+      expect(parsed.frontmatter.cron!["health-check"]).toEqual({
+        schedule: "*/30 * * * *",
+        task: "Check all APIs",
+        timezone: "America/New_York",
+      });
+    });
+
+    it("returns undefined cron when not defined", () => {
+      const parsed = parseAgentMarkdown(`---
+name: test-agent
+---
+
+# Agent
+`);
+      expect(parsed.frontmatter.cron).toBeUndefined();
+    });
+
+    it("throws on missing schedule", () => {
+      expect(() =>
+        parseAgentMarkdown(`---
+name: test-agent
+cron:
+  bad-job:
+    task: "Do something"
+---
+
+# Agent
+`),
+      ).toThrow(/"schedule" is required/);
+    });
+
+    it("throws on missing task", () => {
+      expect(() =>
+        parseAgentMarkdown(`---
+name: test-agent
+cron:
+  bad-job:
+    schedule: "0 9 * * *"
+---
+
+# Agent
+`),
+      ).toThrow(/"task" is required/);
+    });
+
+    it("throws on invalid cron expression", () => {
+      expect(() =>
+        parseAgentMarkdown(`---
+name: test-agent
+cron:
+  bad-job:
+    schedule: "every day"
+    task: "Do something"
+---
+
+# Agent
+`),
+      ).toThrow(/Invalid cron expression/);
+    });
+
+    it("throws on invalid timezone", () => {
+      expect(() =>
+        parseAgentMarkdown(`---
+name: test-agent
+cron:
+  bad-job:
+    schedule: "0 9 * * *"
+    timezone: "Fake/Zone"
+    task: "Do something"
+---
+
+# Agent
+`),
+      ).toThrow(/Invalid timezone/);
+    });
+
+    it("accepts valid timezone", () => {
+      const parsed = parseAgentMarkdown(`---
+name: test-agent
+cron:
+  job:
+    schedule: "0 9 * * *"
+    timezone: "Europe/London"
+    task: "Do something"
+---
+
+# Agent
+`);
+      expect(parsed.frontmatter.cron!["job"]!.timezone).toBe("Europe/London");
+    });
+  });
+
   it("parses approval-required with relative script paths", () => {
     const parsed = parseAgentMarkdown(`---
 name: test-agent