@coinrithm/mcp-trading 0.1.8 → 0.2.0

package/dist/agent/decision.js

@@ -0,0 +1,85 @@
+// Parse the model's single text response into a strict, structured Decision.
+// v1 accepts FUTURES actions only. Anything else — invalid JSON, an unknown
+// action type, a free-form endpoint/tool name, extra unknown fields, or a
+// missing required field — fails closed (the runner then skips the cycle).
+import { z } from "zod";
+const futuresOpen = z
+    .object({
+    type: z.literal("futures_open"),
+    symbol: z.string().min(1),
+    side: z.enum(["long", "short"]),
+    leverage: z.number().positive(),
+    marginMusd: z.number().positive(),
+    stopLossPrice: z.number().nullable().optional(),
+    takeProfitPrice: z.number().nullable().optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    rationaleSummary: z.string().optional(),
+})
+    .strict();
+const futuresClose = z
+    .object({
+    type: z.literal("futures_close"),
+    positionId: z.number(),
+    fraction: z.number().positive().max(1).optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    rationaleSummary: z.string().optional(),
+})
+    .strict();
+const futuresSetSltp = z
+    .object({
+    type: z.literal("futures_set_sltp"),
+    positionId: z.number(),
+    stopLossPrice: z.number().nullable().optional(),
+    takeProfitPrice: z.number().nullable().optional(),
+})
+    .strict();
+const actionSchema = z.discriminatedUnion("type", [
+    futuresOpen,
+    futuresClose,
+    futuresSetSltp,
+]);
+const decisionSchema = z
+    .object({
+    decision: z.enum(["skip", "act"]),
+    confidence: z.number().min(0).max(1).optional(),
+    reason: z.string().optional(),
+    actions: z.array(actionSchema).default([]),
+})
+    .strict();
+// Pull a JSON object out of a model response that may be fenced or wrapped.
+function coerceJson(text) {
+    let s = text.trim();
+    const fence = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(s);
+    if (fence)
+        s = fence[1].trim();
+    if (!s.startsWith("{")) {
+        const i = s.indexOf("{");
+        const j = s.lastIndexOf("}");
+        if (i >= 0 && j > i)
+            s = s.slice(i, j + 1);
+    }
+    return JSON.parse(s); // throws on invalid JSON -> caller treats as fail-closed
+}
+export function parseDecision(text) {
+    let obj;
+    try {
+        obj = coerceJson(text);
+    }
+    catch (err) {
+        return { ok: false, error: `model output is not valid JSON: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const res = decisionSchema.safeParse(obj);
+    if (!res.success) {
+        return {
+            ok: false,
+            error: res.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "),
+        };
+    }
+    const d = res.data;
+    // A "skip" decision ignores any actions; an "act" with no actions is a skip.
+    const actions = d.decision === "act" ? d.actions : [];
+    return {
+        ok: true,
+        decision: { decision: d.decision, confidence: d.confidence, reason: d.reason, actions },
+    };
+}

package/dist/agent/decisionValidator.js

@@ -0,0 +1,107 @@
+// The decision gate: re-check EVERY proposed action against the spec's hard caps
+// BEFORE any write. The model only proposes; this disposes. Because the caps
+// come from the spec (not the observation or the model), a prompt-injection in
+// market text cannot widen a limit or force a trade. v1 = futures only.
+import { ok, fail, actionVenue, } from "./types.js";
+const SERVER_MAX_LEVERAGE = 20;
+export function validateAction(action, ctx) {
+    const { spec, observation } = ctx;
+    // v1 scope: futures only.
+    if (action.type === "spot_order" || action.type === "spot_cancel" || action.type === "pm_open") {
+        return fail("out_of_scope_v1", `action "${action.type}" is out of v1 scope (futures only)`);
+    }
+    const venue = actionVenue(action);
+    if (!spec.venues.includes(venue)) {
+        return fail("venue_not_allowed", `venue ${venue} not in [${spec.venues.join(", ")}]`);
+    }
+    if (spec.sync.requirePollBeforeWrite && !observation.polledBeforeWrite) {
+        return fail("no_poll_before_write", "must successfully poll /trades before writing");
+    }
+    if (ctx.writesThisCycle >= spec.limits.maxWritesPerCycle) {
+        return fail("write_budget_exceeded", `maxWritesPerCycle ${spec.limits.maxWritesPerCycle} reached`);
+    }
+    if (ctx.writesToday >= spec.limits.maxTradesPerDay) {
+        return fail("daily_trade_cap", `maxTradesPerDay ${spec.limits.maxTradesPerDay} reached`);
+    }
+    if (action.type === "futures_open") {
+        // Daily realized-loss stop: once today's loss hits the cap, open no new risk.
+        if (spec.limits.maxDailyLossMusd > 0 && ctx.realizedLossTodayMusd >= spec.limits.maxDailyLossMusd) {
+            return fail("daily_loss_cap", `today's realized loss ${ctx.realizedLossTodayMusd} >= ${spec.limits.maxDailyLossMusd}`);
+        }
+        const entry = observation.watch.find((w) => w.symbol.toUpperCase() === action.symbol.toUpperCase());
+        if (!entry)
+            return fail("unknown_symbol", `${action.symbol} is not on the watchlist`);
+        if (!entry.coinId)
+            return fail("unresolved_symbol", `${action.symbol} did not resolve to a coin`);
+        if (action.leverage > spec.risk.maxLeverage) {
+            return fail("leverage_exceeds_cap", `leverage ${action.leverage} > cap ${spec.risk.maxLeverage}`);
+        }
+        if (action.leverage > SERVER_MAX_LEVERAGE) {
+            return fail("leverage_exceeds_server", `leverage ${action.leverage} > server cap ${SERVER_MAX_LEVERAGE}`);
+        }
+        if (action.marginMusd > spec.risk.perTradeMarginMusd) {
+            return fail("margin_exceeds_cap", `margin ${action.marginMusd} > cap ${spec.risk.perTradeMarginMusd}`);
+        }
+        // Aggregate exposure ceiling (existing open margin + this cycle) — the cap
+        // that perTradeMargin × maxConcurrentPositions would otherwise blow past.
+        if (ctx.openMarginMusd + action.marginMusd > spec.limits.maxOpenMarginMusd) {
+            return fail("open_margin_exceeds_cap", `open margin ${ctx.openMarginMusd} + ${action.marginMusd} > ${spec.limits.maxOpenMarginMusd}`);
+        }
+        if (ctx.openCount >= spec.risk.maxConcurrentPositions) {
+            return fail("max_positions", `already ${ctx.openCount} open >= ${spec.risk.maxConcurrentPositions}`);
+        }
+        if (ctx.cashAvailableMusd != null && action.marginMusd > ctx.cashAvailableMusd) {
+            return fail("insufficient_balance", `margin ${action.marginMusd} > available ${ctx.cashAvailableMusd}`);
+        }
+        // NOTE: minConfidence keys on the model's SELF-REPORTED confidence — a
+        // cooperation hint, NOT an injection-resistant control. The hard caps above
+        // (which come from the spec, never the observation) are what actually bind.
+        if ((action.confidence ?? 0) < spec.abstention.minConfidence) {
+            return fail("below_min_confidence", `confidence ${action.confidence ?? 0} < min ${spec.abstention.minConfidence}`);
+        }
+        if (spec.risk.requireStopLoss) {
+            const sl = action.stopLossPrice;
+            if (sl == null || !Number.isFinite(sl) || sl <= 0) {
+                return fail("missing_stop_loss", "requireStopLoss is set but no valid (finite, positive) stopLossPrice was proposed");
+            }
+            // Side-aware corridor: a long's stop must be BELOW entry, a short's ABOVE.
+            // A wrong-side "stop" is a dead trigger that never protects.
+            const e = ctx.quote?.entryPrice;
+            if (typeof e === "number" && Number.isFinite(e)) {
+                if (action.side === "long" && sl >= e) {
+                    return fail("stop_loss_wrong_side", `long stop ${sl} must be below entry ${e}`);
+                }
+                if (action.side === "short" && sl <= e) {
+                    return fail("stop_loss_wrong_side", `short stop ${sl} must be above entry ${e}`);
+                }
+            }
+        }
+        if (!ctx.quote)
+            return fail("missing_quote", "no quote evidence was fetched for this open");
+        if (!ctx.quote.eligible) {
+            return fail("quote_ineligible", `quote blocked: ${JSON.stringify(ctx.quote.blockReasons ?? [])}`);
+        }
+        // FAIL-CLOSED: a missing freshness block is treated as not-fresh.
+        if (!ctx.quote.freshness || ctx.quote.freshness.status !== "fresh") {
+            return fail("stale_quote", `quote freshness ${ctx.quote.freshness?.status ?? "missing"} (need fresh)`);
+        }
+        return ok();
+    }
+    if (action.type === "futures_close" || action.type === "futures_set_sltp") {
+        const pos = observation.openPositions.find((p) => p.id === action.positionId && p.venue === "futures");
+        if (!pos)
+            return fail("unknown_position", `no open futures position ${action.positionId}`);
+        // No double-acting on the same position within one cycle.
+        if (ctx.targetedPositionIds.includes(action.positionId)) {
+            return fail("position_already_targeted", `position ${action.positionId} already acted on this cycle`);
+        }
+        if (action.type === "futures_set_sltp") {
+            const hasTrigger = [action.stopLossPrice, action.takeProfitPrice].some((v) => typeof v === "number" && Number.isFinite(v) && v > 0);
+            if (!hasTrigger) {
+                return fail("sltp_no_op", "futures_set_sltp must set at least one positive stopLossPrice or takeProfitPrice");
+            }
+        }
+        return ok();
+    }
+    return fail("unknown_action", "unsupported action type");
+}

