@twin3-ai/agent-id 0.1.0

package/sync-service.js

@@ -0,0 +1,312 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const SENSITIVE_KEYS = new Set([
+  "agent_key",
+  "agentkey",
+  "site_agent_key",
+  "site_token",
+  "authorization",
+  "cookie",
+  "password",
+  "secret",
+  "access_token",
+  "refresh_token"
+]);
+
+function redact(value) {
+  if (Array.isArray(value)) return value.map(redact);
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    const normalized = key.toLowerCase().replace(/[-\s]/g, "_");
+    if (SENSITIVE_KEYS.has(normalized) || SENSITIVE_KEYS.has(normalized.replace(/_/g, ""))) continue;
+    out[key] = redact(item);
+  }
+  return out;
+}
+
+function emptyState() {
+  return {
+    schema: "agentx-site-agent-sync-state-v1",
+    lifecycle: "active",
+    lifecycle_reason: "",
+    lifecycle_changed_at: "",
+    cursor: "",
+    queue: [],
+    dead_letters: [],
+    last_sync_at: "",
+    last_success_at: "",
+    last_heartbeat_at: 0,
+    last_error: null
+  };
+}
+
+async function readState(statePath) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(statePath, "utf8"));
+    return { ...emptyState(), ...parsed, queue: parsed.queue || [], dead_letters: parsed.dead_letters || [] };
+  } catch (err) {
+    if (err.code === "ENOENT") return emptyState();
+    throw err;
+  }
+}
+
+async function writeState(statePath, state) {
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  const clean = redact({ ...emptyState(), ...state });
+  const temporary = `${statePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify(clean, null, 2) + "\n", { mode: 0o600 });
+    await fs.rename(temporary, statePath);
+  } finally {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+function publicStatus(state, statePath) {
+  return {
+    schema: state.schema,
+    state_path: statePath,
+    lifecycle: state.lifecycle || "active",
+    lifecycle_reason: state.lifecycle_reason || "",
+    lifecycle_changed_at: state.lifecycle_changed_at || "",
+    cursor: state.cursor || "",
+    queue_count: (state.queue || []).length,
+    dead_letter_count: (state.dead_letters || []).length,
+    dead_letters: (state.dead_letters || []).map((item) => redact(item)),
+    last_sync_at: state.last_sync_at || "",
+    last_success_at: state.last_success_at || "",
+    last_error: redact(state.last_error)
+  };
+}
+
+function versionTuple(value) {
+  const match = String(value || "").trim().replace(/^v/i, "").match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  return match ? [Number(match[1]), Number(match[2] || 0), Number(match[3] || 0)] : null;
+}
+
+function versionAtLeast(actual, required) {
+  const left = versionTuple(actual);
+  const right = versionTuple(required);
+  if (!left || !right) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return true;
+}
+
+function assertCompatibility(result, runtimeVersion, capabilities) {
+  const compatibility = (result && result.compatibility) || (result && result.feed && result.feed.compatibility) || {};
+  const minimum = compatibility.min_runtime_version || compatibility.minRuntimeVersion || "";
+  const requiredCapabilities = Array.isArray(compatibility.required_capabilities)
+    ? compatibility.required_capabilities.map((item) => String(item))
+    : Array.isArray(compatibility.requiredCapabilities) ? compatibility.requiredCapabilities.map((item) => String(item)) : [];
+  const missing = requiredCapabilities.filter((item) => !capabilities.includes(item));
+  if ((minimum && !versionAtLeast(runtimeVersion, minimum)) || missing.length) {
+    const error = new Error("Parent Agent runtime contract is incompatible.");
+    error.code = minimum && !versionAtLeast(runtimeVersion, minimum) ? "SYNC_VERSION_INCOMPATIBLE" : "SYNC_CAPABILITY_INCOMPATIBLE";
+    error.runtime_version = runtimeVersion;
+    error.required_version = minimum;
+    error.missing_capabilities = missing;
+    throw error;
+  }
+}
+
+function createSiteAgentSyncService(options = {}) {
+  const client = options.client;
+  const siteUrl = String(options.siteUrl || options.url || process.env.SITE_URL || "").trim();
+  const statePath = path.resolve(options.statePath || process.env.AGENT_ID_SYNC_STATE || path.join(process.cwd(), ".agent-id", "sync-state.json"));
+  const maxDeliveryAttempts = Math.max(1, Math.min(10, Number(options.maxDeliveryAttempts || 3)));
+  const retryBaseMs = Math.max(0, Number(options.retryBaseMs == null ? 1000 : options.retryBaseMs));
+  const intervalMs = Math.max(1000, Number(options.intervalMs || process.env.AGENT_ID_SYNC_INTERVAL_MS || 900000));
+  const heartbeatIntervalMs = Math.max(300000, Number(options.heartbeatIntervalMs || process.env.AGENT_ID_HEARTBEAT_INTERVAL_MS || options.intervalMs || 900000));
+  const collector = options.collector || null;
+  const runtimeVersion = String(options.runtimeVersion || process.env.AGENT_ID_RUNTIME_VERSION || "0.1.0");
+  const capabilities = Array.from(new Set((Array.isArray(options.capabilities) ? options.capabilities : ["heartbeat", "insights_feed"]).map((item) => String(item).trim()).filter(Boolean))).sort();
+  const now = options.now || Date.now;
+  const sleep = options.sleep || ((ms, signal) => new Promise((resolve) => {
+    if (signal && signal.aborted) return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", done);
+      resolve();
+    }
+    if (signal) signal.addEventListener("abort", done, { once: true });
+  }));
+  if (!client || typeof client.syncOnce !== "function" || typeof client.call !== "function") {
+    throw new Error("A Site Agent client with syncOnce() and call() is required.");
+  }
+  if (collector && (typeof collector.flush !== "function" || typeof collector.status !== "function")) {
+    throw new Error("collector must expose flush() and status().");
+  }
+  if (!siteUrl) throw new Error("siteUrl or SITE_URL is required.");
+
+  async function collectorStatus() {
+    if (!collector) return null;
+    try { return await Promise.resolve().then(() => collector.status()); }
+    catch (error) { return { schema: "agentx-telemetry-status-v1", ok: false, error: redact({ code: error.code || "COLLECTOR_STATUS_FAILED", message: error.message || "Collector status failed" }) }; }
+  }
+  async function status() {
+    const result = publicStatus(await readState(statePath), statePath);
+    if (collector) result.collector = await collectorStatus();
+    return result;
+  }
+
+  async function transition(nextLifecycle, reason = "") {
+    const state = await readState(statePath);
+    const current = state.lifecycle || "active";
+    if (current === "revoked" && nextLifecycle === "active") {
+      const error = new Error("A revoked Site Agent cannot be resumed.");
+      error.code = "SYNC_REVOKED";
+      throw error;
+    }
+    if (!["active", "paused", "disconnected", "revoked"].includes(nextLifecycle)) {
+      const error = new Error(`Unsupported lifecycle state: ${nextLifecycle}`);
+      error.code = "SYNC_INVALID_LIFECYCLE";
+      throw error;
+    }
+    state.lifecycle = nextLifecycle;
+    state.lifecycle_reason = String(reason || "").slice(0, 240);
+    state.lifecycle_changed_at = new Date(now()).toISOString();
+    await writeState(statePath, state);
+    return publicStatus(state, statePath);
+  }
+
+  async function assertActive() {
+    const state = await readState(statePath);
+    const lifecycle = state.lifecycle || "active";
+    if (lifecycle !== "active") {
+      const error = new Error(`Site Agent sync is ${lifecycle}.`);
+      error.code = "SYNC_LIFECYCLE_BLOCKED";
+      error.lifecycle = lifecycle;
+      throw error;
+    }
+    return state;
+  }
+
+  async function enqueue(action, payload = {}) {
+    action = String(action || "").trim();
+    if (!/^[a-z][a-z0-9_]{1,79}$/.test(action)) throw new Error("Queue action must be a private Site Agent action id.");
+    const state = await readState(statePath);
+    const item = {
+      id: crypto.randomUUID(),
+      action,
+      payload: redact({ ...payload, url: payload.url || siteUrl }),
+      attempts: 0,
+      created_at: new Date(now()).toISOString(),
+      next_attempt_at: now()
+    };
+    state.queue.push(item);
+    await writeState(statePath, state);
+    return redact(item);
+  }
+
+  async function flushQueue({ force = false } = {}) {
+    await assertActive();
+    const state = await readState(statePath);
+    const remaining = [];
+    let delivered = 0;
+    let retrying = 0;
+    let deadLettered = 0;
+    for (const queued of state.queue) {
+      if (!force && Number(queued.next_attempt_at || 0) > now()) {
+        remaining.push(queued);
+        continue;
+      }
+      try {
+        await client.call(queued.action, redact(queued.payload || {}));
+        delivered += 1;
+      } catch (err) {
+        const failed = {
+          ...queued,
+          attempts: Number(queued.attempts || 0) + 1,
+          last_error: redact({ code: err.code || "DELIVERY_FAILED", message: err.message || "Delivery failed" })
+        };
+        if (failed.attempts >= maxDeliveryAttempts) {
+          failed.failed_at = new Date(now()).toISOString();
+          state.dead_letters.push(failed);
+          deadLettered += 1;
+        } else {
+          failed.next_attempt_at = now() + Math.min(300000, retryBaseMs * (2 ** Math.max(0, failed.attempts - 1)));
+          remaining.push(failed);
+          retrying += 1;
+        }
+      }
+    }
+    state.queue = remaining;
+    state.dead_letters = state.dead_letters.slice(-100);
+    await writeState(statePath, state);
+    return { delivered, retrying, dead_lettered: deadLettered, queue_count: remaining.length };
+  }
+
+  async function runOnce(payload = {}) {
+    const initialState = await assertActive();
+    const delivery = await flushQueue();
+    const telemetry = collector
+      ? await Promise.resolve().then(() => collector.flush()).catch((error) => ({ ok: false, delivered: 0, error: redact({ code: error.code || "COLLECTOR_FLUSH_FAILED", message: error.message || "Collector flush failed" }) }))
+      : null;
+    const state = initialState;
+    state.last_sync_at = new Date(now()).toISOString();
+    try {
+      const heartbeatDue = Number(state.last_heartbeat_at || 0) + heartbeatIntervalMs <= now();
+      const result = await client.syncOnce({
+        ...payload,
+        heartbeat: payload.heartbeat === false ? false : heartbeatDue,
+        url: payload.url || siteUrl,
+        cursor: state.cursor || "",
+        runtime_version: runtimeVersion,
+        capabilities
+      });
+      assertCompatibility(result, runtimeVersion, capabilities);
+      state.cursor = result.cursor || state.cursor || "";
+      state.last_success_at = new Date(now()).toISOString();
+      if (payload.heartbeat !== false && heartbeatDue) state.last_heartbeat_at = now();
+      state.last_error = null;
+      await writeState(statePath, state);
+      return { ...result, delivery, telemetry, service: { ...publicStatus(state, statePath), ...(collector ? { collector: await collectorStatus() } : {}) } };
+    } catch (err) {
+      state.last_error = redact({ code: err.code || "SYNC_FAILED", message: err.message || "Sync failed", at: state.last_sync_at });
+      await writeState(statePath, state);
+      throw err;
+    }
+  }
+
+  async function run({ signal, onCycle } = {}) {
+    while (!signal || !signal.aborted) {
+      let result;
+      try {
+        result = await runOnce();
+      } catch (err) {
+        result = { ok: false, error: redact({ code: err.code || "SYNC_FAILED", message: err.message || "Sync failed" }) };
+      }
+      if (typeof onCycle === "function") await onCycle(result);
+      if (signal && signal.aborted) break;
+      await sleep(intervalMs, signal);
+    }
+    return status();
+  }
+
+  return Object.freeze({
+    statePath,
+    siteUrl,
+    runtimeVersion,
+    capabilities,
+    heartbeatIntervalMs,
+    status,
+    enqueue,
+    flushQueue,
+    runOnce,
+    run,
+    pause: (reason) => transition("paused", reason),
+    disconnect: (reason) => transition("disconnected", reason),
+    resume: (reason) => transition("active", reason),
+    revoke: (reason) => transition("revoked", reason)
+  });
+}
+
+module.exports = { createSiteAgentSyncService };

package/task-executor.js

@@ -0,0 +1,129 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { authorizeTask } = require("./local-policy.js");
+
+const SIGNED_FIELDS = ["schema","task_id","subject","connector","resource","operations","expected_hash","policy_digest","idempotency_key","causation_id","task_version","issuer_key_id","issued_at","expires_at"];
+
+function executorError(code) { const error = new Error(code); error.code = code; return error; }
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+function canonical(value) { return Buffer.from(JSON.stringify(stableValue(value)), "utf8"); }
+function hash(value) { return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`; }
+function exactSubject(left, right) {
+  return ["tenant_id","host","environment","agent_id"].every((field) => String(left && left[field] || "") === String(right && right[field] || ""));
+}
+function keyId(publicKey) {
+  const raw = publicKey.export({ type: "spki", format: "der" });
+  const prefix = Buffer.from("302a300506032b6570032100", "hex");
+  const keyBytes = raw.subarray(prefix.length);
+  return `ed25519:${crypto.createHash("sha256").update(keyBytes).digest("hex").slice(0, 24)}`;
+}
+function verifyTask(task, publicKey, subject, now) {
+  if (!task || task.schema !== "agentx-enterprise-task-v1" || task.task_version !== 1 || !task.signature || !exactSubject(task.subject, subject)) throw executorError("invalid_task_envelope");
+  if (now < Number(task.issued_at) || now >= Number(task.expires_at)) throw executorError("task_expired");
+  const key = crypto.createPublicKey(publicKey);
+  if (task.issuer_key_id !== keyId(key)) throw executorError("invalid_task_signature");
+  const payload = Object.fromEntries(SIGNED_FIELDS.map((field) => [field, task[field]]));
+  if (!crypto.verify(null, canonical(payload), key, Buffer.from(task.signature, "base64url"))) throw executorError("invalid_task_signature");
+  if (!task.resource || !task.operations.every((operation) => operation.path === task.resource.path)) throw executorError("task_resource_boundary_mismatch");
+}
+function writeState(statePath, state) {
+  const target = path.resolve(statePath);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, target);
+    fs.chmodSync(target, 0o600);
+  } finally { try { fs.rmSync(temporary, { force: true }); } catch (_error) {} }
+}
+function loadState(statePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    return parsed && parsed.schema === "agentx-local-executor-state-v1" && parsed.tasks && typeof parsed.tasks === "object"
+      ? parsed : { schema: "agentx-local-executor-state-v1", tasks: {} };
+  } catch (error) {
+    if (error.code === "ENOENT") return { schema: "agentx-local-executor-state-v1", tasks: {} };
+    throw error;
+  }
+}
+function createTaskExecutor({ issuerPublicKey, identity, policy, connectors, statePath, now = () => Math.floor(Date.now() / 1000) } = {}) {
+  if (!issuerPublicKey || !identity || !identity.key_path || !identity.subject || !policy || !statePath) throw executorError("executor_configuration_invalid");
+  const state = loadState(statePath);
+  const runtime = new Map();
+  const persist = () => writeState(statePath, state);
+  async function prepare(task) {
+    verifyTask(task, issuerPublicKey, identity.subject, now());
+    const connector = connectors && connectors[task.connector];
+    if (!connector) throw executorError("unknown_connector");
+    const resourceRequest = { ...task.resource, environment: task.subject.environment };
+    const current = await connector.readResource(resourceRequest);
+    const policyTask = {
+      ...task,
+      environment: task.subject.environment,
+      operations: task.operations.map((operation) => ({ ...operation, operation: operation.op }))
+    };
+    authorizeTask(policy, policyTask, current);
+    const plan = await connector.planOperations(policyTask, current);
+    return { connector, current, plan, policyTask };
+  }
+  return Object.freeze({
+    async plan(task) {
+      const prepared = await prepare(task);
+      runtime.set(task.task_id, { task, ...prepared });
+      state.tasks[task.task_id] = { task_id: task.task_id, connector: task.connector, idempotency_key: task.idempotency_key, state: "planned", policy_digest: task.policy_digest, envelope_hash: hash(canonical(Object.fromEntries(SIGNED_FIELDS.map((field) => [field, task[field]])))) };
+      persist();
+      return { schema: "agentx-local-execution-plan-v1", task_id: task.task_id, connector: task.connector, approval_required: true, plan_hash: hash(canonical(prepared.plan)), changes: prepared.plan.changes.map(({ after_content, rollback_entries, ...item }) => item) };
+    },
+    async apply(task, approval = {}) {
+      const existing = state.tasks[task.task_id];
+      if (existing && existing.state === "deployed" && existing.result) return existing.result;
+      if (approval.approved !== true || approval.task_id !== task.task_id || approval.policy_digest !== policy.digest) throw executorError("approval_required");
+      const prepared = runtime.get(task.task_id) || { task, ...(await prepare(task)) };
+      const receipt = await prepared.connector.applyOperations(prepared.plan);
+      await prepared.connector.verifyLocalResult(receipt);
+      const appliedResource = (receipt.applied_changes || []).find((item) => item.path === task.resource.path) || {};
+      const publicReceipt = {
+        schema: "agentx-customer-execution-receipt-v1",
+        receipt_nonce: crypto.randomUUID(),
+        task_id: task.task_id,
+        subject: identity.subject,
+        connector: task.connector,
+        policy_digest: policy.digest,
+        resource: task.resource,
+        public_url: task.resource.public === false ? "" : `https://${identity.subject.host}/${String(task.resource.path || task.resource.id || "").replace(/^\/+/, "")}`,
+        result_hash: String(appliedResource.after_sha256 || ""),
+        applied_at: now(),
+        connector_receipt_hash: hash(canonical(receipt))
+      };
+      const privateKey = crypto.createPrivateKey(fs.readFileSync(identity.key_path, "utf8"));
+      publicReceipt.signature = crypto.sign(null, canonical(publicReceipt), privateKey).toString("base64url");
+      publicReceipt.receipt_hash = hash(canonical(publicReceipt));
+      state.tasks[task.task_id] = { ...state.tasks[task.task_id], state: "deployed", receipt_hash: publicReceipt.receipt_hash, result: publicReceipt };
+      runtime.set(task.task_id, { ...prepared, connectorReceipt: receipt });
+      persist();
+      return publicReceipt;
+    },
+    async rollback(taskId, approval = {}) {
+      if (approval.approved !== true || approval.task_id !== taskId) throw executorError("approval_required");
+      const prepared = runtime.get(taskId);
+      const taskState = state.tasks[taskId];
+      if (!taskState || taskState.state !== "deployed") throw executorError("rollback_receipt_unavailable");
+      const connector = prepared && prepared.connector || connectors && connectors[taskState.connector];
+      if (!connector) throw executorError("unknown_connector");
+      const receipt = await connector.rollback(prepared && prepared.connectorReceipt);
+      state.tasks[taskId] = { ...taskState, state: "rolled_back", rollback_receipt_hash: hash(canonical(receipt)) };
+      persist();
+      return receipt;
+    },
+    status(taskId) { return state.tasks[taskId] ? JSON.parse(JSON.stringify(state.tasks[taskId])) : null; }
+  });
+}
+
+module.exports = { createTaskExecutor };

