SKILL.md- the skill, written out in plain English

criteria:
  - name: chat_completion_response_valid
    kind: deterministic
    check: "The output of chatCompletion() must be a valid JSON object matching the expected OpenAI chat completion schema."
  - name: embedding_output_structure
    kind: deterministic
    check: "The output of embed() must be an array of numbers, representing the embedding vector, or an object containing such a vector."
  - name: image_generation_url_present
    kind: deterministic
    check: "The output of generateOpenAIImage() must contain a URL pointing to the generated image."
  - name: api_error_handling
    kind: judge
    check: "The skill should gracefully handle common OpenAI API errors (e.g., rate limits, invalid input, authentication failures) and return informative error messages or codes."

AGENTS.md- what the AI loads when this skill comes up

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-ai-models/api.ts -- Direct OpenAI API for all snappy-* skills.
 *
 * Uses OPENAI_API_KEY from snappy-settings/.env.cache.
 * Direct OpenAI REST API -- chat completions, embeddings, image generation.
 *
 * Usage:
 *   npx tsx api.ts chat "Explain quantum tunneling"
 *   npx tsx api.ts chat "Summarize this" --model gpt-4o
 *   npx tsx api.ts embed "What is Xano?"
 *
 * Or import as module:
 *   import { chatCompletion, embed, generateOpenAIImage } from "./ai-models.ts";
 */

import { env } from "./env.ts";
import { realpathSync } from "fs";

const BASE = "https://api.openai.com/v1";
const DEFAULT_MODEL = "gpt-4o-mini";

interface ChatOptions {
  model?: string;
  systemPrompt?: string;
  temperature?: number;
  maxTokens?: number;
}

interface ImageOptions {
  model?: string;
  size?: string;
}

