@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/telegram_bridge/scripts/verify-tier3-smoke.sh

@@ -1,145 +0,0 @@
-#!/usr/bin/env bash
-# verify-tier3-smoke.sh — Tier 3 live verification smoke-checklist runner.
-#
-# Walks the operator through the live-verification scenarios listed in
-# references/verification.md §Tier 3 (3a daemon-boot, 3b /start handshake,
-# 3c spawn smoke, 3d file upload, 3e hand-off, 3f daemon-restart resilience).
-#
-# This script is INTERACTIVE — it prompts the operator at each step and
-# records pass/fail in a timestamped log. It does NOT run the spike suite
-# (use `VDS_TELEGRAM_SPIKE_LIVE=1 pytest tests/spikes/` for that).
-#
-# Preconditions (validated at start):
-#   - TELEGRAM_BOT_TOKEN set in ~/.vds/.env or environment
-#   - VDS_TELEGRAM_USER_ID set
-#   - vds-cli on PATH
-#   - docker compose stack with the telegram profile up
-#
-# Output: ./verification-log-<UTC-timestamp>.txt
-
-set -euo pipefail
-
-LOG="verification-log-$(date -u +%Y%m%dT%H%M%SZ).txt"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TG_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-WT_ROOT="$(cd "$TG_DIR/.." && pwd)"
-
-# ---- Helpers ---------------------------------------------------------------
-
-_log() {
-    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" | tee -a "$LOG"
-}
-
-_step() {
-    local id="$1"
-    local description="$2"
-    echo
-    _log "===> $id: $description"
-}
-
-_prompt_observe() {
-    local prompt="$1"
-    local result
-    echo "$prompt"
-    read -r -p "  result [pass/fail/skip]: " result
-    case "$result" in
-        pass|p) _log "  OBSERVED: PASS" ;;
-        fail|f) _log "  OBSERVED: FAIL — investigate, do not proceed to merge." ;;
-        skip|s) _log "  OBSERVED: SKIPPED" ;;
-        *) _log "  OBSERVED: '$result' (unrecognised — treating as FAIL)" ;;
-    esac
-}
-
-# ---- Preflight -------------------------------------------------------------
-
-_log "Tier 3 verification smoke for telegram-bridge"
-_log "  spec version: $(grep '^version:' "$WT_ROOT/.gpt-5.4/specs/telegram-bridge/tasks.md" 2>/dev/null | head -1 || echo unknown)"
-_log "  git SHA:      $(cd "$WT_ROOT" && git rev-parse --short HEAD)"
-_log "  log:          $LOG"
-
-if [[ -z "${TELEGRAM_BOT_TOKEN:-}" ]] && [[ -f "$HOME/.vds/.env" ]]; then
-    # shellcheck disable=SC1091
-    set -a; source "$HOME/.vds/.env"; set +a
-fi
-
-if [[ -z "${TELEGRAM_BOT_TOKEN:-}" ]]; then
-    _log "FAIL: TELEGRAM_BOT_TOKEN unset (and ~/.vds/.env did not supply it)"
-    exit 1
-fi
-if [[ -z "${VDS_TELEGRAM_USER_ID:-}" ]]; then
-    _log "FAIL: VDS_TELEGRAM_USER_ID unset"
-    exit 1
-fi
-if ! command -v vds-cli >/dev/null 2>&1; then
-    _log "FAIL: vds-cli not on PATH"
-    exit 1
-fi
-
-# ---- 3a — daemon boot smoke ------------------------------------------------
-
-_step "3a" "Daemon boot — vds-cli telegram status --ci should exit 0"
-if vds-cli telegram status --ci >/dev/null 2>&1; then
-    _log "  status --ci: exit 0 (healthy)"
-else
-    _log "  status --ci: NON-ZERO exit"
-    _log "  inspect: docker logs vds-telegram-daemon | tail -50"
-    exit 1
-fi
-
-# ---- 3b — /start handshake -------------------------------------------------
-
-_step "3b" "First-run /start handshake (AC-1.1)"
-echo "Manual step: in your supergroup, send '/start' from your account."
-_prompt_observe "  expected: bot replies 'registered' with the supergroup_id"
-
-echo
-echo "Sanity check via vds-cli telegram audit query:"
-vds-cli telegram audit query --event-type session_start --limit 3 || true
-
-_step "3b.2" "/start from a different chat is silently dropped"
-echo "Manual step: send '/start' to the bot in a DIFFERENT private chat."
-_prompt_observe "  expected: NO reply, NO new supergroup row"
-
-# ---- 3c — spawn smoke ------------------------------------------------------
-
-_step "3c" "Spawn smoke (AC-1.2 / AC-1.3)"
-echo "Manual step: in the supergroup, send '/spawn claude /tmp'."
-_prompt_observe "  expected: forum topic created, /sessions lists it"
-
-# ---- 3d — file upload smoke ------------------------------------------------
-
-_step "3d" "File upload (AC-1.8) — drop a screenshot"
-echo "Manual step: in the active session topic, drop any image as an attachment."
-_prompt_observe "  expected: bot replies with attached confirmation + sha"
-
-# ---- 3e — hand-off / continuity smoke --------------------------------------
-
-_step "3e" "Hand-off (AC-1.4) — terminal -> phone -> terminal"
-echo "Manual steps:"
-echo "  1. Run 'vds-cli claude --cwd ~/repo' in another terminal."
-echo "  2. From your phone, reply in the topic. Agent responds within 5 s."
-echo "  3. Run 'vds-cli claude --resume <session-id>' to reattach."
-_prompt_observe "  expected: replays >=99% of events from gap window within 10 s"
-
-# ---- 3f — daemon-restart resilience ----------------------------------------
-
-_step "3f" "Daemon-restart resilience (AC-1.9 / FR-9.10)"
-echo "Manual step: in another shell, run:"
-echo "    docker compose -p vds-telegram restart vds-telegram-daemon"
-echo "While a streaming response is in flight."
-_prompt_observe "  expected: streaming resumes <30s after restart, no replay"
-
-echo
-echo "Verifying vds_telegram_polling_state.last_update_offset advanced:"
-psql "${VDS_TELEGRAM_DB_DSN:-}" -c \
-    "SELECT last_update_offset, updated_at FROM vds_telegram_polling_state;" \
-    2>/dev/null || _log "  (could not reach Postgres - check DSN)"
-
-# ---- Summary ---------------------------------------------------------------
-
-echo
-_log "===> Tier 3 smoke walkthrough complete."
-_log "     Log written to: $LOG"
-_log "     Cross-reference per-spike outcomes in references/wave-0-spike-results.md."
-_log "     If all PASS, merge-gate is operator-cleared."
-_log "     If any FAIL, follow references/verification.md Failure Response."

