z0gcode 0.2.0

package/src/client.mjs

@@ -0,0 +1,134 @@
+// Robust client for the 0G Compute Router.
+// The Router is OpenAI-compatible but does NOT switch models on 503, so we add
+// app-level multi-model fallback, retry/backoff, and empty-response handling.
+import OpenAI from "openai";
+import { CONFIG } from "./config.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function makeClient() {
+  if (!CONFIG.apiKey) {
+    throw new Error("Missing ZOG_API_KEY. Get a 0G Router key at https://pc.0g.ai, then export it, put it in a project .env, or in ~/.z0gcode/.env to use it from anywhere.");
+  }
+  return new OpenAI({ baseURL: CONFIG.baseURL, apiKey: CONFIG.apiKey });
+}
+
+// Try each model in order; retry a model on 503/429; move on to the next on hard error.
+// Returns { message, model, usage, responseId, systemFingerprint }. Throws only if every model fails.
+export async function complete(client, { models, messages, tools, effort }) {
+  let lastErr;
+  for (const model of models) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const body = {
+          model,
+          messages,
+          tools,
+          tool_choice: "auto",
+          max_tokens: CONFIG.maxTokens,
+          temperature: CONFIG.temperature,
+        };
+        if (effort) body.reasoning_effort = effort;
+        const res = await client.chat.completions.create(body);
+        const message = res.choices?.[0]?.message;
+        if (!message) throw new Error("empty response");
+        // A turn with neither content nor tool calls is unusable: treat as failure.
+        const hasContent = (message.content || "").trim().length > 0;
+        const hasTools = Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+        if (!hasContent && !hasTools) throw new Error("no content and no tool calls");
+        return {
+          message,
+          model,
+          usage: res.usage || null,
+          responseId: res.id || null,
+          systemFingerprint: res.system_fingerprint || null,
+          trace: res.x_0g_trace || null,
+        };
+      } catch (e) {
+        lastErr = e;
+        const status = e?.status;
+        if (status === 503) {
+          await sleep(400 * (attempt + 1));
+          continue; // retry same model: providers may recover
+        }
+        if (status === 429) {
+          await sleep(800 * (attempt + 1));
+          continue;
+        }
+        break; // 400/auth/other: this model won't work, try the next
+      }
+    }
+  }
+  throw lastErr || new Error("all models failed");
+}
+
+// Streaming variant: calls onDelta(text) for content as it arrives and assembles
+// tool calls from streamed fragments. Same fallback/retry as complete().
+export async function completeStream(client, { models, messages, tools, onDelta, effort }) {
+  let lastErr;
+  for (const model of models) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const body = {
+          model,
+          messages,
+          tools,
+          tool_choice: "auto",
+          max_tokens: CONFIG.maxTokens,
+          temperature: CONFIG.temperature,
+          stream: true,
+          stream_options: { include_usage: true },
+        };
+        if (effort) body.reasoning_effort = effort;
+        const stream = await client.chat.completions.create(body);
+        let content = "";
+        const acc = [];
+        let usage = null;
+        let responseId = null;
+        let trace = null;
+        for await (const chunk of stream) {
+          if (chunk.id) responseId = responseId || chunk.id;
+          if (chunk.usage) usage = chunk.usage;
+          if (chunk.x_0g_trace) trace = chunk.x_0g_trace; // 0G TEE trace: provider node + request id
+
+          const delta = chunk.choices?.[0]?.delta;
+          if (!delta) continue;
+          if (delta.content) {
+            content += delta.content;
+            if (onDelta) onDelta(delta.content);
+          }
+          if (Array.isArray(delta.tool_calls)) {
+            for (const tcd of delta.tool_calls) {
+              const i = tcd.index ?? 0;
+              if (!acc[i]) acc[i] = { id: "", type: "function", function: { name: "", arguments: "" } };
+              if (tcd.id) acc[i].id = tcd.id;
+              if (tcd.function?.name) acc[i].function.name = tcd.function.name;
+              if (tcd.function?.arguments) acc[i].function.arguments += tcd.function.arguments;
+            }
+          }
+        }
+        const toolCalls = acc
+          .filter(Boolean)
+          .map((t, i) => ({ ...t, id: t.id || `call_${responseId || "s"}_${i}` }));
+        const hasContent = content.trim().length > 0;
+        if (!hasContent && toolCalls.length === 0) throw new Error("empty stream");
+        const message = { role: "assistant", content: content || null };
+        if (toolCalls.length) message.tool_calls = toolCalls;
+        return { message, model, usage, responseId, trace };
+      } catch (e) {
+        lastErr = e;
+        const status = e?.status;
+        if (status === 503) {
+          await sleep(400 * (attempt + 1));
+          continue;
+        }
+        if (status === 429) {
+          await sleep(800 * (attempt + 1));
+          continue;
+        }
+        break;
+      }
+    }
+  }
+  throw lastErr || new Error("all models failed");
+}

