@fickydev/pigent 0.1.0

package/.env.example

@@ -0,0 +1,22 @@
+# Runtime
+NODE_ENV=development
+LOG_LEVEL=info
+
+# Database
+DATABASE_URL=file:./pigent.db
+
+# Telegram
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_POLL_TIMEOUT_SECONDS=30
+TELEGRAM_POLL_INTERVAL_MS=1000
+
+# Pi
+PIGENT_WORKSPACE_ROOT=~/.pigent
+# Set to 1 to bypass Pi SDK and use deterministic fake responses.
+PIGENT_FAKE_AGENT=0
+# Set to 1 to use fake responses if Pi SDK execution fails.
+PIGENT_FALLBACK_FAKE_AGENT=1
+# Set to 1 to auto-create DB chat routing for new Telegram chats.
+PIGENT_AUTO_SETUP_CHATS=0
+# Agent used when auto-creating chat routing. Defaults to first loaded agent.
+PIGENT_AUTO_SETUP_DEFAULT_AGENT=coder

package/AGENTS.md

@@ -0,0 +1,242 @@
+# AGENTS.md
+
+## Project
+
+Pigent is an autonomous multi-agent daemon using Pi as core execution engine. It will route messages from external channels to Pi-backed agents with per-agent profiles, skills, extensions, tools, permissions, heartbeat behavior, and per-chat sessions.
+
+## Current Direction
+
+Use smallest working daemon first.
+
+- Bun runtime
+- TypeScript
+- Drizzle ORM
+- SQLite first, PostgreSQL later
+- Telegram polling first
+- Pi SDK for agent execution
+- No Hono server in MVP
+
+Add Hono later only for webhooks, Slack, WhatsApp, admin API, health endpoints, or dashboard backend.
+
+## Coding Rules
+
+- Default workspace root is `~/.pigent`.
+- Keep changes small and scoped.
+- Prefer working code over abstractions.
+- Always update `CHANGELOG.md` after working.
+- Always update `TODO.md` after working.
+- Whenever user says `remember this`, update `AGENTS.md` accordingly.
+- Do not add Hono until explicitly requested.
+- Do not let channel adapters call Pi directly.
+- Do not let Pi runtime know channel secrets.
+- Use repositories for database access; avoid raw Drizzle queries spread across runtime code.
+- Keep SQLite/PostgreSQL portability in mind.
+- Avoid hard-coded Telegram-specific logic outside `channels/telegram` and routing config.
+- Do not inject secrets or env values into model prompts.
+- Default safety policy should be conservative.
+
+## Architecture Boundaries
+
+```text
+Channel Adapter -> Message Router -> Agent Orchestrator -> Pi Runner
+                                   -> State Store
+                                   -> Policy Engine
+```
+
+### Channel Adapter
+
+Responsibilities:
+
+- receive external messages
+- normalize channel payloads
+- send outbound messages
+- manage channel-specific offsets/tokens/retries
+
+Must not:
+
+- create Pi sessions
+- inspect agent internals
+- bypass router
+
+### Message Router
+
+Responsibilities:
+
+- select agent from message
+- parse explicit agent commands
+- apply chat default agent
+- enforce allowed agents
+- return route result or user-facing routing error
+
+### Agent Orchestrator
+
+Responsibilities:
+
+- load agent config
+- get/create session
+- compose prompt context
+- call Pi runner
+- persist messages/events
+- coordinate locks
+
+### Pi Runner
+
+Responsibilities:
+
+- integrate with Pi SDK
+- create/reuse Pi sessions
+- send prompt
+- return response/error
+
+Must not:
+
+- know Telegram/Slack/WhatsApp token details
+- send messages to external channels directly
+
+### State Store
+
+Responsibilities:
+
+- Drizzle client
+- schema
+- repositories
+- migrations
+- runtime state persistence
+
+### Policy Engine
+
+Responsibilities:
+
+- gate tools/actions
+- enforce path policy
+- require approval for risky operations
+- rate-limit autonomous notifications
+
+## Planned Layout
+
+```text
+src/
+  main.ts
+
+  daemon/
+    AgentDaemon.ts
+    HeartbeatScheduler.ts
+
+  channels/
+    types.ts
+    telegram/
+      TelegramPollingAdapter.ts
+      TelegramApi.ts
+      types.ts
+
+  agents/
+    AgentConfig.ts
+    AgentRegistry.ts
+    AgentRunner.ts
+    MessageRouter.ts
+
+  pi/
+    PiAgentRunner.ts
+    PiSessionFactory.ts
+
+  db/
+    client.ts
+    schema.ts
+    repositories/
+
+  config/
+    loadConfig.ts
+    schemas.ts
+
+  policy/
+    PolicyEngine.ts
+
+  logging/
+    logger.ts
+```
+
+## Routing Rules
+
+One Telegram bot can serve many agents.
+
+Priority:
+
+1. explicit `@agentId` prefix
+2. explicit `/agent <agentId>` command
+3. chat default agent
+4. no route error
+
+Session key:
+
+```text
+agentId + channel + chatId + threadId
+```
+
+Group chats share session by default. Private chats use chat id. Telegram forum topics use thread id.
+
+## Prompt Context Rules
+
+Prompt composition may include:
+
+- agent profile instructions
+- agent system prompt
+- chat instructions
+- thread/session metadata
+- current user message
+
+Prompt composition must not include:
+
+- bot tokens
+- API keys
+- raw `.env`
+- unrelated chat history from other sessions
+- other agents' private config unless explicitly allowed
+
+## Database Rules
+
+Use Drizzle repositories.
+
+Initial tables expected:
+
+- `agents`
+- `agent_sessions`
+- `telegram_chats`
+- `telegram_chat_agents`
+- `messages`
+- `heartbeats`
+- `runtime_kv`
+
+SQLite now. PostgreSQL later. Avoid SQLite-only behavior in business logic.
+
+## Safety Rules
+
+Autonomous behavior needs guardrails.
+
+- Heartbeat must support `NOOP`.
+- Heartbeat must have cooldown/rate limits.
+- Dangerous actions need policy checks.
+- File writes and shell commands should be restricted by path/action policy.
+- External sends should be auditable.
+- Dynamic agent creation should require approval.
+
+## Implementation Order
+
+Follow `TODO.md`.
+
+Recommended order:
+
+1. project skeleton
+2. config schemas
+3. database schema/repositories
+4. Telegram polling adapter
+5. router
+6. Pi runner
+7. heartbeat
+8. policy gates
+9. Hono/webhooks later
+
+## Docs
+
+- Product/architecture plan: `PLAN.md`
+- Task checklist: `TODO.md`
+- Agent working instructions: `AGENTS.md`

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- Added `bunx @fickydev/pigent <dir>` scaffold/setup/run CLI path.
+- Added one-command setup-and-run CLI at `src/cli/run.ts` and `bun run run`.
+- Added interactive setup CLI at `src/cli/setup.ts` and `bun run setup`.
+- Expanded setup CLI with quick/custom modes, environment prompts, chat routing prompts, and optional install/migrate/typecheck steps.
+- Added `README.md` with setup, architecture, Telegram testing, routing, and development notes.
+- Added project planning docs: `PLAN.md`, `TODO.md`, and `AGENTS.md`.
+- Added Bun TypeScript project skeleton with startup/shutdown flow.
+- Added config schemas and filesystem config loader.
+- Added example coder agent and software engineer profile.
+- Added Drizzle SQLite schema, migration config, and repositories.
+- Added channel abstraction and Telegram polling adapter skeleton.
+- Added Telegram Bot API wrapper for `getUpdates` and `sendMessage`.
+- Wired Telegram polling startup when `TELEGRAM_BOT_TOKEN` is configured.
+- Added message router for `@agentId`, `/agent <id>`, and chat default routing.
+- Added fake agent runner that creates sessions and persists inbound/outbound messages.
+- Wired routed Telegram messages to fake agent responses.
+- Added Telegram `getMe` support and bot self-message filtering.
+- Added `/help`, `/start`, and `/agents` bot commands.
+- Added `PiAgentRunner` using Pi SDK sessions, read-only tools, and per-agent system prompts.
+- Added fake-runner controls via `PIGENT_FAKE_AGENT` and `PIGENT_FALLBACK_FAKE_AGENT`.
+- Added optional automatic Telegram chat setup via `PIGENT_AUTO_SETUP_CHATS`.
+- Set default workspace root to `~/.pigent` and added tilde expansion for agent workspaces.
+- Added npm package metadata and MIT license for publishing.
+
+### Changed
+
+- Updated `AGENTS.md` with rule to update `CHANGELOG.md` after work.
+- Updated `AGENTS.md` with rule to update `TODO.md` after work.
+- Updated `AGENTS.md` with rule to persist future `remember this` instructions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ficky Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLAN.md

