@fickydev/pigent 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ### Added
 
+- Added `task_runs` table and `TaskRepository` for scheduled task persistence.
+- Added `Scheduler` module with global tick, per-task due check, lock, NOOP handling, and channel output.
+- Added `scheduler` block to root config (`pigent.yaml`) with `tickIntervalMs` and `tasks[]`.
+- Added `agent` field to task config to reference which agent executes the task.
+- Replaced per-agent `heartbeat` config with daemon-level scheduler.
+- Wired scheduler into daemon start/stop lifecycle.
+- Added `task_configs` table and `TaskConfigRepository` for runtime task CRUD.
+- Added `/task list`, `/task create <intervalMs> <prompt>`, `/task remove <id>` Telegram commands.
+- Scheduler loads tasks from both config file and database, supports hot-add and hot-remove.
+- Scheduler now shares AgentRunner's per-session lock instead of using its own PiAgentRunner.
+- Tasks skip message persistence (inbound/outbound) in AgentRunner to avoid DB noise.
+- Added `source` field to InboundMessage type (`"user"` default, `"task"` for scheduled runs).
+
 - 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`.

package/PLAN.md

@@ -77,17 +77,18 @@ Skill is Pi-compatible instruction bundle, usually a `SKILL.md` folder. Agents c
 
 Extension is Pi-compatible TypeScript/JavaScript module that adds tools, hooks, commands, or runtime behavior. Agents can load different extensions.
 
-### Heartbeat
+### Scheduled Tasks
 
-Heartbeat is scheduled self-activation. It prompts an agent periodically to check tasks, channels, external state, or pending work.
+Scheduled tasks are periodic self-activations defined in `pigent.yaml` or created at runtime via `/task create`. Each task references an agent, an interval, a prompt, and a target channel.
 
-Heartbeat must avoid spam via:
+The global `Scheduler` ticks on a configurable interval and evaluates every task's due-ness against its last run timestamp.
 
-- `NOOP` convention
-- cooldowns
-- dedupe
-- max messages per hour
-- lock per agent/session
+Constraints:
+
+- `NOOP` convention — agent returns "NOOP" to skip output
+- Per-task lock — prevent stacking runs of the same task
+- Max messages per hour — rate limit (not yet implemented)
+- Tasks must share the same session lock as user messages to avoid concurrent Pi runs for the same agent+channel+chat
 
 ## Target Architecture
 
@@ -252,9 +253,10 @@ Initial entities:
 - telegram chats
 - telegram chat agents
 - messages
-- heartbeats
+- task_runs (history)
+- task_configs (runtime task definitions)
+- runtime_kv (offsets, daemon state)
 - session model/thinking overrides
-- tasks/events later
 
 SQLite first. Keep schema types portable so PostgreSQL migration is straightforward.
 
@@ -282,7 +284,8 @@ src/
 
   daemon/
     AgentDaemon.ts
-    HeartbeatScheduler.ts
+    Scheduler.ts
+    taskDue.ts
 
   channels/
     types.ts
@@ -299,15 +302,19 @@ src/
 
   pi/
     PiAgentRunner.ts
-    PiSessionFactory.ts
+    PiAvailableModels.ts
+    PiModelResolver.ts
 
   db/
     client.ts
     schema.ts
     repositories/
       AgentRepository.ts
+      HeartbeatRepository.ts
       MessageRepository.ts
       SessionRepository.ts
+      TaskRepository.ts
+      TaskConfigRepository.ts
       TelegramRepository.ts
 
   config/
@@ -384,13 +391,16 @@ drizzle/
 - return responses
 - persist inbound/outbound messages
 
-### Milestone 7: Heartbeat
+### Milestone 7: Scheduler
 
-- scheduler
-- per-agent lock
+- global scheduler tick
+- config-based tasks from `pigent.yaml`
+- DB-based tasks (runtime CRUD via `/task` commands)
+- per-task lock
+- shared session lock with user messages (prevent concurrent Pi runs)
 - `NOOP` handling
-- notification cooldown
-- heartbeat history
+- notification rate limits (future)
+- `/task list`, `/task create`, `/task remove` commands
 
 ### Milestone 8: Safety
 
@@ -425,8 +435,9 @@ Add Hono only after daemon works. Use it for:
 
 - Should `/model <agentId> ...` support non-default agent sessions in the command itself?
 - Should model availability errors block `/model` saves or save with a warning?
-- 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?
+- Should scheduled tasks share the same session lock as user messages, or allow concurrent Pi runs?
+- Should `/task create` enforce permission checks before allowing runtime task creation?

package/TODO.md

@@ -145,17 +145,24 @@
 - [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
-- [x] Persist heartbeat start/result/failure
-- [ ] Add notification cooldown
-- [ ] Add max heartbeat messages per hour
-- [ ] Send heartbeat output to configured channel only when useful
+## Scheduler
+
+- [x] Define task config schema
+- [x] Move task config from per-agent to daemon-level (`pigent.yaml`)
+- [x] Add `task_runs` database table
+- [x] Implement `TaskRepository`
+- [x] Create `Scheduler` module (global tick, per-task due check, lock, NOOP, channel output)
+- [x] Wire scheduler into daemon start/stop
+- [x] Update example root config with scheduler block
+- [x] Add `task_configs` DB table for runtime task definitions
+- [x] Add `TaskConfigRepository`
+- [x] Add `/task list` command
+- [x] Add `/task create <intervalMs> <prompt>` command
+- [x] Add `/task remove <id>` command
+- [x] Scheduler loads tasks from both config file + DB
+- [x] Share session lock between Scheduler and AgentRunner (prevent concurrent Pi runs for same agent+chat)
+- [ ] Add max task runs per hour rate limit
+- [ ] Add `/task status` or similar command
 
 ## Policy And Safety
 
@@ -196,11 +203,11 @@
 
 ## Tests
 
+- [x] Unit test `isTaskDue` logic
 - [ ] Unit test config validation
 - [ ] Unit test Telegram update normalization
 - [ ] Unit test routing rules
 - [ ] Unit test session key generation
-- [ ] Unit test heartbeat `NOOP` behavior
 - [ ] Unit test model selection priority
 - [ ] Unit test Telegram `/model` command parsing
 - [ ] Unit test Telegram model picker callback parsing

package/agents/assistant/agent.yaml

@@ -10,11 +10,6 @@ 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

package/drizzle/migrations/0002_bouncy_leper_queen.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `task_runs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent_id` text NOT NULL,
+	`task_id` text NOT NULL,
+	`prompt` text NOT NULL,
+	`session_id` text,
+	`status` text NOT NULL,
+	`result` text,
+	`error` text,
+	`started_at` integer,
+	`finished_at` integer,
+	`created_at` integer NOT NULL
+);

package/drizzle/migrations/0003_secret_stone_men.sql

@@ -0,0 +1,11 @@
+CREATE TABLE `task_configs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent` text NOT NULL,
+	`interval_ms` integer NOT NULL,
+	`prompt` text NOT NULL,
+	`channel` text DEFAULT 'telegram' NOT NULL,
+	`chat_id` text NOT NULL,
+	`enabled` integer DEFAULT true NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);