@uuaid/agent-commons 0.0.0 → 0.2.0-alpha.2

package/src/index.mjs

@@ -0,0 +1,15 @@
+export { AgentCommons } from "./runtime.mjs";
+export { CommonsCarrier } from "./carrier.mjs";
+export { CommonsStore } from "./store.mjs";
+export { RegistryTrust, REQUIRED_STANDARDS, TrustError } from "./trust.mjs";
+export { runAgentLoop } from "./loop.mjs";
+export { initialize, loadRuntime } from "./config.mjs";
+export { FOUNDING_ROSTER, initializeCohort, cohortStatus } from "./cohort.mjs";
+export { ContinuityMemory, ContinuityError, MemoryContinuityStore, verifyContinuity, CONTINUITY_PROTOCOL } from "./continuity.mjs";
+export { PeerGovernance, GovernanceError, verifyGovernanceDocument, createActionBudget, CLAIM_TYPES, ACTION_MANIFEST } from "./governance.mjs";
+export { CollaborationScheduler, CollaborationError, createCollaboration, createRoster, rosterFromModels, createFilePersistence, createMemoryPersistence, createContinuity, memoryFromContinuity, validateProposal, validateUnifiedDiff, validatePatchPath, hmacIntegrity } from "./collaboration.mjs";
+export { createProfile, verifyProfile, proposeAlias, encode, decode, benchmark, contribution, signDocument, verifyDocument, digest, BASE_PROTOCOL } from "./profiles.mjs";
+export { Keychain, localIdFromKey, CarrierClient, seal, open, decrypt, envelopeSha } from "./pillar.mjs";
+export { MemoryLoopbackTransport, PillarCarrierTransport } from "./transport.mjs";
+export { classifyThread, assertChannelSendAdmission, assertChannelReceiveAdmission, assertForwardingPermission, validateTenantBinding, CANONICAL_CHANNEL_REGEX, RESERVED_CHANNEL_PREFIX } from "./channels.mjs";
+export { classifyOperationTier, verifyPrincipalGovernance, MockPrincipalStatusVerifier } from "./governance-scope.mjs";

package/src/loop.mjs

