cloudagent-daemon 0.4.1__tar.gz → 0.5.0__tar.gz

cloudagent_daemon-0.5.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog — cloudagent-daemon
+
+All notable changes to the local daemon. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versions are
+[PEP 440](https://peps.python.org/pep-0440/). Release with `scripts/release.sh`.
+
+## [0.5.0] — 2026-08-19
+
+First release since 0.4.1 (2026-07-22). Everything below shipped to internal
+hosts from source; this is the first time it reaches the PyPI package.
+
+### Added
+- **No-source installation and release tooling** (#96): a repeatable,
+  fail-closed PyPI release script, end-user installation guide, and
+  `cloudagent-daemon --version` / `-V` for verifying installed builds.
+- **Qoder CLI runtime engine** (`runtime_engine=qoder`, #86/#87): `qodercli`
+  auto-detected, headless spawn via `-p --output-format stream-json`, model
+  and reasoning-effort passthrough, login probe in the periodic health loop.
+  `cloudagent-daemon setup-qoder-token` stores the Personal Access Token in
+  the macOS login Keychain (Linux: 0600 file) and injects it only into the
+  Qoder child process — never argv / plist / config / logs.
+- **Login-session install** (#25): `cloudagent-daemon install-service` now
+  installs the daemon as a `gui/$UID` LaunchAgent (macOS) / user systemd unit
+  (Linux) so spawned CLIs can read the login keychain; boot-time auth
+  pre-flight logs an actionable remedy instead of a silent crash loop.
+- **Periodic auth health → heartbeat** (#53): every 5 min the daemon probes
+  CLI login state and uplinks `runtime_health` with the heartbeat; the
+  backend refuses to dispatch to an agent whose runtime is logged out
+  (`STAFF_UNAVAILABLE`) instead of crash-quarantining it.
+- **Attachments reach agents** (#48): `download_attachment` MCP tool + wake
+  body `【附件】` block; agents can fetch and read images/files shared in chat.
+- **Real reminders** (#49): `schedule_reminder` / `list_reminders` /
+  `cancel_reminder` MCP tools (one-shot and cron, 5-minute floor) that truly
+  re-wake the agent.
+- Per-agent runtime config at creation (model, reasoning effort, runtime
+  env) threaded through assign/identity to the spawn (#22).
+- `acknowledge_new_messages` forwarded on `platform_send` (#28).
+
+### Fixed
+- **Qoder per-conversation session lanes** (#95): Qoder runtime sessions are
+  keyed by `conversation_id` so DM/#channel wakes never resume each other's
+  session; the per-channel system prompt (#88) is carried in the stdin
+  preamble every turn (qodercli `--resume` did not reliably adopt a new
+  `--append-system-prompt`).
+- An `ack` POST failure could swallow a deliver's spawn (message lost until
+  the 120-min watchdog); ack and spawn are now independently contained.
+- `mcp` pinned `>=1.9,<2` — mcp 2.x removed FastMCP and broke a fresh
+  `uv tool install` (#28).
+- Agent working state no longer flickers idle while conversations are queued.
+
+### Changed
+- Runtime engines advertised to the backend: `claude_code`, `codex`, `qoder`.
+- Qoder `read_analyze` (read-only) wakes are refused (fail-closed) until the
+  tool-restriction flags are verified on a real login.
+
+## [0.4.1] — 2026-07-22
+### Fixed
+- Runtime detection: a probe that exits non-zero is reported as version
+  `unknown` instead of parsing its error text as a version (a broken nvm
+  shim no longer outranks a working install).
+
+## [0.4.0] — 2026-07
+- Multi-runtime detection across PATH + well-known dirs, newest version wins.
+- Daemon profiles, SSE+POST transport default, spawn outbox / watchdog.
+
+## [0.3.x] — 2026-05/06
+- M7 W3: local-agent context injection, delegation token/status uplink.
+- Token-level streaming of replies, per-agent `workspace_root`.
+
+## [0.2.x] — 2026-05
+- Initial public releases: spawn-on-message daemon, embedded MCP bridge.

{cloudagent_daemon-0.4.1 → cloudagent_daemon-0.5.0}/PKG-INFO

@@ -1,14 +1,14 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cloudagent-daemon
-Version: 0.4.1
-Summary: Local daemon for cloudagent — bridges Claude Code subprocesses to the cloudagent backend over WebSocket.
+Version: 0.5.0
+Summary: Local daemon for cloudagent — bridges Claude Code, Codex, and Qoder CLI agents to the cloudagent backend.
 Project-URL: Homepage, https://cloudagent.chat
 Project-URL: Repository, https://codeup.aliyun.com/69bd0a4d29ad98af4065ce71/cloudagent
 Project-URL: Documentation, https://codeup.aliyun.com/69bd0a4d29ad98af4065ce71/cloudagent/docs/superpowers/specs
 Author-email: chaoyin <tudoucyx@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: ai-coding-agent,claude-code,cloudagent,daemon
+Keywords: ai-coding-agent,claude-code,cloudagent,codex,daemon,qoder
 Classifier: Development Status :: 4 - Beta
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
@@ -20,7 +20,7 @@ Requires-Python: >=3.12
 Requires-Dist: h2>=4
 Requires-Dist: httpx-sse>=0.4
 Requires-Dist: httpx>=0.27
-Requires-Dist: mcp>=0.9
+Requires-Dist: mcp<2,>=1.9
 Requires-Dist: pydantic>=2.7
 Requires-Dist: typer>=0.12
 Requires-Dist: websockets>=12
@@ -32,19 +32,23 @@ Description-Content-Type: text/markdown
 
 # cloudagent-daemon
 
-Local daemon for cloudagent — runs on user's machine, bridges Claude Code
-subprocesses to the cloudagent backend so that agents can work locally with
-your machine's filesystem and tools.
+Local daemon for cloudagent — runs on the user's machine and bridges AI coding
+CLIs (**Claude Code**, **Codex**, **Qoder CLI**) to the cloudagent backend so
+agents can work locally with your machine's filesystem and tools.
 
-**Architecture:** spawn-on-message model — daemon receives a `deliver` frame over
-WebSocket, spawns `claude --resume <session_id>`, claude uses an MCP server
-(also embedded in this daemon) to `send_message` / `list_messages` back to the
-backend, and exits when its work is done.
+**Architecture:** spawn-on-message — the daemon keeps an SSE stream to the
+backend, receives a `deliver` frame per wake, spawns the agent's CLI
+(`claude` / `codex` / `qodercli`, resuming that agent's session), and the CLI
+talks back through an MCP bridge embedded in this daemon (`platform_send`,
+`send_message`, `download_attachment`, reminders…) before exiting.
 
-## Quick start (no clone)
+## Quick start (no clone) — for end users
 
 Published to PyPI as [`cloudagent-daemon`](https://pypi.org/project/cloudagent-daemon/).
-Requires Python 3.12+ and Claude Code CLI on PATH.
+The repository also contains a step-by-step Chinese walkthrough at
+`docs/daemon-install-guide.md`. Requirements: Python 3.12+ (`uv` will fetch one if missing),
+[`uv`](https://docs.astral.sh/uv/), and at least one agent CLI on PATH and
+logged in — `claude` (Claude Code), `codex`, or `qodercli`.
 
 ```bash
 # One-shot run (no persistent install)
@@ -52,8 +56,10 @@ uvx cloudagent-daemon start --server-url https://api.cloudagent.chat --api-key s
 ```
 
 ```bash
-# Persistent install — install + start chained with && (single line)
-uv tool install cloudagent-daemon && cloudagent-daemon start --server-url https://api.cloudagent.chat --api-key sk_machine_***
+# Persistent install — save the machine identity, then install the service
+uv tool install cloudagent-daemon
+cloudagent-daemon login --server https://api.cloudagent.chat  # paste the key at the hidden prompt
+cloudagent-daemon install-service
 ```
 
 ```bash
@@ -61,10 +67,23 @@ uv tool install cloudagent-daemon && cloudagent-daemon start --server-url https:
 pipx install cloudagent-daemon
 ```
 
+`login` stores the machine identity in a mode-0600 local config file;
+`install-service` then starts a macOS `gui/$UID` LaunchAgent or Linux user
+systemd unit from that config. Do not substitute a one-shot `start
+--server-url ... --api-key ...` here: one-shot mode intentionally persists no
+credentials, so a later argument-free service would start unauthenticated.
+
+Qoder CLI agents need a Personal Access Token stored once per machine
+(Keychain on macOS, 0600 file on Linux; never written to plist/config/logs):
+
+```bash
+cloudagent-daemon setup-qoder-token
+```
+
 To upgrade later:
 
 ```bash
-uv tool upgrade cloudagent-daemon
+uv tool upgrade cloudagent-daemon && cloudagent-daemon install-service   # re-install picks up the new binary
 # or
 pipx upgrade cloudagent-daemon
 ```
@@ -133,6 +152,8 @@ cloudagent-daemon start \
 # Output:
 # Detected runtimes:
 #   ✓ claude_code 2.1.137  (/opt/homebrew/bin/claude)
+#   ✓ codex       0.145.0  (/opt/homebrew/bin/codex)
+#   ✓ qoder       1.1.25   (/Users/me/.local/bin/qodercli)
 # Connecting to https://api.cloudagent.chat as host host_01HXX...
 ```
 
@@ -168,6 +189,7 @@ no state behind. For persistent setups, use `login` once + `start` after.
 | `cloudagent-daemon stop` | Send SIGTERM, wait for clean exit |
 | `cloudagent-daemon install-service` | Install + start as launchd / systemd user service (auto-restart on crash, auto-start at login) |
 | `cloudagent-daemon uninstall-service` | Stop + remove the launchd / systemd service unit |
+| `cloudagent-daemon setup-qoder-token` | Store the Qoder CLI Personal Access Token securely (Keychain / 0600 file) for Qoder agents |
 | `cloudagent-daemon agent register --agent-id ID` | Create local workspace |
 | `cloudagent-daemon agent unregister --agent-id ID` | Archive workspace |
 
@@ -309,3 +331,19 @@ See `docs/superpowers/specs/2026-05-08-local-daemon-runtime-design.md`.
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Releasing (maintainers)
+
+```bash
+# 1. bump version in pyproject.toml AND src/cloudagent_daemon/__init__.py (must match)
+# 2. add a "## [x.y.z]" section to CHANGELOG.md
+# 3. commit, then:
+UV_PUBLISH_TOKEN=pypi-... scripts/release.sh        # or scripts/release.sh --dry-run
+git push cloudagent daemon-v<x.y.z>
+```
+
+The script refuses to publish on a dirty tree, a version/lockfile mismatch, a
+missing changelog entry, an ambiguous PyPI response, an existing version, or a
+conflicting tag. It runs the unit suite with a scrubbed environment, builds,
+and validates both distribution artifacts first. The token is read from the
+environment only — never commit it.

{cloudagent_daemon-0.4.1 → cloudagent_daemon-0.5.0}/README.md

@@ -1,18 +1,22 @@
 # cloudagent-daemon
 
-Local daemon for cloudagent — runs on user's machine, bridges Claude Code
-subprocesses to the cloudagent backend so that agents can work locally with
-your machine's filesystem and tools.
+Local daemon for cloudagent — runs on the user's machine and bridges AI coding
+CLIs (**Claude Code**, **Codex**, **Qoder CLI**) to the cloudagent backend so
+agents can work locally with your machine's filesystem and tools.
 
-**Architecture:** spawn-on-message model — daemon receives a `deliver` frame over
-WebSocket, spawns `claude --resume <session_id>`, claude uses an MCP server
-(also embedded in this daemon) to `send_message` / `list_messages` back to the
-backend, and exits when its work is done.
+**Architecture:** spawn-on-message — the daemon keeps an SSE stream to the
+backend, receives a `deliver` frame per wake, spawns the agent's CLI
+(`claude` / `codex` / `qodercli`, resuming that agent's session), and the CLI
+talks back through an MCP bridge embedded in this daemon (`platform_send`,
+`send_message`, `download_attachment`, reminders…) before exiting.
 
-## Quick start (no clone)
+## Quick start (no clone) — for end users
 
 Published to PyPI as [`cloudagent-daemon`](https://pypi.org/project/cloudagent-daemon/).
-Requires Python 3.12+ and Claude Code CLI on PATH.
+The repository also contains a step-by-step Chinese walkthrough at
+`docs/daemon-install-guide.md`. Requirements: Python 3.12+ (`uv` will fetch one if missing),
+[`uv`](https://docs.astral.sh/uv/), and at least one agent CLI on PATH and
+logged in — `claude` (Claude Code), `codex`, or `qodercli`.
 
 ```bash
 # One-shot run (no persistent install)
@@ -20,8 +24,10 @@ uvx cloudagent-daemon start --server-url https://api.cloudagent.chat --api-key s
 ```
 
 ```bash
-# Persistent install — install + start chained with && (single line)
-uv tool install cloudagent-daemon && cloudagent-daemon start --server-url https://api.cloudagent.chat --api-key sk_machine_***
+# Persistent install — save the machine identity, then install the service
+uv tool install cloudagent-daemon
+cloudagent-daemon login --server https://api.cloudagent.chat  # paste the key at the hidden prompt
+cloudagent-daemon install-service
 ```
 
 ```bash
@@ -29,10 +35,23 @@ uv tool install cloudagent-daemon && cloudagent-daemon start --server-url https:
 pipx install cloudagent-daemon
 ```
 
+`login` stores the machine identity in a mode-0600 local config file;
+`install-service` then starts a macOS `gui/$UID` LaunchAgent or Linux user
+systemd unit from that config. Do not substitute a one-shot `start
+--server-url ... --api-key ...` here: one-shot mode intentionally persists no
+credentials, so a later argument-free service would start unauthenticated.
+
+Qoder CLI agents need a Personal Access Token stored once per machine
+(Keychain on macOS, 0600 file on Linux; never written to plist/config/logs):
+
+```bash
+cloudagent-daemon setup-qoder-token
+```
+
 To upgrade later:
 
 ```bash
-uv tool upgrade cloudagent-daemon
+uv tool upgrade cloudagent-daemon && cloudagent-daemon install-service   # re-install picks up the new binary
 # or
 pipx upgrade cloudagent-daemon
 ```
@@ -101,6 +120,8 @@ cloudagent-daemon start \
 # Output:
 # Detected runtimes:
 #   ✓ claude_code 2.1.137  (/opt/homebrew/bin/claude)
+#   ✓ codex       0.145.0  (/opt/homebrew/bin/codex)
+#   ✓ qoder       1.1.25   (/Users/me/.local/bin/qodercli)
 # Connecting to https://api.cloudagent.chat as host host_01HXX...
 ```
 
@@ -136,6 +157,7 @@ no state behind. For persistent setups, use `login` once + `start` after.
 | `cloudagent-daemon stop` | Send SIGTERM, wait for clean exit |
 | `cloudagent-daemon install-service` | Install + start as launchd / systemd user service (auto-restart on crash, auto-start at login) |
 | `cloudagent-daemon uninstall-service` | Stop + remove the launchd / systemd service unit |
+| `cloudagent-daemon setup-qoder-token` | Store the Qoder CLI Personal Access Token securely (Keychain / 0600 file) for Qoder agents |
 | `cloudagent-daemon agent register --agent-id ID` | Create local workspace |
 | `cloudagent-daemon agent unregister --agent-id ID` | Archive workspace |
 
@@ -277,3 +299,19 @@ See `docs/superpowers/specs/2026-05-08-local-daemon-runtime-design.md`.
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Releasing (maintainers)
+
+```bash
+# 1. bump version in pyproject.toml AND src/cloudagent_daemon/__init__.py (must match)
+# 2. add a "## [x.y.z]" section to CHANGELOG.md
+# 3. commit, then:
+UV_PUBLISH_TOKEN=pypi-... scripts/release.sh        # or scripts/release.sh --dry-run
+git push cloudagent daemon-v<x.y.z>
+```
+
+The script refuses to publish on a dirty tree, a version/lockfile mismatch, a
+missing changelog entry, an ambiguous PyPI response, an existing version, or a
+conflicting tag. It runs the unit suite with a scrubbed environment, builds,
+and validates both distribution artifacts first. The token is read from the
+environment only — never commit it.

{cloudagent_daemon-0.4.1 → cloudagent_daemon-0.5.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cloudagent-daemon"
-version = "0.4.1"
-description = "Local daemon for cloudagent — bridges Claude Code subprocesses to the cloudagent backend over WebSocket."
+version = "0.5.0"
+description = "Local daemon for cloudagent — bridges Claude Code, Codex, and Qoder CLI agents to the cloudagent backend."
 authors = [{name = "chaoyin", email = "tudoucyx@gmail.com"}]
 readme = "README.md"
 license = "MIT"
-keywords = ["cloudagent", "claude-code", "daemon", "ai-coding-agent"]
+keywords = ["cloudagent", "claude-code", "codex", "qoder", "daemon", "ai-coding-agent"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Programming Language :: Python :: 3.12",
@@ -33,7 +33,12 @@ dependencies = [
     # ``:hb`` / deliver events flow as intended. Public endpoints are
     # unaffected (and h2 just downgrades to 1.1 if upstream rejects it).
     "h2>=4",
-    "mcp>=0.9",
+    # #28 — pin BELOW 2.0: the bridge imports ``mcp.server.fastmcp`` (FastMCP),
+    # which mcp 2.x removed/relocated. An unpinned ``mcp>=0.9`` let a fresh
+    # uv-tool install resolve mcp==2.0.0 → ``ModuleNotFoundError`` at
+    # mcp-bridge startup (Cris's tools dead until a manual downgrade). Keep it
+    # on the 1.x line that ships FastMCP.
+    "mcp>=1.9,<2",
 ]
 
 [project.urls]

cloudagent_daemon-0.5.0/scripts/release.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# cloudagent-daemon release — repeatable PyPI publish (#96).
+#
+# Usage:
+#   UV_PUBLISH_TOKEN=pypi-xxx scripts/release.sh            # build + test + publish
+#   scripts/release.sh --dry-run                            # everything except upload
+#   scripts/release.sh --skip-tests                         # (not recommended)
+#
+# What it enforces, in order:
+#   1. clean git tree inside daemon_cli/ (no half-committed release)
+#   2. pyproject.toml version == cloudagent_daemon.__version__
+#   3. uv.lock is current and CHANGELOG.md has a section for that version
+#   4. PyPI is reachable and the version is not already published
+#   5. the release tag, if already present, points at the current commit
+#   6. unit tests pass (set CLOUDAGENT_DAEMON_PROFILE unset — host env pollution
+#      is the known cause of the sandbox-only failures; we run with a scrubbed env)
+#   7. uv build (sdist + wheel) into a fresh dist/ and validate both artifacts
+#   8. uv publish (token from UV_PUBLISH_TOKEN; never stored in the repo)
+#   9. git tag daemon-v<version> (local; push is left to the operator)
+set -euo pipefail
+
+DRY_RUN=0
+SKIP_TESTS=0
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    --skip-tests) SKIP_TESTS=1 ;;
+    -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+    *) echo "unknown arg: $arg" >&2; exit 2 ;;
+  esac
+done
+
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$HERE"
+
+command -v uv >/dev/null || { echo "uv not found — install: curl -LsSf https://astral.sh/uv/install.sh | sh" >&2; exit 1; }
+
+# 1. clean tree (daemon_cli only — the monorepo may have unrelated WIP)
+if [ -n "$(git status --porcelain -- . )" ]; then
+  echo "refusing to release with uncommitted changes under daemon_cli/:" >&2
+  git status --short -- . >&2
+  exit 1
+fi
+
+# 2. version consistency
+PYPROJECT_VER="$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -1)"
+INIT_VER="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/cloudagent_daemon/__init__.py | head -1)"
+if [ -z "$PYPROJECT_VER" ] || [ "$PYPROJECT_VER" != "$INIT_VER" ]; then
+  echo "version mismatch: pyproject=$PYPROJECT_VER __init__=$INIT_VER" >&2
+  exit 1
+fi
+VER="$PYPROJECT_VER"
+TAG="daemon-v$VER"
+echo "== releasing cloudagent-daemon $VER"
+
+# 3. lockfile current + changelog section present.  A version bump changes the
+# editable root package entry in uv.lock; without this check `uv run` below
+# silently rewrites the tracked lockfile after the one-time clean-tree check.
+if ! uv lock --check; then
+  echo "uv.lock is stale — run 'uv lock' and commit the result before releasing" >&2
+  exit 1
+fi
+if ! grep -q "^## \[$VER\]" CHANGELOG.md; then
+  echo "CHANGELOG.md has no '## [$VER]' section — write the release notes first" >&2
+  exit 1
+fi
+
+# 4. PyPI reachable + version absent.  Only an explicit 404 means it is safe
+# to continue; DNS/TLS/timeouts/5xx must fail closed rather than being mistaken
+# for "version does not exist".
+if ! PYPI_STATUS="$(curl -sS -m 15 -o /dev/null -w '%{http_code}' \
+  "https://pypi.org/pypi/cloudagent-daemon/$VER/json")"; then
+  echo "could not verify cloudagent-daemon $VER on PyPI — refusing to publish" >&2
+  exit 1
+fi
+case "$PYPI_STATUS" in
+  200)
+    echo "cloudagent-daemon $VER already exists on PyPI — bump the version" >&2
+    exit 1
+    ;;
+  404) ;;
+  *)
+    echo "PyPI version check returned HTTP $PYPI_STATUS — refusing to publish" >&2
+    exit 1
+    ;;
+esac
+
+# 5. Never publish a commit whose release tag names a different commit.  An
+# existing same-commit tag is allowed so a failed upload can be retried safely.
+if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+  if [ "$(git rev-list -n 1 "$TAG")" != "$(git rev-parse HEAD)" ]; then
+    echo "$TAG already exists but does not point at HEAD — refusing to publish" >&2
+    exit 1
+  fi
+  echo "== existing release tag $TAG already points at HEAD"
+fi
+
+# 6. tests (scrubbed env: profile/server vars from the operator's shell must not leak)
+if [ "$SKIP_TESTS" = "0" ]; then
+  echo "== unit tests"
+  env -u CLOUDAGENT_DAEMON_PROFILE -u CLOUDAGENT_SERVER_URL -u CLOUDAGENT_API_KEY \
+    uv run --extra dev python -m pytest tests/unit -q -x -p no:cacheprovider
+fi
+
+# 7. build + metadata validation
+echo "== build"
+rm -rf dist
+uv build
+ls -l dist/
+uvx --from twine twine check dist/*
+
+# 8. publish
+if [ "$DRY_RUN" = "1" ]; then
+  echo "== dry-run: skipping upload. Artifacts in dist/ — inspect with:"
+  echo "   uv run --with twine twine check dist/*"
+  exit 0
+fi
+: "${UV_PUBLISH_TOKEN:?set UV_PUBLISH_TOKEN=pypi-... (project-scoped token recommended; never commit it)}"
+echo "== publish"
+uv publish dist/*
+
+# 9. tag.  Do not swallow tag failures after a successful upload.
+if ! git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+  git tag -a "$TAG" -m "cloudagent-daemon $VER"
+fi
+echo "== done: https://pypi.org/project/cloudagent-daemon/$VER/"
+echo "   push the tag: git push cloudagent $TAG"
+echo "   verify fresh install: uvx --refresh cloudagent-daemon@$VER --version"

cloudagent_daemon-0.5.0/src/cloudagent_daemon/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

cloudagent_daemon-0.5.0/src/cloudagent_daemon/agent_download.py

@@ -0,0 +1,131 @@
+"""#48 — ``download_attachment``: fetch a platform attachment for a local agent.
+
+The read twin of ``agent_upload``. The agent (claude) calls the bridge tool
+with an ``attachment_id`` (from the wake body's 【附件】 block or a
+``platform_read`` message's ``attachments``); daemon-main pulls the bytes from
+``/v1/daemon/agent-file-download`` (machine-key auth; visibility enforced
+server-side by the shared #51 gate) and lands them under the agent's OWN cwd
+(``<cwd>/attachments/``) so the agent's Read tool can open the file — images
+render multimodally, so "拿到图片" means literally seeing the picture.
+
+Runs in daemon-main (like ``upload_file``): the backend dispatcher can't write
+Mac paths, and the bytes must NOT ride the JSON tool-result channel.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import unquote
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_PATH_AGENT_DOWNLOAD = "/v1/daemon/agent-file-download"
+
+# Windows-reserved + path-separator + control chars — enough to keep a hostile
+# server-supplied filename inside the attachments dir on macOS/Linux.
+_BAD_FILENAME_CHARS = re.compile(r"[\\/\0\r\n:*?\"<>|]")
+
+
+def _err(code: str, message: str) -> dict[str, Any]:
+    return {"ok": False, "error": {"code": code, "message": message}}
+
+
+def _filename_from_headers(headers: dict, fallback: str) -> str:
+    """RFC 5987 ``filename*=UTF-8''…`` first, then plain ``filename=…``."""
+    cd = ""
+    for k, v in headers.items():
+        if str(k).lower() == "content-disposition":
+            cd = str(v)
+            break
+    m = re.search(r"filename\*=UTF-8''([^;]+)", cd)
+    if m:
+        name = unquote(m.group(1))
+    else:
+        m = re.search(r'filename="?([^";]+)"?', cd)
+        name = m.group(1) if m else fallback
+    # basename + character sanitation: never let a server-supplied name escape
+    # the attachments dir or smuggle separators.
+    name = name.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+    name = _BAD_FILENAME_CHARS.sub("_", name).strip().strip(".")
+    return name or fallback
+
+
+async def handle_download_attachment(
+    http: Any,
+    workspace: Any,
+    *,
+    agent_id: str,
+    session_id: str | None,
+    args: dict[str, Any],
+) -> dict[str, Any]:
+    """Download ``args['attachment_id']`` into the agent's cwd; return the path."""
+    att_id = str(args.get("attachment_id") or "").strip()
+    if not att_id:
+        return _err("INVALID_ARGS", "attachment_id is required")
+
+    try:
+        data, headers = await http.get_bytes(
+            _PATH_AGENT_DOWNLOAD,
+            params={"agent_id": agent_id, "attachment_id": att_id},
+        )
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        if status == 404:
+            return _err(
+                "NOT_FOUND",
+                "attachment not found or not visible to this agent "
+                "(需要你是该会话的成员，且消息未被删除)",
+            )
+        logger.warning(
+            "agent_download: backend %d for att=%s agent=%s",
+            status, att_id, agent_id,
+        )
+        return _err("DOWNLOAD_FAILED", f"backend returned HTTP {status}")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "agent_download: fetch failed att=%s: %s", att_id, exc, exc_info=True
+        )
+        return _err("DOWNLOAD_FAILED", f"download failed: {type(exc).__name__}")
+
+    if not data:
+        return _err("EMPTY_FILE", "attachment has no bytes")
+
+    filename = _filename_from_headers(headers, fallback=att_id)
+    mime = ""
+    for k, v in headers.items():
+        if str(k).lower() == "content-type":
+            mime = str(v)
+            break
+
+    try:
+        dest_dir = workspace.for_agent(agent_id).cwd / "attachments"
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dest = dest_dir / filename
+        if dest.exists():
+            # Same name ≠ same file — prefix with the (unique) attachment id.
+            dest = dest_dir / f"{att_id[-8:]}-{filename}"
+        dest.write_bytes(data)
+    except OSError as exc:
+        logger.warning("agent_download: write failed att=%s: %s", att_id, exc)
+        return _err("WRITE_FAILED", f"could not write file: {exc}")
+
+    logger.info(
+        "agent_download: saved att=%s agent=%s → %s (%d bytes)",
+        att_id, agent_id, dest, len(data),
+    )
+    return {
+        "ok": True,
+        "data": {
+            "local_path": str(dest),
+            "filename": filename,
+            "mime_type": mime or "application/octet-stream",
+            "size_bytes": len(data),
+            "hint": "用 Read 工具打开 local_path 查看内容（图片可直接看到画面）",
+        },
+    }
+
+
+__all__ = ["handle_download_attachment"]