mycomesh-consumer 0.2.1 → 0.4.0

package/src/consumer.mjs

@@ -4,12 +4,15 @@ 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";
+import { consoleRoutes, localRequestAllowed } from "./console.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 +50,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 +124,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 +164,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 +187,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;
@@ -134,15 +242,26 @@ 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 } = {}) {
+export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKey, dataDir } = {}) {
+  const routes = dataDir ? consoleRoutes({ consumer, dataDir }) : {};
   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);
     };
     try {
-      if (apiKey && req.headers.authorization !== `Bearer ${apiKey}`) return send(401, openaiError("invalid API key", "unauthorized"));
+      if (!localRequestAllowed(req, server.address().port)) return send(403, openaiError("only this machine may use the local node", "forbidden"));
       const path = new URL(req.url, "http://localhost").pathname.replace(/^\/v1\/v1\//, "/v1/");
+      const route = routes[`${req.method} ${path}`];
+      if (route) {
+        if (req.method === "POST" && !String(req.headers["content-type"] || "").startsWith("application/json")) {
+          return send(415, { error: "JSON body required" });
+        }
+        const result = await route(req.method === "POST" ? await readJson(req) : {});
+        return result?.type ? send(200, result.body, result.type) : send(200, result);
+      }
+      if (apiKey && req.headers.authorization !== `Bearer ${apiKey}`) return send(401, openaiError("invalid API key", "unauthorized"));
       if (req.method === "GET" && path === "/health") return send(200, { ok: true, protocol: 11, key: consumer.key });
       if (req.method === "GET" && path === "/v1/models") {
         return send(200, { object: "list", data: (await consumer.models()).map((id) => ({ id, object: "model", owned_by: "mycomesh" })) });
@@ -160,11 +279,26 @@ 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(); }
+      if (error.message === "wrong wallet password") return send(401, { error: error.message });
+      if (error.status && error.status < 500 && !error.dispatched && routes[`${req.method} ${new URL(req.url, "http://x").pathname}`]) {
+        return send(error.status, { error: error.message });
+      }
       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/disputes.mjs

@@ -1,5 +1,5 @@
 // V11 Consumer disputes: keep each request's plaintexts locally, reveal them as evidence on demand.
-import { chmodSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalJson } from "./secure-envelope.mjs";
 import { encodeCall, encodeWords, hex, keccak, settlementKey } from "./eip712.mjs";
@@ -52,3 +52,31 @@ export const reportId = (key, reporter, digest) =>
   hex(keccak(encodeWords([["bytes32", key], ["address", reporter], ["bytes32", digest]])));
 
 export const openDisputeCall = (key, digest) => encodeCall("openDispute(bytes32,bytes32)", [["bytes32", key], ["bytes32", digest]]);
+
+function preview(document) {
+  const content = document.endpoint === "chat" ? (document.messages || []).filter((m) => m.role === "user").at(-1)?.content : document.input;
+  const text = typeof content === "string" ? content : Array.isArray(content)
+    ? content.map((part) => (typeof part === "string" ? part : part?.text ?? part?.content ?? "")).join(" ") : JSON.stringify(content ?? "");
+  return String(text).slice(0, 400);
+}
+
+/** Recorded requests, newest first, with short previews (the plaintexts never leave this machine). */
+export function listRequests(dir, outputText, limit = 100) {
+  const folder = journal(dir);
+  if (!existsSync(folder)) return [];
+  return readdirSync(folder).filter((name) => name.endsWith(".json"))
+    .map((name) => JSON.parse(readFileSync(join(folder, name), "utf8")))
+    .sort((a, b) => b.recorded_at - a.recorded_at).slice(0, limit)
+    .map((record) => {
+      let request = {}; let response = {};
+      try { request = JSON.parse(Buffer.from(record.request, "base64").toString("utf8")); } catch {}
+      try { response = JSON.parse(Buffer.from(record.response, "base64").toString("utf8")); } catch {}
+      const { authorization, receipt } = record.signed_receipt;
+      return {
+        settlement_key: record.settlement_key, recorded_at: record.recorded_at, relay_url: record.relay_url,
+        model: request.model, endpoint: request.endpoint, prompt: preview(request),
+        answer: String(outputText(response.output)).slice(0, 600), fee: String(receipt.actual_fee),
+        input_tokens: receipt.input_tokens, output_tokens: receipt.output_tokens, provider: authorization.provider_signer,
+      };
+    });
+}

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,114 @@
+// 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, secret) {
+  const path = walletPath(dir);
+  if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+  if (secret !== undefined && String(secret).length < 8) throw new Error("use a wallet password of at least 8 characters");
+  const keystore = encryptKeystore(`0x${randomBytes(32).toString("hex")}`,
+    secret ?? 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));
+}
+
+/** Unlock this machine's wallet with a password given by the local console. */
+export function unlockWallet(dir, secret) {
+  const path = walletPath(dir);
+  if (!existsSync(path)) throw new Error("no owner wallet yet");
+  return decryptKeystore(JSON.parse(readFileSync(path, "utf8")), String(secret ?? ""));
+}