package/telemetry-collector.js

@@ -0,0 +1,163 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const SENSITIVE_KEYS = /^(?:authorization|cookie|set_cookie|email|e_mail|query|query_string|access_token|refresh_token|bootstrap_secret|password|secret|order_id|orderid)$/i;
+const EMAIL = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+
+function cleanString(value, key = "") {
+  if (/url|uri|href/i.test(key)) {
+    try {
+      const parsed = new URL(value);
+      parsed.search = "";
+      parsed.hash = "";
+      return parsed.toString();
+    } catch (_error) {}
+  }
+  return String(value).replace(EMAIL, "[redacted-email]");
+}
+function redact(value, key = "") {
+  if (SENSITIVE_KEYS.test(key)) return "[redacted]";
+  if (Array.isArray(value)) return value.map((item) => redact(item));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([childKey, item]) => [childKey, redact(item, childKey)]));
+  return typeof value === "string" ? cleanString(value, key) : value;
+}
+function bytes(value) { return Buffer.byteLength(JSON.stringify(value), "utf8"); }
+function emptyState() {
+  return { schema: "agentx-telemetry-buffer-v1", events: [], dead_letters: [], retry_at: 0, attempts: 0, last_flush_at: 0, last_error: null };
+}
+function loadState(statePath, maxFileBytes) {
+  try {
+    if (fs.statSync(statePath).size > maxFileBytes) throw new Error("collector_state_too_large");
+    const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    return { ...emptyState(), ...parsed, events: Array.isArray(parsed.events) ? parsed.events : [], dead_letters: Array.isArray(parsed.dead_letters) ? parsed.dead_letters : [] };
+  } catch (error) {
+    if (error.code === "ENOENT") return emptyState();
+    throw error;
+  }
+}
+function writeState(statePath, state) {
+  const target = path.resolve(statePath);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, target);
+    fs.chmodSync(target, 0o600);
+  } finally { try { fs.rmSync(temporary, { force: true }); } catch (_error) {} }
+}
+function createTelemetryCollector({
+  client,
+  statePath,
+  subject,
+  maxBytes = 50 * 1024 * 1024,
+  maxAgeMs = 24 * 60 * 60 * 1000,
+  maxEvents = 50000,
+  maxBatchBytes = 256 * 1024,
+  maxBatchEvents = 250,
+  maxDeadLetters = 100,
+  now = Date.now,
+  random = Math.random
+} = {}) {
+  if (!client || typeof client.call !== "function" || !statePath || !subject) throw new Error("collector_configuration_invalid");
+  maxBytes = Math.max(1024, Number(maxBytes) || 50 * 1024 * 1024);
+  maxAgeMs = Math.max(1000, Number(maxAgeMs) || 24 * 60 * 60 * 1000);
+  maxEvents = Math.max(1, Number(maxEvents) || 50000);
+  maxBatchBytes = Math.max(512, Number(maxBatchBytes) || 256 * 1024);
+  maxBatchEvents = Math.max(1, Math.min(250, Number(maxBatchEvents) || 250));
+  maxDeadLetters = Math.max(1, Math.min(100, Number(maxDeadLetters) || 100));
+  const state = loadState(statePath, maxBytes + 1024 * 1024);
+  function persist() { writeState(statePath, state); }
+  function prune(timestamp = now()) {
+    const cutoff = timestamp - maxAgeMs;
+    const removed = [];
+    state.events = state.events.filter((event) => {
+      if (Number(event.ingestion_time) < cutoff) { removed.push({ ...event, dead_letter_reason: "expired_buffer_event" }); return false; }
+      return true;
+    });
+    while (state.events.length > maxEvents || bytes(state.events) > maxBytes) removed.push({ ...state.events.shift(), dead_letter_reason: "buffer_limit_pruned" });
+    state.dead_letters.push(...removed.map((event) => ({ event_id: event.event_id, source: event.source, dead_letter_reason: event.dead_letter_reason, failed_at: timestamp })));
+    state.dead_letters = state.dead_letters.slice(-maxDeadLetters);
+    persist();
+    return { removed: removed.length, event_count: state.events.length };
+  }
+  async function record(event) {
+    const timestamp = now();
+    const eventId = String(event && (event.event_id || event.id) || crypto.randomUUID());
+    if (state.events.some((item) => item.event_id === eventId) || state.dead_letters.some((item) => item.event_id === eventId)) return { recorded: false, duplicate: true, event_id: eventId };
+    const cleaned = redact(event || {});
+    const normalized = {
+      ...cleaned,
+      schema_version: "1",
+      event_id: eventId,
+      event: String(cleaned.event || "unknown").slice(0, 80),
+      event_time: Number(cleaned.event_time || timestamp),
+      ingestion_time: timestamp,
+      source: String(cleaned.source || "site_agent").slice(0, 80),
+      subject: { tenant_id: subject.tenant_id, host: subject.host, environment: subject.environment, agent_id: subject.agent_id }
+    };
+    if (normalized.user_agent && !normalized.verified_bot_identity) normalized.identity_confidence = "user_agent_only_spoofable";
+    state.events.push(normalized);
+    prune(timestamp);
+    return { recorded: true, event_id: eventId };
+  }
+  function nextBatch(timestamp) {
+    const selected = [];
+    for (const event of state.events) {
+      if (event.expires_at && Number(event.expires_at) <= timestamp) continue;
+      const candidate = [...selected, event];
+      if (candidate.length > maxBatchEvents || bytes({ schema: "agentx-telemetry-batch-v1", events: candidate }) > maxBatchBytes) break;
+      selected.push(event);
+    }
+    return selected;
+  }
+  async function flush() {
+    const timestamp = now();
+    prune(timestamp);
+    const expired = state.events.filter((event) => event.expires_at && Number(event.expires_at) <= timestamp);
+    if (expired.length) {
+      const ids = new Set(expired.map((event) => event.event_id));
+      state.events = state.events.filter((event) => !ids.has(event.event_id));
+      state.dead_letters.push(...expired.map((event) => ({ event_id: event.event_id, source: event.source, dead_letter_reason: "expired_work_refused", failed_at: timestamp })));
+      state.dead_letters = state.dead_letters.slice(-maxDeadLetters);
+    }
+    if (state.retry_at > timestamp) { persist(); return { attempted: 0, delivered: 0, retry_at: state.retry_at, event_count: state.events.length }; }
+    const batch = nextBatch(timestamp);
+    if (!batch.length && state.events.length) {
+      const oversized = state.events.shift();
+      state.dead_letters.push({ event_id: oversized.event_id, source: oversized.source, dead_letter_reason: "event_exceeds_batch_limit", failed_at: timestamp });
+      state.dead_letters = state.dead_letters.slice(-maxDeadLetters);
+      persist();
+      return { attempted: 0, delivered: 0, retry_at: 0, event_count: state.events.length };
+    }
+    if (!batch.length) { persist(); return { attempted: 0, delivered: 0, retry_at: 0, event_count: 0 }; }
+    try {
+      await client.call("site_agent_events", { schema: "agentx-telemetry-batch-v1", events: batch });
+      const deliveredIds = new Set(batch.map((event) => event.event_id));
+      state.events = state.events.filter((event) => !deliveredIds.has(event.event_id));
+      state.retry_at = 0;
+      state.attempts = 0;
+      state.last_flush_at = timestamp;
+      state.last_error = null;
+      persist();
+      return { attempted: batch.length, delivered: batch.length, retry_at: 0, event_count: state.events.length };
+    } catch (error) {
+      state.attempts += 1;
+      const retryAfter = Number(error.retry_after_ms || error.retryAfterMs || 0);
+      const backoff = Math.min(300000, 1000 * (2 ** Math.min(8, state.attempts - 1)));
+      state.retry_at = timestamp + (retryAfter > 0 ? retryAfter : Math.round(backoff * (0.5 + random())));
+      state.last_error = { code: String(error.code || error.status || "delivery_failed"), message: String(error.message || "delivery_failed").slice(0, 240) };
+      persist();
+      return { attempted: batch.length, delivered: 0, retry_at: state.retry_at, event_count: state.events.length };
+    }
+  }
+  async function status() {
+    prune(now());
+    return { schema: "agentx-telemetry-status-v1", event_count: state.events.length, dead_letter_count: state.dead_letters.length, bytes: bytes(state.events), retry_at: state.retry_at, last_flush_at: state.last_flush_at, last_error: state.last_error };
+  }
+  return Object.freeze({ record, flush, status, prune });
+}
+
+module.exports = { createTelemetryCollector };