diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d037700d..816765ee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,15 +26,21 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 20 + node-version-file: .nvmrc cache: npm - name: Install dependencies run: npm ci + - name: Verify runtime contract + run: npm run check:runtime + - name: Build SDK workspace run: npm run build -w packages/sdk + - name: Verify SDK package contract + run: node scripts/check-sdk-package.mjs + - name: Type check run: npm run typecheck @@ -62,7 +68,7 @@ jobs: timeout-minutes: 25 strategy: matrix: - node-version: [20, 22] + node-version: ["22.22.2", "24.15.0"] steps: - uses: actions/checkout@v4 @@ -90,16 +96,16 @@ jobs: - name: Test with coverage run: npm run test:coverage + - name: Enforce SDK coverage + run: npm run test:sdk:coverage + - name: CLI smoke test run: node dist/cli/index.js --help - # ---- Telegram notification (after the full CI passes, pushes only) ---- - # dev : one message PER COMMIT, prefixed [DEV], paced 1/sec. - # main : one clean summary of how many stable commits were merged. - # Both walk the push range (before..after), not just the HEAD commit. + # ---- Telegram notification (one summary per push, pushes only) ---- notify: needs: [checks, test] - if: github.event_name == 'push' + if: always() && github.event_name == 'push' runs-on: ubuntu-latest timeout-minutes: 15 steps: @@ -111,33 +117,22 @@ jobs: env: TG_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }} TG_CHAT: ${{ secrets.TELEGRAM_CHAT_ID }} - REPO: ${{ github.repository }} BRANCH: ${{ github.ref_name }} - BEFORE: ${{ github.event.before }} - AFTER: ${{ github.sha }} + BEFORE_SHA: ${{ github.event.before }} + AFTER_SHA: ${{ github.event.after }} + CHECKS_RESULT: ${{ needs.checks.result }} + TEST_RESULT: ${{ needs.test.result }} run: | set -uo pipefail - ZERO=0000000000000000000000000000000000000000 - - # Resolve the commits in this push, oldest -> newest (merge commits excluded). - # Fallbacks (first push / force-push / unknown before) -> HEAD only. - if [ "$BEFORE" = "$ZERO" ] \ - || ! git cat-file -e "${BEFORE}^{commit}" 2>/dev/null \ - || ! git merge-base --is-ancestor "$BEFORE" "$AFTER" 2>/dev/null; then - SHAS=$(git log -1 --format=%H "$AFTER") - RANGE_OK=0 - else - SHAS=$(git log --reverse --no-merges --format=%H "${BEFORE}..${AFTER}") - RANGE_OK=1 - fi + NULL_SHA="0000000000000000000000000000000000000000" - COUNT=$(printf '%s\n' "$SHAS" | grep -c . || true) - if [ "$COUNT" -eq 0 ]; then echo "Nothing to notify"; exit 0; fi + if [ -z "$TG_TOKEN" ] || [ -z "$TG_CHAT" ]; then + echo "Telegram secrets not configured, skipping" + exit 0 + fi - esc() { printf '%s' "$1" | sed -e 's/&/\&/g' -e 's//\>/g'; } - # Send one message, retrying until Telegram accepts it. IMPORTANT: no - # curl --fail here ā€” on a 429 we must READ the body to get retry_after; - # --fail discards it, which silently drops rate-limited messages. + # Send one message, retrying until Telegram accepts it. Do not use + # curl --fail: a 429 body contains the retry_after value we need. send() { local text="$1" attempt resp ra for attempt in 1 2 3 4 5 6; do @@ -155,26 +150,42 @@ jobs: return 1 } - if [ "$BRANCH" = "main" ]; then - # Clean summary: number of stable commits merged to main. - noun="commits"; [ "$COUNT" -eq 1 ] && noun="commit" - if [ "$RANGE_OK" = 1 ]; then - link="https://github.com/${REPO}/compare/${BEFORE}...${AFTER}" + REPO_URL="${{ github.server_url }}/${{ github.repository }}" + + # One summary notification per push (avoid per-commit spam). + if [ -n "$BRANCH" ]; then + if [ "$BEFORE_SHA" = "$NULL_SHA" ] || ! git merge-base --is-ancestor "$BEFORE_SHA" "$AFTER_SHA" 2>/dev/null; then + COUNT=$(git rev-list --count "$AFTER_SHA") + RANGE="$AFTER_SHA" + URL="$REPO_URL/commits/$BRANCH" + else + COUNT=$(git rev-list --count "$BEFORE_SHA..$AFTER_SHA") + RANGE="$BEFORE_SHA..$AFTER_SHA" + URL="$REPO_URL/compare/$BEFORE_SHA...$AFTER_SHA" + fi + NOUN=commits; [ "$COUNT" = "1" ] && NOUN=commit + REPO_NAME=${REPO_URL##*/} + LABEL=$(printf '%s' "$BRANCH" | tr '[:lower:]' '[:upper:]') + TEXT="[$LABEL] $REPO_NAME" + if [ "$CHECKS_RESULT" = "success" ] && [ "$TEST_RESULT" = "success" ]; then + printf -v TEXT '%s\n%s %s pushed to %s' "$TEXT" "$COUNT" "$NOUN" "$BRANCH" else - link="https://github.com/${REPO}/commit/${AFTER}" + printf -v TEXT '%s\nCI failed on %s (%s %s)' "$TEXT" "$BRANCH" "$COUNT" "$NOUN" fi - send "šŸŸ¢ ${COUNT} stable ${noun} merged to main"$'\n'"View changes" - else - # Per-commit feed for dev (and any other non-main branch), [DEV] prefixed. - tag="[${BRANCH^^}]" + + # Commit titles (HTML-escaped), oldest first, capped to avoid huge messages. + MAX=50 + TITLES=$(git log --reverse --max-count="$MAX" --pretty=format:'%s' "$RANGE" \ + | sed -e 's/&/\&/g' -e 's//\>/g') if [ "$COUNT" -gt 1 ]; then - send "šŸ“¦ ${COUNT} commits pushed to ${BRANCH}" - sleep 1 + if [ "$COUNT" -gt "$MAX" ]; then + printf -v TITLES '%s\nā€¦ and %s more' "$TITLES" "$((COUNT - MAX))" + fi + # Multiple commits: collapse the title list into an expandable quote. + printf -v TEXT '%s\n\n
%s
' "$TEXT" "$TITLES" + elif [ -n "$TITLES" ]; then + printf -v TEXT '%s\n\n
%s
' "$TEXT" "$TITLES" fi - for sha in $SHAS; do - title=$(esc "$(git log -1 --format=%s "$sha")") - url="https://github.com/${REPO}/commit/${sha}" - send "${tag} ${title}"$'\n'"${sha:0:7}" - sleep 1 - done + printf -v TEXT '%s\n\nView commits' "$TEXT" "$URL" + send "$TEXT" fi diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 16b8adb6..c60842b2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 20 + node-version-file: .nvmrc cache: npm cache-dependency-path: | package-lock.json @@ -27,6 +27,7 @@ jobs: - run: npm ci - run: cd web && npm ci - run: npm run build -w packages/sdk + - run: node scripts/check-sdk-package.mjs - run: npm run typecheck - run: npm run build - run: node dist/cli/index.js --help @@ -34,6 +35,9 @@ jobs: - name: Run tests run: npx vitest run + - name: Enforce SDK coverage + run: npm run test:sdk:coverage + - uses: actions/upload-artifact@v4 with: name: dist @@ -52,7 +56,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 20 + node-version-file: .nvmrc registry-url: https://registry.npmjs.org cache: npm cache-dependency-path: | @@ -100,7 +104,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 20 + node-version-file: .nvmrc registry-url: https://registry.npmjs.org cache: npm @@ -117,7 +121,7 @@ jobs: echo "publish=false" >> "$GITHUB_OUTPUT" fi - - name: Install root deps (for @types/node hoisting) + - name: Install dependencies if: steps.check.outputs.publish == 'true' run: npm ci @@ -167,7 +171,7 @@ jobs: # ---- GitHub Release ---- create-release: - needs: [publish-npm] + needs: [publish-npm, publish-sdk, publish-docker] runs-on: ubuntu-latest timeout-minutes: 10 permissions: diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..b6f27f13 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +engine-strict=true diff --git a/.nvmrc b/.nvmrc index 209e3ef4..db49bb14 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -20 +22.22.2 diff --git a/CHANGELOG.md b/CHANGELOG.md index e9eaa06d..7097ecc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.0] - 2026-07-11 + +### Added + +- **GPT-5.6 Codex support** with Sol and Terra model resolution. Luna support is available only behind `TELETON_ENABLE_CODEX_LUNA=true` for controlled backend revalidation. +- **Validated Grok Build provider** with CLI authentication and runtime checks. +- **Claude Opus 4.8** in the shared model catalog. +- **Plugin SDK 2.1** with typed capability contracts, protected low-level TON sends, get-method execution, DeDust/STON.fi brokers, inline-bot operations, Highload Wallet support, isolated storage/secrets/database access, and explicit approval metadata for external actions. +- SDK package verification, coverage enforcement, and independent npm publication through the release workflow. + +### Changed + +- Migrated the LLM client from deprecated `@mariozechner/pi-ai` to maintained `@earendil-works/pi-ai`. +- Refactored the agent loop, application startup, onboarding, WebUI contracts, provider policy, DEX/DNS adapters, and SDK type surface into smaller shared modules. +- **Breaking:** raised the supported runtime baseline to Node.js `^22.22.2`, `^24.15.0`, or `>=26.0.0`. +- **Breaking:** removed the obsolete Deals trading module and its stale CLI/WebUI surfaces. +- Plugin execution now enforces SDK capability boundaries, channel scopes, minimum access floors, creator authority for scheduled tasks, and approval gates for external actions. +- CI Telegram notifications now batch every pushed commit into one expandable message. + +### Fixed + +- Provider quota and runtime failures now produce a clear Telegram error instead of leaving the user without a response. +- Prevented Telegram self-replies, duplicate sends, and false send confirmations; restored bot inline runtime wiring. +- Serialized side-effect operations and bounded stalled MCP/tool calls without retrying non-cancellable financial actions. +- Hardened workspace symlink containment, exec sender allowlists, plugin databases, private reads, log redaction, TON Proxy lifecycle, DEX/DNS transactions, and remote MCP tool trust. +- Bound gift purchases to the approved live price and protected owner-only financial data. +- Replaced eval-based Lottie rendering and pinned patched dependency versions. + +### Removed + +- Dead helpers, exports, row/media duplicates, and the redundant tool-error wrapper. + ## [0.9.0] - 2026-06-19 ### Added @@ -438,7 +470,14 @@ Git history rewritten to fix commit attribution (email update from `tonresistor@ - Professional distribution (npm, Docker, CI/CD) - Pre-commit hooks and linting infrastructure -[Unreleased]: https://github.com/TONresistor/teleton-agent/compare/v0.8.1...HEAD +[Unreleased]: https://github.com/TONresistor/teleton-agent/compare/v0.10.0...HEAD +[0.10.0]: https://github.com/TONresistor/teleton-agent/compare/v0.9.0...v0.10.0 +[0.9.0]: https://github.com/TONresistor/teleton-agent/compare/v0.8.6...v0.9.0 +[0.8.6]: https://github.com/TONresistor/teleton-agent/compare/v0.8.5...v0.8.6 +[0.8.5]: https://github.com/TONresistor/teleton-agent/compare/v0.8.4...v0.8.5 +[0.8.4]: https://github.com/TONresistor/teleton-agent/compare/v0.8.3...v0.8.4 +[0.8.3]: https://github.com/TONresistor/teleton-agent/compare/v0.8.2...v0.8.3 +[0.8.2]: https://github.com/TONresistor/teleton-agent/compare/v0.8.1...v0.8.2 [0.8.1]: https://github.com/TONresistor/teleton-agent/compare/v0.8.0...v0.8.1 [0.8.0]: https://github.com/TONresistor/teleton-agent/compare/v0.7.5...v0.8.0 [0.7.5]: https://github.com/TONresistor/teleton-agent/compare/v0.7.4...v0.7.5 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 047bfdc3..f03c3bb8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ This starts the agent in watch mode with automatic restarts on file changes. ### Prerequisites -- **Node.js 20.0.0+** ([download](https://nodejs.org/)) +- **Node.js 22.22.2+ LTS** ([download](https://nodejs.org/)); Node 24 requires 24.15.0+ - **npm 9+** (ships with Node.js) - An LLM API key from any [supported provider](README.md#supported-providers) (Anthropic, OpenAI, Google, xAI, Groq, OpenRouter, Mistral, and more) - Telegram API credentials from [my.telegram.org/apps](https://my.telegram.org/apps) diff --git a/Dockerfile b/Dockerfile index 956a9c3f..509c8d8c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # ---- Build stage ---- -FROM node:20-slim AS build +FROM node:22.22.2-slim AS build WORKDIR /app @@ -30,7 +30,7 @@ RUN cd web && npm ci RUN npm run build # ---- Runtime stage ---- -FROM node:20-slim +FROM node:22.22.2-slim WORKDIR /app diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index f99105b0..0d925783 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -8,12 +8,12 @@ Complete guide to installing, configuring, and running your Teleton AI agent. | Requirement | Details | |-------------|---------| -| **Node.js 20+** | [Download](https://nodejs.org/) - check with `node --version` | -| **LLM API Key** | [Anthropic](https://console.anthropic.com/) (recommended), [OpenAI](https://platform.openai.com/), [Google](https://aistudio.google.com/), [xAI](https://console.x.ai/), [Groq](https://console.groq.com/), [OpenRouter](https://openrouter.ai/), or any of 15 supported providers | +| **Node.js 22.22.2+ LTS** | [Download](https://nodejs.org/) - Node 24 requires 24.15.0+; check with `node --version` | +| **LLM API Key** | [Anthropic](https://console.anthropic.com/) (recommended), [OpenAI](https://platform.openai.com/), [Google](https://aistudio.google.com/), [xAI](https://console.x.ai/), [Groq](https://console.groq.com/), [OpenRouter](https://openrouter.ai/), or any of 16 supported providers | | **Telegram Account** | Dedicated account recommended (agent has full control) | | **Telegram API Credentials** | `api_id` + `api_hash` from [my.telegram.org/apps](https://my.telegram.org/apps) | | **Telegram User ID** | Message [@userinfobot](https://t.me/userinfobot) to get yours | -| **Bot Token** *(optional)* | From [@BotFather](https://t.me/BotFather) - required for the deals system | +| **Bot Token** *(optional in user mode)* | From [@BotFather](https://t.me/BotFather) for plugin inline cards and callbacks; required in bot mode | | **TonAPI Key** *(optional)* | From [@AntTonTechBot](https://t.me/AntTonTechBot) mini app - higher rate limits | --- @@ -52,12 +52,12 @@ teleton setup The interactive wizard configures everything: -1. **LLM Provider** - Choose between 15 providers (Anthropic, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, and more) +1. **LLM Provider** - Choose between 16 providers (Anthropic, Codex, Grok Build, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, and more) 2. **Telegram Auth** - API credentials, phone number, login code, 2FA password 3. **Access Policies** - DM policy (open/allowlist/pairing/disabled), group policy, mention rules 4. **Admin** - Your Telegram User ID, owner name/username 5. **TON Wallet** - Generates a W5R1 wallet with 24-word mnemonic -6. **Deals** *(optional)* - Bot token for the deals system, trading thresholds +6. **Optional Integrations** - Bot token, TonAPI, Toncenter, and Tavily credentials 7. **Workspace** - Creates template files (SOUL.md, IDENTITY.md, STRATEGY.md, etc.) **Files created:** @@ -98,7 +98,7 @@ You should see: āœ… Knowledge indexed āœ… Telegram: @your_agent connected āœ… TON Blockchain: connected -āœ… Agent is ready! (124 tools) +āœ… Agent is ready! (128 base tools) ``` **Verify:** Send `/ping` to your agent on Telegram. @@ -113,7 +113,7 @@ Configuration is in `~/.teleton/config.yaml`. The setup wizard generates everyth ```yaml agent: - provider: "anthropic" # anthropic | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | gocoon | local + provider: "anthropic" # anthropic | codex | grok-build | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | gocoon | local model: "claude-opus-4-5-20251101" max_tokens: 4096 temperature: 0.7 @@ -125,11 +125,6 @@ telegram: admin_ids: [123456789] # Your Telegram User ID debounce_ms: 1500 # Group message batching delay -deals: - enabled: true - buy_max_floor_percent: 100 # Buy at or below floor price - sell_min_floor_percent: 105 # Sell at floor + 5% minimum - ``` ### Switching LLM Provider @@ -142,7 +137,7 @@ agent: model: "gpt-4o" ``` -Supported: `anthropic`, `openai`, `google`, `xai`, `groq`, `openrouter`, `moonshot`, `mistral`, `cerebras`, `zai`, `minimax`, `huggingface`, `gocoon`, `local` +Supported: `anthropic`, `codex`, `grok-build`, `openai`, `google`, `xai`, `groq`, `openrouter`, `moonshot`, `mistral`, `cerebras`, `zai`, `minimax`, `huggingface`, `gocoon`, `local` --- @@ -158,13 +153,16 @@ Admin commands are only available to users listed in `admin_ids`. All commands w | `/clear` | Clear current chat history | | `/clear ` | Clear specific chat history | | `/model ` | Switch LLM model at runtime | -| `/strategy` | View or change trading thresholds | -| `/strategy buy 95` | Set buy threshold to 95% of floor | -| `/strategy sell 110` | Set sell threshold to 110% of floor | | `/wallet` | Show wallet address and balance | +| `/approve ` / `/reject ` | Resolve a pending financial action | | `/policy dm open` | Change DM policy at runtime | +| `/modules set\|info\|reset` | Manage per-group tool permissions | +| `/plugin set\|unset\|keys` | Manage plugin secrets | | `/pause` / `/resume` | Pause/resume agent responses | | `/loop ` | Set max agentic iterations | +| `/verbose` | Toggle debug logging | +| `/rag [status\|topk ]` | Toggle Tool RAG or view status | +| `/guest [on\|off]` | View or toggle bot guest mode | | `/stop` | Emergency shutdown | | `/help` | List all commands | @@ -172,18 +170,20 @@ Admin commands are only available to users listed in `admin_ids`. All commands w ## Tool Categories -Teleton has **~124 tools** across these categories: +Teleton has **128 always-registered tools**, plus 5 optional system tools: | Category | Count | Highlights | |----------|-------|------------| -| **Telegram** | 77 | Messaging, media, chats, groups, polls, stickers, gifts, stars, stories, contacts, folders, profile, memory, tasks | +| **Telegram** | 83 | Messaging, media, chats, groups, polls, stickers, gifts, stars, stories, contacts, folders, profile, memory, tasks | | **TON & Jettons** | 15 | W5R1 wallet, send/receive TON & jettons, balances, prices, holders, history, charts, NFTs, DEX quotes | | **STON.fi DEX** | 5 | Swap, quote, search, trending tokens, liquidity pools | | **DeDust DEX** | 5 | Swap, quote, pools, prices, token info | -| **TON DNS** | 7 | Domain check, auctions, bidding, resolution | -| **Deals** | 5 | Secure gift/TON trading with strategy enforcement and inline bot confirmations | +| **TON DNS** | 8 | Domain check, auctions, bidding, resolution, TON Sites | | **Journal** | 3 | Log trades/operations with reasoning and P&L | | **Workspace** | 6 | Sandboxed file operations | +| **Web** | 2 | Search and page extraction | +| **Tool Search** | 1 | Semantic retrieval across the registry | +| **System** *(optional)* | 5 | Exec (4) and TON Proxy status (1) | --- @@ -205,27 +205,6 @@ During setup, you can import a wallet instead of generating a new one. --- -## Deals System - -The deals system enables secure gift/TON trading with strategy enforcement. - -**Requirements:** Bot token configured, deals enabled in config. - -**How it works:** -1. Agent proposes a deal (buy/sell gift) -2. Strategy rules are enforced automatically (buy below floor, sell above floor +5%) -3. Inline bot shows deal card with Accept/Decline buttons -4. User sends TON first, agent verifies on-chain -5. Gift is transferred after payment verification - -**Customize thresholds:** -``` -/strategy buy 90 # Only buy at 90% of floor or less -/strategy sell 115 # Only sell at 115% of floor or more -``` - ---- - ## Memory & RAG The agent uses a hybrid search system for context-aware responses: @@ -330,7 +309,7 @@ export const tools = [ Restart the agent ā€” the plugin is auto-loaded: ``` šŸ”Œ Plugin "hello.js": 1 tool registered -āœ… 122 tools loaded (1 from plugins) +āœ… Tool registry loaded (including 1 plugin tool) ``` Plugins receive a full SDK with 108 methods across 9 namespaces: `sdk.ton`, `sdk.telegram`, `sdk.bot`, `sdk.secrets`, `sdk.storage`, `sdk.log`, and more. This includes TON wallet operations like `createTransfer`, `createJettonTransfer`, `getPublicKey`, and `getWalletVersion` for signing transactions without broadcasting. @@ -344,13 +323,12 @@ For contributors, create a TypeScript tool in `src/agent/tools/` and register it ``` src/ ā”œā”€ā”€ index.ts # Main application entry point (TeletonApp) -ā”œā”€ā”€ agent/ # LLM runtime, tool registry, ~124 tool implementations +ā”œā”€ā”€ agent/ # LLM runtime and tool registry ā”‚ ā””ā”€ā”€ tools/ # telegram/, ton/, stonfi/, dedust/, dns/, journal/, workspace/ ā”œā”€ā”€ telegram/ # GramJS bridge, message handlers, admin commands, debouncing ā”œā”€ā”€ memory/ # SQLite database, RAG search (FTS5 + vector), compaction ā”œā”€ā”€ ton/ # Wallet operations, payment verification, TON blockchain -ā”œā”€ā”€ deals/ # Deal proposals, strategy checker, config -ā”œā”€ā”€ bot/ # Grammy + GramJS bot for styled inline deal buttons +ā”œā”€ā”€ bot/ # Plugin inline-query and callback routing ā”œā”€ā”€ sdk/ # Plugin SDK (v1.0.0) ā€” TON, Telegram services for plugins ā”œā”€ā”€ ton-proxy/ # TON Proxy module (Tonutils-Proxy integration) ā”œā”€ā”€ session/ # Session persistence, transcripts diff --git a/README.md b/README.md index 51a853ed..45d17a4b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

License: MIT - Node.js + Node.js 22.22.2+ TypeScript Website Documentation @@ -15,7 +15,7 @@ --- -

Teleton is an autonomous AI agent platform that operates as a real Telegram user account or a Telegram Bot. It thinks through an agentic loop with tool calling, remembers conversations across sessions with hybrid RAG, and natively integrates the TON blockchain: send crypto, swap on DEXs, bid on domains, verify payments - all from a chat message. It can schedule tasks to run autonomously at any time. It ships with 135+ built-in tools, supports 15 LLM providers, and exposes a Plugin SDK so you can build your own tools on top of the platform.

+

Teleton is an autonomous AI agent platform that operates as a real Telegram user account or a Telegram Bot. It thinks through an agentic loop with tool calling, remembers conversations across sessions with hybrid RAG, and natively integrates the TON blockchain: send crypto, swap on DEXs, bid on domains, verify payments - all from a chat message. It can schedule tasks to run autonomously at any time. It ships with 128 always-registered tools plus 5 optional system tools, supports 16 LLM providers, and exposes a Plugin SDK so you can build your own tools on top of the platform.

### Key Highlights @@ -23,12 +23,12 @@
Full Telegram Access
Real user via MTProto,
not a bot


Agentic Loop
Think, act, observe, repeat
until shit gets done

-
15 LLM Providers
Anthropic, OpenAI, Google, xAI, Groq, and more

+
16 LLM Providers
Anthropic, OpenAI, Google, xAI, Groq, and more


TON Blockchain
Wallet, jettons, DEX swaps, DNS, NFTs


Persistent Memory
Hybrid RAG, vector + keyword, auto-compaction

-
135+ Built-in Tools
Messaging, media, crypto, DEX, DNS, files

+
128+ Built-in Tools
Messaging, media, crypto, DEX, DNS, files


Plugin SDK
Custom tools, isolated DBs, secrets, hooks

@@ -45,23 +45,22 @@ | Category | Tools | Description | | ------------- | ----- | -------------------------------------------------------------- | -| Telegram | 80 | Messages, media, chats, polls, stickers, gifts, stars, stories | +| Telegram | 83 | Messages, media, chats, polls, stickers, gifts, stars, stories | | TON & Jettons | 15 | Wallet, send/receive, balances, prices, NFTs, DEX router | | STON.fi DEX | 5 | Swap, quote, search, trending, pools | | DeDust DEX | 5 | Swap, quote, pools, prices, token analytics | | TON DNS | 8 | Auctions, bidding, linking, TON Sites, resolution | -| Deals | 5 | P2P escrow, on-chain verification, anti double-spend | | Journal | 3 | Trade logging, P&L tracking, natural language queries | | Web | 2 | Search and page extraction via Tavily | | Workspace | 6 | Sandboxed file operations, path traversal protection | -| Exec | 4 | Shell, files, processes (off by default, admin-only) | -| Bot | 1 | Inline bot message sending for plugin interactions | +| Tool Search | 1 | Semantic retrieval across the complete tool registry | +| System | 5 | Exec (4) and TON Proxy status (1), both optional | ### Advanced Capabilities | Capability | Description | | ----------------------- | ------------------------------------------------------------------------ | -| **Multi-Provider LLM** | 15 providers, hot-swap from dashboard or CLI | +| **Multi-Provider LLM** | 16 providers, hot-swap from dashboard or CLI | | **RAG + Hybrid Search** | Vector (sqlite-vec) + keyword (FTS5) fused search | | **Auto-Compaction** | AI summarizes old context, saves to `memory/*.md` | | **Observation Masking** | Compresses old tool results, saves ~90% context | @@ -84,12 +83,12 @@ ## Prerequisites -- **Node.js 20.0.0+** - [Download](https://nodejs.org/) -- **LLM API Key** - One of: [Anthropic](https://console.anthropic.com/) (recommended), [OpenAI](https://platform.openai.com/), [Google](https://aistudio.google.com/), [xAI](https://console.x.ai/), [Groq](https://console.groq.com/), [OpenRouter](https://openrouter.ai/), [Moonshot](https://platform.moonshot.ai/), [Mistral](https://console.mistral.ai/), [Cerebras](https://cloud.cerebras.ai/), [ZAI](https://open.bigmodel.cn/), [MiniMax](https://platform.minimaxi.com/), [Hugging Face](https://huggingface.co/settings/tokens) ā€” or keyless: Codex (auto-detect), Gocoon (TON), Local (Ollama/vLLM) +- **Node.js 22.22.2+ LTS** - [Download](https://nodejs.org/) (Node 24 requires 24.15.0+) +- **LLM API Key** - One of: [Anthropic](https://console.anthropic.com/) (recommended), [OpenAI](https://platform.openai.com/), [Google](https://aistudio.google.com/), [xAI](https://console.x.ai/), [Groq](https://console.groq.com/), [OpenRouter](https://openrouter.ai/), [Moonshot](https://platform.moonshot.ai/), [Mistral](https://console.mistral.ai/), [Cerebras](https://cloud.cerebras.ai/), [ZAI](https://open.bigmodel.cn/), [MiniMax](https://platform.minimaxi.com/), [Hugging Face](https://huggingface.co/settings/tokens) ā€” or keyless: Codex and Grok Build (CLI auto-detect), Gocoon (TON), Local (Ollama/vLLM) - **Telegram Account** - Dedicated account recommended for security - **Telegram API Credentials** - From [my.telegram.org/apps](https://my.telegram.org/apps) - **Your Telegram User ID** - Message [@userinfobot](https://t.me/userinfobot) -- **Bot Token** *(optional)* - From [@BotFather](https://t.me/BotFather) for inline bot features (deals) +- **Bot Token** *(optional in user mode)* - From [@BotFather](https://t.me/BotFather) for plugin inline cards and callbacks; required in bot mode > **Security Warning**: The agent will have full control over the Telegram account. Use a dedicated account, not your main one. @@ -154,7 +153,7 @@ Teleton can run as a **user account** (MTProto) or a **Telegram bot** (Bot API). |---|---|---| | **Auth** | Phone + api_id + api_hash | Bot token from @BotFather | | **Protocol** | MTProto (GramJS) | Bot API (Grammy) | -| **Tools** | 135+ | 67 (11 Telegram + 56 non-Telegram) | +| **Tools** | 128 base, up to 133 with optional system modules | Registry filtered automatically by bot-compatible capabilities | | **Risk** | Account ban possible | No ban risk | | **Dialogs/History** | Full access | Not available | | **Media sending** | All types | Photos only (v1) | @@ -172,7 +171,7 @@ The `teleton setup` wizard generates a fully configured `~/.teleton/config.yaml` ```yaml agent: - provider: "anthropic" # anthropic | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | gocoon | local + provider: "anthropic" # anthropic | codex | grok-build | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | gocoon | local api_key: "sk-ant-api03-..." model: "claude-haiku-4-5-20251001" utility_model: "claude-haiku-4-5-20251001" # for summarization, compaction, vision @@ -191,7 +190,7 @@ telegram: owner_username: "your_username" debounce_ms: 1500 # group message batching delay - # Optional: inline bot for interactive features (deals) + # Optional in user mode: plugin inline cards and callbacks bot_token: "123456:ABC-DEF..." bot_username: "your_bot" @@ -214,7 +213,7 @@ ton_proxy: # Optional: .ton domain proxy ### Supported Models -70+ models across 15 providers. Defined in `src/config/model-catalog.ts`, shared across CLI, WebUI, and Dashboard. +70+ models across 16 providers. Defined in `src/config/model-catalog.ts`, shared across CLI, WebUI, and Dashboard. @@ -237,6 +236,7 @@ ton_proxy: # Optional: .ton domain proxy +

Hugging Face
DeepSeek V3.2
Gocoon
Decentralized (TON)
Local
Ollama, vLLM, LM Studio


Grok Build
CLI auto-detected
@@ -365,8 +365,8 @@ All admin commands support `/`, `!`, or `.` prefix: | `/model ` | Hot-swap LLM model at runtime | | `/policy ` | Change access policies live | | `/loop <1-50>` | Set max agentic iterations | -| `/strategy [buy\|sell ]` | View/change trading thresholds | | `/wallet` | Show wallet address + balance | +| `/approve ` / `/reject ` | Resolve a pending financial action | | `/modules set\|info\|reset` | Per-group tool permissions | | `/plugin set\|unset\|keys` | Manage plugin secrets | | `/task ` | Assign a task to the agent | @@ -375,6 +375,7 @@ All admin commands support `/`, `!`, or `.` prefix: | `/clear [chat_id]` | Clear conversation history | | `/verbose` | Toggle debug logging | | `/rag [status\|topk ]` | Toggle Tool RAG or view status | +| `/guest [on\|off]` | View or toggle bot guest mode | | `/stop` | Emergency shutdown | | `/ping` | Check responsiveness | | `/help` | Show all commands | @@ -402,7 +403,7 @@ Plugins export a `tools` function (recommended) or array, plus optional lifecycl export const manifest = { name: "weather", version: "1.0.0", - sdkVersion: "^1.0.0", + sdkVersion: "^2.0.0", }; // Optional: creates an isolated database at ~/.teleton/plugins/data/weather.db @@ -453,7 +454,7 @@ The SDK provides namespaced access to core services: | | **Interactive**: `sendDice()`, `sendReaction()`, `createPoll()`, `createQuiz()` | | | **Moderation**: `banUser()`, `unbanUser()`, `muteUser()`, `kickUser()` | | | **Stars & Gifts**: `getStarsBalance()`, `sendGift()`, `getAvailableGifts()`, `getMyGifts()`, `getResaleGifts()`, `buyResaleGift()`, `getStarsTransactions()`, `transferCollectible()`, `setCollectiblePrice()`, `getCollectibleInfo()`, `getUniqueGift()`, `getUniqueGiftValue()`, `sendGiftOffer()` | -| | **Advanced**: `getMe()`, `getMessages()`, `isAvailable()`, `getRawClient()`, `setTyping()`, `sendStory()` | +| | **Advanced**: `getMe()`, `getMessages()`, `isAvailable()`, `setTyping()`, `sendStory()` | | `sdk.bot` | `onInlineQuery()`, `onCallback()`, `onChosenResult()`, `editInlineMessage()`, `keyboard()`, `isAvailable`, `username` | | `sdk.secrets` | `get()`, `require()`, `has()` | | `sdk.storage` | `get()`, `set()`, `delete()`, `has()`, `clear()` (KV with TTL) | @@ -463,7 +464,7 @@ The SDK provides namespaced access to core services: | `sdk.log` | `info()`, `warn()`, `error()`, `debug()` | | `sdk.on()` | Register hooks: `tool:before`, `tool:after`, `tool:error`, `prompt:before`, `prompt:after`, `session:start`, `session:end`, `message:receive`, `response:before`, `response:after`, `response:error`, `agent:start`, `agent:stop` | -**Lifecycle hooks**: `migrate(db)`, `start(ctx)`, `stop()`, `onMessage(event)`, `onCallbackQuery(event)` +**Lifecycle hooks**: `migrate(db)`, `start(ctx)` (with `ctx.sdk`), `stop()`, `onMessage(event)`, `onCallbackQuery(event)` **Security**: all SDK objects are frozen. Plugins never see API keys or other plugins' data. @@ -475,9 +476,9 @@ The SDK provides namespaced access to core services: | Layer | Technology | |-------|------------| -| LLM | Multi-provider via [pi-ai](https://github.com/mariozechner/pi-ai) (15 providers: Anthropic, Codex, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, Gocoon, Local) | +| LLM | Multi-provider via [pi-ai](https://github.com/mariozechner/pi-ai) (16 providers: Anthropic, Codex, Grok Build, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, Gocoon, Local) | | Telegram Userbot | [GramJS](https://gram.js.org/) Layer 223 fork (MTProto) | -| Inline Bot | [Grammy](https://grammy.dev/) (Bot API, for deals) | +| Inline Bot | [Grammy](https://grammy.dev/) (Bot API, plugin inline cards and callbacks) | | Blockchain | [TON SDK](https://github.com/ton-org/ton) (W5R1 wallet) | | DeFi | STON.fi SDK, DeDust SDK | | Database | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) with WAL mode | @@ -486,7 +487,7 @@ The SDK provides namespaced access to core services: | Embeddings | [@huggingface/transformers](https://www.npmjs.com/package/@huggingface/transformers) (local ONNX) or Voyage AI | | MCP Client | [@modelcontextprotocol/sdk](https://modelcontextprotocol.io/) (stdio + SSE + Streamable HTTP) | | WebUI | [Hono](https://hono.dev/) (API) + React + Vite (frontend) | -| Language | TypeScript 5.7, Node.js 20+ | +| Language | TypeScript 5.7, Node.js 22.22.2+ LTS | ### Project Structure @@ -496,13 +497,13 @@ src/ ā”œā”€ā”€ agent/ # Core agent runtime ā”‚ ā”œā”€ā”€ runtime.ts # Agentic loop (5 iterations, tool calling, masking, compaction) ā”‚ ā”œā”€ā”€ client.ts # Multi-provider LLM client -ā”‚ ā””ā”€ā”€ tools/ # 135+ built-in tools +ā”‚ ā””ā”€ā”€ tools/ # 128 base tools plus 5 optional system tools ā”‚ ā”œā”€ā”€ register-all.ts # Central tool registration (9 categories) ā”‚ ā”œā”€ā”€ registry.ts # Tool registry, scope filtering, provider limits -ā”‚ ā”œā”€ā”€ module-loader.ts # Built-in module loading (deals + exec) +ā”‚ ā”œā”€ā”€ module-loader.ts # Built-in module loading (TON Proxy + exec) ā”‚ ā”œā”€ā”€ plugin-loader.ts # External plugin discovery, validation, hot-reload ā”‚ ā”œā”€ā”€ mcp-loader.ts # MCP client (stdio/SSE), tool discovery, lifecycle -ā”‚ ā”œā”€ā”€ telegram/ # Telegram operations (80 tools) +ā”‚ ā”œā”€ā”€ telegram/ # Telegram operations (83 tools) ā”‚ ā”œā”€ā”€ ton/ # TON blockchain + jettons + DEX router (15 tools) ā”‚ ā”œā”€ā”€ stonfi/ # STON.fi DEX (5 tools) ā”‚ ā”œā”€ā”€ dedust/ # DeDust DEX (5 tools) @@ -510,18 +511,15 @@ src/ ā”‚ ā”œā”€ā”€ exec/ # System execution ā€” YOLO mode (4 tools) ā”‚ ā”œā”€ā”€ journal/ # Business journal (3 tools) ā”‚ ā””ā”€ā”€ workspace/ # File operations (6 tools) -ā”œā”€ā”€ deals/ # Deals module (5 tools, loaded via module-loader) -ā”‚ ā”œā”€ā”€ module.ts # Module definition + lifecycle -ā”‚ ā”œā”€ā”€ executor.ts # Deal execution logic -ā”‚ ā””ā”€ā”€ strategy-checker.ts # Trading strategy enforcement -ā”œā”€ā”€ bot/ # Deals inline bot (Grammy + GramJS) -ā”‚ ā”œā”€ā”€ index.ts # DealBot (Grammy Bot API) -ā”‚ ā”œā”€ā”€ gramjs-bot.ts # GramJS MTProto for styled buttons -ā”‚ ā””ā”€ā”€ services/ # Message builder, styled keyboard, verification +ā”œā”€ā”€ bot/ # Plugin inline-query and callback routing +ā”‚ ā”œā”€ā”€ inline-router.ts # Namespaced plugin inline handlers +ā”‚ ā”œā”€ā”€ callback-router.ts # Nonce-based callback dispatch +ā”‚ ā”œā”€ā”€ gramjs-bot.ts # Userbot-to-bot inline transport +ā”‚ ā””ā”€ā”€ services/ # Shared inline transport ā”œā”€ā”€ telegram/ # Telegram integration layer ā”‚ ā”œā”€ā”€ bridge.ts # GramJS wrapper (peer cache, message parsing, keyboards) ā”‚ ā”œā”€ā”€ handlers.ts # Message routing, rate limiting, ChatQueue, feed storage -ā”‚ ā”œā”€ā”€ admin.ts # 17 admin commands +ā”‚ ā”œā”€ā”€ admin.ts # Runtime admin commands ā”‚ ā”œā”€ā”€ debounce.ts # Message batching for groups ā”‚ ā”œā”€ā”€ formatting.ts # Markdown ā†’ Telegram HTML ā”‚ ā”œā”€ā”€ task-executor.ts # Scheduled task runner @@ -543,7 +541,7 @@ src/ ā”‚ ā”œā”€ā”€ manager.ts # Binary download, start/stop, PID file, health checks ā”‚ ā”œā”€ā”€ module.ts # Module lifecycle integration ā”‚ ā””ā”€ā”€ tools.ts # ton_proxy_status tool -ā”œā”€ā”€ sdk/ # Plugin SDK (v1.0.0) +ā”œā”€ā”€ sdk/ # Plugin SDK (v2.1.0) ā”‚ ā”œā”€ā”€ index.ts # SDK factory (createPluginSDK, all objects frozen) ā”‚ ā”œā”€ā”€ ton.ts # TON service for plugins ā”‚ ā”œā”€ā”€ telegram.ts # Telegram service for plugins @@ -556,7 +554,7 @@ src/ ā”‚ ā””ā”€ā”€ loader.ts # 10 sections: soul + security + strategy + memory + context + ... ā”œā”€ā”€ config/ # Configuration ā”‚ ā”œā”€ā”€ schema.ts # Zod schemas + validation -ā”‚ ā”œā”€ā”€ providers.ts # Multi-provider LLM registry (15 providers) +ā”‚ ā”œā”€ā”€ providers.ts # Multi-provider LLM registry (16 providers) ā”‚ ā””ā”€ā”€ model-catalog.ts # Shared model catalog (70+ models across all providers) ā”œā”€ā”€ webui/ # Optional web dashboard ā”‚ ā”œā”€ā”€ server.ts # Hono server, auth middleware, static serving @@ -590,7 +588,7 @@ packages/sdk/ # Published @teleton-agent/sdk | **Plugin isolation** | Frozen SDK objects, sanitized config (no API keys), isolated per-plugin databases, `npm ci --ignore-scripts` | | **Wallet protection** | File permissions `0o600`, KeyPair cached (single PBKDF2), mnemonic never exposed to plugins | | **Memory protection** | Memory writes blocked in group chats to prevent poisoning | -| **Payment security** | `INSERT OR IGNORE` on tx hashes prevents double-spend, atomic status transitions prevent race conditions | +| **Payment security** | Verified payment hashes are recorded with `INSERT OR IGNORE`, preventing replay of the same transaction | | **Exec audit** | All YOLO mode commands logged to `exec_audit` table with user, command, output, and timestamps | | **Pino redaction** | Structured logging with automatic redaction of apiKey, password, secret, token, mnemonic fields | | **Tool access control** | Per-tool access level (all, allow-list, admin, off), DM vs group gated by global policies, per-group module permissions, all runtime-configurable | diff --git a/config.example.yaml b/config.example.yaml index 4ef10dac..a2e2ba2d 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -3,7 +3,7 @@ # Or run: teleton setup agent: - provider: "anthropic" # anthropic | openai | google | xai | groq | openrouter + provider: "anthropic" # anthropic | codex | grok-build | openai | google | xai | groq | openrouter api_key: "YOUR_API_KEY" model: "claude-haiku-4-5-20251001" # Model ID (varies by provider) # utility_model: "claude-3-5-haiku-20241022" # Optional: cheap model for summarization @@ -40,9 +40,9 @@ telegram: # owner_id: 123456789 # Owner's Telegram user ID debounce_ms: 1500 # Group message batching delay (0 = disabled) - # Optional: inline bot for deals system + # Optional in user mode: plugin inline cards and callback handling # bot_token: "123456:ABC-DEF..." # From @BotFather - # bot_username: "your_deals_bot" + # bot_username: "your_agent_bot" # Optional: TonAPI key for higher rate limits # tonapi_key: "YOUR_TONAPI_KEY" # From @tonapi_bot @@ -79,24 +79,10 @@ webui: # top_k: 35 # Max tools to retrieve per LLM call # skip_unlimited_providers: false # RAG applies to ALL providers (including Anthropic) # always_include: # Tools always included regardless of query -# - telegram_send_message -# - telegram_reply_message -# - telegram_send_photo -# - telegram_send_document # - "journal_*" # Prefix glob: all journal_ tools # - "workspace_*" # - "web_*" -# Deals / OTC trading module -# deals: -# enabled: true -# expiry_seconds: 120 # Seconds before a pending deal expires -# buy_max_floor_percent: 100 # Max price as % of floor for buy offers -# sell_min_floor_percent: 105 # Min price as % of floor for sell offers -# poll_interval_ms: 5000 # Payment verification polling interval -# max_verification_retries: 12 # Max payment verification attempts -# expiry_check_interval_ms: 60000 # Stale deal check interval - # Storage paths (defaults are fine for most users) # storage: # sessions_file: "~/.teleton/sessions.json" diff --git a/docs-sdk/TEMPLATE.md b/docs-sdk/TEMPLATE.md index 841851c6..fd12862d 100644 --- a/docs-sdk/TEMPLATE.md +++ b/docs-sdk/TEMPLATE.md @@ -7,7 +7,7 @@ Use this exact HTML structure for every page. Replace PLACEHOLDERS in CAPS. ```html
Start Here
Understand
-
Tools
+
Tools
Configure
Build Plugins
SDK Reference
diff --git a/docs-sdk/llms-full.txt b/docs-sdk/llms-full.txt index 639abc69..26065178 100644 --- a/docs-sdk/llms-full.txt +++ b/docs-sdk/llms-full.txt @@ -1,11 +1,11 @@ # Teleton Plugin SDK ā€” Complete Reference -> @teleton-agent/sdk v1.0.0 ā€” TypeScript SDK for building Teleton Agent plugins with TON blockchain and Telegram integration. +> @teleton-agent/sdk v2.0.0 ā€” TypeScript SDK for building Teleton Agent plugins with TON blockchain and Telegram integration. ## Installation ```bash -npm install @teleton-agent/sdk +npm install @teleton-agent/sdk@^2 ``` ## Plugin Structure @@ -35,10 +35,10 @@ export const tools = (sdk: PluginSDK): SimpleToolDef[] => [{ ```typescript interface PluginSDK { - readonly version: string; // "1.0.0" + readonly version: string; // "2.0.0" readonly ton: TonSDK; // TON blockchain (18 methods + dex + dns) - readonly telegram: TelegramSDK; // Telegram (52 methods) - readonly db: Database | null; // SQLite (null if no migrate()) + readonly telegram: TelegramSDK; // Telegram (51 methods) + readonly db: Database | null; // Isolated SQLite (null only on initialization failure) readonly config: Record; // Sanitized app config readonly pluginConfig: Record; // Plugin-specific config readonly secrets: SecretsSDK; // API keys (3 methods) @@ -121,7 +121,7 @@ NOTE: DnsCheckResult.auction field exists in types but is NOT populated by imple --- -## sdk.telegram ā€” Telegram (52 methods) +## sdk.telegram ā€” Telegram (51 methods) ### Core - `sendMessage(chatId: string, text: string, opts?: SendMessageOptions): Promise` ā€” Send text message. opts: { replyToId?, inlineKeyboard? }. Returns message ID. @@ -193,7 +193,6 @@ NOTE: DnsCheckResult.auction field exists in types but is NOT populated by imple ### Advanced - `setTyping(chatId: string): Promise` ā€” Show typing indicator. -- `getRawClient(): unknown | null` ā€” Raw GramJS TelegramClient for MTProto. - `isAvailable(): boolean` ā€” Check if connected. --- @@ -217,8 +216,7 @@ Styled buttons (green/red/blue) only work with .toTL() (GramJS Layer 222). .toGr ## sdk.secrets ā€” Secrets (3 methods) -Resolution order: 1. Env var (${PLUGIN_NAME_UPPER}_${KEY_UPPER}), 2. Secrets store (/plugin set), 3. pluginConfig. -NOTE: The `env` field in manifest.secrets is defined but IGNORED ā€” env naming is always auto-derived. +Resolution order: 1. Manifest `env` override or derived TELETON_PLUGIN_${PLUGIN_NAME_UPPER}_${KEY_UPPER}, 2. Secrets store (/plugin set), 3. pluginConfig. Overrides must use the same reserved TELETON_PLUGIN_ namespace. - `get(key: string): string | undefined` ā€” Get secret value. - `require(key: string): string` ā€” Get or throw SECRET_NOT_FOUND. @@ -251,7 +249,7 @@ Auto-prefixed with [plugin:name]. ## sdk.db ā€” SQLite Database -Type: `Database.Database | null` (better-sqlite3). null if plugin doesn't export `migrate()`. +Type: `Database.Database | null` (better-sqlite3). The database is created for every plugin and is null only if initialization fails. Each plugin gets an isolated database. Sync API. ```typescript @@ -294,9 +292,10 @@ interface PluginManifest { description?: string; // Max 256 chars dependencies?: string[]; // Required built-in modules defaultConfig?: Record; - sdkVersion?: string; // Range: ">=1.0.0" + sdkVersion?: string; // Range: ">=2.0.0" secrets?: Record; bot?: BotManifest; // Enables sdk.bot + hooks?: PluginHookDeclaration[]; } ``` @@ -308,8 +307,9 @@ interface SimpleToolDef { description: string; // For LLM parameters?: Record; // JSON Schema execute: (params, context) => Promise; - scope?: "always" | "dm-only" | "group-only" | "admin-only"; + scope?: "open" | "always" | "dm-only" | "group-only" | "admin-only" | "allowlist" | "disabled"; category?: "data-bearing" | "action"; + requiresApproval?: boolean; } interface ToolResult { @@ -337,14 +337,14 @@ export const onCallbackQuery = async (event: PluginCallbackEvent) => { 1. SDK object is frozen ā€” plugins cannot modify or extend it. 2. sdk.bot is null if manifest doesn't declare `bot: { inline: true }`. -3. sdk.db is null if plugin doesn't export `migrate()`. +3. sdk.db is isolated per plugin and is null only if database initialization failed. 4. sdk.storage is null if no database is available. 5. sendTON() uses PAY_GAS_SEPARATELY ā€” amount sent is exact. 6. Float precision: SDK uses string-based decimal conversion, NOT Math.floor(amount * 10**d). 7. verifyPayment() requires `used_transactions` table for replay protection. 8. sendStory() has path allowlist: /tmp, Downloads/, Pictures/, Videos/, teleton workspace. -9. Secrets env naming: auto-derived ${PLUGIN_NAME_UPPER}_${KEY_UPPER} ā€” manifest `env` field is IGNORED. +9. Secrets env naming uses TELETON_PLUGIN_${PLUGIN_NAME_UPPER}_${KEY_UPPER}. Overrides must stay under the same reserved plugin prefix; cross-plugin/global env access is rejected. 10. DnsCheckResult.auction field exists in types but is NOT populated (reserved). 11. Bot SDK callback data is auto-prefixed with plugin name. 12. Styled buttons (colors) only work with .toTL() (GramJS), .toGrammy() falls back to standard. -13. getRawClient() returns GramJS client ā€” BigInteger requires `BigInt(value) as any` cast. +13. Plugins cannot access the raw Telegram bridge or GramJS client; use typed SDK capabilities. diff --git a/docs-sdk/pages/agentic-loop.html b/docs-sdk/pages/agentic-loop.html index 92b92af8..8975445b 100644 --- a/docs-sdk/pages/agentic-loop.html +++ b/docs-sdk/pages/agentic-loop.html @@ -29,7 +29,7 @@