agent-reach

Platform-native social reading for the Aries weekly research stage.

/last30days answers "what have people been saying about this topic across the last 30 days" (aggregate listening). This answers a different question: "what is winning on this platform right now" — the actual posts, opening hooks, formats and comment language currently getting traction in a niche.

THE ONE RULE

A stale session is a normal answer, not an error. These sessions are cookie based and expire. If the session is dead, return the session_stale JSON below immediately and stop. Do not retry, do not log in, do not ask for credentials, do not fall back to a browser or to curl. The research agent is told that session_stale is a reportable outcome and degrades to /last30days plus web_search on its own. Hanging here instead burns the stage's 600 s budget and fails the whole weekly run over a cookie.

Steps

1. Check freshness FIRST (cheap, always)

python3 "${ARIES_COOKIE_PROBER:-$HOME/.agent-reach/cookie-prober.py}" --status

~/.agent-reach/cookie-prober.py is a symlink into the repo, created by the install step below. It is deliberately not a repo path spelled out here: this file gets copied into the live gateway profile, the repo currently lives in a worktree, and a hardcoded path that stops resolving would fail as file-not-found on every single call — silently downgrading this cheap check into the expensive agent-reach doctor probe it exists to avoid. Override with ARIES_COOKIE_PROBER if the symlink cannot be used.

Read the line for the requested platform.

• fresh → continue to step 2.
• stale → return the session_stale payload (step 4) and STOP.
• unknown, or no state file at all → run one direct check, bounded: timeout 60 agent-reach doctor — treat "login required / unauthenticated / expired" as stale, anything else unreadable as stale too. When in doubt, answer session_stale. A false "stale" costs one enrichment; a false "fresh" costs a ten-minute stall.
• the command itself fails (No such file or directory — the symlink is missing or dangling) → treat exactly as unknown and continue, but say so in the detail of whatever you return: the pre-check is mis-installed, and that is an operator fix, not something to work around silently on every call.

2. Read the platform

Use the Agent-Reach channel for the requested platform, read-only, with a hard timeout so nothing can hang:

timeout 120 agent-reach <platform> <query>      # exact sub-command per `agent-reach doctor`

Collect at most 10 items. Reads only — never post, comment, follow, like or DM from these accounts. They are throwaways whose only job is reading.

3. Return strict JSON

{
  "status": "ok",
  "platform": "instagram",
  "query": "leather handbag styling",
  "observed_at": "2026-08-10T09:00:00Z",
  "items": [
    {
      "url": "https://…",
      "author": "@handle",
      "hook": "the opening line / first 8 words",
      "format": "carousel|reel|image|text|video",
      "engagement": "what the platform reported, verbatim (e.g. '12.4k likes, 310 comments')",
      "why_it_works": "one sentence, your read"
    }
  ],
  "patterns": ["2–5 short observations across the items"]
}

4. Stale-session payload

{ "status": "session_stale", "platform": "instagram", "detail": "logged-out session; owner re-mint required" }

Never put a cookie, token, header or account password in the output — not in detail, not anywhere. If a tool prints one, drop that line.

Installation (VM, owner-action)

This file lives in the repo at ops/agent-reach/skill/SKILL.md and is not installed by anything automatic. Copying it into the live profile is a change to the running research pipeline:

REPO=<repo>            # the worktree path until the branch merges, then repoint

mkdir -p ~/.hermes/profiles/aries-research/skills/social-media/agent-reach
cp $REPO/ops/agent-reach/skill/SKILL.md \
   ~/.hermes/profiles/aries-research/skills/social-media/agent-reach/SKILL.md

# The stable path step 1 calls. This symlink is what lets the copied skill find
# the prober no matter where the repo lives — REPOINT IT when the repo moves,
# or step 1 degrades to the expensive probe on every call without ever saying so.
ln -sfn $REPO/ops/agent-reach/cookie-prober.py ~/.agent-reach/cookie-prober.py

# Verify BEFORE restarting anything — this must print platform lines, not an error:
python3 ~/.agent-reach/cookie-prober.py --status

# then restart the aries-research gateway (port 8651) in a maintenance window

Install it only on the aries-research profile. The app advertises /agent-reach to the weekly research stage only, for exactly this reason — see WEEKLY_RESEARCH_AGENT_REACH_GUIDANCE in backend/marketing/ports/hermes.ts.