heylead 0.10.332__tar.gz → 0.10.333__tar.gz

{heylead-0.10.332 → heylead-0.10.333}/AGENTS.md

@@ -33,7 +33,7 @@ HeyLead is an autonomous LinkedIn SDR (Sales Development Representative) that ru
 
 ## Agent ops
 
-When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes.
+When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes. If they ask what the agents left for the next tick, or who went dark, call `inspect(action='commons')`.
 
 A hold: `prospect(action="conversation", outreach_id="...")` then `send_message(action="reply", outreach_id="...")`. Operator replies skip the reply agent.
 

{heylead-0.10.332 → heylead-0.10.333}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: heylead
-Version: 0.10.332
+Version: 0.10.333
 Summary: MCP-native autonomous LinkedIn SDR. Your AI sales rep, one command to fill your pipeline.
 Project-URL: Homepage, https://github.com/D4umak/heylead
 Project-URL: Repository, https://github.com/D4umak/heylead

{heylead-0.10.332 → heylead-0.10.333}/SKILL.md

@@ -77,7 +77,7 @@ After adding the MCP server, tell your OpenClaw agent:
 
 ## Agent ops
 
-When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes.
+When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes. If they ask what the agents left for the next tick, or who went dark, call `inspect(action='commons')`.
 
 A hold: `prospect(action="conversation", outreach_id="...")` then `send_message(action="reply", outreach_id="...")`. Operator replies skip the reply agent.
 

{heylead-0.10.332 → heylead-0.10.333}/clawhub/SKILL.md

@@ -80,7 +80,7 @@ After adding the MCP server, tell your OpenClaw agent:
 
 ## Agent ops
 
-When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes.
+When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes. If they ask what the agents left for the next tick, or who went dark, call `inspect(action='commons')`.
 
 A hold: `prospect(action="conversation", outreach_id="...")` then `send_message(action="reply", outreach_id="...")`. Operator replies skip the reply agent.
 

{heylead-0.10.332 → heylead-0.10.333}/clawhub.json

@@ -17,7 +17,7 @@
     "icp",
     "campaign-management"
   ],
