@fickydev/pigent 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.1.16 - 2026-05-18
+
+### Changed
+
+- Reworked `README.md` to be more end-user facing with clearer setup, Telegram, sessions, agents, and operations guidance.
+
 ## 0.1.15 - 2026-05-18
 
 ### Fixed

package/README.md

@@ -1,290 +1,217 @@
 # Pigent
 
-Pigent is an autonomous multi-agent daemon that uses Pi as its core execution engine. It routes messages from external channels, starting with Telegram, to Pi-backed agents with separate profiles, skills, extensions, permissions, heartbeat behavior, and per-chat sessions.
+Pigent lets you run a Pi-powered assistant from Telegram.
 
-## Status
+Install it on a machine that stays online, connect a Telegram bot, then chat with your own coding/automation agent from Telegram private chats or groups. Pigent keeps per-chat sessions, supports multiple agents, and can run scheduled tasks.
 
-Early MVP.
+## What Pigent Does
 
-Current working slice:
+- Runs as a background user service.
+- Connects Telegram messages to Pi-backed agents.
+- Keeps a separate session per agent + chat + thread.
+- Lets you start a fresh session with `/new`.
+- Shows current session/model/context info with `/status`.
+- Supports model and thinking-level overrides from Telegram.
+- Supports scheduled `/task` runs.
+- Stores app state locally in SQLite.
+- Persists Pi session files under `~/.pigent/pi-sessions` by default.
 
-```text
-Telegram polling -> MessageRouter -> fake AgentRunner -> SQLite persistence -> Telegram reply
-```
-
-Pi SDK execution is now wired through `PiAgentRunner`. Fake responses can still be forced for transport/routing tests with `PIGENT_FAKE_AGENT=1`.
-
-## Stack
-
-- Bun
-- TypeScript
-- Drizzle ORM
-- SQLite now, PostgreSQL later
-- Telegram polling first
-- Pi SDK planned as execution core
-- Hono deferred until webhooks/API are needed
-
-## Architecture
-
-```text
-Channel Adapter -> Message Router -> Agent Orchestrator -> Pi Runner
-                                   -> State Store
-                                   -> Policy Engine
-```
-
-Current modules:
-
-```text
-src/
-  main.ts
-
-  daemon/
-    AgentDaemon.ts
-
-  pi/
-    PiAgentRunner.ts
-
-  channels/
-    types.ts
-    telegram/
-      TelegramApi.ts
-      TelegramPollingAdapter.ts
-      types.ts
-
-  agents/
-    AgentRunner.ts
-    BotCommandHandler.ts
-    MessageRouter.ts
-
-  config/
-    loadConfig.ts
-    schemas.ts
+Pigent is still an early MVP. Telegram polling is the first supported channel.
 
-  db/
-    client.ts
-    schema.ts
-    repositories/
+## Quick Start
 
-  logging/
-    logger.ts
-```
-
-## Setup And Run
-
-Install and start Pigent as a user service:
+Install and start Pigent:
 
 ```bash
 bunx @fickydev/pigent
 ```
 
+The setup wizard will ask for:
+
+- quick or custom setup
+- Telegram bot token
+- default agent routing
+- optional automatic Telegram chat setup
+
 Default app directory:
 
 ```text
 ~/.pigent/app
 ```
 
-After install, use short commands:
+After setup, use:
 
 ```bash
 pigent status
 pigent logs
-pigent stop
-pigent start
 pigent restart
 pigent update
 pigent setup
 ```
 
-Update to latest package:
+Update Pigent later:
 
 ```bash
 pigent update
 ```
 
-`pigent update` backs up the app, preserves `.env`, SQLite DB, `pigent.yaml`, `agents/`, and `profiles/`, refreshes shipped files, and restarts the service.
+`pigent update` backs up the app, keeps your `.env`, SQLite database, `pigent.yaml`, `agents/`, and `profiles/`, refreshes package files, then restarts the service.
 
-Run in foreground instead of installing a service:
+## Create A Telegram Bot
 
-```bash
-bunx @fickydev/pigent run
+1. Open Telegram and message `@BotFather`.
+2. Send:
+
+```text
+/newbot
 ```
 
-From a checked-out repo:
+3. Follow BotFather prompts.
+4. Copy the bot token.
+5. Run setup again if needed:
 
 ```bash
-bun run run
+pigent setup
 ```
 
-The setup flow will:
-
-- ask for quick or custom mode
-- create `.env` from `.env.example` if missing
-- configure `DATABASE_URL`
-- optionally write or replace `TELEGRAM_BOT_TOKEN`
-- optionally enable automatic Telegram chat setup
-- optionally configure Telegram chat routing in `pigent.yaml`
-- optionally configure log level and Telegram polling values in custom mode
-Database migrations run automatically at daemon startup. The published CLI does not ask users to run `bun install`, `bun start`, or `bun typecheck`.
+Paste the token when prompted.
 
-Manual setup:
+You can also put it in `~/.pigent/app/.env`:
 
-```bash
-bun install
-cp .env.example .env
-bun run db:migrate
-bun run typecheck
+```env
+TELEGRAM_BOT_TOKEN=123456:abc...
 ```
 
