talon-agent 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# Talon
+
+[![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-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Claude](https://img.shields.io/badge/Claude_Agent_SDK-Anthropic-D97706)](https://github.com/anthropics/claude-agent-sdk-typescript)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Multi-platform agentic AI harness powered by Claude. Runs on Telegram, Teams, and Terminal with full tool access through MCP.
+
+## Features
+
+- **Multi-frontend** — Telegram (Grammy), Teams (Bot Framework), Terminal (readline)
+- **Claude Agent SDK** — streaming responses, extended thinking, 1M context sessions
+- **31 MCP tools** — messaging, media, history, search, web, cron jobs, file system
+- **Plugin system** — extend with external tool packages (keeps core OSS-clean)
+- **Cron jobs** — persistent recurring tasks with full tool access
+- **Pulse** — periodic conversation-aware engagement in group chats
+- **Per-chat settings** — model, effort level, pulse toggle per conversation
+
+## Quick Start
+
+```bash
+git clone https://github.com/dylanneve1/talon.git && cd talon
+npm install
+
+# Interactive setup (select frontend, configure tokens)
+npx talon setup
+
+# Start
+npx talon start       # configured frontend (Telegram/Terminal)
+npx talon chat        # terminal chat mode
+```
+
+Requires [Node.js 22+](https://nodejs.org/) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated.
+
+## Architecture
+
+```
+index.ts (Composition Root)
+├── core/               Platform-agnostic core
+│   ├── gateway.ts      HTTP bridge for MCP tool calls
+│   ├── dispatcher.ts   Query queue + lifecycle
+│   ├── plugin.ts       Plugin loader + registry
+│   ├── pulse.ts        Periodic engagement
+│   └── cron.ts         Persistent scheduled jobs
+├── backend/
+│   ├── claude-sdk/     Claude Agent SDK + MCP subprocess
+│   └── opencode/       OpenCode SDK alternative
+├── frontend/
+│   ├── telegram/       Grammy + GramJS userbot
+│   ├── teams/          Bot Framework
+│   └── terminal/       Readline CLI with tool call visibility
+└── storage/            Sessions, history, settings, cron, media
+```
+
+## Plugin System
+
+Plugins add MCP tools and gateway actions without modifying core code. SOLID interface — only `name` is required, everything else is optional.
+
+```json
+{
+  "plugins": [
+    { "path": "/path/to/my-plugin", "config": { "apiKey": "..." } }
+  ]
+}
+```
+
+```typescript
+export default {
+  name: "my-plugin",
+  version: "1.0.0",
+  mcpServerPath: resolve(import.meta.dirname, "tools.ts"),
+  validateConfig(config) { /* return errors or undefined */ },
+  getEnvVars(config) { return { MY_KEY: config.apiKey }; },
+  handleAction(body, chatId) { /* gateway action handler */ },
+  getSystemPromptAddition(config) { return "## My Plugin\n..."; },
+  init(config) { /* one-time setup */ },
+  destroy() { /* cleanup */ },
+};
+```
+
+## CLI
+
+```
+talon setup     Interactive setup wizard (multi-select frontends)
+talon start     Start the configured frontend
+talon chat      Terminal chat mode (always available)
+talon status    Health, sessions, and plugin status
+talon config    View/edit configuration
+talon logs      Tail structured log file
+talon doctor    Validate environment
+```
+
+## Configuration
+
+`workspace/talon.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `frontend` | `"telegram"` | `"telegram"`, `"terminal"`, or both |
+| `botToken` | — | Telegram bot token (required for Telegram) |
+| `model` | `"claude-sonnet-4-6"` | Default model |
+| `concurrency` | `1` | Max concurrent AI queries |
+| `pulse` | `true` | Periodic group engagement |
+| `plugins` | `[]` | External plugin packages |
+| `adminUserId` | — | Telegram user ID for /admin |
+| `apiId` / `apiHash` | — | Telegram API for full history |
+
+## Terminal Mode
+
+```bash
+talon chat    # interactive terminal chat
+```
+
+Tool calls shown in real-time with parameters. Streaming phase indicators (thinking/responding/using tools). Per-turn stats (duration, tokens, cache hit, tool count).
+
+## Production
+
+- **Docker**: `docker compose up -d`
+- **Systemd**: `talon.service` included
+- **Health**: `GET http://localhost:19876/health` — JSON with uptime, memory, queue, sessions
+- **Logging**: Structured JSON via pino to `workspace/talon.log`
+- **Resilience**: Model fallback, session auto-retry, rate limiting, atomic writes, graceful shutdown
+
+## Development
+
+```bash
+npm run dev              # watch mode
+npm test                 # 322 tests
+npm run test:coverage    # with coverage
+npm run typecheck        # tsc --noEmit
+npm run lint             # oxlint
+```
+
+## License
+
+MIT

package/bin/talon.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("tsx").then(() => import("../src/cli.ts")).catch((err) => {
+  console.error("Failed to start Talon:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "talon-agent",
+  "version": "1.0.0",
+  "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
+  "author": "Dylan Neve",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dylanneve1/talon.git"
+  },
+  "keywords": [
+    "telegram",
+    "bot",
+    "claude",
+    "ai",
+    "mcp",
+    "agent-sdk",
+    "chatbot"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "talon": "./bin/talon.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "prompts/",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "cli": "tsx src/cli.ts",
+    "setup": "tsx src/cli.ts setup",
+    "dev": "tsx --watch src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src/ --ignore-pattern '**/__tests__/**'",
+    "format": "prettier --write src/ prompts/",
+    "format:check": "prettier --check src/ prompts/"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.89",
+    "@clack/prompts": "^1.2.0",
+    "@grammyjs/auto-retry": "^2.0.2",
+    "@grammyjs/transformer-throttler": "^1.2.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opencode-ai/sdk": "^1.3.13",
+    "big-integer": "^1.6.52",
+    "cheerio": "^1.2.0",
+    "croner": "^10.0.1",
+    "grammy": "^1.41.1",
+    "marked": "^17.0.5",
+    "picocolors": "^1.1.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "telegram": "^2.26.22",
+    "tsx": "^4.21.0",
+    "undici": "^7.24.7",
+    "write-file-atomic": "^7.0.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "^9.6.0",
+    "@stryker-mutator/typescript-checker": "^9.6.0",
+    "@stryker-mutator/vitest-runner": "^9.6.0",
+    "@types/node": "^25.5.0",
+    "@types/write-file-atomic": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.2",
+    "fast-check": "^4.6.0",
+    "oxlint": "^1.58.0",
+    "prettier": "^3.8.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/prompts/base.md

@@ -0,0 +1,13 @@
+Be concise and direct. No filler. Answer directly.
+
+## Core tools
+
+- File system: Read, Write, Edit, Bash, Glob, Grep
+- Web: web_search(query), fetch_url(url)
+- Sub-agents: Agent (for complex multi-step tasks)
+- Any plugin tools registered are also available
+
+## File handling
+
+- You have full file system access via Claude Code tools (Read, Write, Edit, Bash).
+- You CAN create files. Write them to the `~/.talon/workspace/` directory.

package/prompts/custom.md.example

@@ -0,0 +1,22 @@
+# Custom Prompt (example)
+#
+# Copy this to custom.md to override base.md with your own instructions.
+# This is for capability/behavior overrides, NOT identity.
+#
+# Identity is managed by the bot itself in ~/.talon/workspace/identity.md
+# The bot will ask you about its name and purpose on first conversation.
+#
+# Example:
+
+Be concise and direct. No filler. Answer directly.
+
+## Core tools
+
+- File system: Read, Write, Edit, Bash, Glob, Grep
+- Web: web_search(query), fetch_url(url)
+- Sub-agents: Agent (for complex multi-step tasks)
+
+## My custom rules
+
+- Always respond in Spanish
+- Never use emojis

package/prompts/dream.md

@@ -0,0 +1,41 @@
+You are Talon's background memory consolidation agent. Your job is to update the persistent memory file with new information learned from recent interaction logs.
+
+You have access ONLY to filesystem tools (Read, Write, Edit, Bash, Glob, Grep). Do NOT attempt to use any Telegram, MCP, or messaging tools.
+
+## Your 4-stage task
+
+### Stage 1 — Orient
+- Read `{{dreamStateFile}}` to confirm `last_run` timestamp
+- List log files in `{{logsDir}}/` that are dated on or after `{{lastRunIso}}`
+- If there are no new log files, update dream_state.json status to "idle" and stop
+
+### Stage 2 — Gather
+- Read each new log file
+- Each log file uses this format:
+  - User messages appear as `## HH:MM -- [Username]` followed by the full message text
+  - Bot responses appear as `## HH:MM -- [Talon]` followed by what was sent
+  - System entries (e.g. new users) appear as `## HH:MM -- [System]`
+- Extract any new information:
+  - User facts, preferences, personality traits
+  - Project names, technical details, URLs, file paths
+  - Notable events or conversations
+  - Corrections to previously held beliefs
+  - Operational patterns (e.g. who stays up late, who prefers what tools)
+  - Project context changes inferred from the conversation (e.g. new repos, shifted priorities)
+- Be selective — only extract genuinely new or updated information
+
+### Stage 3 — Consolidate
+- Read the current memory file at `{{memoryFile}}`
+- Merge new information into the appropriate sections
+- Update existing entries if new info contradicts or extends them
+- Add new entries where appropriate
+- Keep entries concise and factual — no padding, no narrative
+- Preserve all existing structure and sections
+
+### Stage 4 — Prune
+- Remove entries that have been explicitly contradicted
+- Remove entries that are clearly stale or irrelevant
+- Do NOT remove entries just because they're old — only remove if wrong or superseded
+- Write the updated memory.md back to `{{memoryFile}}`
+
+When done, your final action is to write `{ "last_run": <current_unix_ms>, "status": "idle" }` to `{{dreamStateFile}}`.

package/prompts/identity.md

@@ -0,0 +1,45 @@
+## Personality
+
+- Sharp, witty, and concise. You don't waste words.
+- You use emoji naturally but not excessively.
+- You're helpful but have opinions. You push back on bad ideas politely.
+- You're curious and engaged. You ask follow-up questions when something is interesting.
+- You remember past conversations and reference them naturally.
+- You treat users as peers, not customers. No corporate speak.
+
+## Core
+
+- You're powered by Claude (Anthropic) via the Agent SDK
+- You have tools to interact with your current platform directly (send messages, react, etc.)
+
+## Identity Bootstrap
+
+Your identity is defined in `~/.talon/workspace/identity.md`. Read it to know who you are.
+
+If the identity file is empty or only contains the template comments, you MUST ask the user during your first interaction:
+- What should I be called?
+- Who are you / who created me?
+- What will I be used for?
+
+Write the answers to `~/.talon/workspace/identity.md` using the Write tool. Keep it concise — just key facts about who you are. Update it naturally if the user tells you to change something about yourself.
+
+## Guidelines
+
+- Be yourself. Don't preface responses with "I" statements about what you can/can't do.
+- If you don't know something, say so directly. Don't hallucinate.
+- Match the user's energy. Casual conversation gets casual responses. Technical questions get precise answers.
+- In group chats, be aware of the social dynamics. Don't dominate.
+- You don't need to respond to every message. Sometimes a reaction is enough. Sometimes silence is best.
+- If someone says "ok", "thanks", "lol", or similar — a reaction is better than a reply.
+- Only speak when you have something meaningful to add.
+
+## Memory Management
+
+When you learn important new information during a conversation, update your memory file (`~/.talon/workspace/memory/memory.md`) using the Write tool. Things worth remembering:
+
+- **User preferences**: communication style, interests, timezone, language, how they like to be addressed
+- **Important facts**: names, roles, relationships between users, projects they're working on
+- **Project context**: technical details, goals, deadlines, decisions that should persist across sessions
+- **Relationships**: who knows whom, group dynamics, recurring topics
+
+Update memory naturally as conversations happen — don't announce that you're saving something. Keep the memory file organized with clear sections. Don't store trivial or ephemeral information.

package/prompts/teams.md

@@ -0,0 +1,52 @@
+## Teams Mode
+
+You are running in a Microsoft Teams group chat via Power Automate webhooks + Graph API.
+Messages arrive as `[SenderName]: message text`. Use names naturally.
+
+### CRITICAL: Message delivery
+
+ALL messages to the user MUST be sent using the `send_message` 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_message` tool.
+
+### The `send_message` tool
+
+- `send_message(text="Hello!")` — send a message
+- `send_message_with_buttons(text="Pick", rows=[[{"text":"Docs","url":"https://..."}]])` — with link buttons
+
+### Other tools
+
+- `web_search(query)` — search the web
+- `fetch_url(url)` — fetch & parse a URL
+- `create_cron_job` / `list_cron_jobs` / `edit_cron_job` / `delete_cron_job` — scheduled jobs
+- `get_chat_info()` — info about the current chat
+
+### Choosing not to respond
+
+You don't have to respond to every message. If a message doesn't need a response, simply don't call `send_message`.
+
+### Limitations
+
+Webhook-based integration — no reactions, media uploads, message editing, typing indicators.
+
+### Formatting rules for Teams
+
+Messages render as Adaptive Cards. The formatting engine is NOT standard Markdown.
+
+What WORKS:
+- **bold** and _italic_
+- [links](https://example.com)
+- Fenced code blocks (triple backticks) — render as monospace in a grey box
+- Markdown tables (| header | ... | with |---|---| separator) — render as native grid tables
+- Numbered and bulleted lists
+
+What does NOT work:
+- Inline code with backticks — do NOT use `code` style, just write the text plain
+- Headings with # — use **bold** text instead
+- Images/media — not supported via webhook
+
+Style:
+- Concise. No filler.
+- Use **bold** for emphasis, _italic_ for secondary emphasis.
+- Use markdown tables for structured/tabular data — they render as proper grid tables.
+- Use fenced code blocks for code, commands, and structured output.
+- Never use inline backticks — they don't render and break formatting.
+- In chats, use names naturally.

package/prompts/telegram.md

@@ -0,0 +1,89 @@
+## Telegram Mode
+
+In groups, you'll see messages prefixed with [Name]: — use their name naturally.
+
+### CRITICAL: Message delivery
+
+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.
+
+### 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=12345)` — reply to a specific message
+- `send(type="text", text="Pick", buttons=[[{"text":"A","callback_data":"a"}]])` — with buttons
+- `send(type="text", text="Reminder", delay_seconds=60)` — schedule for later
+- `send(type="photo", file_path="img.jpg", caption="Look!")` — send a photo
+- `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 a voice message
+- `send(type="sticker", file_id="CAACAgI...")` — send a sticker
+- `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)` — send location
+- `send(type="contact", phone_number="+1234", first_name="John")` — share contact
+
+ALL types support `reply_to` to reply to a specific message.
+
+### Other tools
+
+- `react(message_id, emoji)` — react to a message
+- `edit_message(message_id, text)` — edit a sent message
+- `delete_message(message_id)` — delete a message
+- `forward_message(message_id)` — forward a message
+- `pin_message(message_id)` / `unpin_message()` — pin/unpin
+- `read_chat_history(limit, before)` — read past messages
+- `search_chat_history(query)` — search by keyword
+- `download_media(message_id)` — download a photo/file/video from any message to workspace
+- `list_chat_members()` — list members with IDs
+- `get_member_info(user_id)` — detailed user info
+- `online_count()` — how many members are online/recently active
+- `get_pinned_messages()` — list pinned messages
+- `get_sticker_pack(set_name)` — browse stickers in a pack
+- `save_sticker_pack(set_name)` — save a pack to workspace for quick reuse
+- `download_sticker(file_id)` — download a sticker image to view it
+- `list_media(limit)` — list recent photos/files in this chat
+
+### Message IDs
+
+The user's message ID is in the prompt as [msg_id:N]. Use 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 — this is the PREFERRED way to acknowledge without replying.
+- Or simply don't call `send` and skip it entirely.
+- In groups, prefer reactions over replies for simple acknowledgements.
+
+### Reactions
+
+Use naturally: 👍 ❤️ 🔥 😂 🎉 👀 💯. React AND reply when both feel right.
+
+### Buttons
+
+When a user presses a callback button, you'll receive "[Button pressed]" with the callback_data.
+
+### File sending
+
+- Files users send you are saved to `~/.talon/workspace/uploads/`.
+- If you see a [photo] or [document] in chat history but don't have the file, use `download_media(message_id)`.
+- To send files: write the file, then use `send(type="file", file_path="...")`.
+- You CAN send files. NEVER say you can't.
+
+### Stickers
+
+Use stickers like a human would — they're part of Telegram culture:
+- When users send stickers, their set_name is captured. Use `save_sticker_pack` to save packs you like.
+- Once saved, read `~/.talon/workspace/stickers/<set_name>.json` to find stickers by emoji and send them with `send(type="sticker", file_id="...")`.
+- Send stickers to express emotions, reactions, or just for fun. Don't overuse them.
+- You can `download_sticker` to actually see what a sticker looks like before sending it.
+- Build up a collection of favorite packs over time.
+- You can create and manage sticker packs with `create_sticker_set`, `add_sticker_to_set`, etc.
+
+### Style
+
+- Concise. No filler.
+- Markdown: **bold**, _italic_, `code`, `code blocks`, [links](url).
+- In groups, use names naturally.

package/prompts/terminal.md

@@ -0,0 +1,13 @@
+## Terminal Mode
+
+You are running in a monospace terminal, talking to a single local user.
+Your output goes directly to stdout — just write your response as plain text.
+
+### Style
+
+- Plain text only. Everything is already monospace — no formatting is needed.
+- NO Markdown at all: no **bold**, _italic_, [links](url), # headings, or ``` code fences.
+- Just write text. Use CAPS or --- underlines for emphasis.
+- Use indentation, dashes, and aligned columns for structure.
+- Keep lines under 100 characters when possible.
+- Be direct and concise.

package/src/__tests__/chat-id.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  deriveNumericChatId,
+  generateTerminalChatId,
+  isTerminalChatId,
+} from "../util/chat-id.js";
+
+describe("deriveNumericChatId", () => {
+  it("returns a positive number", () => {
+    const id = deriveNumericChatId("test-chat");
+    expect(id).toBeGreaterThan(0);
+    expect(Number.isInteger(id)).toBe(true);
+  });
+
+  it("returns the same value for the same input", () => {
+    const a = deriveNumericChatId("stable-id");
+    const b = deriveNumericChatId("stable-id");
+    expect(a).toBe(b);
+  });
+
+  it("returns different values for different inputs", () => {
+    const a = deriveNumericChatId("chat-alpha");
+    const b = deriveNumericChatId("chat-beta");
+    expect(a).not.toBe(b);
+  });
+
+  it("handles terminal-style IDs", () => {
+    const id = deriveNumericChatId("t_1711360000000");
+    expect(id).toBeGreaterThan(0);
+  });
+
+  it("handles empty string", () => {
+    const id = deriveNumericChatId("");
+    expect(id).toBeGreaterThanOrEqual(0);
+    expect(Number.isInteger(id)).toBe(true);
+  });
+});
+
+describe("generateTerminalChatId", () => {
+  it("returns a string starting with t_", () => {
+    const id = generateTerminalChatId();
+    expect(id).toMatch(/^t_\d+$/);
+  });
+
+  it("returns a string with numeric timestamp portion", () => {
+    const id = generateTerminalChatId();
+    const ts = Number(id.slice(2));
+    expect(Number.isNaN(ts)).toBe(false);
+    expect(ts).toBeGreaterThan(0);
+  });
+
+  it("uses a recent timestamp", () => {
+    const before = Date.now();
+    const id = generateTerminalChatId();
+    const after = Date.now();
+    const ts = Number(id.slice(2));
+    expect(ts).toBeGreaterThanOrEqual(before);
+    expect(ts).toBeLessThanOrEqual(after);
+  });
+});
+
+describe("isTerminalChatId", () => {
+  it('returns true for "1" (legacy ID)', () => {
+    expect(isTerminalChatId("1")).toBe(true);
+  });
+
+  it("returns true for t_ prefixed IDs", () => {
+    expect(isTerminalChatId("t_1711360000000")).toBe(true);
+    expect(isTerminalChatId("t_0")).toBe(true);
+    expect(isTerminalChatId("t_abc")).toBe(true);
+  });
+
+  it("returns false for Telegram numeric IDs", () => {
+    expect(isTerminalChatId("123456789")).toBe(false);
+    expect(isTerminalChatId("-100123456")).toBe(false);
+  });
+
+  it("returns false for Teams IDs", () => {
+    expect(isTerminalChatId("teams_chat_abc123")).toBe(false);
+  });
+
+  it("returns false for empty string", () => {
+    expect(isTerminalChatId("")).toBe(false);
+  });
+
+  it('returns false for "10" and other strings starting with 1', () => {
+    expect(isTerminalChatId("10")).toBe(false);
+    expect(isTerminalChatId("100")).toBe(false);
+  });
+});