-  "version": "0.10.332",
+  "version": "0.10.333",
   "license": "MIT",
   "author": {
     "name": "HeyLead",

heylead-0.10.333/docs/superpowers/plans/2026-09-09-agent-commons-heartbeat.md

@@ -0,0 +1,53 @@
+# Agent Commons + Heartbeat Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Official inspectable scratch so later ticks can read earlier notes, and a host can see when a sibling agent went dark.
+
+**Architecture:** New `agent_commons` table (beat upsert per agent+campaign; append-only notes with 24h expiry). Sidecar `record_agent_beat` after each of the four `run_agent_loop` returns. Kernel passes `reason`/`note` into tools that accept them. `inspect(action='commons')` is read-only. Client SQLite only.
+
+**Tech Stack:** Python 3.12, SQLite, existing `run_agent_loop` / `inspect` / pytest (`PYTHONPATH=src python3.12 -m pytest`).
+
+**Spec:** `docs/superpowers/specs/2026-09-09-agent-commons-heartbeat-design.md`
+
+---
+
+## Files
+
+- Create: `src/heylead/services/agent_commons.py`
+- Create: `tests/test_agent_commons.py`
+- Modify: `src/heylead/db/schema.py` (`SCHEMA_VERSION` 9→10, `_SCHEMA_SQL`, `_apply_migrations`)
+- Modify: `tests/test_migration_backup_gating.py` (`EXPECTED_MIGRATION_STATEMENTS`)
+- Modify: `src/heylead/ai/agent_loop.py` (pass kwargs into tools)
+- Modify: `src/heylead/ai/schemas.py` (four step enums + `note`)
+- Modify: `src/heylead/services/reply_agent.py`, `strategist_replan.py`, `hot_lead_closer.py`, `icp_research.py`
+- Modify: `src/heylead/tools/inspect.py`, `src/heylead/server.py`
+- Modify: `tests/test_agent_loop.py`, `tests/test_inspect.py`, `tests/test_host_ops_playbook.py`
+- Modify: `AGENTS.md`, `SKILL.md`, `clawhub/SKILL.md`
+
+Do not commit unless asked. Do not bump the package version here.
+
+### Task 1: Failing tests
+
+- [ ] `tests/test_agent_commons.py` — beat upsert, off skips beat, one note per run, expiry, 500-char refuse, inspect commons/agents, inspect does not write
+- [ ] Extend `test_agent_loop.py` — tool receives `reason`/`note`
+- [ ] Extend inspect unknown-action + no-write lists with `commons`
+- [ ] Playbook requires `inspect(action='commons')`
+
+### Task 2: Schema + service + kernel
+
+- [ ] Table + SCHEMA_VERSION 10
+- [ ] `agent_commons` service
+- [ ] Kernel `_invoke_tool`
+
+### Task 3: Hook four loops + inspect + playbook
+
+- [ ] Tools + `record_agent_beat` after each loop
+- [ ] `inspect(action='commons')` and agents one-liner
+- [ ] Playbook / MCP instructions / inspect docstring
+
+### Task 4: Verify
+
+```
+PYTHONPATH=src python3.12 -m pytest tests/test_agent_commons.py tests/test_agent_loop.py tests/test_inspect.py tests/test_host_ops_playbook.py tests/test_migration_backup_gating.py tests/test_reply_agent.py tests/test_icp_research.py tests/test_strategist_replan.py tests/test_hot_lead_closer.py -q
+```

heylead-0.10.333/docs/superpowers/specs/2026-09-09-agent-commons-heartbeat-design.md

@@ -0,0 +1,84 @@
+# Agent commons + heartbeat
+
+Date: 2026-09-09
+
+The four in-process agents write `actions_log`. They barely read each other, and a host cannot see whether a sibling went dark. This spec adds an official, inspectable scratch — not a covert channel.
+
+Inspiration is the May–June 2026 OpenAI wiki swarm (cross-run notes, heartbeat, adapt when the world changes). We copy that *shape*. We do not copy covert GET-writes, fighting the operator, impersonation, or sandbox escape.
+
+First slice of a larger program (coordinator and `heylead-api` port come later). Client SQLite only.
+
+## Goals
+
+- Table `agent_commons` with two kinds of row: `beat` and `note`.
+- Python sidecar upserts a beat after every `run_agent_loop` return (observe or act).
+- Kernel tools `read_commons` and `write_commons` on all four registries. One note per run.
+- `inspect(action='commons')` lists beats, ages, live notes, and stale agents.
+- `inspect(action='agents')` gains one commons/liveness line.
+- Playbook: if they ask what the agents left for the next tick, or who went dark, call `inspect(action='commons')`.
+- Notes expire in 24h. Body ≤ 500 characters.
+- Stale = beat older than 6 hours and that agent is not `off`.
+
+## Non-goals
+
+- Coordinator agent.
+- Porting loops to `heylead-api`.
+- Syncing commons to the backend.
+- Operator-delete tool (v1: turn the agent `off`, or wait 24h). `inspect` stays read-only.
+- Recreating a forgotten note under a new key (`ZZZ…`).
+- LinkedIn / email / calendar writes from commons.
+- Changing default observe behavior or act flags.
+- New MCP tool.
+
+## Data
+
+`agent` is `reply` | `strategist` | `closer` | `icp_research`.
+
+| kind | uniqueness | fields |
+|---|---|---|
+| `beat` | one current row per `(campaign_id, agent)` | `decision`, `reason` (≤240 chars), `timestamp`. ICP research uses `campaign_id=""`. |
+| `note` | append | `body`, optional `outreach_id`, `created_at`, `expires_at` (= created + 24h) |
+
+`off` does not run the loop, so the beat is not refreshed and ages. That is the liveness signal.
+
+## Kernel
+
+Today tools are invoked as `tool()` with no arguments. `write_commons` needs the note text.
+
+`run_agent_loop` passes `reason` and extras into a tool when the callable accepts them (`reason=`, `note=` from extras, otherwise ignored). Each vertical step schema adds `read_commons` and `write_commons` to its `action` enum, plus a `note` string (empty = use `reason`).
+
+`write_commons` refuses a second call in the same run. Empty / overlong body is refused. It writes only to `agent_commons`.
+
+`read_commons` returns current beats plus unexpired notes, scoped to the campaign (and outreach when the loop has one).
+
+Sidecar `record_agent_beat` runs after the loop returns, including `none` / exhausted. It does not run when the vertical is `off` (loop skipped).
+
+## Inspect
+
+`inspect(action='commons')` — never writes, no LLM, no LinkedIn.
+
+- Last beat per agent: age, last decision, short reason.
+- Live notes (unexpired).
+- Stale line when a beat is older than 6 hours and mode is not `off`.
+
+`inspect(action='agents')` adds one line: live note count and the newest beat age (e.g. `commons: 2 live notes, reply beat 12m ago`).
+
+Unknown action still lists the valid set (now includes `commons`).
+
+## Failure
+
+- Query failure → short error; nothing written.
+- `write_commons` refused → tool result string, loop continues.
+- Missing table on old DBs → create via existing schema init (`CREATE TABLE IF NOT EXISTS`).
+
+## Tests
+
+- Beat upserted after a reply (and strategist / closer / ICP) loop.
+- `off` does not refresh the beat.
+- `write_commons` first call persists; second call in the same run is refused.
+- Expired notes are hidden from `read_commons` and `inspect(action='commons')`.
+- Body over 500 characters is refused.
+- `inspect(action='commons')` does not write.
+- `inspect(action='agents')` mentions commons / beat.
+- MCP `inspect` signature / dispatch includes `commons`.
+- Playbook names `inspect(action='commons')`.

{heylead-0.10.332 → heylead-0.10.333}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "heylead"
-version = "0.10.332"
+version = "0.10.333"
 description = "MCP-native autonomous LinkedIn SDR. Your AI sales rep, one command to fill your pipeline."
 readme = "README.md"
 license = "MIT"

{heylead-0.10.332 → heylead-0.10.333}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.D4umak/heylead",
   "title": "HeyLead \u2014 Autonomous LinkedIn SDR",
   "description": "Autonomous LinkedIn SDR \u2014 voice-matched outreach, ICP generation, and campaign management.",
-  "version": "0.10.332",
+  "version": "0.10.333",
   "websiteUrl": "https://github.com/D4umak/heylead",
   "repository": {
     "url": "https://github.com/D4umak/heylead",
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "heylead",
-      "version": "0.10.332",
+      "version": "0.10.333",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{heylead-0.10.332 → heylead-0.10.333}/src/heylead/ai/agent_loop.py

@@ -100,7 +100,7 @@ async def run_agent_loop(
             transcript += f"\n\nTOOL {action}: unknown tool"
             continue
         try:
-            result = tool()
+            result = _invoke_tool(tool, reason=reason, extras=extras)
             if inspect.isawaitable(result):
                 result = await result
             text = str(result)
@@ -137,3 +137,18 @@ def _parse_step(raw: str, valid_decisions: frozenset[str]) -> dict[str, Any]:
         "done": done,
         "extras": extras,
     }
+
+
+def _invoke_tool(tool: ToolFn, *, reason: str, extras: dict[str, str]) -> str | Awaitable[str]:
+    kwargs: dict[str, str] = {}
+    try:
+        sig = inspect.signature(tool)
+    except (TypeError, ValueError):
+        return tool()
+    params = sig.parameters
+    accepts_var = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
+    if accepts_var or "reason" in params:
+        kwargs["reason"] = reason
+    if accepts_var or "note" in params:
+        kwargs["note"] = extras.get("note") or ""
+    return tool(**kwargs) if kwargs else tool()

{heylead-0.10.332 → heylead-0.10.333}/src/heylead/ai/schemas.py

@@ -67,7 +67,10 @@ SENTIMENT = _obj({
 AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_thread", "read_timeline", "read_icp", "read_fit", "decide"],
+        "enum": [
+            "read_thread", "read_timeline", "read_icp", "read_fit",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -75,13 +78,17 @@ AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
 })
 
 # ICP research vertical — extra strings are a flat filter patch (empty = no change).
 ICP_AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_icp", "preview_search", "read_filters", "decide"],
+        "enum": [
+            "read_icp", "preview_search", "read_filters",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -89,6 +96,7 @@ ICP_AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
     "titles_include": _STR,
     "titles_exclude": _STR,
     "locations_include": _STR,
@@ -101,7 +109,10 @@ ICP_AGENT_STEP = _obj({
 REPLAN_AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_plan", "read_signals", "read_thread", "read_status", "decide"],
+        "enum": [
+            "read_plan", "read_signals", "read_thread", "read_status",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -109,6 +120,7 @@ REPLAN_AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
     "remaining_json": _STR,
 })
 
@@ -116,7 +128,10 @@ REPLAN_AGENT_STEP = _obj({
 CLOSER_AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_thread", "read_contact", "read_calendar_target", "decide"],
+        "enum": [
+            "read_thread", "read_contact", "read_calendar_target",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -124,6 +139,7 @@ CLOSER_AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
     "attendee_email": _STR,
     "start_iso": _STR,
     "duration_minutes": _STR,

{heylead-0.10.332 → heylead-0.10.333}/src/heylead/db/schema.py

@@ -35,7 +35,7 @@ _DB_RETRY_BACKOFF = 0.1  # seconds, doubles each attempt
 #    dedup read it as "already in a campaign" and never let the person back in.
 # 7: outreaches.chat_id (and headline A/B columns) — a v6 stamp skipped the
 #    ALTER, so planning died with `no such column: o.chat_id`.
-SCHEMA_VERSION = 9  # 9: contacts.timezone (per-prospect planning windows); 8: versioned outreach sync
+SCHEMA_VERSION = 10  # 10: agent_commons (beats + notes); 9: contacts.timezone
 
 # Singleton connection — avoids opening multiple connections per process
 # which causes "database is locked" errors with WAL mode.
@@ -605,6 +605,24 @@ CREATE TABLE IF NOT EXISTS company_posts_tracked (
 );
 CREATE INDEX IF NOT EXISTS idx_cpt_watchlist ON company_posts_tracked(watchlist_id);
 CREATE INDEX IF NOT EXISTS idx_cpt_post_id ON company_posts_tracked(post_id);
+
+-- In-process agent scratch (heartbeat + short notes for the next tick)
+CREATE TABLE IF NOT EXISTS agent_commons (
+    id           TEXT PRIMARY KEY,
+    kind         TEXT NOT NULL,
+    agent        TEXT NOT NULL,
+    campaign_id  TEXT NOT NULL DEFAULT '',
+    outreach_id  TEXT,
+    body         TEXT,
+    decision     TEXT,
+    reason       TEXT,
+    created_at   INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+    expires_at   INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_agent_commons_beat
+    ON agent_commons(campaign_id, agent, kind);
+CREATE INDEX IF NOT EXISTS idx_agent_commons_notes
+    ON agent_commons(campaign_id, kind, expires_at);
 """
 
 
@@ -2278,6 +2296,31 @@ def _apply_migrations(conn: sqlite3.Connection) -> None:
             _reraise_if_migration_interrupted(e)
         logger.warning("Migration: outreach dedup failed: %s", e)
 
+    try:
+        conn.execute("SELECT 1 FROM agent_commons LIMIT 0")
+    except sqlite3.OperationalError as e:
+        _reraise_if_migration_interrupted(e)
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS agent_commons (
+                id           TEXT PRIMARY KEY,
+                kind         TEXT NOT NULL,
+                agent        TEXT NOT NULL,
+                campaign_id  TEXT NOT NULL DEFAULT '',
+                outreach_id  TEXT,
+                body         TEXT,
+                decision     TEXT,
+                reason       TEXT,
+                created_at   INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+                expires_at   INTEGER
+            );
+            CREATE INDEX IF NOT EXISTS idx_agent_commons_beat
+                ON agent_commons(campaign_id, agent, kind);
+            CREATE INDEX IF NOT EXISTS idx_agent_commons_notes
+                ON agent_commons(campaign_id, kind, expires_at);
+        """)
+        conn.commit()
+        logger.info("Migration: added agent_commons table")
+
 
 def _backfill_global_contacts(conn: sqlite3.Connection) -> None:
     """One-time backfill: create global_contacts from existing campaign contacts.

{heylead-0.10.332 → heylead-0.10.333}/src/heylead/server.py

@@ -28,6 +28,12 @@ from .ops_log import run_traced
 _CHANGELOG = """\
 # HeyLead Changelog
 
+## v0.10.333 (2026-09-09)
+- New: in-process agents leave an inspectable commons — a heartbeat after
+  every loop, and one short note per run for the next tick.
+  inspect(action='commons') shows beats, live notes, and who went dark
+  (#275)
+
 ## v0.10.332 (2026-09-09)
 - New: brand_strategy(action="set_headline", focus="...") sets the LinkedIn
   headline to exactly the text you pass. execute and makeover both write a
@@ -1236,7 +1242,9 @@ mcp = FastMCP(
         "    edit_campaign(enable_reply_agent='on'),\n"
         "    edit_campaign(enable_strategist_replan_agent='on'), or\n"
         "    edit_campaign(enable_hot_lead_closer='on'). Use 'observe' to\n"
-        "    return to logging-only, 'off' to disable.\n"
+        "    return to logging-only, 'off' to disable. If they ask what the\n"
+        "    agents left for the next tick, or who went dark, call\n"
+        "    inspect(action='commons').\n"
         "  - book_meeting() — put an agreed call on your Google Calendar and invite them\n"
         "  - suggest_next_action() — AI-recommended next step\n"
         "  - analytics(action='report') — detailed analytics with outcomes and stale lead warnings\n"
@@ -2299,6 +2307,7 @@ async def inspect(
             "closer"  — today's hot_lead_closer_decision rows
             "skips"   — recent reply skips (hard gates, cap, dedup, agent skip)
             "jobs"    — pending scheduler jobs and recent gated-job refusals
+            "commons" — last agent beats, live notes, and stale liveness
         campaign_id: Optional campaign filter (full id or prefix).
         outreach_id: Optional outreach filter (full id or prefix).
         limit: Max rows per slice, 1-100 (default 20).

heylead-0.10.333/src/heylead/services/agent_commons.py

@@ -0,0 +1,227 @@
+"""Official inspectable scratch for in-process agents.
+
+Sidecar beats after every loop. Tools may leave one short note per run.
+Nothing here writes LinkedIn, email, or calendar.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from ..db.schema import get_db
+
+VALID_AGENTS = frozenset({"reply", "strategist", "closer", "icp_research"})
+NOTE_MAX_CHARS = 500
+BEAT_REASON_MAX = 240
+NOTE_TTL_SECONDS = 24 * 3600
+STALE_AFTER_SECONDS = 6 * 3600
+
+
+def beat_is_stale(
+    beat: dict[str, Any],
+    *,
+    mode: str,
+    now: int | None = None,
+) -> bool:
+    if (mode or "").strip().lower() == "off":
+        return False
+    ts = int(beat.get("created_at") or 0)
+    when = int(now if now is not None else time.time())
+    return bool(ts) and (when - ts) > STALE_AFTER_SECONDS
+
+
+def upsert_beat(
+    *,
+    agent: str,
+    campaign_id: str,
+    decision: str,
+    reason: str,
+    timestamp: int | None = None,
+) -> None:
+    if agent not in VALID_AGENTS:
+        return
+    cid = campaign_id or ""
+    ts = int(timestamp if timestamp is not None else time.time())
+    text = (reason or "")[:BEAT_REASON_MAX]
+    db = get_db()
+    try:
+        row = db.execute(
+            """SELECT id FROM agent_commons
+               WHERE kind = 'beat' AND campaign_id = ? AND agent = ?""",
+            (cid, agent),
+        ).fetchone()
+        if row:
+            db.execute(
+                """UPDATE agent_commons
+                   SET decision = ?, reason = ?, created_at = ?
+                   WHERE id = ?""",
+                (decision, text, ts, row["id"]),
+            )
+        else:
+            db.execute(
+                """INSERT INTO agent_commons
+                   (id, kind, agent, campaign_id, decision, reason, created_at)
+                   VALUES (?, 'beat', ?, ?, ?, ?, ?)""",
+                (str(uuid.uuid4()), agent, cid, decision, text, ts),
+            )
+        db.commit()
+    finally:
+        db.close()
+
+
+def insert_note(
+    *,
+    agent: str,
+    campaign_id: str,
+    body: str,
+    outreach_id: str = "",
+    now: int | None = None,
+) -> str:
+    if agent not in VALID_AGENTS:
+        return "refused: unknown agent"
+    text = (body or "").strip()
+    if not text:
+        return "refused: empty note"
+    if len(text) > NOTE_MAX_CHARS:
+        return f"refused: note longer than {NOTE_MAX_CHARS} characters"
+    created = int(now if now is not None else time.time())
+    db = get_db()
+    try:
+        db.execute(
+            """INSERT INTO agent_commons
+               (id, kind, agent, campaign_id, outreach_id, body, created_at, expires_at)
+               VALUES (?, 'note', ?, ?, ?, ?, ?, ?)""",
+            (
+                str(uuid.uuid4()),
+                agent,
+                campaign_id or "",
+                outreach_id or None,
+                text,
+                created,
+                created + NOTE_TTL_SECONDS,
+            ),
+        )
+        db.commit()
+    finally:
+        db.close()
+    return "ok"
+
+
+def list_beats(*, campaign_id: str = "") -> list[dict[str, Any]]:
+    db = get_db()
+    try:
+        if campaign_id:
+            rows = db.execute(
+                """SELECT * FROM agent_commons
+                   WHERE kind = 'beat' AND (campaign_id = ? OR campaign_id = '')
+                   ORDER BY created_at DESC""",
+                (campaign_id,),
+            ).fetchall()
+        else:
+            rows = db.execute(
+                """SELECT * FROM agent_commons
+                   WHERE kind = 'beat'
+                   ORDER BY created_at DESC""",
+            ).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        db.close()
+
+
+def list_live_notes(
+    *,
+    campaign_id: str = "",
+    outreach_id: str = "",
+    now: int | None = None,
+) -> list[dict[str, Any]]:
+    when = int(now if now is not None else time.time())
+    db = get_db()
+    try:
+        params: list[Any] = [when]
+        where = ["kind = 'note'", "(expires_at IS NULL OR expires_at > ?)"]
+        if campaign_id:
+            where.append("(campaign_id = ? OR campaign_id = '')")
+            params.append(campaign_id)
+        if outreach_id:
+            where.append("(outreach_id = ? OR outreach_id IS NULL)")
+            params.append(outreach_id)
+        rows = db.execute(
+            f"""SELECT * FROM agent_commons
+                WHERE {' AND '.join(where)}
+                ORDER BY created_at DESC""",
+            params,
+        ).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        db.close()
+
+
+def read_commons_text(
+    *,
+    campaign_id: str = "",
+    outreach_id: str = "",
+    now: int | None = None,
+) -> str:
+    beats = list_beats(campaign_id=campaign_id)
+    notes = list_live_notes(campaign_id=campaign_id, outreach_id=outreach_id, now=now)
+    lines = ["beats:"]
+    if beats:
+        for beat in beats:
+            lines.append(
+                f"- {beat.get('agent')}: {beat.get('decision') or '?'} "
+                f"— {(beat.get('reason') or '')[:120]}"
+            )
+    else:
+        lines.append("- (none)")
+    lines.append("notes:")
+    if notes:
+        for note in notes:
+            lines.append(f"- {note.get('agent')}: {note.get('body') or ''}")
+    else:
+        lines.append("- (none)")
+    return "\n".join(lines)
+
+
+def commons_tools(
+    *,
+    agent: str,
+    campaign_id: str,
+    outreach_id: str = "",
+) -> dict[str, Callable[..., str]]:
+    wrote = {"n": 0}
+
+    def read_commons() -> str:
+        return read_commons_text(campaign_id=campaign_id, outreach_id=outreach_id)
+
+    def write_commons(reason: str = "", note: str = "") -> str:
+        if wrote["n"]:
+            return "refused: one note per run"
+        result = insert_note(
+            agent=agent,
+            campaign_id=campaign_id,
+            outreach_id=outreach_id,
+            body=(note or reason),
+        )
+        if result == "ok":
+            wrote["n"] += 1
+        return result
+
+    return {"read_commons": read_commons, "write_commons": write_commons}
+
+
+def record_agent_beat(
+    *,
+    agent: str,
+    campaign_id: str,
+    decision: str,
+    reason: str,
+) -> None:
+    upsert_beat(
+        agent=agent,
+        campaign_id=campaign_id,
+        decision=decision,
+        reason=reason,
+    )