mycomesh-consumer 0.2.1 → 0.3.0

package/networks/mycomesh-v11-sepolia.json

@@ -5,6 +5,7 @@
   "settlement": "0xd46b7efb1e650e83cdeb4a36fdfef33499e54842",
   "stablecoin": "0xbce27efad4191277167fe76819581a97959048cf",
   "registry": "0x0ff3210e8e8abf5f5bfa73a39e60db7416b6c8c7",
+  "relay_directory": "0xa0aaad9393f51cb5786c69f152133a174588bdab",
   "deployment_block": 11809185,
   "rpc_urls": [
     "https://ethereum-sepolia-rpc.publicnode.com",
@@ -12,6 +13,7 @@
     "https://sepolia.gateway.tenderly.co"
   ],
   "tls_ca_file": "mycomesh-testnet-ca.crt",
+  "faucet_url": "https://136.0.3.126:10443",
   "relays": [
     {
       "url": "https://136.0.3.126:10443",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mycomesh-consumer",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MycoMesh V11 Consumer: a custodied deposit, relay-blind encrypted requests to any Provider, and a local OpenAI-compatible endpoint.",
   "repository": {
     "type": "git",

package/src/cli.mjs

@@ -1,4 +1,4 @@
-// mycomesh-consumer (V11): init, setup, balance, request, serve.
+// mycomesh-consumer (V11): init, wallet, faucet, setup, balance, request, serve, dispute.
 import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -7,26 +7,32 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { addressOf, encodeCall, settlementKey } from "./eip712.mjs";
 import { availableBalance, rpcCall, sendTransaction } from "./chain.mjs";
-import { Consumer, httpJson, loadNetwork, serveConsumer } from "./consumer.mjs";
+import { Consumer, directoryRelays, httpJson, loadNetwork, serveConsumer } from "./consumer.mjs";
+import { createWallet, ownerAddress, ownerKey, walletAddress } from "./wallet.mjs";
 import { buildEvidence, evidenceHash, loadRequest, openDisputeCall, reportId } from "./disputes.mjs";
 
 const DEFAULT_NETWORK = join(dirname(fileURLToPath(import.meta.url)), "../networks/mycomesh-v11-sepolia.json");
 
 const USAGE = `Usage: mycomesh-consumer <command> [options]
 
-  init                     create the local payment key (never leaves this machine)
+  init                     create the local payment key and the password-protected owner wallet
   address                  print the payment key address
-  setup --owner-key-file F --deposit UNITS [--max-per-request UNITS] [--faucet UNITS]
+  wallet                   print the owner wallet address (a V3 keystore; MetaMask can import it)
+  faucet                   testnet: get gas ETH and tUSDC for the owner wallet
+  setup --deposit UNITS [--max-per-request UNITS]
                            deposit into the settlement contract and authorize the payment key
-                           (--faucet first mints testnet tUSDC to the owner)
+                           (on testnets, tops the wallet up from the faucet first)
   balance [--owner ADDR]   show the custodied deposit
-  request "prompt"         send one request and print the verified answer
-  serve [--port 8110]      run the local OpenAI-compatible endpoint (default)
-  dispute <settlement-key|last> --owner-key-file F [--reason CODE] [--statement TEXT]
+  request "prompt" [--stream]
+                           send one request and print the verified answer
+  serve [--port 8110]      run the local OpenAI-compatible endpoint with streaming (default)
+  dispute <settlement-key|last> [--reason CODE] [--statement TEXT]
                            reveal a recorded request and response to a Provider-AI jury
                            (within 24 hours; the reporter bond is returned if fraud is confirmed)
 
-Common: --network FILE (default: the bundled MycoMesh V11 Sepolia manifest), --data-dir DIR, --model ID, --max-fee UNITS, --provider SIGNER`;
+Common: --network FILE (default: the bundled MycoMesh V11 Sepolia manifest), --data-dir DIR, --model ID,
+  --max-fee UNITS, --provider SIGNER, --owner-key-file F (raw key or keystore instead of the local wallet).
+The wallet password comes from MYCOMESH_WALLET_PASSWORD or a terminal prompt.`;
 
 function dataDir(value) {
   const dir = value || process.env.MYCOMESH_CONSUMER_DATA_DIR || join(homedir(), ".mycomesh", "v11");
@@ -59,26 +65,55 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
       model: { type: "string", default: "gpt-5.5" }, "max-fee": { type: "string", default: "1000000" },
       port: { type: "string", default: "8110" }, host: { type: "string", default: "127.0.0.1" },
       "max-output-tokens": { type: "string", default: "4096" }, help: { type: "boolean" },
-      reason: { type: "string", default: "unrelated_response" }, faucet: { type: "string" }, provider: { type: "string" }, statement: { type: "string", default: "" },
+      reason: { type: "string", default: "unrelated_response" }, faucet: { type: "boolean" }, provider: { type: "string" },
+      statement: { type: "string", default: "" }, stream: { type: "boolean" },
     },
   });
   const [command = "serve", ...rest] = positionals;
   if (values.help || command === "help") { stdout.write(`${USAGE}\n`); return 0; }
   const dir = dataDir(values["data-dir"]);
-  if (command === "init" || command === "address") {
-    stdout.write(`${addressOf(paymentKey(dir, command === "init"))}\n`);
+  if (command === "address") {
+    stdout.write(`${addressOf(paymentKey(dir))}\n`);
+    return 0;
+  }
+  if (command === "init") {
+    stdout.write(`${addressOf(paymentKey(dir, true))}\n`);
+    if (!values["owner-key-file"]) {
+      stdout.write(`owner wallet ${walletAddress(await createWallet(dir))} (${join(dir, "owner-wallet.json")})\n`);
+    }
+    return 0;
+  }
+  if (command === "wallet") {
+    stdout.write(`${values["owner-key-file"] ? ownerAddress(values["owner-key-file"], dir) : walletAddress(await createWallet(dir))}\n`);
     return 0;
   }
   const network = loadNetwork(values.network || process.env.MYCOMESH_NETWORK || DEFAULT_NETWORK);
+  const faucet = async (address) => {
+    if (!network.faucet_url) throw new Error("this network has no faucet");
+    const reply = await httpJson(`${network.faucet_url}/v11/faucet`, { method: "POST", body: { address }, ca: network.tls_ca, timeoutMs: 400_000 });
+    if (reply.status !== 200) throw new Error(`faucet: ${reply.body?.error || reply.status}`);
+    return reply.body;
+  };
+  if (command === "faucet") {
+    const address = values.owner || ownerAddress(values["owner-key-file"], dir) || walletAddress(await createWallet(dir));
+    stdout.write(`${JSON.stringify(await faucet(address))}\n`);
+    return 0;
+  }
   if (command === "setup") {
     const keyPrivate = paymentKey(dir);
-    const owner = readKey(values["owner-key-file"]);
+    if (!values.deposit) throw new Error("--deposit UNITS is required");
+    if (!values["owner-key-file"]) await createWallet(dir);
+    const address = ownerAddress(values["owner-key-file"], dir);
     const deposit = BigInt(values.deposit);
     const limit = BigInt(values["max-per-request"] || values["max-fee"]);
-    if (values.faucet) {
-      await sendTransaction(network.rpc_urls, owner, { to: network.stablecoin,
-        data: encodeCall("mint(address,uint256)", [["address", addressOf(owner)], ["uint", BigInt(values.faucet)]]) });
+    const eth = BigInt(await rpcCall(network.rpc_urls, "eth_getBalance", [address, "latest"]));
+    const tokens = BigInt(await rpcCall(network.rpc_urls, "eth_call", [{ to: network.stablecoin,
+      data: encodeCall("balanceOf(address)", [["address", address]]) }, "latest"]));
+    if (network.faucet_url && (values.faucet || eth < 2_000_000_000_000_000n || tokens < deposit)) {
+      stdout.write(`funding ${address} from the testnet faucet...\n`);
+      await faucet(address);
     }
+    const owner = await ownerKey(values["owner-key-file"], dir);
     await sendTransaction(network.rpc_urls, owner, { to: network.stablecoin,
       data: encodeCall("approve(address,uint256)", [["address", network.settlement], ["uint", deposit]]) });
     await sendTransaction(network.rpc_urls, owner, { to: network.settlement, data: encodeCall("deposit(uint256)", [["uint", deposit]]) });
@@ -88,13 +123,13 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
     return 0;
   }
   if (command === "balance") {
-    const owner = values.owner || (values["owner-key-file"] ? addressOf(readKey(values["owner-key-file"])) : null);
-    if (!owner) throw new Error("--owner or --owner-key-file is required");
+    const owner = values.owner || ownerAddress(values["owner-key-file"], dir);
+    if (!owner) throw new Error("--owner, --owner-key-file or a local wallet (`init`) is required");
     stdout.write(`${await availableBalance(network, owner)}\n`);
     return 0;
   }
   if (command === "dispute") {
-    const owner = readKey(values["owner-key-file"]);
+    const owner = await ownerKey(values["owner-key-file"], dir);
     const record = loadRequest(dir, rest[0] || "last");
     const evidence = buildEvidence(record, { reasonCode: values.reason, statement: values.statement || rest.slice(1).join(" ") });
     const digest = evidenceHash(evidence);
@@ -107,7 +142,9 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
     }
     await sendTransaction(network.rpc_urls, owner, { to: network.settlement, data: openDisputeCall(record.settlement_key, digest) });
     const accepted = [];
-    for (const relay of network.relays) {
+    let relays = network.relays;
+    try { relays = [...relays, ...await directoryRelays(network)]; } catch {}
+    for (const relay of relays) {
       try {
         const reply = await httpJson(`${relay.url}/v11/evidence`, { method: "POST", body: evidence, ca: network.tls_ca, timeoutMs: 30_000 });
         if (reply.status === 200) accepted.push(relay.url);
@@ -122,8 +159,9 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
   if (command === "request") {
     const { response, receipt } = await consumer.request({
       endpoint: "responses", model: values.model, content: rest.join(" "), maxOutputTokens: Number(values["max-output-tokens"]),
-      provider: values.provider,
+      provider: values.provider, onDelta: values.stream ? (text) => process.stderr.write(text) : undefined,
     });
+    if (values.stream) process.stderr.write("\n");
     const output = response.output;
     stdout.write(`${JSON.stringify({ output_text: output.output_text ?? output, fee: receipt.receipt.actual_fee,
       provider: receipt.authorization.provider_signer, request_id: receipt.authorization.request_id,

package/src/consumer.mjs

@@ -4,12 +4,14 @@ import { createServer, request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { dirname, resolve } from "node:path";
 import { rootCertificates } from "node:tls";
-import { addressOf } from "./eip712.mjs";
-import { openResponse, prepareRequest, verifiedProvider } from "./protocol.mjs";
+import { addressOf, encodeCall } from "./eip712.mjs";
+import { rpcCall } from "./chain.mjs";
+import { openDelta, openResponse, outputText, prepareRequest, verifiedProvider } from "./protocol.mjs";
 import { recordRequest } from "./disputes.mjs";
-import { chatSse, responseSse } from "./sse.mjs";
+import { chatStream, responseStream } from "./sse.mjs";
 
 const PROVIDER_CACHE_MS = 30_000;
+const RELAY_CACHE_MS = 300_000;
 const MAX_BODY = 16 * 1024 * 1024;
 
 export function loadNetwork(path) {
@@ -47,8 +49,71 @@ export function httpJson(url, { method = "GET", body, ca, timeoutMs = 330_000 }
   });
 }
 
+/** POST expecting NDJSON; each line goes to onLine. Non-streamed replies resolve as JSON. */
+export function httpNdjson(url, { body, ca, timeoutMs = 340_000, onLine }) {
+  const target = new URL(url);
+  const data = Buffer.from(JSON.stringify(body));
+  const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+  return new Promise((resolvePromise, reject) => {
+    const req = send(target, {
+      method: "POST",
+      headers: { accept: "application/x-ndjson", "content-type": "application/json", "content-length": data.length },
+      ...(target.protocol === "https:" && ca ? { ca: [...rootCertificates, ca] } : {}),
+    }, (res) => {
+      const streaming = res.statusCode === 200 && String(res.headers["content-type"] || "").includes("ndjson");
+      let buffered = "";
+      const chunks = [];
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        if (!streaming) { chunks.push(chunk); return; }
+        buffered += chunk;
+        let index;
+        while ((index = buffered.indexOf("\n")) >= 0) {
+          const line = buffered.slice(0, index);
+          buffered = buffered.slice(index + 1);
+          if (line.trim()) {
+            try { onLine(JSON.parse(line)); } catch (error) { req.destroy(error); return; }
+          }
+        }
+      });
+      res.on("end", () => {
+        if (streaming) return resolvePromise({ status: 200, streamed: true });
+        try { resolvePromise({ status: res.statusCode, body: JSON.parse(chunks.join("") || "{}") }); } catch (error) { reject(error); }
+      });
+    });
+    req.setTimeout(timeoutMs, () => req.destroy(new Error("request timed out")));
+    req.on("error", reject);
+    req.end(data);
+  });
+}
+
+function decodeString(raw, offset) {
+  const length = Number(BigInt(`0x${raw.slice(offset * 2, offset * 2 + 64)}`));
+  return Buffer.from(raw.slice(offset * 2 + 64, offset * 2 + 64 + length * 2), "hex").toString("utf8");
+}
+
+/** Active Relays announced in the on-chain RelayDirectoryV11. */
+export async function directoryRelays(network) {
+  if (!network.relay_directory) return [];
+  const count = Number(BigInt(await rpcCall(network.rpc_urls, "eth_call", [{ to: network.relay_directory, data: encodeCall("relayCount()", []) }, "latest"])));
+  const relays = [];
+  for (let index = 0; index < count; index += 1) {
+    const raw = (await rpcCall(network.rpc_urls, "eth_call", [{ to: network.relay_directory,
+      data: encodeCall("relayAt(uint256)", [["uint", BigInt(index)]]) }, "latest"])).slice(2);
+    const base = Number(BigInt(`0x${raw.slice(0, 64)}`));
+    if (!Number(BigInt(`0x${raw.slice(64, 128)}`))) continue;
+    const entry = raw.slice(base * 2);
+    relays.push({
+      signer: `0x${entry.slice(64 + 24, 128)}`.toLowerCase(),
+      url: decodeString(entry, Number(BigInt(`0x${entry.slice(128, 192)}`))).replace(/\/+$/, ""),
+    });
+  }
+  return relays;
+}
+
 export class Consumer {
-  constructor({ network, keyPrivate, maxFee, journalDir, fetchJson = httpJson, now = () => Math.floor(Date.now() / 1000) }) {
+  constructor({ network, keyPrivate, maxFee, journalDir, fetchJson = httpJson, streamJson = httpNdjson, now = () => Math.floor(Date.now() / 1000) }) {
+    this.streamJson = streamJson;
     this.journalDir = journalDir;
     this.network = network;
     this.keyPrivate = keyPrivate;
@@ -58,6 +123,29 @@ export class Consumer {
     this.now = now;
     this.deployment = { chainId: network.chain_id, settlement: network.settlement.toLowerCase() };
     this.cache = new Map();
+    this.relayCache = null;
+  }
+
+  /** Manifest Relays first, then directory Relays whose /health proves the announced signer. */
+  async relays() {
+    if (this.relayCache && Date.now() - this.relayCache.at < RELAY_CACHE_MS) return this.relayCache.relays;
+    const relays = [...this.network.relays];
+    const known = new Set(relays.map((relay) => relay.signer.toLowerCase()));
+    try {
+      for (const relay of await directoryRelays(this.network)) {
+        if (known.has(relay.signer)) continue;
+        try {
+          const { status, body } = await this.fetchJson(`${relay.url}/health`, { ca: this.network.tls_ca, timeoutMs: 5_000 });
+          if (status === 200 && String(body.relay_signer).toLowerCase() === relay.signer
+              && String(body.settlement).toLowerCase() === this.deployment.settlement) {
+            relays.push(relay);
+            known.add(relay.signer);
+          }
+        } catch {}
+      }
+    } catch {}
+    this.relayCache = { at: Date.now(), relays };
+    return relays;
   }
 
   async providers(relay) {
@@ -75,16 +163,16 @@ export class Consumer {
 
   async models() {
     const names = new Set();
-    for (const relay of this.network.relays) {
+    for (const relay of await this.relays()) {
       try { for (const provider of await this.providers(relay)) for (const model of provider.models || []) names.add(model); } catch {}
     }
     return [...names].sort();
   }
 
   /** Try Relays in order; fail over only while the request provably was not dispatched. */
-  async request({ endpoint, model, content, maxOutputTokens = 4096, options = {}, provider }) {
+  async request({ endpoint, model, content, maxOutputTokens = 4096, options = {}, provider, onDelta }) {
     let lastError;
-    for (const relay of this.network.relays) {
+    for (const relay of await this.relays()) {
       let candidates;
       try {
         candidates = (await this.providers(relay)).filter((descriptor) => (descriptor.models || []).includes(model)
@@ -98,14 +186,33 @@ export class Consumer {
           endpoint, model, content, maxOutputTokens, maxFee: this.maxFee, options, now: this.now(),
         });
         let reply;
+        const streamed = [];
+        let final = null;
         try {
-          reply = await this.fetchJson(`${relay.url}/v11/requests`, { method: "POST", body: prepared.payload, ca: this.network.tls_ca });
+          reply = onDelta
+            ? await this.streamJson(`${relay.url}/v11/requests`, { body: prepared.payload, ca: this.network.tls_ca, onLine: (line) => {
+              if (line.type === "delta") {
+                streamed.push(openDelta(prepared, line.sealed, streamed.length, this.now()));
+                onDelta(streamed.at(-1));
+              } else {
+                final = line;
+              }
+            } })
+            : await this.fetchJson(`${relay.url}/v11/requests`, { method: "POST", body: prepared.payload, ca: this.network.tls_ca });
         } catch (error) {
           // The request may have reached the Relay: never replay it elsewhere.
           throw Object.assign(new Error(`request outcome unknown: ${error.message}`), { code: "outcome_unknown", requestId: prepared.authorization.request_id });
         }
+        if (reply.streamed) {
+          if (!final) throw Object.assign(new Error("stream ended without a result"), { code: "outcome_unknown" });
+          if (final.type === "error") throw Object.assign(new Error(final.error), { status: final.status, dispatched: final.dispatched });
+          reply = { status: 200, body: final };
+        }
         if (reply.status === 200) {
           const opened = openResponse(prepared, reply.body, this.deployment, this.now());
+          if (streamed.length && streamed.join("") !== outputText(opened.response.output)) {
+            throw new Error("streamed text differs from the receipted response");
+          }
           // Only this machine can ever reveal the plaintexts, so keep them for the dispute window.
           if (this.journalDir) recordRequest(this.journalDir, prepared, opened, relay.url);
           return opened;
@@ -136,6 +243,7 @@ async function readJson(req) {
 /** Local OpenAI-compatible endpoint; nothing leaves this machine unsealed except pricing and routing. */
 export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKey } = {}) {
   const server = createServer(async (req, res) => {
+    let writer = null;
     const send = (status, body, type = "application/json") => {
       res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
       res.end(type === "application/json" ? JSON.stringify(body) : body);
@@ -160,11 +268,22 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
       delete rest.max_output_tokens;
       delete rest.max_tokens;
       delete rest.max_completion_tokens;
-      const { response } = await consumer.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens, options: rest });
-      const output = response.output;
-      if (stream) return send(200, chat ? chatSse(output, { includeUsage: streamOptions?.include_usage === true }) : responseSse(output), "text/event-stream");
-      return send(200, output);
+      if (!stream) {
+        const { response } = await consumer.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens, options: rest });
+        return send(200, response.output);
+      }
+      // Headers go out with the first delta, so a request that fails before dispatch still gets an HTTP error.
+      const write = (text) => {
+        if (!res.headersSent) res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+        res.write(text);
+      };
+      writer = chat ? chatStream(write, { model }, { includeUsage: streamOptions?.include_usage === true }) : responseStream(write, { model });
+      const { response } = await consumer.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens,
+        options: rest, onDelta: (text) => writer.delta(text) });
+      writer.finish(response.output);
+      return res.end();
     } catch (error) {
+      if (res.headersSent) { writer?.fail(error.message); return res.end(); }
       const status = error.code === "outcome_unknown" ? 504 : (error.status && error.status < 500 ? error.status : 502);
       return send(status, openaiError(error.message, error.code || "request_failed"));
     }

package/src/protocol.mjs

@@ -12,6 +12,7 @@ export const REQUEST_SCHEMA = "mycomesh.v11.request.v1";
 export const RESPONSE_SCHEMA = "mycomesh.v11.response.v1";
 export const SEALED_REQUEST_PURPOSE = "mycomesh.v11.sealed-request";
 export const SEALED_RESPONSE_PURPOSE = "mycomesh.v11.sealed-response";
+export const SEALED_DELTA_PURPOSE = "mycomesh.v11.sealed-delta";
 
 export const sha256Hex = (bytes) => `0x${createHash("sha256").update(bytes).digest("hex")}`;
 
@@ -70,6 +71,28 @@ export function prepareRequest({ descriptor, deployment, keyPrivate, relaySigner
   };
 }
 
+/** The assistant text of a Responses, Chat Completions or Anthropic Messages payload. */
+export function outputText(output) {
+  if (output && typeof output === "object") {
+    if (typeof output.output_text === "string") return output.output_text;
+    if (Array.isArray(output.choices) && output.choices.length) return String(output.choices[0].message?.content ?? "");
+    if (Array.isArray(output.content)) return output.content.map((part) => part?.text ?? "").join("");
+    return (output.output || []).flatMap((item) => item?.content || []).map((part) => part?.text ?? "").join("");
+  }
+  return output == null ? "" : String(output);
+}
+
+/** Decrypt one streamed delta; a Relay can drop or stall deltas but never reorder or forge them. */
+export function openDelta(prepared, sealed, expectedSeq, now = Math.floor(Date.now() / 1000)) {
+  const opened = openFrame(Buffer.from(sealed, "base64"), {
+    recipientKey: prepared.replyKey, expectedPurpose: SEALED_DELTA_PURPOSE, replaySet: new Set(),
+    expectedSenderPeerId: prepared.providerPeerId, now,
+  });
+  const value = JSON.parse(opened.payload.toString("utf8"));
+  if (value.seq !== expectedSeq || typeof value.delta !== "string") throw new Error("streamed delta is out of order");
+  return value.delta;
+}
+
 /** Decrypt the response and prove it is exactly what the Provider signed for. */
 export function openResponse(prepared, result, deployment, now = Math.floor(Date.now() / 1000)) {
   const signed = result.receipt;

package/src/sse.mjs

@@ -1,4 +1,4 @@
-// Buffered SSE for OpenAI clients (Codex needs the Responses event sequence).
+// SSE for OpenAI clients (Codex needs the Responses event sequence): buffered, or incremental from sealed deltas.
 // Port of the event order in the former gateway/openai_protocol.py.
 import { randomUUID } from "node:crypto";
 
@@ -34,6 +34,35 @@ function added(item) {
   return copy;
 }
 
+function emitItem(emit, item, output_index) {
+  const item_id = item.id;
+  emit("response.output_item.added", { output_index, item: added(item) });
+  if (item.type === "message") {
+    (item.content || []).forEach((part, content_index) => {
+      emit("response.content_part.added", { item_id, output_index, content_index, part: { ...part, text: part.type === "output_text" ? "" : part.text } });
+      if (part.type === "output_text") {
+        if (part.text) emit("response.output_text.delta", { item_id, output_index, content_index, delta: part.text, logprobs: [] });
+        emit("response.output_text.done", { item_id, output_index, content_index, text: part.text || "", logprobs: [] });
+      }
+      emit("response.content_part.done", { item_id, output_index, content_index, part });
+    });
+  } else if (item.type === "reasoning") {
+    (item.summary || []).forEach((part, summary_index) => {
+      emit("response.reasoning_summary_part.added", { item_id, output_index, summary_index, part: { ...part, type: "summary_text", text: "" } });
+      if (part.text) emit("response.reasoning_summary_text.delta", { item_id, output_index, summary_index, delta: part.text });
+      emit("response.reasoning_summary_text.done", { item_id, output_index, summary_index, text: part.text || "" });
+      emit("response.reasoning_summary_part.done", { item_id, output_index, summary_index, part });
+    });
+  } else if (item.type === "function_call") {
+    if (item.arguments) emit("response.function_call_arguments.delta", { item_id, output_index, delta: item.arguments });
+    emit("response.function_call_arguments.done", { item_id, output_index, call_id: item.call_id || "", name: item.name || "", arguments: item.arguments || "" });
+  } else if (item.type === "custom_tool_call") {
+    if (item.input) emit("response.custom_tool_call_input.delta", { item_id, output_index, delta: item.input });
+    emit("response.custom_tool_call_input.done", { item_id, output_index, call_id: item.call_id || "", name: item.name || "", input: item.input || "" });
+  }
+  emit("response.output_item.done", { output_index, item });
+}
+
 export function responseSse(payload) {
   const final = normalize(payload);
   const out = [];
@@ -42,38 +71,66 @@ export function responseSse(payload) {
   const created = { ...structuredClone(final), status: "in_progress", output: [], output_text: "", usage: null };
   emit("response.created", { response: created });
   emit("response.in_progress", { response: created });
-  final.output.forEach((item, output_index) => {
-    const item_id = item.id;
-    emit("response.output_item.added", { output_index, item: added(item) });
-    if (item.type === "message") {
-      (item.content || []).forEach((part, content_index) => {
-        emit("response.content_part.added", { item_id, output_index, content_index, part: { ...part, text: part.type === "output_text" ? "" : part.text } });
-        if (part.type === "output_text") {
-          if (part.text) emit("response.output_text.delta", { item_id, output_index, content_index, delta: part.text, logprobs: [] });
-          emit("response.output_text.done", { item_id, output_index, content_index, text: part.text || "", logprobs: [] });
-        }
-        emit("response.content_part.done", { item_id, output_index, content_index, part });
-      });
-    } else if (item.type === "reasoning") {
-      (item.summary || []).forEach((part, summary_index) => {
-        emit("response.reasoning_summary_part.added", { item_id, output_index, summary_index, part: { ...part, type: "summary_text", text: "" } });
-        if (part.text) emit("response.reasoning_summary_text.delta", { item_id, output_index, summary_index, delta: part.text });
-        emit("response.reasoning_summary_text.done", { item_id, output_index, summary_index, text: part.text || "" });
-        emit("response.reasoning_summary_part.done", { item_id, output_index, summary_index, part });
-      });
-    } else if (item.type === "function_call") {
-      if (item.arguments) emit("response.function_call_arguments.delta", { item_id, output_index, delta: item.arguments });
-      emit("response.function_call_arguments.done", { item_id, output_index, call_id: item.call_id || "", name: item.name || "", arguments: item.arguments || "" });
-    } else if (item.type === "custom_tool_call") {
-      if (item.input) emit("response.custom_tool_call_input.delta", { item_id, output_index, delta: item.input });
-      emit("response.custom_tool_call_input.done", { item_id, output_index, call_id: item.call_id || "", name: item.name || "", input: item.input || "" });
-    }
-    emit("response.output_item.done", { output_index, item });
-  });
+  final.output.forEach((item, output_index) => emitItem(emit, item, output_index));
   emit(TERMINAL[final.status], { response: final });
   return out.join("");
 }
 
+/**
+ * Incremental Responses events: the assistant message streams first as text
+ * deltas; when the verified response arrives its other items follow and the
+ * terminal event carries the full response (message first, with the streamed id).
+ */
+export function responseStream(write, { model }) {
+  let sequence = 0;
+  const emit = (type, fields) => write(sse({ type, sequence_number: sequence++, ...fields }));
+  const id = `resp_${randomUUID().replace(/-/g, "")}`;
+  const item_id = `msg_${randomUUID().replace(/-/g, "")}`;
+  const created = { id, object: "response", created_at: Math.floor(Date.now() / 1000), model, status: "in_progress",
+    output: [], output_text: "", usage: null, error: null, incomplete_details: null };
+  let started = false;
+  let streamed = "";
+  const start = () => {
+    if (started) return;
+    started = true;
+    emit("response.created", { response: created });
+    emit("response.in_progress", { response: created });
+    emit("response.output_item.added", { output_index: 0, item: { type: "message", id: item_id, role: "assistant", status: "in_progress", content: [] } });
+    emit("response.content_part.added", { item_id, output_index: 0, content_index: 0, part: { type: "output_text", text: "", annotations: [] } });
+  };
+  return {
+    delta(text) {
+      start();
+      streamed += text;
+      emit("response.output_text.delta", { item_id, output_index: 0, content_index: 0, delta: text, logprobs: [] });
+    },
+    finish(payload) {
+      start();
+      const final = normalize(payload);
+      final.id = id;
+      const index = final.output.findIndex((item) => item.type === "message");
+      const message = index >= 0 ? final.output.splice(index, 1)[0]
+        : { type: "message", role: "assistant", status: "completed", content: [{ type: "output_text", text: final.output_text, annotations: [] }] };
+      message.id = item_id;
+      final.output.unshift(message);
+      const text = (message.content || []).filter((part) => part.type === "output_text").map((part) => part.text || "").join("");
+      if (text.startsWith(streamed) && text.length > streamed.length) {
+        emit("response.output_text.delta", { item_id, output_index: 0, content_index: 0, delta: text.slice(streamed.length), logprobs: [] });
+      }
+      const part = { type: "output_text", text, annotations: [] };
+      emit("response.output_text.done", { item_id, output_index: 0, content_index: 0, text, logprobs: [] });
+      emit("response.content_part.done", { item_id, output_index: 0, content_index: 0, part });
+      emit("response.output_item.done", { output_index: 0, item: message });
+      final.output.slice(1).forEach((item, offset) => emitItem(emit, item, offset + 1));
+      emit(TERMINAL[final.status], { response: final });
+    },
+    fail(message) {
+      start();
+      emit("response.failed", { response: { ...created, status: "failed", error: { code: "mycomesh_error", message } } });
+    },
+  };
+}
+
 export function chatSse(payload, { includeUsage = false } = {}) {
   const id = payload.id || `chatcmpl_${randomUUID().replace(/-/g, "")}`;
   const model = payload.model || "";
@@ -99,3 +156,33 @@ export function chatSse(payload, { includeUsage = false } = {}) {
   out.push("data: [DONE]\n\n");
   return out.join("");
 }
+
+/** Incremental Chat Completions chunks from sealed deltas. */
+export function chatStream(write, { model }, { includeUsage = false } = {}) {
+  const id = `chatcmpl_${randomUUID().replace(/-/g, "")}`;
+  const created = Math.floor(Date.now() / 1000);
+  const chunk = (delta, finish_reason = null) =>
+    write(`data: ${JSON.stringify({ id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta, finish_reason }] })}\n\n`);
+  let started = false;
+  let streamed = "";
+  const start = () => { if (!started) { started = true; chunk({ role: "assistant" }); } };
+  return {
+    delta(text) { start(); streamed += text; chunk({ content: text }); },
+    finish(payload) {
+      start();
+      const choice = (payload?.choices || [])[0] || {};
+      const text = typeof choice.message?.content === "string" ? choice.message.content : "";
+      if (text.startsWith(streamed) && text.length > streamed.length) chunk({ content: text.slice(streamed.length) });
+      chunk({}, choice.finish_reason || "stop");
+      if (includeUsage && payload?.usage) {
+        write(`data: ${JSON.stringify({ id, object: "chat.completion.chunk", created, model, choices: [], usage: payload.usage })}\n\n`);
+      }
+      write("data: [DONE]\n\n");
+    },
+    fail(message) {
+      start();
+      write(`data: ${JSON.stringify({ error: { message, type: "mycomesh_error" } })}\n\n`);
+      write("data: [DONE]\n\n");
+    },
+  };
+}

package/src/wallet.mjs

@@ -0,0 +1,106 @@
+// The Consumer's owner wallet: an Ethereum V3 keystore (the format MetaMask and geth import),
+// so the key that holds the deposit never sits in a plaintext file.
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, pbkdf2Sync, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { addressOf, keccak } from "./eip712.mjs";
+
+const SCRYPT = { n: 1 << 15, r: 8, p: 1, dklen: 32 };
+
+export function encryptKeystore(privateKey, password) {
+  const salt = randomBytes(32);
+  const iv = randomBytes(16);
+  const derived = scryptSync(Buffer.from(password, "utf8"), salt, SCRYPT.dklen,
+    { N: SCRYPT.n, r: SCRYPT.r, p: SCRYPT.p, maxmem: 128 * SCRYPT.n * SCRYPT.r * 2 });
+  const cipher = createCipheriv("aes-128-ctr", derived.subarray(0, 16), iv);
+  const ciphertext = Buffer.concat([cipher.update(Buffer.from(privateKey.replace(/^0x/, ""), "hex")), cipher.final()]);
+  return {
+    version: 3, id: randomUUID(), address: addressOf(privateKey).slice(2),
+    crypto: {
+      cipher: "aes-128-ctr", cipherparams: { iv: iv.toString("hex") }, ciphertext: ciphertext.toString("hex"),
+      kdf: "scrypt", kdfparams: { ...SCRYPT, salt: salt.toString("hex") },
+      mac: keccak(Buffer.concat([derived.subarray(16, 32), ciphertext])).toString("hex"),
+    },
+  };
+}
+
+export function decryptKeystore(keystore, password) {
+  const crypto = keystore.crypto || keystore.Crypto;
+  if (keystore.version !== 3 || crypto?.cipher !== "aes-128-ctr") throw new Error("unsupported keystore");
+  const params = crypto.kdfparams;
+  const salt = Buffer.from(params.salt, "hex");
+  const secret = Buffer.from(password, "utf8");
+  let derived;
+  if (crypto.kdf === "scrypt") {
+    derived = scryptSync(secret, salt, params.dklen, { N: params.n, r: params.r, p: params.p, maxmem: 128 * params.n * params.r * 2 });
+  } else if (crypto.kdf === "pbkdf2" && params.prf === "hmac-sha256") {
+    derived = pbkdf2Sync(secret, salt, params.c, params.dklen, "sha256");
+  } else {
+    throw new Error(`unsupported keystore KDF ${crypto.kdf}`);
+  }
+  const ciphertext = Buffer.from(crypto.ciphertext, "hex");
+  const mac = keccak(Buffer.concat([derived.subarray(16, 32), ciphertext])).toString("hex");
+  if (mac !== crypto.mac.toLowerCase()) throw new Error("wrong wallet password");
+  const decipher = createDecipheriv("aes-128-ctr", derived.subarray(0, 16), Buffer.from(crypto.cipherparams.iv, "hex"));
+  const privateKey = `0x${Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("hex")}`;
+  if (keystore.address && addressOf(privateKey).slice(2) !== keystore.address.toLowerCase().replace(/^0x/, "")) {
+    throw new Error("keystore address does not match its key");
+  }
+  return privateKey;
+}
+
+/** Password from MYCOMESH_WALLET_PASSWORD, else a muted terminal prompt. */
+export async function password(prompt, { confirm = false } = {}) {
+  if (process.env.MYCOMESH_WALLET_PASSWORD) return process.env.MYCOMESH_WALLET_PASSWORD;
+  if (!process.stdin.isTTY) throw new Error("set MYCOMESH_WALLET_PASSWORD or run in a terminal");
+  const ask = (label) => new Promise((resolve, reject) => {
+    process.stderr.write(label);
+    const input = [];
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const onData = (chunk) => {
+      for (const char of chunk.toString("utf8")) {
+        if (char === "\r" || char === "\n") { done(); return resolve(input.join("")); }
+        if (char === "\u0003") { done(); return reject(new Error("cancelled")); }
+        if (char === "\u007f") input.pop(); else input.push(char);
+      }
+    };
+    const done = () => { process.stdin.setRawMode(false); process.stdin.pause(); process.stdin.off("data", onData); process.stderr.write("\n"); };
+    process.stdin.on("data", onData);
+  });
+  const first = await ask(prompt);
+  if (first.length < 8) throw new Error("use a wallet password of at least 8 characters");
+  if (confirm && (await ask("Repeat the password: ")) !== first) throw new Error("passwords differ");
+  return first;
+}
+
+export const walletPath = (dir) => join(dir, "owner-wallet.json");
+
+export async function createWallet(dir) {
+  const path = walletPath(dir);
+  if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+  const keystore = encryptKeystore(`0x${randomBytes(32).toString("hex")}`,
+    await password("New wallet password (protects your deposit): ", { confirm: true }));
+  writeFileSync(path, `${JSON.stringify(keystore, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return keystore;
+}
+
+export const walletAddress = (keystore) => `0x${keystore.address.toLowerCase().replace(/^0x/, "")}`;
+
+/** The owner key: --owner-key-file (raw hex or a keystore), else this machine's wallet. */
+export async function ownerKey(file, dir) {
+  const path = file || walletPath(dir);
+  if (!existsSync(path)) throw new Error("no owner wallet; run `mycomesh-consumer init` or pass --owner-key-file");
+  const text = readFileSync(path, "utf8").trim();
+  if (/^(0x)?[0-9a-fA-F]{64}$/.test(text)) return text.startsWith("0x") ? text : `0x${text}`;
+  return decryptKeystore(JSON.parse(text), await password("Wallet password: "));
+}
+
+export function ownerAddress(file, dir) {
+  const path = file || walletPath(dir);
+  if (!existsSync(path)) return null;
+  const text = readFileSync(path, "utf8").trim();
+  if (/^(0x)?[0-9a-fA-F]{64}$/.test(text)) return addressOf(text.startsWith("0x") ? text : `0x${text}`);
+  return walletAddress(JSON.parse(text));
+}