package/src/commands.mjs

@@ -0,0 +1,93 @@
+// Custom slash commands and lifecycle hooks, both project-local under .z0g/.
+//
+// Commands: .z0g/commands/<name>.md -> /<name>. The file body is a prompt
+// template; "$ARGUMENTS" (or {{args}}) is replaced with whatever follows the
+// command, otherwise the args are appended. Optional frontmatter: description.
+//
+// Hooks: .z0g/hooks.json maps an event (preRun, postRun) to a shell command or
+// a list of them. Hooks run shell, so they only fire with --auto.
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { exec } from "node:child_process";
+import * as ui from "./ui.mjs";
+
+const CMD_DIR = (cwd) => path.join(cwd, ".z0g", "commands");
+
+// Parse optional --- frontmatter, returning { meta, body }.
+function parseFrontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  if (!m) return { meta: {}, body: text };
+  const meta = {};
+  for (const line of m[1].split("\n")) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+    if (kv) meta[kv[1].toLowerCase()] = kv[2].trim();
+  }
+  return { meta, body: text.slice(m[0].length) };
+}
+
+export function loadCustomCommands(cwd) {
+  const dir = CMD_DIR(cwd);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => f.endsWith(".md")); } catch { return []; }
+  for (const f of files) {
+    try {
+      const { meta, body } = parseFrontmatter(readFileSync(path.join(dir, f), "utf8"));
+      const name = f.replace(/\.md$/, "").toLowerCase();
+      if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) continue;
+      out.push({ name, description: meta.description || "custom command", template: body.trim(), file: path.join(dir, f) });
+    } catch { /* skip unreadable */ }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function expandTemplate(template, args) {
+  const a = (args || "").trim();
+  if (/\$ARGUMENTS|\{\{\s*args\s*\}\}/.test(template)) {
+    return template.replace(/\$ARGUMENTS|\{\{\s*args\s*\}\}/g, a);
+  }
+  return a ? template + "\n\n" + a : template;
+}
+
+// ---- hooks ----------------------------------------------------------------
+const HOOK_EVENTS = ["preRun", "postRun"];
+
+export function loadHooks(cwd) {
+  const file = path.join(cwd, ".z0g", "hooks.json");
+  if (!existsSync(file)) return {};
+  let raw;
+  try { raw = JSON.parse(readFileSync(file, "utf8")); } catch { return {}; }
+  const hooks = {};
+  for (const ev of HOOK_EVENTS) {
+    const v = raw[ev];
+    if (!v) continue;
+    hooks[ev] = (Array.isArray(v) ? v : [v]).map(String).filter(Boolean);
+  }
+  return hooks;
+}
+
+export function hasHooks(hooks) {
+  return HOOK_EVENTS.some((e) => hooks[e] && hooks[e].length);
+}
+
+const run1 = (cmd, cwd) => new Promise((resolve) => {
+  exec(cmd, { cwd, timeout: 120000, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+    resolve({ code: err?.code ?? 0, out: (stdout || "") + (stderr || "") });
+  });
+});
+
+// Run the shell commands for an event. Only fires with allowBash (--auto).
+export async function runHooks(cwd, event, hooks, allowBash, taskText) {
+  const cmds = hooks?.[event];
+  if (!cmds || !cmds.length) return;
+  if (!allowBash) return; // hooks run shell; require --auto
+  for (const cmd of cmds) {
+    const expanded = cmd.replace(/\$TASK/g, () => (taskText || "").replace(/"/g, '\\"'));
+    console.log(ui.muted("  " + ui.GLYPH.point + " hook " + event + ": ") + ui.muted(cmd));
+    const { code, out } = await run1(expanded, cwd);
+    const text = out.trim();
+    if (text) console.log(text.split("\n").map((l) => "    " + ui.muted(l)).join("\n"));
+    if (code !== 0) console.log("    " + ui.warn("hook exited " + code));
+  }
+}

package/src/config.mjs

@@ -0,0 +1,74 @@
+// z0gcode configuration. 0G is baked in as the default backend.
+// Everything can be overridden by env vars, but nothing needs to be.
+import { loadSettings } from "./settings.mjs";
+
+function envList(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  return v.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+// User's saved preferences (e.g. a model picked with /model). Env still wins.
+const settings = loadSettings(process.cwd());
+
+// Reasoning effort: low | medium | high, or null (unset -> model default).
+export const EFFORT_LEVELS = ["low", "medium", "high"];
+export function normEffort(v) {
+  const s = String(v || "").toLowerCase().trim();
+  return EFFORT_LEVELS.includes(s) ? s : null;
+}
+
+// Parse a boolean-ish value: booleans pass through; off/false/0/no -> false,
+// anything else truthy -> true; undefined/null -> undefined (not set).
+export function boolOf(v) {
+  if (v === undefined || v === null || v === "") return undefined;
+  if (typeof v === "boolean") return v;
+  return !/^(off|false|0|no)$/i.test(String(v).trim());
+}
+
+export const CONFIG = {
+  // 0G Compute Router (OpenAI-compatible). Mainnet by default.
+  baseURL: process.env.ZOG_BASE_URL || "https://router-api.0g.ai/v1",
+  apiKey: process.env.ZOG_API_KEY || "",
+
+  // Default model: 0G's own in-house coding model (private + verifiable, TEE).
+  // Precedence: ZOG_MODEL env > saved setting (/model) > built-in default.
+  model: process.env.ZOG_MODEL || settings.model || "0gm-1.0-35b-a3b",
+  // App-level fallbacks: the Router does NOT switch models on 503, so we do.
+  fallbacks: envList("ZOG_FALLBACKS", ["deepseek-v4-pro", "glm-5.2", "kimi-k2.7-code"]),
+
+  maxSteps: Number(process.env.ZOG_MAX_STEPS || 30),
+  maxTokens: Number(process.env.ZOG_MAX_TOKENS || 16384),
+  temperature: Number(process.env.ZOG_TEMPERATURE || 0.2),
+
+  // Reasoning effort passed to the Router as reasoning_effort. Null = unset.
+  effort: normEffort(process.env.ZOG_EFFORT || settings.effort),
+
+  // Max subagents running at once (spawn_subagents fan-out).
+  maxParallel: Math.max(1, Number(process.env.ZOG_MAX_PARALLEL || 4)),
+
+  // Whether the spawn_subagents tool is offered. env > settings > on.
+  subagents: (() => {
+    const e = boolOf(process.env.ZOG_SUBAGENTS);
+    if (e !== undefined) return e;
+    return typeof settings.subagents === "boolean" ? settings.subagents : true;
+  })(),
+
+  // Media models on the 0G Router (image generation, transcription).
+  imageModel: process.env.ZOG_IMAGE_MODEL || "z-image-turbo",
+  transcribeModel: process.env.ZOG_TRANSCRIBE_MODEL || "whisper-large-v3",
+
+  // On-chain actions (0G Storage upload, 0G Chain deploy, session anchor) spend
+  // gas, so they are OFF by default. env > settings > off.
+  onchain: (() => {
+    const e = boolOf(process.env.ZOG_ONCHAIN);
+    if (e !== undefined) return e;
+    return typeof settings.onchain === "boolean" ? settings.onchain : false;
+  })(),
+};
+
+export function modelChain(preferred) {
+  const primary = preferred || CONFIG.model;
+  const chain = [primary, ...CONFIG.fallbacks.filter((m) => m !== primary)];
+  return chain;
+}

package/src/context.mjs

@@ -0,0 +1,55 @@
+// Project context: auto-loaded guidance the agent should always follow.
+// Looks for AGENTS.md (the emerging standard) and .z0g/context.md in the
+// working directory, and injects them into the system prompt.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const CANDIDATES = ["AGENTS.md", ".z0g/context.md"];
+const MAX_CONTEXT = 8000; // keep the injected block small
+
+// Return [{ source, text }] for each context file found (may be empty).
+export function loadProjectContext(cwd) {
+  const found = [];
+  let budget = MAX_CONTEXT;
+  for (const rel of CANDIDATES) {
+    if (budget <= 0) break;
+    try {
+      let text = readFileSync(path.join(cwd, rel), "utf8").trim();
+      if (!text) continue;
+      if (text.length > budget) text = text.slice(0, budget) + "\n… [truncated]";
+      budget -= text.length;
+      found.push({ source: rel, text });
+    } catch { /* not present */ }
+  }
+  return found;
+}
+
+// A system-prompt block describing the project context, or "" if none.
+export function contextPromptBlock(cwd) {
+  const found = loadProjectContext(cwd);
+  if (!found.length) return "";
+  const parts = found.map((f) => "----- " + f.source + " -----\n" + f.text);
+  return [
+    "## Project context",
+    "This project ships contributor guidance below. Treat it as authoritative:",
+    "follow its conventions, use its build/test/run commands, and respect its constraints.",
+    "",
+    parts.join("\n\n"),
+  ].join("\n");
+}
+
+// The task the agent runs for `z0g init` / `/init` to author an AGENTS.md.
+export const INIT_TASK = [
+  "Analyze THIS project and write a concise AGENTS.md at the repository root, so future agents and contributors have the context they need.",
+  "",
+  "Investigate first (do not guess): use list_dir on the root and key folders, read package.json / pyproject.toml / go.mod / Cargo.toml / any config, read the README if present, and search_files for scripts, test setup, and entry points.",
+  "",
+  "AGENTS.md MUST contain, as short markdown sections:",
+  "1. Overview: one paragraph on what the project is and does.",
+  "2. Stack: languages, frameworks, key dependencies.",
+  "3. Commands: exact install, build, run, and test commands you actually found (do NOT invent them; if a command is missing, say so).",
+  "4. Layout: the important directories and what lives in each.",
+  "5. Conventions: anything a contributor must follow (style, patterns, gotchas) that you can infer from the code.",
+  "",
+  "Keep it under ~150 lines and specific to this repo. Create it with write_file at path 'AGENTS.md'. When done, reply with a one-line summary.",
+].join("\n");

package/src/crypto.mjs

@@ -0,0 +1,47 @@
+// Client-side encryption for session bundles before they go to 0G Storage.
+// 0G Storage is public, so we encrypt with a key derived from the user's wallet
+// private key: the content root can be public (anchored on-chain, in the INFT)
+// while only that wallet can decrypt. AES-256-GCM (authenticated), no deps.
+import crypto from "node:crypto";
+
+const INFO = Buffer.from("z0gcode-session-v1");
+
+function deriveKey(privKeyHex, salt) {
+  const pk = Buffer.from(String(privKeyHex).replace(/^0x/, ""), "hex");
+  return Buffer.from(crypto.hkdfSync("sha256", pk, salt, INFO, 32));
+}
+
+// Encrypt a Buffer, returning a self-describing JSON envelope Buffer.
+export function encryptEnvelope(plaintext, privKeyHex) {
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = deriveKey(privKeyHex, salt);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.from(JSON.stringify({
+    tool: "z0gcode", enc: "AES-256-GCM", kdf: "hkdf-sha256(wallet)", v: 1,
+    salt: salt.toString("base64"), iv: iv.toString("base64"),
+    tag: tag.toString("base64"), ct: ct.toString("base64"),
+  }));
+}
+
+// Decrypt an envelope Buffer with the wallet key. Throws if the key is wrong
+// (a different wallet) or the data was tampered with.
+export function decryptEnvelope(envelopeBuf, privKeyHex) {
+  let e;
+  try { e = JSON.parse(envelopeBuf.toString("utf8")); } catch { throw new Error("not an encrypted z0gcode bundle"); }
+  if (!e || e.enc !== "AES-256-GCM" || !e.salt || !e.iv || !e.tag || !e.ct) throw new Error("not an encrypted z0gcode bundle");
+  const key = deriveKey(privKeyHex, Buffer.from(e.salt, "base64"));
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(e.iv, "base64"));
+  decipher.setAuthTag(Buffer.from(e.tag, "base64"));
+  try {
+    return Buffer.concat([decipher.update(Buffer.from(e.ct, "base64")), decipher.final()]);
+  } catch {
+    throw new Error("decryption failed: this session was encrypted for a different wallet");
+  }
+}
+
+export function isEncryptedEnvelope(buf) {
+  try { const e = JSON.parse(buf.toString("utf8")); return e && e.enc === "AES-256-GCM"; } catch { return false; }
+}

package/src/env.mjs

@@ -0,0 +1,47 @@
+// Load .env into process.env BEFORE anything reads config. Imported first in
+// bin/z0g.mjs so config.mjs sees the vars. Dependency-free; never overrides a
+// variable already set in the real environment.
+//
+// Lookup order (first found wins per variable, real env always wins):
+//   1. the nearest .env walking up from the current directory (project-local),
+//      so `z0g` works from any subfolder of a project, not just its root.
+//   2. ~/.z0gcode/.env (global), so a key set once works from anywhere.
+import { readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+function loadEnvFile(file) {
+  if (!file || !existsSync(file)) return;
+  try {
+    for (const raw of readFileSync(file, "utf8").split("\n")) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq === -1) continue;
+      const keyPart = line.slice(0, eq).replace(/^export\s+/, "").trim();
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(keyPart)) continue;
+      let val = line.slice(eq + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      if (process.env[keyPart] === undefined) process.env[keyPart] = val;
+    }
+  } catch {
+    // ignore a malformed .env
+  }
+}
+
+// Nearest .env walking up from `dir` to the filesystem root.
+function nearestEnv(dir) {
+  let cur = path.resolve(dir);
+  for (;;) {
+    const f = path.join(cur, ".env");
+    if (existsSync(f)) return f;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+loadEnvFile(nearestEnv(process.cwd()));                       // project-local (any ancestor)
+loadEnvFile(path.join(os.homedir(), ".z0gcode", ".env"));    // global fallback

package/src/goal.mjs

@@ -0,0 +1,45 @@
+// Goal loop: run an objective, then a verify command; on failure feed the output
+// back and re-run, until it passes or the iteration budget is spent.
+import { exec } from "node:child_process";
+import { runAgent } from "./agent.mjs";
+import { saveMessages } from "./sessions.mjs";
+import * as ui from "./ui.mjs";
+
+function runCmd(cmd, cwd) {
+  return new Promise((resolve) => {
+    exec(cmd, { cwd, timeout: 300_000, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+      resolve({ code, out: `${stdout || ""}${stderr || ""}` });
+    });
+  });
+}
+
+export async function runGoal({ client, objective, cwd, sessionId, sessionDir, allowBash, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, verifyCmd, maxIters = 3, history: historyParam = null }) {
+  let history = historyParam ?? null;
+  let task = objective;
+  for (let iter = 1; iter <= maxIters; iter++) {
+    console.log(ui.section("Goal", "iteration " + iter + "/" + maxIters));
+    const res = await runAgent({ client, task, cwd, sessionDir, allowBash, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, history });
+    history = res.messages;
+    if (sessionId && Array.isArray(history)) {
+      try { await saveMessages(cwd, sessionId, history); } catch {}
+    }
+
+    if (!verifyCmd) {
+      ui.info("  no verify command configured; done after one pass.");
+      return { ok: !!res.ok, iters: iter };
+    }
+
+    console.log("  " + ui.muted("verify: " + verifyCmd));
+    const v = await runCmd(verifyCmd, cwd);
+    if (v.code === 0) {
+      console.log("  " + ui.ok(ui.GLYPH.ok + " passed on iteration " + iter));
+      console.log("  " + ui.ok(ui.GLYPH.ok) + "  " + ui.strong("Goal met in " + iter + " iteration" + (iter > 1 ? "s" : "") + "."));
+      return { ok: true, iters: iter };
+    }
+    console.log("  " + ui.warn(ui.GLYPH.no + " failed (exit " + v.code + ") · feeding output back"));
+    task = `The verification command \`${verifyCmd}\` failed with output:\n\n${v.out.slice(0, 4000)}\n\nFix the code so this command passes, then stop.`;
+  }
+  console.log("  " + ui.err(ui.GLYPH.no) + "  " + ui.strong("Goal not met after " + maxIters + " iterations."));
+  return { ok: false, iters: maxIters };
+}

package/src/inft.mjs

@@ -0,0 +1,79 @@
+// Mint a verifiable z0gcode session as an NFT on 0G Chain. Each token records
+// the 0G Storage content root of the session bundle, so an AI work session
+// becomes an ownable, provable asset. ERC-721 based, ERC-7857-inspired.
+// Needs a funded ZOG_WALLET_KEY and on-chain enabled.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import path from "node:path";
+
+const rpc = () => process.env.ZOG_EVM_RPC || "https://evmrpc.0g.ai";
+
+function requireKey() {
+  const key = process.env.ZOG_WALLET_KEY;
+  if (!key) throw new Error("Set ZOG_WALLET_KEY to a funded 0G mainnet private key.");
+  return key;
+}
+
+function artifact() {
+  const p = new URL("../contracts/Z0gSession.json", import.meta.url);
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+const registryPath = (cwd) => path.join(cwd, ".z0g", "inft.json");
+
+function loadRegistry(cwd) {
+  try { return JSON.parse(readFileSync(registryPath(cwd), "utf8")); } catch { return {}; }
+}
+
+// Return the deployed contract address for this chain, deploying it once and
+// caching it in .z0g/inft.json if needed. Returns { address, chainId, deployed }.
+export async function deployOrLoad(cwd) {
+  const key = requireKey();
+  const { ethers } = await import("ethers");
+  const provider = new ethers.JsonRpcProvider(rpc());
+  const wallet = new ethers.Wallet(key, provider);
+  const chainId = Number((await provider.getNetwork()).chainId);
+
+  const reg = loadRegistry(cwd);
+  if (reg.address && reg.chainId === chainId) {
+    // Confirm code is present at the cached address; redeploy if not.
+    const code = await provider.getCode(reg.address);
+    if (code && code !== "0x") return { address: reg.address, chainId, deployed: false };
+  }
+
+  const art = artifact();
+  const factory = new ethers.ContractFactory(art.abi, art.bytecode, wallet);
+  const contract = await factory.deploy();
+  await contract.waitForDeployment();
+  const address = await contract.getAddress();
+  const deployTx = contract.deploymentTransaction()?.hash || null;
+  writeFileSync(registryPath(cwd), JSON.stringify({ address, chainId, deployTx, contract: art.contractName }, null, 2) + "\n");
+  return { address, chainId, deployed: true, deployTx };
+}
+
+// Mint a session token. Returns { contract, tokenId, txHash, block, deployed, deployTx }.
+export async function mintSession(cwd, { root, uri, to }) {
+  const key = requireKey();
+  const { ethers } = await import("ethers");
+  const { address, deployed, deployTx } = await deployOrLoad(cwd);
+  const provider = new ethers.JsonRpcProvider(rpc());
+  const wallet = new ethers.Wallet(key, provider);
+  const art = artifact();
+  const c = new ethers.Contract(address, art.abi, wallet);
+  const owner = to || wallet.address;
+  const tx = await c.mint(owner, root, uri || "");
+  const receipt = await tx.wait();
+
+  let tokenId = null;
+  const iface = new ethers.Interface(art.abi);
+  for (const log of receipt.logs || []) {
+    try {
+      const parsed = iface.parseLog(log);
+      if (parsed && parsed.name === "Minted") { tokenId = parsed.args.tokenId.toString(); break; }
+    } catch { /* not our event */ }
+  }
+  return { contract: address, tokenId, txHash: tx.hash, block: receipt?.blockNumber, owner, deployed, deployTx };
+}
+
+export function inftRegistry(cwd) {
+  return existsSync(registryPath(cwd)) ? loadRegistry(cwd) : null;
+}

package/src/mcp-server.mjs

@@ -0,0 +1,38 @@
+// MCP server mode: expose z0gcode's 0G tools so other agents (Claude Code, Cursor,
+// another z0gcode) can use them. Stdio transport, so nothing may be written to
+// stdout except the MCP protocol; logs go to stderr.
+import { TOOL_DEFS, makeExecutor } from "./tools.mjs";
+
+// The 0G-native tools worth exposing to other agents.
+const EXPOSE = new Set(["read_skill", "upload_0g_storage"]);
+
+export async function startMcpServer({ cwd, allowBash }) {
+  const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
+
+  const exposed = TOOL_DEFS.filter((t) => EXPOSE.has(t.function.name));
+  const execute = makeExecutor({ cwd, allowBash });
+
+  const server = new Server({ name: "z0gcode", version: "0.2.0" }, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: exposed.map((t) => ({
+      name: t.function.name,
+      description: t.function.description,
+      inputSchema: t.function.parameters,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    if (!EXPOSE.has(name)) {
+      return { content: [{ type: "text", text: `tool ${name} is not exposed` }], isError: true };
+    }
+    const res = await execute(name, args || {});
+    return { content: [{ type: "text", text: String(res.content ?? (res.ok ? "OK" : "ERROR")) }], isError: !res.ok };
+  });
+
+  await server.connect(new StdioServerTransport());
+  process.stderr.write(`z0gcode MCP server ready (tools: ${exposed.map((t) => t.function.name).join(", ")})\n`);
+}