@poncho-ai/harness 0.2.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@poncho-ai/harness",
+  "version": "0.2.0",
+  "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latitude-dev/poncho-ai.git",
+    "directory": "packages/harness"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@aws-sdk/client-dynamodb": "^3.988.0",
+    "@latitude-data/telemetry": "^2.0.2",
+    "jiti": "^2.6.1",
+    "mustache": "^4.2.0",
+    "openai": "^6.3.0",
+    "redis": "^5.10.0",
+    "ws": "^8.18.0",
+    "yaml": "^2.4.0",
+    "@poncho-ai/sdk": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/mustache": "^4.2.6",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.0.0",
+    "vitest": "^1.4.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "harness",
+    "runtime"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest",
+    "lint": "eslint src/"
+  }
+}

package/src/agent-parser.ts

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import Mustache from "mustache";
+import YAML from "yaml";
+
+export interface AgentModelConfig {
+  provider: string;
+  name: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface AgentLimitsConfig {
+  maxSteps?: number;
+  timeout?: number;
+}
+
+export interface AgentFrontmatter {
+  name: string;
+  description?: string;
+  model?: AgentModelConfig;
+  limits?: AgentLimitsConfig;
+}
+
+export interface ParsedAgent {
+  frontmatter: AgentFrontmatter;
+  body: string;
+}
+
+export interface RuntimeRenderContext {
+  parameters?: Record<string, unknown>;
+  runtime?: {
+    workingDir?: string;
+    agentId?: string;
+    runId?: string;
+    environment?: string;
+  };
+}
+
+const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)
+    : {};
+
+const asNumberOrUndefined = (value: unknown): number | undefined =>
+  typeof value === "number" ? value : undefined;
+
+export const parseAgentMarkdown = (content: string): ParsedAgent => {
+  const match = content.match(FRONTMATTER_PATTERN);
+
+  if (!match) {
+    throw new Error(
+      "Invalid AGENT.md: expected YAML frontmatter wrapped in --- markers.",
+    );
+  }
+
+  const parsedYaml = YAML.parse(match[1]) ?? {};
+  const parsed = asRecord(parsedYaml);
+
+  if (typeof parsed.name !== "string" || parsed.name.trim() === "") {
+    throw new Error("Invalid AGENT.md: frontmatter requires a non-empty `name`.");
+  }
+
+  const modelValue = asRecord(parsed.model);
+  const limitsValue = asRecord(parsed.limits);
+
+  const frontmatter: AgentFrontmatter = {
+    name: parsed.name,
+    description:
+      typeof parsed.description === "string" ? parsed.description : undefined,
+    model:
+      Object.keys(modelValue).length > 0
+        ? {
+            provider:
+              typeof modelValue.provider === "string"
+                ? modelValue.provider
+                : "anthropic",
+            name:
+              typeof modelValue.name === "string"
+                ? modelValue.name
+                : "claude-opus-4-5",
+            temperature: asNumberOrUndefined(modelValue.temperature),
+            maxTokens: asNumberOrUndefined(modelValue.maxTokens),
+          }
+        : undefined,
+    limits:
+      Object.keys(limitsValue).length > 0
+        ? {
+            maxSteps: asNumberOrUndefined(limitsValue.maxSteps),
+            timeout: asNumberOrUndefined(limitsValue.timeout),
+          }
+        : undefined,
+  };
+
+  return {
+    frontmatter,
+    body: match[2].trim(),
+  };
+};
+
+export const parseAgentFile = async (workingDir: string): Promise<ParsedAgent> => {
+  const filePath = resolve(workingDir, "AGENT.md");
+  const content = await readFile(filePath, "utf8");
+  return parseAgentMarkdown(content);
+};
+
+export const renderAgentPrompt = (
+  agent: ParsedAgent,
+  context: RuntimeRenderContext = {},
+): string => {
+  const renderContext = {
+    name: agent.frontmatter.name,
+    description: agent.frontmatter.description ?? "",
+    runtime: {
+      workingDir: context.runtime?.workingDir ?? process.cwd(),
+      agentId: context.runtime?.agentId ?? agent.frontmatter.name,
+      runId: context.runtime?.runId ?? `run_${randomUUID()}`,
+      environment: context.runtime?.environment ?? "development",
+    },
+    parameters: context.parameters ?? {},
+  };
+
+  return Mustache.render(agent.body, renderContext).trim();
+};

package/src/anthropic-client.ts