@@ -0,0 +1,71 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { randomUUID } from "node:crypto";
+const DEFAULT_BUDGET={maxSends:100,maxBytesOut:256000,maxRepliesPerPeer:8,maxWallClockMs:900000,windowMs:3600000,windowMaxSends:200,windowMaxBytes:2000000,windowMaxRepliesPerPeer:40};
+const SPONTANEOUS_KEYS=new Set(["recipient","profileId","namespace","body","thread","kind"]);
+/**
+ * Bounded agent loop. Budget (all enforced BEFORE a send):
+ *  - per-run: maxSends, maxBytesOut, maxRepliesPerPeer (stops reply ping-pong), maxWallClockMs
+ *  - per-window, persisted in runtime.store (survives loop restarts): windowMaxSends/Bytes/RepliesPerPeer
+ * The agent cannot raise these: callers pass `budget`; values are clamped to hard ceilings.
+ * Spontaneous actions may only be plain "message" sends to a peer already in policy.
+ */
+export async function runAgentLoop({runtime,respond,spontaneous=null,maxTurns=16,intervalMs=2000,signal,onEvent=()=>{},budget={}}){
+  if(!runtime||typeof respond!=="function"||!Number.isInteger(maxTurns)||maxTurns<1||maxTurns>100||!Number.isInteger(intervalMs)||intervalMs<500)throw new Error("Invalid bounded agent loop");
+  const limits={...DEFAULT_BUDGET};
+  for(const [k,v] of Object.entries(budget??{})){if(!(k in DEFAULT_BUDGET)||!Number.isSafeInteger(v)||v<1||v>DEFAULT_BUDGET[k])throw new Error(`Invalid loop budget ${k}`);limits[k]=v}
+  const started=Date.now(),run={sends:0,bytes:0,peers:{}},store=runtime.store&&typeof runtime.store.get==="function"?runtime.store:null;
+  const record=(reason,extra={})=>{try{store?.append?.(randomUUID(),{kind:"loop-budget-stop",reason,...extra})}catch{}};
+  // Returns a refusal reason or null, and reserves the budget when allowed.
+  const reserve=(peer,bytes)=>{
+    if(Date.now()-started>=limits.maxWallClockMs)return "wall-clock";
+    if(run.sends+1>limits.maxSends)return "run-sends";
+    if(run.bytes+bytes>limits.maxBytesOut)return "run-bytes";
+    if((run.peers[peer]??0)+1>limits.maxRepliesPerPeer)return "run-peer-replies";
+    let meter=null;
+    if(store){
+      meter=store.get("loopMeter",null);const now=Date.now();
+      if(!meter||now-meter.start>=limits.windowMs)meter={start:now,sends:0,bytes:0,peers:{}};
+      if(meter.sends+1>limits.windowMaxSends)return "window-sends";
+      if(meter.bytes+bytes>limits.windowMaxBytes)return "window-bytes";
+      if((meter.peers[peer]??0)+1>limits.windowMaxRepliesPerPeer)return "window-peer-replies";
+      meter.sends++;meter.bytes+=bytes;meter.peers[peer]=(meter.peers[peer]??0)+1;
+      if(Object.keys(meter.peers).length>1000)return "window-peers";
+      store.set("loopMeter",meter);
+    }
+    run.sends++;run.bytes+=bytes;run.peers[peer]=(run.peers[peer]??0)+1;return null;
+  };
+  let turns=0,stopped=null;
+  const send=async(action)=>{
+    const reason=reserve(String(action.recipient),Buffer.byteLength(String(action.body??"")));
+    if(reason){stopped=`budget:${reason}`;record(reason,{peer:String(action.recipient).slice(0,120)});onEvent({rejected:true,state:"budget-refused",reason});return false}
+    onEvent(await runtime.send(action));return true;
+  };
+  while(turns<maxTurns&&!signal?.aborted&&!stopped){
+    const packets=await runtime.poll();
+    for(const packet of packets){
+      if(packet.duplicate||packet.rejected||packet.deferred||typeof packet.body!=="string"){onEvent(packet);continue}
+      let reply;
+      try{reply=await respond({packet,status:runtime.status(),signal})}
+      catch(error){turns++;onEvent({rejected:true,state:"responder-failed",reason:String(error?.message??error).slice(0,200)});if(turns>=maxTurns||signal?.aborted)break;continue}
+      turns++;
+      if(reply!==null&&reply!==undefined){
+        if(typeof reply!=="string")throw new Error("Agent responder must return bounded plain text or null");
+        if(!await send({recipient:packet.sender,profileId:packet.profileId,thread:packet.thread,body:reply}))break;
+      }
+      if(turns>=maxTurns||signal?.aborted)break;
+    }
+    if(stopped)break;
+    if(!packets.length&&spontaneous&&turns<maxTurns){
+      const action=await spontaneous({status:runtime.status(),signal});
+      turns++;
+      if(action){
+        const allowedPeers=runtime.policy?.agents;
+        if(typeof action!=="object"||Object.keys(action).some(k=>!SPONTANEOUS_KEYS.has(k))||(action.kind!==undefined&&action.kind!=="message")||typeof action.recipient!=="string"||typeof action.body!=="string"||(allowedPeers&&!Object.hasOwn(allowedPeers,action.recipient))){onEvent({rejected:true,state:"spontaneous-action-refused"});record("spontaneous-action-refused")}
+        else if(!await send(action))break;
+      }
+    }
+    await runtime.flush();
+    if(turns<maxTurns&&!signal?.aborted)try{await delay(intervalMs,null,{signal})}catch(error){if(error.name!=="AbortError")throw error}
+  }
+  return {turns,stopped:stopped??(signal?.aborted?"aborted":"turn-limit"),usage:{...run,peers:undefined}};
+}

package/src/offline.d.mts

