@twin3-ai/agent-id 0.1.0

package/site-agent.js

@@ -0,0 +1,1010 @@
+"use strict";
+
+const { DEFAULT_ENDPOINT } = require("./runtime-config.js");
+
+const SITE_AGENT_KEY_POLICY = Object.freeze({
+  serverSideOnly: true,
+  keepIn: ["backend", "CMS connector", "worker secret", "server-side agent runtime"],
+  neverExposeIn: ["browser JavaScript", "public HTML", "client-side bundle"],
+  privateEndpoint: "/api/site_agents/call"
+});
+
+function normalizeEndpoint(value) {
+  return String(value || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+
+function siteAgentError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function defaultSleep(ms, signal) {
+  return 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 });
+  });
+}
+
+function retryDelayMs(res, attempt, baseMs) {
+  const retryAfter = res && res.headers && typeof res.headers.get === "function"
+    ? res.headers.get("retry-after")
+    : null;
+  if (retryAfter && /^\d+(\.\d+)?$/.test(String(retryAfter).trim())) {
+    return Math.min(30000, Math.max(0, Number(retryAfter) * 1000));
+  }
+  return Math.min(30000, baseMs * (2 ** Math.max(0, attempt - 1)));
+}
+
+const C5_REPAIR_CATALOG = Object.freeze({
+  content_schema_supported: ["Regenerate the Content Pack with the supported AgentX content schema.", "regenerate_content_pack"],
+  c1_plan_present: ["Regenerate the C1 answer-first content plan before publication.", "regenerate_content_plan"],
+  c4_package_present: ["Regenerate the C4 content workflow package before publication.", "regenerate_content_workflow"],
+  c2_prompt_sheet_present: ["Create the C2 fixed prompt-test sheet before reporting AI visibility.", "create_prompt_test_sheet"],
+  six_step_workflow_complete: ["Complete all six C4 workflow steps before owner review.", "complete_content_workflow"],
+  work_products_complete: ["Add the missing C1/C4 work products to the Content Pack.", "complete_work_products"],
+  deliverable_files_complete: ["Add all required deliverable files to the Content Pack manifest.", "complete_deliverable_files"],
+  manual_measurement_required: ["Add manual prompt-test requirements before claiming AI visibility.", "add_measurement_protocol"],
+  no_external_service_claim: ["Remove claims that the pack ran real AI engines unless observed evidence is supplied.", "owner_content_review"],
+  no_background_mutation_claim: ["Add owner-review and no-background-mutation boundaries.", "owner_content_review"],
+  no_credentials_required_for_review: ["Remove credential requirements from the C5 review package.", "remove_review_credentials"],
+  no_fabricated_statistics: ["Remove or label unsupported statistics before publication.", "owner_content_review"],
+  no_fabricated_competitor_scores: ["Replace competitor scores with evidence-backed rows or manual-check labels.", "owner_content_review"],
+  no_ai_citation_guarantee: ["Remove guaranteed AI citation/ranking claims and keep measurement as observed evidence.", "owner_content_review"]
+});
+
+function contentWorkflowRepairItems(failedChecks = []) {
+  return failedChecks.map((check) => {
+    const [nextStep, route] = C5_REPAIR_CATALOG[check] || ["Fix this failed C5 review check before publication.", "owner_content_review"];
+    return {
+      id: `repair_${check}`,
+      failed_check: check,
+      title: `Repair ${check}`,
+      route,
+      next_step: nextStep,
+      source: "content_workflow_review"
+    };
+  });
+}
+
+function contentWorkflowReviewGate(review = {}) {
+  const failedChecks = Array.isArray(review.failed_checks) ? review.failed_checks : [];
+  const passed = review.ok === true && failedChecks.length === 0;
+  const repairItems = passed ? [] : contentWorkflowRepairItems(failedChecks);
+  return {
+    schema: "agentx-c5-review-gate-v0.1",
+    status: passed ? "passed" : "blocked",
+    release_status: passed ? "ready_for_owner_review" : "blocked_by_c5_review",
+    review_status: review.review_status || (passed ? "reviewed" : "needs_revision"),
+    failed_checks: failedChecks,
+    repair_items: repairItems,
+    recommended_next_step: review.recommended_next_step || (passed ? "publish_owner_reviewed_outputs_then_run_c2_c3_a2_measurement" : "fix_failed_checks_before_publication_or_claims"),
+    source_hash: review.content_hash || ""
+  };
+}
+
+function monthlyDeliverySummary(parts = {}) {
+  const pack = parts.pack || {};
+  const review = parts.review || {};
+  const repairPack = parts.repair_pack || parts.repairPack || {};
+  const repairJobDrafts = parts.repair_job_drafts || parts.repairJobDrafts || {};
+  const reviewGate = contentWorkflowReviewGate(review);
+  const monthlyPackage = parts.package || {};
+  const tracker = parts.tracker || {};
+  const scorecard = parts.scorecard || {};
+  const dashboard = parts.dashboard || {};
+  const claimLimits = Array.isArray(dashboard.claim_limits) ? dashboard.claim_limits : [];
+  const decisionQueue = (Array.isArray(repairJobDrafts.drafts) ? repairJobDrafts.drafts : [])
+    .filter((draft) => draft && draft.draft_id)
+    .map((draft) => ({
+      id: `decide_${draft.draft_id}`,
+      status: "awaiting_owner_or_agent_decision",
+      decision_options: ["accept", "defer", "reject"],
+      draft_id: draft.draft_id || "",
+      title: draft.title || draft.check_id || draft.draft_id || "",
+      priority: draft.priority || "",
+      source: "repair_job_drafts",
+      source_repair_item_id: draft.source_repair_item_id || "",
+      check_id: draft.check_id || draft.failed_check || "",
+      route: draft.route || draft.repair_route || "",
+      decision_helper: "createSiteAgentClient().decideJobDraft",
+      decision_action: "decide_job_draft",
+      accept_helper: "createSiteAgentClient().acceptJobDraft",
+      accept_action: "accept_job_draft",
+      required_confirmation: "owner_or_authorized_website_agent"
+    }));
+  const claimBoundaries = new Set([
+    ...(Array.isArray(dashboard.non_claims) ? dashboard.non_claims : []),
+    ...(Array.isArray(scorecard.non_claims) ? scorecard.non_claims : []),
+    ...claimLimits.map((item) => item && item.id).filter(Boolean),
+    ...(reviewGate.status === "blocked" ? ["content_workflow_review_failed"] : []),
+    ...(decisionQueue.length ? ["does_not_accept_or_start_jobs_without_explicit_confirmation"] : []),
+    "does_not_modify_customer_site"
+  ]);
+  return {
+    schema: "agentx-monthly-delivery-summary-v0.1",
+    host: dashboard.host || scorecard.host || monthlyPackage.host || pack.host || "",
+    url: dashboard.url || scorecard.url || monthlyPackage.url || pack.url || "",
+    agent_id: dashboard.agent_id || scorecard.agent_id || monthlyPackage.agent_id || pack.agent_id || "",
+    period: dashboard.period || scorecard.period || monthlyPackage.period || {},
+    headline: reviewGate.status === "passed" ? (dashboard.headline || "Monthly AEO evidence package is ready for review.") : "C5 review needs revision before publication or reporting.",
+    review_gate: reviewGate,
+    deliverables: [
+      { id: "content_pack", label: "Content Pack", schema: pack.schema || "", source_hash: pack.content_hash || "" },
+      { id: "c5_content_workflow_review", label: "C5 Content Workflow Review", schema: review.schema || "", source_hash: review.content_hash || "" },
+      ...(repairPack.schema ? [{ id: "c6_content_repair_pack", label: "C6 Content Repair Pack", schema: repairPack.schema || "", source_hash: repairPack.content_hash || "" }] : []),
+      ...(repairJobDrafts.schema ? [{ id: "c6_repair_job_drafts", label: "C6 Repair Job Drafts", schema: repairJobDrafts.schema || "", source_hash: repairJobDrafts.content_hash || "" }] : []),
+      { id: "m2_monthly_optimization_package", label: "M2 Monthly Optimization Package", schema: monthlyPackage.schema || "", source_hash: monthlyPackage.content_hash || "" },
+      { id: "m3_monthly_execution_tracker", label: "M3 Monthly Execution Tracker", schema: tracker.schema || "", source_hash: tracker.content_hash || "" },
+      { id: "m4_monthly_outcome_scorecard", label: "M4 Monthly Outcome Scorecard", schema: scorecard.schema || "", source_hash: scorecard.content_hash || "" },
+      { id: "m5_monthly_dashboard", label: "M5 Monthly Dashboard", schema: dashboard.schema || "", source_hash: dashboard.content_hash || "" }
+    ],
+    source_hashes: {
+      pack: pack.content_hash || "",
+      review: review.content_hash || "",
+      repair_pack: repairPack.content_hash || "",
+      repair_job_drafts: repairJobDrafts.content_hash || "",
+      package: monthlyPackage.content_hash || "",
+      tracker: tracker.content_hash || "",
+      scorecard: scorecard.content_hash || "",
+      dashboard: dashboard.content_hash || ""
+    },
+    kpi_cards: (Array.isArray(dashboard.kpi_cards) ? dashboard.kpi_cards : []).map((item) => ({
+      id: item.id || "",
+      label: item.label || "",
+      value: item.value || "",
+      status: item.status || "",
+      source: item.source || "",
+      claim_level: item.claim_level || ""
+    })),
+    decision_queue: decisionQueue,
+    next_actions: [
+      ...(reviewGate.status === "blocked" ? [{
+        id: "fix_c5_content_workflow_review",
+        title: "Fix C5 content workflow review",
+        next_step: reviewGate.recommended_next_step,
+        source: "content_workflow_review"
+      }] : []),
+      ...(Array.isArray(dashboard.next_actions) ? dashboard.next_actions : []).map((item) => ({
+      id: item.id || "",
+      title: item.title || item.id || "",
+      next_step: item.next_step || item.action || "",
+      source: item.source || ""
+      }))
+    ],
+    claim_boundaries: Array.from(claimBoundaries).sort(),
+    non_claims: [
+      "summary_does_not_recalculate_evidence",
+      "does_not_accept_or_start_jobs_without_explicit_confirmation",
+      "does_not_prove_incrementality_or_causality",
+      "does_not_modify_customer_site"
+    ]
+  };
+}
+
+function normalizeEvidenceItems(payload, applyPlan) {
+  const applyItems = Array.isArray(applyPlan && applyPlan.apply_items) ? applyPlan.apply_items : [];
+  const firstApplyItem = applyItems[0] || {};
+  const firstDeliveryItem = applyItems.find((item) => item && item.route !== "owner_decision_review") || {};
+  const rawItems = payload.evidence_items || payload.evidenceItems || payload.evidence || [];
+  const items = Array.isArray(rawItems) ? rawItems : (rawItems ? [rawItems] : []);
+  if (items.length) {
+    return items.map((item) => ({
+      ...item,
+      apply_item_id: item.apply_item_id || item.applyItemId || (item.apply_item && item.apply_item.id) || firstApplyItem.id || ""
+    }));
+  }
+  if (payload.evidence_uri || payload.proof_url || payload.pull_request_url || payload.deployment_reference) {
+    const targetItem = firstDeliveryItem.id ? firstDeliveryItem : firstApplyItem;
+    if (targetItem.route === "owner_decision_review") return [];
+    return [{
+      apply_item_id: payload.apply_item_id || payload.applyItemId || targetItem.id || "",
+      evidence_uri: payload.evidence_uri,
+      proof_url: payload.proof_url,
+      pull_request_url: payload.pull_request_url,
+      deployment_reference: payload.deployment_reference,
+      verify_proof: payload.verify_proof,
+      verify: payload.verify
+    }];
+  }
+  return [];
+}
+
+function normalizePromptResultRows(payload) {
+  const rawRows = payload.rows || payload.results || payload.completed_rows || payload.completedRows || [];
+  if (!rawRows) return [];
+  return Array.isArray(rawRows) ? rawRows : [rawRows];
+}
+
+function requireServerSideRuntime(options) {
+  if (options && options.allowBrowser) return;
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    throw siteAgentError(
+      "SITE_AGENT_BROWSER_RUNTIME",
+      "Site Agent Key calls are server-side only. Use the browser SDK only for public page signals."
+    );
+  }
+}
+
+async function readJsonResponse(res) {
+  const text = await res.text();
+  try {
+    return JSON.parse(text || "{}");
+  } catch (_err) {
+    return { ok: res.ok, text };
+  }
+}
+
+function createSiteAgentClient(options = {}) {
+  requireServerSideRuntime(options);
+  const endpoint = normalizeEndpoint(options.endpoint || process.env.AGENT_ID_ENDPOINT || process.env.AEO_AGENT_ENDPOINT);
+  const agentKey = options.agentKey || options.agent_key || process.env.SITE_AGENT_KEY || process.env.AEO_AGENT_KEY || "";
+  const fetcher = options.fetch || globalThis.fetch;
+  const maxAttempts = Math.max(1, Math.min(5, Number(options.maxAttempts || 3)));
+  const retryBaseMs = Math.max(0, Number(options.retryBaseMs == null ? 250 : options.retryBaseMs));
+  const sleep = options.sleep || defaultSleep;
+  if (typeof fetcher !== "function") {
+    throw siteAgentError("FETCH_UNAVAILABLE", "A fetch implementation is required to call the Site Agent API.");
+  }
+
+  async function fetchWithRetry(url, request) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      try {
+        const res = await fetcher(url, request);
+        const retryableStateConflict = res && res.status === 409 && res.headers
+          && typeof res.headers.get === "function"
+          && res.headers.get("x-agent-id-retryable") === "state-conflict";
+        const retryable = res && (res.status === 429 || res.status >= 500 || retryableStateConflict);
+        if (!retryable || attempt >= maxAttempts) return res;
+        if (typeof res.text === "function") await res.text();
+        await sleep(retryDelayMs(res, attempt, retryBaseMs));
+      } catch (err) {
+        lastError = err;
+        if (attempt >= maxAttempts) break;
+        await sleep(Math.min(30000, retryBaseMs * (2 ** Math.max(0, attempt - 1))));
+      }
+    }
+    throw siteAgentError(
+      "SITE_AGENT_NETWORK_FAILED",
+      lastError && lastError.message ? lastError.message : "Site Agent network request failed"
+    );
+  }
+
+  async function call(action, payload = {}) {
+    const key = payload.agent_key || payload.agentKey || agentKey;
+    if (!key) {
+      throw siteAgentError(
+        "SITE_AGENT_KEY_REQUIRED",
+        "A Site Agent Key is required for private server-side Site Agent calls."
+      );
+    }
+    const body = {
+      ...payload,
+      agent_key: key,
+      action
+    };
+    delete body.agentKey;
+    const res = await fetchWithRetry(endpoint + SITE_AGENT_KEY_POLICY.privateEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const data = await readJsonResponse(res);
+    if (!res.ok || data.ok === false) {
+      const error = siteAgentError(
+        data.code || "SITE_AGENT_CALL_FAILED",
+        data.error || data.message || `Site Agent call failed with HTTP ${res.status}`
+      );
+      error.status = res.status;
+      const retryAfter = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : "";
+      if (retryAfter && /^\d+(?:\.\d+)?$/.test(retryAfter)) error.retry_after_ms = Number(retryAfter) * 1000;
+      throw error;
+    }
+    return data;
+  }
+
+  async function publicPost(path, payload = {}) {
+    const res = await fetchWithRetry(endpoint + path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload || {})
+    });
+    const data = await readJsonResponse(res);
+    if (!res.ok || data.ok === false) {
+      const error = siteAgentError(
+        data.code || "AGENT_ID_PUBLIC_CALL_FAILED",
+        data.error || data.message || `Agent ID public call failed with HTTP ${res.status}`
+      );
+      error.status = res.status;
+      const retryAfter = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : "";
+      if (retryAfter && /^\d+(?:\.\d+)?$/.test(retryAfter)) error.retry_after_ms = Number(retryAfter) * 1000;
+      throw error;
+    }
+    return data;
+  }
+
+  return Object.freeze({
+    endpoint,
+    policy: SITE_AGENT_KEY_POLICY,
+    call,
+    verify(payload = {}) {
+      const key = payload.agent_key || payload.agentKey || agentKey;
+      if (!key) {
+        throw siteAgentError(
+          "SITE_AGENT_KEY_REQUIRED",
+          "A Site Agent Key is required to verify this website agent."
+        );
+      }
+      const body = {
+        ...payload,
+        agent_key: key
+      };
+      delete body.agentKey;
+      return publicPost("/api/site_agents/verify", body);
+    },
+    insightsFeed(payload = {}) {
+      return call("insights_feed", payload);
+    },
+    heartbeat(payload = {}) {
+      return call("site_agent_events", {
+        ...payload,
+        source: payload.source || "site_agent_sync",
+        events: [{
+          event: "heartbeat",
+          url: payload.url || payload.website || "",
+          ts: payload.ts == null ? Math.floor(Date.now() / 1000) : payload.ts,
+          data: {
+            runtime: payload.runtime || "server_side_site_agent",
+            sdk_version: payload.sdk_version || payload.sdkVersion || "0.1.0"
+          }
+        }]
+      });
+    },
+    async syncOnce(payload = {}) {
+      const heartbeat = payload.heartbeat === false
+        ? null
+        : await call("site_agent_events", {
+            ...payload,
+            source: payload.source || "site_agent_sync",
+            events: [{
+              event: "heartbeat",
+              url: payload.url || payload.website || "",
+              ts: payload.ts == null ? Math.floor(Date.now() / 1000) : payload.ts,
+              data: {
+                runtime: payload.runtime || "server_side_site_agent",
+                sdk_version: payload.sdk_version || payload.sdkVersion || "0.1.0"
+              }
+            }]
+          });
+      const feedResponse = await call("insights_feed", payload);
+      const feed = feedResponse.feed || {};
+      const sync = feedResponse.sync || {
+        changed: (feed.content_hash || "") !== (payload.cursor || ""),
+        previous_cursor: payload.cursor || "",
+        cursor: feed.content_hash || ""
+      };
+      return {
+        schema: "agentx-site-agent-sync-once-v1",
+        changed: sync.changed === true,
+        previous_cursor: sync.previous_cursor || payload.cursor || "",
+        cursor: sync.cursor || feed.content_hash || "",
+        heartbeat,
+        feed,
+        sync
+      };
+    },
+    refreshInsightInbox(payload = {}) {
+      return call("refresh_insight_inbox", payload);
+    },
+    insightInbox(payload = {}) {
+      return call("insight_inbox", payload);
+    },
+    acknowledgeInsight(payload = {}) {
+      return call("acknowledge_insight", payload);
+    },
+    dismissInsight(payload = {}) {
+      return call("dismiss_insight", payload);
+    },
+    installDescriptor(payload = {}) {
+      return call("install_descriptor", payload);
+    },
+    evidencePack(payload = {}) {
+      return call("evidence_pack", payload);
+    },
+    auditReport(payload = {}) {
+      return call("audit_report", payload);
+    },
+    implementationBundle(payload = {}) {
+      return call("implementation_bundle", payload);
+    },
+    auditFilePackage(payload = {}) {
+      return call("audit_file_package", payload);
+    },
+    skillPackage(payload = {}) {
+      return call("skill_package", payload);
+    },
+    installationVerification(payload = {}) {
+      return call("installation_verification", payload);
+    },
+    contentOptimizationPlan(payload = {}) {
+      return call("content_optimization_plan", payload);
+    },
+    citationGapMatrix(payload = {}) {
+      return call("citation_gap_matrix", payload);
+    },
+    communityCitationPlan(payload = {}) {
+      return call("community_citation_plan", payload);
+    },
+    promptTestRunSheet(payload = {}) {
+      return call("prompt_test_run_sheet", payload);
+    },
+    promptTestResults(payload = {}) {
+      return call("prompt_test_results", payload);
+    },
+    a2CitationPackage(payload = {}) {
+      return call("a2_citation_evidence_package", payload);
+    },
+    async siteEvents(payload = {}) {
+      const eventRes = await call("site_agent_events", payload);
+      return {
+        ...eventRes,
+        steps: [
+          { action: "site_agent_events", field: "import" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(eventRes.non_claims) ? eventRes.non_claims : []),
+            ...((eventRes.import && Array.isArray(eventRes.import.non_claims)) ? eventRes.import.non_claims : []),
+            "connector_observed_page_signals_only",
+            "does_not_prove_ai_crawler_read_or_conversion",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    applyPlan(payload = {}) {
+      return call("apply_plan", payload);
+    },
+    async applyCycle(payload = {}) {
+      const feedRes = await call("insights_feed", payload);
+      const applyPlanRes = await call("apply_plan", {
+        ...payload,
+        feed: feedRes.feed
+      });
+      const evidenceItems = normalizeEvidenceItems(payload, applyPlanRes.apply_plan);
+      const evidenceResults = [];
+      for (const item of evidenceItems) {
+        if (!item.apply_item_id) continue;
+        evidenceResults.push(await call("apply_evidence", {
+          ...payload,
+          ...item,
+          apply_plan: applyPlanRes.apply_plan,
+          source_feed_hash: item.source_feed_hash || (applyPlanRes.apply_plan && applyPlanRes.apply_plan.source_feed_hash) || (feedRes.feed && feedRes.feed.content_hash) || ""
+        }));
+      }
+      return {
+        ok: true,
+        schema: "agentx-site-agent-apply-cycle-v0.1",
+        lane: "site_agent_key",
+        action: "apply_cycle",
+        feed: feedRes.feed,
+        apply_plan: applyPlanRes.apply_plan,
+        evidence_results: evidenceResults,
+        responses: {
+          insights_feed: feedRes,
+          apply_plan: applyPlanRes,
+          apply_evidence: evidenceResults
+        },
+        steps: [
+          { action: "insights_feed", field: "feed" },
+          { action: "apply_plan", field: "apply_plan" },
+          ...(evidenceResults.length ? [{ action: "apply_evidence", field: "evidence_results" }] : [])
+        ],
+        non_claims: [
+          "does_not_apply_changes_without_owner_or_connector",
+          "does_not_prove_ai_ranking_or_conversion_lift",
+          "site_agent_key_must_remain_server_side"
+        ]
+      };
+    },
+    contentPack(payload = {}) {
+      return call("content_pack", payload);
+    },
+    async contentRepairPack(payload = {}) {
+      const repairRes = await call("content_repair_pack", payload);
+      return {
+        ...repairRes,
+        steps: [
+          { action: "content_repair_pack", field: "pack" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(repairRes.non_claims) ? repairRes.non_claims : []),
+            ...((repairRes.pack && Array.isArray(repairRes.pack.non_claims)) ? repairRes.pack.non_claims : []),
+            "site_agent_key_must_remain_server_side",
+            "does_not_modify_customer_site"
+          ])
+        ]
+      };
+    },
+    contentWorkflowReview(payload = {}) {
+      const body = { ...payload };
+      if (payload.contentPack && !body.content_pack) body.content_pack = payload.contentPack;
+      if (payload.package && !body.content_pack) body.content_pack = payload.package;
+      return publicPost("/api/agent/content_workflow_review", body);
+    },
+    async contentWorkflow(payload = {}) {
+      const workflowRes = await call("content_workflow_package", payload);
+      return {
+        ...workflowRes,
+        steps: [
+          { action: "content_workflow_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...((workflowRes.package && Array.isArray(workflowRes.package.non_claims)) ? workflowRes.package.non_claims : []),
+            "does_not_run_real_ai_engines",
+            "does_not_fabricate_statistics",
+            "does_not_guarantee_ai_citation_or_ranking",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async contentPublication(payload = {}) {
+      const publicationRes = await call("content_publication_package", payload);
+      return {
+        ...publicationRes,
+        steps: [
+          { action: "content_publication_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...((publicationRes.package && Array.isArray(publicationRes.package.non_claims)) ? publicationRes.package.non_claims : []),
+            "does_not_verify_ai_engine_visibility",
+            "does_not_claim_rankings_or_citations",
+            "does_not_prove_conversion_lift",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async promptTestCycle(payload = {}) {
+      const sheetRes = await call("prompt_test_run_sheet", payload);
+      const rows = normalizePromptResultRows(payload);
+      const importRes = rows.length ? await call("prompt_test_results", {
+        ...payload,
+        sheet: payload.sheet || sheetRes.sheet,
+        rows
+      }) : null;
+      return {
+        ok: true,
+        schema: "agentx-site-agent-prompt-test-cycle-v0.1",
+        lane: "site_agent_key",
+        action: "prompt_test_cycle",
+        sheet: sheetRes.sheet,
+        import_result: importRes,
+        responses: {
+          prompt_test_run_sheet: sheetRes,
+          prompt_test_results: importRes
+        },
+        steps: [
+          { action: "prompt_test_run_sheet", field: "sheet" },
+          ...(importRes ? [{ action: "prompt_test_results", field: "import_result" }] : [])
+        ],
+        non_claims: [
+          "manual_prompt_results_required",
+          "does_not_run_real_ai_engines",
+          "does_not_fabricate_ai_citations",
+          "does_not_prove_conversion_lift",
+          "site_agent_key_must_remain_server_side"
+        ]
+      };
+    },
+    async aiReads(payload = {}) {
+      const readRes = await call("a1_ai_reads", payload);
+      return {
+        ...readRes,
+        steps: [
+          { action: "a1_ai_reads", field: "import" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(readRes.non_claims) ? readRes.non_claims : []),
+            "observed_server_logs_only",
+            "does_not_prove_ai_answer_citation_or_conversion",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async conversions(payload = {}) {
+      const conversionRes = await call("b1_conversions", payload);
+      return {
+        ...conversionRes,
+        steps: [
+          { action: "b1_conversions", field: "import" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(conversionRes.non_claims) ? conversionRes.non_claims : []),
+            "observed_conversion_events_only",
+            "does_not_prove_incremental_lift_or_causality",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async a1ReadPackage(payload = {}) {
+      const packageRes = await call("a1_read_evidence_package", payload);
+      return {
+        ...packageRes,
+        steps: [
+          { action: "a1_read_evidence_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(packageRes.non_claims) ? packageRes.non_claims : []),
+            ...((packageRes.package && Array.isArray(packageRes.package.non_claims)) ? packageRes.package.non_claims : []),
+            "observed_server_logs_only",
+            "does_not_prove_ai_answer_citation_or_conversion",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async a1Dashboard(payload = {}) {
+      const dashboardRes = await call("a1_dashboard", payload);
+      return {
+        ...dashboardRes,
+        steps: [
+          { action: "a1_dashboard", field: "dashboard" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(dashboardRes.non_claims) ? dashboardRes.non_claims : []),
+            ...((dashboardRes.dashboard && Array.isArray(dashboardRes.dashboard.claim_limits)) ? dashboardRes.dashboard.claim_limits : []),
+            "observed_server_logs_only",
+            "does_not_prove_ai_answer_citation_or_conversion",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async b1ConversionPackage(payload = {}) {
+      const packageRes = await call("b1_conversion_evidence_package", payload);
+      return {
+        ...packageRes,
+        steps: [
+          { action: "b1_conversion_evidence_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(packageRes.non_claims) ? packageRes.non_claims : []),
+            ...((packageRes.package && Array.isArray(packageRes.package.non_claims)) ? packageRes.package.non_claims : []),
+            "observed_conversion_events_only",
+            "does_not_prove_incremental_lift_or_causality",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async siteSignalPackage(payload = {}) {
+      const packageRes = await call("site_signal_package", payload);
+      return {
+        ...packageRes,
+        steps: [
+          { action: "site_signal_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(packageRes.non_claims) ? packageRes.non_claims : []),
+            ...((packageRes.package && Array.isArray(packageRes.package.non_claims)) ? packageRes.package.non_claims : []),
+            "site_signal_evidence_only",
+            "does_not_prove_ai_crawler_read_or_conversion",
+            "does_not_prove_ai_answer_citation",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async outcomeReport(payload = {}) {
+      const reportRes = await call("outcome_report", payload);
+      return {
+        ...reportRes,
+        steps: [
+          { action: "outcome_report", field: "report" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(reportRes.non_claims) ? reportRes.non_claims : []),
+            ...((reportRes.report && Array.isArray(reportRes.report.non_claims)) ? reportRes.report.non_claims : []),
+            "observed_evidence_only",
+            "does_not_prove_incremental_lift_or_causality",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async outcomePackage(payload = {}) {
+      const packageRes = await call("m1_outcome_evidence_package", payload);
+      return {
+        ...packageRes,
+        steps: [
+          { action: "m1_outcome_evidence_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(packageRes.non_claims) ? packageRes.non_claims : []),
+            ...((packageRes.package && Array.isArray(packageRes.package.non_claims)) ? packageRes.package.non_claims : []),
+            "observed_evidence_only",
+            "does_not_prove_incremental_lift_or_causality",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async outcomeReview(payload = {}) {
+      const reportRes = await this.outcomeReport(payload);
+      const packageRes = await this.outcomePackage(payload);
+      return {
+        ok: true,
+        schema: "agentx-site-agent-outcome-review-v0.1",
+        lane: "site_agent_key",
+        action: "outcome_review",
+        report: reportRes.report,
+        package: packageRes.package,
+        responses: {
+          outcome_report: reportRes,
+          m1_outcome_evidence_package: packageRes
+        },
+        steps: [
+          { action: "outcome_report", field: "report" },
+          { action: "m1_outcome_evidence_package", field: "package" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(reportRes.non_claims) ? reportRes.non_claims : []),
+            ...(Array.isArray(packageRes.non_claims) ? packageRes.non_claims : []),
+            "observed_evidence_only",
+            "does_not_prove_incremental_lift_or_causality",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    monthlyPackage(payload = {}) {
+      return call("monthly_package", payload);
+    },
+    monthlyTracker(payload = {}) {
+      return call("monthly_tracker", payload);
+    },
+    monthlyScorecard(payload = {}) {
+      return call("monthly_scorecard", payload);
+    },
+    monthlyDashboard(payload = {}) {
+      return call("monthly_dashboard", payload);
+    },
+    async monthlyEvidenceLoop(payload = {}) {
+      const contentPackRes = await call("content_pack", payload);
+      const reviewRes = await publicPost("/api/agent/content_workflow_review", {
+        content_pack: contentPackRes.pack
+      });
+      const reviewGate = contentWorkflowReviewGate(reviewRes.review);
+      const repairPackRes = reviewGate.status === "blocked" ? await call("content_repair_pack", {
+        ...payload,
+        content_pack: contentPackRes.pack,
+        review_gate: reviewGate
+      }) : null;
+      const repairDraftsRes = reviewGate.status === "blocked" ? await call("job_drafts", {
+        ...payload,
+        review_gate: reviewGate
+      }) : null;
+      const loopPayload = {
+        ...payload,
+        content_pack: contentPackRes.pack
+      };
+      const packageRes = await call("monthly_package", loopPayload);
+      const trackerRes = await call("monthly_tracker", loopPayload);
+      const scorecardRes = await call("monthly_scorecard", loopPayload);
+      const dashboardRes = await call("monthly_dashboard", loopPayload);
+      const deliverySummary = monthlyDeliverySummary({
+        pack: contentPackRes.pack,
+        review: reviewRes.review,
+        repair_pack: repairPackRes && repairPackRes.pack,
+        repair_job_drafts: repairDraftsRes && repairDraftsRes.drafts,
+        package: packageRes.package,
+        tracker: trackerRes.tracker,
+        scorecard: scorecardRes.scorecard,
+        dashboard: dashboardRes.dashboard
+      });
+      return {
+        ok: true,
+        lane: "site_agent_key",
+        action: "monthly_evidence_loop",
+        pack: contentPackRes.pack,
+        review: reviewRes.review,
+        review_gate: reviewGate,
+        ...(repairPackRes ? { repair_pack: repairPackRes.pack } : {}),
+        ...(repairDraftsRes ? { repair_job_drafts: repairDraftsRes.drafts } : {}),
+        package: packageRes.package,
+        tracker: trackerRes.tracker,
+        scorecard: scorecardRes.scorecard,
+        dashboard: dashboardRes.dashboard,
+        delivery_summary: deliverySummary,
+        responses: {
+          content_pack: contentPackRes,
+          content_workflow_review: reviewRes,
+          ...(repairPackRes ? { content_repair_pack: repairPackRes } : {}),
+          ...(repairDraftsRes ? { job_drafts: repairDraftsRes } : {}),
+          monthly_package: packageRes,
+          monthly_tracker: trackerRes,
+          monthly_scorecard: scorecardRes,
+          monthly_dashboard: dashboardRes
+        },
+        steps: [
+          { action: "content_pack", field: "pack" },
+          { action: "content_workflow_review", field: "review" },
+          ...(repairPackRes ? [{ action: "content_repair_pack", field: "repair_pack" }] : []),
+          ...(repairDraftsRes ? [{ action: "job_drafts", field: "repair_job_drafts" }] : []),
+          { action: "monthly_package", field: "package" },
+          { action: "monthly_tracker", field: "tracker" },
+          { action: "monthly_scorecard", field: "scorecard" },
+          { action: "monthly_dashboard", field: "dashboard" }
+        ]
+      };
+    },
+    async optimizationCycle(payload = {}) {
+      const cycleRes = await call("optimization_cycle", payload);
+      return {
+        ...cycleRes,
+        steps: [
+          { action: "optimization_cycle", field: "cycle" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(cycleRes.non_claims) ? cycleRes.non_claims : []),
+            ...((cycleRes.cycle && Array.isArray(cycleRes.cycle.non_claims)) ? cycleRes.cycle.non_claims : []),
+            "read_only_optimization_plan_not_site_mutation",
+            "does_not_accept_or_start_jobs_without_owner_confirmation",
+            "does_not_prove_incremental_lift_or_causality",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async jobDrafts(payload = {}) {
+      const draftRes = await call("job_drafts", payload);
+      return {
+        ...draftRes,
+        steps: [
+          { action: "job_drafts", field: "drafts" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(draftRes.non_claims) ? draftRes.non_claims : []),
+            ...((draftRes.drafts && Array.isArray(draftRes.drafts.non_claims)) ? draftRes.drafts.non_claims : []),
+            "drafts_only_not_started_work",
+            "does_not_accept_or_start_jobs_without_owner_confirmation",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async acceptJobDraft(payload = {}) {
+      const acceptedRes = await call("accept_job_draft", payload);
+      return {
+        ...acceptedRes,
+        steps: [
+          { action: "accept_job_draft", field: "job" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(acceptedRes.non_claims) ? acceptedRes.non_claims : []),
+            "explicit_owner_or_agent_confirmation_required",
+            "does_not_fund_or_release_payment",
+            "does_not_prove_delivery_or_outcome",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async decideJobDraft(payload = {}) {
+      const decisionRes = await call("decide_job_draft", payload);
+      return {
+        ...decisionRes,
+        steps: [
+          { action: "decide_job_draft", field: "decision" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(decisionRes.non_claims) ? decisionRes.non_claims : []),
+            "decision_receipt_only",
+            "does_not_start_work_when_deferred_or_rejected",
+            "does_not_prove_delivery_or_outcome",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async draftDecisions(payload = {}) {
+      const historyRes = await call("draft_decisions", payload);
+      return {
+        ...historyRes,
+        steps: [
+          { action: "draft_decisions", field: "decisions" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(historyRes.non_claims) ? historyRes.non_claims : []),
+            ...((historyRes.decisions && Array.isArray(historyRes.decisions.non_claims)) ? historyRes.decisions.non_claims : []),
+            "decision_history_not_delivery_or_outcome_proof",
+            "does_not_prove_ai_ranking_or_conversion_lift",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async decisionReviews(payload = {}) {
+      const historyRes = await call("decision_reviews", payload);
+      return {
+        ...historyRes,
+        steps: [
+          { action: "decision_reviews", field: "reviews" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(historyRes.non_claims) ? historyRes.non_claims : []),
+            ...((historyRes.reviews && Array.isArray(historyRes.reviews.non_claims)) ? historyRes.reviews.non_claims : []),
+            "decision_review_history_not_delivery_or_outcome_proof",
+            "does_not_prove_ai_ranking_or_conversion_lift",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    async c5RepairHistory(payload = {}) {
+      const historyRes = await call("c5_repair_history", payload);
+      return {
+        ...historyRes,
+        steps: [
+          { action: "c5_repair_history", field: "history" }
+        ],
+        non_claims: [
+          ...new Set([
+            ...(Array.isArray(historyRes.non_claims) ? historyRes.non_claims : []),
+            ...((historyRes.history && Array.isArray(historyRes.history.non_claims)) ? historyRes.history.non_claims : []),
+            "observed_repair_ledger_only",
+            "does_not_prove_ai_ranking_or_conversion_lift",
+            "site_agent_key_must_remain_server_side"
+          ])
+        ]
+      };
+    },
+    applyEvidence(payload = {}) {
+      return call("apply_evidence", payload);
+    },
+    reportJobEvidence(payload = {}) {
+      return call("report_job_evidence", payload);
+    },
+    insights(payload = {}) {
+      return call("insights", payload);
+    },
+    jobs(payload = {}) {
+      return call("jobs", payload);
+    }
+  });
+}
+
+module.exports = {
+  SITE_AGENT_KEY_POLICY,
+  createSiteAgentClient,
+  createTelemetryCollector: (options) => require("./telemetry-collector.js").createTelemetryCollector(options)
+};