@poncho-ai/harness 0.2.0

package/src/model-client.ts

@@ -0,0 +1,44 @@
+import type { Message, ToolDefinition } from "@poncho-ai/sdk";
+import type { LatitudeCapture } from "./latitude-capture.js";
+
+export interface ModelResponse {
+  text: string;
+  toolCalls: Array<{
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+  }>;
+  usage: {
+    input: number;
+    output: number;
+  };
+  rawContent: unknown[];
+}
+
+export interface ModelCallInput {
+  systemPrompt: string;
+  messages: Message[];
+  tools: ToolDefinition[];
+  modelName: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface ModelClientOptions {
+  latitudeCapture?: LatitudeCapture;
+}
+
+export type ModelStreamEvent =
+  | {
+      type: "chunk";
+      content: string;
+    }
+  | {
+      type: "final";
+      response: ModelResponse;
+    };
+
+export interface ModelClient {
+  generate(input: ModelCallInput): Promise<ModelResponse>;
+  generateStream?(input: ModelCallInput): AsyncGenerator<ModelStreamEvent>;
+}

package/src/model-factory.ts

@@ -0,0 +1,14 @@
+import type { ModelClient, ModelClientOptions } from "./model-client.js";
+import { AnthropicModelClient } from "./anthropic-client.js";
+import { OpenAiModelClient } from "./openai-client.js";
+
+export const createModelClient = (
+  provider?: string,
+  options?: ModelClientOptions,
+): ModelClient => {
+  const normalized = (provider ?? "anthropic").toLowerCase();
+  if (normalized === "openai") {
+    return new OpenAiModelClient(undefined, options);
+  }
+  return new AnthropicModelClient(undefined, options);
+};

package/src/openai-client.ts

@@ -0,0 +1,169 @@
+import OpenAI from "openai";
+import type { Message } from "@poncho-ai/sdk";
+import type {
+  ModelCallInput,
+  ModelClient,
+  ModelClientOptions,
+  ModelResponse,
+  ModelStreamEvent,
+} from "./model-client.js";
+
+type OpenAIMessage = {
+  role: "system" | "user" | "assistant";
+  content: string;
+};
+
+const toOpenAiMessages = (systemPrompt: string, messages: Message[]): OpenAIMessage[] => {
+  const mapped: OpenAIMessage[] = [{ role: "system", content: systemPrompt }];
+  for (const message of messages) {
+    if (message.role === "system") {
+      continue;
+    }
+    if (message.role === "tool") {
+      mapped.push({
+        role: "user",
+        content: `Tool result context: ${message.content}`,
+      });
+      continue;
+    }
+    mapped.push({ role: message.role, content: message.content });
+  }
+  return mapped;
+};
+
+export class OpenAiModelClient implements ModelClient {
+  private readonly client: OpenAI;
+  private readonly latitudeCapture;
+
+  constructor(apiKey?: string, options?: ModelClientOptions) {
+    this.client = new OpenAI({
+      apiKey: apiKey ?? process.env.OPENAI_API_KEY ?? "missing-openai-key",
+    });
+    this.latitudeCapture = options?.latitudeCapture;
+  }
+
+  async *generateStream(input: ModelCallInput): AsyncGenerator<ModelStreamEvent> {
+    const stream = await (this.latitudeCapture?.capture(async () =>
+      this.client.chat.completions.create({
+        model: input.modelName,
+        temperature: input.temperature ?? 0.2,
+        max_tokens: input.maxTokens ?? 1024,
+        messages: toOpenAiMessages(input.systemPrompt, input.messages),
+        tools: input.tools.map((tool) => ({
+          type: "function",
+          function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema as Record<string, unknown>,
+          },
+        })),
+        tool_choice: "auto",
+        stream: true,
+        stream_options: { include_usage: true },
+      }),
+    ) ??
+      this.client.chat.completions.create({
+        model: input.modelName,
+        temperature: input.temperature ?? 0.2,
+        max_tokens: input.maxTokens ?? 1024,
+        messages: toOpenAiMessages(input.systemPrompt, input.messages),
+        tools: input.tools.map((tool) => ({
+          type: "function",
+          function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema as Record<string, unknown>,
+          },
+        })),
+        tool_choice: "auto",
+        stream: true,
+        stream_options: { include_usage: true },
+      }));
+
+    let text = "";
+    let inputTokens = 0;
+    let outputTokens = 0;
+    const toolCallsByIndex = new Map<
+      number,
+      { id: string; name: string; argumentsJson: string }
+    >();
+
+    for await (const chunk of stream) {
+      if (chunk.usage) {
+        inputTokens = chunk.usage.prompt_tokens ?? inputTokens;
+        outputTokens = chunk.usage.completion_tokens ?? outputTokens;
+      }
+
+      const delta = chunk.choices[0]?.delta;
+      if (delta?.content) {
+        text += delta.content;
+        yield { type: "chunk", content: delta.content };
+      }
+
+      for (const toolCall of delta?.tool_calls ?? []) {
+        const index = toolCall.index ?? 0;
+        const current = toolCallsByIndex.get(index) ?? {
+          id: toolCall.id ?? `tool_call_${index}`,
+          name: "",
+          argumentsJson: "",
+        };
+
+        if (toolCall.id) {
+          current.id = toolCall.id;
+        }
+        if (toolCall.function?.name) {
+          current.name = toolCall.function.name;
+        }
+        if (toolCall.function?.arguments) {
+          current.argumentsJson += toolCall.function.arguments;
+        }
+
+        toolCallsByIndex.set(index, current);
+      }
+    }
+
+    const toolCalls: ModelResponse["toolCalls"] = Array.from(toolCallsByIndex.values())
+      .filter((call) => call.name.length > 0)
+      .map((call) => {
+        let parsedInput: Record<string, unknown> = {};
+        if (call.argumentsJson.trim().length > 0) {
+          try {
+            parsedInput = JSON.parse(call.argumentsJson) as Record<string, unknown>;
+          } catch {
+            parsedInput = { raw: call.argumentsJson };
+          }
+        }
+        return {
+          id: call.id,
+          name: call.name,
+          input: parsedInput,
+        };
+      });
+
+    yield {
+      type: "final",
+      response: {
+        text,
+        toolCalls,
+        usage: {
+          input: inputTokens,
+          output: outputTokens,
+        },
+        rawContent: [],
+      },
+    };
+  }
+
+  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("OpenAI response ended without final payload");
+    }
+    return finalResponse;
+  }
+}

