agentlinkops 0.5.0

package/scripts/disavow.py

@@ -0,0 +1,207 @@
+"""Offline, user-managed disavow lists. No network access or rule recommendations."""
+import datetime as dt
+import hashlib
+import ipaddress
+import json
+from pathlib import Path
+import re
+import urllib.parse
+
+# Google's help page states "2MB" without defining the byte convention.
+# Use decimal MB so every accepted export is below either common interpretation.
+MAX_BYTES = 2000000
+MAX_LINES = 100000
+MAX_URL = 2048
+
+
+class DisavowError(Exception):
+    def __init__(self, message, code="INVALID_DISAVOW"):
+        super().__init__(message)
+        self.code = code
+
+
+def stamp():
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def stable_id(prefix, parts):
+    return prefix + hashlib.sha256(json.dumps(parts, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()
+
+
+def domain(value):
+    if not isinstance(value, str):
+        raise DisavowError("Domain rule must contain a hostname")
+    value = value.strip().lower().removesuffix(".")
+    try:
+        ipaddress.ip_address(value)
+    except ValueError:
+        pass
+    else:
+        raise DisavowError("A domain rule requires a DNS hostname, not an IP address")
+    if len(value) > 253 or "." not in value or not value.isascii() or any(not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label) for label in value.split(".")):
+        raise DisavowError("Domain rules require an ASCII or Punycode hostname without scheme, port, path or wildcard")
+    return value
+
+
+def url(value, property_url=False):
+    if not isinstance(value, str) or not value or len(value) > MAX_URL or any(ord(char) <= 32 or ord(char) == 127 for char in value) or "\\" in value:
+        raise DisavowError("URLs must be at most 2,048 characters without whitespace or control characters")
+    try:
+        parsed = urllib.parse.urlsplit(value)
+        if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username is not None or parsed.password is not None:
+            raise ValueError()
+        port = parsed.port
+        try:
+            address = ipaddress.ip_address(parsed.hostname)
+            hostname = "[" + address.compressed + "]" if address.version == 6 else address.compressed
+        except ValueError:
+            hostname = domain(parsed.hostname)
+        if port is not None:
+            hostname += ":" + str(port)
+    except (ValueError, DisavowError) as exc:
+        raise DisavowError("Use an HTTP(S) URL with an ASCII/Punycode hostname and no credentials") from exc
+    if "*" in parsed.path or "*" in parsed.query:
+        raise DisavowError("Wildcard and subpath patterns are unsupported; specify an exact page URL or a domain rule")
+    if property_url and (parsed.query or parsed.fragment):
+        raise DisavowError("Property scope must be a URL prefix without query or fragment")
+    normalized = urllib.parse.urlunsplit((parsed.scheme, hostname, parsed.path or "/", parsed.query, parsed.fragment))
+    if len(normalized) > MAX_URL:
+        raise DisavowError("Normalized URL exceeds 2,048 characters")
+    return normalized
+
+
+def rule(kind, value):
+    if kind == "domain":
+        return domain(value)
+    if kind == "url":
+        return url(value)
+    raise DisavowError("Rule kind must be domain or url")
+
+
+def source_label(value):
+    if not isinstance(value, str) or not value.strip() or len(value) > 1024 or any(ord(char) < 32 for char in value):
+        raise DisavowError("Source provenance must be a nonempty label without control characters")
+    return value.strip()
+
+
+def parse_file(path):
+    if Path(path).suffix.lower() != ".txt":
+        raise DisavowError("Disavow import requires a .txt file")
+    with Path(path).open("rb") as file:
+        raw = file.read(MAX_BYTES + 1)
+    if len(raw) > MAX_BYTES:
+        raise DisavowError("Disavow file exceeds the 2 MB limit")
+    try:
+        original = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise DisavowError("Disavow file must be UTF-8 or 7-bit ASCII") from exc
+    # Accept a UTF-8 BOM but retain the original bytes' hash and original decoded text.
+    content = original.removeprefix("\ufeff")
+    if "\x00" in content:
+        raise DisavowError("Disavow file contains NUL characters")
+    # Counting physical LF lines (including blank/comment lines) avoids treating
+    # Unicode separators inside a URL or comment as extra file lines.
+    lines = content.split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()
+    if len(lines) > MAX_LINES:
+        raise DisavowError("Disavow file exceeds 100,000 lines including comments and blanks")
+    entries, comments = [], []
+    for number, original_line in enumerate(lines, 1):
+        line = original_line.rstrip("\r").strip()
+        if not line:
+            continue
+        if line.startswith("#"):
+            comments.append({"line": number, "text": line[1:].lstrip()})
+            continue
+        kind, value = ("domain", line[7:]) if line.startswith("domain:") else ("url", line)
+        try:
+            normalized = rule(kind, value)
+        except DisavowError as exc:
+            raise DisavowError(f"Line {number}: {exc}") from exc
+        entries.append({"kind": kind, "value": normalized, "line": number, "original": original_line.rstrip("\r"), "comments": comments})
+        comments = []
+    return original, hashlib.sha256(raw).hexdigest(), entries, len(lines)
+
+
+def import_rules(connection, path, property_url, source):
+    property_url, source = url(property_url, True), source_label(source)
+    original, digest, entries, line_count = parse_file(path)
+    source_id = stable_id("dsrc_", [property_url, source, digest, "txt"])
+    added, existing, recorded = 0, 0, stamp()
+    connection.execute("BEGIN IMMEDIATE")
+    try:
+        connection.execute("INSERT OR IGNORE INTO disavow_sources VALUES (?,?,?,?,?,?,?)", (source_id, property_url, source, digest, "txt", original, recorded))
+        for entry in entries:
+            rule_id = stable_id("drule_", [property_url, entry["kind"], entry["value"]])
+            inserted = connection.execute("INSERT OR IGNORE INTO disavow_rules(id,property_url,kind,value,created_at,updated_at) VALUES (?,?,?,?,?,?)", (rule_id, property_url, entry["kind"], entry["value"], recorded, recorded)).rowcount
+            added += inserted
+            existing += 1 - inserted
+            # An import never overwrites local notes or reactivates a rule the user disabled.
+            connection.execute("INSERT OR IGNORE INTO disavow_provenance VALUES (?,?,?,?,?,?)", (rule_id, source_id, entry["line"], entry["original"], json.dumps(entry["comments"], ensure_ascii=False), recorded))
+        connection.execute("COMMIT")
+    except Exception:
+        connection.execute("ROLLBACK")
+        raise
+    return {"property_url": property_url, "source_id": source_id, "rules_added": added, "existing_rule_lines": existing, "lines": line_count, "mode": "merge", "uploaded": False}
+
+
+def upsert_rule(connection, record, property_url, source):
+    property_url, source = url(property_url, True), source_label(source)
+    if not isinstance(record, dict) or record.keys() - {"kind", "value", "active", "notes"}:
+        raise DisavowError("Rule JSON accepts kind, value, active and notes")
+    kind = record.get("kind")
+    value = rule(kind, record.get("value"))
+    if "active" in record and type(record["active"]) is not bool:
+        raise DisavowError("active must be a JSON boolean")
+    if "notes" in record and not isinstance(record["notes"], str):
+        raise DisavowError("notes must be a string")
+    rule_id = stable_id("drule_", [property_url, kind, value])
+    raw = json.dumps(record, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    digest = hashlib.sha256(raw.encode()).hexdigest()
+    source_id = stable_id("dsrc_", [property_url, source, digest, "manual"])
+    recorded = stamp()
+    connection.execute("BEGIN IMMEDIATE")
+    try:
+        existing = connection.execute("SELECT active,notes FROM disavow_rules WHERE id=?", (rule_id,)).fetchone()
+        active = int(record.get("active", bool(existing[0]) if existing else True))
+        notes = record.get("notes", existing[1] if existing else "")
+        connection.execute("INSERT INTO disavow_rules VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET active=excluded.active,notes=excluded.notes,updated_at=excluded.updated_at", (rule_id, property_url, kind, value, active, notes, recorded, recorded))
+        connection.execute("INSERT OR IGNORE INTO disavow_sources VALUES (?,?,?,?,?,?,?)", (source_id, property_url, source, digest, "manual", raw, recorded))
+        connection.execute("INSERT OR IGNORE INTO disavow_provenance VALUES (?,?,?,?,?,?)", (rule_id, source_id, 0, raw, "[]", recorded))
+        connection.execute("COMMIT")
+    except Exception:
+        connection.execute("ROLLBACK")
+        raise
+    return {"id": rule_id, "property_url": property_url, "kind": kind, "value": value, "active": bool(active), "notes": notes, "source_id": source_id}
+
+
+def list_rules(connection, property_url, active_only=False):
+    property_url = url(property_url, True)
+    result = []
+    for row in connection.execute("SELECT * FROM disavow_rules WHERE property_url=?" + (" AND active=1" if active_only else "") + " ORDER BY kind,value", (property_url,)):
+        item = dict(row)
+        item["active"] = bool(item["active"])
+        item["provenance"] = []
+        for source in connection.execute("SELECT s.id AS source_id,s.source_label,s.source_sha256,s.format,p.line_number,p.line_text,p.comments_json,p.recorded_at FROM disavow_provenance p JOIN disavow_sources s ON s.id=p.source_id WHERE p.rule_id=? ORDER BY p.recorded_at,s.id,p.line_number", (item["id"],)):
+            entry = dict(source)
+            entry["comments"] = json.loads(entry.pop("comments_json"))
+            item["provenance"].append(entry)
+        result.append(item)
+    return result
+
+
+def export_rules(connection, property_url):
+    property_url = url(property_url, True)
+    # No timestamps or private notes: the same active rule set produces identical bytes.
+    lines = ["# AgentLinkOps user-managed disavow rules", "# Property: " + property_url]
+    for kind, value in connection.execute("SELECT kind,value FROM disavow_rules WHERE property_url=? AND active=1 ORDER BY kind,value", (property_url,)):
+        lines.append("domain:" + value if kind == "domain" else value)
+    text = "\n".join(lines) + "\n"
+    if len(lines) > MAX_LINES or len(text.encode("utf-8")) > MAX_BYTES:
+        raise DisavowError("Export exceeds Google's .txt line or byte limits; review the list before exporting")
+    return text, {"property_url": property_url, "active_rules": len(lines) - 2, "format": "txt", "uploaded": False}
+
+
+def snapshot(connection):
+    return {"rules": [dict(row) for row in connection.execute("SELECT * FROM disavow_rules ORDER BY property_url,kind,value")], "sources": [dict(row) for row in connection.execute("SELECT * FROM disavow_sources ORDER BY id")], "provenance": [dict(row) for row in connection.execute("SELECT * FROM disavow_provenance ORDER BY rule_id,source_id,line_number")]}

package/scripts/linktrail.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Compatibility alias (DP-0029): the CRM helper is now agentlinkops.py beside this file."""
+import os
+import runpy
+import sys
+
+sys.stderr.write("linktrail.py: this helper is now agentlinkops.py; the old name keeps working during the pilot compatibility window.\n")
+TARGET = os.path.join(os.path.dirname(os.path.abspath(__file__)), "agentlinkops.py")
+sys.argv[0] = TARGET
+runpy.run_path(TARGET, run_name="__main__")

package/scripts/migrations/001_crm.sql

@@ -0,0 +1,45 @@
+CREATE TABLE crm_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE products (
+  id TEXT PRIMARY KEY, name TEXT NOT NULL, url TEXT NOT NULL,
+  audience TEXT NOT NULL DEFAULT '', description TEXT NOT NULL DEFAULT '',
+  target_pages TEXT NOT NULL DEFAULT '[]', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE campaigns (
+  id TEXT PRIMARY KEY, product_id TEXT REFERENCES products(id), name TEXT NOT NULL,
+  type TEXT NOT NULL, template_version INTEGER NOT NULL DEFAULT 1,
+  status TEXT NOT NULL DEFAULT 'draft', goal TEXT NOT NULL DEFAULT '',
+  target_url TEXT NOT NULL DEFAULT '', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE contacts (
+  id TEXT PRIMARY KEY, publisher_url TEXT NOT NULL, name TEXT NOT NULL DEFAULT '',
+  email TEXT NOT NULL DEFAULT '', contact_url TEXT NOT NULL DEFAULT '',
+  source_url TEXT NOT NULL DEFAULT '', observed_at TEXT NOT NULL DEFAULT '',
+  confidence TEXT NOT NULL DEFAULT 'unverified', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE opportunities (
+  id TEXT PRIMARY KEY, campaign_id TEXT REFERENCES campaigns(id),
+  contact_id TEXT REFERENCES contacts(id), source_url TEXT NOT NULL, target_url TEXT NOT NULL,
+  type TEXT NOT NULL DEFAULT 'custom', status TEXT NOT NULL DEFAULT 'candidate',
+  evidence TEXT NOT NULL DEFAULT '{}', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE activities (
+  id TEXT PRIMARY KEY, opportunity_id TEXT REFERENCES opportunities(id),
+  contact_id TEXT REFERENCES contacts(id), campaign_id TEXT REFERENCES campaigns(id),
+  channel TEXT NOT NULL DEFAULT 'email', kind TEXT NOT NULL,
+  external_message_id TEXT NOT NULL DEFAULT '', occurred_at TEXT NOT NULL,
+  outcome TEXT NOT NULL DEFAULT '', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE placements (
+  id TEXT PRIMARY KEY, opportunity_id TEXT REFERENCES opportunities(id),
+  project_id TEXT, watch_id TEXT UNIQUE, source_url TEXT NOT NULL, target_url TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX campaigns_product ON campaigns(product_id);
+CREATE INDEX opportunities_campaign ON opportunities(campaign_id);
+CREATE INDEX activities_opportunity ON activities(opportunity_id, occurred_at);

package/scripts/migrations/002_cloud_events.sql

@@ -0,0 +1,13 @@
+ALTER TABLE placements ADD COLUMN cloud_state TEXT NOT NULL DEFAULT '{}';
+ALTER TABLE placements ADD COLUMN cloud_observed_at TEXT;
+ALTER TABLE placements ADD COLUMN cloud_event_id TEXT;
+CREATE TABLE cloud_events (
+  id TEXT PRIMARY KEY, cursor TEXT NOT NULL UNIQUE, type TEXT NOT NULL,
+  project_id TEXT, watch_id TEXT, created_at TEXT NOT NULL,
+  payload TEXT NOT NULL, payload_hash TEXT NOT NULL, applied_at TEXT NOT NULL
+);
+CREATE TABLE sync_state (
+  singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+  endpoint TEXT, cursor TEXT, updated_at TEXT NOT NULL
+);
+INSERT INTO sync_state(singleton, updated_at) VALUES(1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));

package/scripts/migrations/003_disavow.sql

@@ -0,0 +1,20 @@
+CREATE TABLE disavow_rules (
+  id TEXT PRIMARY KEY, property_url TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('domain','url')), value TEXT NOT NULL,
+  active INTEGER NOT NULL DEFAULT 1 CHECK(active IN (0,1)),
+  notes TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  UNIQUE(property_url,kind,value)
+);
+CREATE TABLE disavow_sources (
+  id TEXT PRIMARY KEY, property_url TEXT NOT NULL, source_label TEXT NOT NULL,
+  source_sha256 TEXT NOT NULL, format TEXT NOT NULL CHECK(format IN ('txt','manual')),
+  raw_text TEXT NOT NULL, created_at TEXT NOT NULL
+);
+CREATE TABLE disavow_provenance (
+  rule_id TEXT NOT NULL REFERENCES disavow_rules(id),
+  source_id TEXT NOT NULL REFERENCES disavow_sources(id),
+  line_number INTEGER NOT NULL, line_text TEXT NOT NULL,
+  comments_json TEXT NOT NULL DEFAULT '[]', recorded_at TEXT NOT NULL,
+  PRIMARY KEY(rule_id,source_id,line_number)
+);
+CREATE INDEX disavow_property_rules ON disavow_rules(property_url,active,kind,value);

package/scripts/migrations/004_placement_costs.sql

@@ -0,0 +1,2 @@
+ALTER TABLE placements ADD COLUMN cost_amount TEXT;
+ALTER TABLE placements ADD COLUMN cost_currency TEXT;

package/scripts/report.py

@@ -0,0 +1,113 @@
+"""Escaped, self-contained HTML reports from explicitly selected local CRM data."""
+import datetime as dt
+from decimal import Decimal, localcontext
+from html import escape
+import json
+import re
+import urllib.parse
+
+
+def cost(amount, currency):
+    if amount is None and currency is None:
+        return None, None
+    if not isinstance(amount, str) or not re.fullmatch(r"(?:0|[1-9][0-9]{0,17})(?:\.[0-9]{1,6})?", amount):
+        raise ValueError("cost_amount must be a nonnegative decimal string with at most six decimal places")
+    if not isinstance(currency, str) or not re.fullmatch(r"[A-Z]{3}", currency):
+        raise ValueError("cost_currency must be an uppercase three-letter currency label paired with cost_amount")
+    return decimal_text(Decimal(amount)), currency
+
+
+def decimal_text(value):
+    text = format(value, "f")
+    return text.rstrip("0").rstrip(".") if "." in text else text
+
+
+def escaped(value):
+    return escape(str(value) if value is not None else "", quote=True)
+
+
+def link(value):
+    try:
+        parsed = urllib.parse.urlsplit(value)
+        if parsed.scheme not in {"https", "http"} or not parsed.hostname or parsed.username or parsed.password or any(ord(char) < 32 for char in value):
+            raise ValueError()
+    except (ValueError, TypeError):
+        return escaped(value)
+    return '<a href="' + escaped(value) + '" target="_blank" rel="noopener noreferrer">' + escaped(value) + '</a>'
+
+
+def render(connection, title, brand, generated_at, project_id=None, include_notes=False, include_costs=False):
+    for name, value in (("title", title), ("brand", brand)):
+        if not isinstance(value, str) or not value.strip() or len(value) > 300 or any(ord(char) < 32 for char in value):
+            raise ValueError(name + " must be a nonempty label of at most 300 characters")
+    query = "SELECT * FROM placements" + (" WHERE project_id=?" if project_id else "") + " ORDER BY COALESCE(project_id,''),source_url,target_url,id"
+    connection.execute("BEGIN")
+    try:
+        placements = [dict(row) for row in connection.execute(query, (project_id,) if project_id else ())]
+        connection.execute("COMMIT")
+    except Exception:
+        connection.execute("ROLLBACK")
+        raise
+    counts, totals, rows, observed_dates = {}, {}, [], []
+    for placement in placements:
+        cloud = json.loads(placement["cloud_state"])
+        if not isinstance(cloud, dict) or not isinstance(cloud.get("state", "unobserved"), str):
+            raise ValueError("A placement has malformed cloud state; repair the CRM before reporting")
+        state = cloud.get("state", "unobserved")
+        counts[state] = counts.get(state, 0) + 1
+        observed_at = placement["cloud_observed_at"]
+        if observed_at:
+            observed_dates.append(observed_at)
+        columns = [link(placement["source_url"]), link(placement["target_url"]), escaped(str(state).replace("_", " ")), escaped(observed_at or "No observation")]
+        if include_notes:
+            columns.append(escaped(placement["notes"]))
+        if include_costs:
+            amount, currency = cost(placement["cost_amount"], placement["cost_currency"])
+            if amount is not None:
+                with localcontext() as context:
+                    context.prec = 50
+                    totals[currency] = totals.get(currency, Decimal(0)) + Decimal(amount)
+                columns.append(escaped(currency + " " + amount))
+            else:
+                columns.append("Not recorded")
+        rows.append("<tr>" + "".join("<td>" + column + "</td>" for column in columns) + "</tr>")
+    headings = ["Source page", "Destination", "Observed state", "Observation time (UTC offset shown)"]
+    if include_notes:
+        headings.append("Local notes (included by request)")
+    if include_costs:
+        headings.append("Recorded local cost")
+    if not rows:
+        rows.append('<tr><td colspan="' + str(len(headings)) + '">No placements match this report selection.</td></tr>')
+    privacy = "Includes source and destination URLs, observed states and observation times."
+    privacy += " Local notes are included by request." if include_notes else " Local notes are excluded."
+    privacy += " Recorded costs are included by request." if include_costs else " Recorded costs are excluded."
+    scope = "Selected project" if project_id else "All local placements"
+    coverage = "No cloud observations are available for these placements."
+    if observed_dates:
+        chronological = sorted(observed_dates, key=lambda value: dt.datetime.fromisoformat(value.replace("Z", "+00:00")))
+        coverage = "Observed timestamps range from " + chronological[0] + " to " + chronological[-1] + "."
+    totals_html = ""
+    if include_costs:
+        totals_html = '<section class="costs"><h2>Recorded costs</h2>'
+        if totals:
+            totals_html += '<ul>' + ''.join('<li>' + escaped(currency + " " + decimal_text(amount)) + '</li>' for currency, amount in sorted(totals.items())) + '</ul>'
+        else:
+            totals_html += '<p>No costs are recorded for the selected placements.</p>'
+        totals_html += '<p>Totals combine recorded amounts within each currency. No currency conversion, market valuation or tax calculation is applied.</p></section>'
+    document = '''<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="referrer" content="no-referrer"><meta name="robots" content="noindex,nofollow">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+<title>''' + escaped(title) + '''</title>
+<style>
+*{box-sizing:border-box}body{margin:0;color:#192b36;background:#f7f9fb;font:14px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}main{max-width:1400px;margin:auto;padding:48px 36px}.brand{font:12px/1.5 ui-monospace,SFMono-Regular,Consolas,monospace;letter-spacing:.06em;text-transform:uppercase;color:#c4472d}h1,h2{font-weight:600;line-height:1.12;letter-spacing:-.04em}h1{font-size:44px;margin:18px 0 20px}h2{font-size:27px}.meta,.coverage,.disclosure{color:#566570;font-size:13px;max-width:1000px}.coverage{border-left:2px solid #c4472d;padding-left:16px;margin-top:24px}.metrics{display:flex;flex-wrap:wrap;margin:32px 0;border-block:1px solid #d8dfe5}.metric{flex:1;min-width:160px;padding:20px 24px 20px 0}.metric+.metric{border-left:1px solid #d8dfe5;padding-left:24px}.metric strong{display:block;font-size:32px;font-weight:550;letter-spacing:-.03em}.metric span{font-size:12px;color:#566570}.table-region{overflow-x:auto;max-width:100%}table{border-collapse:collapse;width:100%;min-width:760px;background:#fff;font-size:13px;table-layout:fixed}caption{text-align:left;font-size:19px;font-weight:600;letter-spacing:-.025em;padding:0 0 16px}th,td{text-align:left;border-bottom:1px solid #d8dfe5;padding:15px;vertical-align:top;overflow-wrap:anywhere;white-space:pre-wrap}th{background:#eef2f5;color:#566570;font:11px/1.6 ui-monospace,SFMono-Regular,Consolas,monospace}a{color:#192b36;text-underline-offset:3px}a:focus-visible{outline:3px solid #c4472d;outline-offset:3px}footer{border-top:1px solid #d8dfe5;margin-top:36px;padding-top:20px;font-size:12px;color:#566570}.costs{margin-top:32px}.costs p{font-size:13px;color:#566570}ul{padding-left:20px}@media(max-width:700px){main{padding:32px 20px}h1{font-size:34px}.metric{min-width:50%;padding:16px 12px}.metric+.metric{padding-left:12px}.metric:nth-child(odd){border-left:0}.metric:nth-child(n+3){border-top:1px solid #d8dfe5}}@media print{body{background:white}main{padding:0;max-width:none}.metric,th{background:#eef2f5}.table-region{overflow:visible}table{min-width:0;font-size:10px}th,td{padding:9px}th{font-size:9px}tr{break-inside:avoid}thead{display:table-header-group}a{color:#192b36;text-decoration:none}@page{size:landscape;margin:12mm}}
+</style></head><body><main>
+<div class="brand">''' + escaped(brand) + '''</div><h1>''' + escaped(title) + '''</h1>
+<p class="meta">Generated ''' + escaped(generated_at) + " · " + escaped(scope) + ''' · Local CRM snapshot</p>
+<p class="coverage">''' + escaped(coverage) + ''' This report does not perform new checks. Unknown or unobserved results do not establish link loss.</p>
+<div class="metrics"><div class="metric"><strong>''' + str(len(placements)) + '''</strong><span>Selected placements</span></div><div class="metric"><strong>''' + str(counts.get("present", 0)) + '''</strong><span>Observed present</span></div><div class="metric"><strong>''' + str(counts.get("confirmed_missing", 0)) + '''</strong><span>Confirmed missing</span></div><div class="metric"><strong>''' + str(counts.get("unknown", 0) + counts.get("unobserved", 0)) + '''</strong><span>Unknown or unobserved</span></div></div>
+<div class="table-region" role="region" aria-label="Selected placement observations" tabindex="0"><table><caption>Selected placement observations</caption><thead><tr>''' + ''.join('<th scope="col">' + escaped(heading) + '</th>' for heading in headings) + '''</tr></thead><tbody>''' + ''.join(rows) + '''</tbody></table></div>
+''' + totals_html + '''<footer><p>''' + escaped(privacy) + ''' Contacts, messages, API credentials, disavow rules and raw cloud event payloads are not included.</p><p>Created with the local AgentLinkOps toolkit. This is an HTML report; browser print options are separate from report generation.</p></footer>
+</main></body></html>
+'''
+    return document, {"format": "html", "placements": len(placements), "project_id": project_id, "generated_at": generated_at, "included_local_notes": include_notes, "included_local_costs": include_costs}

package/shared/agent-clients.js

@@ -0,0 +1,49 @@
+// DP-0036-T06: the client view table. Which MCP view each agent client should connect to and
+// where it keeps skills and MCP configuration, from the client behavior recorded in the
+// agent-surface research (docs/research/agent-surface-v2-2026-09-15/report.md §1 and §6).
+// Read by `agentlinkops agent setup` (DP-0036-T09), GET /v1/catalog.json and the generators.
+// Pure data; no imports. Paths use `~` for the home directory and are relative to the
+// project root otherwise.
+export const AGENT_CLIENTS = [
+  {
+    id: 'claude-code', name: 'Claude Code',
+    detect: ['~/.claude', '~/.claude.json'],
+    skills: { project: '.claude/skills', user: '~/.claude/skills' },
+    mcp: { scope: 'project', file: '.mcp.json', format: 'mcpServers-json' },
+    view: '/mcp/all', deferral: true,
+    reason: 'Claude Code defers MCP tool definitions above about 10K tokens behind its own tool search, so the flat view keeps every annotation, parallel read dispatch and direct calls with no meta layer.',
+  },
+  {
+    id: 'codex', name: 'Codex',
+    detect: ['~/.codex'],
+    skills: { project: '.agents/skills', user: '~/.agents/skills' },
+    mcp: { scope: 'user', file: '~/.codex/config.toml', format: 'toml-mcp_servers' },
+    view: '/mcp', deferral: false,
+    reason: 'Codex loads MCP tools flat (its catalog limit is 2,048 definitions, not a context budget) and budgets the skill list at 2% of context, so the bounded default view keeps the connection small.',
+  },
+  {
+    id: 'cursor', name: 'Cursor',
+    detect: ['~/.cursor'],
+    skills: { project: '.agents/skills', user: '~/.agents/skills' },
+    mcp: { scope: 'project', file: '.cursor/mcp.json', format: 'mcpServers-json' },
+    view: '/mcp', deferral: false,
+    reason: 'Cursor caps active tools at 40 across every connected server and drops the rest silently; the default view uses nine definitions.',
+  },
+  {
+    id: 'gemini-cli', name: 'Gemini CLI',
+    detect: ['~/.gemini'],
+    skills: { project: '.agents/skills', user: '~/.agents/skills' },
+    mcp: { scope: 'project', file: '.gemini/settings.json', format: 'mcpServers-httpUrl' },
+    view: '/mcp', deferral: false,
+    reason: 'Gemini CLI loads MCP tools flat and activates skills with a consent prompt; the default view keeps the listing small and the skills name the commands.',
+  },
+  {
+    id: 'hermes', name: 'Hermes Agent',
+    detect: ['~/.hermes'],
+    skills: { user: '~/.hermes/skills' },
+    mcp: { scope: 'user', file: '~/.hermes/config.yaml', format: 'yaml-mcp_servers' },
+    view: '/mcp/all', deferral: true,
+    reason: 'Hermes replaces deferred MCP tools with its own tool_search, tool_describe and tool_call bridge over a grouped manifest, so the flat view is the right input.',
+  },
+];
+export const clientById = id => AGENT_CLIENTS.find(client => client.id === id) ?? null;

package/shared/observation-event.js

@@ -0,0 +1,43 @@
+export function eventSnapshot(state) {
+  const latest = state.latestAttempt || {};
+  const occurrences = (latest.occurrences || []).slice(0, 20).map(item => ({
+    targetUrl: String(item.targetUrl || '').slice(0, 4096),
+    anchor: String(item.anchor || '').slice(0, 256),
+    rel: (item.rel || []).slice(0, 20),
+  }));
+  return {
+    schema_version: 1, target_scope: state.target_scope,
+    check_state: latest.state ?? 'unknown', link_signature: latest.linkSignature ?? null,
+    checker_version: latest.evidence?.checkerVersion ?? null,
+    state: state.state || 'unknown', uncertain: state.uncertain ?? true,
+    watch_id: state.watch_id, source_url: state.source_url, target_url: state.target_url,
+    checked_at: state.checked_at, reason: latest.reason || null,
+    http_status: latest.httpStatus ?? null, expectations: latest.expectations || null,
+    occurrences, occurrence_count: latest.occurrences?.length || 0,
+    occurrences_truncated: (latest.occurrences?.length || 0) > occurrences.length,
+    next_check_at: state.nextCheckAt || null,
+  };
+}
+
+/** Accept v1 flat events and pre-version snapshots. Reject unknown versions explicitly. */
+export function observationFromSnapshot(snapshot) {
+  if (snapshot.schema_version !== undefined && snapshot.schema_version !== 1) throw new Error('Unsupported observation event version.');
+  if (typeof snapshot.checked_at !== 'string' || !Number.isFinite(Date.parse(snapshot.checked_at))) throw new Error('Invalid observation event timestamp.');
+  const latest = snapshot.latestAttempt ?? {};
+  const occurrences = snapshot.occurrences ?? latest.occurrences ?? [];
+  if (!Array.isArray(occurrences)) throw new Error('Invalid observation event occurrences.');
+  return {
+    sourceUrl: snapshot.source_url ?? latest.sourceUrl,
+    targetUrl: snapshot.target_url ?? latest.targetUrl,
+    targetScope: snapshot.target_scope ?? latest.targetScope,
+    state: snapshot.uncertain !== false ? 'unknown' : snapshot.state === 'confirmed_missing' ? 'absent' : snapshot.state === 'present' ? 'present' : 'unknown',
+    watchState: snapshot.state,
+    checkState: snapshot.check_state ?? latest.state ?? null,
+    reason: snapshot.reason ?? latest.reason ?? null,
+    checkedAt: snapshot.checked_at, occurrences,
+    occurrencesTruncated: snapshot.occurrences_truncated ?? false,
+    occurrenceCount: snapshot.occurrence_count ?? occurrences.length,
+    linkSignature: snapshot.link_signature ?? latest.linkSignature ?? null,
+    evidence: {complete: snapshot.uncertain === false, checkerVersion: snapshot.checker_version ?? latest.evidence?.checkerVersion ?? null},
+  };
+}

package/shared/response-contract.js

@@ -0,0 +1,59 @@
+import {searchConnectionsResponse,searchRowsResponse,searchSyncResponse,searchPropertiesResponse,searchStartResponse,searchConnection,searchImportResponse} from './search-connection-contract.js';
+import {z} from 'zod';
+export const objectResponse=z.looseObject({});
+export const pageResponse=z.looseObject({items:z.array(objectResponse),next_cursor:z.string().nullable().optional()});
+export const watchResponse=z.looseObject({id:z.string(),source_url:z.string(),target_url:z.string(),state:z.string(),observation_state:objectResponse});
+export const targetResponse=z.looseObject({id:z.string(),url:z.string(),state:z.string(),observation_state:objectResponse});
+export const historyResponse=z.looseObject({items:z.array(z.looseObject({id:z.string(),state:z.string(),checked_at:z.string(),result:objectResponse})),next_cursor:z.string().nullable().optional()});
+export const jobResponse=z.looseObject({id:z.string(),state:z.enum(['queued','running','succeeded','failed','cancelled'])});
+export const observationEvent=z.looseObject({id:z.string(),data:objectResponse});
+export const eventFeedResponse=z.looseObject({events:z.array(observationEvent),next_cursor:z.string(),has_more:z.boolean()});
+export const usageResponse=z.looseObject({
+  workspace_id:z.string(),period:z.string().regex(/^\d{4}-\d{2}$/),plan:z.string(),
+  check_reservations:z.looseObject({reserved:z.number().nonnegative(),consumed:z.number().nonnegative(),released:z.number().nonnegative()}),
+  units:z.record(z.string(),z.looseObject({used:z.number().nonnegative()})),
+  at_allowance:z.looseObject({note:z.string()}),checkout:z.looseObject({available:z.boolean(),reason:z.string().nullable().optional()}),
+});
+export const candidateVerificationBatchResponse=z.looseObject({
+  schema_version:z.literal(1),id:z.string(),workspace_id:z.string(),project_id:z.string(),run_id:z.string(),
+  state:z.enum(['pending','completed','partial','failed']),
+  counts:z.object(Object.fromEntries(['rejected','queued','running','succeeded','failed','cancelled'].map(state=>[state,z.number().int().nonnegative()]))),
+  items:z.array(z.looseObject({
+    ordinal:z.number().int().nonnegative(),candidate_id:z.string(),local_reference:z.string().nullable(),
+    job_id:z.string().nullable(),watch_id:z.string().nullable(),
+    state:z.enum(['rejected','queued','running','succeeded','failed','cancelled']),error_code:z.string().nullable(),
+    observation:z.looseObject({id:z.string(),state:z.string(),reason:z.string().nullable(),checked_at:z.string()}).nullable(),
+    usage:z.looseObject({unit:z.literal('source_check'),state:z.string()}).nullable(),
+  })).min(1).max(50),
+  reservation:z.looseObject({units:z.number().int().nonnegative(),outstanding:z.number().int().nonnegative(),consumed:z.number().int().nonnegative(),released:z.number().int().nonnegative(),period:z.string()}).nullable(),
+  replayed:z.boolean().optional(),
+});
+export const candidateMonitoringResponse=z.looseObject({
+  watch:z.looseObject({id:z.string(),source_url:z.string(),target_url:z.string(),status:z.enum(['active','paused']),observation_state:objectResponse}),verification_job_id:z.string(),candidate_id:z.string(),run_id:z.string(),
+  local_reference:z.string().nullable(),replayed:z.boolean(),recurring_monitoring_created:z.literal(true),
+});
+/** Network boundary shared by the console and command adapters. Unknown fields survive evolution. */
+export function restResponseContract(path,method='GET') {
+  const pathname=path.split('?')[0];
+  if(method==='POST' && /^\/v1\/discovery\/runs\/[^/]+\/verification-batches$/.test(pathname))return candidateVerificationBatchResponse;
+  if(method==='GET' && /^\/v1\/discovery\/verification-batches\/[^/]+$/.test(pathname))return candidateVerificationBatchResponse;
+  if(method==='POST' && /^\/v1\/discovery\/verifications\/[^/]+\/monitor$/.test(pathname))return candidateMonitoringResponse;
+  if(pathname==='/v1/search-connections'&&method==='GET')return searchConnectionsResponse;
+  if(pathname==='/v1/search-connections/start'&&method==='POST')return searchStartResponse;
+  if(/^\/v1\/search-connections\/[^/]+\/rows$/.test(pathname)&&method==='GET')return searchRowsResponse;
+  if(/^\/v1\/search-connections\/[^/]+\/properties$/.test(pathname)&&method==='GET')return searchPropertiesResponse;
+  if(/^\/v1\/search-connections\/[^/]+\/sync$/.test(pathname)&&method==='POST')return searchSyncResponse;
+  if(/^\/v1\/search-connections\/[^/]+\/property$/.test(pathname)&&method==='PUT')return z.object({connection:searchConnection});
+  if(/^\/v1\/search-connections\/[^/]+\/import$/.test(pathname)&&method==='POST')return searchImportResponse;
+  if(/^\/v1\/search-connections\/[^/]+\/disconnect$/.test(pathname)&&method==='POST')return z.object({disconnected:z.literal(true),retainedRows:z.literal(true)});
+  if(/^\/v1\/search-connections\/[^/]+$/.test(pathname)&&method==='DELETE')return z.object({forgotten:z.literal(true)});
+  if(method!=='GET')return objectResponse;
+  if(/^\/v1\/(?:watches|targets)\/[^/]+\/history$/.test(pathname))return historyResponse;
+  if(/^\/v1\/watches\/[^/]+$/.test(pathname))return watchResponse;
+  if(/^\/v1\/targets\/[^/]+$/.test(pathname))return targetResponse;
+  if(['/v1/watches','/v1/targets','/v1/projects','/v1/exports/watches'].includes(pathname))return pageResponse;
+  if(pathname==='/v1/usage')return usageResponse;
+  if(['/v1/events','/v1/target-events'].includes(pathname))return eventFeedResponse;
+  if(/^\/v1\/(?:jobs|target-jobs)\/[^/]+$/.test(pathname))return jobResponse;
+  return objectResponse;
+}

package/shared/search-connection-contract.js

@@ -0,0 +1,18 @@
+import {z} from 'zod';
+const text=z.string(),nullable=text.nullable();
+export const searchConnection=z.looseObject({
+ id:text,project_id:text,provider:z.enum(['google','bing']),status:text,property:nullable,
+ last_sync_at:nullable,next_sync_at:nullable,last_error:nullable,coverage:z.record(text,z.unknown()).nullable(),
+ snapshot_id:nullable,capability:z.enum(['search_performance','backlinks']),created_at:text,updated_at:text,
+});
+export const searchConnectionsResponse=z.looseObject({connections:z.array(searchConnection),providers:z.array(z.looseObject({provider:z.enum(['google','bing']),configured:z.boolean(),capability:z.enum(['search_performance','backlinks'])}))});
+const rowMeta={rowId:text,fetched_at:text};
+export const searchProviderRow=z.discriminatedUnion('kind',[
+ z.looseObject({...rowMeta,kind:z.literal('search_performance'),page:text,query:text,clicks:z.number().nonnegative(),impressions:z.number().nonnegative(),ctr:z.number().nonnegative(),position:z.number().nonnegative(),startDate:text,endDate:text}),
+ z.looseObject({...rowMeta,kind:z.literal('backlinks'),source_url:text,target_url:text,anchor:nullable,supplier:z.literal('bing_webmaster_tools'),verification_status:z.literal('unverified')}),
+]);
+export const searchRowsResponse=z.looseObject({connection:searchConnection,rows:z.array(searchProviderRow),nextCursor:nullable});
+export const searchSyncResponse=z.looseObject({connection:searchConnection,rowCount:z.number().int().nonnegative()});
+export const searchPropertiesResponse=z.looseObject({properties:z.array(z.looseObject({property:text,permission:text}))});
+export const searchStartResponse=z.looseObject({authorizationUrl:z.url(),expiresAt:text});
+export const searchImportResponse=z.looseObject({id:text,status:text,replayed:z.boolean().optional(),usage:z.looseObject({accepted_candidates:z.number().int().nonnegative()}),rejected:z.array(z.looseObject({row:z.number(),reason:text})),duplicates:z.array(z.looseObject({row:z.number(),first_seen_on_row:z.number()})),rejected_total:z.number().int().nonnegative(),duplicates_total:z.number().int().nonnegative()});

package/skills/agentlinkops-assets/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: agentlinkops-assets
+description: Improve a code-built site's resource, guide or research page for a specific backlink campaign, with sourced claims and useful internal links. Use when a campaign requires a better linkable asset; avoid unrelated site-wide rewrites.
+allowed-tools: Read Grep Glob Edit Bash(npm run *) Bash(agentlinkops call *)
+---
+
+Read the repository's applicable instructions and the campaign's publisher/audience evidence before editing. Define what the target reader needs and what the current page lacks. Prefer an asset with independent utility: a sourced reference, comparison, original dataset, calculator, template or practical guide that fits the product.
+
+Preserve the project's rendering and routing conventions. Inspect nearby pages before changing a Next.js or other code-built site. Keep factual claims tied to sources and dates, distinguish original analysis from reported facts, and preserve qualifications that affect accuracy. Do not invent expertise, statistics, citations or endorsements.
+
+Write plainly and specifically. Remove repetition and generic filler without deleting necessary evidence. Add internal links only where the destination answers the reader's next relevant question; inspect the actual routes before linking. Check for an existing competing page before creating a new URL.
+
+Use the site's existing validation commands appropriate to the change. Record the final target URL, reader benefit and evidence in the AgentLinkOps product/campaign record using [the CRM contract](../../references/cli.md). A completed local edit does not establish that the page is deployed or that a publisher accepted it.

package/skills/agentlinkops-assets/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: AgentLinkOps Assets
+  short_description: Improve a code-built site's resource, guide or research page for a specific backlink campaign, with sourced claims and u
+policy:
+  allow_implicit_invocation: true