@fickydev/pigent 0.1.0

package/README.md

@@ -0,0 +1,369 @@
+# 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.
+
+## Status
+
+Early MVP.
+
+Current working slice:
+
+```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
+
+  db/
+    client.ts
+    schema.ts
+    repositories/
+
+  logging/
+    logger.ts
+```
+
+## Setup And Run
+
+From a published package, one command can create a project, run setup, and start the daemon:
+
+```bash
+bunx @fickydev/pigent my-pigent
+```
+
+From a checked-out repo, one command handles setup when needed, then starts the daemon:
+
+```bash
+bun run run
+```
+
+Reconfigure anytime:
+
+```bash
+bun run run -- --setup
+# or, with bunx after publish:
+bunx @fickydev/pigent my-pigent --setup
+```
+
+Skip slow setup steps when needed:
+
+```bash
+bun run run -- --skip-install --skip-migrate --skip-typecheck
+```
+
+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
+- optionally install dependencies
+- optionally apply database migrations
+- optionally run typecheck
+
+Manual setup:
+
+```bash
+bun install
+cp .env.example .env
+bun run db:migrate
+bun run typecheck
+```
+
+Configure `.env`:
+
+```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=0
+PIGENT_AUTO_SETUP_DEFAULT_AGENT=coder
+```
+
+Start daemon directly after setup:
+
+```bash
+bun run start
+```
+
+Development watch mode:
+
+```bash
+bun run dev
+```
+
+Typecheck:
+
+```bash
+bun run typecheck
+```
+
+## Telegram Testing
+
+### 1. Create bot
+
+Use Telegram `@BotFather`:
+
+```text
+/newbot
+```
+
+Copy token into `.env`:
+
+```env
+TELEGRAM_BOT_TOKEN=123456:abc...
+```
+
+### 2. Discover chat id
+
+Run daemon:
+
+```bash
+bun run start
+```
+
+Message bot in private chat or add bot to a group and send `/help`.
+
+Logs will include:
+
+```json
+{"message":"inbound message received","chatId":"123456"}
+```
+
+Group chat ids usually look like:
+
+```text
+-1001234567890
+```
+
+### 3. Configure chat
+
+Edit `pigent.yaml`:
+
+```yaml
+telegramChats:
+  - chatId: "123456"
+    title: Ficky Private Chat
+    defaultAgent: coder
+    allowedAgents:
+      - coder
+    instructions: |
+      Be concise.
+```
+
+Restart daemon after editing config.
+
+### 4. Test commands
+
+In Telegram:
+
+```text
+/help
+```
+
+```text
+/agents
+```
+
+```text
+hello
+```
+
+```text
+@coder review this
+```
+
+```text
+/agent coder write a test
+```
+
+With `PIGENT_FAKE_AGENT=1`, expected fake runner response:
+
+```text
+[Code Agent] fake runner received: hello
+```
+
+With `PIGENT_FAKE_AGENT=0`, Pigent calls the Pi SDK and returns the Pi assistant response.
+
+## Agent Config
+
+Example agent lives at:
+
+```text
+agents/coder/agent.yaml
+agents/coder/SYSTEM.md
+```
+
+Example profile:
+
+```text
+profiles/software-engineer.yaml
+```
+
+Agent config shape:
+
+```yaml
+id: coder
+name: Code Agent
+profile: software-engineer
+workspace: ~/.pigent/workspaces/coder
+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
+  allowedPaths: []
+  blockedTools: []
+```
+
+## Automatic Chat Setup
+
+For easier Telegram testing, Pigent can auto-create DB routing for new Telegram chats.
+
+Enable in `.env`:
+
+```env
+PIGENT_AUTO_SETUP_CHATS=1
+PIGENT_AUTO_SETUP_DEFAULT_AGENT=coder
+```
+
+When a new Telegram chat sends any message Pigent receives, the daemon inserts a chat config into SQLite with:
+
+- `defaultAgent: coder`
+- `allowedAgents: [coder]`
+- `enabled: true`
+
+This does not write to `pigent.yaml`; it creates runtime DB config only. Keep it off for stricter production setups.
+
+## Routing
+
+One Telegram bot can serve many agents.
+
+Routing priority:
+
+1. `@agentId <message>`
+2. `/agent <agentId> <message>`
+3. chat default agent
+4. no-route error
+
+Session key:
+
+```text
+agentId + channel + chatId + threadId
+```
+
+## Database
+
+Drizzle schema currently includes:
+
+- `agents`
+- `agent_sessions`
+- `telegram_chats`
+- `telegram_chat_agents`
+- `messages`
+- `heartbeats`
+- `runtime_kv`
+
+SQLite database path is controlled by:
+
+```env
+DATABASE_URL=file:./pigent.db
+```
+
+## Commands
+
+Available Telegram commands:
+
+```text
+/help
+/start
+/agents
+/agent <agentId> <message>
+```
+
+Planned commands:
+
+```text
+/default-agent <agentId>
+/instructions <text>
+/sessions
+/reset-session <agentId>
+/heartbeat status
+```
+
+## Development 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.
+- Use repositories for database access.
+- Keep SQLite/PostgreSQL portability in mind.
+- Never inject secrets or raw `.env` values into model prompts.
+
+See also:
+
+- `PLAN.md` — architecture and milestones
+- `TODO.md` — task checklist
+- `AGENTS.md` — coding rules and project instructions
+- `CHANGELOG.md` — project changes

