@genkaku/protocol 0.0.0-stage → 0.1.1

package/dist/directory.js

@@ -0,0 +1,149 @@
+// GENKAKU: on-chain worker discovery (P4.9b).
+//
+// Replaces the bootstrap seed. The directory is built from `WorkerLocated` logs
+// and never from a server we run: a cold client with an empty config and no
+// cache can find workers using nothing but a public Base RPC.
+//
+// Two cost controls make that affordable at scale:
+//   1. a persisted checkpoint (`lastBlock`) so a normal boot scans only the
+//      blocks since the last run — usually a handful;
+//   2. an on-disk entry cache, so the offer list is available even when the
+//      chain read fails (offline start, RPC trouble).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readWorkerDeactivations, readWorkerLocators, REGISTRY_DEPLOY_BLOCK, } from "./chain.js";
+import { peerIdDigestOf } from "./registry.js";
+export function directoryPath(keyDir) {
+    return join(keyDir, 'directory.json');
+}
+export function loadDirectory(keyDir, env) {
+    const empty = {
+        version: 1,
+        env,
+        lastBlock: (REGISTRY_DEPLOY_BLOCK[env] - 1n).toString(),
+        entries: [],
+        updatedAt: 0,
+    };
+    try {
+        if (!existsSync(directoryPath(keyDir)))
+            return empty;
+        const raw = JSON.parse(readFileSync(directoryPath(keyDir), 'utf8'));
+        if (raw?.version !== 1 || raw.env !== env || !Array.isArray(raw.entries))
+            return empty;
+        return raw;
+    }
+    catch {
+        return empty;
+    }
+}
+function saveDirectory(keyDir, cache) {
+    try {
+        mkdirSync(keyDir, { recursive: true });
+        writeFileSync(directoryPath(keyDir), JSON.stringify(cache, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // the cache is an optimisation; never fail discovery because of it
+    }
+}
+/** Does the locator actually point at the peerId the wallet pinned?
+ *  A worker could advertise someone else's address (or an old one); the digest
+ *  compare is the only thing that makes the directory trustworthy. */
+function locatorMatchesPeer(entry) {
+    const wanted = entry.peerId.toLowerCase();
+    const ids = entry.locator
+        .split(/[;\n]+/)
+        .map(part => part.split('/p2p/').pop()?.split('/')[0])
+        .filter((id) => id != null && id !== '');
+    if (ids.length === 0)
+        return false;
+    return ids.every((id) => {
+        try {
+            return peerIdDigestOf(id).toLowerCase() === wanted;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Scan forward from the checkpoint, merge into the cache, and persist.
+ *  Returns the merged directory (live entries only). */
+export async function syncDirectory(publicC, env, keyDir, log) {
+    const cache = loadDirectory(keyDir, env);
+    const floor = REGISTRY_DEPLOY_BLOCK[env] - 1n;
+    const scannedFrom = BigInt(cache.lastBlock) + 1n > floor ? BigInt(cache.lastBlock) + 1n : floor;
+    const latest = await publicC.getBlockNumber();
+    const byWallet = new Map();
+    for (const entry of cache.entries)
+        byWallet.set(entry.wallet.toLowerCase(), entry);
+    let added = 0;
+    let removed = 0;
+    if (latest >= scannedFrom) {
+        const [located, dead] = await Promise.all([
+            readWorkerLocators(publicC, env, { fromBlock: scannedFrom, toBlock: latest }),
+            readWorkerDeactivations(publicC, env, { fromBlock: scannedFrom, toBlock: latest }),
+        ]);
+        for (const entry of located) {
+            if (!locatorMatchesPeer(entry)) {
+                log.warn('directory: %s advertises a locator that does not contain its pinned peerId — ignored', entry.wallet);
+                continue;
+            }
+            const key = entry.wallet.toLowerCase();
+            const prev = byWallet.get(key);
+            if (prev == null || BigInt(prev.blockNumber) < entry.blockNumber)
+                added++;
+            byWallet.set(key, toCacheEntry(entry));
+        }
+        for (const gone of dead) {
+            const key = gone.wallet.toLowerCase();
+            const prev = byWallet.get(key);
+            if (prev != null && BigInt(prev.blockNumber) < gone.blockNumber) {
+                byWallet.delete(key);
+                removed++;
+            }
+        }
+        log.info('directory: scanned %s..%s (%d located, %d deactivated, %d new, %d dropped)', scannedFrom.toString(), latest.toString(), located.length, dead.length, added, removed);
+    }
+    const next = {
+        version: 1,
+        env,
+        lastBlock: latest.toString(),
+        entries: [...byWallet.values()],
+        updatedAt: Date.now(),
+    };
+    saveDirectory(keyDir, next);
+    return { entries: next.entries, scannedFrom, scannedTo: latest, added, removed };
+}
+function toCacheEntry(entry) {
+    return {
+        wallet: entry.wallet,
+        peerId: entry.peerId,
+        locator: entry.locator,
+        updatedAt: entry.updatedAt,
+        blockNumber: entry.blockNumber.toString(),
+    };
+}
+/** Every dialable multiaddr in the directory, newest worker first. */
+export function workerAddrs(cache) {
+    const addrs = [];
+    const newestFirst = [...cache.entries].sort((a, b) => {
+        const delta = BigInt(b.blockNumber) - BigInt(a.blockNumber);
+        return delta === 0n ? 0 : delta > 0n ? 1 : -1;
+    });
+    for (const entry of newestFirst) {
+        for (const addr of entry.locator.split(/[;\n]+/).map(s => s.trim())) {
+            if (addr.startsWith('/'))
+                addrs.push(addr);
+        }
+    }
+    return [...new Set(addrs)];
+}
+/** Drop a wallet from the cache after repeated dial failures, so a dead worker
+ *  stops costing a connection attempt on every boot until it advertises again. */
+export function dropEntry(keyDir, env, wallet) {
+    const cache = loadDirectory(keyDir, env);
+    const next = cache.entries.filter(e => e.wallet.toLowerCase() !== wallet.toLowerCase());
+    if (next.length === cache.entries.length)
+        return;
+    saveDirectory(keyDir, { ...cache, entries: next, updatedAt: Date.now() });
+}
+//# sourceMappingURL=directory.js.map

package/dist/discovery.d.ts

@@ -0,0 +1,20 @@
+export declare const DNS_SEED_NAME = "_genkaku-v0.seeds.genkaku.app";
+/** Cloudflare's JSON DoH endpoint (no key, no logging of the query body). */
+export declare const DEFAULT_DOH_URL = "https://cloudflare-dns.com/dns-query";
+export type SeedResolverOptions = {
+    /** the DNS name to query (default _genkaku-v0.seeds.genkaku.app) */
+    name?: string;
+    /** DoH endpoint override (tests inject a fake fetch instead) */
+    dohUrl?: string;
+    /** injectable fetch for tests */
+    fetchImpl?: typeof fetch;
+    /** hard cap — discovery must never stall the marketplace */
+    timeoutMs?: number;
+};
+/** Resolve TXT seed multiaddrs. Any failure (network, DNS, malformed record)
+ *  degrades to [] — the caller falls through to peerstore/manual layers. */
+export declare function resolveDnsSeeds(opts?: SeedResolverOptions): Promise<string[]>;
+/** TXT payloads → multiaddrs. Quoted chunks are joined, `v=1;` style prefixes
+ *  ignored, and only "/"-prefixed tokens survive. */
+export declare function parseSeedTxt(records: string[]): string[];
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,aAAa,kCAAkC,CAAA;AAE5D,6EAA6E;AAC7E,eAAO,MAAM,eAAe,yCAAyC,CAAA;AAKrE,MAAM,MAAM,mBAAmB,GAAG;IAChC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iCAAiC;IACjC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;4EAC4E;AAC5E,wBAAsB,eAAe,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BvF;AAED;qDACqD;AACrD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAoBxD"}

package/dist/discovery.js

@@ -0,0 +1,58 @@
+// GENKAKU: discovery layer 2 (P2 §2) — DNS TXT seeds.
+// A TXT record lists multiaddrs; editing DNS reboots discovery without a
+// client release. Resolution goes through DNS-over-HTTPS so a client whose
+// local resolver strips TXT (or is hijacked) still works, and so there is no
+// native resolver dependency in the main process.
+//
+// Record shape (chunked strings are joined before parsing):
+//   _genkaku-v0.seeds.genkaku.app. TXT "v=1; seeds=<addr1>,<addr2>"
+// The `v=1;` prefix is optional; only tokens that look like multiaddrs ("/…")
+// are kept, so prose or future fields cannot be dialed by accident.
+export const DNS_SEED_NAME = '_genkaku-v0.seeds.genkaku.app';
+/** Cloudflare's JSON DoH endpoint (no key, no logging of the query body). */
+export const DEFAULT_DOH_URL = 'https://cloudflare-dns.com/dns-query';
+/** Resolve TXT seed multiaddrs. Any failure (network, DNS, malformed record)
+ *  degrades to [] — the caller falls through to peerstore/manual layers. */
+export async function resolveDnsSeeds(opts = {}) {
+    const name = opts.name ?? DNS_SEED_NAME;
+    const dohUrl = opts.dohUrl ?? DEFAULT_DOH_URL;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${dohUrl}?name=${encodeURIComponent(name)}&type=TXT`;
+    try {
+        const res = await doFetch(url, {
+            headers: { accept: 'application/dns-json' },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 4_000),
+        });
+        if (!res.ok) {
+            return [];
+        }
+        const body = (await res.json());
+        if (body.Status !== 0 || !Array.isArray(body.Answer)) {
+            return [];
+        }
+        return parseSeedTxt(body.Answer.map(a => a.data).filter((d) => typeof d === 'string'));
+    }
+    catch {
+        return [];
+    }
+}
+/** TXT payloads → multiaddrs. Quoted chunks are joined, `v=1;` style prefixes
+ *  ignored, and only "/"-prefixed tokens survive. */
+export function parseSeedTxt(records) {
+    const out = new Set();
+    for (const raw of records) {
+        const joined = raw
+            .split('"')
+            .join('')
+            .replace(/^\s*v=\d+\s*;\s*/i, '');
+        for (const token of joined.split(/[,\s]+/)) {
+            // tolerate `seeds=` / `v=` style key prefixes on the first token
+            const addr = token.trim().replace(/^[a-z][a-z0-9_-]*=/i, '');
+            if (addr.startsWith('/') && addr.includes('/p2p/')) {
+                out.add(addr);
+            }
+        }
+    }
+    return [...out];
+}
+//# sourceMappingURL=discovery.js.map

package/dist/hello.d.ts

@@ -0,0 +1,14 @@
+export type HelloProof = {
+    peerId: string;
+    wallet: `0x${string}`;
+    sig: string;
+};
+/** Fresh challenge for one handshake (never reused, never stored). */
+export declare function newNonce(): `0x${string}`;
+/** The exact bytes both sides sign — one definition, no drift. */
+export declare function helloDigest(peerId: string, wallet: `0x${string}`, nonce: `0x${string}`): Uint8Array;
+/** Worker side: prove possession of the wallet key for this PeerId. */
+export declare function signHello(key: `0x${string}`, peerId: string, nonce: `0x${string}`): Promise<HelloProof>;
+/** Client side: does this proof really come from `wallet` over `nonce`? */
+export declare function verifyHello(proof: HelloProof, nonce: `0x${string}`): Promise<boolean>;
+//# sourceMappingURL=hello.d.ts.map

package/dist/hello.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hello.d.ts","sourceRoot":"","sources":["../src/hello.ts"],"names":[],"mappings":"AA2BA,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACrB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,sEAAsE;AACtE,wBAAgB,QAAQ,IAAI,KAAK,MAAM,EAAE,CAExC;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,KAAK,MAAM,EAAE,EACrB,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,UAAU,CAEZ;AAED,uEAAuE;AACvE,wBAAsB,SAAS,CAC7B,GAAG,EAAE,KAAK,MAAM,EAAE,EAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,MAAM,EAAE,GACnB,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3F"}

package/dist/hello.js

@@ -0,0 +1,42 @@
+// GENKAKU: data-plane identity proof (P4.9e).
+//
+// WorkerRegistry proves wallet ⇄ PeerId, but only for a worker that chose to
+// register — and the record is self-declared (whoever pays gas claims the
+// peerId). The hello handshake closes that hole directly: the client sends a
+// fresh 32-byte nonce, the peer signs
+//
+//     keccak("genkaku.hello.v0:<peerId>:<wallet>:<nonce>")
+//
+// with the EVM key it claims, and the client recovers the signer. A peer can
+// only answer for a wallet whose private key it holds, so an offer that claims
+// someone else's wallet is dropped before any escrow is opened. This also works
+// for invite-link workers that never touched the chain.
+//
+// Both nonce and peerId are inside the digest: the nonce makes a recorded hello
+// useless to another client, and the peerId stops a peer from re-serving a
+// signature it obtained from a different node.
+import { randomBytes } from 'node:crypto';
+import { keccak256, toBytes } from 'viem';
+import { walletAddress } from "./chain.js";
+import { recoverSigner, signDigest } from "./receipts.js";
+const HELLO_TAG = 'genkaku.hello.v0:';
+/** Fresh challenge for one handshake (never reused, never stored). */
+export function newNonce() {
+    return `0x${randomBytes(32).toString('hex')}`;
+}
+/** The exact bytes both sides sign — one definition, no drift. */
+export function helloDigest(peerId, wallet, nonce) {
+    return toBytes(keccak256(toBytes(`${HELLO_TAG}${peerId}:${wallet.toLowerCase()}:${nonce.toLowerCase()}`)));
+}
+/** Worker side: prove possession of the wallet key for this PeerId. */
+export async function signHello(key, peerId, nonce) {
+    const wallet = walletAddress(key);
+    const sig = await signDigest(key, helloDigest(peerId, wallet, nonce));
+    return { peerId, wallet, sig };
+}
+/** Client side: does this proof really come from `wallet` over `nonce`? */
+export async function verifyHello(proof, nonce) {
+    const signer = await recoverSigner(helloDigest(proof.peerId, proof.wallet, nonce), proof.sig);
+    return signer != null && signer.toLowerCase() === proof.wallet.toLowerCase();
+}
+//# sourceMappingURL=hello.js.map

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * GenKaKu protocol core.
+ *
+ * Everything here is harness-independent: contracts, escrow accounting, the
+ * libp2p transport, the Ollama supervisor and the OpenAI-compatible bridge.
+ * The DeepSeek Harness adapters live in @genkaku/dsh-runtime and the two
+ * plugin packages above it.
+ */
+export * from './bridge.ts';
+export * from './chain.ts';
+export * from './credit.ts';
+export * from './dial.ts';
+export * from './directory.ts';
+export * from './discovery.ts';
+export * from './hello.ts';
+export * from './keys.ts';
+export * from './llmBridge.ts';
+export * from './lp.ts';
+export * from './modeManager.ts';
+export * from './netconfig.ts';
+export * from './offer.ts';
+export * from './ollama.ts';
+export * from './p2pNode.ts';
+export * from './paywall.ts';
+export * from './publishOptIn.ts';
+export * from './receipts.ts';
+export * from './registry.ts';
+export * from './rpc.ts';
+export * from './status.ts';
+export * from './userSession.ts';
+export * from './workerSession.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,SAAS,CAAA;AACvB,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * GenKaKu protocol core.
+ *
+ * Everything here is harness-independent: contracts, escrow accounting, the
+ * libp2p transport, the Ollama supervisor and the OpenAI-compatible bridge.
+ * The DeepSeek Harness adapters live in @genkaku/dsh-runtime and the two
+ * plugin packages above it.
+ */
+export * from "./bridge.js";
+export * from "./chain.js";
+export * from "./credit.js";
+export * from "./dial.js";
+export * from "./directory.js";
+export * from "./discovery.js";
+export * from "./hello.js";
+export * from "./keys.js";
+export * from "./llmBridge.js";
+export * from "./lp.js";
+export * from "./modeManager.js";
+export * from "./netconfig.js";
+export * from "./offer.js";
+export * from "./ollama.js";
+export * from "./p2pNode.js";
+export * from "./paywall.js";
+export * from "./publishOptIn.js";
+export * from "./receipts.js";
+export * from "./registry.js";
+export * from "./rpc.js";
+export * from "./status.js";
+export * from "./userSession.js";
+export * from "./workerSession.js";
+//# sourceMappingURL=index.js.map

package/dist/keys.d.ts

@@ -0,0 +1,30 @@
+import type { Hex } from 'viem';
+export type PrivKey = Hex;
+export type EthAddress = `0x${string}`;
+/** safeStorage-shaped codec: electron main wires { encryptString, ... };
+ *  tests/dev can pass a plaintext pass-through (files still skip keys repo). */
+export type KeyCodec = {
+    encrypt(plain: string): Buffer;
+    decrypt(blob: Buffer): string;
+};
+export type KeyVault = {
+    /** the app's user identity key — generated on first use */
+    userKey(): PrivKey;
+    /** the app's worker identity key — generated on first use */
+    workerKey(): PrivKey;
+    /** derived addresses only (renderer-safe mirror of the keys) */
+    addresses(): {
+        user: EthAddress;
+        worker: EthAddress;
+    };
+    /** true when ANY key came from env overrides (dev-only telemetry) */
+    readonly usingEnvOverrides: boolean;
+};
+export declare function createKeyVault(opts: {
+    /** directory for the encrypted key file (app userData in main process) */
+    dir: string;
+    codec?: KeyCodec;
+}): KeyVault;
+/** Accepts 0x-prefixed or bare 32-byte hex; returns lowercase Hex or throws. */
+export declare function normalizeKey(input: string): PrivKey;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAG/B,MAAM,MAAM,OAAO,GAAG,GAAG,CAAA;AACzB,MAAM,MAAM,UAAU,GAAG,KAAK,MAAM,EAAE,CAAA;AAEtC;gFACgF;AAChF,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IAC9B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAC9B,CAAA;AASD,MAAM,MAAM,QAAQ,GAAG;IACrB,2DAA2D;IAC3D,OAAO,IAAI,OAAO,CAAA;IAClB,6DAA6D;IAC7D,SAAS,IAAI,OAAO,CAAA;IACpB,gEAAgE;IAChE,SAAS,IAAI;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAA;IACrD,qEAAqE;IACrE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;CACpC,CAAA;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,QAAQ,CAAA;CACjB,GAAG,QAAQ,CA2GX;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQnD"}

package/dist/keys.js

@@ -0,0 +1,126 @@
+// GENKAKU: wallet key vault (P4.4.al) — Electron main process ONLY.
+// Key material: one EVM keypair as the app's USER identity (receipt signing,
+// escrow open + settle) and one as the WORKER identity (sidecar co-sign,
+// claim). Encrypted by an injectable safeStorage-compatible codec and stored
+// under the userData dir; dev/test overrides come from GENKAKU_USER_KEY /
+// GENKAKU_WORKER_KEY env (documented DEV-ONLY).
+//
+// NO mainnet paths: consumers are testnet-locked at the chain layer (chain.ts
+// refuses non-base-sepolia writes). Keys NEVER leave the main process — the
+// renderer receives only the derived ADDRESSES.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+const PLAINTEXT_CODEC = {
+    encrypt: plain => Buffer.from(plain, 'utf8'),
+    decrypt: blob => blob.toString('utf8'),
+};
+export function createKeyVault(opts) {
+    const codec = opts.codec ?? PLAINTEXT_CODEC;
+    const file = join(opts.dir, 'genkaku.keys.json');
+    mkdirSync(opts.dir, { recursive: true });
+    let vault = { version: 1 };
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        if (raw?.version === 1) {
+            vault = raw;
+        }
+    }
+    catch {
+        // first run / unreadable → fresh vault below
+    }
+    // DEV override (P4.4.al): env keys win when present. Deliberately loud.
+    const envUser = envKey('GENKAKU_USER_KEY');
+    const envWorker = envKey('GENKAKU_WORKER_KEY');
+    if (envUser != null || envWorker != null) {
+        console.warn('[genkaku:keys] DEV-ONLY env key override active '
+            + `(user:${envUser != null ? 'set' : '-'} worker:${envWorker != null ? 'set' : '-'}) — never ship this path`);
+    }
+    let userKey = envUser;
+    let workerKey = envWorker;
+    const decode = (enc) => {
+        if (enc == null) {
+            return null;
+        }
+        try {
+            return normalizeKey(codec.decrypt(Buffer.from(enc, 'base64')));
+        }
+        catch (error) {
+            console.error('[genkaku:keys] decrypt failed', error instanceof Error ? error.message : String(error));
+            return null;
+        }
+    };
+    userKey ??= decode(vault.userKeyEnc);
+    workerKey ??= decode(vault.workerKeyEnc);
+    const persist = () => {
+        let writeable = true;
+        try {
+            writeFileSync(file, JSON.stringify(vault), { mode: 0o600 });
+        }
+        catch (error) {
+            writeable = false;
+            console.error('[genkaku:keys] vault write failed', error instanceof Error ? error.message : String(error));
+        }
+        if (!writeable) {
+            throw new Error('[genkaku:keys] cannot persist key vault');
+        }
+    };
+    const lock = (name) => {
+        const current = userKey != null && name === 'user' ? userKey : workerKey != null && name === 'worker' ? workerKey : null;
+        if (current != null) {
+            return current;
+        }
+        const generated = normalizeKey(generatePrivateKey());
+        // keys from env overrides are intentionally NOT re-persisted — they stay
+        // env-scoped for the process lifetime.
+        if (name === 'user') {
+            userKey = generated;
+            if (envUser != null) {
+                return generated;
+            }
+            vault.userKeyEnc = codec.encrypt(generated).toString('base64');
+        }
+        else {
+            workerKey = generated;
+            if (envWorker != null) {
+                return generated;
+            }
+            vault.workerKeyEnc = codec.encrypt(generated).toString('base64');
+        }
+        persist();
+        return generated;
+    };
+    return {
+        userKey: () => lock('user'),
+        workerKey: () => lock('worker'),
+        addresses: () => ({
+            user: privateKeyToAccount(lock('user')).address,
+            worker: privateKeyToAccount(lock('worker')).address,
+        }),
+        get usingEnvOverrides() {
+            return envUser != null || envWorker != null;
+        },
+    };
+}
+/** Accepts 0x-prefixed or bare 32-byte hex; returns lowercase Hex or throws. */
+export function normalizeKey(input) {
+    const bare = input.trim().toLowerCase().replace(/^0x/, '');
+    if (!/^[0-9a-f]{64}$/.test(bare)) {
+        throw new Error('[genkaku:keys] invalid private key material (expected 32-byte hex)');
+    }
+    return `0x${bare}`;
+}
+function envKey(name) {
+    const value = process.env[name];
+    if (value == null || value === '') {
+        return null;
+    }
+    try {
+        return normalizeKey(value);
+    }
+    catch (error) {
+        console.error(`[genkaku:keys] ${name} malformed`, error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/llmBridge.d.ts

@@ -0,0 +1,100 @@
+import { type ModelProfile, type OllamaModelFacts } from './capabilities.ts';
+export type CompletionRequest = {
+    model: string;
+    prompt: string;
+    system?: string;
+    maxTokens?: number;
+};
+export type LocalCompletionSource = {
+    /** stream tokens; resolves when the source is exhausted */
+    stream(req: CompletionRequest, onDelta: (text: string) => void, signal?: AbortSignal): Promise<{
+        promptTokens: number;
+        completionTokens: number;
+        model: string;
+    }>;
+};
+export type ModelInfo = {
+    name: string;
+    sizeBytes?: number | undefined;
+    family?: string | undefined;
+    quantization?: string | undefined;
+};
+export type PullProgress = {
+    status: string;
+    percent?: number | undefined;
+};
+export declare function ollamaAdmin(host?: string): {
+    /** locally installed models (what the worker may choose to publish) */
+    list(): Promise<ModelInfo[]>;
+    /** download a model from the Ollama registry (registry name like "llama3:8b") */
+    pull(model: string, onProgress?: (p: PullProgress) => void, signal?: AbortSignal): Promise<{
+        status: string;
+    }>;
+};
+/**
+ * Ask Ollama what a model can do.
+ *
+ * `/api/show` is the authoritative answer for capabilities; the parameter size
+ * lives in `/api/tags` under `details.parameter_size`. Both are needed for the
+ * tier, so callers usually want {@link probeModels}.
+ *
+ * @param model - model name as Ollama knows it.
+ * @param host - Ollama base URL.
+ */
+export declare function probeModel(model: string, host?: string): Promise<OllamaModelFacts>;
+/**
+ * Profile every model Ollama has locally: capabilities from `/api/show`,
+ * size from `/api/tags`.
+ *
+ * A model whose probe fails is reported with no capabilities, which lands it in
+ * the `chat` tier. That is the safe direction: an unreadable model is never
+ * advertised as agent-capable.
+ *
+ * @param host - Ollama base URL.
+ */
+export declare function probeModels(host?: string): Promise<ModelProfile[]>;
+export declare function createOllamaSource(host?: string): LocalCompletionSource;
+/** One chat turn as the network carries it. */
+export type ChatMessage = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** assistant turns only: calls the model already made */
+    tool_calls?: unknown[];
+    /** tool turns only: which call this answers */
+    tool_call_id?: string;
+};
+/** Incremental output of one chat completion. */
+export type ChatEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool-call';
+    index: number;
+    id?: string;
+    name?: string;
+    argumentsDelta: string;
+};
+/** A worker-side source that can serve a chat with tool schemas. */
+export type LocalChatSource = {
+    streamChat(req: {
+        model: string;
+        messages: ChatMessage[];
+        tools?: unknown[];
+        maxTokens?: number;
+    }, onEvent: (event: ChatEvent) => void, signal?: AbortSignal): Promise<{
+        completionTokens: number;
+        model: string;
+    }>;
+};
+/**
+ * Serve a chat with tools through Ollama's `/api/chat`.
+ *
+ * The legacy `/api/generate` path takes a single prompt string and therefore
+ * cannot carry tool schemas or tool results; this source exists so a worker can
+ * serve an agent, not only a chat box.
+ *
+ * Ollama reports tool calls as complete objects rather than deltas, so each one
+ * is emitted as a single `tool-call` event with the full arguments string.
+ */
+export declare function createOllamaChatSource(host?: string): LocalChatSource;
+//# sourceMappingURL=llmBridge.d.ts.map

package/dist/llmBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmBridge.d.ts","sourceRoot":"","sources":["../src/llmBridge.ts"],"names":[],"mappings":"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"}