@poncho-ai/cli 0.37.0 → 0.38.1

package/src/cron-helpers.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import {
+  executeConversationTurn,
+  flushTurnDraft,
+  buildAssistantMetadata,
+  TOOL_RESULT_ARCHIVE_PARAM,
+  type AgentHarness,
+  type Conversation,
+  type ConversationStore,
+} from "@poncho-ai/harness";
+import type { AgentEvent, Message } from "@poncho-ai/sdk";
+
+export const normalizeMessageForClient = (message: Message): Message | null => {
+  // Hide tool-role and system-role messages from the web UI — they are
+  // internal harness bookkeeping that leaks into conv.messages when
+  // _harnessMessages are used as canonical history.
+  if (message.role === "tool" || message.role === "system") {
+    return null;
+  }
+  if (message.role !== "assistant" || typeof message.content !== "string") {
+    return message;
+  }
+  try {
+    const parsed = JSON.parse(message.content) as Record<string, unknown>;
+    const toolCalls = Array.isArray(parsed.tool_calls) ? parsed.tool_calls : undefined;
+    if (toolCalls) {
+      const text = typeof parsed.text === "string" ? parsed.text : "";
+      const meta = { ...(message.metadata ?? {}) } as Record<string, unknown>;
+      if (!meta.sections && toolCalls.length > 0) {
+        const toolLabels = toolCalls.map((tc: Record<string, unknown>) => {
+          const name = typeof tc.name === "string" ? tc.name : "tool";
+          return `✓ ${name}`;
+        });
+        const sections: { type: string; content: string | string[] }[] = [];
+        if (toolLabels.length > 0) sections.push({ type: "tools", content: toolLabels });
+        if (text) sections.push({ type: "text", content: text });
+        meta.sections = sections;
+      }
+      return {
+        ...message,
+        content: text,
+        metadata: meta as Message["metadata"],
+      };
+    }
+  } catch {
+    // Keep original assistant content when it's plain text or non-JSON.
+  }
+  return message;
+};
+
+// ── Shared cron helpers ──────────────────────────────────────────
+// Used by both the HTTP /api/cron endpoint and the local-dev scheduler.
+
+export type CronRunResult = {
+  response: string;
+  steps: number;
+  assistantMetadata?: Message["metadata"];
+  hasContent: boolean;
+  contextTokens: number;
+  contextWindow: number;
+  harnessMessages?: Message[];
+  toolResultArchive?: Conversation["_toolResultArchive"];
+  latestRunId: string;
+  continuation: boolean;
+  continuationMessages?: Message[];
+  /** Stable id for the user-turn message persisted by buildCronMessages/appendCronTurn. */
+  userMessageId: string;
+  /** Timestamp shared by user and assistant messages of this turn. */
+  turnTimestamp: number;
+};
+
+export const runCronAgent = async (
+  harnessRef: AgentHarness,
+  task: string,
+  conversationId: string,
+  historyMessages: Message[],
+  toolResultArchive?: Conversation["_toolResultArchive"],
+  onEvent?: (event: AgentEvent) => void | Promise<void>,
+  parameters?: Record<string, unknown>,
+  tenantId?: string | null,
+): Promise<CronRunResult> => {
+  const turnTimestamp = Date.now();
+  const userMessageId = randomUUID();
+  const assistantId = randomUUID();
+  // Callers normally build `parameters` via buildTurnParameters() which
+  // already merges the tool-result archive. The `toolResultArchive` arg is a
+  // fallback for callers that don't (legacy / minimal callers).
+  const finalParameters = {
+    ...(parameters ?? {}),
+    __activeConversationId: conversationId,
+    [TOOL_RESULT_ARCHIVE_PARAM]:
+      parameters?.[TOOL_RESULT_ARCHIVE_PARAM] ?? toolResultArchive ?? {},
+  };
+  const execution = await executeConversationTurn({
+    harness: harnessRef,
+    runInput: {
+      task,
+      conversationId,
+      tenantId: tenantId ?? undefined,
+      parameters: finalParameters,
+      messages: historyMessages,
+    },
+    onEvent,
+  });
+  flushTurnDraft(execution.draft);
+  const hasContent = execution.draft.assistantResponse.length > 0 || execution.draft.toolTimeline.length > 0;
+  const assistantMetadata = buildAssistantMetadata(execution.draft, undefined, {
+    id: assistantId,
+    timestamp: turnTimestamp,
+  });
+  return {
+    response: execution.draft.assistantResponse,
+    steps: execution.runSteps,
+    assistantMetadata,
+    hasContent,
+    contextTokens: execution.runContextTokens,
+    contextWindow: execution.runContextWindow,
+    harnessMessages: execution.runHarnessMessages,
+    toolResultArchive: harnessRef.getToolResultArchive(conversationId),
+    latestRunId: execution.latestRunId,
+    continuation: execution.runContinuation,
+    continuationMessages: execution.runContinuationMessages,
+    userMessageId,
+    turnTimestamp,
+  };
+};
+
+export const buildCronMessages = (
+  task: string,
+  historyMessages: Message[],
+  result: CronRunResult,
+): Message[] => [
+  ...historyMessages,
+  {
+    role: "user" as const,
+    content: task,
+    metadata: { id: result.userMessageId, timestamp: result.turnTimestamp },
+  },
+  ...(result.hasContent
+    ? [{ role: "assistant" as const, content: result.response, metadata: result.assistantMetadata }]
+    : []),
+];
+
+/** Append a cron turn to a freshly-fetched conversation (avoids overwriting concurrent writes). */
+export const appendCronTurn = (conv: Conversation, task: string, result: CronRunResult): void => {
+  conv.messages.push(
+    {
+      role: "user" as const,
+      content: task,
+      metadata: { id: result.userMessageId, timestamp: result.turnTimestamp },
+    },
+    ...(result.hasContent
+      ? [{ role: "assistant" as const, content: result.response, metadata: result.assistantMetadata }]
+      : []),
+  );
+};
+
+export const MAX_PRUNE_PER_RUN = 25;
+
+/** Delete old cron conversations beyond `maxRuns`, capped to avoid API storms on catch-up. */
+export const pruneCronConversations = async (
+  store: ConversationStore,
+  ownerId: string,
+  jobName: string,
+  maxRuns: number,
+): Promise<number> => {
+  const summaries = await store.listSummaries(ownerId);
+  const cronPrefix = `[cron] ${jobName} `;
+  const cronSummaries = summaries
+    .filter((s) => s.title?.startsWith(cronPrefix))
+    .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+
+  if (cronSummaries.length <= maxRuns) return 0;
+
+  const toDelete = cronSummaries.slice(maxRuns, maxRuns + MAX_PRUNE_PER_RUN);
+  let deleted = 0;
+  for (const s of toDelete) {
+    try {
+      if (await store.delete(s.conversationId)) deleted++;
+    } catch { /* best-effort per entry */ }
+  }
+  return deleted;
+};