package/TODO.md

@@ -0,0 +1,183 @@
+# Pigent TODO
+
+## Now
+
+- [x] Add `bunx @fickydev/pigent <dir>` scaffold/setup/run command
+- [x] Add one-command setup-and-run CLI
+- [x] Add interactive setup CLI
+- [x] Add quick/custom setup modes
+- [x] Create `README.md`
+- [x] Initialize Bun TypeScript project
+- [x] Add npm publish metadata
+- [x] Add package metadata
+- [x] Add `tsconfig.json`
+- [x] Set default workspace to `~/.pigent`
+- [x] Add `.env.example`
+- [x] Add `.gitignore`
+- [x] Add basic `src/main.ts`
+- [x] Add graceful shutdown handling
+
+## Dependencies
+
+- [x] Add runtime dependencies
+  - [x] `drizzle-orm`
+  - [x] `zod`
+  - [x] `yaml`
+  - [x] `nanoid`
+  - [x] Pi SDK package
+- [x] Add dev dependencies
+  - [x] `drizzle-kit`
+  - [x] `@types/bun`
+- [x] Pick SQLite driver compatible with Bun and Drizzle
+- [ ] Document PostgreSQL migration path
+
+## Config
+
+- [x] Define root config format
+- [x] Define `AgentConfig`
+- [x] Define `ProfileConfig`
+- [x] Define `TelegramChatConfig`
+- [x] Add Zod schemas
+- [x] Implement config loader
+- [x] Load configs from `agents/*/agent.yaml`
+- [x] Load profiles from `profiles/*.yaml`
+- [x] Add example `agents/coder/agent.yaml`
+- [x] Add example `agents/coder/SYSTEM.md`
+- [x] Add example `profiles/software-engineer.yaml`
+
+## Database
+
+- [x] Create `src/db/schema.ts`
+- [x] Create `src/db/client.ts`
+- [x] Configure Drizzle Kit
+- [x] Add SQLite database path env var
+- [x] Create migrations folder
+- [x] Define `agents` table
+- [x] Define `agent_sessions` table
+- [x] Define `telegram_chats` table
+- [x] Define `telegram_chat_agents` table
+- [x] Define `messages` table
+- [x] Define `heartbeats` table
+- [x] Define `runtime_kv` table for offsets and daemon state
+- [ ] Implement repositories
+  - [x] `AgentRepository`
+  - [x] `SessionRepository`
+  - [x] `MessageRepository`
+  - [x] `TelegramRepository`
+  - [ ] `HeartbeatRepository`
+
+## Channel Layer
+
+- [x] Define `InboundMessage`
+- [x] Define `OutboundMessage`
+- [x] Define `ChannelAdapter`
+- [x] Define Telegram normalized types
+- [ ] Implement `TelegramApi`
+  - [x] `getUpdates`
+  - [x] `sendMessage`
+  - [x] error handling
+  - [ ] retry/backoff
+- [x] Implement `TelegramPollingAdapter`
+  - [x] polling loop
+  - [x] offset tracking
+  - [x] graceful stop
+  - [x] update normalization
+- [x] Persist Telegram offset in DB
+
+## Routing
+
+- [x] Implement `MessageRouter`
+- [x] Route by explicit `@agentId`
+- [x] Route by `/agent <agentId>` command
+- [x] Route to chat default agent
+- [x] Enforce allowed agents per chat
+- [x] Auto-configure new Telegram chats when enabled
+- [x] Ignore bot's own messages
+- [x] Ignore unsupported message types initially
+- [x] Add helpful error reply for unknown agent
+- [x] Add helpful error reply for disallowed agent
+
+## Agent Runtime
+
+- [ ] Implement `AgentRegistry`
+- [x] Implement `AgentDaemon`
+- [x] Implement `AgentRunner`
+- [ ] Implement `PiSessionFactory`
+- [x] Implement `PiAgentRunner`
+- [x] Create/get session by `agentId + channel + chatId + threadId`
+- [ ] Compose prompt with chat instructions
+- [x] Compose basic channel/chat/user prompt for Pi runner
+- [x] Persist inbound message before Pi run
+- [x] Persist outbound response after Pi run
+- [ ] Handle Pi errors and send safe error reply
+- [ ] Add per-session lock to prevent concurrent Pi runs
+
+## Pi Integration
+
+- [x] Confirm SDK APIs needed for session creation
+- [ ] Confirm persistent session manager approach
+- [ ] Confirm per-agent system prompt injection
+- [ ] Confirm per-agent skills loading
+- [ ] Confirm per-agent extensions loading
+- [x] Prototype one prompt through Pi SDK
+- [x] Decide CLI fallback strategy if SDK gaps appear
+
+## Heartbeat
+
+- [ ] Define heartbeat config
+- [ ] Implement scheduler
+- [ ] Add per-agent heartbeat lock
+- [ ] Add heartbeat prompt composition
+- [ ] Add `NOOP` handling
+- [ ] Persist heartbeat start/result/failure
+- [ ] Add notification cooldown
+- [ ] Add max heartbeat messages per hour
+- [ ] Send heartbeat output to configured channel only when useful
+
+## Policy And Safety
+
+- [ ] Define permission config
+- [ ] Implement `PolicyEngine`
+- [ ] Add default deny for dangerous tools/actions
+- [ ] Add allowed path checks
+- [ ] Add blocked path checks
+- [ ] Add shell command policy design
+- [ ] Add approval workflow design
+- [ ] Prevent secrets from being injected into prompts
+- [ ] Add audit log for risky actions
+
+## Commands UX
+
+- [x] `/agents` list agents available in chat
+- [ ] `/agent <id> <message>` route message
+- [ ] `/default-agent <id>` set chat default
+- [ ] `/instructions <text>` set chat instructions
+- [ ] `/sessions` list active sessions for chat
+- [ ] `/reset-session <agentId>` clear chat session
+- [ ] `/heartbeat status` show heartbeat state
+- [x] `/help` show bot commands
+
+## Tests
+
+- [ ] Unit test config validation
+- [ ] Unit test Telegram update normalization
+- [ ] Unit test routing rules
+- [ ] Unit test session key generation
+- [ ] Unit test heartbeat `NOOP` behavior
+- [ ] Repository tests against temp SQLite DB
+- [ ] Integration test fake Telegram update to fake Pi runner
+
+## Later
+
+- [ ] Add Hono HTTP server
+- [ ] Add Telegram webhook transport
+- [ ] Add Slack adapter
+- [ ] Add WhatsApp Cloud API adapter
+- [ ] Add admin API
+- [ ] Add dashboard
+- [ ] Add PostgreSQL client/schema variant
+- [ ] Add multi-agent delegation
+- [ ] Add dynamic agent creation with approval
+- [ ] Publish npm package for `bunx @fickydev/pigent`
+- [ ] Add package install support for Pi skills/extensions
+- [ ] Add semantic memory