package/dist/agent/extract.js

@@ -0,0 +1,5 @@
+// Defensive extractors for untyped API JSON.
+export const asObj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
+export const asArr = (v) => (Array.isArray(v) ? v : []);
+export const asNum = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+export const asStr = (v) => typeof v === "string" ? v : undefined;

package/dist/agent/frontmatter.js

@@ -0,0 +1,19 @@
+import { parse as parseYaml } from "yaml";
+export function parseFrontmatter(text) {
+    const src = text.replace(/\r\n/g, "\n");
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(src);
+    if (!m) {
+        throw new Error("skill file has no YAML frontmatter (expected a `---` block at the top)");
+    }
+    let data;
+    try {
+        data = parseYaml(m[1]);
+    }
+    catch (err) {
+        throw new Error(`skill frontmatter is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (data == null || typeof data !== "object" || Array.isArray(data)) {
+        throw new Error("skill frontmatter must be a YAML mapping (key: value pairs)");
+    }
+    return { data: data, body: (m[2] ?? "").trim() };
+}

package/dist/agent/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// coinrithm-agent CLI entrypoint.
+import { main } from "./cli.js";
+main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/agent/manifest.js

@@ -0,0 +1,40 @@
+// The frozen, fully-resolved agent definition. Writing meta/manifest.lock.json
+// makes a decomposed folder as reproducible as pinning a single SKILL.md by
+// commit SHA: anyone can see exactly which knob values (and from which files)
+// produced a run. Deterministic by construction — no timestamps, keys sorted.
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { sha256, stableStringify, toPosix } from "./util.js";
+import { RESOLVER_VERSION, RUNNER_VERSION, MANIFEST_SCHEMA } from "./version.js";
+export function buildManifest(resolved, spec) {
+    // configHash binds the RESOLVED spec to the resolver + schema version, so a
+    // run reproduces only against the same compile (not just the same files).
+    const configHash = sha256(stableStringify({
+        resolvedSpec: spec,
+        resolverVersion: RESOLVER_VERSION,
+        schema: MANIFEST_SCHEMA,
+    }));
+    return {
+        schema: MANIFEST_SCHEMA,
+        spec: spec.spec || "coinrithm.agent.v1",
+        resolverVersion: RESOLVER_VERSION,
+        runnerVersion: RUNNER_VERSION,
+        resolvedConfig: resolved.rawFrontmatter,
+        resolvedSpec: spec,
+        provenance: resolved.provenance,
+        contentHashes: resolved.contentHashes,
+        configHash,
+    };
+}
+// Serialize deterministically (sorted keys, no timestamps) so two compiles of
+// the same inputs on Windows and Linux are byte-identical.
+export function serializeManifest(manifest) {
+    return stableStringify(manifest) + "\n";
+}
+export function writeManifest(agentDir, manifest) {
+    const metaDir = join(agentDir, "meta");
+    mkdirSync(metaDir, { recursive: true });
+    const out = join(metaDir, "manifest.lock.json");
+    writeFileSync(out, serializeManifest(manifest), "utf8");
+    return toPosix(out);
+}

package/dist/agent/mergeRules.js

@@ -0,0 +1,82 @@
+// Deterministic merge rules for the agent resolver.
+//
+// Codex audit, adopted: HARD CAPS merge by "most-restrictive-wins", NOT
+// last-writer-wins. A skill/tactic module may only TIGHTEN a cap; any attempt
+// to WIDEN one is rejected (fail-closed), never silently ignored. This makes a
+// decomposed agent strictly safer than its inline form can be — a part-file or
+// a tactic can never loosen a limit, regardless of file/merge order.
+//
+// Normal (non-cap) config uses simple precedence (inline > $ref > defaults),
+// handled in the resolver; this module owns only the cap arithmetic.
+// risk.* hard caps a tactic module may tighten.
+export const RISK_CAPS = {
+    maxLeverage: "lower",
+    perTradeMarginMusd: "lower",
+    maxConcurrentPositions: "lower",
+    requireStopLoss: "true",
+};
+// limits.* throughput/spend caps a tactic module may tighten.
+export const LIMIT_CAPS = {
+    maxTradesPerDay: "lower",
+    maxWritesPerCycle: "lower",
+    maxDailyLossMusd: "lower",
+    maxOpenMarginMusd: "lower",
+};
+// Is `candidate` at least as restrictive as `base` (i.e. a legal tightening)?
+export function isAtLeastAsRestrictive(dir, candidate, base) {
+    if (dir === "true") {
+        // true is tighter than false. candidate must not be LESS strict than base.
+        // legal: base=false→candidate any; base=true→candidate must be true.
+        return base === true ? candidate === true : true;
+    }
+    if (typeof candidate !== "number" || typeof base !== "number") {
+        // a non-numeric cap candidate where a number is expected is not a legal
+        // tightening (caller will surface a type issue separately).
+        return false;
+    }
+    return dir === "lower" ? candidate <= base : candidate >= base;
+}
+// The more-restrictive of two values for a cap field.
+export function mostRestrictive(dir, a, b) {
+    if (dir === "true")
+        return a === true || b === true ? true : false;
+    if (typeof a !== "number")
+        return b;
+    if (typeof b !== "number")
+        return a;
+    return dir === "lower" ? Math.min(a, b) : Math.max(a, b);
+}
+// Merge a tactic-module cap patch onto a base cap block under tighten-only +
+// most-restrictive-wins. `caps` is the field→direction map (RISK_CAPS/LIMIT_CAPS).
+// A patch key that is NOT a known cap, or that WIDENS a cap, is an issue.
+export function mergeCapPatch(base, patch, caps, sourceLabel) {
+    const merged = { ...base };
+    const issues = [];
+    for (const [key, value] of Object.entries(patch)) {
+        const dir = caps[key];
+        if (!dir) {
+            issues.push({
+                code: "skill_patch_unknown_cap",
+                path: sourceLabel,
+                message: `tactic "${sourceLabel}" may only tighten known caps (${Object.keys(caps).join(", ")}); got "${key}"`,
+            });
+            continue;
+        }
+        if (!(key in base) || base[key] === undefined) {
+            // No base to tighten against — accept the value as-is (it can't widen
+            // something that wasn't set; the top-level/defaults still bound it).
+            merged[key] = value;
+            continue;
+        }
+        if (!isAtLeastAsRestrictive(dir, value, base[key])) {
+            issues.push({
+                code: "skill_patch_widens_cap",
+                path: sourceLabel,
+                message: `tactic "${sourceLabel}" tries to WIDEN ${key} (${JSON.stringify(base[key])} → ${JSON.stringify(value)}); a tactic may only tighten`,
+            });
+            continue;
+        }
+        merged[key] = mostRestrictive(dir, base[key], value);
+    }
+    return { merged, issues };
+}

package/dist/agent/observe.js

@@ -0,0 +1,110 @@
+// Observe phase: read CoinRithm state into one Observation. Sync-polls /trades
+// before any write (polledBeforeWrite=true only after that succeeds). If a
+// required read fails, or no watchlist symbol resolves, the cycle SKIPS writes.
+import { asObj, asArr, asNum, asStr } from "./extract.js";
+function freshnessOf(block) {
+    const fr = asObj(block.freshness);
+    const status = asStr(fr.status);
+    return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
+}
+function emptyObservation(state, scopes = []) {
+    return {
+        asOf: state.cursor ?? new Date().toISOString(),
+        scopes,
+        cashAvailableMusd: null,
+        equityMusd: null,
+        openPositions: [],
+        watch: [],
+        syncCursor: state.cursor,
+        newClosedTrades: [],
+        polledBeforeWrite: false,
+    };
+}
+export async function observe(client, spec, state, trace) {
+    const meR = await client.me(trace);
+    if (!meR.ok)
+        return { observation: emptyObservation(state), skip: `me failed (HTTP ${meR.status})` };
+    const scopes = asArr(asObj(meR.data).scopes).filter((s) => typeof s === "string");
+    const [portR, walletR, posR] = await Promise.all([
+        client.portfolio(trace),
+        client.wallet(undefined, trace),
+        client.futuresPositions(undefined, trace),
+    ]);
+    if (!portR.ok || !walletR.ok || !posR.ok) {
+        return { observation: emptyObservation(state, scopes), skip: "required reads failed (portfolio/wallet/positions)" };
+    }
+    const usdt = asObj(asObj(walletR.data).usdt);
+    const equity = asObj(asObj(portR.data).equity);
+    const cashAvailableMusd = asNum(usdt.available) ?? asNum(equity.availableUsd) ?? null;
+    const equityMusd = asNum(equity.totalUsd) ?? asNum(asObj(portR.data).equityUsd) ?? null;
+    const openPositions = asArr(asObj(posR.data).positions)
+        .map(asObj)
+        .filter((p) => (asStr(p.status) ?? "open") === "open")
+        .map((p) => ({
+        venue: "futures",
+        id: Number(asNum(p.id) ?? p.id),
+        coinId: asStr(p.coinId),
+        symbol: asStr(p.symbol),
+        side: asStr(p.side),
+        status: asStr(p.status) ?? "open",
+        marginMusd: asNum(p.marginMusd),
+        unrealizedPnlMusd: asNum(p.unrealizedPnlMusd),
+    }));
+    // Sync poll: /trades since the persisted cursor.
+    const tradesR = await client.trades({ venue: "futures", updatedSince: state.cursor ?? undefined, limit: state.cursor ? undefined : 1 }, trace);
+    let polledBeforeWrite = false;
+    let newClosedTrades = [];
+    let syncCursor = state.cursor;
+    if (tradesR.ok) {
+        polledBeforeWrite = true;
+        const td = asObj(tradesR.data);
+        syncCursor = asStr(td.asOf) ?? state.cursor;
+        newClosedTrades = asArr(td.trades)
+            .map(asObj)
+            .filter((t) => !state.seen.includes(`${asStr(t.venue) ?? "futures"}:${asNum(t.id) ?? t.id}`));
+    }
+    // Watchlist market context.
+    const watch = [];
+    let resolvedAny = false;
+    for (const symbol of spec.risk.watchlist) {
+        const rs = await client.resolve(symbol, trace);
+        const match = asObj(asObj(rs.data).match);
+        const coinId = rs.ok && match.coinId != null ? String(match.coinId) : null;
+        if (!coinId) {
+            watch.push({ symbol, coinId: null });
+            continue;
+        }
+        resolvedAny = true;
+        const mk = await client.market(coinId, trace);
+        const m = asObj(mk.data);
+        const price = asObj(m.price);
+        watch.push({
+            symbol,
+            coinId,
+            name: asStr(match.name),
+            priceUsd: asNum(price.usd),
+            change1h: asNum(price.change1h),
+            change24h: asNum(price.change24h),
+            change7d: asNum(price.change7d),
+            // Freshness lives under the response's `observation` block.
+            freshness: freshnessOf(asObj(m.observation)),
+        });
+    }
+    const observation = {
+        asOf: syncCursor ?? new Date().toISOString(),
+        scopes,
+        cashAvailableMusd,
+        equityMusd,
+        openPositions,
+        watch,
+        syncCursor,
+        newClosedTrades,
+        polledBeforeWrite,
+    };
+    if (!resolvedAny)
+        return { observation, skip: "no watchlist symbol resolved to a coin" };
+    if (spec.sync.requirePollBeforeWrite && !polledBeforeWrite) {
+        return { observation, skip: "poll-before-write required but /trades poll failed" };
+    }
+    return { observation };
+}

package/dist/agent/prompt.js

@@ -0,0 +1,45 @@
+// Build the system + user prompts for one decide step. The system prompt is the
+// static character (cached prefix); the user prompt is the fresh observation.
+// The model only PROPOSES — the runner re-checks every action against the caps,
+// so the prompt states the caps but never relies on the model to honor them.
+export function buildSystemPrompt(spec, mergedProse) {
+    const r = spec.risk;
+    return [
+        "You operate a CoinRithm PAPER-TRADING futures agent (simulated 50,000 mUSD; not real money, not financial advice).",
+        "You only PROPOSE actions as structured JSON. A separate runner re-validates every action against hard caps and executes it; you cannot bypass a cap.",
+        "",
+        "## Your strategy (your borders)",
+        mergedProse.trim() || "(no strategy prose provided)",
+        "",
+        "## Hard caps the runner enforces (do not exceed; proposing over a cap wastes the cycle)",
+        `- venues: ${spec.venues.join(", ")} (v1 executes FUTURES only)`,
+        `- maxLeverage ${r.maxLeverage}; perTradeMarginMusd ${r.perTradeMarginMusd}; maxConcurrentPositions ${r.maxConcurrentPositions}; requireStopLoss ${r.requireStopLoss}`,
+        `- watchlist (only these): ${r.watchlist.join(", ")}`,
+        `- abstention.minConfidence ${spec.abstention.minConfidence}; a skipped cycle is correct and cheap`,
+        "",
+        "## Output contract — return ONLY this JSON object, nothing else:",
+        `{"decision":"skip"|"act","confidence":0..1,"reason":"short","actions":[]}`,
+        'Each action is one of: {"type":"futures_open","symbol","side":"long"|"short","leverage","marginMusd","stopLossPrice","takeProfitPrice"},',
+        '{"type":"futures_close","positionId","fraction"}, {"type":"futures_set_sltp","positionId","stopLossPrice","takeProfitPrice"}.',
+        "Always include a stopLossPrice on a futures_open. Prefer skip when the signal is weak or data is stale.",
+    ].join("\n");
+}
+export function buildUserPrompt(obs) {
+    return [
+        "Decide for THIS cycle using only the observation below (data available now — no look-ahead).",
+        "",
+        "```json",
+        JSON.stringify({
+            asOf: obs.asOf,
+            cashAvailableMusd: obs.cashAvailableMusd,
+            equityMusd: obs.equityMusd,
+            openPositions: obs.openPositions,
+            watch: obs.watch,
+            newClosedTrades: obs.newClosedTrades,
+            polledBeforeWrite: obs.polledBeforeWrite,
+        }, null, 2),
+        "```",
+        "",
+        "Return ONLY the JSON decision object.",
+    ].join("\n");
+}

package/dist/agent/providers.js

@@ -0,0 +1,134 @@
+// BYO-model provider layer. The user's model API key comes from the ENV ONLY,
+// never from an agent file. One call returns one chunk of text that must be a
+// single structured-JSON decision (parsed in decision.ts). No free-form tool
+// execution — the model only proposes; the runner disposes.
+function envKey(provider, env) {
+    switch (provider) {
+        case "anthropic":
+            return env.ANTHROPIC_API_KEY;
+        case "openai":
+            return env.OPENAI_API_KEY;
+        case "groq":
+            return env.GROQ_API_KEY;
+        case "openai-compatible":
+            return env.MODEL_API_KEY ?? env.OPENAI_API_KEY;
+    }
+}
+function baseUrlFor(provider, configured) {
+    switch (provider) {
+        case "openai":
+            return "https://api.openai.com/v1";
+        case "groq":
+            return "https://api.groq.com/openai/v1";
+        case "openai-compatible":
+            return (configured ?? "").replace(/\/+$/, "");
+        case "anthropic":
+            return "https://api.anthropic.com/v1";
+    }
+}
+class AnthropicProvider {
+    model;
+    apiKey;
+    fetchFn;
+    label;
+    constructor(model, apiKey, fetchFn) {
+        this.model = model;
+        this.apiKey = apiKey;
+        this.fetchFn = fetchFn;
+        this.label = `anthropic/${model}`;
+    }
+    async decide(input) {
+        try {
+            const res = await this.fetchFn("https://api.anthropic.com/v1/messages", {
+                method: "POST",
+                headers: {
+                    "x-api-key": this.apiKey,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    max_tokens: input.maxTokens ?? 1024,
+                    system: input.system,
+                    messages: [{ role: "user", content: input.user }],
+                }),
+            });
+            if (!res.ok)
+                return { ok: false, error: `anthropic HTTP ${res.status}: ${await res.text()}` };
+            const json = (await res.json());
+            const text = json.content?.map((c) => c.text ?? "").join("") ?? "";
+            return text ? { ok: true, text } : { ok: false, error: "anthropic returned empty content" };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+}
+class OpenAiCompatProvider {
+    model;
+    apiKey;
+    baseUrl;
+    fetchFn;
+    label;
+    constructor(model, apiKey, baseUrl, fetchFn) {
+        this.model = model;
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.fetchFn = fetchFn;
+        this.label = `${baseUrl}/${model}`;
+    }
+    async decide(input) {
+        try {
+            const res = await this.fetchFn(`${this.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    temperature: 0.2,
+                    max_tokens: input.maxTokens ?? 1024,
+                    response_format: { type: "json_object" },
+                    messages: [
+                        { role: "system", content: input.system },
+                        { role: "user", content: input.user },
+                    ],
+                }),
+            });
+            if (!res.ok)
+                return { ok: false, error: `provider HTTP ${res.status}: ${await res.text()}` };
+            const json = (await res.json());
+            const text = json.choices?.[0]?.message?.content ?? "";
+            return text ? { ok: true, text } : { ok: false, error: "provider returned empty content" };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+}
+// Build the provider from the spec's model block + env key. Throws a clear
+// error if no model is configured (self-host requires one) or the env key is
+// missing. fetch is injectable for tests.
+export function selectProvider(spec, env, fetchFn = fetch) {
+    if (!spec.model) {
+        throw new Error("no model configured: set model.provider + model.name in the agent (self-host needs an explicit model)");
+    }
+    const { provider, name, baseUrl } = spec.model;
+    const key = envKey(provider, env);
+    if (!key) {
+        const varName = provider === "anthropic"
+            ? "ANTHROPIC_API_KEY"
+            : provider === "groq"
+                ? "GROQ_API_KEY"
+                : "OPENAI_API_KEY / MODEL_API_KEY";
+        throw new Error(`missing model API key: set ${varName} in the environment (never in an agent file)`);
+    }
+    if (provider === "anthropic")
+        return new AnthropicProvider(name, key, fetchFn);
+    const resolvedBase = baseUrlFor(provider, baseUrl);
+    if (!resolvedBase) {
+        throw new Error("openai-compatible provider needs model.baseUrl");
+    }
+    return new OpenAiCompatProvider(name, key, resolvedBase, fetchFn);
+}