@poncho-ai/harness 0.11.2 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "redis": "^5.10.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "0.6.0"
+    "@poncho-ai/sdk": "1.0.0"
   },
   "devDependencies": {
     "@types/mustache": "^4.2.6",

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/config.ts

@@ -23,6 +23,15 @@ export interface StorageConfig {
   };
 }
 
+export interface UploadsConfig {
+  provider?: "local" | "vercel-blob" | "s3";
+  /** Vercel Blob access mode. Must match the store's configuration. Defaults to "public". */
+  access?: "public" | "private";
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+}
+
 export type BuiltInToolToggles = {
   list_directory?: boolean;
   read_file?: boolean;
@@ -67,6 +76,7 @@ export interface PonchoConfig extends McpConfig {
   /** Extra directories (relative to project root) to scan for skills.
    *  `skills/` and `.poncho/skills/` are always scanned. */
   skillPaths?: string[];
+  uploads?: UploadsConfig;
   build?: {
     vercel?: Record<string, unknown>;
     docker?: Record<string, unknown>;

package/src/harness.ts

@@ -1,13 +1,19 @@
 import { randomUUID } from "node:crypto";
 import type {
   AgentEvent,
+  ContentPart,
+  FileContentPart,
   Message,
   RunInput,
   RunResult,
+  TextContentPart,
   ToolContext,
   ToolDefinition,
 } from "@poncho-ai/sdk";
-import { parseAgentFile, renderAgentPrompt, type ParsedAgent } from "./agent-parser.js";
+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, type AgentFrontmatter } from "./agent-parser.js";
 import { loadPonchoConfig, resolveMemoryConfig, type PonchoConfig } from "./config.js";
 import { createDefaultTools, createWriteTool } from "./default-tools.js";
 import {
@@ -44,6 +50,7 @@ export interface HarnessOptions {
     approvalId: string;
   }) => Promise<boolean> | boolean;
   modelProvider?: ModelProviderFactory;
+  uploadStore?: UploadStore;
 }
 
 export interface HarnessRunOutput {
@@ -229,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.
@@ -257,6 +283,7 @@ export class AgentHarness {
   private readonly modelProviderInjected: boolean;
   private readonly dispatcher = new ToolDispatcher();
   private readonly approvalHandler?: HarnessOptions["approvalHandler"];
+  readonly uploadStore?: UploadStore;
   private skillContextWindow = "";
   private memoryStore?: MemoryStore;
   private loadedConfig?: PonchoConfig;
@@ -329,12 +356,17 @@ export class AgentHarness {
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
     this.approvalHandler = options.approvalHandler;
+    this.uploadStore = options.uploadStore;
 
     if (options.toolDefinitions?.length) {
       this.dispatcher.registerMany(options.toolDefinitions);
     }
   }
 
+  get frontmatter(): AgentFrontmatter | undefined {
+    return this.parsedAgent?.frontmatter;
+  }
+
   private listActiveSkills(): string[] {
     return [...this.activeSkillNames].sort();
   }
@@ -706,6 +738,10 @@ export class AgentHarness {
     const start = now();
     const maxSteps = agent.frontmatter.limits?.maxSteps ?? 50;
     const timeoutMs = (agent.frontmatter.limits?.timeout ?? 300) * 1000;
+    const platformMaxDurationSec = Number(process.env.PONCHO_MAX_DURATION) || 0;
+    const softDeadlineMs = platformMaxDurationSec > 0
+      ? platformMaxDurationSec * 800
+      : 0;
     const messages: Message[] = [...(input.messages ?? [])];
     const events: AgentEvent[] = [];
 
@@ -763,11 +799,42 @@ ${boundedMainMemory.trim()}`
       agentId: agent.frontmatter.id ?? agent.frontmatter.name,
     });
 
-    messages.push({
-      role: "user",
-      content: input.task,
-      metadata: { timestamp: now(), id: randomUUID() },
-    });
+    if (input.files && input.files.length > 0) {
+      const parts: ContentPart[] = [
+        { type: "text", text: input.task } satisfies TextContentPart,
+      ];
+      for (const file of input.files) {
+        if (this.uploadStore) {
+          const buf = Buffer.from(file.data, "base64");
+          const key = deriveUploadKey(buf, file.mediaType);
+          const ref = await this.uploadStore.put(key, buf, file.mediaType);
+          parts.push({
+            type: "file",
+            data: ref,
+            mediaType: file.mediaType,
+            filename: file.filename,
+          } satisfies FileContentPart);
+        } else {
+          parts.push({
+            type: "file",
+            data: file.data,
+            mediaType: file.mediaType,
+            filename: file.filename,
+          } satisfies FileContentPart);
+        }
+      }
+      messages.push({
+        role: "user",
+        content: parts,
+        metadata: { timestamp: now(), id: randomUUID() },
+      });
+    } else {
+      messages.push({
+        role: "user",
+        content: input.task,
+        metadata: { timestamp: now(), id: randomUUID() },
+      });
+    }
 
     let responseText = "";
     let totalInputTokens = 0;
@@ -791,6 +858,19 @@ ${boundedMainMemory.trim()}`
           });
           return;
         }
+        if (softDeadlineMs > 0 && now() - start > softDeadlineMs) {
+          const result: RunResult = {
+            status: "completed",
+            response: responseText,
+            steps: step - 1,
+            tokens: { input: totalInputTokens, output: totalOutputTokens, cached: 0 },
+            duration: now() - start,
+            continuation: true,
+            maxSteps,
+          };
+          yield pushEvent({ type: "run:completed", runId, result });
+          return;
+        }
 
         const stepStart = now();
         yield pushEvent({ type: "step:started", step });
@@ -818,13 +898,13 @@ ${boundedMainMemory.trim()}`
       }
 
         // Convert messages to ModelMessage format
-        const coreMessages: ModelMessage[] = trimMessageWindow(messages).flatMap(
-          (msg): ModelMessage[] => {
+        const convertMessage = async (msg: Message): Promise<ModelMessage[]> => {
           if (msg.role === "tool") {
             // Tool messages are provider-sensitive; skip malformed historical records
             // instead of failing the entire run continuation.
+            const textContent = typeof msg.content === "string" ? msg.content : getTextContent(msg);
             try {
-              const parsed: unknown = JSON.parse(msg.content);
+              const parsed: unknown = JSON.parse(textContent);
               if (!Array.isArray(parsed)) {
                 return [];
               }
@@ -881,12 +961,13 @@ ${boundedMainMemory.trim()}`
           if (msg.role === "assistant") {
             // Assistant messages may contain serialized tool calls from previous runs.
             // Keep only valid tool-call records to avoid broken continuation payloads.
+            const assistantText = typeof msg.content === "string" ? msg.content : getTextContent(msg);
             try {
-              const parsed: unknown = JSON.parse(msg.content);
+              const parsed: unknown = JSON.parse(assistantText);
               if (typeof parsed === "object" && parsed !== null) {
                 const parsedRecord = parsed as { text?: unknown; tool_calls?: unknown };
                 if (!Array.isArray(parsedRecord.tool_calls)) {
-                  return [{ role: "assistant" as const, content: msg.content }];
+                  return [{ role: "assistant" as const, content: assistantText }];
                 }
                 const textPart = typeof parsedRecord.text === "string" ? parsedRecord.text : "";
                 const validToolCalls = parsedRecord.tool_calls
@@ -922,18 +1003,115 @@ ${boundedMainMemory.trim()}`
             } catch {
               // Not JSON, treat as regular assistant text.
             }
-            return [{ role: "assistant" as const, content: msg.content }];
+            return [{ role: "assistant" as const, content: assistantText }];
           }
 
-          if (msg.role === "user" || msg.role === "system") {
+          if (msg.role === "system") {
             return [{
-              role: msg.role,
-              content: msg.content,
+              role: "system" as const,
+              content: typeof msg.content === "string" ? msg.content : getTextContent(msg),
             }];
           }
 
+          if (msg.role === "user") {
+            if (typeof msg.content === "string") {
+              return [{ role: "user" as const, content: msg.content }];
+            }
+            // Convert ContentPart[] to Vercel AI SDK UserContent.
+            // Only specific media types can be sent as binary attachments —
+            // everything else is inlined as text or skipped gracefully.
+            const MODEL_IMAGE_TYPES = new Set([
+              "image/jpeg", "image/png", "image/gif", "image/webp",
+            ]);
+            const MODEL_FILE_TYPES = new Set([
+              "application/pdf",
+            ]);
+            const isTextBasedMime = (mt: string): boolean =>
+              mt.startsWith("text/") ||
+              mt === "application/json" ||
+              mt === "application/xml" ||
+              mt === "application/x-yaml" ||
+              mt.endsWith("+json") ||
+              mt.endsWith("+xml");
+
+            const userContent = await Promise.all(
+              msg.content.map(async (part) => {
+                if (part.type === "text") {
+                  return { type: "text" as const, text: part.text };
+                }
+
+                const isSupportedImage = MODEL_IMAGE_TYPES.has(part.mediaType);
+                const isSupportedFile = MODEL_FILE_TYPES.has(part.mediaType);
+
+                // Text-based files: inline the content so the model can read it
+                if (!isSupportedImage && !isSupportedFile && isTextBasedMime(part.mediaType)) {
+                  let textContent: string;
+                  try {
+                    if (part.data.startsWith(PONCHO_UPLOAD_SCHEME) && this.uploadStore) {
+                      const buf = await this.uploadStore.get(part.data);
+                      textContent = buf.toString("utf8");
+                    } else if (part.data.startsWith("https://") || part.data.startsWith("http://")) {
+                      const resp = await fetch(part.data);
+                      textContent = await resp.text();
+                    } else {
+                      textContent = Buffer.from(part.data, "base64").toString("utf8");
+                    }
+                  } catch {
+                    textContent = "(could not read file)";
+                  }
+                  const label = part.filename ?? part.mediaType;
+                  return { type: "text" as const, text: `[File: ${label}]\n${textContent}` };
+                }
+
+                // Unsupported binary formats (e.g. AVIF, HEIC, MP4): skip with a note
+                if (!isSupportedImage && !isSupportedFile) {
+                  const label = part.filename ?? part.mediaType;
+                  return {
+                    type: "text" as const,
+                    text: `[Attached file: ${label} (${part.mediaType}) — this format is not supported by the model and was skipped]`,
+                  };
+                }
+
+                // Always resolve to base64 so the model doesn't need to
+                // fetch URLs itself (which fails for private blob stores).
+                let resolvedData: string;
+                if (part.data.startsWith(PONCHO_UPLOAD_SCHEME) && this.uploadStore) {
+                  const buf = await this.uploadStore.get(part.data);
+                  resolvedData = buf.toString("base64");
+                } else if (part.data.startsWith("https://") || part.data.startsWith("http://")) {
+                  if (this.uploadStore) {
+                    const buf = await this.uploadStore.get(part.data);
+                    resolvedData = buf.toString("base64");
+                  } else {
+                    const resp = await fetch(part.data);
+                    resolvedData = Buffer.from(await resp.arrayBuffer()).toString("base64");
+                  }
+                } else {
+                  resolvedData = part.data;
+                }
+                if (isSupportedImage) {
+                  return {
+                    type: "image" as const,
+                    image: resolvedData,
+                    mediaType: part.mediaType,
+                  };
+                }
+                return {
+                  type: "file" as const,
+                  data: resolvedData,
+                  mediaType: part.mediaType,
+                  filename: part.filename,
+                };
+              }),
+            );
+            return [{ role: "user" as const, content: userContent }];
+          }
+
           return [];
-        });
+        };
+        const coreMessages: ModelMessage[] = (
+          await Promise.all(trimMessageWindow(messages).map(convertMessage))
+        ).flat();
 
         const modelName = agent.frontmatter.model?.name ?? "claude-opus-4-5";
         const temperature = agent.frontmatter.model?.temperature ?? 0.2;
@@ -1319,14 +1497,27 @@ ${boundedMainMemory.trim()}`
       }
     }
 
-    yield {
-      type: "run:error",
-      runId,
-      error: {
-        code: "MAX_STEPS_EXCEEDED",
-        message: `Run reached maximum of ${maxSteps} steps`,
-      },
-    };
+    if (softDeadlineMs > 0) {
+      const result: RunResult = {
+        status: "completed",
+        response: responseText,
+        steps: maxSteps,
+        tokens: { input: totalInputTokens, output: totalOutputTokens, cached: 0 },
+        duration: now() - start,
+        continuation: true,
+        maxSteps,
+      };
+      yield pushEvent({ type: "run:completed", runId, result });
+    } else {
+      yield pushEvent({
+        type: "run:error",
+        runId,
+        error: {
+          code: "MAX_STEPS_EXCEEDED",
+          message: `Run reached maximum of ${maxSteps} steps`,
+        },
+      });
+    }
   }
 
   async runToCompletion(input: RunInput): Promise<HarnessRunOutput> {

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./schema-converter.js";
 export * from "./skill-context.js";
 export * from "./skill-tools.js";
 export * from "./state.js";
+export * from "./upload-store.js";
 export * from "./telemetry.js";
 export * from "./tool-dispatcher.js";
 export { defineTool } from "@poncho-ai/sdk";