elanous 0.2.4 → 0.2.6

package/src/plugins/maker/plugin-maker.ts

@@ -0,0 +1,208 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { elanousStateRoot } from '../../autopilot/state-paths.js';
+import { debug } from '../../debug/log.js';
+import { runGraph } from '../../graph-runner/runner.js';
+import { parseGraphTemplateYaml } from '../../self-implement/graph-yaml.js';
+import { installPlugin } from '../install/plugin-install.js';
+
+const CAPABILITIES = ['fs:workdir', 'proc:bun', 'proc:elanous'];
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+export interface MakePluginDeps {
+  codex: (dir: string, prompt: string) => Promise<void>;
+  install?: typeof installPlugin;
+  runGraph?: typeof runGraph;
+}
+export interface MakePluginOptions {
+  request: string;
+  name?: string;
+  parentDir?: string;
+  run?: boolean;
+  input?: unknown;
+  deps?: MakePluginDeps;
+}
+export interface MakePluginResult {
+  status: 'installed' | 'ran' | 'failed';
+  dir: string;
+  plugin: string;
+  graph: string;
+  errors: string[];
+  runStatus?: Awaited<ReturnType<typeof runGraph>>['status'];
+  timings: { scaffold: number; write: number; validate: number; repair?: number; install: number; run?: number };
+}
+
+export async function codexWrite(dir: string, prompt: string): Promise<void> {
+  const child = Bun.spawn(['codex', 'exec', '-C', dir, '-s', 'workspace-write', '--skip-git-repo-check', '-o', join(dir, '.codex-last-message.txt'), prompt], {
+    cwd: dir, stdin: 'ignore', stdout: 'ignore', stderr: 'pipe',
+  });
+  const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+  if (code !== 0) throw new Error(`codex exec failed (${code}): ${stderr.trim().slice(0, 500)}`);
+}
+
+function scaffold(dir: string, slug: string, request: string): void {
+  mkdirSync(join(dir, 'graphs'));
+  mkdirSync(join(dir, 'examples'));
+  writeFileSync(join(dir, 'plugin.json'), JSON.stringify({ name: slug, version: '0.1.0', description: request,
+    extensions: { 'ai.elanous': { graphs: [`./graphs/${slug}.yaml`], capabilities: CAPABILITIES } } }, null, 2) + '\n');
+  writeFileSync(join(dir, 'graphs', `${slug}.yaml`), `graph_id: ${slug}\nversion: 1\nentry_node: main\nterminal_nodes: [done, failed]\nnodes:\n  - { node_id: main, kind: agent, recipe: 'cmd:main', max_visits: 1 }\n  - { node_id: done, kind: gate, recipe: none, max_visits: 1 }\n  - { node_id: failed, kind: gate, recipe: none, max_visits: 1 }\nedges:\n  - { from: main, on: outcome, map: { ok: done, fail: failed } }\n`);
+  writeFileSync(join(dir, 'graphs', 'recipes.yaml'), `main:\n  command: 'bun "$ELANOUS_GRAPH_DIR/run-step.ts" main'\n  timeout_ms: 120000\n`);
+  writeFileSync(join(dir, 'graphs', 'run-step.ts'), `import { readFileSync } from 'node:fs';\nconst context = JSON.parse(readFileSync(process.env.ELANOUS_GRAPH_CONTEXT!, 'utf8'));\nconsole.log(JSON.stringify({ outcome: 'ok', input: context.input }));\n`);
+  writeFileSync(join(dir, 'examples', 'input.json'), '{}\n');
+  writeFileSync(join(dir, 'README.md'), `# ${slug}\n\n${request}\n\nRun the installed graph with examples/input.json as input. No messages are sent.\n`);
+}
+
+function inside(dir: string, path: string): string | undefined {
+  const full = resolve(dir, path);
+  return full.startsWith(`${dir}${sep}`) ? full : undefined;
+}
+
+function realTarget(path: string): string {
+  let ancestor = path;
+  while (!existsSync(ancestor)) {
+    const next = dirname(ancestor);
+    if (next === ancestor) throw new Error(`cannot resolve plugin directory: ${path}`);
+    ancestor = next;
+  }
+  return resolve(realpathSync(ancestor), relative(ancestor, path));
+}
+
+function assertLocalParent(parent: string): void {
+  const repoPlugins = realpathSync(resolve(import.meta.dir, '../../../plugins'));
+  const target = realTarget(parent);
+  if (target === repoPlugins || target.startsWith(`${repoPlugins}${sep}`)) {
+    throw new Error('repository plugins/ is not a local plugin directory');
+  }
+}
+
+export async function validatePluginDir(dir: string): Promise<string[]> {
+  const errors: string[] = [];
+  let manifest: unknown;
+  try {
+    const file = join(dir, 'plugin.json');
+    if (lstatSync(file).isSymbolicLink()) errors.push('안전하지 않은 plugin.json 링크');
+    else manifest = JSON.parse(readFileSync(file, 'utf8'));
+  }
+  catch (error) { errors.push(`plugin.json 파싱 실패: ${String(error)}`); }
+  const extension = isRecord(manifest) && isRecord(manifest.extensions) ? manifest.extensions['ai.elanous'] : undefined;
+  const graphs = isRecord(extension) ? extension.graphs : undefined;
+  if (isRecord(extension) && extension.contributes !== undefined) errors.push('extension contributes 덮어쓰기 금지');
+  if (!isRecord(manifest) || typeof manifest.name !== 'string' || !/^[a-z0-9][a-z0-9-]{1,39}$/.test(manifest.name) || typeof manifest.version !== 'string') errors.push('plugin.json 이름/버전 오류');
+  if (isRecord(manifest) && (manifest.capabilities !== undefined || manifest.contributes !== undefined || manifest.main !== undefined)) errors.push('plugin.json 최상위 권한/기여/main 덮어쓰기 금지');
+  if (!isRecord(extension) || !Array.isArray(extension.capabilities) || JSON.stringify(extension.capabilities) !== JSON.stringify(CAPABILITIES)) {
+    errors.push('capabilities 는 ["fs:workdir","proc:bun","proc:elanous"] 이어야 한다');
+  }
+  if (!Array.isArray(graphs) || graphs.length === 0 || !graphs.every(g => typeof g === 'string')) errors.push('plugin.json graphs 경로 없음');
+  let recipes: unknown;
+  try {
+    const file = join(dir, 'graphs', 'recipes.yaml');
+    if (lstatSync(file).isSymbolicLink()) errors.push('안전하지 않은 recipes.yaml 링크');
+    else recipes = parseYaml(readFileSync(file, 'utf8'));
+  }
+  catch (error) { errors.push(`recipes.yaml 파싱 실패: ${String(error)}`); }
+  if (!isRecord(recipes)) errors.push('recipes.yaml 은 맵이어야 한다');
+  else for (const [id, recipe] of Object.entries(recipes)) {
+    if (!isRecord(recipe) || typeof recipe.command !== 'string' || !recipe.command.trim() ||
+      (recipe.timeout_ms !== undefined && (!Number.isSafeInteger(recipe.timeout_ms) || Number(recipe.timeout_ms) <= 0))) errors.push(`잘못된 recipe: ${id}`);
+  }
+  for (const graph of Array.isArray(graphs) ? graphs : []) {
+    if (typeof graph !== 'string') continue;
+    const file = inside(dir, graph);
+    if (!file || !/^\.\/graphs\/[a-zA-Z0-9_-]+\.ya?ml$/.test(graph)) { errors.push(`안전하지 않은 graph 경로: ${graph}`); continue; }
+    try {
+      if (lstatSync(file).isSymbolicLink()) { errors.push(`안전하지 않은 graph 링크: ${graph}`); continue; }
+      const parsed = parseGraphTemplateYaml(readFileSync(file, 'utf8'), file);
+      errors.push(...parsed.errors.map(issue => `${issue.path}: ${issue.message}`));
+      const template = parsed.template;
+      if (!template) continue;
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(template.graphId)) errors.push(`잘못된 graph_id: ${template.graphId}`);
+      if (template.terminalNodes.length !== 2 || !template.terminalNodes.includes('done') || !template.terminalNodes.includes('failed')) errors.push('terminal_nodes 는 done, failed 이어야 한다');
+      const executionNodes = template.nodes.filter(node => !template.terminalNodes.includes(node.nodeId));
+      if (executionNodes.length < 2 || executionNodes.length > 6) errors.push(`실행 노드는 2~6개여야 한다: ${executionNodes.length}개`);
+      for (const node of template.nodes) {
+        if (node.recipe.startsWith('cmd:')) {
+          const id = node.recipe.slice(4);
+          if (!isRecord(recipes) || !isRecord(recipes[id]) || typeof recipes[id].command !== 'string' || !recipes[id].command) errors.push(`recipe ${id} 없음`);
+        } else if (node.recipe !== 'none') errors.push(`지원하지 않는 recipe: ${node.recipe}`);
+      }
+    } catch (error) { errors.push(`${graph} 파싱 실패: ${String(error)}`); }
+  }
+  const visit = (path: string): void => {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      const file = join(path, entry.name);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) { errors.push(`안전하지 않은 파일: ${file}`); continue; }
+      if (entry.isDirectory()) visit(file);
+      else if (/\.[cm]?[jt]sx?$/.test(entry.name)) {
+        const source = readFileSync(file, 'utf8');
+        for (const match of source.matchAll(/\b(?:import|export)\s*(?:[\s\S]*?\s+from\s*)?["']([^"']+)["']|\b(?:import|require)\s*\(\s*["']([^"']+)["']/g)) {
+          const target = match[1] ?? match[2]!;
+          if (/(?:^|\/)src\//.test(target) && (target.startsWith('/') || target.startsWith('.'))) errors.push(`src import 금지: ${file}: ${target}`);
+        }
+      }
+    }
+  };
+  try { visit(dir); } catch (error) { errors.push(`파일 검사 실패: ${String(error)}`); }
+  try {
+    const example = join(dir, 'examples', 'input.json');
+    if (lstatSync(example).isSymbolicLink()) errors.push('안전하지 않은 examples/input.json 링크');
+    else JSON.parse(readFileSync(example, 'utf8'));
+  } catch (error) { errors.push(`examples/input.json 파싱 실패: ${String(error)}`); }
+  const step = join(dir, 'graphs', 'run-step.ts');
+  try {
+    if (!existsSync(step)) errors.push('run-step.ts 없음');
+    else if (errors.some(error => error.startsWith('안전하지 않은 파일:'))) return errors;
+    else {
+      const build = await Bun.build({ entrypoints: [step], target: 'bun' });
+      if (!build.success) errors.push(...build.logs.map(log => `run-step.ts 문법 오류: ${log.message}`));
+    }
+  } catch (error) { errors.push(`run-step.ts 문법 오류: ${String(error)}`); }
+  return errors;
+}
+
+export async function makePlugin({ request, name, parentDir, run, input, deps }: MakePluginOptions): Promise<MakePluginResult> {
+  const slug = (name ?? request).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 32).replace(/-$/, '') || `plugin-${Date.now()}`;
+  if (!request.trim() || !/^[a-z0-9][a-z0-9-]{1,39}$/.test(slug)) throw new Error(`invalid plugin request or name: ${slug}`);
+  if (name !== undefined && !/^[a-z0-9][a-z0-9-]{1,31}$/.test(name)) throw new Error(`invalid --name slug: ${name}`);
+  const root = elanousStateRoot();
+  const parent = resolve(parentDir ?? join(root, 'plugins-local'));
+  assertLocalParent(parent);
+  const dir = join(parent, slug);
+  if (existsSync(dir)) throw new Error(`plugin directory already exists: ${dir}`);
+  const timings: MakePluginResult['timings'] = { scaffold: 0, write: 0, validate: 0, install: 0 };
+  const result: MakePluginResult = { status: 'failed', dir, plugin: slug, graph: join(dir, 'graphs', `${slug}.yaml`), errors: [], timings };
+  const step = async (stage: keyof MakePluginResult['timings'], action: () => void | Promise<void>): Promise<void> => {
+    const start = performance.now();
+    try { await action(); }
+    finally { const ms = Math.round(performance.now() - start); timings[stage] = ms; debug.log('plugin.maker', stage, { ms, errors: result.errors }); }
+  };
+  try {
+    await step('scaffold', () => { mkdirSync(parent, { recursive: true }); mkdirSync(dir); scaffold(dir, slug, request); });
+    const codex = deps?.codex ?? codexWrite;
+    const prompt = `요청 원문:\n${request}\n\n이 폴더의 뼈대를 수정해 작동하는 로컬 그래프 플러그인을 작성하라. plugin.json extensions["ai.elanous"].graphs 와 capabilities 는 유지하고, graphs/<id>.yaml 은 entry_node, terminal_nodes: [done, failed], nodes 의 recipe: 'cmd:<id>', edges 의 on: outcome, map: { ok, fail } 을 써라. graphs/recipes.yaml 에 모든 cmd:<id> 의 command: 'bun "$ELANOUS_GRAPH_DIR/run-step.ts" <id>' 와 timeout_ms 를 선언하라. graphs/run-step.ts 의 각 단계 stdout 마지막 줄은 JSON {outcome, ...} 이며 이전 출력은 ELANOUS_GRAPH_CONTEXT JSON 의 outputs 에 있다. src/ import 금지. 엘라누스 기능은 CLI elanous ask --json 또는 elanous research --json 로만 사용. 아무것도 보내지 말 것. 실행 노드는 2~6개. examples/input.json 에 실제로 돌릴 입력을 넣을 것. 폴더 밖에는 쓰지 말 것.`;
+    await step('write', () => codex(dir, prompt));
+    await step('validate', async () => { result.errors = await validatePluginDir(dir); });
+    if (result.errors.length) {
+      await step('repair', () => codex(dir, `${prompt}\n\n아래 오류를 모두 수리하라:\n${result.errors.join('\n')}`));
+      await step('validate', async () => { result.errors = await validatePluginDir(dir); });
+    }
+    if (result.errors.length) return result;
+    let installedPath = '';
+    await step('install', async () => { installedPath = (await (deps?.install ?? installPlugin)(dir, { yes: true, root })).path; });
+    result.status = 'installed';
+    const graph = JSON.parse(readFileSync(join(dir, 'plugin.json'), 'utf8')).extensions['ai.elanous'].graphs[0] as string;
+    result.graph = resolve(installedPath, graph);
+    if (run) {
+      await step('run', async () => {
+        const value = input === undefined ? JSON.parse(readFileSync(join(dir, 'examples', 'input.json'), 'utf8')) : input;
+        result.runStatus = (await (deps?.runGraph ?? runGraph)(result.graph, { input: value })).status;
+      });
+      result.status = result.runStatus === 'done' ? 'ran' : 'failed';
+      if (result.status === 'failed') result.errors.push(`graph run: ${result.runStatus}`);
+    }
+  } catch (error) {
+    result.status = 'failed';
+    result.errors.push(error instanceof Error ? error.message : String(error));
+  }
+  return result;
+}

