@mnemom/mnemom 0.16.1 → 0.17.0-next.0

package/dist/commands/wrap.js

@@ -0,0 +1,331 @@
+/**
+ * `mnemom wrap` — instrument an existing production agent through the Mnemom gateway (MNE-935, A4).
+ *
+ * Asks the developer for their provider + framework + agent name, makes a birth
+ * call to the gateway to provision the agent identity, seeds starter alignment +
+ * protection cards, and emits a drop-in code example. No reasoning change to the
+ * host agent.
+ *
+ * AUTH MODEL: Two credentials are involved:
+ *   - Mnemom auth (MNEMOM_API_KEY or `mnemom login` JWT) — used for card writes
+ *   - Provider API key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY) — used
+ *     for the one-time gateway birth call; this is the same key the user's agent
+ *     already holds, so the birth requires no new credential
+ *
+ * See SKILL-RUNNER-CONTRACT.md §2–§4 for the lifecycle + output contract.
+ */
+import { requireAuth } from "../lib/auth.js";
+import { putAlignmentCard, putProtectionCard, MnemomApiError } from "../lib/api.js";
+import { mergeAgentConfig } from "../lib/agent-config.js";
+import { askSelect, askInput, isInteractive } from "../lib/prompt.js";
+import { getGatewayUrl } from "../lib/config.js";
+import { fmt } from "../lib/format.js";
+const AGENT_HEADER = "x-mnemom-agent";
+const PROVIDERS = {
+    anthropic: {
+        label: "Anthropic",
+        keyEnv: "ANTHROPIC_API_KEY",
+        keyHeader: "x-api-key",
+        defaultModel: "claude-haiku-4-5-20251001",
+        basePath: "/anthropic",
+    },
+    openai: {
+        label: "OpenAI",
+        keyEnv: "OPENAI_API_KEY",
+        keyHeader: "Authorization",
+        defaultModel: "gpt-4o-mini",
+        basePath: "/openai",
+    },
+    gemini: {
+        label: "Google Gemini",
+        keyEnv: "GOOGLE_API_KEY",
+        keyHeader: "x-goog-api-key",
+        defaultModel: "gemini-2.0-flash",
+        basePath: "/gemini",
+    },
+};
+export async function wrapCommand(options = {}) {
+    const json = !!options.json;
+    const nonInteractive = !!options.yes || json || !isInteractive();
+    const steps = [];
+    const say = (line = "") => {
+        if (!json)
+            console.log(line);
+    };
+    say(fmt.header("Mnemom — wrap"));
+    say();
+    say(fmt.dim("Instrument your existing agent through the Mnemom gateway."));
+    say();
+    // Phase 1 — Resolve + Auth (Mnemom session for card writes)
+    await requireAuth();
+    const gatewayUrl = getGatewayUrl().replace(/\/$/, "");
+    const provider = await resolveProvider(options, nonInteractive);
+    const framework = await resolveFramework(options, nonInteractive);
+    const agentName = await resolveAgentName(options, nonInteractive);
+    const providerKey = await resolveProviderKey(options, PROVIDERS[provider], nonInteractive, say);
+    steps.push({
+        step: "resolve",
+        status: "ok",
+        detail: `provider=${provider} framework=${framework} name=${agentName}`,
+    });
+    // Phase 2 — Birth: one gateway call to provision the identity
+    say();
+    say(`${fmt.badge("birth", "cyan")} Provisioning ${fmt.badge(agentName, "magenta")} through the gateway…`);
+    let agentId;
+    try {
+        agentId = await birthThroughGateway(gatewayUrl, provider, agentName, providerKey);
+        steps.push({ step: "birth", status: "ok", detail: agentId });
+        say(fmt.success(`Provisioned → ${agentId}`));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "birth", status: "error", detail: msg });
+        if (json) {
+            console.log(JSON.stringify({
+                skill: "wrap",
+                verdict: "error",
+                agent_id: null,
+                gateway_base_url: gatewayUrl,
+                next_step: null,
+                steps,
+            }, null, 2));
+        }
+        throw new Error(`Gateway birth failed: ${msg}`, { cause: err });
+    }
+    mergeAgentConfig({ agent_id: agentId, agent_name: agentName, gateway_url: gatewayUrl });
+    // Phase 2 — Seed alignment card
+    say();
+    say(`${fmt.badge("alignment", "cyan")} Seeding starter alignment card…`);
+    try {
+        await putAlignmentCard(agentId, JSON.stringify(buildStarterAlignmentCard(agentId)), "application/json");
+        steps.push({ step: "alignment", status: "ok" });
+        say(fmt.success("Alignment card set."));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "alignment", status: "error", detail: msg });
+        say(fmt.warn(`Alignment card skipped — set it later with \`mnemom card publish\`. (${msg})`));
+    }
+    // Phase 2 — Seed protection card
+    say();
+    say(`${fmt.badge("protection", "cyan")} Seeding starter protection card…`);
+    try {
+        await putProtectionCard(agentId, JSON.stringify(buildStarterProtectionCard(agentId)), "application/json");
+        steps.push({ step: "protection", status: "ok" });
+        say(fmt.success("Protection card set."));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "protection", status: "error", detail: msg });
+        say(fmt.warn(`Protection card skipped — set it later with \`mnemom protection publish\`. (${msg})`));
+    }
+    // Phase 3 — Report
+    say();
+    say(renderCodeExample(framework, provider, gatewayUrl, agentName));
+    say();
+    say(renderClaimInstructions(agentId));
+    if (json) {
+        console.log(JSON.stringify({
+            skill: "wrap",
+            verdict: "ok",
+            agent_id: agentId,
+            gateway_base_url: gatewayUrl,
+            next_step: "claim",
+            steps,
+        }, null, 2));
+    }
+}
+// ── Phase 1 resolvers ─────────────────────────────────────────────────────────
+async function resolveProvider(options, nonInteractive) {
+    if (options.provider) {
+        const p = options.provider.toLowerCase();
+        if (!PROVIDERS[p]) {
+            throw new Error(`Unknown provider "${options.provider}". Choose: anthropic, openai, gemini`);
+        }
+        return p;
+    }
+    if (nonInteractive)
+        return "anthropic";
+    const choice = await askSelect("Which AI provider does your agent use?", [
+        "Anthropic (Claude)",
+        "OpenAI (GPT)",
+        "Google Gemini",
+    ]);
+    if (choice?.startsWith("OpenAI"))
+        return "openai";
+    if (choice?.startsWith("Google"))
+        return "gemini";
+    return "anthropic";
+}
+async function resolveFramework(options, nonInteractive) {
+    if (options.framework) {
+        const f = options.framework.toLowerCase();
+        if (f === "python" || f === "py")
+            return "python";
+        if (f === "node" || f === "nodejs" || f === "js" || f === "ts" || f === "typescript")
+            return "node";
+        throw new Error(`Unknown framework "${options.framework}". Choose: python, node`);
+    }
+    if (nonInteractive)
+        return "python";
+    const choice = await askSelect("Which language/framework is your agent using?", [
+        "Python",
+        "Node.js / TypeScript",
+    ]);
+    return choice?.startsWith("Node") ? "node" : "python";
+}
+async function resolveAgentName(options, nonInteractive) {
+    if (options.name?.trim())
+        return options.name.trim();
+    if (nonInteractive)
+        return "my-agent";
+    const name = (await askInput("What should we call this agent? (x-mnemom-agent value)")).trim();
+    return name || "my-agent";
+}
+async function resolveProviderKey(options, prov, nonInteractive, say) {
+    if (options.providerKey?.trim())
+        return options.providerKey.trim();
+    const fromEnv = process.env[prov.keyEnv]?.trim();
+    if (fromEnv) {
+        say(fmt.dim(`Using ${prov.keyEnv} from environment.`));
+        return fromEnv;
+    }
+    if (nonInteractive) {
+        throw new Error(`No ${prov.label} API key found. Set ${prov.keyEnv} or pass --provider-key <key>.`);
+    }
+    const key = (await askInput(`Enter your ${prov.label} API key (one-time birth call — never stored):`)).trim();
+    if (!key)
+        throw new Error(`A ${prov.label} API key is required to birth the agent.`);
+    return key;
+}
+// ── Birth call ────────────────────────────────────────────────────────────────
+export async function birthThroughGateway(gatewayUrl, provider, agentName, providerKey) {
+    const prov = PROVIDERS[provider];
+    const authValue = provider === "openai" ? `Bearer ${providerKey}` : providerKey;
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        [prov.keyHeader]: authValue,
+        [AGENT_HEADER]: agentName,
+    };
+    if (provider === "anthropic") {
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    let url;
+    let body;
+    switch (provider) {
+        case "openai":
+            url = `${gatewayUrl}${prov.basePath}/v1/chat/completions`;
+            body = JSON.stringify({
+                model: prov.defaultModel,
+                max_tokens: 16,
+                messages: [{ role: "user", content: "hello" }],
+            });
+            break;
+        case "gemini":
+            url = `${gatewayUrl}${prov.basePath}/v1beta/models/${prov.defaultModel}:generateContent`;
+            body = JSON.stringify({ contents: [{ parts: [{ text: "hello" }] }] });
+            break;
+        case "anthropic":
+        default:
+            url = `${gatewayUrl}${prov.basePath}/v1/messages`;
+            body = JSON.stringify({
+                model: prov.defaultModel,
+                max_tokens: 16,
+                messages: [{ role: "user", content: "hello" }],
+            });
+    }
+    const response = await fetch(url, { method: "POST", headers, body });
+    const agentId = response.headers.get(AGENT_HEADER);
+    if (!response.ok && !agentId) {
+        const text = await response.text().catch(() => "");
+        throw new MnemomApiError(response.status, `Gateway returned ${response.status}: ${text.slice(0, 300)}`);
+    }
+    if (!agentId || !/^mnm-/.test(agentId)) {
+        throw new Error(`Gateway returned no mnm- agent id on the ${AGENT_HEADER} response header (status ${response.status}).`);
+    }
+    return agentId;
+}
+// ── Starter cards ─────────────────────────────────────────────────────────────
+function buildStarterAlignmentCard(agentId) {
+    return {
+        card_version: "unified/2026-04-26",
+        agent_id: agentId,
+        autonomy_mode: "observe",
+        integrity_mode: "observe",
+        principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
+        values: { declared: ["transparency", "safety", "honesty"] },
+        autonomy: {
+            bounded_actions: ["respond_to_prompts"],
+            forbidden_actions: [],
+            escalation_triggers: [],
+        },
+        audit: { retention_days: 30, queryable: false, trace_format: "otel" },
+    };
+}
+function buildStarterProtectionCard(agentId) {
+    return {
+        card_version: "protection/2026-04-26",
+        agent_id: agentId,
+        mode: "observe",
+        thresholds: { warn: 0.3, quarantine: 0.6, block: 0.9 },
+        screen_surfaces: {
+            incoming: true,
+            outgoing: true,
+            tool_calls: true,
+            tool_responses: true,
+        },
+        trusted_sources: { domains: [], agent_ids: [], ip_ranges: [] },
+    };
+}
+// ── Code example rendering ────────────────────────────────────────────────────
+function renderCodeExample(framework, provider, gatewayUrl, agentName) {
+    const prov = PROVIDERS[provider];
+    const lines = [fmt.section("Drop-in gateway wrapper"), ""];
+    if (framework === "python") {
+        renderPythonSnippet(lines, provider, prov, gatewayUrl, agentName);
+    }
+    else {
+        renderNodeSnippet(lines, provider, prov, gatewayUrl, agentName);
+    }
+    lines.push("", fmt.dim("No other changes needed — your agent logic is unchanged."));
+    return lines.join("\n");
+}
+function renderPythonSnippet(lines, provider, prov, gatewayUrl, agentName) {
+    const base = `${gatewayUrl}${prov.basePath}`;
+    if (provider === "anthropic") {
+        lines.push("  import anthropic", "", "  client = anthropic.Anthropic(", `      base_url="${base}",`, `      default_headers={"x-mnemom-agent": "${agentName}"},`, "  )");
+    }
+    else if (provider === "openai") {
+        lines.push("  from openai import OpenAI", "", "  client = OpenAI(", `      base_url="${base}/v1",`, `      default_headers={"x-mnemom-agent": "${agentName}"},`, "  )");
+    }
+    else {
+        lines.push("  # Google Gemini via Mnemom gateway", `  # Set base URL to: ${base}`, `  # Add header: x-mnemom-agent: ${agentName}`);
+    }
+}
+function renderNodeSnippet(lines, provider, prov, gatewayUrl, agentName) {
+    const base = `${gatewayUrl}${prov.basePath}`;
+    if (provider === "anthropic") {
+        lines.push('  import Anthropic from "@anthropic-ai/sdk";', "", "  const client = new Anthropic({", `    baseURL: "${base}",`, `    defaultHeaders: { "x-mnemom-agent": "${agentName}" },`, "  });");
+    }
+    else if (provider === "openai") {
+        lines.push('  import OpenAI from "openai";', "", "  const client = new OpenAI({", `    baseURL: "${base}/v1",`, `    defaultHeaders: { "x-mnemom-agent": "${agentName}" },`, "  });");
+    }
+    else {
+        lines.push("  // Google Gemini via Mnemom gateway", `  // Set base URL to: ${base}`, `  // Add header: "x-mnemom-agent": "${agentName}"`);
+    }
+}
+function renderClaimInstructions(agentId) {
+    const lines = [
+        fmt.section("Next step — claim this agent"),
+        "",
+        fmt.label("  Agent ID:", agentId),
+        "",
+        fmt.dim("  Claim this agent so you own its identity on the platform:"),
+        "",
+        `    mnemom agents claim ${agentId}`,
+        "",
+        fmt.dim("  After claiming, traces appear in `mnemom logs`."),
+    ];
+    return lines.join("\n");
+}