@m13v/s4l 1.6.197-rc.7

package/scripts/dm_db_update.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""dm_db_update.py — single-row PATCH helper for the `dms` table.
+
+Created 2026-05-18 as the replacement for the three inline
+`psql "$DATABASE_URL" -c "UPDATE dms SET ..."` lines the dm-outreach-*
+shell pipelines used to embed in their Claude prompts. The LLM is told to
+shell out to this script instead of psql so all DB writes route through
+/api/v1/dms/:id and we keep the credentials surface inside the helper.
+
+Usage:
+    python3 scripts/dm_db_update.py --dm-id N \
+        [--status pending|sent|error|skipped|...] \
+        [--skip-reason TEXT] \
+        [--claude-session-id UUID]
+
+At least one of --status / --skip-reason / --claude-session-id is
+required. Status and skip_reason can be set independently (the PATCH
+route uses COALESCE for every field, so omitted fields stay unchanged).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_patch  # noqa: E402
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dm-id", type=int, required=True)
+    ap.add_argument("--status")
+    ap.add_argument("--skip-reason")
+    ap.add_argument("--claude-session-id")
+    args = ap.parse_args()
+
+    body: dict = {}
+    if args.status:
+        body["status"] = args.status
+    if args.skip_reason:
+        body["skip_reason"] = args.skip_reason
+    if args.claude_session_id:
+        body["claude_session_id"] = args.claude_session_id
+
+    if not body:
+        print(
+            "dm_db_update: nothing to update; pass at least --status, "
+            "--skip-reason, or --claude-session-id",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        resp = api_patch(f"/api/v1/dms/{args.dm_id}", body)
+    except SystemExit as e:
+        print(f"dm_db_update: PATCH /api/v1/dms/{args.dm_id} failed: {e}", file=sys.stderr)
+        return 1
+
+    dm = (resp.get("data") or {}).get("dm") or {}
+    print(
+        f"dm_db_update: dm #{args.dm_id} status={dm.get('status')!r} "
+        f"skip_reason={dm.get('skip_reason')!r}",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/dm_engage_helper.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""HTTP-only stdout shims for the psql one-liners in skill/engage-dm-replies.sh.
+
+The engage pipeline used to embed raw `psql "$DATABASE_URL" -t -A -c "..."`
+calls for its read-side gates and end-of-run summary. The direct-Postgres lane
+was removed 2026-06-01; DATABASE_URL is deliberately ignored, no DB, no
+fallback. Each subcommand here calls the s4l.ai HTTP API (scripts/http_api.py)
+and prints EXACTLY what the corresponding psql call printed, so the shell
+parsing around it (json.load, `tr '|' ' '`, integer compares) is unchanged.
+
+Subcommands (each maps 1:1 to a former psql call):
+  pending --platform X --limit 30   -> PENDING_CONVOS: JSON array, or 'null'
+  needs-reply --platform X          -> needs_reply_count_for: integer
+  run-counts --platform X --since N -> dm_counts_for: 'POSTED STALE'
+  summary                           -> DM_SUMMARY: json object
+  reddit-authors                    -> KNOWN_REDDIT_AUTHORS: 'a, b, c'
+  reddit-campaign-suffix            -> REDDIT_CAMPAIGN_SUFFIX_LITERAL
+  reddit-campaign-sample-rate       -> REDDIT_CAMPAIGN_SAMPLE_RATE
+  flagged-count                     -> FLAGGED_COUNT: integer
+
+All endpoints live under /api/v1/dms/engage except the campaign subcommands
+(/api/v1/campaigns) and flagged-count (/api/v1/dms/flagged).
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get
+
+
+def _data(resp):
+    return (resp or {}).get("data") or {}
+
+
+def cmd_pending(args):
+    resp = api_get(
+        "/api/v1/dms/engage",
+        query={"mode": "pending", "platform": args.platform or "", "limit": args.limit},
+    )
+    rows = _data(resp).get("rows")
+    # Mirror psql's `json_agg(...) -> NULL when empty` which the shell echoed as
+    # the literal string 'null'.
+    if not rows:
+        print("null")
+    else:
+        print(json.dumps(rows))
+
+
+def cmd_needs_reply(args):
+    resp = api_get(
+        "/api/v1/dms/engage",
+        query={"mode": "needs_reply", "platform": args.platform or ""},
+    )
+    print(_data(resp).get("count", 0))
+
+
+def cmd_run_counts(args):
+    resp = api_get(
+        "/api/v1/dms/engage",
+        query={"mode": "run_counts", "platform": args.platform or "", "since": args.since},
+    )
+    d = _data(resp)
+    # psql printed 'posted|stale' then the shell did `tr '|' ' '`; emit the
+    # already-split form so `read -r POSTED STALE` works directly.
+    print(f"{d.get('posted', 0)} {d.get('stale', 0)}")
+
+
+def cmd_summary(_args):
+    resp = api_get("/api/v1/dms/engage", query={"mode": "summary"})
+    summary = _data(resp).get("summary") or {}
+    # Match the json_build_object the shell logs verbatim.
+    print(json.dumps(summary))
+
+
+def cmd_reddit_authors(_args):
+    resp = api_get("/api/v1/dms/engage", query={"mode": "reddit_authors"})
+    print(_data(resp).get("authors") or "")
+
+
+def _active_reddit_campaign():
+    """First active reddit campaign with budget remaining + a non-empty suffix.
+
+    Mirrors the two REDDIT_CAMPAIGN_* psql queries: status='active',
+    platforms includes reddit, max_posts_total set AND posts_made < it,
+    suffix non-empty, ORDER BY id LIMIT 1.
+    """
+    resp = api_get(
+        "/api/v1/campaigns",
+        query={
+            "status": "active",
+            "platform": "reddit",
+            "has_suffix": "true",
+            "with_budget_remaining": "true",
+            "limit": 500,
+        },
+    )
+    rows = _data(resp).get("campaigns") or []
+    for r in rows:  # already ORDER BY id ASC server-side
+        max_total = r.get("max_posts_total")
+        posts_made = r.get("posts_made") or 0
+        suffix = r.get("suffix")
+        if max_total is None or posts_made >= max_total:
+            continue
+        if not suffix:
+            continue
+        return r
+    return None
+
+
+def cmd_reddit_campaign_suffix(_args):
+    c = _active_reddit_campaign()
+    # psql piped through `tr -d '\n'`; print with no trailing newline.
+    sys.stdout.write(c.get("suffix") if c else "")
+
+
+def cmd_reddit_campaign_sample_rate(_args):
+    c = _active_reddit_campaign()
+    if not c:
+        sys.stdout.write("")
+        return
+    rate = c.get("sample_rate")
+    sys.stdout.write("1.000" if rate is None else str(rate))
+
+
+def cmd_flagged_count(_args):
+    resp = api_get("/api/v1/dms/flagged")
+    print(_data(resp).get("count", 0))
+
+
+def main():
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("pending")
+    sp.add_argument("--platform", default="")
+    sp.add_argument("--limit", type=int, default=30)
+    sp.set_defaults(func=cmd_pending)
+
+    sp = sub.add_parser("needs-reply")
+    sp.add_argument("--platform", default="")
+    sp.set_defaults(func=cmd_needs_reply)
+
+    sp = sub.add_parser("run-counts")
+    sp.add_argument("--platform", default="")
+    sp.add_argument("--since", type=int, required=True)
+    sp.set_defaults(func=cmd_run_counts)
+
+    sub.add_parser("summary").set_defaults(func=cmd_summary)
+    sub.add_parser("reddit-authors").set_defaults(func=cmd_reddit_authors)
+    sub.add_parser("reddit-campaign-suffix").set_defaults(func=cmd_reddit_campaign_suffix)
+    sub.add_parser("reddit-campaign-sample-rate").set_defaults(func=cmd_reddit_campaign_sample_rate)
+    sub.add_parser("flagged-count").set_defaults(func=cmd_flagged_count)
+
+    args = p.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/dm_outreach_helper.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""dm_outreach_helper.py — shell-friendly entrypoints for the dm-outreach
+{reddit,twitter,linkedin}.sh pipelines that used to inline `psql` calls.
+
+Subcommands (all route through /api/v1/dms* on the website):
+
+  count --platform reddit --status pending
+    -> prints integer count to stdout (one line). Used by the bash
+       script's "DM_PENDING / SENT / STILL_PENDING" sentinels.
+
+  outreach-queue --platform reddit
+    -> prints JSON shape matching the legacy
+       `psql ... "SELECT json_agg(q) FROM ... JOIN replies ... JOIN posts ..."`
+       query: an array of dms rows joined with reply + post + a 60-day
+       other_engagement summary per author. Output is exactly the same
+       JSON the LLM prompt expects (DM_DATA variable in dm-outreach-*.sh).
+
+  patch --id 123 --status error --skip-reason send_unverified
+    -> PATCH /api/v1/dms/123. Replaces the bash-embedded
+       `psql ... "UPDATE dms SET status=..., skip_reason=..."` blocks
+       (the ones the LLM is told to run). Supports any combo of
+       --status / --skip-reason / --claude-session-id.
+
+       (NOTE: this still flips status freely. dm_send_log.py is the only
+        path that's allowed to set status='sent' with verification — DO
+        NOT use this `patch` subcommand to mark a DM as sent. The legacy
+        bash script's prompt was already careful about this; we preserve
+        that constraint.)
+
+This script intentionally does NOT touch dm_conversation.py or the dms
+DB schema directly. Everything goes through HTTP routes, no psycopg2.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get, api_patch
+
+
+def _cmd_count(args):
+    query = {
+        "platform": args.platform,
+        "status": args.status,
+        "count_only": "true",
+    }
+    if args.target_project:
+        query["target_project"] = args.target_project
+    resp = api_get("/api/v1/dms", query=query)
+    data = (resp or {}).get("data") or {}
+    print(int(data.get("count") or 0))
+
+
+def _cmd_outreach_queue(args):
+    query = {
+        "platform": args.platform,
+        "status": args.status,
+        "limit": args.limit,
+        "other_engagement_days": args.other_engagement_days,
+    }
+    resp = api_get("/api/v1/dms/outreach-queue", query=query)
+    data = (resp or {}).get("data") or {}
+    rows = data.get("rows") or []
+    # Mirror the legacy `SELECT json_agg(q) FROM (...) q;` output shape.
+    # The psql command returned a single JSON array (or empty string when
+    # zero rows). The LLM prompt expects an array literal it can read
+    # directly. Print [] when empty to match.
+    json.dump(rows, sys.stdout)
+    print("", file=sys.stdout)
+
+
+def _cmd_patch(args):
+    if args.status == "sent":
+        # status='sent' must go through scripts/dm_send_log.py (verified
+        # outbound path). Anything else (error, skipped, queued, ...) is
+        # fine to flip from here.
+        print(
+            "ERROR: dm_outreach_helper.py patch refuses to set status=sent. "
+            "Use scripts/dm_send_log.py with --verified instead.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    body: dict = {}
+    if args.status:
+        body["status"] = args.status
+    if args.skip_reason is not None:
+        body["skip_reason"] = args.skip_reason
+    if args.claude_session_id:
+        body["claude_session_id"] = args.claude_session_id
+    if args.conversation_status:
+        body["conversation_status"] = args.conversation_status
+
+    if not body:
+        print("ERROR: nothing to patch (no --status / --skip-reason / ...)",
+              file=sys.stderr)
+        sys.exit(2)
+
+    resp = api_patch(f"/api/v1/dms/{args.id}", body)
+    data = (resp or {}).get("data") or {}
+    dm = data.get("dm")
+    if dm:
+        print(f"PATCHED dm_id={dm.get('id')} status={dm.get('status')} "
+              f"skip_reason={dm.get('skip_reason')}")
+    else:
+        # Route returned no body (shouldn't happen on 200) — emit raw resp.
+        json.dump(resp, sys.stdout)
+        print("", file=sys.stdout)
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pc = sub.add_parser("count", help="Print COUNT(*) for filtered dms")
+    pc.add_argument("--platform", required=True)
+    pc.add_argument("--status", default="pending")
+    pc.add_argument("--target-project", default=None)
+    pc.set_defaults(func=_cmd_count)
+
+    pq = sub.add_parser("outreach-queue",
+                        help="Emit the join'd DM/reply/post JSON for the LLM prompt")
+    pq.add_argument("--platform", required=True)
+    pq.add_argument("--status", default="pending")
+    pq.add_argument("--limit", type=int, default=50)
+    pq.add_argument("--other-engagement-days", type=int, default=60)
+    pq.set_defaults(func=_cmd_outreach_queue)
+
+    pp = sub.add_parser("patch",
+                        help="PATCH a dms row (status / skip_reason / etc.)")
+    pp.add_argument("--id", required=True, type=int)
+    pp.add_argument("--status", default=None,
+                    help="New status (NOT 'sent' — use dm_send_log.py for that).")
+    pp.add_argument("--skip-reason", default=None,
+                    help="Reason string (e.g. 'send_unverified', 'reddit_browser_busy').")
+    pp.add_argument("--conversation-status", default=None)
+    pp.add_argument("--claude-session-id", default=None)
+    pp.set_defaults(func=_cmd_patch)
+
+    args = p.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/dm_outreach_twitter_helper.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""dm_outreach_twitter_helper.py — small CLI wrapper used by
+skill/dm-outreach-twitter.sh to replace the four direct `psql` one-liners
+the script used to embed inline (pending count, outreach JSON aggregation,
+MCP-failure recovery sweep, sent/still-pending summary counts).
+
+Subcommands:
+  pending-count
+      -> GET /api/v1/dms/counts?platform=twitter (canonicalises to 'x')
+      -> prints the integer pending count
+
+  outreach-queue
+      -> GET /api/v1/dms/outreach-queue?platform=twitter&status=pending
+      -> prints the rows as a JSON ARRAY (mirrors the legacy
+         `SELECT json_agg(q) FROM (...) q` shape the bash prompt embeds)
+
+  recover-mcp --session-id UUID
+      -> POST /api/v1/dms/recover-mcp-failures { platform, claude_session_id }
+      -> prints the recovered_count integer
+
+  summary
+      -> GET /api/v1/dms/counts?platform=twitter
+      -> prints "<sent> <still_pending>" so the legacy two-variable capture
+         keeps working (SENT/STILL_PENDING in dm-outreach-twitter.sh).
+
+Migrated 2026-05-18: removes 4 direct psql calls from
+skill/dm-outreach-twitter.sh. The dms table stores Twitter rows with
+platform='x' (scan_dm_candidates.py:219-220 normalises 'twitter' → 'x'
+before INSERT); routes accept either form and the canonicalDmPlatform
+helper rewrites the WHERE clauses uniformly.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get, api_post  # noqa: E402
+
+
+def _counts_dict() -> dict[str, int]:
+    resp = api_get(
+        "/api/v1/dms/counts",
+        query={"platform": "twitter"},
+    )
+    rows = (resp.get("data") or {}).get("counts") or []
+    out: dict[str, int] = {}
+    for r in rows:
+        s = r.get("status")
+        if s is None:
+            continue
+        try:
+            out[str(s)] = int(r.get("count") or 0)
+        except (TypeError, ValueError):
+            out[str(s)] = 0
+    return out
+
+
+def cmd_pending_count() -> int:
+    counts = _counts_dict()
+    sys.stdout.write(f"{int(counts.get('pending') or 0)}\n")
+    return 0
+
+
+def cmd_summary() -> int:
+    counts = _counts_dict()
+    sent = int(counts.get("sent") or 0)
+    pending = int(counts.get("pending") or 0)
+    sys.stdout.write(f"{sent} {pending}\n")
+    return 0
+
+
+def cmd_outreach_queue() -> int:
+    resp = api_get(
+        "/api/v1/dms/outreach-queue",
+        query={
+            "platform": "twitter",
+            "status": "pending",
+            "limit": 200,
+            "other_engagement_days": 60,
+        },
+    )
+    rows = (resp.get("data") or {}).get("rows") or []
+    # The legacy psql query returned an array (json_agg result); reshape
+    # to that same array shape. Each row already carries the embedded
+    # other_engagement array from the route's correlated subquery.
+    sys.stdout.write(json.dumps(rows))
+    sys.stdout.write("\n")
+    return 0
+
+
+def cmd_recover_mcp(session_id: str) -> int:
+    resp = api_post(
+        "/api/v1/dms/recover-mcp-failures",
+        {"platform": "twitter", "claude_session_id": session_id},
+    )
+    d = resp.get("data") or {}
+    sys.stdout.write(f"{int(d.get('recovered_count') or 0)}\n")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Helper for dm-outreach-twitter.sh")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("pending-count")
+    sub.add_parser("outreach-queue")
+    sub.add_parser("summary")
+
+    p_rec = sub.add_parser("recover-mcp")
+    p_rec.add_argument("--session-id", required=True)
+
+    args = ap.parse_args()
+
+    if args.cmd == "pending-count":
+        return cmd_pending_count()
+    if args.cmd == "summary":
+        return cmd_summary()
+    if args.cmd == "outreach-queue":
+        return cmd_outreach_queue()
+    if args.cmd == "recover-mcp":
+        return cmd_recover_mcp(args.session_id)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/dm_send_log.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Log a successful, verified DM send.
+
+Usage:
+  dm_send_log.py --dm-id DM_ID --message TEXT --verified \
+                 [--session-id UUID]
+
+REQUIRES --verified. Without it the script refuses to flip status='sent'.
+This is the gate against the prompt-driven "always mark sent" bug that
+produced ~700 phantom rows in April 2026. The browser tool's send_dm /
+compose_dm now returns ok=False when DOM verification fails; the LLM
+running the outreach pipeline must only call this script when the tool
+actually returned verified=true.
+"""
+import argparse
+import os
+import subprocess
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+
+def load_env():
+    env_path = "/Users/matthewdi/social-autoposter/.env"
+    if not os.path.exists(env_path):
+        return
+    for line in open(env_path):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            k, v = line.split("=", 1)
+            os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Log a verified DM send (gates status='sent' on --verified)."
+    )
+    parser.add_argument("--dm-id", required=True, help="dms.id")
+    parser.add_argument("--message", required=True, help="DM body that was sent")
+    parser.add_argument(
+        "--verified",
+        action="store_true",
+        help="REQUIRED. Confirms the browser tool returned verified=true.",
+    )
+    parser.add_argument(
+        "--session-id",
+        default=os.environ.get("CLAUDE_SESSION_ID"),
+        help="claude_session_id UUID (defaults to $CLAUDE_SESSION_ID)",
+    )
+
+    # Back-compat: old call sites used positional dm_id + message.
+    # Detect that shape so we can refuse cleanly instead of crashing.
+    if len(sys.argv) >= 3 and not sys.argv[1].startswith("--"):
+        print(
+            "ERROR: dm_send_log.py now requires named flags. Call as:\n"
+            "  dm_send_log.py --dm-id ID --message TEXT --verified",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    args = parser.parse_args()
+
+    if not args.verified:
+        print(
+            "ERROR: refusing to mark dm_id={} as sent without --verified.\n"
+            "The browser send_dm/compose_dm tool must return verified=true "
+            "first. If verification failed, mark the row as 'error' instead.".format(
+                args.dm_id
+            ),
+            file=sys.stderr,
+        )
+        sys.exit(3)
+
+    load_env()
+    import http_api
+    from version import read_version as read_autoposter_version
+    patch_body: dict = {"status": "sent", "our_dm_content": args.message}
+    if args.session_id:
+        patch_body["claude_session_id"] = args.session_id
+    # autoposter_version: stamp on the 'sent' transition so DM engagement
+    # (replies / bookings) can be attributed to the release of the autoposter
+    # code that drafted the message.
+    autoposter_version = read_autoposter_version()
+    if autoposter_version:
+        patch_body["autoposter_version"] = autoposter_version
+    http_api.api_patch(f"/api/v1/dms/{args.dm_id}", patch_body)
+
+    subprocess.run(
+        [
+            "python3",
+            "/Users/matthewdi/social-autoposter/scripts/dm_conversation.py",
+            "log-outbound",
+            "--dm-id",
+            str(args.dm_id),
+            "--content",
+            args.message,
+            "--verified",
+        ],
+        check=True,
+    )
+
+
+if __name__ == "__main__":
+    main()