@@ -0,0 +1,134 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";
+import type { Message } from "@poncho-ai/sdk";
+import type {
+  ModelCallInput,
+  ModelClient,
+  ModelClientOptions,
+  ModelResponse,
+  ModelStreamEvent,
+} from "./model-client.js";
+
+const toAnthropicMessages = (messages: Message[]): MessageParam[] =>
+  messages.flatMap((message) => {
+    if (message.role === "system") {
+      return [];
+    }
+    if (message.role === "tool") {
+      return [{ role: "user", content: message.content }];
+    }
+    return [{ role: message.role, content: message.content }];
+  });
+
+export class AnthropicModelClient implements ModelClient {
+  private readonly client: Anthropic;
+  private readonly latitudeCapture;
+
+  constructor(apiKey?: string, options?: ModelClientOptions) {
+    this.client = new Anthropic({
+      apiKey: apiKey ?? process.env.ANTHROPIC_API_KEY,
+    });
+    this.latitudeCapture = options?.latitudeCapture;
+  }
+
+  async *generateStream(input: ModelCallInput): AsyncGenerator<ModelStreamEvent> {
+    let stream;
+    try {
+      stream = await (this.latitudeCapture?.capture(async () =>
+        this.client.messages.stream({
+          model: input.modelName,
+          max_tokens: input.maxTokens ?? 1024,
+          temperature: input.temperature ?? 0.2,
+          system: input.systemPrompt,
+          messages: toAnthropicMessages(input.messages),
+          tools: input.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.inputSchema,
+          })),
+        }),
+      ) ??
+        this.client.messages.stream({
+          model: input.modelName,
+          max_tokens: input.maxTokens ?? 1024,
+          temperature: input.temperature ?? 0.2,
+          system: input.systemPrompt,
+          messages: toAnthropicMessages(input.messages),
+          tools: input.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.inputSchema,
+          })),
+        }));
+    } catch (error) {
+      const maybeStatus = (error as { status?: number }).status;
+      if (maybeStatus === 404) {
+        throw new Error(
+          `Anthropic model not found: ${input.modelName}. Update AGENT.md frontmatter model.name to a valid model (for example: claude-opus-4-5).`,
+        );
+      }
+      throw error;
+    }
+
+    let text = "";
+    for await (const event of stream as AsyncIterable<{
+      type: string;
+      delta?: { type?: string; text?: string };
+    }>) {
+      if (
+        event.type === "content_block_delta" &&
+        event.delta?.type === "text_delta" &&
+        typeof event.delta.text === "string" &&
+        event.delta.text.length > 0
+      ) {
+        text += event.delta.text;
+        yield { type: "chunk", content: event.delta.text };
+      }
+    }
+
+    const response = await (
+      stream as { finalMessage: () => Promise<Anthropic.Messages.Message> }
+    ).finalMessage();
+    const toolCalls: ModelResponse["toolCalls"] = [];
+    for (const block of response.content) {
+      if (block.type === "text") {
+        if (text.length === 0 && block.text) {
+          text = block.text;
+        }
+      }
+      if (block.type === "tool_use") {
+        toolCalls.push({
+          id: block.id,
+          name: block.name,
+          input: (block.input ?? {}) as Record<string, unknown>,
+        });
+      }
+    }
+
+    yield {
+      type: "final",
+      response: {
+        text,
+        toolCalls,
+        usage: {
+          input: response.usage.input_tokens,
+          output: response.usage.output_tokens,
+        },
+        rawContent: response.content as unknown[],
+      },
+    };
+  }
+
+  async generate(input: ModelCallInput): Promise<ModelResponse> {
+    let finalResponse: ModelResponse | undefined;
+    for await (const event of this.generateStream(input)) {
+      if (event.type === "final") {
+        finalResponse = event.response;
+      }
+    }
+    if (!finalResponse) {
+      throw new Error("Anthropic response ended without final payload");
+    }
+    return finalResponse;
+  }
+}

package/src/config.ts