package/src/prompt-library/universal-preamble.ts

@@ -59,6 +59,10 @@ export const PROJECT_ANCHOR_NON_CANDIDATE_FILENAMES = ['CLAUDE.md'] as const;
 export const PROJECT_TREE_MAX_CHARS = 8 * 1024;
 export const PROJECT_TREE_DIR_ENTRY_LIMIT = 20;
 
+const NO_TOOLS_VERIFICATION_GUIDANCE = `## Chat without tools — verify rather than guess
+This conversation has tools disabled. Do not guess repository or real-time facts that require verification, such as file counts, file contents, commits, or the current time. Say you cannot check them here. The project tree above is for navigation, not evidence for counts.
+To check these facts, enable tools with \`elanous agent …\` or \`elanous chat --tools …\`.`;
+
 // P4 (2026-05-03) — Family-agnostic coding-agent lifecycle. Maps the
 // three user-facing pipelines to an explicit tool-batch sequence so every
 // model (not just codex) follows the same shape. Pattern source:
@@ -673,8 +677,7 @@ export function loadProjectAnchor(cwd: string): ProjectAnchorResult {
   return result;
 }
 
-/** Build the surface-agnostic preamble. Currently MVP — emits zero or
- *  one system message (project anchor). Surfaces spread the result
+/** Build the surface-agnostic preamble. Surfaces spread the result
  *  into their own preamble; e.g.
  *
  *  ```ts
@@ -729,6 +732,9 @@ export function buildUniversalPreamble(ctx: UniversalPreambleContext): LLMMessag
       content: `## Project Layout (top-level + 1 depth)\n\n\`\`\`\n${tree.content}\n\`\`\`\n\nUse this layout to pick directories directly instead of issuing broad project-root Grep/Glob calls. When AGENTS.md / CLAUDE.md describe a track or subsystem, this layout shows where its files actually live.`,
     });
   }
+  if (!ctx.enabledTools?.length) {
+    out.push({ role: 'system', content: NO_TOOLS_VERIFICATION_GUIDANCE });
+  }
   // P4 (2026-05-03) — Family-agnostic coding-agent lifecycle. Append
   // before family addendum so codex (which has its own discipline
   // overlay) sees both: lifecycle (what shape) + addendum (how to behave

package/src/relay/channel.ts

@@ -0,0 +1,184 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import sodium from 'libsodium-wrappers';
+
+/** Maximum size of a complete encrypted frame, including sequence and MAC. */
+export const MAX_FRAME_BYTES = 1024 * 1024;
+const SEQUENCE_BYTES = 8;
+const MAC_BYTES = 16;
+const NONCE_BYTES = 24;
+const MAX_SEQUENCE = (1n << 64n) - 1n;
+
+export type ChannelResult<T> = { ok: true; value: T } | { ok: false; reason: string };
+export interface DaemonKeyPair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+export interface SerializedDaemonKeyPair {
+  publicKey: string;
+  secretKey: string;
+}
+
+function rejected<T>(reason: string): ChannelResult<T> {
+  return { ok: false, reason };
+}
+
+function validKey(key: Uint8Array): boolean {
+  return key instanceof Uint8Array && key.length === 32;
+}
+
+function equalKeys(left: Uint8Array, right: Uint8Array): boolean {
+  return validKey(left) && validKey(right) && timingSafeEqual(left, right);
+}
+
+/** The daemon persists this pair; the phone creates a fresh pair per connection. */
+export async function generateDaemonKeyPair(seed?: Uint8Array): Promise<DaemonKeyPair> {
+  await sodium.ready;
+  if (seed !== undefined && !validKey(seed)) throw new RangeError('X25519 seed must be 32 bytes');
+  const pair = seed === undefined ? sodium.crypto_kx_keypair() : sodium.crypto_kx_seed_keypair(seed);
+  return { publicKey: pair.publicKey, secretKey: pair.privateKey };
+}
+
+export function serverIdFromPublicKey(publicKey: Uint8Array): string {
+  if (!validKey(publicKey)) throw new RangeError('X25519 public key must be 32 bytes');
+  return createHash('sha256').update(publicKey).digest('hex');
+}
+
+export function serializeDaemonKeyPair(pair: DaemonKeyPair): SerializedDaemonKeyPair {
+  if (!validKey(pair.publicKey) || !validKey(pair.secretKey)) throw new RangeError('invalid X25519 key pair');
+  return { publicKey: Buffer.from(pair.publicKey).toString('base64'), secretKey: Buffer.from(pair.secretKey).toString('base64') };
+}
+
+export async function deserializeDaemonKeyPair(serialized: SerializedDaemonKeyPair): Promise<ChannelResult<DaemonKeyPair>> {
+  await sodium.ready;
+  if (typeof serialized?.publicKey !== 'string' || typeof serialized?.secretKey !== 'string' ||
+      !/^[A-Za-z0-9+/]{43}=$/.test(serialized.publicKey) || !/^[A-Za-z0-9+/]{43}=$/.test(serialized.secretKey)) {
+    return rejected('invalid daemon key serialization');
+  }
+  const publicKey = new Uint8Array(Buffer.from(serialized.publicKey, 'base64'));
+  const secretKey = new Uint8Array(Buffer.from(serialized.secretKey, 'base64'));
+  try {
+    if (!validKey(publicKey) || !validKey(secretKey) ||
+        !equalKeys(sodium.crypto_scalarmult_base(secretKey), publicKey)) {
+      return rejected('invalid daemon key pair');
+    }
+  } catch {
+    return rejected('invalid daemon key pair');
+  }
+  return { ok: true, value: { publicKey, secretKey } };
+}
+
+function sequenceBytes(sequence: bigint): Uint8Array {
+  const bytes = new Uint8Array(SEQUENCE_BYTES);
+  new DataView(bytes.buffer).setBigUint64(0, sequence, false);
+  return bytes;
+}
+
+function nonceFor(sequence: bigint): Uint8Array {
+  const nonce = new Uint8Array(NONCE_BYTES);
+  nonce.set(sequenceBytes(sequence), NONCE_BYTES - SEQUENCE_BYTES);
+  return nonce;
+}
+
+/** Each direction uses its own crypto_kx key and monotonically increasing sequence. */
+export class EncryptedChannel {
+  private sendSequence = 0n;
+  private receiveSequence = 0n;
+  private readonly sendKey: Uint8Array;
+  private readonly receiveKey: Uint8Array;
+
+  constructor(sendKey: Uint8Array, receiveKey: Uint8Array) {
+    if (!validKey(sendKey) || !validKey(receiveKey)) throw new RangeError('invalid session keys');
+    this.sendKey = new Uint8Array(sendKey);
+    this.receiveKey = new Uint8Array(receiveKey);
+  }
+
+  seal(plaintext: Uint8Array): ChannelResult<Uint8Array> {
+    if (!(plaintext instanceof Uint8Array)) return rejected('invalid plaintext');
+    if (plaintext.length + SEQUENCE_BYTES + MAC_BYTES > MAX_FRAME_BYTES) return rejected('frame exceeds 1MB');
+    if (this.sendSequence > MAX_SEQUENCE) return rejected('send sequence exhausted');
+    const header = sequenceBytes(this.sendSequence);
+    try {
+      const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
+        plaintext, header, null, nonceFor(this.sendSequence), this.sendKey,
+      );
+      const frame = new Uint8Array(header.length + ciphertext.length);
+      frame.set(header);
+      frame.set(ciphertext, header.length);
+      this.sendSequence++;
+      return { ok: true, value: frame };
+    } catch {
+      return rejected('frame encryption failed');
+    }
+  }
+
+  open(frame: Uint8Array): ChannelResult<Uint8Array> {
+    if (!(frame instanceof Uint8Array) || frame.length < SEQUENCE_BYTES + MAC_BYTES) return rejected('invalid frame');
+    if (frame.length > MAX_FRAME_BYTES) return rejected('frame exceeds 1MB');
+    if (this.receiveSequence > MAX_SEQUENCE) return rejected('receive sequence exhausted');
+    const sequence = new DataView(frame.buffer, frame.byteOffset, SEQUENCE_BYTES).getBigUint64(0, false);
+    if (sequence < this.receiveSequence) return rejected('replayed frame');
+    if (sequence > this.receiveSequence) return rejected('out-of-order frame');
+    const header = frame.subarray(0, SEQUENCE_BYTES);
+    try {
+      const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(
+        null, frame.subarray(SEQUENCE_BYTES), header, nonceFor(sequence), this.receiveKey,
+      );
+      this.receiveSequence++;
+      return { ok: true, value: plaintext };
+    } catch {
+      return rejected('frame authentication failed');
+    }
+  }
+}
+
+export interface PhoneChannel {
+  /** Sent to the daemon during handshake; the private key stays on the phone. */
+  phonePublicKey: Uint8Array;
+  serverId: string;
+  channel: EncryptedChannel;
+}
+
+/** Pin the daemon's public key before deriving any traffic keys. */
+export async function createPhoneChannel(
+  daemonPublicKey: Uint8Array,
+  expectedDaemonPublicKey: Uint8Array,
+  phoneSeed?: Uint8Array,
+): Promise<ChannelResult<PhoneChannel>> {
+  await sodium.ready;
+  if (!validKey(daemonPublicKey) || !equalKeys(daemonPublicKey, expectedDaemonPublicKey)) {
+    return rejected('wrong daemon public key');
+  }
+  if (phoneSeed !== undefined && !validKey(phoneSeed)) return rejected('invalid phone seed');
+  const phoneKeys = phoneSeed === undefined ? sodium.crypto_kx_keypair() : sodium.crypto_kx_seed_keypair(phoneSeed);
+  try {
+    const keys = sodium.crypto_kx_client_session_keys(phoneKeys.publicKey, phoneKeys.privateKey, daemonPublicKey);
+    return { ok: true, value: {
+      phonePublicKey: phoneKeys.publicKey,
+      serverId: serverIdFromPublicKey(daemonPublicKey),
+      channel: new EncryptedChannel(keys.sharedTx, keys.sharedRx),
+    } };
+  } catch {
+    return rejected('invalid daemon public key');
+  }
+}
+
+/** Called with the phone's ephemeral public key; crypto_kx supplies opposite Tx/Rx keys. */
+export async function acceptDaemonChannel(
+  daemonKeys: DaemonKeyPair,
+  phonePublicKey: Uint8Array,
+): Promise<ChannelResult<EncryptedChannel>> {
+  await sodium.ready;
+  if (!validKey(daemonKeys?.publicKey) || !validKey(daemonKeys?.secretKey)) {
+    return rejected('invalid daemon key pair');
+  }
+  if (!validKey(phonePublicKey)) return rejected('invalid phone public key');
+  try {
+    if (!equalKeys(sodium.crypto_scalarmult_base(daemonKeys.secretKey), daemonKeys.publicKey)) {
+      return rejected('invalid daemon key pair');
+    }
+    const keys = sodium.crypto_kx_server_session_keys(daemonKeys.publicKey, daemonKeys.secretKey, phonePublicKey);
+    return { ok: true, value: new EncryptedChannel(keys.sharedTx, keys.sharedRx) };
+  } catch {
+    return rejected('invalid handshake key');
+  }
+}