@@ -0,0 +1,369 @@
+# Pigent Plan
+
+## Vision
+
+Build an autonomous multi-agent daemon with Pi as core execution engine. One transport, such as a Telegram bot, can route messages to many Pi-backed agents. Each agent can have its own profile, skills, extensions, tools, heartbeat policy, permissions, and per-channel session memory.
+
+## Current Product Direction
+
+Start with a local Bun daemon, not an HTTP server. Defer Hono until webhook-based channels, admin API, health endpoints, or dashboard backend become necessary.
+
+Initial stack:
+
+- Bun runtime and package manager
+- TypeScript
+- Pi SDK for agent sessions
+- Drizzle ORM
+- SQLite first, PostgreSQL later
+- Telegram polling first
+- File-based agent/profile config plus database-backed runtime state
+
+## Core Concepts
+
+### Transport
+
+Transport connects external channels to the daemon. A transport receives inbound messages and sends outbound replies. Telegram bot is a transport, not an agent.
+
+Examples:
+
+- Telegram polling transport
+- Telegram webhook transport later
+- Slack webhook transport later
+- WhatsApp Cloud API transport later
+
+### Agent
+
+Agent is a named Pi-backed worker with its own identity, profile, system prompt, skills, extensions, tools, and policy.
+
+Examples:
+
+- `coder`
+- `reviewer`
+- `devops`
+- `researcher`
+- `personal-assistant`
+
+### Session
+
+Session is conversation memory for one agent in one channel context.
+
+Recommended Telegram session key:
+
+```text
+agentId + channel + chatId + threadId
+```
+
+Private chat can omit `threadId`. Group forum topic should include `threadId`.
+
+### Profile
+
+Profile defines reusable behavior shared by agents.
+
+Profile may include:
+
+- model preference
+- base system prompt
+- response style
+- default skills
+- default extensions
+- default permission policy
+
+### Skill
+
+Skill is Pi-compatible instruction bundle, usually a `SKILL.md` folder. Agents can load different skills.
+
+### Extension
+
+Extension is Pi-compatible TypeScript/JavaScript module that adds tools, hooks, commands, or runtime behavior. Agents can load different extensions.
+
+### Heartbeat
+
+Heartbeat is scheduled self-activation. It prompts an agent periodically to check tasks, channels, external state, or pending work.
+
+Heartbeat must avoid spam via:
+
+- `NOOP` convention
+- cooldowns
+- dedupe
+- max messages per hour
+- lock per agent/session
+
+## Target Architecture
+
+```text
+Bun Daemon
+  ├─ Config Loader
+  ├─ Agent Registry
+  ├─ Channel Transports
+  │   └─ Telegram Polling Transport
+  ├─ Message Router
+  ├─ Agent Orchestrator
+  │   ├─ Pi Session Factory
+  │   ├─ Pi Agent Runner
+  │   └─ Policy Engine
+  ├─ Heartbeat Scheduler
+  └─ Drizzle State Store
+      └─ SQLite now, PostgreSQL later
+```
+
+## Message Flow
+
+```text
+Telegram update
+  ↓
+TelegramPollingTransport normalizes update
+  ↓
+MessageRouter selects target agent
+  ↓
+AgentRegistry loads agent config and chat config
+  ↓
+StateStore gets or creates agent session
+  ↓
+PiAgentRunner sends prompt to Pi SDK session
+  ↓
+Response returned to router
+  ↓
+Telegram transport sends reply
+  ↓
+Messages and session metadata persisted
+```
+
+## Routing Strategy
+
+One Telegram bot can serve many agents.
+
+Routing modes:
+
+1. Default agent per Telegram chat
+2. Explicit agent mention, such as `@coder review this`
+3. Slash command, such as `/agent coder review this`
+4. Auto-dispatcher agent later
+
+Recommended MVP:
+
+- one default agent per chat
+- explicit `@agentId` override
+- allowed agent list per chat
+
+## Telegram Chat Configuration
+
+Each Telegram group/private chat can define:
+
+- default agent
+- allowed agents
+- custom instructions
+- heartbeat settings
+- enabled/disabled status
+
+Example:
+
+```yaml
+telegramChats:
+  - chatId: "-100111"
+    title: Engineering
+    defaultAgent: coder
+    allowedAgents:
+      - coder
+      - reviewer
+      - devops
+    instructions: |
+      This is engineering group. Be concise. Prefer TypeScript.
+```
+
+## Prompt Composition
+
+For each request, compose context from:
+
+1. base Pi system prompt
+2. agent profile prompt
+3. agent system prompt
+4. channel/chat instructions
+5. thread/session metadata
+6. current user message
+
+Never inject secrets into model context.
+
+## State Model
+
+Use Drizzle repositories. Do not spread raw Drizzle queries across runtime code.
+
+Initial entities:
+
+- agents
+- agent sessions
+- telegram chats
+- telegram chat agents
+- messages
+- heartbeats
+- tasks/events later
+
+SQLite first. Keep schema types portable so PostgreSQL migration is straightforward.
+
+## Safety Model
+
+Autonomous agents need strict policy gates.
+
+Policy controls:
+
+- allowed filesystem paths
+- blocked filesystem paths
+- shell command allow/deny
+- tool allow/deny
+- external send approval
+- destructive action approval
+- heartbeat notification limits
+
+Default policy should be conservative.
+
+## File Layout
+
+```text
+src/
+  main.ts
+
+  daemon/
+    AgentDaemon.ts
+    HeartbeatScheduler.ts
+
+  channels/
+    types.ts
+    telegram/
+      TelegramPollingAdapter.ts
+      TelegramApi.ts
+      types.ts
+
+  agents/
+    AgentConfig.ts
+    AgentRegistry.ts
+    AgentRunner.ts
+    MessageRouter.ts
+
+  pi/
+    PiAgentRunner.ts
+    PiSessionFactory.ts
+
+  db/
+    client.ts
+    schema.ts
+    repositories/
+      AgentRepository.ts
+      MessageRepository.ts
+      SessionRepository.ts
+      TelegramRepository.ts
+
+  config/
+    loadConfig.ts
+    schemas.ts
+
+  policy/
+    PolicyEngine.ts
+
+  logging/
+    logger.ts
+
+agents/
+  coder/
+    agent.yaml
+    SYSTEM.md
+    skills/
+    extensions/
+
+profiles/
+  software-engineer.yaml
+
+drizzle/
+  migrations/
+```
+
+## MVP Milestones
+
+### Milestone 1: Skeleton
+
+- Bun TypeScript project
+- env loading
+- structured logging
+- graceful shutdown
+- config loader
+- initial docs
+
+### Milestone 2: Database
+
+- Drizzle SQLite client
+- schema
+- migrations
+- repositories
+- basic integration test
+
+### Milestone 3: Agent Registry
+
+- load agents from filesystem
+- load profiles
+- validate config with Zod
+- expose list/get methods
+
+### Milestone 4: Telegram Polling
+
+- bot API wrapper
+- polling loop
+- update normalization
+- outbound send
+- offset persistence
+
+### Milestone 5: Routing and Sessions
+
+- default agent per chat
+- `@agentId` route override
+- allowed-agent enforcement
+- per `agentId + chatId + threadId` session
+
+### Milestone 6: Pi Runner
+
+- create Pi SDK sessions
+- send prompts
+- return responses
+- persist inbound/outbound messages
+
+### Milestone 7: Heartbeat
+
+- scheduler
+- per-agent lock
+- `NOOP` handling
+- notification cooldown
+- heartbeat history
+
+### Milestone 8: Safety
+
+- policy engine
+- path/tool restrictions
+- approval hooks design
+- default conservative config
+
+### Milestone 9: Webhooks/API Later
+
+Add Hono only after daemon works. Use it for:
+
+- Telegram webhooks
+- Slack Events API
+- WhatsApp Cloud API
+- admin API
+- health/readiness endpoints
+- dashboard backend
+
+## Non-Goals For MVP
+
+- no Hono server
+- no web UI
+- no WhatsApp
+- no Slack
+- no vector database
+- no dynamic npm package install
+- no auto-created agents without approval
+- no production deployment automation
+
+## Open Questions
+
+- Which Pi SDK session manager should be used for persistent sessions?
+- How exactly should per-agent skills/extensions be loaded into Pi runtime?
+- Should group instructions live in YAML, DB, or both?
+- Should each chat have one default agent or multiple active agents?
+- What minimum approval flow is needed before shell/file-write tools?