@coinrithm/mcp-trading 0.1.7 → 0.2.0

package/dist/agent/resolve.js

@@ -0,0 +1,490 @@
+// The agent resolver: compile a single agent.md OR a decomposed agent FOLDER
+// into one deterministic { rawFrontmatter, mergedProse, provenance, hashes }.
+//
+// Design (Codex audit, adopted):
+//   - Single FILE input  -> passthrough: frontmatter + body, exactly like a
+//     legacy SKILL.md. No $ref/include resolution.
+//   - DIRECTORY input    -> full resolve: a keystone (agent.md | SKILL.md) whose
+//     config blocks may be inline OR a { $ref: "<path>" } to a part-file, plus
+//     an optional include[] of tactic skills.
+//   - FAIL-CLOSED on: missing keystone, missing $ref, path traversal, symlink,
+//     $ref cycle, invalid YAML, a tactic that widens a hard cap, and ANY
+//     secret found in merged frontmatter OR merged prose. All issues are
+//     collected, then thrown together.
+//   - The machine-read config and the prose the LLM reads never cross: only
+//     YAML/frontmatter feeds rawFrontmatter; only markdown bodies feed
+//     mergedProse.
+import { readFileSync, existsSync, statSync, lstatSync } from "node:fs";
+import { resolve as resolvePath, relative as relativePath, join, isAbsolute } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseFrontmatter } from "./frontmatter.js";
+import { sha256, toPosix, isPathInside, boundTail, scanForSecrets, } from "./util.js";
+import { mergeCapPatch, RISK_CAPS, LIMIT_CAPS } from "./mergeRules.js";
+export class ResolveError extends Error {
+    issues;
+    constructor(issues) {
+        super("agent resolve failed:\n" +
+            issues.map((i) => `  [${i.code}] ${i.message}`).join("\n"));
+        this.name = "ResolveError";
+        this.issues = issues;
+    }
+}
+const KEYSTONE_NAMES = ["agent.md", "SKILL.md"]; // SKILL.md kept as an alias
+const CONFIG_BLOCKS = [
+    "trigger",
+    "model",
+    "venues",
+    "risk",
+    "sizing",
+    "limits",
+    "abstention",
+    "sync",
+    "killSwitch",
+    "objective",
+    "capabilities",
+];
+const IDENTITY_KEYS = ["name", "description", "spec", "mode"];
+const JOURNAL_MAX_LINES = 200;
+const JOURNAL_MAX_BYTES = 8_000;
+// Optional prose files (markdown the LLM reads), in assembly order.
+const PROSE_FILES = ["character/thesis.md", "character/persona.md"];
+// Enforced cap field names. sizing.yaml is SOFT guidance and must NOT contain
+// any of these (or a user could think a limit binds when it does not).
+const ENFORCED_FIELD_NAMES = new Set([
+    ...Object.keys(RISK_CAPS),
+    ...Object.keys(LIMIT_CAPS),
+    "maxDrawdownMusd",
+    "maxConsecutiveRejects",
+    "maxConsecutiveModelFailures",
+    "onRateLimitPressure",
+]);
+// A $ref must be a LOCAL, RELATIVE path inside the agent folder — never a URL,
+// an absolute path, a home/drive path, or a Windows backslash path.
+function refSyntaxIssue(ref) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(ref))
+        return "remote/URL $ref is not allowed";
+    if (ref.startsWith("~"))
+        return "home-relative (~) $ref is not allowed";
+    if (ref.includes("\\"))
+        return "backslash in $ref is not allowed (use forward slashes)";
+    if (isAbsolute(ref) || /^[a-zA-Z]:/.test(ref))
+        return "absolute $ref is not allowed";
+    return null;
+}
+function rel(dir, abs) {
+    return toPosix(relativePath(dir, abs));
+}
+// Resolve a ref relative to the agent dir, enforcing: inside the folder, exists,
+// not a symlink. Returns the absolute path or null (with an issue pushed).
+function safePath(ctx, ref, label) {
+    const syn = refSyntaxIssue(ref);
+    if (syn) {
+        ctx.issues.push({ code: "unsafe_ref", path: ref, message: `${label} "${ref}": ${syn}` });
+        return null;
+    }
+    const target = resolvePath(ctx.dir, ref);
+    if (!isPathInside(ctx.dir, target)) {
+        ctx.issues.push({
+            code: "path_traversal",
+            path: ref,
+            message: `${label} "${ref}" escapes the agent folder`,
+        });
+        return null;
+    }
+    if (!existsSync(target)) {
+        ctx.issues.push({
+            code: "missing_ref",
+            path: ref,
+            message: `${label} target not found: "${ref}"`,
+        });
+        return null;
+    }
+    if (lstatSync(target).isSymbolicLink()) {
+        ctx.issues.push({
+            code: "symlink_rejected",
+            path: ref,
+            message: `${label} "${ref}" is a symlink (not allowed)`,
+        });
+        return null;
+    }
+    return target;
+}
+function readHashed(ctx, abs) {
+    const content = readFileSync(abs, "utf8");
+    const r = rel(ctx.dir, abs);
+    const lower = r.toLowerCase();
+    const prior = ctx.seenLower.get(lower);
+    if (prior && prior !== r) {
+        ctx.issues.push({
+            code: "path_case_collision",
+            path: r,
+            message: `"${r}" differs only by case from "${prior}" — ambiguous on case-insensitive filesystems`,
+        });
+    }
+    ctx.seenLower.set(lower, r);
+    ctx.hashes[r] = sha256(content);
+    if (!ctx.mergeOrder.includes(r))
+        ctx.mergeOrder.push(r);
+    return content;
+}
+// sizing.yaml is SOFT guidance: it must never carry an enforced cap name, or a
+// user could believe a limit binds when only risk/limits/killSwitch actually do.
+function checkSizing(ctx, rawFrontmatter) {
+    const sizing = rawFrontmatter.sizing;
+    if (sizing && typeof sizing === "object" && !Array.isArray(sizing)) {
+        for (const k of Object.keys(sizing)) {
+            if (ENFORCED_FIELD_NAMES.has(k)) {
+                ctx.issues.push({
+                    code: "sizing_enforced_key",
+                    path: "sizing",
+                    message: `sizing is SOFT guidance and may not contain the enforced cap "${k}" — move it to risk/limits/killSwitch`,
+                });
+            }
+        }
+    }
+}
+function parseYamlSafe(ctx, content, label) {
+    try {
+        return parseYaml(content);
+    }
+    catch (err) {
+        ctx.issues.push({
+            code: "invalid_yaml",
+            path: label,
+            message: `invalid YAML in "${label}": ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return undefined;
+    }
+}
+function isRef(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        typeof value.$ref === "string");
+}
+// Resolve a config-block value: inline values pass through; a { $ref } loads the
+// part-file (recursively, with cycle detection) and parses it as YAML.
+function resolveValue(ctx, value, visiting) {
+    if (!isRef(value))
+        return value;
+    const ref = value.$ref;
+    const abs = safePath(ctx, ref, "$ref");
+    if (!abs)
+        return undefined;
+    if (visiting.has(abs)) {
+        ctx.issues.push({
+            code: "include_cycle",
+            path: ref,
+            message: `$ref cycle detected at "${ref}"`,
+        });
+        return undefined;
+    }
+    const content = readHashed(ctx, abs);
+    const parsed = parseYamlSafe(ctx, content, rel(ctx.dir, abs));
+    visiting.add(abs);
+    const resolved = resolveValue(ctx, parsed, visiting);
+    visiting.delete(abs);
+    return resolved;
+}
+function scanSecrets(ctx, frontmatter, prose) {
+    for (const f of scanForSecrets(frontmatter)) {
+        ctx.issues.push({ code: "secret_in_frontmatter", message: f });
+    }
+    for (const f of scanForSecrets(prose)) {
+        ctx.issues.push({
+            code: "secret_in_prose",
+            message: `${f} (a key in a prose body would be sent to the model — remove it)`,
+        });
+    }
+}
+// ── single-file passthrough ──────────────────────────────────────────────────
+function resolveSingleFile(abs) {
+    const issues = [];
+    const dir = abs; // single file: refs are not resolved, so dir is unused
+    const content = readFileSync(abs, "utf8");
+    let data = {};
+    let body = "";
+    try {
+        const fm = parseFrontmatter(content);
+        data = fm.data;
+        body = fm.body;
+    }
+    catch (err) {
+        throw new ResolveError([
+            {
+                code: "invalid_frontmatter",
+                path: toPosix(abs),
+                message: err instanceof Error ? err.message : String(err),
+            },
+        ]);
+    }
+    const ctx = { dir, issues, hashes: {}, mergeOrder: [], seenLower: new Map() };
+    const r = toPosix(abs);
+    ctx.hashes[r] = sha256(content);
+    ctx.mergeOrder.push(r);
+    checkSizing(ctx, data);
+    scanSecrets(ctx, data, body);
+    if (issues.length)
+        throw new ResolveError(issues);
+    const sources = {};
+    for (const k of Object.keys(data))
+        sources[k] = r;
+    return {
+        inputPath: abs,
+        isDirectory: false,
+        rawFrontmatter: data,
+        mergedProse: body,
+        proseParts: [{ source: r, text: body }],
+        provenance: { sources, mergeOrder: ctx.mergeOrder, includeOrder: [] },
+        contentHashes: ctx.hashes,
+    };
+}
+// ── directory resolve ────────────────────────────────────────────────────────
+function findKeystone(dir) {
+    for (const name of KEYSTONE_NAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function loadSkillList(ctx, frontmatter) {
+    // include[] in the keystone wins; else character/skills/_index.yaml `active`.
+    if (Array.isArray(frontmatter.include)) {
+        return frontmatter.include.filter((s) => typeof s === "string");
+    }
+    const indexPath = join(ctx.dir, "character/skills/_index.yaml");
+    if (existsSync(indexPath)) {
+        const abs = safePath(ctx, "character/skills/_index.yaml", "skills index");
+        if (!abs)
+            return [];
+        const parsed = parseYamlSafe(ctx, readHashed(ctx, abs), "character/skills/_index.yaml");
+        const active = parsed?.active;
+        if (Array.isArray(active))
+            return active.filter((s) => typeof s === "string");
+    }
+    return [];
+}
+function resolveDirectory(dir) {
+    const ctx = { dir, issues: [], hashes: {}, mergeOrder: [], seenLower: new Map() };
+    const keystoneAbs = findKeystone(dir);
+    if (!keystoneAbs) {
+        throw new ResolveError([
+            {
+                code: "missing_keystone",
+                message: `agent folder has no keystone (expected one of: ${KEYSTONE_NAMES.join(", ")})`,
+            },
+        ]);
+    }
+    let frontmatter = {};
+    let keystoneBody = "";
+    try {
+        const fm = parseFrontmatter(readHashed(ctx, keystoneAbs));
+        frontmatter = fm.data;
+        keystoneBody = fm.body;
+    }
+    catch (err) {
+        throw new ResolveError([
+            {
+                code: "invalid_frontmatter",
+                path: rel(dir, keystoneAbs),
+                message: err instanceof Error ? err.message : String(err),
+            },
+        ]);
+    }
+    const keystoneRel = rel(dir, keystoneAbs);
+    const rawFrontmatter = {};
+    const sources = {};
+    // `extends`: a base layer of whole config blocks (e.g. runtime.yaml provides
+    // model + trigger). Shallow + flat — an extends file is a YAML mapping of
+    // config blocks; inline frontmatter overrides it block-for-block. No nesting.
+    const baseBlocks = {};
+    const baseSource = {};
+    if (Array.isArray(frontmatter.extends)) {
+        for (const ext of frontmatter.extends) {
+            if (typeof ext !== "string")
+                continue;
+            const abs = safePath(ctx, ext, "extends");
+            if (!abs)
+                continue;
+            const parsed = parseYamlSafe(ctx, readHashed(ctx, abs), ext);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                ctx.issues.push({
+                    code: "invalid_extends",
+                    path: ext,
+                    message: `extends file "${ext}" must be a YAML mapping of config blocks`,
+                });
+                continue;
+            }
+            const map = parsed;
+            if ("extends" in map) {
+                ctx.issues.push({
+                    code: "nested_extends",
+                    path: ext,
+                    message: `extends file "${ext}" may not itself use extends`,
+                });
+            }
+            for (const [k, v] of Object.entries(map)) {
+                if (k === "extends")
+                    continue;
+                baseBlocks[k] = v; // later extends wins
+                baseSource[k] = ext;
+            }
+        }
+    }
+    // Copy EVERY keystone key (so the strict key-lint can also flag unknown keys
+    // in the folder path, not just single-file); resolve $ref pointers for config
+    // blocks. `extends` is a directive (handled above). `include` is copied here
+    // AND consumed for skills below.
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key === "extends")
+            continue;
+        if (CONFIG_BLOCKS.includes(key)) {
+            const wasRef = isRef(value);
+            rawFrontmatter[key] = resolveValue(ctx, value, new Set([keystoneAbs]));
+            sources[key] = wasRef
+                ? (() => {
+                    const t = safePath(ctx, value.$ref, "$ref");
+                    return t ? rel(dir, t) : keystoneRel;
+                })()
+                : keystoneRel;
+        }
+        else {
+            rawFrontmatter[key] = value;
+            sources[key] = keystoneRel;
+        }
+    }
+    // Fill any config block the keystone did NOT set from the extends base layer.
+    for (const [k, v] of Object.entries(baseBlocks)) {
+        if (!(k in rawFrontmatter)) {
+            rawFrontmatter[k] = v;
+            sources[k] = baseSource[k];
+        }
+    }
+    // Skills (tactics): bodies → prose; optional risk/limits patch → tighten-only.
+    const includeOrder = [];
+    const skillProse = [];
+    const seenSkills = new Set();
+    for (const name of loadSkillList(ctx, frontmatter)) {
+        if (seenSkills.has(name)) {
+            ctx.issues.push({
+                code: "duplicate_include",
+                path: name,
+                message: `skill "${name}" included more than once`,
+            });
+            continue;
+        }
+        seenSkills.add(name);
+        const refPath = `character/skills/${name}.md`;
+        const abs = safePath(ctx, refPath, "skill");
+        if (!abs)
+            continue;
+        let patch = {};
+        let body = "";
+        try {
+            const fm = parseFrontmatter(readHashed(ctx, abs));
+            patch = fm.data;
+            body = fm.body;
+        }
+        catch {
+            // a skill file may be pure prose (no frontmatter) — treat whole as body.
+            body = readFileSync(abs, "utf8");
+        }
+        includeOrder.push(name);
+        skillProse.push({ source: refPath, text: body });
+        applySkillPatch(ctx, rawFrontmatter, patch, refPath);
+    }
+    // Prose assembly (machine-read config never enters here).
+    const proseParts = [];
+    if (keystoneBody.trim())
+        proseParts.push({ source: keystoneRel, text: keystoneBody });
+    for (const pf of PROSE_FILES) {
+        const p = join(dir, pf);
+        if (existsSync(p)) {
+            const abs = safePath(ctx, pf, "prose");
+            if (abs)
+                proseParts.push({ source: pf, text: readHashed(ctx, abs) });
+        }
+    }
+    proseParts.push(...skillProse);
+    // Bounded memory: most-recent-N of journal/notes.md. runs/ is NEVER loaded.
+    const journalPath = join(dir, "journal/notes.md");
+    if (existsSync(journalPath)) {
+        const abs = safePath(ctx, "journal/notes.md", "journal");
+        if (abs) {
+            const full = readHashed(ctx, abs);
+            proseParts.push({
+                source: "journal/notes.md",
+                text: boundTail(full, JOURNAL_MAX_LINES, JOURNAL_MAX_BYTES),
+            });
+        }
+    }
+    const mergedProse = proseParts
+        .map((p) => `<!-- ${p.source} -->\n${p.text.trim()}`)
+        .join("\n\n");
+    checkSizing(ctx, rawFrontmatter);
+    scanSecrets(ctx, rawFrontmatter, mergedProse);
+    if (ctx.issues.length)
+        throw new ResolveError(ctx.issues);
+    const provenance = {
+        sources,
+        mergeOrder: ctx.mergeOrder,
+        includeOrder,
+    };
+    return {
+        inputPath: dir,
+        isDirectory: true,
+        rawFrontmatter,
+        mergedProse,
+        proseParts,
+        provenance,
+        contentHashes: ctx.hashes,
+    };
+}
+// Apply a tactic module's frontmatter patch. Only risk/limits cap blocks are
+// permitted, tighten-only; anything else is rejected (no permission expansion).
+function applySkillPatch(ctx, rawFrontmatter, patch, sourceLabel) {
+    for (const key of Object.keys(patch)) {
+        if (key === "risk" || key === "limits") {
+            const caps = key === "risk" ? RISK_CAPS : LIMIT_CAPS;
+            const base = rawFrontmatter[key] ?? {};
+            const p = patch[key];
+            if (!p || typeof p !== "object" || Array.isArray(p)) {
+                ctx.issues.push({
+                    code: "skill_patch_invalid",
+                    path: sourceLabel,
+                    message: `tactic "${sourceLabel}" ${key} patch must be a mapping`,
+                });
+                continue;
+            }
+            const { merged, issues } = mergeCapPatch(base, p, caps, sourceLabel);
+            rawFrontmatter[key] = merged;
+            ctx.issues.push(...issues);
+        }
+        else {
+            ctx.issues.push({
+                code: "skill_patch_forbidden_key",
+                path: sourceLabel,
+                message: `tactic "${sourceLabel}" may only tighten risk/limits caps (include order controls prompt order, not permissions); got "${key}"`,
+            });
+        }
+    }
+}
+// ── entry point ──────────────────────────────────────────────────────────────
+export function resolveAgent(inputPath) {
+    const abs = resolvePath(inputPath);
+    if (!existsSync(abs)) {
+        throw new ResolveError([
+            { code: "input_missing", message: `no such path: ${inputPath}` },
+        ]);
+    }
+    const st = statSync(abs);
+    if (st.isFile())
+        return resolveSingleFile(abs);
+    if (st.isDirectory())
+        return resolveDirectory(abs);
+    throw new ResolveError([
+        { code: "input_invalid", message: "input must be a file or a directory" },
+    ]);
+}

package/dist/agent/runEvidence.js

@@ -0,0 +1,23 @@
+// Run-evidence helpers: one runId per process, one decisionId per cycle, the
+// agentTrace stamped on every traced call, and the export at the end.
+import { shortId } from "./util.js";
+export function makeRunId(spec) {
+    const slug = (spec.name || "agent").replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
+    return `${slug}-${shortId()}`;
+}
+export function makeDecisionId(cycle) {
+    return `cycle-${cycle}-${shortId()}`;
+}
+export function makeTrace(runId, decisionId, spec, confidence, rationaleSummary) {
+    return {
+        runId,
+        decisionId,
+        strategyLabel: spec.name || "agent",
+        confidence,
+        rationaleSummary,
+    };
+}
+export async function exportRunEvidence(client, runId) {
+    const r = await client.exportRunEvidence(runId);
+    return r.ok ? r.data : { error: `run-evidence export failed (HTTP ${r.status})` };
+}