package/src/relay/mux.ts

@@ -0,0 +1,182 @@
+import { MAX_FRAME_BYTES } from './channel.js';
+import type { ChannelResult } from './channel.js';
+
+export type MuxFrame =
+  | { streamId: number; kind: 'open'; protocol: 'http'; method: string; path: string; headers: Record<string, string> }
+  | { streamId: number; kind: 'open'; protocol: 'ws'; path: string; headers: Record<string, string> }
+  | { streamId: number; kind: 'data'; data: Uint8Array }
+  | { streamId: number; kind: 'close'; reason: string };
+
+// u32 BE length (remaining bytes), u32 BE stream ID, u8 kind (1=open, 2=data, 3=close).
+// Open: u8 protocol (1=http, 2=ws), [http: u16 method bytes + UTF-8 method],
+// u32 path bytes + UTF-8 path, u16 header count, then u16 name bytes + UTF-8 name,
+// u16 value bytes + UTF-8 value per header. Data: remaining raw bytes.
+// Close: u16 reason bytes + UTF-8 reason. One frame per encrypted plaintext.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const HEADER_BYTES = 9;
+// EncryptedChannel appends an 8-byte sequence and 16-byte MAC to each plaintext.
+export const MAX_MUX_FRAME_BYTES = MAX_FRAME_BYTES - 24;
+
+type Result<T> = ChannelResult<T>;
+function reject<T>(reason: string): Result<T> { return { ok: false, reason }; }
+
+class Writer {
+  private parts: Uint8Array[] = [];
+  length = 0;
+  bytes(value: Uint8Array) { this.parts.push(value); this.length += value.length; }
+  number(value: number, size: 1 | 2 | 4) {
+    const bytes = new Uint8Array(size);
+    const view = new DataView(bytes.buffer);
+    if (size === 1) view.setUint8(0, value);
+    else if (size === 2) view.setUint16(0, value, false);
+    else view.setUint32(0, value, false);
+    this.bytes(bytes);
+  }
+  text(value: string, size: 2 | 4): boolean {
+    if (typeof value !== 'string') return false;
+    const bytes = encoder.encode(value);
+    if (bytes.length > (size === 2 ? 0xffff : 0xffffffff)) return false;
+    this.number(bytes.length, size);
+    this.bytes(bytes);
+    return true;
+  }
+  finish(): Uint8Array {
+    const out = new Uint8Array(this.length);
+    let offset = 0;
+    for (const part of this.parts) { out.set(part, offset); offset += part.length; }
+    return out;
+  }
+}
+
+class Reader {
+  offset = 0;
+  constructor(readonly bytes: Uint8Array) {}
+  number(size: 1 | 2 | 4): number | undefined {
+    if (this.offset + size > this.bytes.length) return undefined;
+    const view = new DataView(this.bytes.buffer, this.bytes.byteOffset + this.offset, size);
+    this.offset += size;
+    return size === 1 ? view.getUint8(0) : size === 2 ? view.getUint16(0, false) : view.getUint32(0, false);
+  }
+  text(size: 2 | 4): string | undefined {
+    const length = this.number(size);
+    if (length === undefined || this.offset + length > this.bytes.length) return undefined;
+    const bytes = this.bytes.subarray(this.offset, this.offset + length);
+    this.offset += length;
+    return decoder.decode(bytes);
+  }
+}
+
+function validId(id: number): boolean { return Number.isInteger(id) && id >= 0 && id <= 0xffffffff; }
+
+/** Share one instance between the encoder and decoder of a single endpoint. */
+export class MuxStreamState {
+  private readonly active = new Set<number>();
+
+  isOpen(id: number): boolean { return this.active.has(id); }
+  opened(id: number): void { this.active.add(id); }
+  closed(id: number): void { this.active.delete(id); }
+}
+
+/** No network I/O; shares stream IDs with the receiving decoder when supplied a state. */
+export class MuxEncoder {
+  constructor(private readonly streams: MuxStreamState = new MuxStreamState()) {}
+
+  encode(frame: MuxFrame): Result<Uint8Array> {
+    if (!frame || !validId(frame.streamId)) return reject('invalid stream ID');
+    if (frame.kind !== 'open' && frame.kind !== 'data' && frame.kind !== 'close') return reject('unknown frame kind');
+    if (frame.kind === 'open' ? this.streams.isOpen(frame.streamId) : !this.streams.isOpen(frame.streamId)) {
+      return reject(frame.kind === 'open' ? 'stream already open' : 'stream not open');
+    }
+    const writer = new Writer();
+    writer.number(0, 4);
+    writer.number(frame.streamId, 4);
+    if (frame.kind === 'open') {
+      writer.number(1, 1);
+      if (frame.protocol !== 'http' && frame.protocol !== 'ws') return reject('unknown protocol');
+      writer.number(frame.protocol === 'http' ? 1 : 2, 1);
+      if (frame.protocol === 'http' && (!frame.method || !writer.text(frame.method, 2))) return reject('invalid method');
+      if (!frame.path || !writer.text(frame.path, 4)) return reject('invalid path');
+      if (!frame.headers || typeof frame.headers !== 'object' || Array.isArray(frame.headers)) return reject('invalid headers');
+      const entries = Object.entries(frame.headers);
+      if (entries.length > 0xffff) return reject('invalid headers');
+      writer.number(entries.length, 2);
+      for (const [name, value] of entries) {
+        if (!name || !writer.text(name, 2) || !writer.text(value, 2)) return reject('invalid headers');
+      }
+    } else if (frame.kind === 'data') {
+      if (!(frame.data instanceof Uint8Array)) return reject('invalid data');
+      writer.number(2, 1);
+      writer.bytes(frame.data);
+    } else if (frame.kind === 'close') {
+      writer.number(3, 1);
+      if (!writer.text(frame.reason, 2)) return reject('invalid reason');
+    }
+    if (writer.length > MAX_MUX_FRAME_BYTES) return reject('frame exceeds 1MB');
+    const out = writer.finish();
+    new DataView(out.buffer).setUint32(0, out.length - 4, false);
+    if (frame.kind === 'open') this.streams.opened(frame.streamId);
+    if (frame.kind === 'close') this.streams.closed(frame.streamId);
+    return { ok: true, value: out };
+  }
+}
+
+/** Rejected frames never change stream state. Share state with the sending encoder per endpoint. */
+export class MuxDecoder {
+  constructor(private readonly streams: MuxStreamState = new MuxStreamState()) {}
+
+  decode(bytes: Uint8Array): Result<MuxFrame> {
+    if (!(bytes instanceof Uint8Array)) return reject('invalid frame');
+    if (bytes.length > MAX_MUX_FRAME_BYTES) return reject('frame exceeds 1MB');
+    if (bytes.length < HEADER_BYTES) return reject('truncated frame');
+    const reader = new Reader(bytes);
+    const length = reader.number(4)!;
+    if (length !== bytes.length - 4) return reject(length > bytes.length - 4 ? 'truncated frame' : 'trailing frame bytes');
+    const streamId = reader.number(4)!;
+    const kind = reader.number(1)!;
+    if (kind !== 1 && kind !== 2 && kind !== 3) return reject('unknown frame kind');
+    if (kind === 1 ? this.streams.isOpen(streamId) : !this.streams.isOpen(streamId)) {
+      return reject(kind === 1 ? 'stream already open' : 'stream not open');
+    }
+    try {
+      let frame: MuxFrame;
+      if (kind === 1) {
+        const protocolByte = reader.number(1);
+        if (protocolByte !== 1 && protocolByte !== 2) return reject(protocolByte === undefined ? 'truncated frame' : 'unknown protocol');
+        const method = protocolByte === 1 ? reader.text(2) : undefined;
+        if (protocolByte === 1 && method === undefined) return reject('truncated frame');
+        const path = reader.text(4);
+        const count = reader.number(2);
+        if (path === undefined || count === undefined) return reject('truncated frame');
+        if (!path || (protocolByte === 1 && !method)) return reject('invalid open frame');
+        const entries: [string, string][] = [];
+        const names = new Set<string>();
+        for (let i = 0; i < count; i++) {
+          const name = reader.text(2);
+          const value = reader.text(2);
+          if (name === undefined || value === undefined) return reject('truncated frame');
+          if (!name || names.has(name)) return reject('invalid headers');
+          names.add(name);
+          entries.push([name, value]);
+        }
+        const headers = Object.fromEntries(entries);
+        frame = protocolByte === 1
+          ? { streamId, kind: 'open', protocol: 'http', method: method!, path, headers }
+          : { streamId, kind: 'open', protocol: 'ws', path, headers };
+      } else if (kind === 2) {
+        frame = { streamId, kind: 'data', data: bytes.slice(reader.offset) };
+        reader.offset = bytes.length;
+      } else {
+        const reason = reader.text(2);
+        if (reason === undefined) return reject('truncated frame');
+        frame = { streamId, kind: 'close', reason };
+      }
+      if (reader.offset !== bytes.length) return reject('trailing frame bytes');
+      if (kind === 1) this.streams.opened(streamId);
+      if (kind === 3) this.streams.closed(streamId);
+      return { ok: true, value: frame };
+    } catch {
+      return reject('invalid UTF-8 frame');
+    }
+  }
+}

