deepagents-talon 0.0.1__tar.gz

deepagents_talon-0.0.1/.gitignore

@@ -0,0 +1,252 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!libs/cli/frontend/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.*
+.envrc
+env.local
+*.env.local
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Local credentials and secrets
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+*.jks
+credentials.json
+token.json
+Cookies
+Cookies.db
+cookies.sqlite
+cookies.txt
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# LangGraph
+.langgraph_api
+
+#claude
+.claude
+
+# Harbor local job output
+jobs/
+
+.idea
+TEXTUAL_REFACTOR_PLAN.md
+libs/cli/TEXTUAL_PROGRESS.md
+
+/tmp/
+
+# macOS
+.DS_Store
+*/tmp/.DS_Store
+
+CLAUDE.md
+.worktrees/
+
+# Frontend build artifacts (source tree; package data under libs/cli/deepagents_cli/deploy/frontend_dist/ is tracked)
+libs/cli/frontend/node_modules/
+libs/cli/frontend/dist/
+node_modules/

deepagents_talon-0.0.1/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.

deepagents_talon-0.0.1/Makefile

@@ -0,0 +1,41 @@
+.PHONY: lint format type typecheck test tests test_watch help
+
+.DEFAULT_GOAL := help
+
+.EXPORT_ALL_VARIABLES:
+UV_FROZEN = true
+
+TEST_FILE ?= tests/
+PYTEST_EXTRA ?=
+
+test: ## Run unit tests
+test tests:
+	uv run --group test pytest --disable-socket --allow-unix-socket $(PYTEST_EXTRA) $(TEST_FILE) \
+		--timeout 10 --cov=deepagents_talon --cov-report=term-missing
+
+test_watch: ## Run tests in watch mode
+	uv run --group test ptw . -- $(TEST_FILE)
+
+lint format: PYTHON_FILES=deepagents_talon/ tests/
+lint_diff format_diff: PYTHON_FILES=$(shell git diff --relative=libs/talon --name-only --diff-filter=d main | grep -E '\.py$$|\.ipynb$$')
+
+lint: ## Run linters and type checker
+lint lint_diff:
+	[ "$(PYTHON_FILES)" = "" ] || uv run --group test ruff check $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run --group test ruff format $(PYTHON_FILES) --diff
+	$(MAKE) type
+
+type: ## Run type checker
+type typecheck:
+	uv run --group test ty check deepagents_talon
+
+format: ## Run code formatters
+format format_diff:
+	[ "$(PYTHON_FILES)" = "" ] || uv run --group test ruff format $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run --group test ruff check --fix $(PYTHON_FILES)
+
+help: ## Show this help message
+	@echo "Usage: make [target] [TEST_FILE=path/to/tests/]"
+	@echo ""
+	@echo "Targets:"
+	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z_-]+:.*##/ {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

