talon-agent 3.25.0 → 3.25.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,14 +4,16 @@
|
|
|
4
4
|
|
|
5
5
|
# Talon
|
|
6
6
|
|
|
7
|
-
[](https://nodejs.org)
|
|
8
|
+
[](https://bun.sh)
|
|
9
|
+
[](https://www.typescriptlang.org/)
|
|
10
|
+
[](#frontends)
|
|
9
11
|
[](#backends)
|
|
10
12
|
[](LICENSE)
|
|
11
13
|
[](https://github.com/dylanneve1/talon/actions/workflows/ci.yml)
|
|
12
14
|
[](https://github.com/sponsors/dylanneve1)
|
|
13
15
|
|
|
14
|
-
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.
|
|
16
|
+
Multi-platform agentic AI harness. Runs on **Telegram**, **WhatsApp**, **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.
|
|
15
17
|
|
|
16
18
|
---
|
|
17
19
|
|
|
@@ -19,7 +21,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
|
|
|
19
21
|
|
|
20
22
|
| | |
|
|
21
23
|
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
-
| **Multi-frontend** | Telegram (
|
|
24
|
+
| **Multi-frontend** | Telegram (grammY + GramJS userbot), WhatsApp (Baileys multi-device), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility, and a **Desktop/Mobile app** (Flutter) over a local/remote bridge — one or several at once, see [Frontends](#frontends) |
|
|
23
25
|
| **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex, OpenAI Agents — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
|
|
24
26
|
| **MCP tools** | Messaging, media, history, search, web fetch, cron jobs, triggers, goals, stickers, file system, admin controls |
|
|
25
27
|
| **Plugins** | Hot-reloadable plugin system with `talon plugin install/enable/disable` (npm, git, or local sources). Built-in: GitHub, MemPalace, Playwright, Brave Search |
|
|
@@ -51,7 +53,12 @@ npx talon chat # terminal chat mode
|
|
|
51
53
|
|
|
52
54
|
**Prerequisites:**
|
|
53
55
|
|
|
54
|
-
- [Node.js 24+](https://nodejs.org/)
|
|
56
|
+
- [Bun 1.3+](https://bun.sh) **or** [Node.js 24+](https://nodejs.org/). Talon ships as
|
|
57
|
+
TypeScript sources and runs them directly: Bun executes them natively, Node goes
|
|
58
|
+
through a `tsx` loader. The `talon` launcher detects which runtime started it, so
|
|
59
|
+
either works with no configuration — `npm start` / `npm run dev` take the Bun path,
|
|
60
|
+
`npm run start:node` / `npm run dev:node` the Node one. Bun is what the release
|
|
61
|
+
binaries and the maintained deployment run on; Node stays supported.
|
|
55
62
|
- Backend-specific:
|
|
56
63
|
- `claude` backend: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI on PATH).
|
|
57
64
|
- `kilo` backend: nothing extra — `@kilocode/sdk` spawns a local server. Free models are accessible without auth; routed models use Kilo's own credentials.
|
|
@@ -81,9 +88,11 @@ Verify a direct download against the release `SHA256SUMS`:
|
|
|
81
88
|
`sha256sum -c SHA256SUMS --ignore-missing`.
|
|
82
89
|
|
|
83
90
|
> The binary runs the full interactive/agent CLI (`setup`, `start`, `chat`,
|
|
84
|
-
> `doctor`, …)
|
|
85
|
-
>
|
|
86
|
-
>
|
|
91
|
+
> `doctor`, …) and supervises MCP children like any other install shape. The one
|
|
92
|
+
> gap: a plugin shipping its MCP server as TypeScript source (`mcpServerPath`)
|
|
93
|
+
> needs a runtime that can execute TS, which a compiled binary is not — those
|
|
94
|
+
> want the npm install. Plugins declaring an explicit `mcpServer` command work
|
|
95
|
+
> everywhere.
|
|
87
96
|
|
|
88
97
|
---
|
|
89
98
|
|
|
@@ -93,17 +102,30 @@ Verify a direct download against the release `SHA256SUMS`:
|
|
|
93
102
|
index.ts Composition root
|
|
94
103
|
|
|
|
95
104
|
+-- core/ Platform-agnostic engine
|
|
96
|
-
| +-- agent-runtime/ Backend capability
|
|
105
|
+
| +-- agent-runtime/ Backend capability interface, events, stores
|
|
106
|
+
| +-- frontend-runtime/ Frontend capability interface + descriptor registry
|
|
97
107
|
| +-- models/ Model layer: catalog, per-chat active model,
|
|
98
108
|
| | reasoning-effort vocabulary
|
|
99
109
|
| +-- prompt/ System-prompt assembly + prompts/system templates
|
|
100
110
|
| +-- background/ Agents that run without a user message:
|
|
101
111
|
| | heartbeat, dream, pulse, cron, triggers
|
|
102
112
|
| +-- tools/ MCP tool definitions + spawn/env contract
|
|
113
|
+
| +-- mcp-hub/ Daemon-hosted MCP over streamable HTTP; supervises
|
|
114
|
+
| | stdio children with respawn-and-backoff
|
|
103
115
|
| +-- engine/ Message flow: dispatcher (per-chat serial,
|
|
104
116
|
| | cross-chat parallel), HTTP gateway for MCP
|
|
105
117
|
| | tool calls, backend lifecycle controller
|
|
106
|
-
| +--
|
|
118
|
+
| +-- weaver/ Per-chat live state: a Weaver owns Looms own Threads
|
|
119
|
+
| +-- tasks/ Task table — the process table for agent work
|
|
120
|
+
| +-- bus/ Typed pub-sub spine + event journal
|
|
121
|
+
| +-- vfs/ The talon:// namespace (~/.talon/ns), FUSE-backed
|
|
122
|
+
| +-- mesh/ Device mesh: presence, exec/fs channel, teleport
|
|
123
|
+
| +-- soul/ Soul kernel — associative recall over memory
|
|
124
|
+
| +-- scripts/ Run-to-completion execution of saved scripts
|
|
125
|
+
| +-- scripting/ WASM-sandboxed Lua runner for trigger scripts
|
|
126
|
+
| +-- daemon/ Start / stop / restart, pidfile, discovery
|
|
127
|
+
| +-- plugin/ Plugin loader, registry, hot-reload
|
|
128
|
+
| +-- update/ Self-update for git-checkout deployments
|
|
107
129
|
|
|
|
108
130
|
+-- backend/
|
|
109
131
|
| +-- registry.ts Bootstrap-decoupled backend lookup
|
|
@@ -119,16 +141,21 @@ index.ts Composition root
|
|
|
119
141
|
| +-- openai-agents/ OpenAI Agents SDK backend (Responses API)
|
|
120
142
|
|
|
|
121
143
|
+-- frontend/
|
|
144
|
+
| +-- factories.ts Attaches each built-in's lazy `create`
|
|
122
145
|
| +-- shared/ Cross-frontend presentation helpers
|
|
123
|
-
| +-- telegram/
|
|
146
|
+
| +-- telegram/ grammY bot + GramJS userbot
|
|
147
|
+
| +-- whatsapp/ Baileys multi-device socket
|
|
124
148
|
| +-- discord/ discord.js v14
|
|
125
149
|
| +-- teams/ Bot Framework + Graph API
|
|
126
150
|
| +-- terminal/ Readline CLI with tool call visibility
|
|
127
|
-
| +--
|
|
151
|
+
| +-- native/ Client bridge (HTTP + SSE) for the companion app
|
|
128
152
|
|
|
|
129
|
-
+--
|
|
130
|
-
|
|
|
131
|
-
|
|
153
|
+
+-- native/ WASM + napi cores (blake3, strsim, textops, sqlguard,
|
|
154
|
+
| htmlents, scheduler, fusefs, warden), each with a
|
|
155
|
+
| pure-TS or wasm fallback
|
|
156
|
+
+-- storage/ SQLite layer: sessions, history, chat settings, cron,
|
|
157
|
+
| media index, metrics, goals, skills, kv, daily logs
|
|
158
|
+
+-- util/ Config, logging, workspace, paths, time, runtime
|
|
132
159
|
```
|
|
133
160
|
|
|
134
161
|
**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`. Frontends mirror this: each implements the `Frontend` contract from `core/frontend-runtime/capabilities.ts` and self-registers in the frontend registry (identity + chat-id routing in a descriptor, lazy `create` in a per-frontend `factory.ts`) — see [docs/frontends.md](docs/frontends.md). Kilo and OpenCode additionally share the `remote-server/` infrastructure because they wrap forks of the same upstream HTTP agent server.
|
|
@@ -137,6 +164,54 @@ index.ts Composition root
|
|
|
137
164
|
|
|
138
165
|
---
|
|
139
166
|
|
|
167
|
+
## Frontends
|
|
168
|
+
|
|
169
|
+
Select via the `frontend` field in `~/.talon/config.json` — one id, or an array to run several at once. Every frontend implements the same `Frontend` contract and registers a descriptor (identity + which chat ids it owns) in the frontend registry, so a chat id routes to its owning frontend with no central switch — see [docs/frontends.md](docs/frontends.md).
|
|
170
|
+
|
|
171
|
+
| Frontend | `frontend` value | Transport | Notes |
|
|
172
|
+
| ---------- | ---------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
173
|
+
| Telegram | `"telegram"` | grammY long-poll (+ optional GramJS userbot) | The widest surface: inline keyboards, reactions, media groups, stickers, polls, admin commands. `apiId` / `apiHash` add userbot history access. |
|
|
174
|
+
| WhatsApp | `"whatsapp"` | Baileys multi-device (WebSocket) | Drives a real WhatsApp account, paired by phone code or QR. Media, reactions, edits, deletes, forwards, polls, locations, contacts, group admin. |
|
|
175
|
+
| Discord | `"discord"` | discord.js v14 gateway | Slash commands, guild / channel allowlists, presence text. |
|
|
176
|
+
| Teams | `"teams"` | Bot Framework + Graph API | Inbound over a Power Automate webhook, outbound over Graph. |
|
|
177
|
+
| Terminal | `"terminal"` | Local readline | Always available via `talon chat`, even when another frontend is configured. Live tool-call visibility. |
|
|
178
|
+
| Native | `"native"` | HTTP + Server-Sent Events bridge | The protocol the Flutter companion app speaks — see [Desktop & mobile app](#desktop--mobile-app). |
|
|
179
|
+
|
|
180
|
+
Running several is just an array; each chat id keeps its own session and the frontend that owns it answers:
|
|
181
|
+
|
|
182
|
+
```jsonc
|
|
183
|
+
{ "frontend": ["telegram", "whatsapp", "native"] }
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### WhatsApp
|
|
187
|
+
|
|
188
|
+
The WhatsApp frontend drives a real WhatsApp account over Baileys multi-device — the same mechanism as WhatsApp Web, so no Business API account is involved.
|
|
189
|
+
|
|
190
|
+
```jsonc
|
|
191
|
+
// ~/.talon/config.json
|
|
192
|
+
{
|
|
193
|
+
"frontend": "whatsapp",
|
|
194
|
+
"whatsapp": {
|
|
195
|
+
// The bot account's own number, E.164 digits, no "+". Omit for QR pairing.
|
|
196
|
+
"pairingNumber": "353871234567",
|
|
197
|
+
// Who may DM it — bare numbers or full JIDs. Empty disables DMs.
|
|
198
|
+
"allowedJids": ["353834733284"],
|
|
199
|
+
// Which groups it serves: "listed" | "with-allowed-user" | "all"
|
|
200
|
+
"groupPolicy": "with-allowed-user",
|
|
201
|
+
// In groups: reply only when mentioned/quoted, or to everything
|
|
202
|
+
"respondMode": "mention"
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
First start prints a pairing code (or a QR when `pairingNumber` is omitted) — enter it under **WhatsApp → Linked devices → Link with phone number**. Credentials persist in `~/.talon/whatsapp-auth/`, so later starts reconnect on their own, with backoff across drops.
|
|
208
|
+
|
|
209
|
+
`groupPolicy: "with-allowed-user"` is the useful middle setting: the bot serves any group containing someone from `allowedJids` — "the groups I'm in" — without listing group JIDs by hand.
|
|
210
|
+
|
|
211
|
+
Markdown from the model is translated into WhatsApp's own dialect (`*bold*`, `_italic_`, `~strike~`, monospace blocks) by walking the parsed token tree rather than by regex, and long replies split on message boundaries instead of truncating.
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
140
215
|
## Backends
|
|
141
216
|
|
|
142
217
|
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.
|
|
@@ -155,20 +230,23 @@ The Kilo and OpenCode backends share infrastructure (`backend/remote-server/`) s
|
|
|
155
230
|
|
|
156
231
|
## Desktop & mobile app
|
|
157
232
|
|
|
158
|
-
The `
|
|
233
|
+
The `native` frontend turns the daemon into a **client bridge** — a versioned HTTP + Server-Sent-Events JSON API (the _Talon Client Bridge Protocol_, `src/frontend/native/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**. The protocol has three independent implementations (daemon, companion, [talon-node](apps/node/)); shared wire fixtures in [protocol/](protocol/) are replayed by all three test suites so a drift on any side fails its CI — see [protocol/README.md](protocol/README.md).
|
|
159
234
|
|
|
160
235
|
```jsonc
|
|
161
236
|
// ~/.talon/config.json
|
|
162
237
|
{
|
|
163
|
-
"frontend": "
|
|
164
|
-
"
|
|
238
|
+
"frontend": "native",
|
|
239
|
+
"native": { "host": "127.0.0.1", "port": 19880 }
|
|
165
240
|
// For remote (e.g. a phone): "host": "0.0.0.0", "token": "your-secret"
|
|
166
241
|
}
|
|
167
242
|
```
|
|
168
243
|
|
|
244
|
+
> The old `"desktop"` spelling still loads — config normalization rewrites it to
|
|
245
|
+
> `"native"` and logs a deprecation — but new configs should say `native`.
|
|
246
|
+
|
|
169
247
|
- **Local (desktop):** the app connects to a Talon on the same machine and launches one if needed (`TALON_FRONTEND_OVERRIDE=desktop`).
|
|
170
248
|
- **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.
|
|
171
|
-
- **Encryption:** off-loopback binds serve **HTTPS by default** with a persistent self-signed certificate (`~/.talon/keys/`); the companion pins its SHA-256 fingerprint on first connect and refuses any change afterwards. The daemon logs the fingerprint at startup and `/health` advertises it. Opt out (or in, on loopback) with `"tls": false` / `true` in the `
|
|
249
|
+
- **Encryption:** off-loopback binds serve **HTTPS by default** with a persistent self-signed certificate (`~/.talon/keys/`); the companion pins its SHA-256 fingerprint on first connect and refuses any change afterwards. The daemon logs the fingerprint at startup and `/health` advertises it. Opt out (or in, on loopback) with `"tls": false` / `true` in the `native` section.
|
|
172
250
|
|
|
173
251
|
The app provides multi-chat history, live streaming with reasoning + tool-call visibility, per-chat model/effort/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).
|
|
174
252
|
|
|
@@ -358,11 +436,19 @@ Plugins support hot-reload via the `reload_plugins` MCP tool --- no restart requ
|
|
|
358
436
|
## CLI
|
|
359
437
|
|
|
360
438
|
```
|
|
361
|
-
talon
|
|
439
|
+
talon Interactive menu (runs setup on first launch)
|
|
440
|
+
talon setup Guided setup wizard
|
|
362
441
|
talon start Start as a background daemon
|
|
363
442
|
talon stop Stop the daemon
|
|
443
|
+
talon restart Restart the daemon
|
|
444
|
+
talon run Run in the foreground, attached
|
|
364
445
|
talon chat Terminal chat mode (always available)
|
|
365
|
-
talon status Health, sessions, plugins, disk usage
|
|
446
|
+
talon status Health, sessions, plugins, runtime, disk usage
|
|
447
|
+
talon ps List agent tasks (--all includes journal history)
|
|
448
|
+
talon kill Abort a killable task by id
|
|
449
|
+
talon events Tail the event bus (-f follows, --history [N] reads the journal)
|
|
450
|
+
talon plugin Manage plugins (install / enable / disable / remove)
|
|
451
|
+
talon skill Manage skills (install / enable / disable / remove)
|
|
366
452
|
talon config View or edit configuration
|
|
367
453
|
talon logs Tail structured log file
|
|
368
454
|
talon doctor Validate environment and dependencies
|
|
@@ -376,7 +462,7 @@ Config file: `~/.talon/config.json`
|
|
|
376
462
|
|
|
377
463
|
| Field | Default | Description |
|
|
378
464
|
| -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
|
379
|
-
| `frontend` | `"telegram"` | `"telegram"`, `"discord"`, `"teams"`, `"terminal"`, or an array
|
|
465
|
+
| `frontend` | `"telegram"` | `"telegram"`, `"whatsapp"`, `"discord"`, `"teams"`, `"terminal"`, `"native"`, or an array ([Frontends](#frontends)) |
|
|
380
466
|
| `backend` | `"claude"` | `"claude"`, `"kilo"`, `"opencode"`, `"codex"`, or `"openai-agents"` |
|
|
381
467
|
| `botToken` | --- | Telegram bot token |
|
|
382
468
|
| `model` | `"default"` | Default model. Interpretation depends on the active backend. |
|
|
@@ -397,6 +483,11 @@ Config file: `~/.talon/config.json`
|
|
|
397
483
|
| `adminUserId` | --- | Telegram user ID for `/admin` commands |
|
|
398
484
|
| `allowedUsers` | --- | Whitelist of Telegram user IDs |
|
|
399
485
|
| `apiId` / `apiHash` | --- | Telegram API credentials for full message history |
|
|
486
|
+
| `whatsapp` | --- | WhatsApp frontend: pairing, allowlists, group policy ([above](#whatsapp)) |
|
|
487
|
+
| `discord` | --- | Discord frontend: bot token, application ID, guild / channel allowlists |
|
|
488
|
+
| `native` | --- | Client bridge: host, port, token, TLS ([above](#desktop--mobile-app)) |
|
|
489
|
+
| `nativeTools` | `false` | Swap the SDK's built-in Read/Write/Edit/Bash/Glob/Grep for Talon's own — these also route to a teleported device |
|
|
490
|
+
| `fuse` | `"auto"` | Mount the `talon://` namespace with FUSE live views; falls back to a symlink farm where the host can't |
|
|
400
491
|
| `github` | --- | GitHub plugin config (see above) |
|
|
401
492
|
| `memory` | --- | Long-term memory backend selection: `mempalace` or `mem0` (see above) |
|
|
402
493
|
| `mempalace` | --- | Legacy MemPalace plugin config (prefer `memory`) |
|
|
@@ -424,7 +515,7 @@ npx talon chat
|
|
|
424
515
|
|
|
425
516
|
Tool calls shown in real-time with parameters. Streaming phase indicators (thinking / responding / using tools). Per-turn stats: duration, tokens, cache hit rate, tool count.
|
|
426
517
|
|
|
427
|
-
Commands: `/model`, `/effort`, `/
|
|
518
|
+
Commands: `/model`, `/effort`, `/context`, `/status`, `/reset`, `/rename`, `/resume`, `/help`, `/quit`
|
|
428
519
|
|
|
429
520
|
---
|
|
430
521
|
|
|
@@ -449,14 +540,21 @@ docker compose up -d
|
|
|
449
540
|
## Development
|
|
450
541
|
|
|
451
542
|
```bash
|
|
452
|
-
npm run dev # watch mode
|
|
453
|
-
npm
|
|
543
|
+
npm run dev # watch mode (Bun)
|
|
544
|
+
npm run dev:node # watch mode (Node + tsx)
|
|
545
|
+
npm test # 4500+ tests across unit / SDK-stub / MCP-functional / integration tiers
|
|
454
546
|
npm run test:coverage # with coverage report
|
|
455
547
|
npm run typecheck # tsc --noEmit
|
|
456
548
|
npm run lint # oxlint
|
|
457
549
|
npm run format # prettier --write
|
|
550
|
+
npm run depcruise # dependency-cruiser — enforces the core/ import rule
|
|
551
|
+
npm run knip # unused files, exports, and dependencies
|
|
458
552
|
```
|
|
459
553
|
|
|
554
|
+
CI runs the full suite on Node 24 across Linux, macOS, and Windows; a separate
|
|
555
|
+
job compiles the standalone `bun build --compile` binary on all three and
|
|
556
|
+
smoke-tests the CLI and the MCP supervisor from it.
|
|
557
|
+
|
|
460
558
|
---
|
|
461
559
|
|
|
462
560
|
## Support
|