async function openai(path: string, body: Record<string, unknown>): Promise<unknown> {
  const res = await fetch(`${BASE}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${env("OPENAI_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(`OpenAI failed (${res.status}): ${err}`);
  }
  return res.json();
}

/** Token usage returned by billable OpenAI endpoints (embeddings/responses/chat). */
export interface OpenAiUsage {
  prompt_tokens?: number;
  completion_tokens?: number;
  total_tokens?: number;
  input_tokens?: number;
  output_tokens?: number;
}

/** A typed OpenAI API result carrying the receipt fields the capability engine
 *  needs (request id, model, usage) so a connector run can build an honest
 *  receipt instead of scattering provider data across logs. */
export interface OpenAiApiResult {
  ok: boolean;
  status: number;
  data: unknown;
  /** OpenAI's x-request-id response header - the canonical request id. */
  requestId: string | null;
  /** The model the response reports (when present). */
  model: string | null;
  /** Token usage when the endpoint is billable (embeddings/responses/chat). */
  usage: OpenAiUsage | null;
  /** Safe product-facing error message when ok=false (no key/raw dumps). */
  error?: string;
}

/** The ONE method-aware OpenAI API caller for capability-engine providers.
 *  GET for reads (models/files/batches), POST/DELETE for writes. Never throws -
 *  returns a typed OpenAiApiResult so the provider switch can shape a receipt or
 *  a first-class failure. Reuses OPENAI_API_KEY from .env.cache; the key is never
 *  returned. */
export async function openaiApiRequest(
  method: "GET" | "POST" | "DELETE",
  path: string,
  body?: Record<string, unknown>,
): Promise<OpenAiApiResult> {
  let key = "";
  try {
    key = env("OPENAI_API_KEY");
  } catch {
    return { ok: false, status: 0, data: null, requestId: null, model: null, usage: null, error: "OpenAI is not connected. Add your OpenAI API key to connect it." };
  }
  if (!key) {
    return { ok: false, status: 0, data: null, requestId: null, model: null, usage: null, error: "OpenAI is not connected. Add your OpenAI API key to connect it." };
  }
  const headers: Record<string, string> = { Authorization: `Bearer ${key}` };
  if (method !== "GET" && body !== undefined) headers["Content-Type"] = "application/json";
  let res: Response;
  try {
    res = await fetch(`${BASE}${path.startsWith("/") ? path : `/${path}`}`, {
      method,
      headers,
      body: method !== "GET" && body !== undefined ? JSON.stringify(body) : undefined,
      signal: AbortSignal.timeout(30000),
    });
  } catch (e) {
    return { ok: false, status: 0, data: null, requestId: null, model: null, usage: null, error: `OpenAI request could not be reached: ${e instanceof Error ? e.message : String(e)}` };
  }
  const requestId = res.headers.get("x-request-id");
  const text = await res.text();
  let data: unknown = text;
  try { data = text ? JSON.parse(text) : null; } catch { /* keep raw text */ }
  if (!res.ok) {
    const apiMsg = (data && typeof data === "object" && (data as { error?: { message?: string } }).error?.message) || `OpenAI returned ${res.status}`;
    return { ok: false, status: res.status, data, requestId, model: null, usage: null, error: String(apiMsg) };
  }
  const obj = data && typeof data === "object" ? data as Record<string, unknown> : {};
  const model = typeof obj.model === "string" ? obj.model : null;
  const usage = obj.usage && typeof obj.usage === "object" ? obj.usage as OpenAiUsage : null;
  return { ok: true, status: res.status, data, requestId, model, usage };
}

// --- Public API ---

export async function chatCompletion(prompt: string, opts: ChatOptions = {}): Promise<{ text: string; raw: unknown }> {
  const model = opts.model || DEFAULT_MODEL;
  const messages: { role: string; content: string }[] = [];
  if (opts.systemPrompt) messages.push({ role: "system", content: opts.systemPrompt });
  messages.push({ role: "user", content: prompt });

  const data = await openai("/chat/completions", {
    model,
    messages,
    ...(opts.temperature != null ? { temperature: opts.temperature } : {}),
    ...(opts.maxTokens ? { max_tokens: opts.maxTokens } : {}),
  }) as any;
  const text = data.choices?.[0]?.message?.content || "";
  return { text, raw: data };
}

export async function embed(text: string, model = process.env.SNAPPY_EMBEDDING_MODEL || "text-embedding-3-small"): Promise<{ vector: number[]; raw: unknown }> {
  const data = await openai("/embeddings", {
    model,
    input: text,
  }) as any;
  const vector = data.data?.[0]?.embedding || [];
  return { vector, raw: data };
}

export async function generateOpenAIImage(prompt: string, opts: ImageOptions = {}): Promise<{ url: string; raw: unknown }> {
  const model = opts.model || "gpt-image-1";
  const data = await openai("/images/generations", {
    model,
    prompt,
    size: opts.size || "1024x1024",
    n: 1,
  }) as any;
  const url = data.data?.[0]?.url || data.data?.[0]?.b64_json || "";
  return { url, raw: data };
}

// --- Model catalog (single source of truth for both harnesses) ----------
//
// 2026-05-19: per Robert's two-harness analysis - the picker should mirror
// what the harness can actually do. The catalog lives here so the cockpit,
// the parent dispatch, and RunSubagent all read from one place. Adding a
// model = one entry below + (if it's a new provider routing slug) the
// corresponding ALIASES row in state/lib/dispatch.ts. The cockpit picker
// reads /harness/models which dumps this catalog.
//
// Slug discipline: shortest unambiguous form ("haiku", "sonnet", "opus")
// for the user-facing options; the resolver maps to the wire-protocol
// model id ("claude-haiku-4-5-20251001" etc) used at spawn time.

export type ModelTier = "headline" | "fast" | "deep" | "experimental";

export interface ModelCatalogEntry {
  slug: string;
  label: string;
  modelId: string;
  provider: "anthropic" | "openrouter" | "openai" | "google";
  tier: ModelTier;
  description: string;
  isDefault?: boolean;
}

export const MODEL_CATALOG: ModelCatalogEntry[] = [
  // Anthropic direct (via ANTHROPIC_API_KEY)
  {
    slug: "haiku",
    label: "Claude Haiku 4.5",
    modelId: "claude-haiku-4-5-20251001",
    provider: "anthropic",
    tier: "fast",
    description: "Default. Fast, cheap, good enough for most fan-out work. Use this unless a job genuinely needs more reasoning depth.",
    isDefault: true,
  },
  {
    slug: "sonnet",
    label: "Claude Sonnet 4.6",
    modelId: "claude-sonnet-4-6",
    provider: "anthropic",
    tier: "headline",
    description: "Better at multi-step reasoning, cross-file refactors, and subtle type constraints. Use when haiku produces low-quality output.",
  },
  {
    slug: "opus",
    label: "Claude Opus 4.7",
    modelId: "claude-opus-4-7",
    provider: "anthropic",
    tier: "deep",
    description: "Highest quality, most expensive. Reserve for architectural work and tasks where rerun cost outweighs token cost.",
  },
  // OpenAI (via OpenRouter — wires through the same snappy harness)
  {
    slug: "gpt-5.5",
    label: "GPT-5.5",
    modelId: "openai/gpt-5.5",
    provider: "openrouter",
    tier: "headline",
    description: "OpenAI's flagship via OpenRouter. Strong at structured reasoning and tool use. Routes through OPENROUTER_API_KEY.",
  },
  {
    slug: "gpt-5.4",
    label: "GPT-5.4",
    modelId: "openai/gpt-5.4",
    provider: "openrouter",
    tier: "headline",
    description: "Previous OpenAI flagship via OpenRouter. Sometimes cheaper than 5.5 with similar quality on shorter prompts.",
  },
  {
    slug: "gpt-4.1",
    label: "GPT-4.1",
    modelId: "openai/gpt-4.1",
    provider: "openrouter",
    tier: "fast",
    description: "OpenAI mid-tier. Good cost/quality balance for moderate complexity work.",
  },
  {
    slug: "gpt-4.1-mini",
    label: "GPT-4.1 mini",
    modelId: "openai/gpt-4.1-mini",
    provider: "openrouter",
    tier: "fast",
    description: "OpenAI cheap tier. Use when GPT-quality reasoning is needed but the budget is tight.",
  },
  {
    slug: "o4-mini",
    label: "o4-mini",
    modelId: "openai/o4-mini",
    provider: "openrouter",
    tier: "deep",
    description: "OpenAI reasoning model. Excellent for math, code, and multi-step logical tasks. Slower than chat models.",
  },
  // Google (via OpenRouter)
  {
    slug: "gemini-flash",
    label: "Gemini 2.5 Flash",
    modelId: "google/gemini-2.5-flash",
    provider: "openrouter",
    tier: "fast",
    description: "Google's fast tier. Huge context window, low cost. Good for long-context work where Claude's window is tight.",
  },
  {
    slug: "gemini-pro",
    label: "Gemini 2.5 Pro",
    modelId: "google/gemini-2.5-pro",
    provider: "openrouter",
    tier: "headline",
    description: "Google's flagship. Strong at long-context reasoning, structured output, and multimodal work.",
  },
  // Open-weight (via OpenRouter)
  {
    slug: "llama",
    label: "Llama 3.3 70B",
    modelId: "meta-llama/llama-3.3-70b-instruct",
    provider: "openrouter",
    tier: "headline",
    description: "Meta's open-weight flagship. Strong instruction following at competitive cost. Use when you want non-frontier coverage.",
  },
  {
    slug: "qwen",
    label: "Qwen 2.5 72B",
    modelId: "qwen/qwen-2.5-72b-instruct",
    provider: "openrouter",
    tier: "headline",
    description: "Alibaba's open-weight model. Especially strong at structured output and bilingual work.",
  },
  {
    slug: "deepseek",
    label: "DeepSeek Chat",
    modelId: "deepseek/deepseek-chat",
    provider: "openrouter",
    tier: "headline",
    description: "DeepSeek's open-weight model. Strong code generation; very cheap per token.",
  },
];

/**
 * The catalog entry for a given slug, or undefined if the slug is unknown.
 * Both harnesses use this to validate operator picks before passing the slug
 * downstream.
 */
export function getModelCatalogEntry(slug: string): ModelCatalogEntry | undefined {
  return MODEL_CATALOG.find((e) => e.slug === slug);
}

/**
 * Resolve a user-facing slug ("haiku" | "sonnet" | "opus" | ...) to the
 * wire-protocol model id the spawned binary accepts via --model. Falls back
 * to the default catalog entry when the slug is unknown.
 */
export function resolveModelSlug(slug: string): string {
  const entry = getModelCatalogEntry(slug);
  if (entry) return entry.modelId;
  const defaultEntry = MODEL_CATALOG.find((e) => e.isDefault) ?? MODEL_CATALOG[0];
  return defaultEntry.modelId;
}

/**
 * True iff the slug exists in the catalog. Used by HTTP endpoints + the
 * operator-settings validator.
 */
export function isKnownModelSlug(slug: unknown): slug is string {
  return typeof slug === "string" && MODEL_CATALOG.some((e) => e.slug === slug);
}

/**
 * The default slug, used when no operator override is set. Sourced from
 * the catalog so changing the default = flipping one isDefault flag.
 */
export function defaultModelSlug(): string {
  const entry = MODEL_CATALOG.find((e) => e.isDefault) ?? MODEL_CATALOG[0];
  return entry.slug;
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "chat": {
        const prompt = args.filter(a => !a.startsWith("--")).join(" ");
        const modelIdx = args.indexOf("--model");
        const model = modelIdx >= 0 ? args[modelIdx + 1] : undefined;
        if (!prompt) { console.error("Usage: api.ts chat <prompt> [--model <model>]"); process.exit(1); }
        const { text } = await chatCompletion(prompt, { model });
        console.log(text);
        break;
      }
      case "embed": {
        const text = args.join(" ");
        if (!text) { console.error("Usage: api.ts embed <text>"); process.exit(1); }
        const { vector } = await embed(text);
        console.log(`Dimensions: ${vector.length}`);
        console.log(JSON.stringify(vector.slice(0, 5)) + "...");
        break;
      }
      case "image": {
        const prompt = args.filter(a => !a.startsWith("--")).join(" ");
        const sizeIdx = args.indexOf("--size");
        const size = sizeIdx >= 0 ? args[sizeIdx + 1] : undefined;
        if (!prompt) { console.error("Usage: api.ts image <prompt> [--size <WxH>]"); process.exit(1); }
        const { url } = await generateOpenAIImage(prompt, { size });
        console.log(url);
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [chat|embed|image] ...");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet