tiger-agent 0.2.4 → 0.3.1

package/.env.example

@@ -10,6 +10,16 @@ GEMINI_API_KEY=your_gemini_api_key_here
 # Telegram Bot
 TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
 TELEGRAM_CHAT_ID=8172556270
+# Swarm agent step timeout in ms (0 = no extra swarm timeout)
+SWARM_AGENT_TIMEOUT_MS=0
+# Swarm-only provider failover on timeout/network/API error (true/false)
+SWARM_ROUTE_ON_PROVIDER_ERROR=false
+# Swarm default flow for new Telegram tasks (auto|design|research_build)
+SWARM_DEFAULT_FLOW=auto
+# First agent policy (auto|flow|fixed|designer|scout|coder|critic|senior_eng|spec_writer)
+SWARM_FIRST_AGENT_POLICY=auto
+# Used when SWARM_FIRST_AGENT_POLICY=fixed
+SWARM_FIRST_AGENT=designer
 
 # X/Twitter (optional - paid API)
 X_BEARER_TOKEN=your_x_bearer_token_here

package/README.md

@@ -1,16 +1,32 @@
+<p align="center">
+  <img src="./IMG_5745.jpg" alt="Tiger bot" width="900" />
+</p>
+
 # 🐯 Tiger Agent
 
 [![npm version](https://img.shields.io/npm/v/tiger-agent.svg)](https://www.npmjs.com/package/tiger-agent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 
-**Cognitive AI Agent** with persistent long-term memory, multi-provider LLM support, self-learning, and Telegram bot integration — designed for 24/7 autonomous operation on Linux.
+**Agentic Swarm AI Agent** with persistent long-term memory, multi-provider LLM support, token management, self-learning, and Telegram bot integration — designed for 24/7 autonomous operation on Linux.
 
 Made by **AI Research Group, Department of Civil Engineering, KMUTT**
 
 ---
 
-## 🆕 What's New — v0.2.4
+## 🆕 What's New — v0.3.1
+
+- **YAML swarm architecture** — swarm flow is now configurable in `swarm/architecture/*.yaml` with orchestrator, agents, stages, and judgment matrix
+- **YAML task style** — task routing style is configurable in `tasks/styles/*.yaml` and can select which architecture file to use
+- **Telegram architecture editing** — added `/architecture` and `/taskstyle` commands so Telegram users can list/show/write YAML and switch default architecture
+- **Parallel design orchestration default** — default architecture runs 3 designers in parallel, reviewer selects best, revision loop applies, then spec writer finalizes
+
+### v0.2.5
+
+- **Context-file mirror compatibility** — if legacy root files like `./soul.md` or `./ownskill.md` already exist, Tiger now mirrors updates to them automatically while continuing to use `DATA_DIR` as the canonical source
+- **README path clarification** — docs now explicitly distinguish canonical `DATA_DIR` files from optional legacy root mirrors
+
+### v0.2.4
 
 - **ClawHub skill install fixed** — `clawhub_install` and `clawhub_search` now work correctly when installed via `npm install -g`
 - **No required API keys** — `tiger onboard` skips providers with no key; any single provider is enough to start
@@ -96,6 +112,13 @@ tiger status                  # check if running
 tiger stop                    # stop
 ```
 
+**Restart background bot (after editing `.env` in this repo):**
+```bash
+cd /root/tiger
+npm run telegram:stop
+npm run telegram:bg
+```
+
 Logs: `~/.tiger/logs/telegram.out.log`
 
 ---
@@ -141,7 +164,7 @@ Logs: `~/.tiger/logs/telegram.out.log`
 | `ALLOW_SHELL` | `false` | Enable shell tool |
 | `ALLOW_SKILL_INSTALL` | `false` | Enable ClawHub skill install |
 | `VECTOR_DB_PATH` | `~/.tiger/db/memory.sqlite` | SQLite vector DB path |
-| `DATA_DIR` | `~/.tiger/data` | Context files directory |
+| `DATA_DIR` | `~/.tiger/data` | Canonical context files directory |
 | `OWN_SKILL_UPDATE_HOURS` | `24` | Hours between `ownskill.md` regenerations (min 1) |
 | `SOUL_UPDATE_HOURS` | `24` | Hours between `soul.md` regenerations (min 1) |
 | `REFLECTION_UPDATE_HOURS` | `12` | Hours between reflection cycles (min 1) |
@@ -184,6 +207,22 @@ ZAI_TOKEN_LIMIT=100000
 MINIMAX_TOKEN_LIMIT=100000
 CLAUDE_TOKEN_LIMIT=500000
 MOONSHOT_TOKEN_LIMIT=100000
+
+# Provider request timeouts (ms)
+KIMI_TIMEOUT_MS=120000
+ZAI_TIMEOUT_MS=120000
+
+# Swarm worker-step timeout (0 = no extra swarm timeout)
+SWARM_AGENT_TIMEOUT_MS=120000
+
+# Swarm only: on timeout/network/API error, retry via next provider
+SWARM_ROUTE_ON_PROVIDER_ERROR=true
+
+# Swarm task entry policy
+SWARM_DEFAULT_FLOW=auto
+SWARM_FIRST_AGENT_POLICY=auto
+# Used only when SWARM_FIRST_AGENT_POLICY=fixed
+SWARM_FIRST_AGENT=designer
 ```
 
 ### Auto-Switch Behaviour
@@ -205,15 +244,232 @@ MOONSHOT_TOKEN_LIMIT=100000
 | `/tokens` | Show today's token usage per provider |
 | `/limit` | Show daily token limits per provider |
 | `/limit <provider> <n>` | Set daily token limit (0 = unlimited, e.g. `/limit zai 100000`) |
+| `/swarm` | Show agent swarm status (ON/OFF) |
+| `/swarm <on|off>` | Enable or disable internal swarm routing for normal messages |
+| `/status` | Show swarm task queues (`pending`, `in_progress`, `done`, `failed`) |
+| `/task` | List swarm tasks across queues |
+| `/task continue <task_id>` | Resume a failed/stuck swarm task from the last failed agent |
+| `/task retry <task_id>` | Alias of `/task continue <task_id>` |
+| `/task delete <task_id>` | Delete a swarm task file from queue storage |
+| `/agents` | Show internal swarm agents and availability |
+| `/cancel <task_id>` | Cancel a swarm task |
+| `/ask <agent> <question>` | Ask a specific internal agent role directly |
+| `/architecture` | List swarm architecture YAML files |
+| `/architecture show <file>` | Show one architecture YAML file |
+| `/architecture use <file>` | Set default task-style architecture file |
+| `/architecture write <file>` + newline + yaml | Save architecture YAML from Telegram |
+| `/taskstyle` | List task-style YAML files |
+| `/taskstyle show <file>` | Show one task-style YAML file |
+| `/taskstyle write <file>` + newline + yaml | Save task-style YAML from Telegram |
 | `/help` | Show all commands |
 
+### Swarm Settings (`/swarm`)
+
+Tiger v0.3.1 includes an internal agent swarm for Telegram message routing.
+
+- **Default:** swarm is **ON** when the Telegram bot starts
+- **`/swarm on`**: regular user messages are routed through the YAML architecture in `swarm/architecture/*.yaml` (selected by `tasks/styles/default.yaml`)
+- **`/swarm off`**: regular user messages skip the swarm and go directly to the standard Tiger agent reply path
+- **Scope:** this toggle affects only **normal chat messages** (not admin commands like `/api`, `/tokens`, `/limit`)
+- **Current persistence:** the `/swarm` toggle is currently **in-memory only** and resets to **ON** after bot restart
+- **Task resume:** use `/task continue <task_id>` (or `/task retry <task_id>`) to continue a failed timeout/API-error task without starting over
+
+### Swarm Timeout / Failover (`.env`)
+
+- `SWARM_AGENT_TIMEOUT_MS`: timeout per swarm worker step (e.g. one `designer` turn). `0` disables the extra swarm timeout.
+- `SWARM_ROUTE_ON_PROVIDER_ERROR=true|false`: swarm-only provider failover on timeout/network/API errors.
+- Provider timeouts are separate and provider-specific, for example `KIMI_TIMEOUT_MS`, `ZAI_TIMEOUT_MS`, `CLAUDE_TIMEOUT_MS`.
+
+### Swarm Entry Policy (`.env`)
+
+- `SWARM_DEFAULT_FLOW=auto|design|research_build`: default flow for new Telegram swarm tasks.
+- `SWARM_FIRST_AGENT_POLICY` controls who starts first:
+  - `auto` (default): Tiger/orchestrator picks based on the goal text
+  - `flow`: use flow mapping (`research_build -> scout`, otherwise `designer`)
+  - `fixed`: use `SWARM_FIRST_AGENT`
+  - or set a direct agent name (for example `designer`, `scout`, `coder`)
+- `SWARM_FIRST_AGENT` is used when `SWARM_FIRST_AGENT_POLICY=fixed`
+
+Examples:
+
+```text
+/swarm
+/swarm off
+/swarm on
+/task
+/task retry task_xxx
+/task delete task_xxx
+```
+
+### Swarm Agent Files (Manual Customization)
+
+Tiger creates a local swarm workspace so you can manually customize each agent's behavior.
+
+Default folders (project/runtime root):
+
+```text
+agents/
+  tiger/
+  designer/
+  senior_eng/
+  spec_writer/
+  scout/
+  coder/
+  critic/
+tasks/
+  pending/
+  in_progress/
+  done/
+  failed/
+```
+
+Each agent folder includes files such as:
+
+- `soul.md` — the agent's personality, rules, and mindset
+- `ownskill.md` — what the agent is good at / preferred workflow
+- `experience.json` — learned lessons and task stats
+- `memory.md` — long-form notes/patterns
+- `human.md` — only for `agents/tiger/` (user preferences)
+
+Manual setup / editing:
+
+- Start the bot once (`tiger telegram` or `tiger start`) and Tiger will auto-create missing `agents/` and `tasks/` folders
+- You can then open and edit files like `agents/designer/soul.md` or `agents/senior_eng/soul.md` manually
+- Your edits are used on future swarm runs (for example `/ask designer ...` or normal swarm-routed messages)
+- Keep edits in plain Markdown/JSON and avoid deleting required files while the bot is running
+
+Example customization ideas:
+
+- Make `designer` more creative / visual
+- Make `senior_eng` stricter about security, error handling, and scalability
+- Make `spec_writer` produce a specific document format your team uses
+
+### Swarm Architecture YAML (v0.3.1)
+
+Default files:
+
+```text
+swarm/architecture/tiger_parallel_design.yaml
+tasks/styles/default.yaml
+```
+
+Default architecture behavior:
+
+- Orchestrator: `tiger`
+- Stage 1: send task simultaneously to `designer_a`, `designer_b`, `designer_c` (different souls/personalities)
+  - `designer_a`: senior conservative
+  - `designer_b`: balanced, around 40 style
+  - `designer_c`: young aggressive, higher risk appetite
+- Stage 2: `reviewer` evaluates with the judgment matrix and picks best candidate
+- Stage 3: selected designer revises based on reviewer feedback (loop until approved)
+- Stage 4: `spec_writer` writes final output in two sections: **Calculation Report** and **Executive Summary**
+
+Example `swarm/architecture/tiger_parallel_design.yaml`:
+
+```yaml
+version: 1
+name: tiger_parallel_design
+main_orchestrator: tiger
+start_stage: design_parallel
+agents:
+  - id: designer_a
+    runtime_agent: designer_a
+    role: designer
+  - id: designer_b
+    runtime_agent: designer_b
+    role: designer
+  - id: designer_c
+    runtime_agent: designer_c
+    role: designer
+  - id: reviewer
+    runtime_agent: senior_eng
+    role: reviewer
+  - id: spec_writer
+    runtime_agent: spec_writer
+    role: spec_writer
+stages:
+  - id: design_parallel
+    type: parallel
+    roles:
+      - designer_a
+      - designer_b
+      - designer_c
+    store_as: design_candidates
+    next: review_best
+  - id: review_best
+    type: judge
+    role: reviewer
+    candidates_from: design_candidates
+    selected_role_key: selected_role
+    feedback_key: reviewer_feedback
+    calculation_report_key: best_calculation_report
+    pass_next: final_spec
+    fail_next: revise_selected
+  - id: revise_selected
+    type: revise
+    role_from_context: selected_role
+    feedback_from_context: reviewer_feedback
+    candidates_from: design_candidates
+    update_context_keys_from_revised:
+      - best_calculation_report
+    next: review_best
+  - id: final_spec
+    type: final
+    role: spec_writer
+    source_from_context: best_calculation_report
+    output_sections:
+      - Calculation Report
+      - Executive Summary
+    output_notes: Include formulas, assumptions, step-by-step calculations, final values, and concise recommendations.
+    next: tiger_done
+judgment_matrix:
+  criteria:
+    - name: objective_fit
+      weight: 0.35
+      description: How well the design satisfies the objective.
+    - name: feasibility
+      weight: 0.25
+      description: Delivery realism and technical viability.
+    - name: clarity
+      weight: 0.2
+      description: Readability and implementation clarity.
+    - name: risk
+      weight: 0.2
+      description: Risk exposure and mitigation quality.
+  pass_rule: reviewer_approval
+```
+
+### Task Style YAML
+
+Task style is the selector/policy layer for swarm execution.
+
+- `architecture`: which file in `swarm/architecture/` to run
+- `flow`: flow label for task routing mode
+- `objective_prefix`: text prepended to the user objective before processing
+
+Default file:
+
+```text
+tasks/styles/default.yaml
+```
+
+Example:
+
+```yaml
+version: 1
+name: default
+architecture: tiger_parallel_design.yaml
+flow: architecture
+objective_prefix: "Objective:"
+```
+
 ---
 
 ## 🧠 Memory & Context
 
 ### Context Files
 
-Loaded on every turn from `~/.tiger/data/`:
+Loaded on every turn from `DATA_DIR` (default: `~/.tiger/data/`):
 
 | File | Purpose |
 |------|---------|
@@ -222,6 +478,8 @@ Loaded on every turn from `~/.tiger/data/`:
 | `human2.md` | Running update log written after every conversation turn |
 | `ownskill.md` | Known skills, workflows, and lessons learned |
 
+> **v0.2.5 compatibility note:** If root-level legacy files already exist (for example `./soul.md`, `./ownskill.md`), Tiger mirrors updates to those files automatically. The canonical source remains `DATA_DIR`.
+
 ### Auto-Refresh Cycles
 
 Tiger periodically regenerates these files using the LLM. All durations are configurable in `.env` (minimum 1 hour).
@@ -335,6 +593,8 @@ rm .env.secrets
 | `403` quota error | Daily quota exhausted — auto-switches; raise `*_TOKEN_LIMIT` |
 | `429` rate limit | Auto-switches to next provider in `PROVIDER_ORDER` |
 | Z.ai auth fails | Key must be `id.secret` format (from Zhipu/BigModel console) |
+| Telegram bot runs but does not respond | Ensure only one polling instance is running for the same bot token (stop old/global service copies) |
+| `soul.md` / `ownskill.md` look stale | Check `DATA_DIR` first (default `~/.tiger/data`). In v0.2.5+, existing root legacy copies are mirrored automatically |
 | Shell tool disabled | Set `ALLOW_SHELL=true` in `~/.tiger/.env` |
 | Stuck processes | `pkill -f tiger-agent` then restart |
 | Reset token counters | Delete `~/.tiger/db/token_usage.json` and restart |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiger-agent",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Cognitive AI agent with persistent memory, multi-provider LLM, and Telegram bot",
   "type": "commonjs",
   "main": "src/cli.js",

package/src/agent/contextFileMirrors.js

@@ -0,0 +1,39 @@
+const fs = require('fs');
+const path = require('path');
+
+function getLegacyRootMirrorPath(filePath) {
+  const canonical = path.resolve(filePath);
+  const candidate = path.resolve(process.cwd(), path.basename(canonical));
+
+  if (candidate === canonical) return null;
+  if (!fs.existsSync(candidate)) return null;
+
+  return candidate;
+}
+
+function syncLegacyRootMirror(filePath) {
+  const canonical = path.resolve(filePath);
+  const legacy = getLegacyRootMirrorPath(canonical);
+  if (!legacy) return;
+
+  const content = fs.readFileSync(canonical, 'utf8');
+  fs.writeFileSync(legacy, content, 'utf8');
+}
+
+function writeContextFile(filePath, content) {
+  const canonical = path.resolve(filePath);
+  fs.writeFileSync(canonical, content, 'utf8');
+  syncLegacyRootMirror(canonical);
+}
+
+function appendContextFile(filePath, content) {
+  const canonical = path.resolve(filePath);
+  fs.appendFileSync(canonical, content, 'utf8');
+  syncLegacyRootMirror(canonical);
+}
+
+module.exports = {
+  writeContextFile,
+  appendContextFile,
+  syncLegacyRootMirror
+};

package/src/agent/contextFiles.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const { dataDir } = require('../config');
 const { ensureDir } = require('../utils');
+const { writeContextFile, syncLegacyRootMirror } = require('./contextFileMirrors');
 
 const files = ['soul.md', 'human.md', 'human2.md', 'ownskill.md'];
 
@@ -10,8 +11,10 @@ function ensureContextFiles() {
   for (const name of files) {
     const full = path.join(dataDir, name);
     if (!fs.existsSync(full)) {
-      fs.writeFileSync(full, `# ${name.replace('.md', '')}\n\n`, 'utf8');
+      writeContextFile(full, `# ${name.replace('.md', '')}\n\n`);
+      continue;
     }
+    syncLegacyRootMirror(full);
   }
 }
 

package/src/agent/mainAgent.js

@@ -12,6 +12,7 @@ const {
   memoryIngestMinChars
 } = require('../config');
 const { loadContextFiles } = require('./contextFiles');
+const { writeContextFile, appendContextFile } = require('./contextFileMirrors');
 const { tools, callTool } = require('./toolbox');
 const {
   ensureConversation,
@@ -98,7 +99,7 @@ async function maybeUpdateHumanFile(userText, assistantText) {
   if (!append) return;
 
   const block = `\n## Update ${new Date().toISOString()}\n${append}\n`;
-  fs.appendFileSync(path.resolve(human2.full), block, 'utf8');
+  appendContextFile(path.resolve(human2.full), block);
 }
 
 function buildSystemPrompt(contextText, memoriesText) {
@@ -173,7 +174,7 @@ async function maybeUpdateOwnSkillSummary(conversationIdValue) {
 
   const next = String(message.content || '').trim();
   if (!next) return;
-  fs.writeFileSync(path.resolve(ownSkillPath), `${next}\n`, 'utf8');
+  writeContextFile(path.resolve(ownSkillPath), `${next}\n`);
   setMeta(OWNSKILL_META_KEY, Date.now());
 }
 
@@ -209,7 +210,7 @@ async function maybeUpdateSoulSummary(conversationIdValue) {
 
   const next = String(message.content || '').trim();
   if (!next) return;
-  fs.writeFileSync(path.resolve(soulPath), `${next}\n`, 'utf8');
+  writeContextFile(path.resolve(soulPath), `${next}\n`);
   setMeta(SOUL_META_KEY, Date.now());
 }
 

package/src/agent/reflectionAgent.js

@@ -3,6 +3,7 @@ const path = require('path');
 const { chatCompletion, embedText } = require('../llmClient');
 const { dataDir, embeddingsEnabled, reflectionUpdateHours } = require('../config');
 const { addMemory, getMeta, setMeta, getMessagesSince, getRecentMessagesAll } = require('./db');
+const { writeContextFile } = require('./contextFileMirrors');
 
 const REFLECTION_META_KEY = 'memory_reflection_last_run_ts';
 const MAX_MESSAGE_SCAN = 600;
@@ -67,7 +68,7 @@ function appendTimestampedBullets(filePath, heading, bullets, stamp) {
   const withHeading = ensureHeading(existing, heading);
   const lines = bullets.map((line) => `- [${stamp}] ${line}`).join('\n');
   const next = `${withHeading.trimEnd()}\n${lines}\n`;
-  fs.writeFileSync(full, next, 'utf8');
+  writeContextFile(full, next);
 }
 
 function appendHuman2Update(filePath, payload, stampIso) {
@@ -80,7 +81,7 @@ function appendHuman2Update(filePath, payload, stampIso) {
   for (const w of payload.successfulWorkflows) lines.push(`- Workflow: ${w}`);
   if (!lines.length) return;
   const block = `\n## Update ${stampIso}\n${lines.join('\n')}\n`;
-  fs.writeFileSync(full, `${existing.trimEnd()}${block}`, 'utf8');
+  writeContextFile(full, `${existing.trimEnd()}${block}`);
 }
 
 async function generateReflection(rows, sinceIso, untilIso) {

package/src/agent/skills.js

@@ -135,7 +135,7 @@ async function clawhubInstall(args = {}) {
   if (force) argv.push('--force');
 
   const res = await runClawhub(argv, {
-    timeout: Number(args.timeout_ms || 120000),
+    timeout: Number(args.timeout_ms || process.env.SWARM_AGENT_TIMEOUT_MS || 720000),
     maxBuffer: 1024 * 1024
   });
   if (res.ok) {

package/src/apiProviders.js

@@ -134,7 +134,7 @@ function buildProviders(env) {
       embedPath: '/embeddings',
       formatRequest: standardFormat,
       parseResponse: standardParse,
-      timeout: Number(env.KIMI_TIMEOUT_MS || 30000)
+      timeout: Number(env.KIMI_TIMEOUT_MS || 180000)
     },
 
     moonshot: {
@@ -150,7 +150,7 @@ function buildProviders(env) {
       embedPath: '/embeddings',
       formatRequest: standardFormat,
       parseResponse: standardParse,
-      timeout: Number(env.KIMI_TIMEOUT_MS || 30000)
+      timeout: Number(env.KIMI_TIMEOUT_MS || 180000)
     },
 
     zai: {
@@ -171,7 +171,7 @@ function buildProviders(env) {
       embedPath: '/embeddings',
       formatRequest: standardFormat,
       parseResponse: standardParse,
-      timeout: Number(env.ZAI_TIMEOUT_MS || 30000)
+      timeout: Number(env.ZAI_TIMEOUT_MS || 180000)
     },
 
     minimax: {
@@ -187,7 +187,7 @@ function buildProviders(env) {
       embedPath: '/embeddings',
       formatRequest: standardFormat,
       parseResponse: standardParse,
-      timeout: Number(env.MINIMAX_TIMEOUT_MS || 30000)
+      timeout: Number(env.MINIMAX_TIMEOUT_MS || 180000)
     },
 
     claude: {
@@ -203,16 +203,15 @@ function buildProviders(env) {
       embedPath: null, // Claude does not expose an embeddings endpoint
       formatRequest: claudeFormat,
       parseResponse: claudeParse,
-      timeout: Number(env.CLAUDE_TIMEOUT_MS || 60000)
+      timeout: Number(env.CLAUDE_TIMEOUT_MS || 180000)
     }
   };
 }
 
-// Singleton — providers are built once from process.env on first access
-let _providers = null;
+// Always rebuild from current process.env so runtime .env changes take effect
+// (fixes stale timeout after PM2 restart or .env update)
 function getProviders() {
-  if (!_providers) _providers = buildProviders(process.env);
-  return _providers;
+  return buildProviders(process.env);
 }
 
 function getProvider(id) {