package/src/http-utils.ts

@@ -0,0 +1,220 @@
+import { readFile } from "node:fs/promises";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import Busboy from "busboy";
+import type { FileInput } from "@poncho-ai/sdk";
+import type { AgentEvent } from "@poncho-ai/sdk";
+
+export const writeJson = (response: ServerResponse, statusCode: number, payload: unknown) => {
+  response.writeHead(statusCode, { "Content-Type": "application/json" });
+  response.end(JSON.stringify(payload));
+};
+
+export const writeHtml = (response: ServerResponse, statusCode: number, payload: string) => {
+  response.writeHead(statusCode, { "Content-Type": "text/html; charset=utf-8" });
+  response.end(payload);
+};
+
+export const EXT_MIME_MAP: Record<string, string> = {
+  jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png",
+  gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+  pdf: "application/pdf", mp4: "video/mp4", webm: "video/webm",
+  mp3: "audio/mpeg", wav: "audio/wav", txt: "text/plain",
+  json: "application/json", csv: "text/csv", html: "text/html",
+};
+export const extToMime = (ext: string): string => EXT_MIME_MAP[ext] ?? "application/octet-stream";
+
+export const readRequestBody = async (request: IncomingMessage): Promise<unknown> => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.from(chunk));
+  }
+  const body = Buffer.concat(chunks).toString("utf8");
+  return body.length > 0 ? (JSON.parse(body) as unknown) : {};
+};
+
+export const parseTelegramMessageThreadIdFromPlatformThreadId = (
+  platformThreadId: string | undefined,
+  chatId: string | undefined,
+): number | undefined => {
+  if (!platformThreadId || !chatId) return undefined;
+  const parts = platformThreadId.split(":");
+  if (parts.length !== 3 || parts[0] !== chatId) return undefined;
+  const threadId = Number(parts[1]);
+  return Number.isInteger(threadId) ? threadId : undefined;
+};
+
+export const MAX_UPLOAD_SIZE = 25 * 1024 * 1024; // 25MB per file
+
+export interface ParsedMultipart {
+  message: string;
+  parameters?: Record<string, unknown>;
+  files: FileInput[];
+}
+
+export const parseMultipartRequest = (request: IncomingMessage): Promise<ParsedMultipart> =>
+  new Promise((resolve, reject) => {
+    const result: ParsedMultipart = { message: "", files: [] };
+    const bb = Busboy({
+      headers: request.headers,
+      limits: { fileSize: MAX_UPLOAD_SIZE },
+    });
+
+    bb.on("field", (name: string, value: string) => {
+      if (name === "message") result.message = value;
+      if (name === "parameters") {
+        try {
+          result.parameters = JSON.parse(value) as Record<string, unknown>;
+        } catch { /* ignore malformed parameters */ }
+      }
+    });
+
+    bb.on("file", (_name: string, stream: NodeJS.ReadableStream, info: { filename: string; mimeType: string }) => {
+      const chunks: Buffer[] = [];
+      stream.on("data", (chunk: Buffer) => chunks.push(chunk));
+      stream.on("end", () => {
+        const buf = Buffer.concat(chunks);
+        result.files.push({
+          data: buf.toString("base64"),
+          mediaType: info.mimeType,
+          filename: info.filename,
+        });
+      });
+    });
+
+    bb.on("finish", () => resolve(result));
+    bb.on("error", (err: Error) => reject(err));
+    request.pipe(bb);
+  });
+
+/**
+ * Detects the runtime environment from platform-specific or standard environment variables.
+ * Priority: PONCHO_ENV > platform detection (Vercel, Railway, etc.) > NODE_ENV > "development"
+ */
+export const resolveHarnessEnvironment = (): "development" | "staging" | "production" => {
+  // Check explicit Poncho environment variable first
+  if (process.env.PONCHO_ENV) {
+    const value = process.env.PONCHO_ENV.toLowerCase();
+    if (value === "production" || value === "staging") {
+      return value;
+    }
+    return "development";
+  }
+
+  // Detect platform-specific environment variables
+  // Vercel
+  if (process.env.VERCEL_ENV) {
+    const vercelEnv = process.env.VERCEL_ENV.toLowerCase();
+    if (vercelEnv === "production") return "production";
+    if (vercelEnv === "preview") return "staging";
+    return "development";
+  }
+
+  // Railway
+  if (process.env.RAILWAY_ENVIRONMENT) {
+    const railwayEnv = process.env.RAILWAY_ENVIRONMENT.toLowerCase();
+    if (railwayEnv === "production") return "production";
+    return "staging";
+  }
+
+  // Render
+  if (process.env.RENDER) {
+    // Render sets IS_PULL_REQUEST for preview deploys
+    if (process.env.IS_PULL_REQUEST === "true") return "staging";
+    return "production";
+  }
+
+  // AWS Lambda
+  if (process.env.AWS_EXECUTION_ENV || process.env.AWS_LAMBDA_FUNCTION_NAME) {
+    return "production";
+  }
+
+  // Fly.io
+  if (process.env.FLY_APP_NAME) {
+    return "production";
+  }
+
+  // Fall back to NODE_ENV
+  if (process.env.NODE_ENV) {
+    const value = process.env.NODE_ENV.toLowerCase();
+    if (value === "production" || value === "staging") {
+      return value;
+    }
+    return "development";
+  }
+
+  // Default to development
+  return "development";
+};
+
+export const listenOnAvailablePort = async (
+  server: Server,
+  preferredPort: number,
+): Promise<number> =>
+  await new Promise<number>((resolveListen, rejectListen) => {
+    let currentPort = preferredPort;
+
+    const tryListen = (): void => {
+      const onListening = (): void => {
+        server.off("error", onError);
+        const address = server.address();
+        if (address && typeof address === "object" && typeof address.port === "number") {
+          resolveListen(address.port);
+          return;
+        }
+        resolveListen(currentPort);
+      };
+
+      const onError = (error: unknown): void => {
+        server.off("listening", onListening);
+        if (
+          typeof error === "object" &&
+          error !== null &&
+          "code" in error &&
+          (error as { code?: string }).code === "EADDRINUSE"
+        ) {
+          currentPort += 1;
+          if (currentPort > 65535) {
+            rejectListen(
+              new Error(
+                "No available ports found from the requested port up to 65535.",
+              ),
+            );
+            return;
+          }
+          setImmediate(tryListen);
+          return;
+        }
+        rejectListen(error);
+      };
+
+      server.once("listening", onListening);
+      server.once("error", onError);
+      server.listen(currentPort);
+    };
+
+    tryListen();
+  });
+
+export const readJsonFile = async <T>(path: string): Promise<T | undefined> => {
+  try {
+    const content = await readFile(path, "utf8");
+    return JSON.parse(content) as T;
+  } catch {
+    return undefined;
+  }
+};
+
+export const parseParams = (values: string[]): Record<string, string> => {
+  const params: Record<string, string> = {};
+  for (const value of values) {
+    const [key, ...rest] = value.split("=");
+    if (!key) {
+      continue;
+    }
+    params[key] = rest.join("=");
+  }
+  return params;
+};
+
+export const formatSseEvent = (event: AgentEvent): string =>
+  `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;