package/tools/vds-scripts/telegram_bridge/shim.py

@@ -1,220 +0,0 @@
-"""Terminal shim — `vds-cli claude` / `vds-cli acp <agent>` (TSK-9.1-9.4).
-
-Per ADR-12, the shim uses `docker exec -i <container> socat UNIX-CONNECT:
-/run/vds-telegram/shim.sock STDIO` to reach the daemon's shim UDS from the
-host. This avoids exposing the UDS volume directly to the host (which would
-lose Docker's auth gate).
-
-Wave-3 P1-I deliverable. v1 scope:
-  * `vds-cli claude` — opens a session via `shim/hello {action="new"}`,
-    bidirectionally pipes stdin/stdout to the daemon.
-  * `vds-cli claude --resume <id>` — `shim/hello {action="resume",
-    session_id=<id>}` reattaches.
-  * `vds-cli claude --attach <topic-id>` — `shim/hello {action="attach",
-    topic_id=<id>}` joins a Telegram-driven session.
-  * `vds-cli acp <agent>` — same shape, parameterised by agent registry key.
-
-The daemon-side `shim_server.py` binding `/run/vds-telegram/shim.sock` lands
-in a follow-up commit; this module is the host-side client only.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import os
-import shutil
-import sys
-from pathlib import Path
-from typing import NoReturn
-
-import typer
-
-app = typer.Typer(help="vds-cli telegram-bridge shims (Wave 3 P1-I)")
-
-DEFAULT_CONTAINER = "vds-telegram-daemon"
-DEFAULT_SOCKET = "/run/vds-telegram/shim.sock"
-
-
-def _docker_exec_command(container: str, socket: str) -> list[str]:
-    """Build the docker-exec argv for the host-to-daemon UDS bridge."""
-    return [
-        "docker",
-        "exec",
-        "-i",
-        container,
-        "socat",
-        f"UNIX-CONNECT:{socket}",
-        "STDIO",
-    ]
-
-
-def _resolve_container() -> str:
-    """Container name from env, or default."""
-    return os.environ.get("VDS_TELEGRAM_CONTAINER", DEFAULT_CONTAINER)
-
-
-def _ensure_docker_available() -> None:
-    """Fail-fast with a friendly message if `docker` isn't on PATH."""
-    if shutil.which("docker") is None:
-        raise typer.BadParameter(
-            "the `docker` CLI is required to reach the daemon's shim socket. "
-            "Install Docker Desktop / docker-cli and ensure it's on PATH."
-        )
-
-
-@app.command("claude")
-def cmd_claude(
-    cwd: Path = typer.Option(
-        None,
-        "--cwd",
-        "-C",
-        help="Working directory for the new session (default: current dir).",
-    ),
-    resume: str | None = typer.Option(None, "--resume", help="Resume an existing session by id."),
-    attach: int | None = typer.Option(None, "--attach", help="Attach to a session by Telegram topic id."),
-) -> None:
-    """Start (or resume / attach) a Claude Code session via the daemon."""
-    _drive_session(agent_id="claude", cwd=cwd, resume=resume, attach=attach)
-
-
-@app.command("acp")
-def cmd_acp(
-    agent: str = typer.Argument(..., help="Registry key — e.g. cursor, codex, droid."),
-    cwd: Path = typer.Option(None, "--cwd", "-C"),
-    resume: str | None = typer.Option(None, "--resume"),
-    attach: int | None = typer.Option(None, "--attach"),
-) -> None:
-    """Start an ACP-native agent session via the daemon."""
-    _drive_session(agent_id=agent, cwd=cwd, resume=resume, attach=attach)
-
-
-def _drive_session(
-    *,
-    agent_id: str,
-    cwd: Path | None,
-    resume: str | None,
-    attach: int | None,
-) -> NoReturn:
-    """Open a daemon-shim connection and bidirectionally pipe stdin/stdout."""
-    _ensure_docker_available()
-
-    if sum(x is not None for x in (resume, attach)) > 1:
-        raise typer.BadParameter("--resume and --attach are mutually exclusive")
-
-    if resume is not None:
-        action = "resume"
-        hello = {"action": "resume", "session_id": resume}
-    elif attach is not None:
-        action = "attach"
-        hello = {"action": "attach", "topic_id": attach}
-    else:
-        action = "new"
-        cwd_path = (cwd or Path.cwd()).resolve()
-        hello = {"action": "new", "agent_id": agent_id, "cwd": str(cwd_path)}
-
-    container = _resolve_container()
-    socket = os.environ.get("VDS_TELEGRAM_SHIM_SOCKET", DEFAULT_SOCKET)
-    argv = _docker_exec_command(container, socket)
-
-    sys.stderr.write(f"vds-cli {agent_id}: {action} via {container}:{socket}\n")
-
-    try:
-        rc = asyncio.run(_pipe(argv, hello))
-    except KeyboardInterrupt:
-        sys.stderr.write("\n[detached]\n")
-        rc = 130
-    raise typer.Exit(code=rc)
-
-
-async def _pipe(argv: list[str], hello: dict) -> int:
-    """Spawn the docker-exec subprocess and pipe stdin/stdout over its stdio."""
-    proc = await asyncio.create_subprocess_exec(
-        *argv,
-        stdin=asyncio.subprocess.PIPE,
-        stdout=asyncio.subprocess.PIPE,
-        stderr=sys.stderr,
-    )
-    if proc.stdin is None or proc.stdout is None:
-        sys.stderr.write("subprocess pipes unavailable\n")
-        return 1
-
-    # Send hello frame first.
-    hello_line = json.dumps({"kind": "shim/hello", **hello}) + "\n"
-    proc.stdin.write(hello_line.encode())
-    await proc.stdin.drain()
-
-    # Run two pumps concurrently.
-    pump_in_task = asyncio.create_task(_pump_stdin_to_proc(proc))
-    pump_out_task = asyncio.create_task(_pump_proc_to_stdout(proc))
-    rc_task = asyncio.create_task(proc.wait())
-    _done, pending = await asyncio.wait(
-        {pump_in_task, pump_out_task, rc_task},
-        return_when=asyncio.FIRST_COMPLETED,
-    )
-    for t in pending:
-        t.cancel()
-    return proc.returncode if proc.returncode is not None else 1
-
-
-async def _pump_stdin_to_proc(proc: asyncio.subprocess.Process) -> None:
-    loop = asyncio.get_running_loop()
-    reader = asyncio.StreamReader()
-    transport, _ = await loop.connect_read_pipe(
-        lambda: asyncio.StreamReaderProtocol(reader),
-        sys.stdin,
-    )
-    try:
-        while True:
-            chunk = await reader.read(4096)
-            if not chunk:
-                if proc.stdin is not None:
-                    proc.stdin.close()
-                return
-            if proc.stdin is None:
-                return
-            proc.stdin.write(chunk)
-            await proc.stdin.drain()
-    except asyncio.CancelledError:
-        pass
-    finally:
-        transport.close()
-
-
-async def _pump_proc_to_stdout(proc: asyncio.subprocess.Process) -> None:
-    out = sys.stdout.buffer
-    try:
-        while True:
-            if proc.stdout is None:
-                return
-            chunk = await proc.stdout.read(4096)
-            if not chunk:
-                return
-            out.write(chunk)
-            out.flush()
-    except asyncio.CancelledError:
-        pass
-
-
-def main() -> None:
-    """Multi-subcommand entrypoint: `vds-telegram-shim claude ...` / `... acp ...`."""
-    app()
-
-
-def main_claude() -> None:
-    """Direct entrypoint for `vds-cli claude ...` — single command, no `claude` prefix.
-
-    The router invokes this via `vds-telegram-claude <args>` so the user's
-    args land directly on `cmd_claude`'s parameters. Avoids forcing the user
-    to type `vds-cli claude claude` (the multi-subcommand `app` would).
-    """
-    typer.run(cmd_claude)
-
-
-def main_acp() -> None:
-    """Direct entrypoint for `vds-cli acp <agent> ...`."""
-    typer.run(cmd_acp)
-
-
-if __name__ == "__main__":
-    main()

