framework-agents 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,1209 @@
+#!/usr/bin/env node
+import {
+  Agent,
+  AgentError,
+  LocalFileStorage,
+  SessionManager,
+  filesystemMiddleware,
+  hasImages,
+  imagesOf,
+  todoListMiddleware,
+  wireTextOf
+} from "./chunk-LUGUQQLR.js";
+
+// src/serve/cli.ts
+import { resolve as resolve3 } from "path";
+
+// src/serve/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { config as dotenvConfig } from "dotenv";
+import { z as z4 } from "zod";
+
+// src/config/index.ts
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { config } from "dotenv";
+import { z } from "zod";
+function loadEnv() {
+  if (process.env.FRAMEWORK_ENV_PATH) {
+    config({ path: process.env.FRAMEWORK_ENV_PATH });
+    return;
+  }
+  config();
+  let dir = resolve(process.cwd());
+  for (let i = 0; i < 3; i++) {
+    dir = dirname(dir);
+    const candidate = join(dir, ".env");
+    if (existsSync(candidate)) {
+      config({ path: candidate });
+      return;
+    }
+  }
+}
+loadEnv();
+var ConfigSchema = z.object({
+  TOGETHER_API_KEY: z.string().default(""),
+  TOGETHER_BASE_URL: z.string().default("https://api.together.xyz/v1"),
+  /** Small chat default — one model, no tiers. */
+  TOGETHER_MODEL: z.string().default("Qwen/Qwen3.5-9B"),
+  OPENAI_BASE_URL: z.string().default("https://api.openai.com/v1"),
+  OPENAI_API_KEY: z.string().default(""),
+  OPENAI_MODEL: z.string().default("gpt-4o-mini"),
+  ANTHROPIC_API_KEY: z.string().default(""),
+  ANTHROPIC_BASE_URL: z.string().default("https://api.anthropic.com"),
+  ANTHROPIC_MODEL: z.string().default("claude-sonnet-4-6"),
+  OLLAMA_BASE_URL: z.string().default("http://localhost:11434/v1"),
+  OLLAMA_MODEL: z.string().default("qwen2.5"),
+  E2E_MODEL: z.string().default("")
+});
+var cached;
+function loadConfig(env = process.env) {
+  if (cached) return cached;
+  const parsed = ConfigSchema.parse({
+    TOGETHER_API_KEY: env.TOGETHER_API_KEY ?? "",
+    TOGETHER_BASE_URL: env.TOGETHER_BASE_URL,
+    TOGETHER_MODEL: env.TOGETHER_MODEL,
+    OPENAI_BASE_URL: env.OPENAI_BASE_URL,
+    OPENAI_API_KEY: env.OPENAI_API_KEY ?? "",
+    OPENAI_MODEL: env.OPENAI_MODEL,
+    ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY ?? "",
+    ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL,
+    ANTHROPIC_MODEL: env.ANTHROPIC_MODEL,
+    OLLAMA_BASE_URL: env.OLLAMA_BASE_URL,
+    OLLAMA_MODEL: env.OLLAMA_MODEL,
+    E2E_MODEL: env.E2E_MODEL ?? ""
+  });
+  const useTogether = parsed.TOGETHER_API_KEY.length > 0;
+  const model = useTogether ? parsed.TOGETHER_MODEL : parsed.OPENAI_MODEL;
+  cached = {
+    ...parsed,
+    active: useTogether ? { baseUrl: parsed.TOGETHER_BASE_URL, apiKey: parsed.TOGETHER_API_KEY, model, source: "together" } : { baseUrl: parsed.OPENAI_BASE_URL, apiKey: parsed.OPENAI_API_KEY, model, source: "openai" }
+  };
+  return cached;
+}
+
+// src/models/capabilities.ts
+var VISION_CAPABLE_PATTERNS = [
+  /qwen2.*vl/i,
+  /qwen.*vl/i,
+  /llama-3\.2-11b-vision/i,
+  /llama-3\.2-90b-vision/i,
+  /llava/i,
+  /minicpm-v/i,
+  /gpt-4o/i,
+  /gpt-4\.1/i,
+  /claude.*sonnet/i,
+  /claude.*opus/i,
+  /gemini/i
+];
+function supportsVision(modelId) {
+  return VISION_CAPABLE_PATTERNS.some((re) => re.test(modelId));
+}
+function assertCanHandle(modelId, needsVision) {
+  if (needsVision && !supportsVision(modelId)) {
+    throw new AgentError(
+      "MODEL_CAPABILITY",
+      `Model "${modelId}" cannot take image input. Switch TOGETHER_MODEL to a vision-capable model (e.g. Qwen/Qwen2.5-VL-72B-Instruct) or drop the images.`,
+      false
+    );
+  }
+}
+
+// src/models/openai-compatible.ts
+function reasoningOf(usage) {
+  return usage.reasoning_tokens ?? usage.completion_tokens_details?.reasoning_tokens;
+}
+function thinkingOf(m) {
+  const trace = m.reasoning ?? m.reasoning_content;
+  return trace ? trace : void 0;
+}
+function toWireRole(role) {
+  if (role === "tool") return "tool";
+  return role;
+}
+function toWireContent(m) {
+  if (typeof m.content === "string" && !hasImages(m.content)) return m.content;
+  const text = wireTextOf(m.content);
+  const imgs = imagesOf(m.content);
+  if (!imgs.length) return text;
+  return [
+    ...text ? [{ type: "text", text }] : [],
+    ...imgs.map((img) => ({
+      type: "image_url",
+      image_url: { url: img.data ? `data:${img.mimeType ?? "image/jpeg"};base64,${img.data}` : img.url }
+    }))
+  ];
+}
+function toWireMessage(m) {
+  const base = { role: toWireRole(m.role), content: toWireContent(m) };
+  if (m.toolCallId) base.tool_call_id = m.toolCallId;
+  if (typeof m.content !== "string") {
+    const calls = m.content.filter(
+      (b) => b.type === "tool_call"
+    );
+    if (calls.length) {
+      base.tool_calls = calls.map((c) => ({
+        id: c.id,
+        type: "function",
+        function: { name: c.name, arguments: JSON.stringify(c.args ?? {}) }
+      }));
+    }
+  }
+  return base;
+}
+var OpenAICompatibleProvider = class {
+  id;
+  capabilities = { structuredOutput: true, streaming: true };
+  opts;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("OpenAICompatibleProvider: apiKey is required (.env TOGETHER_API_KEY / OPENAI_API_KEY)");
+    this.opts = { temperature: 0.2, ...opts };
+    this.id = `openai-compatible:${opts.model}`;
+  }
+  async complete(options) {
+    const { fetchFn = fetch, baseUrl, apiKey, model, temperature, maxTokens, stream } = this.opts;
+    const needsVision = options.messages.some((m) => hasImages(m.content));
+    assertCanHandle(model, needsVision);
+    const url = `${baseUrl.replace(/\/$/, "")}/chat/completions`;
+    const body = {
+      model,
+      temperature,
+      ...maxTokens ? { max_tokens: maxTokens } : {},
+      // stream_options makes OpenAI-compatible servers attach usage to the final
+      // chunk; without it streaming runs report {0,0} — budgets/cost would be fiction.
+      ...stream ? { stream: true, stream_options: { include_usage: true } } : {},
+      ...options.responseFormat ? {
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            name: options.responseFormat.name,
+            strict: options.responseFormat.strict ?? true,
+            schema: options.responseFormat.schema
+          }
+        }
+      } : {},
+      messages: options.messages.map(toWireMessage),
+      ...options.tools.length ? {
+        tools: options.tools.map((t) => ({
+          type: "function",
+          function: {
+            name: t.name,
+            description: t.description,
+            // Without parameters the API advertises a zero-arg tool.
+            ...t.parametersSchema ? { parameters: t.parametersSchema } : {}
+          }
+        }))
+      } : {}
+    };
+    let res;
+    try {
+      res = await fetchFn(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify(body),
+        ...options.signal ? { signal: options.signal } : {}
+      });
+    } catch (err) {
+      throw new AgentError("MODEL_ERROR", `Model request failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      const retryable = res.status === 429 || res.status >= 500;
+      throw new AgentError("MODEL_ERROR", `Model HTTP ${res.status}: ${text.slice(0, 300)}`, retryable);
+    }
+    return stream ? this.readStream(res, options) : this.readJson(res, options);
+  }
+  async readJson(res, options) {
+    const json = await res.json();
+    const choice = json.choices[0];
+    const msg = choice?.message ?? {};
+    const thinking = thinkingOf(msg);
+    if (thinking) options.onThinking?.(thinking);
+    if (msg.content) options.onToken?.(msg.content);
+    const finishReason = choice?.finish_reason ?? void 0;
+    if (!msg.content && !(msg.tool_calls ?? []).length && thinking && finishReason === "stop") {
+      throw new AgentError(
+        "MODEL_ERROR",
+        "Model stopped with finish_reason=stop having put the entire answer in the reasoning channel (empty content, no tool calls, thinking present). The reasoning/content split lost the reply \u2014 retry or raise maxTokens.",
+        true
+      );
+    }
+    if (!msg.content && !(msg.tool_calls ?? []).length && finishReason === "length") {
+      throw new AgentError(
+        "MODEL_ERROR",
+        `Model spent its entire max_tokens budget (${json.usage?.completion_tokens ?? "?"} tokens, finish_reason=length) thinking without producing content. Raise maxTokens.`,
+        false
+      );
+    }
+    const reasoningTokens = json.usage ? reasoningOf(json.usage) : void 0;
+    return {
+      text: msg.content ?? "",
+      ...thinking ? { thinking } : {},
+      toolCalls: parseToolCalls(msg.tool_calls ?? []),
+      ...finishReason ? { finishReason } : {},
+      usage: {
+        inputTokens: json.usage?.prompt_tokens ?? 0,
+        outputTokens: json.usage?.completion_tokens ?? 0,
+        ...reasoningTokens != null ? { reasoningTokens } : {}
+      }
+    };
+  }
+  /** SSE: `data: {...}` lines; delta.content -> onToken, delta.reasoning_content -> onThinking. */
+  async readStream(res, options) {
+    if (!res.body) throw new Error("Streaming response has no body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let thinking = "";
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let reasoningTokens;
+    let finishReason;
+    const toolArgBuffers = /* @__PURE__ */ new Map();
+    let buffer = "";
+    const flush = (chunk) => {
+      buffer += chunk;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const t = line.trim();
+        if (!t.startsWith("data:")) continue;
+        const payload = t.slice(5).trim();
+        if (payload === "[DONE]") continue;
+        let evt;
+        try {
+          evt = JSON.parse(payload);
+        } catch {
+          continue;
+        }
+        if (evt.choices?.[0]?.finish_reason) finishReason = evt.choices[0].finish_reason ?? void 0;
+        if (evt.usage) {
+          if (evt.usage.prompt_tokens != null) inputTokens = evt.usage.prompt_tokens;
+          if (evt.usage.completion_tokens != null) outputTokens = evt.usage.completion_tokens;
+          const rt = reasoningOf(evt.usage);
+          if (rt != null) reasoningTokens = rt;
+          continue;
+        }
+        const delta = evt.choices?.[0]?.delta;
+        if (!delta) continue;
+        const think = thinkingOf(delta);
+        if (think) {
+          thinking += think;
+          options.onThinking?.(think);
+        }
+        if (delta.content) {
+          text += delta.content;
+          options.onToken?.(delta.content);
+        }
+        for (const [i, tc] of (delta.tool_calls ?? []).entries()) {
+          const key = tc.index ?? i;
+          const slot = toolArgBuffers.get(key) ?? { id: "", name: "", args: "" };
+          if (tc.id) slot.id = tc.id;
+          if (tc.function?.name) slot.name = tc.function.name;
+          if (tc.function?.arguments) slot.args += tc.function.arguments;
+          toolArgBuffers.set(key, slot);
+        }
+      }
+    };
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      flush(decoder.decode(value, { stream: true }));
+    }
+    flush(decoder.decode());
+    if (!text && !toolArgBuffers.size && thinking && finishReason === "stop") {
+      throw new AgentError(
+        "MODEL_ERROR",
+        "Stream ended at finish_reason=stop having put the entire answer in the reasoning channel (no content, no tool calls, thinking present). The reasoning/content split lost the reply \u2014 retry or raise maxTokens.",
+        true
+      );
+    }
+    if (!text && !toolArgBuffers.size && finishReason === "length") {
+      throw new AgentError(
+        "MODEL_ERROR",
+        `Stream ended at finish_reason=length with no content (${outputTokens} tokens burned). Raise maxTokens.`,
+        false
+      );
+    }
+    return {
+      text,
+      ...thinking ? { thinking } : {},
+      ...finishReason ? { finishReason } : {},
+      toolCalls: [...toolArgBuffers.values()].filter((t) => t.name).map((t) => ({ id: t.id || `call_${++callSeq}`, name: t.name, args: safeJson(t.args) })),
+      usage: {
+        inputTokens,
+        outputTokens,
+        ...reasoningTokens != null ? { reasoningTokens } : {}
+      }
+    };
+  }
+};
+var callSeq = 0;
+function parseToolCalls(calls) {
+  return calls.map((c) => ({ id: c.id ?? `call_${++callSeq}`, name: c.function.name, args: safeJson(c.function.arguments || "{}") }));
+}
+function safeJson(raw) {
+  try {
+    return JSON.parse(raw || "{}");
+  } catch {
+    return {};
+  }
+}
+
+// src/models/anthropic.ts
+function normalizeStopReason(stopReason) {
+  if (!stopReason) return void 0;
+  return stopReason === "max_tokens" ? "length" : stopReason;
+}
+function assertNotEmptyTruncation(text, toolCalls, finishReason, tokenCount) {
+  if (!text && !toolCalls.length && finishReason === "length") {
+    throw new AgentError(
+      "MODEL_ERROR",
+      `Model stopped at max_tokens (${tokenCount} tokens) without producing content. Raise maxTokens.`,
+      false
+    );
+  }
+}
+function assertNotEmptyReasoningSplit(text, toolCalls, thinking, stopReason) {
+  if (!text && !toolCalls.length && thinking && stopReason === "stop") {
+    throw new AgentError(
+      "MODEL_ERROR",
+      "Model stopped with stop_reason=stop having put the entire answer in the reasoning channel (empty content, no tool calls, thinking present). The reasoning/content split lost the reply \u2014 retry or raise maxTokens.",
+      true
+    );
+  }
+}
+function toAnthropicContent(m) {
+  if (typeof m.content === "string") return m.content;
+  const parts = [];
+  const text = wireTextOf(m.content);
+  if (text) parts.push({ type: "text", text });
+  for (const img of imagesOf(m.content)) {
+    parts.push({
+      type: "image",
+      source: img.data ? { type: "base64", media_type: img.mimeType ?? "image/jpeg", data: img.data } : { type: "url", url: img.url }
+    });
+  }
+  for (const b of m.content) {
+    if (b.type === "tool_call") parts.push({ type: "tool_use", id: b.id, name: b.name, input: b.args ?? {} });
+  }
+  return parts;
+}
+var AnthropicProvider = class {
+  id;
+  capabilities = { structuredOutput: false, streaming: true };
+  opts;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("AnthropicProvider: apiKey is required (.env ANTHROPIC_API_KEY)");
+    this.opts = { baseUrl: "https://api.anthropic.com", maxTokens: 1024, ...opts };
+    if (this.opts.thinkingBudget && this.opts.maxTokens != null && this.opts.maxTokens <= this.opts.thinkingBudget) {
+      throw new Error(
+        `AnthropicProvider: maxTokens (${this.opts.maxTokens}) must exceed thinkingBudget (${this.opts.thinkingBudget}); raise maxTokens`
+      );
+    }
+    this.id = `anthropic:${opts.model}`;
+  }
+  async complete(options) {
+    const { fetchFn = fetch, apiKey, model, baseUrl, maxTokens, temperature, thinkingBudget, stream } = this.opts;
+    const needsVision = options.messages.some((m) => hasImages(m.content));
+    assertCanHandle(model, needsVision);
+    const system = options.messages.filter((m) => m.role === "system").map((m) => wireTextOf(m.content)).join("\n\n");
+    const messages = [];
+    for (const m of options.messages.filter((x) => x.role !== "system")) {
+      if (m.role === "tool") {
+        const result = { type: "tool_result", tool_use_id: m.toolCallId, content: toAnthropicContent(m) };
+        const last = messages[messages.length - 1];
+        if (last && last.role === "user" && Array.isArray(last.content) && last.content.some((b) => b.type === "tool_result")) {
+          last.content.push(result);
+          continue;
+        }
+        messages.push({ role: "user", content: [result] });
+        continue;
+      }
+      messages.push({ role: m.role === "assistant" ? "assistant" : "user", content: toAnthropicContent(m) });
+    }
+    const body = {
+      model,
+      max_tokens: maxTokens,
+      ...system ? { system } : {},
+      ...temperature != null ? { temperature } : {},
+      ...thinkingBudget ? { thinking: { type: "enabled", budget_tokens: thinkingBudget } } : {},
+      ...stream ? { stream: true } : {},
+      messages,
+      ...options.tools.length ? {
+        tools: options.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.parametersSchema ?? { type: "object" }
+        }))
+      } : {}
+    };
+    let res;
+    try {
+      res = await fetchFn(`${baseUrl.replace(/\/$/, "")}/v1/messages`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+          ...stream ? { accept: "text/event-stream" } : {}
+        },
+        body: JSON.stringify(body),
+        ...options.signal ? { signal: options.signal } : {}
+      });
+    } catch (err) {
+      throw new AgentError("MODEL_ERROR", `Model request failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      const retryable = res.status === 429 || res.status >= 500;
+      throw new AgentError("MODEL_ERROR", `Model HTTP ${res.status}: ${text.slice(0, 300)}`, retryable);
+    }
+    return stream ? this.readStream(res, options) : this.readJson(res, options);
+  }
+  toCompletion(blocks, usage, options) {
+    let text = "";
+    let thinking = "";
+    const toolCalls = [];
+    for (const b of blocks) {
+      if (b.type === "text" && b.text) {
+        text += b.text;
+        options.onToken?.(b.text);
+      } else if (b.type === "thinking" && b.thinking) {
+        thinking += b.thinking;
+        options.onThinking?.(b.thinking);
+      } else if (b.type === "tool_use" && b.name) {
+        toolCalls.push({ id: b.id ?? `call_${toolCalls.length}`, name: b.name, args: b.input ?? {} });
+      }
+    }
+    return { text, ...thinking ? { thinking } : {}, toolCalls, usage };
+  }
+  async readJson(res, options) {
+    const json = await res.json();
+    const out = this.toCompletion(json.content ?? [], {
+      inputTokens: json.usage?.input_tokens ?? 0,
+      outputTokens: json.usage?.output_tokens ?? 0
+    }, options);
+    const finishReason = normalizeStopReason(json.stop_reason);
+    assertNotEmptyTruncation(out.text, out.toolCalls, finishReason, json.usage?.output_tokens ?? 0);
+    assertNotEmptyReasoningSplit(out.text, out.toolCalls, out.thinking ?? "", finishReason);
+    return finishReason ? { ...out, finishReason } : out;
+  }
+  async readStream(res, options) {
+    if (!res.body) throw new Error("Streaming response has no body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let event = "";
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let stopReason;
+    const blocks = [];
+    let current;
+    let jsonInput = "";
+    const flush = (chunk) => {
+      buffer += chunk;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const t = line.trim();
+        if (!t) continue;
+        if (t.startsWith("event:")) {
+          event = t.slice(6).trim();
+          continue;
+        }
+        if (!t.startsWith("data:")) continue;
+        const payload = t.slice(5).trim();
+        if (!payload) continue;
+        let data;
+        try {
+          data = JSON.parse(payload);
+        } catch {
+          continue;
+        }
+        if (event === "message_start") {
+          const mu = (data.message ?? {}).usage;
+          if (mu?.input_tokens != null) inputTokens = mu.input_tokens;
+        } else if (event === "message_delta") {
+          const du = data.usage ?? {};
+          if (du.output_tokens != null) outputTokens = du.output_tokens;
+          const sr = data.delta ?? {};
+          if (sr.stop_reason) stopReason = normalizeStopReason(sr.stop_reason);
+        } else if (event === "content_block_start") {
+          const block = data.content_block ?? {};
+          current = { type: block.type, id: block.id, name: block.name };
+          jsonInput = "";
+        } else if (event === "content_block_delta") {
+          const delta = data.delta ?? {};
+          if (delta.text) {
+            current = current ?? { type: "text" };
+            current.text = (current.text ?? "") + delta.text;
+          } else if (delta.thinking) {
+            current = current ?? { type: "thinking" };
+            current.thinking = (current.thinking ?? "") + delta.thinking;
+          } else if (delta.partial_json) {
+            jsonInput += delta.partial_json;
+          }
+        } else if (event === "content_block_stop") {
+          if (current) {
+            if (current.type === "tool_use") {
+              try {
+                current.input = JSON.parse(jsonInput || "{}");
+              } catch {
+                current.input = {};
+              }
+            }
+            blocks.push(current);
+            current = void 0;
+          }
+        }
+      }
+    };
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      flush(decoder.decode(value, { stream: true }));
+    }
+    flush(decoder.decode());
+    if (current) blocks.push(current);
+    const out = this.toCompletion(blocks, { inputTokens, outputTokens }, options);
+    assertNotEmptyTruncation(out.text, out.toolCalls, stopReason, outputTokens);
+    assertNotEmptyReasoningSplit(out.text, out.toolCalls, out.thinking ?? "", stopReason);
+    return stopReason ? { ...out, finishReason: stopReason } : out;
+  }
+};
+
+// src/models/ollama.ts
+var OllamaProvider = class extends OpenAICompatibleProvider {
+  id;
+  capabilities = { structuredOutput: false, streaming: true };
+  constructor(opts) {
+    super({
+      baseUrl: opts.baseUrl ?? "http://localhost:11434/v1",
+      apiKey: "ollama",
+      model: opts.model,
+      ...opts.temperature != null ? { temperature: opts.temperature } : {},
+      ...opts.maxTokens != null ? { maxTokens: opts.maxTokens } : {},
+      ...opts.stream != null ? { stream: opts.stream } : {},
+      ...opts.fetchFn ? { fetchFn: opts.fetchFn } : {}
+    });
+    this.id = `ollama:${opts.model}`;
+  }
+};
+
+// src/models/factory.ts
+function initChatModel(spec, opts = {}) {
+  const cfg = loadConfig();
+  const extra = {
+    ...opts.temperature != null ? { temperature: opts.temperature } : {},
+    ...opts.maxTokens != null ? { maxTokens: opts.maxTokens } : {},
+    ...opts.stream != null ? { stream: opts.stream } : {}
+  };
+  const colon = spec.indexOf(":");
+  const provider = colon > 0 ? spec.slice(0, colon) : "together";
+  const model = colon > 0 ? spec.slice(colon + 1) : spec;
+  switch (provider) {
+    case "together": {
+      const apiKey = opts.apiKey ?? cfg.TOGETHER_API_KEY;
+      if (!apiKey) throw new Error("initChatModel: set TOGETHER_API_KEY in .env (or pass apiKey)");
+      return new OpenAICompatibleProvider({ baseUrl: opts.baseUrl ?? cfg.TOGETHER_BASE_URL, apiKey, model, ...extra });
+    }
+    case "openai": {
+      const apiKey = opts.apiKey ?? cfg.OPENAI_API_KEY;
+      if (!apiKey) throw new Error("initChatModel: set OPENAI_API_KEY in .env (or pass apiKey)");
+      return new OpenAICompatibleProvider({ baseUrl: opts.baseUrl ?? cfg.OPENAI_BASE_URL, apiKey, model, ...extra });
+    }
+    case "anthropic": {
+      const apiKey = opts.apiKey ?? cfg.ANTHROPIC_API_KEY;
+      if (!apiKey) throw new Error("initChatModel: set ANTHROPIC_API_KEY in .env (or pass apiKey)");
+      return new AnthropicProvider({
+        apiKey,
+        model,
+        ...opts.baseUrl ? { baseUrl: opts.baseUrl } : { baseUrl: cfg.ANTHROPIC_BASE_URL },
+        ...opts.thinkingBudget != null ? { thinkingBudget: opts.thinkingBudget } : {},
+        ...extra
+      });
+    }
+    case "ollama": {
+      return new OllamaProvider({ model, ...opts.baseUrl ? { baseUrl: opts.baseUrl } : { baseUrl: cfg.OLLAMA_BASE_URL }, ...extra });
+    }
+    case "custom": {
+      if (!opts.baseUrl || !opts.apiKey) throw new Error("initChatModel: custom: needs baseUrl + apiKey");
+      return new OpenAICompatibleProvider({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, model, ...extra });
+    }
+    default:
+      throw new Error(`initChatModel: unknown provider "${provider}" (use together:|openai:|anthropic:|ollama:|custom:)`);
+  }
+}
+
+// src/a2a/index.ts
+import { createServer } from "http";
+import { z as z2 } from "zod";
+function textOfParts(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts.map((p) => {
+    if (typeof p === "string") return p;
+    if (p && typeof p === "object") {
+      const o = p;
+      if (typeof o.text === "string") return o.text;
+    }
+    return "";
+  }).join("");
+}
+var A2AServer = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.maxContexts = Math.max(1, opts.maxContexts ?? 1e3);
+  }
+  opts;
+  server;
+  contexts = /* @__PURE__ */ new Map();
+  maxContexts;
+  corsHeaders(origin) {
+    const allowed = this.opts.corsOrigins ?? [];
+    if (!allowed.length || !origin) return {};
+    if (!allowed.includes("*") && !allowed.includes(origin)) return {};
+    return {
+      "access-control-allow-origin": allowed.includes("*") ? "*" : origin,
+      "access-control-allow-methods": "GET, POST, OPTIONS",
+      "access-control-allow-headers": "content-type, authorization"
+    };
+  }
+  runOpts(contextId) {
+    return this.opts.checkpointer ? { checkpointer: this.opts.checkpointer, threadId: contextId } : {};
+  }
+  async agentFor(contextId) {
+    const existing = this.contexts.get(contextId);
+    if (existing) {
+      this.contexts.delete(contextId);
+      this.contexts.set(contextId, existing);
+      return existing;
+    }
+    const agent = await this.opts.agentFactory(contextId);
+    this.contexts.set(contextId, agent);
+    while (this.contexts.size > this.maxContexts) {
+      const oldest = this.contexts.keys().next().value;
+      if (oldest === void 0) break;
+      this.contexts.delete(oldest);
+    }
+    return agent;
+  }
+  /** Read a request body with a hard cap; JSON.parse errors to the caller. */
+  readBody(req) {
+    const max = this.opts.maxBodyBytes ?? 10 * 1024 * 1024;
+    return new Promise((resolve4, reject) => {
+      let data = "";
+      req.on("data", (c) => {
+        data += c;
+        if (data.length > max) {
+          req.destroy();
+          reject(new AgentError("A2A_BODY_TOO_LARGE", `Request body exceeds ${max} bytes`, false));
+        }
+      });
+      req.on("end", () => resolve4(data));
+      req.on("error", reject);
+    });
+  }
+  async handle(req, res) {
+    const cors = this.corsHeaders(req.headers.origin);
+    const send = (code, body) => {
+      res.writeHead(code, { "content-type": "application/json", ...cors });
+      res.end(JSON.stringify(body));
+    };
+    try {
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, { ...cors });
+        res.end();
+        return;
+      }
+      if (req.method === "GET" && (req.url === "/ok" || req.url === "/health")) {
+        send(200, { ok: true });
+        return;
+      }
+      if (req.method === "GET" && req.url === "/.well-known/agent-card.json") {
+        send(200, this.opts.card);
+        return;
+      }
+      if (req.method === "POST" && (req.url === "/" || req.url === "")) {
+        const rpc = JSON.parse(await this.readBody(req));
+        if (rpc.method !== "message/send") {
+          send(200, { jsonrpc: "2.0", id: rpc.id, error: { code: -32601, message: `Unknown method: ${rpc.method}` } });
+          return;
+        }
+        const contextId = rpc.params?.contextId ?? `ctx-${Date.now().toString(36)}`;
+        const text = textOfParts(rpc.params?.message?.parts);
+        const result = await (await this.agentFor(contextId)).run(text, this.runOpts(contextId));
+        send(200, {
+          jsonrpc: "2.0",
+          id: rpc.id,
+          result: { message: { role: "agent", parts: [{ kind: "text", text: result.text }] }, contextId }
+        });
+        return;
+      }
+      if (req.method === "POST" && req.url === "/stream") {
+        const rpc = JSON.parse(await this.readBody(req));
+        const contextId = rpc.params?.contextId ?? `ctx-${Date.now().toString(36)}`;
+        const text = textOfParts(rpc.params?.message?.parts);
+        res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+        const write = (payload) => {
+          res.write(`data: ${JSON.stringify(payload)}
+
+`);
+        };
+        const disconnect = new AbortController();
+        res.on("close", () => {
+          if (!res.writableEnded) disconnect.abort();
+        });
+        try {
+          const gen = (await this.agentFor(contextId)).stream(text, {
+            signal: disconnect.signal,
+            ...this.runOpts(contextId)
+          });
+          for (; ; ) {
+            const next = await gen.next();
+            if (next.done) {
+              write({ contextId, done: true, text: next.value.text });
+              break;
+            }
+            write({ contextId, event: next.value });
+          }
+        } catch (err) {
+          write({ contextId, error: err instanceof Error ? err.message : String(err) });
+        }
+        write("[DONE]");
+        res.end();
+        return;
+      }
+      send(404, { error: "not found" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (res.headersSent) {
+        try {
+          res.write(`data: ${JSON.stringify({ error: message })}
+
+`);
+          res.write("data: [DONE]\n\n");
+          res.end();
+        } catch {
+        }
+        return;
+      }
+      send(
+        err instanceof AgentError && err.code === "A2A_BODY_TOO_LARGE" ? 413 : 200,
+        { jsonrpc: "2.0", id: null, error: { code: -32603, message } }
+      );
+    }
+  }
+  async start(port, host2) {
+    const listenPort = port ?? this.opts.port ?? 0;
+    const listenHost = host2 ?? this.opts.host ?? "127.0.0.1";
+    this.server = createServer((req, res) => void this.handle(req, res));
+    await new Promise((resolve4) => this.server?.listen(listenPort, listenHost, () => resolve4()));
+    return this.server.address().port;
+  }
+  async stop() {
+    await new Promise(
+      (resolve4, reject) => this.server ? this.server.close((e) => e ? reject(e) : resolve4()) : resolve4()
+    );
+    this.server = void 0;
+    this.contexts.clear();
+  }
+};
+
+// src/skills/index.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join as join2 } from "path";
+import { z as z3 } from "zod";
+var FrontmatterSchema = z3.object({
+  name: z3.string().min(1),
+  description: z3.string().min(1),
+  version: z3.string().default("0.1.0")
+});
+function parseSkillFile(content, path = "<inline>") {
+  const raw = content.startsWith("\uFEFF") ? content.slice(1) : content;
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) throw new Error(`Invalid SKILL.md (missing frontmatter): ${path}`);
+  const [, fm, body] = match;
+  const meta = {};
+  for (const line of fm.split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  const parsed = FrontmatterSchema.parse(meta);
+  if (!body.trim()) throw new Error(`Invalid SKILL.md (empty body): ${path}`);
+  return { ...parsed, path, body: body.trim() };
+}
+var SkillRegistry = class {
+  skills = /* @__PURE__ */ new Map();
+  register(skill) {
+    if (this.skills.has(skill.name)) throw new Error(`Skill already registered: ${skill.name}`);
+    this.skills.set(skill.name, skill);
+    return this;
+  }
+  get(name) {
+    return this.skills.get(name);
+  }
+  list() {
+    return [...this.skills.values()];
+  }
+  /** Expose each skill's tools (if any) for Agent consumption. */
+  asTools() {
+    return this.list().flatMap((s) => s.tools ?? []);
+  }
+};
+async function discoverSkills(dirs, opts = {}) {
+  const found = [];
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = join2(dir, entry);
+      let stat2;
+      try {
+        stat2 = statSync(full);
+      } catch {
+        continue;
+      }
+      const file2 = stat2.isDirectory() ? join2(full, "SKILL.md") : full;
+      if (!file2.endsWith("SKILL.md")) continue;
+      try {
+        found.push({ ...parseSkillFile(readFileSync(file2, "utf8"), file2), tools: [] });
+      } catch (err) {
+        if (opts.strict) throw err;
+      }
+    }
+  }
+  return found;
+}
+
+// src/checkpoint/index.ts
+import { mkdir, open, readFile, stat, unlink, writeFile } from "fs/promises";
+import { join as join3 } from "path";
+async function withFileLock(lockPath, fn, opts = {}) {
+  const staleMs = opts.staleMs ?? 3e4;
+  await mkdir(join3(lockPath, ".."), { recursive: true });
+  for (; ; ) {
+    try {
+      const handle = await open(lockPath, "wx");
+      await handle.close();
+      break;
+    } catch (err) {
+      const code = err.code;
+      if (code !== "EEXIST") throw err;
+      try {
+        const info = await stat(lockPath);
+        if (Date.now() - info.mtimeMs < staleMs) {
+          throw new Error(`Lock held: ${lockPath}`);
+        }
+      } catch (statErr) {
+        if (statErr.code !== "ENOENT") throw statErr;
+      }
+      try {
+        await unlink(lockPath);
+      } catch {
+      }
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try {
+      await unlink(lockPath);
+    } catch {
+    }
+  }
+}
+var FileCheckpointer = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  /** threadId lands in a filesystem path — keep it a single safe directory name. */
+  threadDir(threadId) {
+    if (threadId === "" || threadId === "." || threadId === ".." || threadId.includes("/")) {
+      throw new AgentError("THREAD_ID_INVALID", `Invalid threadId: ${JSON.stringify(threadId)}`, false);
+    }
+    return join3(this.root, "threads", threadId);
+  }
+  file(threadId) {
+    return join3(this.threadDir(threadId), "checkpoint.json");
+  }
+  lock(threadId) {
+    return join3(this.threadDir(threadId), ".lock");
+  }
+  async save(threadId, checkpoint) {
+    const record = { threadId, savedAt: (/* @__PURE__ */ new Date()).toISOString(), ...checkpoint };
+    await withFileLock(this.lock(threadId), async () => {
+      await mkdir(join3(this.file(threadId), ".."), { recursive: true });
+      await writeFile(this.file(threadId), JSON.stringify(record), "utf8");
+    });
+  }
+  async load(threadId) {
+    return withFileLock(this.lock(threadId), async () => {
+      try {
+        return JSON.parse(await readFile(this.file(threadId), "utf8"));
+      } catch {
+        return void 0;
+      }
+    });
+  }
+  async delete(threadId) {
+    await withFileLock(this.lock(threadId), async () => {
+      try {
+        await unlink(this.file(threadId));
+      } catch {
+      }
+    });
+  }
+};
+
+// src/serve/index.ts
+var AgentDefSchema = z4.object({
+  name: z4.string().min(1),
+  description: z4.string().default(""),
+  systemPrompt: z4.string().default("You are a helpful agent. Use tools when needed. Be concise."),
+  model: z4.string(),
+  port: z4.number().int().positive().optional(),
+  skills: z4.array(z4.string()).default([]),
+  filesystem: z4.string().optional(),
+  todos: z4.boolean().default(false),
+  maxSteps: z4.number().int().positive().default(8),
+  sessionDir: z4.string().optional(),
+  /** Extra env file for this agent (keys override framework-level). */
+  envFile: z4.string().optional()
+});
+var AgentEntrySchema = z4.union([
+  AgentDefSchema,
+  z4.object({ file: z4.string() }).catchall(z4.unknown())
+]);
+var FrameworkFileSchema = z4.object({
+  server: z4.object({ host: z4.string().default("127.0.0.1"), basePort: z4.number().int().min(0).default(8484) }).default({}),
+  /** Framework-level env file(s), loaded before agents resolve models. */
+  envFile: z4.union([z4.string(), z4.array(z4.string())]).optional(),
+  /** Inline env mapping (applied after env files, overrides them). */
+  env: z4.record(z4.string()).optional(),
+  /** Local checkpoint dir for served agents (durable HITL threads). */
+  checkpointer: z4.object({ dir: z4.string() }).optional(),
+  http: z4.object({ corsOrigins: z4.array(z4.string()).default([]) }).default({}),
+  agents: z4.array(AgentEntrySchema).min(1)
+});
+function loadEnvFile(path, override = true) {
+  dotenvConfig({ path, override });
+}
+function resolveAgentPaths(def, dir) {
+  return {
+    ...def,
+    skills: def.skills.map((s) => resolve2(dir, s)),
+    ...def.filesystem ? { filesystem: resolve2(dir, def.filesystem) } : {},
+    ...def.sessionDir ? { sessionDir: resolve2(dir, def.sessionDir) } : {},
+    ...def.envFile ? { envFile: resolve2(dir, def.envFile) } : {}
+  };
+}
+function resolveAgentEntry(fileRaw, overrides, agentDir, frameworkDir) {
+  const fileKeys = new Set(Object.keys(fileRaw));
+  const merged = AgentDefSchema.parse({ ...fileRaw, ...overrides });
+  const against = (key) => fileKeys.has(key) && !(key in overrides) ? agentDir : frameworkDir;
+  return {
+    ...merged,
+    skills: merged.skills.map((s) => resolve2(against("skills"), s)),
+    ...merged.filesystem ? { filesystem: resolve2(against("filesystem"), merged.filesystem) } : {},
+    ...merged.sessionDir ? { sessionDir: resolve2(against("sessionDir"), merged.sessionDir) } : {},
+    ...merged.envFile ? { envFile: resolve2(against("envFile"), merged.envFile) } : {}
+  };
+}
+function loadFrameworkConfig(path) {
+  const raw = JSON.parse(readFileSync2(path, "utf8"));
+  const parsed = FrameworkFileSchema.parse(raw);
+  const dir = dirname2(resolve2(path));
+  for (const envFile of parsed.envFile ? [parsed.envFile].flat() : []) {
+    loadEnvFile(resolve2(dir, envFile), false);
+  }
+  for (const [key, value] of Object.entries(parsed.env ?? {})) {
+    process.env[key] = value;
+  }
+  return {
+    server: parsed.server,
+    ...parsed.envFile ? { envFile: parsed.envFile } : {},
+    ...parsed.env ? { env: parsed.env } : {},
+    ...parsed.checkpointer ? { checkpointer: { dir: resolve2(dir, parsed.checkpointer.dir) } } : {},
+    http: parsed.http,
+    agents: parsed.agents.map((entry) => {
+      if ("file" in entry && typeof entry.file === "string") {
+        const agentPath = resolve2(dir, entry.file);
+        const agentDir = dirname2(agentPath);
+        const fileRaw = JSON.parse(readFileSync2(agentPath, "utf8"));
+        const { file: _file, ...overrides } = entry;
+        void _file;
+        const resolved2 = resolveAgentEntry(fileRaw, overrides, agentDir, dir);
+        if (resolved2.envFile) loadEnvFile(resolved2.envFile);
+        return resolved2;
+      }
+      const resolved = resolveAgentPaths(AgentDefSchema.parse(entry), dir);
+      if (resolved.envFile) loadEnvFile(resolved.envFile);
+      return resolved;
+    })
+  };
+}
+async function buildServedAgent(def, opts = {}) {
+  const middlewares = [];
+  if (def.filesystem) middlewares.push(filesystemMiddleware({ root: def.filesystem }));
+  if (def.todos) middlewares.push(todoListMiddleware());
+  let systemPrompt = def.systemPrompt;
+  if (def.skills.length) {
+    const registry = new SkillRegistry();
+    for (const dir of def.skills) {
+      for (const s of await discoverSkills([dir])) {
+        try {
+          registry.register(s);
+        } catch {
+        }
+      }
+    }
+    const catalog = registry.list().map((s) => `- ${s.name}: ${s.description}`).join("\n");
+    if (catalog) systemPrompt += `
+
+Available skill packs (mention $name to invoke):
+${catalog}`;
+  }
+  const agent = new Agent({
+    name: def.name,
+    description: def.description,
+    systemPrompt,
+    model: initChatModel(def.model),
+    maxSteps: def.maxSteps,
+    middleware: middlewares,
+    ...def.sessionDir ? {
+      // Context-scoped id keeps one def's sessions from mingling when
+      // the server runs a fresh agent per A2A contextId.
+      sessionManager: new SessionManager({
+        sessionId: opts.sessionId ?? def.name,
+        storage: new LocalFileStorage(def.sessionDir)
+      })
+    } : {}
+  });
+  return { agent, card: { name: def.name, ...def.description ? { description: def.description } : {} } };
+}
+async function serveFramework(file2) {
+  const served = [];
+  const checkpointer = file2.checkpointer ? new FileCheckpointer(file2.checkpointer.dir) : void 0;
+  let port = file2.server.basePort;
+  for (const def of file2.agents) {
+    const { card } = await buildServedAgent(def);
+    const server = new A2AServer({
+      card,
+      // Fresh agent per A2A contextId — sharing one instance would leak one
+      // conversation into another context's history.
+      agentFactory: (contextId) => buildServedAgent(def, def.sessionDir ? { sessionId: `${def.name}:${contextId}` } : {}).then((r) => r.agent),
+      ...checkpointer ? { checkpointer } : {},
+      corsOrigins: file2.http.corsOrigins,
+      host: file2.server.host
+    });
+    const actual = await server.start(def.port ?? port, file2.server.host);
+    port = actual + 1;
+    const url = `http://${file2.server.host}:${actual}`;
+    served.push({ name: def.name, url, cardUrl: `${url}/.well-known/agent-card.json`, server });
+  }
+  return {
+    agents: served,
+    stop: async () => {
+      for (const s of served) await s.server.stop();
+    }
+  };
+}
+
+// src/observability/index.ts
+function supportsColor() {
+  return !process.env.NO_COLOR && !!process.stdout?.isTTY;
+}
+var C = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m",
+  magenta: "\x1B[35m",
+  red: "\x1B[31m"
+};
+function paint(color, text, on) {
+  if (!on || color === "reset") return text;
+  return `${C[color]}${text}${C.reset}`;
+}
+function logError(prefix, err, colors) {
+  const on = colors ?? supportsColor();
+  const message = err instanceof Error ? err.stack ?? err.message : String(err);
+  console.error(paint("red", `${prefix} error:`, on), message);
+}
+
+// src/serve/cli.ts
+var HELP = `framework \u2014 launch Framework agents as local servers.
+
+Usage:
+  framework-serve [command] [options]
+
+Commands:
+  dev [-c framework.json] [--host H] [--port N]   local dev server (default)
+  serve|up [-c framework.json]                     serve agents
+  validate [-c framework.json]                     validate config and print agents
+  --help                                           this help
+
+framework.json keys: server{host,basePort}, envFile, env{}, checkpointer{dir},
+http{corsOrigins}, agents[{name, model, file?, envFile?, skills?, filesystem?,
+todos?, maxSteps?, sessionDir?, port?}]. Agent files + relative paths resolve
+against their own file's directory; inline overrides against framework.json.
+`;
+function arg(flag, short) {
+  const i = process.argv.findIndex((a) => a === flag || short && a === short);
+  return i >= 0 ? process.argv[i + 1] : void 0;
+}
+var command = process.argv[2] ?? "dev";
+if (command === "--help" || command === "-h" || process.argv.includes("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (!["dev", "serve", "up", "validate"].includes(command)) {
+  console.error(`Unknown command: ${command}
+${HELP}`);
+  process.exit(1);
+}
+var configPath = resolve3(arg("-c", "--config") ?? "framework.json");
+var file;
+try {
+  file = loadFrameworkConfig(configPath);
+} catch (err) {
+  logError("[framework]", err);
+  process.exit(1);
+}
+if (command === "validate") {
+  console.log(`OK: ${configPath}`);
+  for (const a of file.agents) {
+    console.log(`- ${a.name} [${a.model}]${a.port ? ` :${a.port}` : ""}${a.envFile ? ` (env: ${a.envFile})` : ""}`);
+  }
+  process.exit(0);
+}
+var host = arg("--host") ?? file.server.host;
+var portArg = arg("--port");
+if (portArg) {
+  const port = Number.parseInt(portArg, 10);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error(`Invalid --port: ${portArg}`);
+    process.exit(1);
+  }
+  file.server.basePort = port;
+}
+var { agents, stop } = await serveFramework({ ...file, server: { ...file.server, host } });
+for (const a of agents) {
+  console.log(`[framework] ${a.name} -> ${a.url} (card: ${a.cardUrl})`);
+}
+console.log(`[framework] ${command === "dev" ? "dev server" : "serving"} ${agents.length} agent(s). Ctrl-C to stop.`);
+var shutdown = async () => {
+  await stop();
+  process.exit(0);
+};
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());