-Configure `.env`:
+## First Chat
 
-```env
-DATABASE_URL=file:./pigent.db
-TELEGRAM_BOT_TOKEN=
-PIGENT_WORKSPACE_ROOT=~/.pigent
-PIGENT_FAKE_AGENT=0
-PIGENT_FALLBACK_FAKE_AGENT=1
-PIGENT_AUTO_SETUP_CHATS=1
-PIGENT_AUTO_SETUP_DEFAULT_AGENT=assistant
+Send your bot a message in Telegram:
+
+```text
+/help
 ```
 
-Start daemon directly after setup:
+If automatic chat setup is enabled, Pigent will route the chat to the default `assistant` agent.
 
-```bash
-bun run start
+If automatic setup is disabled, configure the chat in `pigent.yaml`:
+
+```yaml
+telegramChats:
+  - chatId: "123456"
+    title: My Private Chat
+    defaultAgent: assistant
+    allowedAgents:
+      - assistant
+    instructions: |
+      Be concise.
 ```
 
-Development watch mode:
+Then restart:
 
 ```bash
-bun run dev
+pigent restart
 ```
 
-Typecheck:
+To find a chat id, send any message to the bot and check logs:
 
 ```bash
-bun run typecheck
+pigent logs
 ```
 
-## Telegram Testing
-
-### 1. Create bot
-
-Use Telegram `@BotFather`:
+Look for:
 
-```text
-/newbot
+```json
+{"message":"inbound message received","chatId":"123456"}
 ```
 
-Copy token into `.env`:
-
-```env
-TELEGRAM_BOT_TOKEN=123456:abc...
-```
+Group chat ids often start with `-100`.
 
-### 2. Discover chat id
+## Telegram Commands
 
-Run daemon:
+Common commands:
 
-```bash
-bun run start
+```text
+/help                         Show help
+/start                        Start bot help
+/agents                       List agents
+/new                          Start a fresh chat session
+/status                       Show session/model/context status
+/model                        Pick model
+/thinking                     Pick thinking level
+/agent <agentId> <message>    Send message to a specific agent
+@agentId <message>            Send message to a specific agent
 ```
 
-Message bot in private chat or add bot to a group and send `/help`.
-
-Logs will include:
+Task commands:
 
-```json
-{"message":"inbound message received","chatId":"123456"}
+```text
+/task list
+/task create <intervalMs> <prompt>
+/task remove <id>
 ```
 
-Group chat ids usually look like:
+Example:
 
 ```text
--1001234567890
+/task create 3600000 Check repo status and summarize anything important.
 ```
 
-### 3. Configure chat
+## Sessions And Memory
 
-Edit `pigent.yaml`:
+Pigent keeps sessions by this key:
 
-```yaml
-telegramChats:
-  - chatId: "123456"
-    title: Ficky Private Chat
-    defaultAgent: assistant
-    allowedAgents:
-      - assistant
-    instructions: |
-      Be concise.
+```text
+agentId + channel + chatId + threadId
 ```
 
-Restart daemon after editing config.
+That means:
 
-### 4. Test commands
+- private chats get their own session
+- groups share a session by default
+- Telegram forum topics can have separate sessions
+- different agents do not share the same session
 
-In Telegram:
+Use `/new` to end the current active session and start fresh. The next normal message creates a new Pi session file.
 
-```text
-/help
-```
+Use `/status` to inspect current state. When a Pi session exists, status shows Pi context usage; otherwise it falls back to a database estimate.
 
-```text
-/agents
-```
+Pi session files live here by default:
 
 ```text
-hello
+~/.pigent/pi-sessions
 ```
 
-```text
-@assistant review this
-```
+Override with:
 
-```text
-/agent assistant write a test
+```env
+PIGENT_PI_SESSION_DIR=/path/to/pi-sessions
 ```
 
-With `PIGENT_FAKE_AGENT=1`, expected fake runner response:
+## Agents
+
+The default assistant lives at:
 
 ```text
-[Assistant] fake runner received: hello
+~/.pigent/app/agents/assistant/
 ```
 
-With `PIGENT_FAKE_AGENT=0`, Pigent calls the Pi SDK and returns the Pi assistant response.
-
-## Agent Config
-
-Example agent lives at:
+Main files:
 
 ```text
 agents/assistant/agent.yaml
 agents/assistant/SYSTEM.md
-```
-
-Example profile:
-
-```text
 profiles/assistant.yaml
 ```
 
-Agent config shape:
+Example `agent.yaml`:
 
 ```yaml
 id: assistant
 name: Assistant
-profile: generic-assistant
+profile: assistant
 workspace: ~/.pigent/workspaces/assistant
 systemPromptFile: ./SYSTEM.md
 skills: []
 extensions: []
-channels:
-  telegram:
-    enabled: false
-heartbeat:
-  enabled: false
-  intervalMs: 600000
-  prompt: |
-    Check assigned tasks. If no useful action is needed, reply exactly: NOOP.
 permissions:
   canRunShell: false
   canEditFiles: false