package/src/relay/test-vectors.json

@@ -0,0 +1,29 @@
+{
+  "daemonSeedHex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+  "phoneSeedHex": "202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f",
+  "daemonPublicKeyHex": "0e0216223f147143d32615a91189c288c1728cba3cc5f9f621b1026e03d83129",
+  "phonePublicKeyHex": "99f4674ecc87c0b8e712f192b8f49e7442a9376b4875967ababa28471019a93e",
+  "serverId": "4bc447d530c4044729c44372319cebfcbe079462826a6d39ea4828b149f9c685",
+  "phoneToDaemonKeySha256": "1fd0e0a3bd4e5afff9efb91653c4e67f549b2aaf26e8fea9a5fb263cbd987ea0",
+  "daemonToPhoneKeySha256": "534f8e2462d2bfe07a31cc43a2fd7a46d6109c31289c971c17626324b9806ee8",
+  "nonceHex": "000000000000000000000000000000000000000000000000",
+  "request": {
+    "streamId": 16909060,
+    "kind": "open",
+    "protocol": "http",
+    "method": "POST",
+    "path": "/v1/health",
+    "headers": {
+      "authorization": "Bearer vector-token"
+    }
+  },
+  "requestMuxHex": "000000400102030401010004504f53540000000a2f76312f6865616c74680001000d617574686f72697a6174696f6e001342656172657220766563746f722d746f6b656e",
+  "requestEncryptedHex": "0000000000000000d793343f86630442fcf3812bc1375c4b102aa1ffd546ac4ecbd5f5f4e9e4b3c2de47616a01df19b25b317cd0c5f3c2f0aa7a8b12f307c9872c5f03765a0b1c0e6b6f46dcbda1758ae286b475870eb7ad957f409e",
+  "response": {
+    "streamId": 16909060,
+    "kind": "data",
+    "dataHex": "00ff1020"
+  },
+  "responseMuxHex": "00000009010203040200ff1020",
+  "responseEncryptedHex": "0000000000000000bf589589e25e990a1c7da5fb7a773f0a798e84d1f444d51bd8e3e0bdb4"
+}