@@ -0,0 +1,7 @@
+export const OFFLINE_ENV: "AGENT_COMMONS_OFFLINE";
+export function isLoopbackHost(hostname: string): boolean;
+export function isLoopbackUrl(url: string): boolean;
+export function isOffline(
+  env?: Record<string, string | undefined>,
+  policy?: { mode?: string; offline?: boolean },
+): boolean;

package/src/offline.mjs

@@ -0,0 +1,29 @@
+// Offline mode. Default on for a local run.
+// AGENT_COMMONS_OFFLINE=1 forces offline, including policy.mode "global".
+// AGENT_COMMONS_OFFLINE=0 is the only opt-in that allows outbound calls.
+// Unset: offline, unless policy.offline is false, or policy.mode is "global"
+// and the policy does not set offline. Loopback is a local carrier, not egress.
+
+export const OFFLINE_ENV = "AGENT_COMMONS_OFFLINE";
+
+export function isLoopbackHost(hostname) {
+  const host = String(hostname ?? "").toLowerCase().replace(/^\[|\]$/g, "");
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+export function isLoopbackUrl(url) {
+  try {
+    return isLoopbackHost(new URL(String(url)).hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function isOffline(env = process.env, policy) {
+  const flag = env?.[OFFLINE_ENV];
+  if (flag === "1") return true;
+  if (flag === "0") return false;
+  if (policy && Object.prototype.hasOwnProperty.call(policy, "offline")) return policy.offline !== false;
+  if (policy?.mode === "global") return false;
+  return true;
+}

package/src/pillar.mjs

@@ -0,0 +1,59 @@
+// Unmodified upstream modules are covered by NOTICE and PROVENANCE.json.
+// CarrierClient is wrapped here. The vendored module stays byte-identical to
+// @uuaid/pillar 2.0.2. Offline refusal happens before any vendored method runs.
+import { CarrierClient as VendoredCarrierClient } from "./vendor/pillar/net/carrier-client.mjs";
+import { isLoopbackUrl, isOffline } from "./offline.mjs";
+
+export { Keychain, localIdFromKey } from "./vendor/pillar/identity/keychain.mjs";
+export { jcs } from "./vendor/pillar/identity/jcs.mjs";
+export { seal, open, decrypt, envelopeSha, ENVELOPE_VERSION } from "./vendor/pillar/net/envelope.mjs";
+
+function refusedCarrier(urls, env) {
+  if (!isOffline(env)) return null;
+  for (const url of urls ?? []) {
+    if (!isLoopbackUrl(url)) return url;
+  }
+  return null;
+}
+
+function offlineError(url) {
+  const error = new Error(`offline: refused outbound carrier call to ${url}`);
+  error.code = "offline";
+  error.carrier = url;
+  return error;
+}
+
+export class CarrierClient extends VendoredCarrierClient {
+  constructor(options = {}) {
+    super(options);
+    // Upstream pillar 2.0.2 does not store env. The package seam does.
+    this._offlineEnv = options.env ?? process.env;
+  }
+
+  async deliver(envelope, options) {
+    const blocked = refusedCarrier(this.carriers, this._offlineEnv);
+    if (blocked) throw offlineError(blocked);
+    return super.deliver(envelope, options);
+  }
+
+  async fetchInbox(base, options) {
+    const blocked = refusedCarrier([base], this._offlineEnv);
+    if (blocked) throw offlineError(blocked);
+    return super.fetchInbox(base, options);
+  }
+
+  startPolling(options = {}) {
+    const blocked = refusedCarrier(this.carriers, this._offlineEnv);
+    if (blocked) {
+      const error = offlineError(blocked);
+      options.onError?.(error, { carrier: blocked });
+      const cursors = { ...(options.cursors ?? {}) };
+      return {
+        stop() {},
+        cursors: () => ({ ...cursors }),
+        done: Promise.resolve([]),
+      };
+    }
+    return super.startPolling(options);
+  }
+}

package/src/profiles.d.mts

@@ -0,0 +1,12 @@
+import type { Profile, Keychain } from "./index.d.ts";
+export function createProfile(options:{namespace:string;name:string;fixtures:string[];scope?:"local"|"tenant"|"global";lexicon?:Record<string,string>;parent?:string|null;revision?:number;quorum?:number}):Profile;
+export function verifyProfile(profile:Profile):Profile;
+export function proposeAlias(profile:Profile,phrase:string):any;
+export function contribution(profile:Profile,options?:{includeFixtures?:boolean}):any;
+export function signDocument(keychain:Keychain,kind:string,payload:any):any;
+export function digest(value:any):string;
+export function benchmark(lexicon:Record<string,string>,fixtures:string[]):Profile["benchmark"];
+export function encode(text:string,lexicon:Record<string,string>):string;
+export function decode(text:string,lexicon:Record<string,string>):string;
+export function verifyDocument(document:any):any;
+export const BASE_PROTOCOL:"agent-commons/1";

package/src/profiles.mjs

@@ -0,0 +1,91 @@
+import { createHash, randomUUID } from "node:crypto";
+import { jcs, Keychain } from "./pillar.mjs";
+
+export const BASE_PROTOCOL = "agent-commons/1";
+export function digest(value) { assertJSON(value);return createHash("sha256").update(jcs(value)).digest("hex"); }
+export function assertJSON(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return;
+  if (Array.isArray(value)) return value.forEach(assertJSON);
+  if (value && Object.getPrototypeOf(value) === Object.prototype) {
+    for (const [key, item] of Object.entries(value)) {
+      if (!/^[\x20-\x7e]+$/.test(key) || ["__proto__", "prototype", "constructor"].includes(key)) throw new Error("Unsafe canonical key");
+      assertJSON(item);
+    }
+    return;
+  }
+  throw new Error("Expected canonical JSON; decimal measurements must be strings");
+}
+export function encode(body, lexicon) {
+  let wire=body.replaceAll("~","~~");
+  for (const [phrase,alias] of Object.entries(lexicon).sort((a,b)=>b[0].length-a[0].length)) wire=wire.split(phrase).join(alias);
+  return wire;
+}
+export function decode(wire, lexicon) {
+  const reverse=new Map(Object.entries(lexicon).map(([k,v])=>[v,k]));
+  return wire.replace(/~~|~\d+~/g,t=>t==="~~"?"~":reverse.get(t)??t);
+}
+export function validateLexicon(lexicon) {
+  if (!lexicon || typeof lexicon!=="object" || Array.isArray(lexicon) || Object.keys(lexicon).length>128) throw new Error("Invalid lexicon");
+  const symbols=new Set();
+  for (const [phrase,symbol] of Object.entries(lexicon)) {
+    if (!/^[A-Za-z][A-Za-z ]{7,79}$/.test(phrase) || phrase!==phrase.trim() || !/^~\d{1,3}~$/.test(symbol) || symbols.has(symbol)) throw new Error("Invalid or colliding alias");
+    symbols.add(symbol);
+  }
+}
+export function benchmark(lexicon, fixtures) {
+  validateLexicon(lexicon);
+  let originalBytes=0,wireBytes=0,passed=0;
+  for (const fixture of fixtures) {
+    const wire=encode(fixture,lexicon);
+    if(decode(wire,lexicon)===fixture)passed++;
+    originalBytes+=Buffer.byteLength(fixture);wireBytes+=Buffer.byteLength(wire);
+  }
+  return {tests:fixtures.length,passed,originalBytes,wireBytes,reductionBps:originalBytes?Math.round(10000*(originalBytes-wireBytes)/originalBytes):0};
+}
+const safetyFixtures=["","~0~","~~","~123~","தமிழ் மொழி","🧬","\n\\\"", "a".repeat(128)];
+export function createProfile({ namespace, name, fixtures, scope="local", lexicon={}, parent=null, revision=0, quorum=2 }) {
+  if (!/^[a-z0-9][a-z0-9._/-]{1,119}$/.test(namespace)||typeof name!=="string"||name.length<2||name.length>120) throw new Error("Invalid profile name or namespace");
+  if (!["local","tenant","global"].includes(scope)) throw new Error("Invalid profile scope");
+  if(!Array.isArray(fixtures)||fixtures.length<2||fixtures.length>100||fixtures.some(f=>typeof f!=="string"||f.length>8000)||Buffer.byteLength(JSON.stringify(fixtures))>256000) throw new Error("Provide 2–100 bounded text fixtures");
+  if(!Number.isSafeInteger(revision)||revision<0||!Number.isSafeInteger(quorum)||quorum<2||quorum>10)throw new Error("Invalid profile revision or quorum");
+  validateLexicon(lexicon);
+  const report=benchmark(lexicon,[...fixtures,...safetyFixtures]);
+  if(report.tests!==report.passed)throw new Error("Profile fails lossless gate");
+  const document={v:BASE_PROTOCOL,namespace,name,scope,parent,revision,quorum,lexicon,fixtureHash:digest(fixtures),fixtures};
+  assertJSON(document);
+  return {...document,id:digest(document),benchmark:report};
+}
+export function verifyProfile(profile) {
+  const allowed=new Set(["v","namespace","name","scope","parent","revision","quorum","lexicon","fixtureHash","fixtures","id","benchmark"]);
+  if(Object.keys(profile??{}).some(key=>!allowed.has(key)))throw new Error("Unknown profile field");
+  const rebuilt=createProfile(profile);
+  if(rebuilt.id!==profile.id || digest(rebuilt.benchmark)!==digest(profile.benchmark))throw new Error("Profile digest or benchmark mismatch");
+  return rebuilt;
+}
+export function proposeAlias(profile, phrase) {
+  verifyProfile(profile);
+  if(Object.hasOwn(profile.lexicon,phrase))throw new Error("Alias already exists");
+  const numbers=Object.values(profile.lexicon).map(s=>Number(s.slice(1,-1)));
+  const alias=`~${numbers.length?Math.max(...numbers)+1:0}~`;
+  const candidate=createProfile({...profile,lexicon:{...profile.lexicon,[phrase]:alias},parent:profile.id,revision:profile.revision+1});
+  if(candidate.benchmark.wireBytes>=profile.benchmark.wireBytes)throw new Error("Candidate does not improve the local benchmark");
+  return {id:randomUUID(),parent:profile.id,candidate,phrase,alias,status:"pending",votes:{}};
+}
+export function signDocument(keychain, kind, payload) {
+  assertJSON(payload);
+  const body={v:BASE_PROTOCOL,id:randomUUID(),kind,issuer:keychain._identity.uuaid,publicKey:keychain._identity.publicKeyHex,createdAt:new Date().toISOString(),payload};
+  return {...body,signature:keychain.sign(Buffer.from(jcs(body))).toString("hex")};
+}
+export function verifyDocument(document) {
+  assertJSON(document);
+  const {signature,...body}=document;
+  if(body.v!==BASE_PROTOCOL||!["profile-proposal","profile-vote","profile-contribution","profile-recovery"].includes(body.kind)||!/^uuaid:[a-z0-9-]+:agent:[0-9a-f-]{36}$/.test(body.issuer)||!/^[0-9a-f]{64}$/.test(body.publicKey)||!/^[0-9a-f]{128}$/.test(signature))throw new Error("Invalid agent document");
+  if(Keychain.localIdFromKey(Buffer.from(body.publicKey,"hex"))!==body.issuer.split(":")[3])throw new Error("Agent key is not bound to UUAID");
+  if(!Keychain.verifyDetached(body.publicKey,Buffer.from(jcs(body)),Buffer.from(signature,"hex")))throw new Error("Invalid document signature");
+  return body;
+}
+export function contribution(profile, { includeFixtures=false }={}) {
+  verifyProfile(profile);
+  return {profileId:profile.id,namespace:profile.namespace,parent:profile.parent,base:BASE_PROTOCOL,lexicon:profile.lexicon,fixtureHash:profile.fixtureHash,benchmark:profile.benchmark,visibility:includeFixtures?"shared-fixtures":"metadata-only",...(includeFixtures?{profile}:{}),stage:"candidate",standardization:"requires-IAASO-review"};
+}