package/tools/vds-scripts/telegram_bridge/skill_content/QUALITY.md

@@ -1,47 +0,0 @@
-# Quality Baseline — telegram-bridge-skill
-
-## Version History
-
-| Version | Date | Score | Evaluator | Notes |
-|---------|------|-------|-----------|-------|
-| 1.0.0 | 2026-04-26 | TBD | Automated | AgentSkills compliance baseline established at spec v1.0.6 |
-
-## Evaluation Criteria
-
-This skill is evaluated on the standard AgentSkills rubric:
-
-1. **Frontmatter completeness** — `name`, `description`, `license`, `metadata.version`,
-   `metadata.category`, `metadata.author` all present in `SKILL.md`.
-2. **Reference coverage** — at minimum: `setup.md`, `commands.md`, `agent-onboarding.md`,
-   `audit-queries.md`, `architecture.md`, `troubleshooting.md`. Wave 0 evidence document
-   (`wave-0-spike-results.md`) included as operator artifact.
-3. **Bridge-contract clarity** — coding agents receiving this skill MUST learn the
-   audit-write-before-side-effect invariant, the topic-promotion rules, the
-   1 Hz streaming cadence, and the file-detection conventions.
-4. **Hard-rule enumeration** — load-bearing invariants explicit in `## Hard rules`.
-5. **Out-of-scope discipline** — v2-deferred items listed so agents don't propose them.
-
-## Coverage Surface
-
-This skill teaches agents:
-
-- How to drive Claude / Codex / generic ACP agents from a Telegram supergroup.
-- The bridge contract for emitted output (HTML escaping, code-block formatting,
-  fenced-block spill thresholds, subagent-promotion semantics).
-- How user-uploaded files reach the agent (Claude in-process MCP vs ACP `resource_link`).
-- Where to look for setup, commands, audit queries, troubleshooting.
-
-## Out-of-Scope
-
-This skill does NOT teach:
-
-- Daemon implementation details (those live in `telegram_bridge/`, not the skill).
-- Postgres schema (covered in `audit-queries.md` only as far as needed for
-  forensic lookups).
-- Container deployment beyond the one-line `COMPOSE_PROFILES=...` invocation.
-
-## Sync Provenance
-
-Source of truth: `WHO-project/vds-scripts/telegram_bridge/skill_content/`.
-Sync target: `WHO-project/vds-skills/skills/telegram-bridge-skill/`.
-Sync command: `vds-cli skills sync --agent claude` (post-merge).