@@ -0,0 +1,141 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { MemoryConfig } from "./memory.js";
+import type { McpConfig } from "./mcp.js";
+import type { StateConfig } from "./state.js";
+
+export interface StorageConfig {
+  provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
+  url?: string;
+  token?: string;
+  table?: string;
+  region?: string;
+  ttl?:
+    | number
+    | {
+        conversations?: number;
+        memory?: number;
+      };
+  memory?: {
+    enabled?: boolean;
+    maxRecallConversations?: number;
+  };
+}
+
+export type BuiltInToolToggles = {
+  list_directory?: boolean;
+  read_file?: boolean;
+  write_file?: boolean;
+};
+
+export interface PonchoConfig extends McpConfig {
+  harness?: string;
+  tools?: {
+    defaults?: BuiltInToolToggles;
+    byEnvironment?: {
+      development?: BuiltInToolToggles;
+      staging?: BuiltInToolToggles;
+      production?: BuiltInToolToggles;
+    };
+  };
+  auth?: {
+    required?: boolean;
+    type?: "bearer" | "header" | "custom";
+    headerName?: string;
+    validate?: (token: string, req?: unknown) => Promise<boolean> | boolean;
+  };
+  state?: {
+    provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
+    ttl?: number;
+    [key: string]: unknown;
+  };
+  memory?: MemoryConfig;
+  storage?: StorageConfig;
+  telemetry?: {
+    enabled?: boolean;
+    otlp?: string;
+    latitude?: {
+      apiKey?: string;
+      projectId?: string | number;
+      path?: string;
+      documentPath?: string;
+    };
+    handler?: (event: unknown) => Promise<void> | void;
+  };
+  skills?: Record<string, Record<string, unknown>>;
+  /** Extra directories (relative to project root) to scan for skills.
+   *  `skills/` and `.poncho/skills/` are always scanned. */
+  skillPaths?: string[];
+  build?: {
+    vercel?: Record<string, unknown>;
+    docker?: Record<string, unknown>;
+    lambda?: Record<string, unknown>;
+    fly?: Record<string, unknown>;
+  };
+}
+
+const resolveTtl = (
+  ttl: StorageConfig["ttl"] | undefined,
+  key: "conversations" | "memory",
+): number | undefined => {
+  if (typeof ttl === "number") {
+    return ttl;
+  }
+  if (ttl && typeof ttl === "object" && typeof ttl[key] === "number") {
+    return ttl[key];
+  }
+  return undefined;
+};
+
+export const resolveStateConfig = (
+  config: PonchoConfig | undefined,
+): StateConfig | undefined => {
+  if (config?.storage) {
+    return {
+      provider: config.storage.provider,
+      url: config.storage.url,
+      token: config.storage.token,
+      table: config.storage.table,
+      region: config.storage.region,
+      ttl: resolveTtl(config.storage.ttl, "conversations"),
+    };
+  }
+  return config?.state as StateConfig | undefined;
+};
+
+export const resolveMemoryConfig = (
+  config: PonchoConfig | undefined,
+): MemoryConfig | undefined => {
+  if (config?.storage) {
+    return {
+      enabled: config.storage.memory?.enabled ?? config.memory?.enabled,
+      provider: config.storage.provider,
+      url: config.storage.url,
+      token: config.storage.token,
+      table: config.storage.table,
+      region: config.storage.region,
+      ttl: resolveTtl(config.storage.ttl, "memory"),
+      maxRecallConversations:
+        config.storage.memory?.maxRecallConversations ??
+        config.memory?.maxRecallConversations,
+    };
+  }
+  return config?.memory;
+};
+
+export const loadPonchoConfig = async (
+  workingDir: string,
+): Promise<PonchoConfig | undefined> => {
+  const filePath = resolve(workingDir, "poncho.config.js");
+  try {
+    await access(filePath);
+  } catch {
+    return undefined;
+  }
+
+  const imported = (await import(`${filePath}?t=${Date.now()}`)) as {
+    default?: PonchoConfig;
+  };
+
+  return imported.default;
+};

package/src/default-tools.ts

@@ -0,0 +1,89 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+
+const resolveSafePath = (workingDir: string, inputPath: string): string => {
+  const base = resolve(workingDir);
+  const target = resolve(base, inputPath);
+  if (target === base || target.startsWith(`${base}${sep}`)) {
+    return target;
+  }
+  throw new Error("Access denied: path must stay inside the working directory.");
+};
+
+export const createDefaultTools = (workingDir: string): ToolDefinition[] => [
+  defineTool({
+    name: "list_directory",
+    description: "List files and folders at a path",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Directory path relative to working directory",
+        },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const path = typeof input.path === "string" ? input.path : ".";
+      const resolved = resolveSafePath(workingDir, path);
+      const entries = await readdir(resolved, { withFileTypes: true });
+      return entries.map((entry) => ({
+        name: entry.name,
+        type: entry.isDirectory() ? "directory" : "file",
+      }));
+    },
+  }),
+  defineTool({
+    name: "read_file",
+    description: "Read UTF-8 text file contents",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "File path relative to working directory",
+        },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const path = typeof input.path === "string" ? input.path : "";
+      const resolved = resolveSafePath(workingDir, path);
+      const content = await readFile(resolved, "utf8");
+      return { path, content };
+    },
+  }),
+];
+
+export const createWriteTool = (workingDir: string): ToolDefinition =>
+  defineTool({
+    name: "write_file",
+    description: "Write UTF-8 text file contents (create or overwrite)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "File path relative to working directory",
+        },
+        content: {
+          type: "string",
+          description: "Text content to write",
+        },
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const path = typeof input.path === "string" ? input.path : "";
+      const content = typeof input.content === "string" ? input.content : "";
+      const resolved = resolveSafePath(workingDir, path);
+      await mkdir(dirname(resolved), { recursive: true });
+      await writeFile(resolved, content, "utf8");
+      return { path, written: true };
+    },
+  });