deepagents_talon-0.0.1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: deepagents-talon
+Version: 0.0.1
+Summary: Local runtime host for long-running Deep Agents channels and schedules (experimental)
+Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview
+Project-URL: Documentation, https://reference.langchain.com/python/deepagents/
+Project-URL: Repository, https://github.com/langchain-ai/deepagents
+Project-URL: Issues, https://github.com/langchain-ai/deepagents/issues
+License: MIT
+Keywords: agents,ai,channels,deepagents,runtime,scheduling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: deepagents-code<1.0.0,>=0.1.11
+Requires-Dist: deepagents<0.7.0,>=0.6.8
+Requires-Dist: fleet-deepagents-export<1.0.0,>=0.0.1
+Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.2.2
+Provides-Extra: speech
+Requires-Dist: librosa<1.0.0,>=0.11.0; extra == 'speech'
+Requires-Dist: numpy<3.0.0,>=2.4.6; extra == 'speech'
+Requires-Dist: phonemizer<4.0.0,>=3.3.0; extra == 'speech'
+Requires-Dist: torch<2.13.0,>=2.12.0; extra == 'speech'
+Requires-Dist: torchaudio<2.12.0,>=2.11.0; extra == 'speech'
+Requires-Dist: transformers<6.0.0,>=5.10.2; extra == 'speech'
+Description-Content-Type: text/markdown
+
+# Deep Agents Talon
+
+Deep Agents Talon is the local runtime host for long-running Deep Agents. It owns the process lifecycle for channel adapters, cron schedulers, and the agent runtime in a single event loop.
+
+> **Experimental:** Talon is an experimental runtime and is subject to change or removal at any time.
+
+Talon currently includes:
+
+- A host process with graceful shutdown, per-conversation serialization, and `/stop` cancellation.
+- A generic channel protocol plus a WhatsApp adapter backed by a loopback Node bridge.
+- A persistent cron scheduler with agent-facing cron tool helpers.
+- MCP tool loading from the assistant manifest directory.
+- Optional LangSmith tracing for each channel or cron-triggered run.
+
+## Quickstart
+
+```bash
+uv sync --group test
+AGENT_ASSISTANT_ID=local AGENT_MODEL=openai:gpt-5.2 uv run deepagents-talon --once
+```
+
+If `AGENT_MODEL` is unset, Talon starts with the echo runtime. This is useful for checking host lifecycle and channel wiring without provider credentials.
+
+Assistant state lives under `~/.deepagents/<assistant_id>/` by default. The host creates restrictive state directories for the materialized agent manifest, channel sessions, and cron jobs. The default local execution workspace is `/workspace`; set `DEEPAGENTS_TALON_WORKSPACE` to use a different directory.
+
+## Fleet Exports
+
+Talon can host an operator-unzipped LangSmith Fleet export through the `fleet-deepagents-export` library:
+
+```bash
+unzip path/to/fleet-export.zip -d ./fleet
+
+DEEPAGENTS_TALON_FLEET_DIR=./fleet \
+AGENT_ASSISTANT_ID=fleet-local \
+uv run deepagents-talon --once
+```
+
+In Fleet mode, Talon uses the model from `fleet/config.json` unless `DEEPAGENTS_TALON_MODEL` or `AGENT_MODEL` is set. The Fleet loader resolves MCP registry references through LangSmith, so provide the required `LANGSMITH_API_KEY`, `LANGSMITH_TENANT_ID`, `LANGSMITH_ORGANIZATION_ID`, and when needed `LANGSMITH_USER_ID`, `BUILTIN_MCP_URL`, `LANGSMITH_HOST_URL`, and `HOST_LANGCHAIN_API_URL`. Locally-authored agents without `DEEPAGENTS_TALON_FLEET_DIR` continue to load from the assistant manifest directory and Talon's plain MCP config discovery.
+
+OAuth-backed Fleet MCP tools must be authorized once from an interactive shell before starting a headless host. Run the host in `--once` mode with the same Fleet directory and LangSmith environment you will use in production, complete the browser authorization if prompted, then start the long-running host:
+
+```bash
+DEEPAGENTS_TALON_FLEET_DIR=./fleet \
+AGENT_ASSISTANT_ID=fleet-local \
+uv run deepagents-talon --once
+```
+
+During a long-running Fleet session, Talon treats a 401/403 from an MCP tool as an expired OAuth credential signal. It reloads the Fleet components once, which re-mints tokens and rebuilds MCP connections, then retries the failed graph invocation once. If authorization still fails, Talon returns a structured `mcp_auth_failed` error instead of looping.
+
+## WhatsApp
+
+The WhatsApp channel uses a local Node bridge packaged with this library. The Python adapter talks to the bridge over loopback only.
+
+```bash
+cd deepagents_talon/channels/whatsapp_bridge
+npm install
+cd ../../..
+
+DEEPAGENTS_TALON_WHATSAPP_ENABLED=true \
+DEEPAGENTS_TALON_WHATSAPP_START_BRIDGE=true \
+AGENT_ASSISTANT_ID=whatsapp-local \
+AGENT_MODEL=openai:gpt-5.2 \
+uv run deepagents-talon --whatsapp
+```
+
+The bridge prints a QR code during pairing. By default, inbound exposure is `self`, so only messages from the paired account trigger the agent. Configure `DEEPAGENTS_TALON_WHATSAPP_EXPOSURE=allowlist` with `DEEPAGENTS_TALON_WHATSAPP_ALLOWLIST_CHATS` or `DEEPAGENTS_TALON_WHATSAPP_MENTION_PATTERNS` to allow specific chats. Outbound WhatsApp messages include a `deepagents bot` header by default so self-message conversations clearly distinguish agent replies from operator messages. Set `DEEPAGENTS_TALON_WHATSAPP_BOT_HEADER` to customize that label. Markdown image/video references in assistant replies may attach files only when they are relative paths inside `DEEPAGENTS_TALON_OUTBOUND_MEDIA_DIR`, or inside `DEEPAGENTS_TALON_WORKSPACE` when no outbound media directory is configured.
+
+Inbound voice transcription is opt-in:
+
+```bash
+DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_ENABLED=true
+```
+
+When enabled without `DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_MODEL`, Talon uses the same local default as the original WhatsApp example: `nvidia/parakeet-tdt-0.6b-v3` through Transformers, with ffmpeg converting inbound audio to 16 kHz mono WAV first. Set `DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_DEVICE=cuda` to use a GPU. The legacy example variables `SPEECH_ENABLED` and `SPEECH_DEVICE` are also accepted. Setting `DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_MODEL` to a non-Parakeet model keeps the existing OpenAI SDK transcription path.
+
+`open` exposure allows arbitrary WhatsApp senders to trigger the agent while it runs with the operator's model credentials, channel credentials, MCP tool access, and local-host access when the local execution backend is active. Enabling it requires explicit acknowledgement:
+
+```bash
+DEEPAGENTS_TALON_WHATSAPP_EXPOSURE=open
+DEEPAGENTS_TALON_WHATSAPP_OPEN_ACK=allow-arbitrary-senders
+```
+
+See `../../examples/talon-whatsapp/` for a runnable Docker Compose topology and `.env` reference.
+
+## Tracing
+
+LangSmith tracing is opt-in. Set both values before starting the host:
+
+```bash
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=...
+LANGSMITH_PROJECT=deepagents-talon
+```
+
+When enabled, Talon wraps each agent run in a LangSmith tracing context with assistant id, conversation id, trigger metadata, and source message metadata.
+
+## MCP Tools
+
+Talon loads MCP servers from one config file. It checks `DEEPAGENTS_TALON_MCP_CONFIG`, then `MCP_CONFIG`, then `~/.deepagents/<assistant_id>/agent/tools.json`, then `~/.deepagents/.mcp.json`. Add Talon-local servers by editing `tools.json` directly:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.example/mcp"
+    }
+  }
+}
+```
+
+Run `deepagents-talon mcp config` to print the resolved config paths, and `deepagents-talon mcp login <server>` for OAuth-backed servers.
+
+## Cron Observability
+
+Cron jobs are persisted in `cron/jobs.json` under the assistant state directory. Scheduler lifecycle events are emitted through the standard Python logger as `talon_event` JSON records:
+
+- `cron.tick`
+- `cron.dispatch`
+- `cron.success`
+- `cron.failure`
+- `cron.delivery`
+- `cron.delivery_suppressed`
+- `cron.delivery_failure`
+
+These logs complement the persisted `last_status` and `last_error` fields.
+
+## Security and Data Lifecycle
+
+Talon is single-operator by design. It does not provide multi-tenant isolation, and channel exposure should be treated as direct access to the operator's agent.
+
+Attacker-influenceable inputs include channel message text, voice transcripts, channel media metadata, downloaded media files when a channel adapter persists them for processing, web or search result content, MCP tool results, and imported manifest instructions. Treat all of those inputs as untrusted content entering the agent context.
+
+Outbound data leaves Talon through these integrations:
+
+- Model providers receive conversation text, cron prompts, voice transcripts, selected tool outputs, and system or manifest instructions.
+- LangSmith receives trace metadata and serialized run inputs/outputs when `LANGSMITH_TRACING=true`.
+- MCP servers receive tool arguments chosen by the model and may receive conversation-derived values.
+- Tavily or other search tools receive query strings chosen by the model and may include conversation-derived values.
+- Channel providers receive assistant replies and outbound media paths supplied to the channel adapter.
+
+Sensitive local state is stored under `~/.deepagents/<assistant_id>/` by default with `0700` directories and `0600` cron files:
+
+- `cron/jobs.json` stores cron prompts, origin conversation ids, message ids, run status, and errors. Active jobs are retained while enabled. Completed jobs are deleted on startup after `DEEPAGENTS_TALON_CRON_RETENTION_DAYS`, default `30`.
+- `channels/whatsapp/` stores WhatsApp `LocalAuth` credentials and Chromium profile state. These credentials are retained until the operator deletes the directory, because automatic deletion would silently unpair the channel.
+- `media/inbound/` is reserved for downloaded inbound media. Files older than `DEEPAGENTS_TALON_INBOUND_MEDIA_RETENTION_HOURS`, default `24`, are deleted on startup. The WhatsApp bridge stores downloaded inbound media under the assistant's inbound media directory and passes local paths plus MIME metadata to the host.
+
+Conversation persistence is intentionally not durable yet. Runtime conversation state is in-memory unless a future backend explicitly adds thread persistence.
+
+## Development
+
+```bash
+uv sync --group test
+uv run --group test pytest tests/
+uv run deepagents-talon
+```
+
+Focused verification:
+
+```bash
+make lint
+make test
+```

deepagents_talon-0.0.1/README.md

@@ -0,0 +1,163 @@
+# Deep Agents Talon
+
+Deep Agents Talon is the local runtime host for long-running Deep Agents. It owns the process lifecycle for channel adapters, cron schedulers, and the agent runtime in a single event loop.
+
+> **Experimental:** Talon is an experimental runtime and is subject to change or removal at any time.
+
+Talon currently includes:
+
+- A host process with graceful shutdown, per-conversation serialization, and `/stop` cancellation.
+- A generic channel protocol plus a WhatsApp adapter backed by a loopback Node bridge.
+- A persistent cron scheduler with agent-facing cron tool helpers.
+- MCP tool loading from the assistant manifest directory.
+- Optional LangSmith tracing for each channel or cron-triggered run.
+
+## Quickstart
+
+```bash
+uv sync --group test
+AGENT_ASSISTANT_ID=local AGENT_MODEL=openai:gpt-5.2 uv run deepagents-talon --once
+```
+
+If `AGENT_MODEL` is unset, Talon starts with the echo runtime. This is useful for checking host lifecycle and channel wiring without provider credentials.
+
+Assistant state lives under `~/.deepagents/<assistant_id>/` by default. The host creates restrictive state directories for the materialized agent manifest, channel sessions, and cron jobs. The default local execution workspace is `/workspace`; set `DEEPAGENTS_TALON_WORKSPACE` to use a different directory.
+
+## Fleet Exports
+
+Talon can host an operator-unzipped LangSmith Fleet export through the `fleet-deepagents-export` library:
+
+```bash
+unzip path/to/fleet-export.zip -d ./fleet
+
+DEEPAGENTS_TALON_FLEET_DIR=./fleet \
+AGENT_ASSISTANT_ID=fleet-local \
+uv run deepagents-talon --once
+```
+
+In Fleet mode, Talon uses the model from `fleet/config.json` unless `DEEPAGENTS_TALON_MODEL` or `AGENT_MODEL` is set. The Fleet loader resolves MCP registry references through LangSmith, so provide the required `LANGSMITH_API_KEY`, `LANGSMITH_TENANT_ID`, `LANGSMITH_ORGANIZATION_ID`, and when needed `LANGSMITH_USER_ID`, `BUILTIN_MCP_URL`, `LANGSMITH_HOST_URL`, and `HOST_LANGCHAIN_API_URL`. Locally-authored agents without `DEEPAGENTS_TALON_FLEET_DIR` continue to load from the assistant manifest directory and Talon's plain MCP config discovery.
+
+OAuth-backed Fleet MCP tools must be authorized once from an interactive shell before starting a headless host. Run the host in `--once` mode with the same Fleet directory and LangSmith environment you will use in production, complete the browser authorization if prompted, then start the long-running host:
+
+```bash
+DEEPAGENTS_TALON_FLEET_DIR=./fleet \
+AGENT_ASSISTANT_ID=fleet-local \
+uv run deepagents-talon --once
+```
+
+During a long-running Fleet session, Talon treats a 401/403 from an MCP tool as an expired OAuth credential signal. It reloads the Fleet components once, which re-mints tokens and rebuilds MCP connections, then retries the failed graph invocation once. If authorization still fails, Talon returns a structured `mcp_auth_failed` error instead of looping.
+
+## WhatsApp
+
+The WhatsApp channel uses a local Node bridge packaged with this library. The Python adapter talks to the bridge over loopback only.
+
+```bash
+cd deepagents_talon/channels/whatsapp_bridge
+npm install
+cd ../../..
+
+DEEPAGENTS_TALON_WHATSAPP_ENABLED=true \
+DEEPAGENTS_TALON_WHATSAPP_START_BRIDGE=true \
+AGENT_ASSISTANT_ID=whatsapp-local \
+AGENT_MODEL=openai:gpt-5.2 \
+uv run deepagents-talon --whatsapp
+```
+
+The bridge prints a QR code during pairing. By default, inbound exposure is `self`, so only messages from the paired account trigger the agent. Configure `DEEPAGENTS_TALON_WHATSAPP_EXPOSURE=allowlist` with `DEEPAGENTS_TALON_WHATSAPP_ALLOWLIST_CHATS` or `DEEPAGENTS_TALON_WHATSAPP_MENTION_PATTERNS` to allow specific chats. Outbound WhatsApp messages include a `deepagents bot` header by default so self-message conversations clearly distinguish agent replies from operator messages. Set `DEEPAGENTS_TALON_WHATSAPP_BOT_HEADER` to customize that label. Markdown image/video references in assistant replies may attach files only when they are relative paths inside `DEEPAGENTS_TALON_OUTBOUND_MEDIA_DIR`, or inside `DEEPAGENTS_TALON_WORKSPACE` when no outbound media directory is configured.
+
+Inbound voice transcription is opt-in:
+
+```bash
+DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_ENABLED=true
+```
+
+When enabled without `DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_MODEL`, Talon uses the same local default as the original WhatsApp example: `nvidia/parakeet-tdt-0.6b-v3` through Transformers, with ffmpeg converting inbound audio to 16 kHz mono WAV first. Set `DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_DEVICE=cuda` to use a GPU. The legacy example variables `SPEECH_ENABLED` and `SPEECH_DEVICE` are also accepted. Setting `DEEPAGENTS_TALON_VOICE_TRANSCRIPTION_MODEL` to a non-Parakeet model keeps the existing OpenAI SDK transcription path.
+
+`open` exposure allows arbitrary WhatsApp senders to trigger the agent while it runs with the operator's model credentials, channel credentials, MCP tool access, and local-host access when the local execution backend is active. Enabling it requires explicit acknowledgement:
+
+```bash
+DEEPAGENTS_TALON_WHATSAPP_EXPOSURE=open
+DEEPAGENTS_TALON_WHATSAPP_OPEN_ACK=allow-arbitrary-senders
+```
+
+See `../../examples/talon-whatsapp/` for a runnable Docker Compose topology and `.env` reference.
+
+## Tracing
+
+LangSmith tracing is opt-in. Set both values before starting the host:
+
+```bash
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=...
+LANGSMITH_PROJECT=deepagents-talon
+```
+
+When enabled, Talon wraps each agent run in a LangSmith tracing context with assistant id, conversation id, trigger metadata, and source message metadata.
+
+## MCP Tools
+
+Talon loads MCP servers from one config file. It checks `DEEPAGENTS_TALON_MCP_CONFIG`, then `MCP_CONFIG`, then `~/.deepagents/<assistant_id>/agent/tools.json`, then `~/.deepagents/.mcp.json`. Add Talon-local servers by editing `tools.json` directly:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.example/mcp"
+    }
+  }
+}
+```
+
+Run `deepagents-talon mcp config` to print the resolved config paths, and `deepagents-talon mcp login <server>` for OAuth-backed servers.
+
+## Cron Observability
+
+Cron jobs are persisted in `cron/jobs.json` under the assistant state directory. Scheduler lifecycle events are emitted through the standard Python logger as `talon_event` JSON records:
+
+- `cron.tick`
+- `cron.dispatch`
+- `cron.success`
+- `cron.failure`
+- `cron.delivery`
+- `cron.delivery_suppressed`
+- `cron.delivery_failure`
+
+These logs complement the persisted `last_status` and `last_error` fields.
+
+## Security and Data Lifecycle
+
+Talon is single-operator by design. It does not provide multi-tenant isolation, and channel exposure should be treated as direct access to the operator's agent.
+
+Attacker-influenceable inputs include channel message text, voice transcripts, channel media metadata, downloaded media files when a channel adapter persists them for processing, web or search result content, MCP tool results, and imported manifest instructions. Treat all of those inputs as untrusted content entering the agent context.
+
+Outbound data leaves Talon through these integrations:
+
+- Model providers receive conversation text, cron prompts, voice transcripts, selected tool outputs, and system or manifest instructions.
+- LangSmith receives trace metadata and serialized run inputs/outputs when `LANGSMITH_TRACING=true`.
+- MCP servers receive tool arguments chosen by the model and may receive conversation-derived values.
+- Tavily or other search tools receive query strings chosen by the model and may include conversation-derived values.
+- Channel providers receive assistant replies and outbound media paths supplied to the channel adapter.
+
+Sensitive local state is stored under `~/.deepagents/<assistant_id>/` by default with `0700` directories and `0600` cron files:
+
+- `cron/jobs.json` stores cron prompts, origin conversation ids, message ids, run status, and errors. Active jobs are retained while enabled. Completed jobs are deleted on startup after `DEEPAGENTS_TALON_CRON_RETENTION_DAYS`, default `30`.
+- `channels/whatsapp/` stores WhatsApp `LocalAuth` credentials and Chromium profile state. These credentials are retained until the operator deletes the directory, because automatic deletion would silently unpair the channel.
+- `media/inbound/` is reserved for downloaded inbound media. Files older than `DEEPAGENTS_TALON_INBOUND_MEDIA_RETENTION_HOURS`, default `24`, are deleted on startup. The WhatsApp bridge stores downloaded inbound media under the assistant's inbound media directory and passes local paths plus MIME metadata to the host.
+
+Conversation persistence is intentionally not durable yet. Runtime conversation state is in-memory unless a future backend explicitly adds thread persistence.
+
+## Development
+
+```bash
+uv sync --group test
+uv run --group test pytest tests/
+uv run deepagents-talon
+```
+
+Focused verification:
+
+```bash
+make lint
+make test
+```