package/tools/vds-scripts/telegram_bridge/skill_content/SKILL.md

@@ -1,99 +0,0 @@
----
-name: telegram-bridge-skill
-description: Drive any ACP-capable coding agent (Claude Code, Codex, Cursor, Cline, Droid, Kimi-CLI, Pi, Goose, Amp, Kiro) from a personal Telegram supergroup. Forum topics map to sessions; full bidirectional input from terminal AND phone; Postgres-backed audit log as the sole accountability mechanism (audit-only safety per ADR-5).
-license: Apache-2.0
-metadata:
-  version: "1.0.15"
-  category: "infrastructure"
-  author: "VDS Platform Team"
----
-
-# Telegram Bridge Skill
-
-VDS Telegram Bridge: a personal Telegram supergroup is a co-equal control surface to terminal and IDE for any ACP-capable coding agent.
-
-## When to use
-
-- The user wants to drive a coding agent from Telegram (`/spawn claude /repo`, then keep typing).
-- A long-running agent task should report progress / completion to Telegram.
-- The user wants to hand off a session between desk and phone — start in terminal, continue from Telegram, switch back.
-- The user wants `/audit` queries against the Postgres-backed event log.
-
-## Quick reference
-
-```bash
-# Start the daemon (Compose, opt-in via the `telegram` profile):
-COMPOSE_PROFILES=dev,mem0,telegram docker compose -f docker/docker-compose.services.yml \
-                                                  -f telegram_bridge/docker-compose.telegram.yml \
-                                                  up -d vds-telegram-daemon
-
-# Health-check (also called by the Compose healthcheck):
-./scripts/worktree_uv.sh run --project vds_cli vds-cli telegram status --ci
-
-# Drive Claude from terminal (next-session: shim wraps `vds-cli claude`):
-./scripts/worktree_uv.sh run --project telegram_bridge python -m telegram_bridge.daemon
-```
-
-## Required setup (one-time)
-
-1. Create a private Telegram supergroup with **forum topics** enabled.
-2. Promote the bot to admin with these permissions (categorised by reason):
-   - `can_manage_topics` (hard-required — `createForumTopic` rejects without it)
-   - `can_post_messages`, `can_edit_messages`, `can_delete_messages`, `can_change_info` (UX-required)
-   - NOT requested: `can_pin_messages`, `can_invite_users`
-3. Set in `~/.vds/.env`:
-   ```
-   TELEGRAM_BOT_TOKEN=<from @BotFather>
-   VDS_TELEGRAM_USER_ID=<your Telegram user-id>
-   ANTHROPIC_API_KEY=<for Claude>
-   OPENAI_API_KEY=<for Codex>
-   ```
-4. Send `/start` to the bot in the supergroup. The daemon registers the supergroup_id once and pins to it.
-
-Full setup walk-through: `references/setup.md`.
-
-## Architecture (1-paragraph)
-
-A daemon (`vds-telegram-daemon`) hosts an aiogram v3 bot polling Telegram. Per session, a runner subprocess wraps the agent: `claude-sdk-runner` for Claude (via `ClaudeSDKClient` + the hooks matrix per ADR-10), or the generic `acp-runner` for any other ACP-native agent (Codex, Cursor, Cline, Droid, Kimi-CLI, Pi, Goose, Amp, Kiro). Daemon ↔ runner uses a per-session UDS at `/run/vds-telegram/runners/<sid>.sock`; the daemon owns the only writer (FR-5.1) so concurrent input from Telegram and terminal serialises via a per-session `asyncio.Lock`. Every event is INSERT-committed to Postgres BEFORE the side effect runs (FR-7.5, the load-bearing audit invariant). Long-running subagent spawns get their own forum topic after 30s, on subscription, or on explicit `Task` invocation. Diagram + responsibility split: `references/architecture.md`.
-
-## Bridge contract for agents
-
-When the agent emits output that lands in a Telegram topic, formatting matters:
-
-- **Plain text** is HTML-escaped and rendered in the streaming message buffer (1 Hz edit coalesce; max 4096 chars per message).
-- **Code blocks** must use the nested form ` ```language ... ``` ` — the runner translates these to `<pre><code class="language-X">…</code></pre>`. Standalone `<code class="…">` is silently dropped by Telegram (round-5 finding).
-- **Long code blocks** (>3800 chars or >50-line diffs) auto-spill to a `sendDocument` attachment.
-- **`Write`-tool invocations that create new files** auto-spill the file content as a Document.
-- **Subagent spawns** running >30 s get their own forum topic; the parent topic gets a one-line "⤷ promoted to topic …" announcement, and on subagent end a "✅ subagent finished in N s" summary cross-posts to the parent.
-
-## Files-in (user uploads to a topic)
-
-When the user uploads a Document/Photo/Audio/Video into a topic, the daemon hashes it (SHA-256), dedupes into `vds_telegram_audit_blobs`, and:
-
-- For **Claude**: registers a per-session in-process MCP tool `read_telegram_upload(sha256)` → bytes. The user prompt sees only `{file_name, sha256, mime, size}`; the agent decides when to `read_telegram_upload(<sha>)` for the bytes.
-- For **ACP agents**: the next `session/prompt` includes a `resource_link`-typed content block with URI `vds-telegram://upload/<sha256>` plus `name`, `size`, `mimeType`. Agents resolve via the in-process MCP server.
-
-20 MB inbound cap (Bot API `getFile`); files > cap are rejected with a topic message pointing at self-hosted Bot API as the lift.
-
-## Tasks-where-to-look guide (this skill is loaded BEFORE running these)
-
-- **Add a new ACP agent**: `references/agent-onboarding.md`
-- **Set up the bot for the first time**: `references/setup.md`
-- **Look up `/commands`**: `references/commands.md`
-- **Run an audit-log query**: `references/audit-queries.md`
-- **Diagnose runner crash / orphaned topic / advisory-lock-held**: `references/troubleshooting.md`
-- **Architecture deep-dive**: `references/architecture.md`
-
-## Hard rules
-
-1. **One bot = one supergroup, ever.** PID-lock at `/run/vds-telegram/daemon.pid` enforces one container.
-2. **Audit-write before side effect.** Every event is Postgres-INSERT-committed before its consequences run. The `vds_telegram_audit_immutable` trigger forbids UPDATE/DELETE on event rows.
-3. **No tool approvals in v1.** All tool calls auto-approve; the audit log is the sole accountability mechanism (ADR-5).
-4. **Sensitive `:ro` overrides for ${HOME}**: `~/.vds`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config/gh` mounted read-only ahead of the broad HOME mount (NFR-5.5).
-5. **Container restart is destructive** in v1: `docker compose restart vds-telegram-daemon` kills runners; only same-container daemon-process restart preserves them (FR-1.3).
-
-## Out of scope (deferred to v2+)
-
-Voice input · Multi-tenant · Public groups/channels · Tool-approval policies / 2FA · KMS-redaction (pattern-redaction is in v1) · Self-hosted Bot API · IDE extension · Cross-agent routing · Scheduler · Reverse-tunnel deployments · Slack/Discord mirrors · Group chats outside the personal supergroup.
-
-Each deferred item has a v1-side hook documented in the spec's "Out of Scope" table.

package/tools/vds-scripts/telegram_bridge/skill_content/references/CHANGELOG.md

@@ -1,47 +0,0 @@
-# Telegram Bridge — Operator Changelog
-
-Operator-visible changes only. Spec changelog (full detail): `.gpt-5.4/specs/telegram-bridge/`.
-
----
-
-## v1.0.15 (2026-04-26)
-- 4-teammate parallel implementation pass; GitHub Actions CI workflow added; ACP SDK import collision fixed (`agent-client-protocol` vs `acp` PyPI name clash).
-
-## v1.0.14
-- Three-tier verification plan documented; `scripts/verify-tier1.sh` added for offline/CI tier-1 checks.
-
-## v1.0.13
-- Master alignment pass; shim + runner lifecycle wiring completed.
-
-## v1.0.12
-- Unit tests added for `session_store` and `vds-cli telegram/claude/acp` subcommands.
-
-## v1.0.11
-- `pyarrow>=16.0` added as runtime dependency; fixes `ModuleNotFoundError` on cold installs.
-
-## v1.0.10
-- AC-1.13 75% unit-test coverage gate passes.
-
-## v1.0.9
-- Unit tests added for `bot_gateway` and `dispatcher` modules.
-
-## v1.0.8
-- 3-auditor spec alignment pass; doc drift between spec and implementation resolved.
-
-## v1.0.7
-- Coverage tooling wired; spec audit-trail hygiene (version bumps enforced).
-
-## v1.0.6
-- `vds-cli telegram`, `vds-cli claude`, `vds-cli acp` wired into master router (`vds-cli`).
-
-## v1.0.5
-- FR-9.10: `last_processed_update_id` persisted to `vds_telegram_polling_state`; daemon restart now resumes from saved offset without replay. Healthcheck updated to call `vds-telegram` (container-local) instead of `vds-cli`.
-
-## v1.0.4
-- Soft-cap LRU eviction for `/sessions` list overflow protection; session count bounded at runtime.
-
-## v1.0.3
-- Full 27-AC scaffold matrix implemented across all acceptance criteria.
-
-## v1.0.0 – v1.0.2
-- Initial implementation: Wave 1 (daemon + bot gateway), Wave 2 (claude-sdk-runner + acp-runner), Wave 3 (Postgres audit log + Compose stack).

package/tools/vds-scripts/telegram_bridge/skill_content/references/agent-onboarding.md

@@ -1,84 +0,0 @@
-# Adding a new ACP agent
-
-Almost zero code: register the agent in `registry.yaml`, run the conformance smoke, graduate to `stable`. The generic `acp-runner` handles every ACP-native agent without per-agent Python.
-
-## 1. Add a `registry.yaml` entry
-
-```yaml
-agents:
-  my-new-agent:
-    runner: acp-runner            # use claude-sdk-runner only for Claude;
-                                   # codex-runner only for Codex (thin
-                                   # wrapper); everything else uses
-                                   # the generic acp-runner.
-    command: [my-agent-cli, --acp]   # the command the runner will spawn
-    icon: yellow                  # one of: blue/yellow/purple/green/pink/red
-    support_level: experimental   # NEW agents start as experimental; promote
-                                   # to `stable` after the conformance smoke
-                                   # below passes.
-    requires_env: [MY_AGENT_API_KEY]   # any env vars the agent needs
-```
-
-Six valid icon colors (round-5 — gray was a blog-cited mistake): `blue=0x6FB9F0`, `yellow=0xFFD67E`, `purple=0xCB86DB`, `green=0x8EEE98`, `pink=0xFF93B2`, `red=0xFB6F5F`.
-
-## 2. Run the conformance smoke
-
-The Wave-0 generic ACP smoke fixture is at
-`telegram_bridge/tests/spikes/test_0_8_generic_acp_smoke.py`. It runs against
-every agent listed in the `experimental` set; new entries you add to
-`registry.yaml` are picked up automatically by the parametrised fixture (no
-new test file needed).
-
-Run:
-
-```bash
-# Live run requires the agent binary on PATH and live-spike opt-in:
-VDS_TELEGRAM_SPIKE_LIVE=1 \
-  pytest telegram_bridge/tests/spikes/test_0_8_generic_acp_smoke.py -v -k my_new_agent
-```
-
-Without `VDS_TELEGRAM_SPIKE_LIVE=1` the spike is skipped — the spec marks
-all Wave-0 spikes as operator-driven (real subprocess + real ACP server).
-
-The fixture verifies:
-
-1. The agent binary starts and binds an ACP stdio.
-2. `initialize` handshake succeeds with our `client_capabilities`.
-3. `session/new` returns a session id.
-4. `session/prompt` streams `agent_message_chunk` events.
-5. `session/request_permission` round-trip works.
-6. `session/cancel` is fire-and-forget (no awaitable response — cancellation arrives as the eventual `prompt` resolution with `stop_reason="cancelled"`).
-7. `loadSession` capability negotiation degrades gracefully if the agent doesn't support it.
-8. Process exit on EOF is clean.
-
-## 3. Graduate to `stable`
-
-If all 8 checks pass, edit `registry.yaml`:
-
-```yaml
-agents:
-  my-new-agent:
-    support_level: stable
-```
-
-Commit + sync:
-
-```bash
-git add telegram_bridge/registry.yaml
-git commit -m "feat(telegram-bridge): graduate my-new-agent to stable"
-```
-
-After graduation, `/spawn my-new-agent` works without the experimental warning prefix.
-
-## When the smoke fails
-
-Capture the failing step + ACP wire trace and file it under `references/wave-0-spike-results.md`. Common failure modes:
-
-- **`initialize` rejects `loadSession=true`** — the agent doesn't support resume. Set `loadSession: False` in our client_capabilities for that agent and degrade.
-- **`session/prompt` returns immediately with no events** — agent expects different `content_blocks` shape. Check the agent's docs for `content` vs `contentBlocks` casing.
-- **`session/request_permission` hangs** — agent expects the doubly-nested envelope `{"outcome": {"outcome": "selected", "optionId": "approve"}}`; check our v1 always-grant impl.
-- **stdio framing errors** — likely hitting SDK issue #62 (`LimitOverrunError` on >64KB lines). Confirm `stdio_buffer_limit_bytes=200*1024*1024` is in effect.
-
-## Notes for non-ACP agents
-
-If an agent doesn't speak ACP yet (e.g. the Pi consumer chatbot — distinct from `pi-mono` which has `pi-acp`), don't add an entry. Wait for the agent to ship ACP, OR write a custom runner subclass that wraps the agent's native protocol and emits the same OutboundFrame types via `Runner.emit()`.