fuli-context 0.12.0 → 0.12.2

package/src/agent-peer/protocol.js

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
+
+export const PEER_PROTOCOL = 'peer/1';
+export const PEER_LIMITS = Object.freeze({
+  requestBytes: 64 * 1024,
+  responseBytes: 1024 * 1024,
+  messageChars: 16_000,
+  queuePerNode: 100,
+  directoryAgents: 50,
+  defaultTtlSeconds: 30 * 60,
+  maxTtlSeconds: 30 * 60,
+  acceptSeconds: 15,
+  leaseSeconds: 60,
+  renewSeconds: 15,
+  claimWaitMs: 20_000,
+  maxDepth: 3,
+  maxStartAttempts: 3,
+  invitationSeconds: 10 * 60,
+  executionSeconds: 900,
+});
+export const MESSAGE_STATUSES = Object.freeze(['queued', 'claimed', 'running', 'answered', 'failed', 'cancelled', 'expired', 'unknown']);
+export const TERMINAL_STATUSES = new Set(['answered', 'failed', 'cancelled', 'expired', 'unknown']);
+export const RESULT_OUTCOMES = new Set(['answered', 'failed', 'cancelled', 'unknown', 'never_started']);
+
+const INVITATION_PREFIX = 'fuli-peer-invite:1:';
+const FINGERPRINT = /^[0-9a-f]{64}$/;
+const OPAQUE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+export class PeerError extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function isFingerprint(value) {
+  return typeof value === 'string' && FINGERPRINT.test(value);
+}
+
+export function isOpaqueId(value) {
+  return typeof value === 'string' && OPAQUE_ID.test(value);
+}
+
+// Persisted and signed times are compared as text, so only the canonical
+// UTC form produced by Date#toISOString is accepted.
+export function canonicalTime(value) {
+  if (typeof value !== 'string') return null;
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value ? time : null;
+}
+
+export function shortFingerprint(fingerprint) {
+  return fingerprint.slice(0, 24).toUpperCase().match(/.{4}/g).join(' ');
+}
+
+// Signatures cover a canonical form, so property order never changes meaning.
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).filter((key) => value[key] !== undefined).sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+export function sha256Hex(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function coordinatorUrl(host, port) {
+  if (!isIP(host)) throw new PeerError('invalid_address', 'The coordinator address must be an IP address');
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) throw new PeerError('invalid_address', 'Invalid coordinator port');
+  return `https://${isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+}
+
+export function encodeInvitation({ url, fingerprint, code, expiresAt, name, certificate, authority }) {
+  const payload = { a: url, f: fingerprint, c: code, e: expiresAt, n: name, k: certificate, o: authority };
+  return INVITATION_PREFIX + Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+// An invitation carries the coordinator certificate, so the joining device
+// trusts exactly that certificate from its first connection.
+export function decodeInvitation(text, { now = Date.now() } = {}) {
+  const value = String(text ?? '').trim();
+  if (!value.startsWith(INVITATION_PREFIX) || value.length > 8192) {
+    throw new PeerError('invalid_invitation', 'This is not a FULI device invitation');
+  }
+  let payload;
+  try { payload = JSON.parse(Buffer.from(value.slice(INVITATION_PREFIX.length), 'base64url').toString('utf8')); }
+  catch { throw new PeerError('invalid_invitation', 'This is not a FULI device invitation'); }
+  const url = parseCoordinatorUrl(payload?.a);
+  if (!isFingerprint(payload?.f) || typeof payload?.c !== 'string' || payload.c.length < 32 || payload.c.length > 128
+    || typeof payload?.k !== 'string' || typeof payload?.e !== 'string'
+    || typeof payload?.o?.keyId !== 'string' || typeof payload?.o?.publicKey !== 'string') {
+    throw new PeerError('invalid_invitation', 'This is not a FULI device invitation');
+  }
+  const certificate = Buffer.from(payload.k, 'base64');
+  if (sha256Hex(certificate) !== payload.f) throw new PeerError('invalid_invitation', 'The invitation fingerprint does not match its certificate');
+  if (!(canonicalTime(payload.e) > now)) throw new PeerError('invitation_expired', 'This invitation has expired', 410);
+  return { url, fingerprint: payload.f, code: payload.c, expiresAt: payload.e,
+    name: typeof payload.n === 'string' ? payload.n.slice(0, 80) : '', certificatePem: derToPem(certificate),
+    authority: { keyId: payload.o.keyId, publicKey: payload.o.publicKey } };
+}
+
+export function parseCoordinatorUrl(value) {
+  let url;
+  try { url = new URL(String(value ?? '')); } catch { throw new PeerError('invalid_address', 'Invalid coordinator address'); }
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  if (url.protocol !== 'https:' || !isIP(host) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new PeerError('invalid_address', 'The coordinator address must be https://IP:port');
+  }
+  return url.origin;
+}
+
+export function derToPem(der) {
+  return `-----BEGIN CERTIFICATE-----\n${Buffer.from(der).toString('base64').match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE-----\n`;
+}
+
+export function pemToDer(pem) {
+  const body = String(pem ?? '').match(/-----BEGIN CERTIFICATE-----([\s\S]+?)-----END CERTIFICATE-----/)?.[1];
+  if (!body) throw new PeerError('invalid_certificate', 'Invalid device certificate');
+  return Buffer.from(body.replace(/\s+/g, ''), 'base64');
+}
+
+// The signed request a sending device makes on behalf of one verified local task.
+export function validateAssertion(assertion, { now = Date.now() } = {}) {
+  const fail = (message) => { throw new PeerError('invalid_message', message); };
+  if (!assertion || typeof assertion !== 'object' || assertion.protocol !== PEER_PROTOCOL) fail('Unsupported message protocol');
+  if (!isOpaqueId(assertion.messageId) || !isOpaqueId(assertion.threadId)) fail('Invalid message identity');
+  const { from, to } = assertion;
+  if (!isFingerprint(from?.node) || !isOpaqueId(from?.agentId) || typeof from?.name !== 'string' || from.name.length > 120) fail('Invalid sender');
+  if (!isFingerprint(to?.node) || !isOpaqueId(to?.bindingId) || !isOpaqueId(to?.agentId)) fail('Invalid recipient');
+  if (from.node === to.node) fail('A device cannot send a remote message to itself');
+  if (typeof assertion.body !== 'string' || !assertion.body.trim() || assertion.body.length > PEER_LIMITS.messageChars) fail('Invalid message body');
+  if (!['auto', 'new'].includes(assertion.conversation)) fail('Invalid conversation policy');
+  if (!Number.isSafeInteger(assertion.depth) || assertion.depth < 1 || assertion.depth > PEER_LIMITS.maxDepth) {
+    throw new PeerError('budget_exceeded', 'This conversation reached its cross-device depth limit');
+  }
+  const origin = assertion.origin;
+  if (!origin || typeof origin.payload !== 'string' || typeof origin.signature !== 'string'
+    || origin.payload.length > 4096 || origin.signature.length > 128 || Object.keys(origin).length !== 2) {
+    fail('A remote message needs its origin proof');
+  }
+  const issued = canonicalTime(assertion.issuedAt);
+  const expires = canonicalTime(assertion.expiresAt);
+  if (issued === null || expires === null) fail('Message times must be canonical UTC ISO timestamps');
+  if (!(issued <= now + 60_000) || !(expires > issued) || expires - issued > PEER_LIMITS.maxTtlSeconds * 1000) fail('Invalid message lifetime');
+  if (expires <= now) throw new PeerError('message_expired', 'This message has expired', 410);
+  return assertion;
+}
+
+export function publicDirectoryEntry(entry) {
+  if (!isOpaqueId(entry?.bindingId) || !isOpaqueId(entry?.agentId)) throw new PeerError('invalid_directory', 'Invalid shared Agent');
+  const text = (value, max) => typeof value === 'string' ? value.slice(0, max) : null;
+  return { bindingId: entry.bindingId, agentId: entry.agentId, name: text(entry.name, 120) ?? entry.agentId,
+    employeeNumber: text(entry.employeeNumber, 32), responsibility: text(entry.responsibility, 500),
+    projectName: text(entry.projectName, 120),
+    clients: (Array.isArray(entry.clients) ? entry.clients : []).filter((client) => isOpaqueId(client)).slice(0, 4) };
+}

package/src/agent-peer/runner.js

@@ -0,0 +1,251 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { certificateFingerprint, verifyDeviceSignature } from './device-identity.js';
+import { isAuthorityKey, verifyOriginProof } from './origin-proof.js';
+import { PEER_LIMITS, PeerError, validateAssertion } from './protocol.js';
+
+const RETRY_MS = 5_000;
+const STARTED_STATES = new Set(['starting', 'running', 'finished']);
+
+// Receives asks for this device's shared project leads. Every claim is written
+// down before it is accepted, nothing runs before the coordinator confirmed the
+// acceptance, and an attempt that may have run is never reported as not started.
+export function createPeerRunner({ store, client, roundtable, provider, nodeId, spaceId,
+  clock = Date.now, retryMs = RETRY_MS, renewMs = PEER_LIMITS.renewSeconds * 1000, onError = () => {} }) {
+  const stopping = new AbortController();
+  const running = new Map();
+  const handlers = new Map();
+  let loop = null;
+
+  function start() {
+    loop ??= run();
+    return loop;
+  }
+
+  async function run() {
+    recover();
+    while (!stopping.signal.aborted) {
+      await flush();
+      let claim = null;
+      try {
+        claim = (await client.post('/peer/1/claim', {}, { signal: stopping.signal,
+          timeoutMs: PEER_LIMITS.claimWaitMs + 10_000 })).claim;
+      } catch (error) {
+        if (stopping.signal.aborted) break;
+        onError(error);
+        await pause(retryMs);
+        continue;
+      }
+      if (claim) handle(claim).catch(onError);
+    }
+  }
+
+  // After a restart nothing from a previous run is still being supervised.
+  function recover() {
+    for (const attempt of store.unfinishedAttempts()) {
+      const started = STARTED_STATES.has(attempt.state);
+      queue(attempt.message_id, attempt.attempt_id, started ? 'unknown' : 'never_started',
+        { error: started ? 'runner_restarted' : 'not_started' });
+    }
+  }
+
+  // Tracked so stop() can wait for every handler before the store is closed.
+  function handle(claim) {
+    const work = handleClaim(claim);
+    handlers.set(work, claim.messageId);
+    return work.finally(() => handlers.delete(work));
+  }
+
+  async function handleClaim(claim) {
+    const { messageId, attemptId } = claim;
+    // Not accepted: the coordinator hands the claim out again after its short window.
+    if (stopping.signal.aborted) return;
+    if (!store.recordAttempt({ messageId, attemptId, bindingId: claim.assertion?.to?.bindingId }).inserted) return;
+    let acceptance;
+    const acceptedAt = clock();
+    try {
+      acceptance = await client.post('/peer/1/renew', { messageId, attemptId, state: 'accepted' }, { signal: stopping.signal });
+      if (stopping.signal.aborted) throw new PeerError('stopped', 'The runner stopped while accepting', 499);
+    } catch (error) {
+      // The acceptance may or may not have been recorded; the coordinator decides
+      // between requeueing and unknown. Nothing was started here either way.
+      store.setAttemptState(messageId, attemptId, 'not_started', error.code ?? 'accept_failed');
+      queue(messageId, attemptId, 'never_started', { error: error.code ?? 'accept_failed' });
+      return flush();
+    }
+    store.setAttemptState(messageId, attemptId, 'accepted');
+    if (acceptance?.cancel) {
+      store.setAttemptState(messageId, attemptId, 'not_started', 'cancelled');
+      queue(messageId, attemptId, 'cancelled', { error: 'cancelled' });
+      return flush();
+    }
+    let authorized;
+    try {
+      authorized = authorize(claim);
+    } catch (error) {
+      store.setAttemptState(messageId, attemptId, 'rejected', error.code ?? 'rejected');
+      queue(messageId, attemptId, 'failed', { error: error.code ?? 'rejected' });
+      return flush();
+    }
+    if (stopping.signal.aborted) {
+      store.setAttemptState(messageId, attemptId, 'not_started', 'stopped');
+      queue(messageId, attemptId, 'never_started', { error: 'stopped' });
+      return flush();
+    }
+    store.setAttemptState(messageId, attemptId, 'starting');
+    const outcome = await supervise(claim, authorized, acceptedAt);
+    store.setAttemptState(messageId, attemptId, 'finished', outcome.outcome);
+    queue(messageId, attemptId, outcome.outcome, outcome);
+    return flush();
+  }
+
+  // Every check that decides whether this device may act, before any authority is issued.
+  function authorize(claim) {
+    const { assertion, signature, sender } = claim;
+    validateAssertion(assertion, { now: clock() });
+    if (!sender || certificateFingerprint(sender.certPem) !== sender.nodeId || assertion.from.node !== sender.nodeId) {
+      throw new PeerError('sender_mismatch', 'The message sender does not match its device', 403);
+    }
+    if (!verifyDeviceSignature(sender.certPem, assertion, signature)) throw new PeerError('invalid_signature', 'Invalid device signature', 403);
+    if (assertion.to.node !== nodeId) throw new PeerError('wrong_device', 'The message is for another device', 403);
+    const share = store.share(assertion.to.bindingId);
+    if (!share || share.agentId !== assertion.to.agentId || share.spaceId !== spaceId()) {
+      throw new PeerError('agent_not_shared', 'That Agent is not shared on this device', 403);
+    }
+    const authority = pinnedAuthority(sender);
+    const origin = verifyOriginProof(assertion, authority, { now: clock() });
+    const earlier = store.attemptsFor(claim.messageId)
+      .filter((attempt) => attempt.attempt_id !== claim.attemptId && STARTED_STATES.has(attempt.state));
+    if (earlier.length) throw new PeerError('already_started', 'This message already started on this device', 409);
+    return { share, origin };
+  }
+
+  function pinnedAuthority(sender) {
+    const pinned = store.authority(sender.nodeId);
+    if (pinned) {
+      if (sender.authority && (sender.authority.keyId !== pinned.keyId || sender.authority.publicKey !== pinned.publicKey)) {
+        throw new PeerError('authority_changed', 'The sending device presented a different origin key; pair it again', 403);
+      }
+      return pinned;
+    }
+    // Devices other than the coordinator are bound on first contact from the
+    // coordinator's pairing record, and pinned from then on.
+    if (!isAuthorityKey(sender.authority)) throw new PeerError('authority_unknown', 'The sending device has no origin key', 403);
+    const { bound, authority } = store.bindAuthority(sender.nodeId, sender.authority, 'coordinator');
+    if (!bound) throw new PeerError('authority_changed', 'The sending device presented a different origin key; pair it again', 403);
+    return authority;
+  }
+
+  async function supervise(claim, { share }, acceptedAt) {
+    const { messageId, attemptId } = claim;
+    const controller = new AbortController();
+    let reason = null;
+    const stop = (why) => { reason ??= why; controller.abort(why); };
+    const stopOnShutdown = () => stop('stopped');
+    stopping.signal.addEventListener('abort', stopOnShutdown, { once: true });
+    if (stopping.signal.aborted) stopOnShutdown();
+    let lastRenewal = acceptedAt;
+    let leaseTimer;
+    const armDeadline = () => {
+      clearTimeout(leaseTimer);
+      if (controller.signal.aborted) return;
+      const remaining = PEER_LIMITS.leaseSeconds * 1000 - (clock() - lastRenewal);
+      if (remaining <= 0) stop('lease_lost');
+      else leaseTimer = setTimeout(() => stop('lease_lost'), remaining);
+    };
+    armDeadline();
+    async function renew(state) {
+      const sentAt = clock();
+      try {
+        const answer = await client.post('/peer/1/renew', { messageId, attemptId, state }, { signal: controller.signal });
+        if (controller.signal.aborted) return;
+        lastRenewal = Math.max(lastRenewal, sentAt);
+        armDeadline();
+        if (answer.cancel) stop('cancelled');
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        if (error.status === 403 || error.status === 409) stop(error.status === 403 ? 'cancelled' : 'lease_lost');
+      }
+    }
+    const renewals = (async () => {
+      while (!controller.signal.aborted) {
+        try { await delay(renewMs, undefined, { signal: controller.signal }); } catch { return; }
+        const state = store.attemptsFor(messageId).find((attempt) => attempt.attempt_id === attemptId)?.state;
+        await renew(state === 'running' ? 'running' : 'starting');
+      }
+    })();
+    running.set(messageId, { controller, share, stop });
+    try {
+      const answer = await roundtable.answerRemote({ claim, share, signal: controller.signal,
+        timeoutMs: PEER_LIMITS.executionSeconds * 1000,
+        onSpawn: () => {
+          try { store.setAttemptState(messageId, attemptId, 'running'); }
+          catch { stop('persistence_failed'); return; }
+          void renew('running');
+        },
+        issueGrant: (delivery, lifetime) => provider.issueRemoteAgentDelegation({
+          personal_space_id: share.spaceId, personal_project_id: share.projectId, agent_id: share.agentId,
+          target_application: delivery.client,
+          target_session_id: delivery.client === 'codex' ? delivery.sessionId : null,
+          lifetime_seconds: Math.max(30, Math.min(900, Math.round(lifetime))),
+          origin_node: claim.sender.nodeId, origin_message_id: messageId, origin_attempt_id: attemptId }) });
+      if (controller.signal.aborted) throw new PeerError('cancelled', 'The delivery was stopped', 499);
+      return { outcome: 'answered', reply: answer.body, via: answer.via, verified: true };
+    } catch (error) {
+      if (reason === 'lease_lost') return { outcome: 'unknown', error: 'lease_lost' };
+      if (reason === 'cancelled' || reason === 'stopped' || error.code === 'cancelled') return { outcome: 'cancelled', error: reason ?? 'cancelled' };
+      return { outcome: 'failed', error: error.code ?? 'wake_failed' };
+    } finally {
+      controller.abort('finished');
+      clearTimeout(leaseTimer);
+      stopping.signal.removeEventListener('abort', stopOnShutdown);
+      running.delete(messageId);
+      await renewals;
+    }
+  }
+
+  function queue(messageId, attemptId, outcome, { reply = null, via = null, verified = false, error = null } = {}) {
+    store.queueResult(messageId, attemptId, { messageId, attemptId, outcome, reply, via, verified, error });
+  }
+
+  async function flush() {
+    for (const pending of store.pendingResults()) {
+      try {
+        await client.post('/peer/1/result', pending.payload);
+        store.markDelivered(pending.messageId, pending.attemptId);
+      } catch (error) {
+        // The coordinator already moved on from this attempt; keep the local record only.
+        if (error.status === 404 || error.status === 409) store.markDelivered(pending.messageId, pending.attemptId);
+        else return;
+      }
+    }
+  }
+
+  async function pause(ms) {
+    try { await delay(ms, undefined, { signal: stopping.signal }); } catch { /* stopping */ }
+  }
+
+  async function stop() {
+    stopping.abort();
+    for (const { stop } of running.values()) stop('stopped');
+    await loop?.catch(() => {});
+    await Promise.allSettled([...handlers.keys()]);
+    await flush();
+  }
+
+  async function reconcileShares(validBindings = null) {
+    const cancelled = new Set();
+    for (const [messageId, { share, stop }] of running) {
+      const current = store.share(share.bindingId);
+      if (!current || (validBindings && !validBindings.has(share.bindingId))
+        || current.workingDirectory !== share.workingDirectory
+        || share.clients.some((client) => !current.clients.includes(client))) {
+        cancelled.add(messageId);
+        stop('cancelled');
+      }
+    }
+    await Promise.allSettled([...handlers].filter(([, id]) => cancelled.has(id)).map(([work]) => work));
+  }
+
+  return { start, stop, flush, handle, reconcileShares, active: () => running.size };
+}

package/src/agent-roundtable/http.js

@@ -1,14 +1,28 @@
-import { sendJson } from '../http/response.js';
+import { readJson, sendJson } from '../http/response.js';
 
-// Read-only console view of Agent-to-Agent threads.
+// Console view of Agent-to-Agent threads, plus the owner's status and cancel
+// for one message (the same actions Agents have as MCP tools).
 export async function handleRoundtableApiRequest({ request, response, url, roundtable }) {
-  if (!roundtable || request.method !== 'GET') return false;
+  if (!roundtable) return false;
+  const message = /^\/api\/roundtable\/messages\/([^/]+)(\/cancel)?$/.exec(url.pathname);
+  if (message && request.method === 'GET' && !message[2]) {
+    sendJson(response, 200, await roundtable.ownerMessageStatus({ messageId: decodeURIComponent(message[1]) }));
+    return true;
+  }
+  if (message && request.method === 'POST' && message[2]) {
+    await readJson(request);
+    sendJson(response, 200, await roundtable.ownerCancelMessage({ messageId: decodeURIComponent(message[1]) }));
+    return true;
+  }
+  if (request.method !== 'GET') return false;
   if (url.pathname === '/api/roundtable/threads') {
+    await roundtable.refreshRemote?.();
     sendJson(response, 200, roundtable.threads({ limit: Math.min(Number(url.searchParams.get('limit')) || 50, 200) }));
     return true;
   }
   const match = /^\/api\/roundtable\/threads\/([^/]+)$/.exec(url.pathname);
   if (!match) return false;
+  await roundtable.refreshRemote?.({ threadId: decodeURIComponent(match[1]) });
   sendJson(response, 200, roundtable.thread({ threadId: decodeURIComponent(match[1]) }));
   return true;
 }