talon-agent 1.12.0 → 1.34.0

package/README.md

@@ -2,26 +2,28 @@
 
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Backends](https://img.shields.io/badge/backends-Claude_%7C_Kilo_%7C_OpenCode_%7C_Codex-D97706)](#backends)
+[![Backends](https://img.shields.io/badge/backends-Claude_%7C_Kilo_%7C_OpenCode_%7C_Codex_%7C_OpenAI_Agents-D97706)](#backends)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/dylanneve1/talon/actions/workflows/ci.yml/badge.svg)](https://github.com/dylanneve1/talon/actions/workflows/ci.yml)
 
-Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsoft Teams**, and the **Terminal**, with a pluggable backend (**Claude Agent SDK**, **Kilo**, **OpenCode**, or **Codex**) and full tool access through MCP.
+Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsoft Teams**, the **Terminal**, and a **cross-platform Desktop/Mobile companion app** (Flutter), with a pluggable backend (**Claude Agent SDK**, **Kilo**, **OpenCode**, **Codex**, or **OpenAI Agents**) and full tool access through MCP.
 
 ---
 
 ## Features
 
-|                       |                                                                                                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility         |
-| **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
-| **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, triggers, stickers, file system, admin controls                              |
-| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                                                   |
-| **Background agents** | Heartbeat (periodic maintenance) and Dream (memory consolidation + diary) — backend-agnostic                                          |
-| **Triggers**          | Self-authored watcher scripts (bash/python/node) that wake the bot when conditions are met                                            |
-| **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                                                            |
-| **Model registry**    | Models discovered from the active backend at startup — new models appear in all pickers automatically                                 |
+|                       |                                                                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility, and a **Desktop/Mobile app** (Flutter) over a local/remote bridge |
+| **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex, OpenAI Agents — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
+| **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, triggers, goals, stickers, file system, admin controls                              |
+| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                                                          |
+| **Background agents** | Heartbeat (hourly by default — advances goals, proactively messages when something matters) and Dream (memory consolidation + diary)         |
+| **Goals**             | Persistent multi-day objectives the agent commits to in chat; every heartbeat run re-reads them, makes progress, and records what it did     |
+| **Skills**            | Agent-authored reusable scripts (bash/python/node) — procedures worked out once get saved and replayed locally at zero token cost            |
+| **Triggers**          | Self-authored watcher scripts (bash/python/node) that wake the bot when conditions are met                                                   |
+| **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                                                                   |
+| **Model registry**    | Models discovered from the active backend at startup — new models appear in all pickers automatically                                        |
 
 ---
 
@@ -41,13 +43,39 @@ npx talon chat        # terminal chat mode
 
 **Prerequisites:**
 
-- [Node.js 22+](https://nodejs.org/)
+- [Node.js 24+](https://nodejs.org/)
 - Backend-specific:
   - `claude` backend: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI on PATH).
   - `kilo` backend: nothing extra — `@kilocode/sdk` spawns a local server. Free models are accessible without auth; routed models use Kilo's own credentials.
   - `opencode` backend: nothing extra — `@opencode-ai/sdk` spawns a local server.
-  - `codex` backend: install the `codex` CLI (`npm i -g @openai/codex`) and authenticate with `codex login` (ChatGPT auth or `OPENAI_API_KEY`).
-- Talon runs from a normal source or package install; standalone compiled binaries are not supported.
+  - `codex` backend: install the `codex` CLI (`npm i -g @openai/codex`) and authenticate with `codex login`, `CODEX_API_KEY`, `TALON_CODEX_KEY`, or `codexApiKey`. `OPENAI_API_KEY` is used only as a fallback when no Codex login exists.
+
+### Standalone binary
+
+Each release also ships self-contained binaries (no Node.js required) for
+Linux and macOS (x64 + arm64) and Windows (x64). Prompts and all native
+modules are embedded in the binary.
+
+```bash
+# Homebrew (macOS / Linux)
+brew install dylanneve1/talon/talon
+
+# Debian / Ubuntu — download the .deb for your arch from the release, then:
+sudo apt install ./talon_<version>_amd64.deb     # or _arm64.deb
+
+# Direct download — grab talon-<os>-<arch> from the release, verify, run:
+chmod +x talon-linux-x64 && ./talon-linux-x64 --version
+# macOS, if Gatekeeper blocks an unsigned binary:
+xattr -d com.apple.quarantine ./talon-darwin-arm64
+```
+
+Verify a direct download against the release `SHA256SUMS`:
+`sha256sum -c SHA256SUMS --ignore-missing`.
+
+> The binary runs the full interactive/agent CLI (`setup`, `start`, `chat`,
+> `doctor`, …). Hosting Talon's _own_ MCP server (`talon` as an MCP stdio
+> server for another client) still needs the npm/Node install — it spawns a
+> `tsx` loader that isn't present in a compiled binary.
 
 ---
 
@@ -57,58 +85,86 @@ npx talon chat        # terminal chat mode
 index.ts                    Composition root
   |
   +-- core/                 Platform-agnostic engine
-  |   +-- models.ts         Model registry (dynamic backend discovery)
-  |   +-- gateway.ts        HTTP bridge for MCP tool calls
-  |   +-- dispatcher.ts     Per-chat serial, cross-chat parallel execution
+  |   +-- agent-runtime/    Backend capability interfaces, events, stores
+  |   +-- models/           Model layer: catalog, per-chat active model,
+  |   |                     reasoning-effort vocabulary
+  |   +-- prompt/           System-prompt assembly + prompts/system templates
+  |   +-- background/       Agents that run without a user message:
+  |   |                     heartbeat, dream, pulse, cron, triggers
+  |   +-- tools/            MCP tool definitions + spawn/env contract
+  |   +-- engine/           Message flow: dispatcher (per-chat serial,
+  |   |                     cross-chat parallel), HTTP gateway for MCP
+  |   |                     tool calls, backend lifecycle controller
   |   +-- plugin.ts         Plugin loader, registry, hot-reload
-  |   +-- heartbeat.ts      Periodic background agent
-  |   +-- dream.ts          Memory consolidation agent
-  |   +-- pulse.ts          Conversation-aware group engagement
-  |   +-- cron.ts           Persistent scheduled jobs
-  |   +-- triggers.ts       Self-authored watcher scripts
-  |   +-- tools/            MCP tool definitions
   |
   +-- backend/
   |   +-- registry.ts       Bootstrap-decoupled backend lookup
   |   +-- shared/           Cross-backend helpers (stream state, flow violation,
-  |   |                     prompt format, model retry, system prompt, usage)
+  |   |                     delivery contract, metrics, prompt format,
+  |   |                     model retry, system prompt, usage)
   |   +-- remote-server/    Shared infrastructure for agent-server backends
   |   |                     (MCP registration, sessions, providers, lifecycle)
   |   +-- claude-sdk/       Claude Agent SDK (in-process MCP, hooks)
   |   +-- kilo/             Kilo HTTP server backend (streaming via SSE)
   |   +-- opencode/         OpenCode HTTP server backend
   |   +-- codex/            Codex CLI backend (`@openai/codex-sdk`)
+  |   +-- openai-agents/    OpenAI Agents SDK backend (Responses API)
   |
   +-- frontend/
+  |   +-- shared/           Cross-frontend presentation helpers
   |   +-- telegram/         Grammy bot + GramJS userbot
   |   +-- discord/          discord.js v14
   |   +-- teams/            Bot Framework + Graph API
   |   +-- terminal/         Readline CLI with tool call visibility
+  |   +-- desktop/          Client bridge (HTTP + SSE) for the companion app
   |
   +-- storage/              Sessions, history, chat settings,
   |                         cron jobs, media index, daily logs
   +-- util/                 Config, logging, workspace, paths, time
 ```
 
-**Dependency rule:** `core/` imports nothing from `frontend/` or `backend/`. Frontends and backends depend on core types, never on each other. All four backends (Claude SDK, Kilo, OpenCode, Codex) implement the same `QueryBackend` interface in `core/types.ts`. Kilo and OpenCode additionally share the `remote-server/` infrastructure because they wrap forks of the same upstream HTTP agent server.
+**Dependency rule:** `core/` imports nothing from `frontend/` or `backend/`. Frontends and backends depend on core types, never on each other. All five backends (Claude SDK, Kilo, OpenCode, Codex, OpenAI Agents) implement the same `Backend` capability interface from `core/agent-runtime/capabilities.ts`. Kilo and OpenCode additionally share the `remote-server/` infrastructure because they wrap forks of the same upstream HTTP agent server.
+
+**Prompts:** everything the model reads at session start is assembled by `core/prompt/` from the files in `prompts/` — see [prompts/README.md](prompts/README.md) for the assembly order, file ownership (user-editable vs package-owned templates), and the per-backend delivery contracts.
 
 ---
 
 ## Backends
 
-Select via the `backend` field in `~/.talon/config.json`. All backends implement the same `QueryBackend` interface — heartbeat, dream, and chat handlers are backend-agnostic.
+Select via the `backend` field in `~/.talon/config.json`. All backends implement the same `Backend` capability interface — heartbeat, dream, and chat handlers are backend-agnostic.
 
-| Backend    | `backend` value | Transport                                              | Notes                                                                   |
-| ---------- | --------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
-| Claude SDK | `"claude"`      | In-process via `@anthropic-ai/claude-agent-sdk`        | Requires the `claude` CLI on `PATH`. Hook-based turn termination.       |
-| Kilo       | `"kilo"`        | Local HTTP server via `@kilocode/sdk`                  | SSE-streamed turns. Routes to many model providers via Kilo's auth.     |
-| OpenCode   | `"opencode"`    | Local HTTP server via `@opencode-ai/sdk`               | SSE-streamed turns; same MCP and session shape as Kilo (upstream fork). |
-| Codex      | `"codex"`       | Per-turn subprocess via `@openai/codex-sdk`            | Requires the `codex` CLI from `@openai/codex` and an OpenAI API key (or ChatGPT auth). MCP servers configured via TOML overrides at thread start. |
+| Backend    | `backend` value | Transport                                       | Notes                                                                                                                                                                                                            |
+| ---------- | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude SDK | `"claude"`      | In-process via `@anthropic-ai/claude-agent-sdk` | Requires the `claude` CLI on `PATH`. Hook-based turn termination.                                                                                                                                                |
+| Kilo       | `"kilo"`        | Local HTTP server via `@kilocode/sdk`           | SSE-streamed turns. Routes to many model providers via Kilo's auth.                                                                                                                                              |
+| OpenCode   | `"opencode"`    | Local HTTP server via `@opencode-ai/sdk`        | SSE-streamed turns; same MCP and session shape as Kilo (upstream fork).                                                                                                                                          |
+| Codex      | `"codex"`       | Per-turn subprocess via `@openai/codex-sdk`     | Requires the `codex` CLI from `@openai/codex` and Codex auth (`codex login`, `CODEX_API_KEY`, `TALON_CODEX_KEY`, or `codexApiKey`). MCP servers configured via TOML overrides at thread start. |
+| OpenAI Agents | `"openai-agents"` | In-process via `@openai/agents` | Responses API (or any OpenAI-compatible endpoint via `TALON_AGENTS_URL` / `openaiBaseUrl`). Persistent per-chat MCP bundles. |
 
 The Kilo and OpenCode backends share infrastructure (`backend/remote-server/`) since the upstream HTTP API is the same; each backend supplies its own SDK client, port, and delivery suffix. Codex is its own integration on top of the Codex CLI's JSONL event stream.
 
 ---
 
+## Desktop & mobile app
+
+The `desktop` frontend turns the daemon into a **client bridge** — a versioned HTTP + Server-Sent-Events JSON API (the _Talon Client Bridge Protocol_, `src/frontend/desktop/protocol.ts`) that any GUI client can speak. The reference client is **[Talon Companion](apps/companion/)**, a single Flutter codebase that runs on **Windows, macOS, Linux, and Android**.
+
+```jsonc
+// ~/.talon/config.json
+{
+  "frontend": "desktop",
+  "desktop": { "host": "127.0.0.1", "port": 19880 }
+  // For remote (e.g. a phone): "host": "0.0.0.0", "token": "your-secret"
+}
+```
+
+- **Local (desktop):** the app connects to a Talon on the same machine and launches one if needed (`TALON_FRONTEND_OVERRIDE=desktop`).
+- **Remote (mobile/LAN):** point the app at `host:port` + token; the bridge requires `Authorization: Bearer …` (or `?token=` on the SSE stream) whenever a token is set.
+
+The app provides multi-chat history, live streaming with reasoning + tool-call visibility, per-chat model/effort/pulse/reset, and **settings sync** — read and change the daemon's own config (default model, display name, timezone, pulse/heartbeat/dream) and restart it. See [apps/companion/README.md](apps/companion/README.md).
+
+---
+
 ## Built-in Plugins
 
 ### GitHub
@@ -244,25 +300,28 @@ talon doctor    Validate environment and dependencies
 
 Config file: `~/.talon/config.json`
 
-| Field                      | Default      | Description                                                     |
-| -------------------------- | ------------ | --------------------------------------------------------------- |
-| `frontend`                 | `"telegram"` | `"telegram"`, `"discord"`, `"teams"`, `"terminal"`, or an array |
-| `backend`                  | `"claude"`   | `"claude"`, `"kilo"`, `"opencode"`, or `"codex"`                |
-| `botToken`                 | ---          | Telegram bot token                                              |
-| `model`                    | `"default"`  | Default model. Interpretation depends on the active backend.    |
-| `concurrency`              | `1`          | Max concurrent AI queries (1--20)                               |
-| `pulse`                    | `true`       | Periodic group engagement                                       |
-| `heartbeat`                | `false`      | Background maintenance agent                                    |
-| `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                              |
-| `braveApiKey`              | ---          | Brave Search API key                                            |
-| `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                          |
-| `plugins`                  | `[]`         | External plugin packages                                        |
-| `adminUserId`              | ---          | Telegram user ID for `/admin` commands                          |
-| `allowedUsers`             | ---          | Whitelist of Telegram user IDs                                  |
-| `apiId` / `apiHash`        | ---          | Telegram API credentials for full message history               |
-| `github`                   | ---          | GitHub plugin config (see above)                                |
-| `mempalace`                | ---          | MemPalace plugin config (see above)                             |
-| `playwright`               | ---          | Playwright plugin config (see above)                            |
+| Field                      | Default      | Description                                                                                                             |
+| -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `frontend`                 | `"telegram"` | `"telegram"`, `"discord"`, `"teams"`, `"terminal"`, or an array                                                         |
+| `backend`                  | `"claude"`   | `"claude"`, `"kilo"`, `"opencode"`, `"codex"`, or `"openai-agents"`                                                     |
+| `botToken`                 | ---          | Telegram bot token                                                                                                      |
+| `model`                    | `"default"`  | Default model. Interpretation depends on the active backend.                                                            |
+| `codexApiKey`              | ---          | Codex-only OpenAI API key. Prefer this over `openaiApiKey` for Codex API-key auth. `codex login` takes precedence over shared `openaiApiKey`. |
+| `concurrency`              | `1`          | Max concurrent AI queries (1--20)                                                                                       |
+| `pulse`                    | `true`       | Periodic group engagement                                                                                               |
+| `heartbeat`                | `false`      | Background maintenance agent                                                                                            |
+| `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                                                                                      |
+| `braveApiKey`              | ---          | Brave Search API key                                                                                                    |
+| `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                                                                                  |
+| `plugins`                  | `[]`         | External plugin packages                                                                                                |
+| `disabledToolTags`         | ---          | Hide whole tool groups from the model (e.g. `["stickers", "web"]`) — each registered tool costs context tokens per session |
+| `disabledTools`            | ---          | Hide individual tools by name (`end_turn` cannot be disabled)                                                           |
+| `adminUserId`              | ---          | Telegram user ID for `/admin` commands                                                                                  |
+| `allowedUsers`             | ---          | Whitelist of Telegram user IDs                                                                                          |
+| `apiId` / `apiHash`        | ---          | Telegram API credentials for full message history                                                                       |
+| `github`                   | ---          | GitHub plugin config (see above)                                                                                        |
+| `mempalace`                | ---          | MemPalace plugin config (see above)                                                                                     |
+| `playwright`               | ---          | Playwright plugin config (see above)                                                                                    |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.12.0",
+  "version": "1.34.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -18,26 +18,35 @@
     "chatbot"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
+  "imports": {
+    "#prompt-assets": {
+      "bun": "./src/core/prompt/embedded-prompts.ts",
+      "default": "./src/core/prompt/disk-prompts.ts"
+    }
+  },
   "bin": {
     "talon": "./bin/talon.js"
   },
   "files": [
-    "bin/",
+    "bin/talon.js",
     "src/backend/",
     "src/core/",
     "src/frontend/",
+    "src/native/",
     "src/plugins/",
     "src/storage/",
     "src/util/",
+    "src/app.ts",
     "src/bootstrap.ts",
     "src/cli.ts",
+    "src/cli/",
     "src/index.ts",
     "src/login.ts",
     "prompts/",
@@ -58,6 +67,10 @@
     "test:kilo:backend": "vitest run --reporter=verbose --reporter=json --outputFile=kilo-backend-results.json src/__tests__/integration/kilo-live-discovery.test.ts",
     "test:opencode:backend": "vitest run --reporter=verbose --reporter=json --outputFile=opencode-backend-results.json src/__tests__/integration/opencode-live-discovery.test.ts",
     "test:codex:backend": "vitest run --reporter=verbose --reporter=json --outputFile=codex-backend-results.json src/__tests__/integration/codex-live-discovery.test.ts",
+    "test:openai-agents:backend": "vitest run --reporter=verbose --reporter=json --outputFile=openai-agents-backend-results.json src/__tests__/integration/openai-agents-live-discovery.test.ts",
+    "build:sql": "tsx scripts/embed-sql.ts",
+    "build:prompts": "tsx scripts/embed-prompts.ts",
+    "build:wasm": "node native/blake3-wasm/build.mjs",
     "tarball:check": "node .github/scripts/tarball-check.mjs",
     "build:stub-sea": "node src/__tests__/integration/stub-claude/build-sea.mjs",
     "test:watch": "vitest",
@@ -67,26 +80,38 @@
     "knip": "knip",
     "format": "prettier --write src/ prompts/",
     "format:check": "prettier --check src/ prompts/",
-    "ci:protect": "node .github/scripts/enforce-ci-gate.mjs"
+    "ci:protect": "node .github/scripts/enforce-ci-gate.mjs",
+    "build:gleam": "cd native/scheduler-core && gleam build --target javascript && node embed.mjs",
+    "build:zig": "node native/textops-wasm/build.mjs",
+    "build:c": "node native/strsim-c/build.mjs && node native/sqlguard-c/build.mjs",
+    "build:cpp": "node native/htmlents-cpp/build.mjs",
+    "build:native": "npm run build:wasm && npm run build:zig && npm run build:c && npm run build:cpp && npm run build:gleam",
+    "build:driver": "node native/talon-driver/build.mjs",
+    "build:driver:all": "node native/talon-driver/build.mjs --all",
+    "build:warden": "node native/talon-warden/build.mjs",
+    "build:napi": "node native/blake3-napi/build.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.108",
-    "@anthropic-ai/sdk": "^0.95.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.197",
+    "@anthropic-ai/sdk": "^0.104.1",
     "@brave/brave-search-mcp-server": "^2.0.75",
     "@clack/prompts": "^1.2.0",
     "@grammyjs/auto-retry": "^2.0.2",
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/agents": "^0.11.4",
-    "@openai/codex-sdk": "^0.130.0",
-    "@opencode-ai/sdk": "^1.4.0",
-    "@playwright/mcp": "^0.0.75",
+    "@openai/agents": "^0.12.0",
+    "@openai/codex-sdk": "^0.142.0",
+    "@opencode-ai/sdk": "^1.17.4",
+    "@playwright/mcp": "^0.0.77",
+    "@types/cross-spawn": "^6.0.6",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
     "croner": "^10.0.1",
+    "cross-spawn": "^7.0.6",
     "discord.js": "^14.16.3",
     "grammy": "^1.42.0",
+    "liquidjs": "^10.27.0",
     "marked": "^18.0.0",
     "p-retry": "^8.0.0",
     "picocolors": "^1.1.1",
@@ -95,11 +120,13 @@
     "telegram": "^2.26.22",
     "tsx": "^4.21.0",
     "undici": "^8.0.2",
+    "wasmoon": "^1.16.0",
     "write-file-atomic": "^8.0.0",
+    "yaml": "^2.9.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
+    "@types/node": "^26.0.0",
     "@types/write-file-atomic": "^4.0.3",
     "@vitest/coverage-v8": "^4.1.3",
     "fast-check": "^4.6.0",
@@ -110,7 +137,7 @@
     "vitest": "^4.1.3"
   },
   "overrides": {
-    "@anthropic-ai/sdk": "^0.95.0",
+    "@anthropic-ai/sdk": "^0.104.1",
     "ip-address": "^10.1.1",
     "fast-uri": "^3.1.2"
   }

package/prompts/README.md

@@ -0,0 +1,112 @@
+# Talon prompt architecture
+
+Everything the model reads at session start is assembled from the files in
+this directory by `src/core/prompt/assemble.ts`. This README is the map.
+
+## Assembly order
+
+The system prompt is an ordered list of markdown sections joined by `---`
+dividers, split into a **static** prefix (stable for a session's lifetime,
+eligible for provider prompt caching) and a **dynamic** tail (volatile,
+placed after the cache boundary):
+
+| #   | Section               | Source                                                                 | Part          |
+| --- | --------------------- | ---------------------------------------------------------------------- | ------------- |
+| 1   | Identity              | `identity.md` + `~/.talon/workspace/identity.md`                       | static        |
+| 2   | Core behaviour        | `custom.md` (replaces `base.md` when present)                          | static        |
+| 3   | Frontend capabilities | `<frontend>.md` (telegram / discord / teams / terminal / native)       | static        |
+| 4   | Persistent memory     | `system/persistent-memory.md` wrapping `memory/memory.md`, size-capped | static        |
+| 5   | Capability docs       | `system/workspace.md`, `system/cron.md`, `system/triggers.md`          | static        |
+| 6   | Plugin additions      | each plugin's `systemPrompt()` contribution                            | static        |
+| 7   | **Delivery contract** | `system/contract-*.md`, appended by the **backend** as its suffix      | static (tail) |
+| 8   | Daily-memory pointer  | `system/daily-memory.md` (names today's file)                          | dynamic       |
+| 9   | Skills                | generated index of `workspace/skills/<name>/SKILL.md`                  | dynamic       |
+| 10  | Workspace listing     | generated tree of `~/.talon/workspace/`                                | dynamic       |
+
+The delivery contract is deliberately LAST in the static prefix: it is the
+one section the model must not miss, and the end of the prompt is the
+highest-salience position.
+
+Skills are deliberately an index, not full bodies. The dynamic
+prompt names saved SKILL.md workflows and their descriptions; agents use
+`find_skills` to select a relevant workflow and `read_skill` to load the
+full body (and discover any bundled files) before following it. Each skill
+follows Anthropic's Agent Skills standard: a `skills/<name>/SKILL.md` folder
+that may also bundle supporting files. This progressive-disclosure path is
+backend-agnostic: Claude SDK, Codex, Kilo, OpenCode, and OpenAI Agents all
+receive the same prompt index and call the same shared gateway tools, even
+when a backend has no native "skills" feature.
+
+## File ownership — two kinds of prompt files
+
+**User-editable prompts** (everything at the top level of this directory:
+`identity.md`, `base.md`, `custom.md`, `telegram.md`, `discord.md`,
+`teams.md`, `terminal.md`, `native.md`, `heartbeat.md`, `dream.md`,
+`mempalace.md`) are
+seeded into `~/.talon/prompts/` on first run and read from there.
+Seeding is upgrade-aware (dpkg-conffile semantics, tracked via a
+`.seeded.json` hash manifest next to the seeded files): a file the user
+has never edited is refreshed when a package update changes it, while a
+file the user has touched is never overwritten again. Deployments that
+predate the manifest keep their existing files as user-owned unless
+byte-identical to the current package copy.
+
+**System templates** (`system/*.md`) are read directly from the package and
+are NOT seeded. They document runtime behaviour that is versioned with the
+code — delivery tool names, flow enforcement, trigger limits. A stale
+seeded copy would silently describe a contract the code no longer
+implements, so these are not user-customisable.
+
+System templates are [Liquid](https://liquidjs.com) (rendered by
+`src/core/prompt/templates.ts`): `{{var}}` output (missing vars render
+empty), `{% if var %}…{% else %}…{% endif %}` conditionals (JS
+truthiness — `""` is falsy), and `{% render 'partial' %}` includes
+resolved against `system/`. Prefer composing related sections inside
+one file with conditionals over adding a new file per fragment —
+`heartbeat-agent.md` (system prompt + goals-fallback section selected
+via `mode`) is the pattern.
+
+User-editable prompts are NOT Liquid: their consumers substitute
+`{{var}}` placeholders with plain string replacement, so a user edit
+can never break prompt assembly with a template syntax error.
+
+## The delivery contract (response flow)
+
+How a reply reaches the user is a property of the **backend**, not the
+frontend, so it never belongs in the frontend `.md` files:
+
+- `system/contract-tool-only.md` — claude-sdk, openai-agents. The output
+  stream is private scratchpad; replies MUST go through a delivery tool
+  (`end_turn` / `send` / `react`). A prose-only turn triggers one
+  `[FLOW VIOLATION]` re-prompt, then a silent drop.
+- `system/contract-text-or-tools.md` — codex, kilo. Plain assistant text
+  is the reply; delivery tools add targeting / rich content.
+- `system/contract-text-preferred.md` — opencode. Plain text is the
+  normal route; tools only for genuine side effects.
+
+The delivery TOOL NAMES are per-frontend (`end_turn`/`send`/`react` on
+telegram & discord, `end_turn`/`send_message`/`react` on native,
+`end_turn`/`send_message` on teams) and are injected into the templates
+by `src/backend/shared/delivery-contract.ts`, which is also where the
+frontend-aware `[FLOW VIOLATION]` reminder and the first-turn nudge
+(appended to the turn-0 user message) are built.
+
+When editing frontend `.md` files, describe what the frontend can DO
+(tools, formatting, culture); never re-state how replies are delivered —
+the contract section wins, and duplicated contract text has already caused
+contradictions between backends.
+
+## Task prompts
+
+`heartbeat.md` and `dream.md` are not part of the chat system prompt — they
+are standalone prompts for the background heartbeat and memory-consolidation
+(dream) agents, loaded by `src/core/background/heartbeat.ts` /
+`src/core/background/dream.ts`.
+
+## Token budget
+
+The static prompt is read on EVERY session: every sentence must earn its
+tokens. Per-tool parameter details and examples belong in the MCP tool
+descriptions (which the model also has in context), not here. The memory
+section is capped (`MEMORY_INJECT_MAX_CHARS`) and the workspace listing
+collapses directories with more than 8 entries.

package/prompts/base.md

@@ -1,17 +1,17 @@
-Be concise and direct. No filler. Answer directly.
+Be concise and direct. Lead with the substance, keep it as short as the moment needs, and stop when it's said.
+
+## Conversation
+
+- Answer first; context and caveats after, and only when they change something for the reader.
+- Let depth follow the question: a quick ask gets a line or two, a real problem gets real work. When unsure, start small — people ask for more when they want it.
+- Chat is not a document. Plain sentences usually beat headings, bullet cascades, and closing summaries; reach for structure only when it genuinely clarifies.
+- Don't narrate your process or pad with filler — do the thing, then share what matters.
+- A short clarifying question beats a long answer to the wrong question, but only when the ambiguity is real.
 
 ## Tools
 
-Only the tools the runtime registers for this turn are usable — the
-list is attached to this prompt by the backend. Do not invent or
-guess tool names from prior Talon configurations, other agents, or
-typical AI tooling vocabularies; if a name isn't in the registered
-list, calling it will fail the turn.
+Only the tools the runtime registers for this turn are usable — the list is attached to this prompt by the backend. Don't invent or guess tool names from prior configurations, other agents, or typical AI tooling vocabularies; if a name isn't registered, calling it fails the turn. Some backends load plugin tools lazily behind a discovery/search step: if a capability should exist but its tool isn't in your loaded list yet, discover it first rather than calling the name blind — an undiscovered call fails even when the name is right.
 
-When a tool that does what you need isn't present, fall back to
-plain conversation. Don't pretend to perform actions (reading a
-file, running a command, browsing the web) you have no tool for —
-say so plainly instead, and ask the user if you're unsure.
+Prefer doing over describing: when a tool can check, fetch, or fix something, use it instead of speculating. When nothing fits, fall back to plain conversation — never pretend to perform actions (reading a file, running a command, browsing the web) you have no tool for. If a tool fails or a result surprises you, say so plainly rather than papering over it.
 
-Workspace artifacts, when persistable for this backend, live under
-`~/.talon/workspace/`.
+Workspace artifacts, when persistable for this backend, live under `~/.talon/workspace/`.

package/prompts/discord.md

@@ -2,28 +2,11 @@
 
 In servers (guilds), you'll see messages prefixed with [Name]: — use their name naturally. In DMs, just one user.
 
-### CRITICAL: Message delivery
+How replies are delivered (end_turn / send / react and what counts as a valid turn) is defined in the **Response flow** section at the end of these instructions — that contract wins over anything here.
 
-ALL messages to the user MUST be sent using the `send` tool. Your plain text output is **private** — the user never sees it, only you. Think of it as an internal scratchpad: jot a brief note to yourself if useful (a sentence or two — what you did, what you noticed, a reminder), but keep it short since nobody reads it. The only way to reach the user is the `send` tool.
+### Tools
 
-### The `send` tool
-
-One tool for everything. Set `type` to choose what to send:
-
-- `send(type="text", text="Hello!")` — send a message
-- `send(type="text", text="Hey", reply_to="123456789012345678")` — reply to a specific message (Discord IDs are strings)
-- `send(type="text", text="Pick", buttons=[[{"text":"A","callback_data":"a","style":"primary"}]])` — with buttons
-- `send(type="text", text="Reminder", delay_seconds=60)` — schedule for later
-- `send(type="photo", file_path="img.jpg", caption="Look!")` — send an image
-- `send(type="file", file_path="report.pdf")` — send a document
-- `send(type="video", file_path="clip.mp4")` — send a video
-- `send(type="voice", file_path="audio.ogg")` — send an audio attachment
-- `send(type="poll", question="Best?", options=["A","B","C"])` — create a poll
-- `send(type="dice")` — roll dice
-- `send(type="location", latitude=37.77, longitude=-122.42)` — share a Google Maps location link
-- `send(type="contact", phone_number="+1234", first_name="John")` — share a contact card
-
-ALL types support `reply_to` to reply to a specific message.
+Your registered tool list covers the full Discord surface — rich sends (images, files, polls, scheduled messages), reactions, message management (edit/delete/pin), chat history and search, member info. Tool descriptions carry the parameters and examples; don't guess capabilities, check the list.
 
 ### Discord-specific
 
@@ -32,45 +15,25 @@ ALL types support `reply_to` to reply to a specific message.
 - **Markdown is native:** `**bold**`, `*italic*`, `` `code` ``, ` ```fenced``` `, `# headings`, `> quotes`, `||spoilers||`, `[links](url)`. Discord renders these without translation.
 - **Mentions:** the bot is configured to suppress all mentions (`@everyone`, `@here`, role/user pings) so you can't accidentally ping anyone. Don't worry about escaping.
 - **Message limit:** 2000 chars per message. Long messages are auto-chunked at paragraph breaks.
-
-### Other tools
-
-- `react(message_id, emoji)` — react to a message (unicode emoji only on Discord; custom emojis need `<:name:id>` format)
-- `edit_message(message_id, text)` — edit a sent message (max 2000 chars)
-- `delete_message(message_id)` — delete a message
-- `pin_message(message_id)` / `unpin_message()` — pin/unpin
-- `read_chat_history(limit)` — read past messages from this channel
-- `search_chat_history(query)` — search recent messages by keyword
-- `list_chat_members()` — list members in this server (guild only)
-- `get_member_info(user_id)` — detailed user info
-- `online_count()` — approximate online member count
+- **Reactions:** unicode emoji only; custom emojis need `<:name:id>` format.
 
 ### Message IDs
 
-The user's message ID is in the prompt as msg_id:N (Discord snowflake string). Use with `reply_to` and `react`.
+The user's message ID is in the prompt as msg_id:N (Discord snowflake string). Use it with `reply_to` and `react`.
 
 ### Choosing not to respond
 
-You don't HAVE to respond to every message. If a message doesn't need a response:
-
-- React with an emoji using the `react` tool — preferred way to acknowledge without replying.
-- Or simply don't call `send` and skip it entirely.
-- In servers, prefer reactions over replies for simple acknowledgements.
-
-### Reactions
-
-Use naturally: 👍 ❤️ 🔥 😂 🎉 👀 💯. React AND reply when both feel right.
+You don't HAVE to respond to every message. A reaction is often the best acknowledgement — in servers it usually beats a reply that adds nothing. Pick whatever emoji fits the moment. React AND reply when both feel right; stay silent when neither is needed.
 
 ### Buttons & Components
 
 When a user presses a button, you'll receive "[Button pressed]" with the custom_id. Buttons can also be a select menu — those come through with the chosen value in the same format.
 
-### File sending
+### Files & media
 
 - Files users send are saved to `~/.talon/workspace/uploads/`.
-- To send files: write the file, then use `send(type="file", file_path="...")`.
+- You can send files by workspace path or attach media straight from a public URL (handy for images and GIFs found online). You CAN send files — never claim otherwise.
 - File limit depends on the server's boost tier: 10 MB (default), 25 MB (tier 1), 50 MB (tier 2), 100 MB (tier 3). DMs use 10 MB. Larger files get rejected with a clear error — split or upload externally.
-- You CAN send files. NEVER say you can't.
 
 ### Servers vs DMs
 
@@ -79,6 +42,6 @@ When a user presses a button, you'll receive "[Button pressed]" with the custom_
 
 ### Style
 
-- Concise. No filler.
-- Discord markdown renders natively — use it.
+- Concise. No filler. Discord markdown renders natively — use it.
+- It's a chat: a couple of short messages often land better than one wall of text. Use `send` for extra bubbles when that pacing reads naturally.
 - In servers, use names naturally.