@@ -292,100 +219,124 @@ permissions:
   blockedTools: []
 ```
 
-## Automatic Chat Setup
+Edit `SYSTEM.md` to change how the agent behaves.
+
+Each agent can have its own:
+
+- name
+- profile
+- workspace
+- system prompt
+- skills/extensions
+- permissions
 
-For easier Telegram testing, Pigent can auto-create DB routing for new Telegram chats.
+## Configuration
 
-Enable in `.env`:
+Important environment variables in `~/.pigent/app/.env`:
 
 ```env
+DATABASE_URL=file:./pigent.db
+TELEGRAM_BOT_TOKEN=
+PIGENT_WORKSPACE_ROOT=~/.pigent
+PIGENT_PI_SESSION_DIR=~/.pigent/pi-sessions
+PIGENT_FAKE_AGENT=0
+PIGENT_FALLBACK_FAKE_AGENT=1
 PIGENT_AUTO_SETUP_CHATS=1
 PIGENT_AUTO_SETUP_DEFAULT_AGENT=assistant
 ```
 
-When a new Telegram chat sends any message Pigent receives, the daemon inserts a chat config into SQLite with:
+Use fake mode only for testing Telegram routing without calling Pi:
 
-- `defaultAgent: assistant`
-- `allowedAgents: [assistant]`
-- `enabled: true`
+```env
+PIGENT_FAKE_AGENT=1
+```
 
-This does not write to `pigent.yaml`; it creates runtime DB config only. Keep it off for stricter production setups.
+## Running In Foreground
 
-## Routing
+Run without installing a service:
 
-One Telegram bot can serve many agents.
+```bash
+bunx @fickydev/pigent run
+```
 
-Routing priority:
+From a checked-out repo:
 
-1. `@agentId <message>`
-2. `/agent <agentId> <message>`
-3. chat default agent
-4. no-route error
+```bash
+bun install
+bun run run
+```
 
-Session key:
+Development commands:
+
+```bash
+bun run start
+bun run dev
+bun run typecheck
+bun run check
+```
+
+## Data Storage
+
+Pigent stores local runtime data in SQLite.
+
+Default database:
 
 ```text
-agentId + channel + chatId + threadId
+~/.pigent/app/pigent.db
 ```
 
-## Database
+Configured by:
 
-Drizzle schema currently includes:
+```env
+DATABASE_URL=file:./pigent.db
+```
+
+Important tables include:
 
 - `agents`
 - `agent_sessions`
 - `telegram_chats`
 - `telegram_chat_agents`
 - `messages`
-- `heartbeats`
+- `task_configs`
+- `task_runs`
 - `runtime_kv`
 
-SQLite database path is controlled by:
-
-```env
-DATABASE_URL=file:./pigent.db
-```
+Database migrations run automatically when the daemon starts.
 
-## Commands
+## Architecture
 
-Available Telegram commands:
+High-level flow:
 
 ```text
-/help
-/start
-/agents
-/new
-/status
-/model
-/thinking
-/task list
-/task create <intervalMs> <prompt>
-/task remove <id>
-/agent <agentId> <message>
+Telegram -> Message Router -> Agent Runner -> Pi Runner
+                         \-> SQLite state
 ```
 
-Planned commands:
+Code layout:
 
 ```text
-/default-agent <agentId>
-/instructions <text>
-/sessions
-/reset-session <agentId>
-/heartbeat status
+src/
+  main.ts
+  daemon/
+  channels/telegram/
+  agents/
+  pi/
+  db/
+  config/
+  logging/
 ```
 
-## Development Notes
+## Safety Notes
 
-- Do not add Hono until webhook/API needs exist.
-- Keep Telegram-specific logic inside `src/channels/telegram` or routing config.
-- Channel adapters must not call Pi directly.
-- Pi runner must not know channel secrets.
-- Pi sessions are persisted under `~/.pigent/pi-sessions` by default (`PIGENT_PI_SESSION_DIR` overrides this).
-- Use repositories for database access.
-- Keep SQLite/PostgreSQL portability in mind.
-- Never inject secrets or raw `.env` values into model prompts.
+- Do not put bot tokens or API keys in prompts.
+- Keep Telegram-specific logic inside the Telegram channel adapter or routing config.
+- Channel adapters should not call Pi directly.
+- Pi runner should not know Telegram secrets.
+- Default permissions are conservative.
+- File and shell capabilities should be enabled only for trusted agents/workspaces.
 
-See also:
+## More Docs
 
 - `PLAN.md` — architecture and milestones
 - `TODO.md` — task checklist

package/TODO.md

@@ -143,6 +143,7 @@
 - [x] Persist Pi session file path per active Pigent session
 - [x] Reuse Pi session files across messages
 - [x] Self-heal missing runtime `agent_sessions` columns after partial/mismatched migration state
+- [x] Make README more end-user facing
 - [ ] Confirm per-agent system prompt injection
 - [ ] Confirm per-agent skills loading
 - [ ] Confirm per-agent extensions loading

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fickydev/pigent",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "private": false,
   "type": "module",
   "description": "Autonomous multi-agent daemon using Pi as core execution engine.",