package/agents/coder/SYSTEM.md

@@ -0,0 +1,3 @@
+You are coder agent.
+
+Focus on implementation, debugging, and code review. Keep responses concise. Ask before risky changes.

package/agents/coder/agent.yaml

@@ -0,0 +1,20 @@
+id: coder
+name: Code Agent
+profile: software-engineer
+workspace: ~/.pigent/workspaces/coder
+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
+  allowedPaths: []
+  blockedTools: []

package/drizzle/migrations/0000_great_daredevil.sql

@@ -0,0 +1,78 @@
+CREATE TABLE `agent_sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent_id` text NOT NULL,
+	`channel` text NOT NULL,
+	`chat_id` text NOT NULL,
+	`thread_id` text,
+	`user_id` text,
+	`pi_session_id` text,
+	`instructions_hash` text,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `agent_sessions_key_unique` ON `agent_sessions` (`agent_id`,`channel`,`chat_id`,`thread_id`);--> statement-breakpoint
+CREATE TABLE `agents` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`profile` text NOT NULL,
+	`workspace` text NOT NULL,
+	`config_json` text NOT NULL,
+	`system_prompt` text DEFAULT '' NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `heartbeats` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent_id` text NOT NULL,
+	`session_id` text,
+	`status` text NOT NULL,
+	`prompt` text NOT NULL,
+	`result` text,
+	`error` text,
+	`started_at` integer,
+	`finished_at` integer,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `messages` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent_id` text NOT NULL,
+	`session_id` text,
+	`channel` text NOT NULL,
+	`direction` text NOT NULL,
+	`sender_id` text,
+	`chat_id` text,
+	`thread_id` text,
+	`content` text NOT NULL,
+	`raw_json` text,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `runtime_kv` (
+	`key` text PRIMARY KEY NOT NULL,
+	`value` text NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `telegram_chat_agents` (
+	`id` text PRIMARY KEY NOT NULL,
+	`chat_id` text NOT NULL,
+	`agent_id` text NOT NULL,
+	`enabled` integer DEFAULT true NOT NULL,
+	`custom_instructions` text DEFAULT '' NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `telegram_chat_agents_chat_agent_unique` ON `telegram_chat_agents` (`chat_id`,`agent_id`);--> statement-breakpoint
+CREATE TABLE `telegram_chats` (
+	`chat_id` text PRIMARY KEY NOT NULL,
+	`title` text,
+	`default_agent_id` text,
+	`instructions` text DEFAULT '' NOT NULL,
+	`enabled` integer DEFAULT true NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);