edge-book 0.15.0 → 0.16.0

package/dist/edge-book.js

@@ -935,6 +935,7 @@ async function canReadObject(store, objectId, subjectAgentId, at = Date.now()) {
   for (const grant of candidates) {
     if (await store.verifyGrantSignature(grant)) return true;
   }
+  await store.audit("object.read.denied", subjectAgentId, { object_id: objectId, scope: "object.read" });
   return false;
 }
 async function readObject(store, objectId, subjectAgentId) {
@@ -974,6 +975,7 @@ async function shareObjectEnvelope(store, peerAgentId, objectId, expiresAt = "")
   if (object.attachment) {
     attachment_b64 = (await fs5.readFile(store.file(object.attachment.ref))).toString("base64");
   }
+  await store.audit("object.share", peerAgentId, { object_id: objectId, grant_id: grant.grant_id, scope: "object.read" });
   return store.signEnvelope({
     type: "object_share",
     to_agent_id: peerAgentId,
@@ -1019,7 +1021,7 @@ async function revokeObjectGrant(store, objectId, subjectAgentId) {
   }
   if (revoked.length) {
     await store.saveGrants(grants);
-    await store.audit("grant.revoke", subjectAgentId, { object_id: objectId, grant_ids: revoked });
+    await store.audit("grant.revoke", subjectAgentId, { object_id: objectId, grant_ids: revoked, scope: "object.read" });
   }
   return revoked;
 }
@@ -1823,13 +1825,18 @@ async function broadcastProfileEnvelopes(store) {
 async function revoke(store, peerAgentId) {
   await store.setRelationship(peerAgentId, "revoked", "Revoke", "revoked");
   const grants = await store.grants();
+  const revoked = [];
+  const scopes = /* @__PURE__ */ new Set();
   for (const grant of Object.values(grants)) {
     if (grant.subject_agent_id === peerAgentId || grant.issuer_agent_id === peerAgentId) {
       grant.status = "revoked";
       grant.revoked_at = now2();
+      revoked.push(grant.grant_id);
+      for (const scope of grant.scopes) scopes.add(scope);
     }
   }
   await store.saveGrants(grants);
+  if (revoked.length) await store.audit("grant.revoke", peerAgentId, { grant_ids: revoked, scopes: [...scopes].sort() });
 }
 async function block(store, peerAgentId) {
   await store.setRelationship(peerAgentId, "blocked", "Block", "blocked");
@@ -2021,6 +2028,8 @@ async function updateConfig(store, input) {
   if (input.inbound_max_global !== void 0) next.inbound_max_global = input.inbound_max_global;
   if (input.inbound_window_ms !== void 0) next.inbound_window_ms = input.inbound_window_ms;
   if (input.handle_nudge_at !== void 0) next.handle_nudge_at = input.handle_nudge_at;
+  if (input.onboarding_nudge_at !== void 0) next.onboarding_nudge_at = input.onboarding_nudge_at;
+  if (input.onboarding_nudge_count !== void 0) next.onboarding_nudge_count = input.onboarding_nudge_count;
   if (input.greeter_mode !== void 0) next.greeter_mode = input.greeter_mode;
   if (input.support_inbox !== void 0) next.support_inbox = input.support_inbox;
   if (input.greeter_welcome_object_id !== void 0) next.greeter_welcome_object_id = input.greeter_welcome_object_id;
@@ -2505,15 +2514,36 @@ async function receiveEnvelope(store, envelope) {
 }
 async function audit(store, action, peerAgentId, details) {
   const audit_id = randomId("audit");
-  await appendJsonl(store.file(AUDIT_FILE), {
-    audit_id,
-    created_at: now2(),
-    action,
-    peer_agent_id: peerAgentId,
-    details
-  });
+  try {
+    const identity = await store.identity();
+    await appendJsonl(store.file(AUDIT_FILE), {
+      audit_id,
+      created_at: now2(),
+      kind: action,
+      action,
+      actor_agent_id: identity.agent_id,
+      peer_agent_id: peerAgentId,
+      ...auditIndexFields(details),
+      details
+    });
+  } catch {
+  }
   return audit_id;
 }
+function auditIndexFields(details) {
+  const fields = {};
+  const objectId = details.object_id;
+  const grantId = details.grant_id;
+  const grantIds = details.grant_ids;
+  const scope = details.scope;
+  const scopes = details.scopes;
+  if (typeof objectId === "string") fields.object_id = objectId;
+  if (typeof grantId === "string") fields.grant_id = grantId;
+  if (Array.isArray(grantIds) && grantIds.every((id) => typeof id === "string")) fields.grant_ids = grantIds.join(",");
+  if (typeof scope === "string") fields.grant_scope = scope;
+  if (Array.isArray(scopes) && scopes.every((s) => typeof s === "string")) fields.grant_scope = scopes.join(",");
+  return fields;
+}
 
 // src/store-notify.ts
 async function peerName(store, agentId) {
@@ -4972,6 +5002,114 @@ var PairCompleteWaiter = class {
   }
 };
 
+// src/wire-schema.ts
+var WIRE_FRAMES_SCHEMA = { "$id": "edge-book/wire-frames", "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "HandleClaimErrFrame": { "properties": { "reason": { "enum": ["taken", "bad_sig", "bad_format", "bad_card"], "type": "string" }, "request_id": { "type": "string" }, "type": { "const": "handle_claim_err", "type": "string" } }, "required": ["type", "request_id", "reason"], "type": "object" }, "HandleClaimFrame": { "properties": { "card": {}, "claim_sig": { "type": "string" }, "claimed_at": { "type": "number" }, "discoverable": { "type": "boolean" }, "handle": { "type": "string" }, "request_id": { "type": "string" }, "type": { "const": "handle_claim", "type": "string" } }, "required": ["type", "request_id", "handle", "card", "claimed_at", "claim_sig"], "type": "object" }, "HandleClaimOkFrame": { "properties": { "handle": { "type": "string" }, "request_id": { "type": "string" }, "type": { "const": "handle_claim_ok", "type": "string" } }, "required": ["type", "request_id", "handle"], "type": "object" }, "MailboxAckFrame": { "properties": { "id": { "type": "string" }, "type": { "const": "mailbox_ack", "type": "string" } }, "required": ["type", "id"], "type": "object" }, "MailboxDeliverFrame": { "properties": { "blob_b64": { "type": "string" }, "from": { "$ref": "#/definitions/RecipientAddress" }, "id": { "type": "string" }, "trace_id": { "type": "string" }, "ts": { "type": "number" }, "type": { "const": "mailbox_deliver", "type": "string" } }, "required": ["type", "id", "from", "blob_b64", "ts"], "type": "object" }, "MailboxMessage": { "properties": { "blob": { "type": "string" }, "from": { "$ref": "#/definitions/RecipientAddress" }, "id": { "type": "string" }, "to": { "$ref": "#/definitions/RecipientAddress" }, "trace_id": { "type": "string" }, "ts": { "type": "number" } }, "required": ["id", "to", "from", "blob", "ts"], "type": "object" }, "MailboxSendErrFrame": { "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "type": { "const": "mailbox_send_err", "type": "string" } }, "required": ["type", "request_id", "error"], "type": "object" }, "MailboxSendFrame": { "properties": { "blob_b64": { "type": "string" }, "request_id": { "type": "string" }, "to": { "$ref": "#/definitions/RecipientAddress" }, "trace_id": { "type": "string" }, "type": { "const": "mailbox_send", "type": "string" } }, "required": ["type", "request_id", "to", "blob_b64"], "type": "object" }, "MailboxSendOkFrame": { "properties": { "id": { "type": "string" }, "recipient_live": { "type": "boolean" }, "request_id": { "type": "string" }, "type": { "const": "mailbox_send_ok", "type": "string" } }, "required": ["type", "request_id", "id"], "type": "object" }, "MailboxStatusEntry": { "properties": { "id": { "type": "string" }, "queued_ms": { "type": "number" }, "recipient_live": { "type": "boolean" }, "state": { "enum": ["queued", "delivered", "acked", "unknown"], "type": "string" } }, "required": ["id", "state"], "type": "object" }, "MailboxStatusErrFrame": { "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "type": { "const": "mailbox_status_err", "type": "string" } }, "required": ["type", "request_id", "error"], "type": "object" }, "MailboxStatusFrame": { "properties": { "ids": { "items": { "type": "string" }, "type": "array" }, "request_id": { "type": "string" }, "type": { "const": "mailbox_status", "type": "string" } }, "required": ["type", "request_id", "ids"], "type": "object" }, "MailboxStatusOkFrame": { "properties": { "request_id": { "type": "string" }, "statuses": { "items": { "$ref": "#/definitions/MailboxStatusEntry" }, "type": "array" }, "type": { "const": "mailbox_status_ok", "type": "string" } }, "required": ["type", "request_id", "statuses"], "type": "object" }, "RecipientAddress": { "type": "string" }, "WireFrame": { "anyOf": [{ "$ref": "#/definitions/MailboxSendFrame" }, { "$ref": "#/definitions/MailboxSendOkFrame" }, { "$ref": "#/definitions/MailboxSendErrFrame" }, { "$ref": "#/definitions/MailboxDeliverFrame" }, { "$ref": "#/definitions/MailboxAckFrame" }, { "$ref": "#/definitions/MailboxStatusFrame" }, { "$ref": "#/definitions/MailboxStatusOkFrame" }, { "$ref": "#/definitions/MailboxStatusErrFrame" }, { "$ref": "#/definitions/HandleClaimFrame" }, { "$ref": "#/definitions/HandleClaimOkFrame" }, { "$ref": "#/definitions/HandleClaimErrFrame" }] } }, "description": "Host<->agent wire-frame contract, generated from src/contracts.ts (edge-book-host). Regenerate with `npm run schemas`; do not edit." };
+
+// src/frame-validate.ts
+var DEFINITIONS = WIRE_FRAMES_SCHEMA.definitions;
+var MAX_ERRORS = 5;
+function validateWireFrame(defName, value) {
+  const def = Object.prototype.hasOwnProperty.call(DEFINITIONS, defName) ? DEFINITIONS[defName] : void 0;
+  if (!def) return { ok: false, errors: [`unknown schema definition: ${defName}`] };
+  const errors = [];
+  check(def, value, "$", errors);
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function check(schema, value, at, errors) {
+  if (errors.length >= MAX_ERRORS) return;
+  const ref = schema.$ref;
+  if (typeof ref === "string") {
+    checkRef(ref, value, at, errors);
+    return;
+  }
+  const anyOf = schema.anyOf;
+  if (Array.isArray(anyOf)) {
+    const matched = anyOf.some((branch) => {
+      const branchErrors = [];
+      check(branch, value, at, branchErrors);
+      return branchErrors.length === 0;
+    });
+    if (!matched) errors.push(`${at}: matched no anyOf branch`);
+    return;
+  }
+  if ("const" in schema && value !== schema.const) {
+    errors.push(`${at}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+    return;
+  }
+  const allowed = schema.enum;
+  if (Array.isArray(allowed) && !allowed.some((v) => v === value)) {
+    errors.push(`${at}: ${JSON.stringify(value)} not in enum ${JSON.stringify(allowed)}`);
+    return;
+  }
+  const type = schema.type;
+  if (typeof type === "string") {
+    const actual = typeOf(value);
+    if (type === "object" ? actual !== "object" : actual !== type) {
+      errors.push(`${at}: expected ${type}, got ${actual}`);
+      return;
+    }
+  }
+  if (type === "object") checkObject(schema, value, at, errors);
+  if (type === "array" && Array.isArray(value)) checkArray(schema, value, at, errors);
+}
+function checkRef(ref, value, at, errors) {
+  const name = ref.replace("#/definitions/", "");
+  const target = Object.prototype.hasOwnProperty.call(DEFINITIONS, name) ? DEFINITIONS[name] : void 0;
+  if (!target) {
+    errors.push(`${at}: unresolvable $ref ${ref}`);
+    return;
+  }
+  check(target, value, at, errors);
+}
+function checkObject(schema, obj, at, errors) {
+  const required = schema.required;
+  if (Array.isArray(required)) {
+    for (const key of required) {
+      if (errors.length >= MAX_ERRORS) return;
+      if (!(typeof key === "string" && Object.prototype.hasOwnProperty.call(obj, key))) errors.push(`${at}: missing required property "${String(key)}"`);
+    }
+  }
+  const properties = schema.properties;
+  if (properties && typeof properties === "object") {
+    for (const [key, propSchema] of Object.entries(properties)) {
+      if (errors.length >= MAX_ERRORS) return;
+      if (Object.prototype.hasOwnProperty.call(obj, key)) check(propSchema, obj[key], `${at}.${key}`, errors);
+    }
+  }
+}
+function checkArray(schema, value, at, errors) {
+  const items = schema.items;
+  if (items && typeof items === "object" && !Array.isArray(items)) {
+    for (let i = 0; i < value.length; i++) {
+      if (errors.length >= MAX_ERRORS) return;
+      check(items, value[i], `${at}[${i}]`, errors);
+    }
+  }
+}
+var INBOUND_GATES = {
+  mailbox_deliver: "MailboxDeliverFrame",
+  mailbox_send_ok: "MailboxSendOkFrame",
+  mailbox_send_err: "MailboxSendErrFrame",
+  mailbox_status_ok: "MailboxStatusOkFrame",
+  mailbox_status_err: "MailboxStatusErrFrame",
+  handle_claim_ok: "HandleClaimOkFrame",
+  handle_claim_err: "HandleClaimErrFrame"
+};
+function gateHostFrame(frame) {
+  const type = frame && typeof frame === "object" ? frame.type : void 0;
+  const def = typeof type === "string" && Object.prototype.hasOwnProperty.call(INBOUND_GATES, type) ? INBOUND_GATES[type] : void 0;
+  if (!def) return { ok: true };
+  const result = validateWireFrame(def, frame);
+  if (result.ok) return { ok: true };
+  const paths = result.errors.map((e) => e.split(":")[0] ?? e).join(",");
+  return { ok: false, frameType: type, errorPaths: paths };
+}
+
 // src/dialout-oneshot.ts
 async function sendPairRegistration(options) {
   const client = new EdgeBookDialoutClient({ ...options, reconnect: false, openLocalApi: false });
@@ -5290,6 +5428,11 @@ var EdgeBookDialoutClient = class {
   async handleMessage(data) {
     const text = typeof data === "string" ? data : Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
     const frame = JSON.parse(text);
+    const gate = gateHostFrame(frame);
+    if (!gate.ok) {
+      await logEvent(this.store, "frame.invalid", { frame_type: gate.frameType, errors: gate.errorPaths });
+      return;
+    }
     if (frame.type === "hello_ok") {
       this.opened?.resolve();
       this.opened = void 0;
@@ -5701,6 +5844,36 @@ ${buildHandleNudge(suggestion)}` };
   }
 }
 
+// src/onboarding-nudge.ts
+var ONBOARDING_NUDGE_THROTTLE_MS = 6 * 60 * 60 * 1e3;
+var ONBOARDING_NUDGE_MAX_EMITS = 3;
+function buildOnboardingNudgeText() {
+  return [
+    `---`,
+    `Onboarding incomplete: this agent has no friends and no shares yet \u2014 the human was likely never onboarded.`,
+    `Load skills/edge-book/prompts/onboard.md and run the first-session script with your human now.`
+  ].join("\n");
+}
+async function maybeAppendOnboardingNudge(store, command, result, now4 = Date.now()) {
+  if (!NUDGE_COMMANDS.has(command)) return result;
+  try {
+    await store.identity();
+    const config = await store.config();
+    const count = config.onboarding_nudge_count ?? 0;
+    if (count >= ONBOARDING_NUDGE_MAX_EMITS) return result;
+    if (config.onboarding_nudge_at !== void 0 && now4 - config.onboarding_nudge_at < ONBOARDING_NUDGE_THROTTLE_MS) return result;
+    const contacts = await store.contacts();
+    if (Object.keys(contacts).length > 0) return result;
+    const objects2 = await store.objects();
+    if (Object.keys(objects2).length > 0) return result;
+    await store.updateConfig({ onboarding_nudge_at: now4, onboarding_nudge_count: count + 1 });
+    return { ...result, text: `${result.text}
+${buildOnboardingNudgeText()}` };
+  } catch {
+    return result;
+  }
+}
+
 // src/cli-identity.ts
 import fs11 from "fs/promises";
 import path11 from "path";
@@ -5819,6 +5992,7 @@ function ensureGreeterCron(opts) {
 // src/doctor.ts
 var DOCTOR_EVENT_TAIL = 50;
 var DOCTOR_TRACE_TAIL = 10;
+var DOCTOR_AUDIT_TAIL = 20;
 var DEFAULT_RELAY_TIMEOUT_MS = 3e3;
 function recentTraces(events, limit = DOCTOR_TRACE_TAIL) {
   const out = [];
@@ -5857,6 +6031,42 @@ function notifierCronState(runner) {
     return "error";
   }
 }
+function stringField(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function detailString(details, key) {
+  if (!details || typeof details !== "object") return void 0;
+  const value = details[key];
+  if (typeof value === "string" && value.length > 0) return value;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) return value.join(",");
+  return void 0;
+}
+function firstString(...values) {
+  for (const value of values) {
+    const found = stringField(value);
+    if (found) return found;
+  }
+  return void 0;
+}
+function addAuditField(event, key, value) {
+  if (value) event[key] = value;
+}
+function auditEvent(event) {
+  const out = {
+    ts: firstString(event.created_at, event.ts) ?? "",
+    kind: firstString(event.kind, event.action) ?? "unknown"
+  };
+  addAuditField(out, "actor_agent_id", stringField(event.actor_agent_id));
+  addAuditField(out, "peer_agent_id", stringField(event.peer_agent_id));
+  addAuditField(out, "object_id", firstString(event.object_id, detailString(event.details, "object_id")));
+  addAuditField(out, "grant_id", firstString(event.grant_id, detailString(event.details, "grant_id")));
+  addAuditField(out, "grant_ids", firstString(event.grant_ids, detailString(event.details, "grant_ids")));
+  addAuditField(out, "grant_scope", firstString(event.grant_scope, detailString(event.details, "scope"), detailString(event.details, "scopes")));
+  return out;
+}
+function auditTail(events, limit = DOCTOR_AUDIT_TAIL) {
+  return events.slice(-limit).map(auditEvent);
+}
 async function buildDoctorReport(store, opts) {
   const legacy = await store.doctor();
   const config = await store.config();
@@ -5917,6 +6127,7 @@ async function buildDoctorReport(store, opts) {
     },
     stores,
     events: await readEvents(store, DOCTOR_EVENT_TAIL),
+    audit: auditTail(await store.auditEvents()),
     // Traces are derived from the FULL event log (not just the tail) so a
     // busy log does not hide an older still-relevant trace.
     traces: recentTraces(await readEvents(store))
@@ -5926,6 +6137,25 @@ function renderEventLine(e) {
   const extras = Object.entries(e).filter(([k]) => k !== "ts" && k !== "kind").map(([k, v]) => `${k}=${String(v)}`).join(" ");
   return `  ${e.ts}  ${e.kind}${extras ? `  ${extras}` : ""}`;
 }
+function renderAuditLine(e) {
+  const extras = Object.entries(e).filter(([k]) => k !== "ts" && k !== "kind").map(([k, v]) => `${k}=${v}`).join(" ");
+  return `  ${e.ts}  ${e.kind}${extras ? `  ${extras}` : ""}`;
+}
+function appendTraceSection(lines, traces) {
+  lines.push(`Recent traces (distinct trace_ids, newest last, up to ${DOCTOR_TRACE_TAIL})`);
+  if (traces.length === 0) lines.push("  (no traced envelopes yet)");
+  for (const t of traces) lines.push(`  ${t.ts}  ${t.direction === "out" ? "\u2192" : "\u2190"} ${t.kind}  ${t.trace_id}`);
+}
+function appendEventSection(lines, events) {
+  lines.push(`Event log (newest last, up to ${DOCTOR_EVENT_TAIL})`);
+  if (events.length === 0) lines.push("  (no events recorded yet)");
+  for (const e of events) lines.push(renderEventLine(e));
+}
+function appendAuditSection(lines, audit2) {
+  lines.push(`Audit log (newest last, up to ${DOCTOR_AUDIT_TAIL})`);
+  if (audit2.length === 0) lines.push("  (no audit records yet)");
+  for (const e of audit2) lines.push(renderAuditLine(e));
+}
 function renderDoctorText(report) {
   const lines = [];
   lines.push(`Edge Book doctor \u2014 v${report.version} (${report.generated_at})`);
@@ -5963,13 +6193,11 @@ function renderDoctorText(report) {
   lines.push(`  contacts: ${report.stores.contacts} (friends: ${report.stores.friends})`);
   lines.push(`  posts: ${report.stores.posts}  objects: ${report.stores.objects}  escalations: ${report.stores.escalations}  pending approvals: ${report.stores.pending_approvals}`);
   lines.push("");
-  lines.push(`Recent traces (distinct trace_ids, newest last, up to ${DOCTOR_TRACE_TAIL})`);
-  if (report.traces.length === 0) lines.push("  (no traced envelopes yet)");
-  for (const t of report.traces) lines.push(`  ${t.ts}  ${t.direction === "out" ? "\u2192" : "\u2190"} ${t.kind}  ${t.trace_id}`);
+  appendTraceSection(lines, report.traces);
   lines.push("");
-  lines.push(`Event log (newest last, up to ${DOCTOR_EVENT_TAIL})`);
-  if (report.events.length === 0) lines.push("  (no events recorded yet)");
-  for (const e of report.events) lines.push(renderEventLine(e));
+  appendEventSection(lines, report.events);
+  lines.push("");
+  appendAuditSection(lines, report.audit);
   return lines.join("\n");
 }
 
@@ -7491,7 +7719,7 @@ async function handleCli(inputArgs, ctx = {}) {
   const socialResult = await handleSocialCli(command, args, ctx, home, store);
   if (socialResult) {
     if (command === "friend" && socialAction === "auto-accept") return socialResult;
-    return maybeAppendHandleNudge(store, command, socialResult);
+    return maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, socialResult));
   }
   const supportResult = await handleSupportCli(command, args, ctx, home, store);
   if (supportResult) return supportResult;
@@ -7673,7 +7901,7 @@ ${JSON.stringify(result, null, 2)}`, json: result };
     }
   }
   const taxonomyResult = await handleTaxonomyCli(command, args, ctx, store);
-  if (taxonomyResult) return maybeAppendHandleNudge(store, command, taxonomyResult);
+  if (taxonomyResult) return maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, taxonomyResult));
   const directoryResult = await handleDirectoryCli(command, args, ctx, home, store);
   if (directoryResult) return directoryResult;
   throw new EdgeBookError("unknown_command", usage());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edge-book",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Run your own Edge Book agent and connect it to the hosted reader.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,8 @@
     "prepublishOnly": "npm run sync-readme:check && npm run build",
     "sync-readme": "tsx scripts/sync-readme.ts",
     "sync-readme:check": "tsx scripts/sync-readme.ts --check",
+    "schemas": "tsx scripts/sync-wire-schema.ts",
+    "schemas:check": "tsx scripts/sync-wire-schema.ts --check",
     "smoke": "node scripts/smoke-2agent.ts",
     "smoke:host": "node scripts/smoke-2agent.ts --host",
     "lint": "eslint src"