docs: fold PR #497's unique Deep Agents research notes into roadmap doc

[cgfixit]

What

Closes out the last open item from the recent PR resolution batch (#515-520 merged, #497 was the remaining open PR). #497's branch (origin/clonebackup-792026) added a single root file, LangchainDeepAgent.md, with research notes on Deep Agents memory design and harness-primitive naming.

• Privacy check: clean. None of the personal-identity markers ac1a195's redaction sweep removed appear in the file.
• Redundancy check: most content (the builder.py toothless-agent bug, unused SurfaceType/GovernanceFinding findings, Qwen/Kimi pricing research) was already absorbed into docs/agentic/GITHUB_DEEP_AGENT_HARNESS_OPTIMIZER_PLAN.md and docs/LangChain_Deep_Agentic_Harness_latest_roadmap.md during the 2026-07-11 consolidation. Three items were genuinely unique.

This PR folds those three items into the roadmap doc as a new dated section — the harness-primitive taxonomy / "doorbell" naming aside, the proposed multi-tier Deep Agents memory model, and a dynamic-subagent deployment policy sketch — preserved explicitly as unincorporated design research, not shipped behavior. Also adds a terminal PR resolution status section recording the whole batch's outcome, and fixes one now-stale line ("merge #515 first") in the working-agreements section now that #515 has merged.

LangchainDeepAgent.md itself is not added to the repo; #497's branch is not merged.

Why

Per owner instruction: fold #497's unique notes into the roadmap doc and drop the source file rather than merging a root-level notes dump, consistent with the repo's "don't duplicate another doc's authority" convention.

Risk to monitor

None — docs-only, one file. Recommend closing #497 as superseded once this merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K3WhoiUiUak84jUmiBhhvA

---

Generated by Claude Code

[cgfixit]

@claude Please Review Lint.yml errors since adding the SMS feature branch and a 127.0.0.1 triggered a security-PR-agent:

--

Ruff lint failures on sms_relay_v2.py (I001 + UP045 + S110 + S104) for PRs 527/528 branches.

These are exactly the kind of clean, low-effort hygiene issues that should be resolved before merge. Eight of the ten are auto-fixable; the two S-rule findings require deliberate judgment because they touch error handling and network exposure — areas that matter for any component that bridges external input (Twilio webhooks + SMS) into CyClaw.

1. I001 – Import block unsorted/unformatted

Ruff (isort) wants stdlib → third-party grouping with alphabetical ordering inside each block. This is non-negotiable for a project that values auditability and low-friction reviews.

Fixed import block (apply this or let ruff check --fix do it):

import asyncio
import hashlib
import json
import logging
import os
import sqlite3
import time
from xml.sax.saxutils import escape as xml_escape

import httpx
from fastapi import FastAPI, Form, HTTPException, Request
from fastapi.responses import Response
from twilio.request_validator import RequestValidator
from twilio.rest import Client as TwilioClient

• Removed the now-unnecessary from typing import Optional (see UP045 below).
• xml.sax.saxutils is stdlib, so it stays in the first block.
• FastAPI sub-imports are sorted; Twilio imports grouped.

Run ruff check --fix --select I . (or the full select list) and it will apply this cleanly.

2. UP045 – Replace Optional[X] with X | None (Python 3.10+ / 3.12 style)

CyClaw targets Python 3.12 (Dockerfile + verify.sh). The modern union syntax is shorter, more readable, and the project standard going forward.

Affected sites and fixes (from the traceback):

• log_event(...) (lines ~102-104):

  def log_event(
      phone: str,
      event_type: str,
      msg_sid: str | None = None,
      query: str | None = None,
      provider: str | None = None,
      detail: str | None = None,
  ) -> None:

• get_session(...) (line 125):

  def get_session(phone: str) -> dict | None:

• format_page(...) (line 205):

  def format_page(chunks: list[str], idx: int, footer: str | None = None) -> str:

• handle_cyclaw_result(...) (line 265):

  async def handle_cyclaw_result(
      phone: str,
      query: str,
      data: dict,
      msg_sid: str,
      provider_override: str | None = None,
  ):

ruff check --fix --select UP will rewrite all of these automatically. No behavior change.

3. S110 – try: ... except Exception: pass (bare except that swallows everything)

Line ~301 (the CyClaw error notification path):

try:
    await send_sms(phone, f"CyClaw error: {str(e)[:120]}")
except Exception:
    pass

Why this is a real problem here:

• This is a webhook handler / SMS relay that surfaces CyClaw results or errors to a human via SMS. Silently swallowing failures means you can lose visibility into Twilio delivery problems, rate limits, or downstream issues.
• CyClaw's own philosophy (Audit Convergence invariant + explicit logging in audit_logger, ops_* events, etc.) demands that errors surface somewhere. A bare pass violates that spirit even in an auxiliary relay.
• It can hide bugs during development or production incidents.

Recommended fix (best-effort notification with visibility):

try:
    await send_sms(phone, f"CyClaw error: {str(e)[:120]}")
except Exception as exc:
    logging.exception("Failed to deliver CyClaw error notification via SMS to %s: %s", phone, exc)
    # Do NOT re-raise — we still want to return a 200/valid TwiML response to Twilio
    # so the webhook doesn't get retried endlessly. The exception is now logged.

You could narrow the except to (httpx.HTTPError, TwilioRestException) if you import the latter, but a broad Exception with explicit logging is acceptable in a webhook "best effort" notification path. The key is never silent.

4. S104 – Binding to all interfaces (host="0.0.0.0")

Line ~396 in __main__:

uvicorn.run(app, host="0.0.0.0", port=SMS_RELAY_PORT)

Nuance specific to this component:

• CyClaw core (gate.py) deliberately binds only to 127.0.0.1 (see Dockerfile, threat model, and SECURITY_THREAT_model.md). That is correct for the primary RAG/soul service.
• An SMS relay that receives Twilio webhooks is different: Twilio must be able to POST to it from the public internet. Hardcoding 0.0.0.0 without configuration or documentation is still risky (accidental exposure, IPv6 surprises, etc.).
• Bandit flags it because "all interfaces" is a common footgun.

Better pattern (recommended):

if __name__ == "__main__":
    import uvicorn

    host = os.environ.get("SMS_RELAY_HOST", "127.0.0.1")
    port = int(os.environ.get("SMS_RELAY_PORT", SMS_RELAY_PORT))
    uvicorn.run(app, host=host, port=port)

Add a comment block:

# SMS_RELAY_HOST: Set to 0.0.0.0 (or specific interface) only when this relay
# must accept Twilio webhooks from the public internet. Production deploys
# should front this with a reverse proxy / TLS terminator + firewall rules.
# Default remains loopback for consistency with CyClaw's zero-trust posture.

If the relay is intended to be publicly reachable, you should also ensure:

• Twilio RequestValidator signature checking is always active (it already appears to be).
• Strong rate limiting / per-phone allow-listing.
• Minimal PII in logs (hash phones or use short-lived session tokens).
• Consider running it behind Caddy/Nginx/Traefik with mTLS or IP allow-listing from Twilio's webhook IPs.

Recommended workflow for PRs 527/528 and lint.yml

1. Apply the auto-fixes locally:

   ruff check --fix --select E,F,I,B,C4,UP,S .

   This will clean I001 + all UP045. Then manually address S110 and S104 as above.

2. Update / create .github/workflows/lint.yml (if these PRs are also touching or introducing it):

   • Pin a recent ruff version (e.g., ruff==0.5.x or whatever is current and stable).
   • Run both ruff check and ruff format --check (or ruff check --select I + format).
   • Use a matrix or explicit Python 3.12 job.
   • Fail on the selected rules; consider making S104 a warning (with a comment) only for this relay module if you add a per-file ignore or config exception with justification.
   • Run on pull_request targeting main and on pushes to the feature branches linked to 527/528.
   • Add a step that surfaces the exact ruff command so future contributors see the exact select list.

   Example minimal job skeleton (adapt to your existing style):

   - name: Ruff lint
     run: |
       pip install "ruff==0.5.*"
       ruff check --select E,F,I,B,C4,UP,S .
       ruff format --check .

3. Broader CyClaw alignment notes (from the invariants perspective):

   • This relay is not core gate.py/graph.py path, so it doesn't directly threaten RAG-first / Topology=Policy / triple-gate / soul governance. Treat it as an optional operator / integration surface (similar in spirit to the out-of-band consoles or ops_runner.py shims).
   • Still apply the same rigor: explicit logging (for audit convergence), no silent failures, configurable networking, input validation (Twilio sig + your own phone allow-list + length/sanitizer on queries).
   • If handle_cyclaw_result or the query path eventually calls into CyClaw's HTTP API, go through the existing /query (or future MCP) surface rather than importing internal modules — that preserves module isolation (I6).
   • Edge cases worth handling before merge: SMS chunking/pagination (format_page), concurrent webhook handling + SQLite (consider aiosqlite or proper locking), Twilio retry behavior, phone number canonicalization (E.164), long-running CyClaw queries (async timeout + progress SMS), and graceful degradation when CyClaw is offline.

Bottom line: These are straightforward fixes. The auto-fixable ones (imports + Optional → | None) should be applied immediately. The S110/S104 items are the real value — they force you to think about observability and deployment posture for an externally triggered component. Fix them thoughtfully, document the networking decision, and the PRs will be cleaner.

If you paste the full current content of sms_relay_v2.py (or the diff from the branch), I can generate an exact unified diff or the complete corrected file ready to commit. I can also help review the broader design of the relay against CyClaw's logging/audit/sanitizer patterns if you want it to feel like a native extension rather than a bolt-on.

Run the fix command, push to the 527/528 branches, and re-trigger CI — reply with results in claude code

[github-actions]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.