package/src/skill-context.ts

@@ -0,0 +1,259 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, resolve, normalize } from "node:path";
+import YAML from "yaml";
+
+// ---------------------------------------------------------------------------
+// Skill directory scanning — default directories and ecosystem compatibility
+// ---------------------------------------------------------------------------
+
+/**
+ * Default directories to scan for skills, relative to the project root.
+ * Additional directories can be added via `skillPaths` in poncho.config.js.
+ */
+const DEFAULT_SKILL_DIRS: string[] = ["skills"];
+
+/**
+ * Resolve the full list of skill directories to scan.
+ * Merges the defaults with any extra paths provided via config.
+ */
+export const resolveSkillDirs = (
+  workingDir: string,
+  extraPaths?: string[],
+): string[] => {
+  const dirs = [...DEFAULT_SKILL_DIRS];
+  if (extraPaths) {
+    for (const p of extraPaths) {
+      if (!dirs.includes(p)) {
+        dirs.push(p);
+      }
+    }
+  }
+  return dirs.map((d) => resolve(workingDir, d));
+};
+
+export interface SkillMetadata {
+  /** Unique skill name from frontmatter. */
+  name: string;
+  /** What the skill does and when to use it. */
+  description: string;
+  /** Tool hints declared in frontmatter (spec `allowed-tools` or legacy `tools`). */
+  tools: string[];
+  /** Absolute path to the skill directory. */
+  skillDir: string;
+  /** Absolute path to the SKILL.md file. */
+  skillPath: string;
+}
+
+/**
+ * @deprecated Use {@link SkillMetadata} instead. Kept for backward compatibility.
+ */
+export type SkillContextEntry = SkillMetadata & {
+  instructions: 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>)
+    : {};
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing (metadata only — no body content)
+// ---------------------------------------------------------------------------
+
+const parseSkillFrontmatter = (
+  content: string,
+): { name: string; description: string; tools: string[] } | undefined => {
+  const match = content.match(FRONTMATTER_PATTERN);
+  if (!match) {
+    return undefined;
+  }
+
+  const parsedYaml = YAML.parse(match[1]) ?? {};
+  const parsed = asRecord(parsedYaml);
+  const name = typeof parsed.name === "string" ? parsed.name.trim() : "";
+  if (!name) {
+    return undefined;
+  }
+
+  const description =
+    typeof parsed.description === "string" ? parsed.description.trim() : "";
+
+  const allowedToolsValue = parsed["allowed-tools"];
+  const allowedTools =
+    typeof allowedToolsValue === "string"
+      ? allowedToolsValue
+          .split(/\s+/)
+          .map((tool) => tool.trim())
+          .filter((tool) => tool.length > 0)
+      : [];
+
+  const legacyToolsValue = parsed.tools;
+  const legacyTools = Array.isArray(legacyToolsValue)
+    ? legacyToolsValue.filter((tool): tool is string => typeof tool === "string")
+    : [];
+
+  const tools = allowedTools.length > 0 ? allowedTools : legacyTools;
+
+  return { name, description, tools };
+};
+
+// ---------------------------------------------------------------------------
+// Discovery — find all SKILL.md files recursively
+// ---------------------------------------------------------------------------
+
+const collectSkillManifests = async (directory: string): Promise<string[]> => {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = resolve(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectSkillManifests(fullPath)));
+      continue;
+    }
+    if (entry.isFile() && entry.name.toLowerCase() === "skill.md") {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+};
+
+// ---------------------------------------------------------------------------
+// Public: load only metadata at startup (name + description per skill)
+// ---------------------------------------------------------------------------
+
+export const loadSkillMetadata = async (
+  workingDir: string,
+  extraSkillPaths?: string[],
+): Promise<SkillMetadata[]> => {
+  const skillDirs = resolveSkillDirs(workingDir, extraSkillPaths);
+  const allManifests: string[] = [];
+
+  for (const dir of skillDirs) {
+    try {
+      allManifests.push(...(await collectSkillManifests(dir)));
+    } catch {
+      // Directory doesn't exist or isn't readable — skip silently.
+    }
+  }
+
+  const skills: SkillMetadata[] = [];
+  const seen = new Set<string>();
+
+  for (const manifest of allManifests) {
+    try {
+      const content = await readFile(manifest, "utf8");
+      const parsed = parseSkillFrontmatter(content);
+      if (parsed && !seen.has(parsed.name)) {
+        seen.add(parsed.name);
+        skills.push({
+          ...parsed,
+          skillDir: dirname(manifest),
+          skillPath: manifest,
+        });
+      }
+    } catch {
+      // Ignore unreadable skill manifests.
+    }
+  }
+  return skills;
+};
+
+// ---------------------------------------------------------------------------
+// Public: build the <available_skills> XML injected into the system prompt
+// ---------------------------------------------------------------------------
+
+export const buildSkillContextWindow = (skills: SkillMetadata[]): string => {
+  if (skills.length === 0) {
+    return "";
+  }
+
+  const xmlSkills = skills
+    .map((skill) => {
+      const lines = [
+        "  <skill>",
+        `    <name>${escapeXml(skill.name)}</name>`,
+      ];
+      if (skill.description) {
+        lines.push(
+          `    <description>${escapeXml(skill.description)}</description>`,
+        );
+      }
+      lines.push("  </skill>");
+      return lines.join("\n");
+    })
+    .join("\n");
+
+  return `<available_skills description="Skills the agent can use. Use the activate_skill tool to load full instructions for a skill when a user's request matches its description.">
+${xmlSkills}
+</available_skills>`;
+};
+
+const escapeXml = (value: string): string =>
+  value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+
+// ---------------------------------------------------------------------------
+// Public: on-demand activation — load the full SKILL.md body
+// ---------------------------------------------------------------------------
+
+export const loadSkillInstructions = async (
+  skill: SkillMetadata,
+): Promise<string> => {
+  const content = await readFile(skill.skillPath, "utf8");
+  const match = content.match(FRONTMATTER_PATTERN);
+  return match ? match[2].trim() : content.trim();
+};
+
+// ---------------------------------------------------------------------------
+// Public: on-demand resource reading from a skill directory
+// ---------------------------------------------------------------------------
+
+export const readSkillResource = async (
+  skill: SkillMetadata,
+  relativePath: string,
+): Promise<string> => {
+  const normalized = normalize(relativePath);
+  if (normalized.startsWith("..") || normalized.startsWith("/")) {
+    throw new Error("Path must be relative and within the skill directory");
+  }
+  const fullPath = resolve(skill.skillDir, normalized);
+  // Ensure the resolved path is still inside the skill directory
+  if (!fullPath.startsWith(skill.skillDir)) {
+    throw new Error("Path escapes the skill directory");
+  }
+  return await readFile(fullPath, "utf8");
+};
+
+// ---------------------------------------------------------------------------
+// Backward-compat: loadSkillContext (returns full entries with instructions)
+// ---------------------------------------------------------------------------
+
+const MAX_INSTRUCTIONS_PER_SKILL = 1200;
+
+export const loadSkillContext = async (
+  workingDir: string,
+): Promise<SkillContextEntry[]> => {
+  const metadata = await loadSkillMetadata(workingDir);
+  const entries: SkillContextEntry[] = [];
+  for (const skill of metadata) {
+    try {
+      const instructions = await loadSkillInstructions(skill);
+      const trimmed =
+        instructions.length > MAX_INSTRUCTIONS_PER_SKILL
+          ? `${instructions.slice(0, MAX_INSTRUCTIONS_PER_SKILL)}...`
+          : instructions;
+      entries.push({ ...skill, instructions: trimmed });
+    } catch {
+      entries.push({ ...skill, instructions: "" });
+    }
+  }
+  return entries;
+};