todo-enforcer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 buihongduc132
+
+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/README.md

@@ -0,0 +1,216 @@
+# todo-enforcer
+
+> Todo continuation enforcer for [pi-coding-agent](https://github.com/mariozechner/pi-coding-agent) — monitors todo state and injects prompts to keep agents working until all tasks complete.
+
+[![npm version](https://img.shields.io/npm/v/todo-enforcer?style=flat-square)](https://www.npmjs.com/package/todo-enforcer)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![pi-package](https://img.shields.io/badge/pi-package-blue?style=flat-square)](https://www.npmjs.com/search?q=pi-package)
+
+## Features
+
+- **Automatic task continuation** — injects prompts when the agent goes idle with incomplete tasks
+- **Configurable rule engine** — first-match-wins rule evaluation with built-in and custom conditions
+- **Multiple delivery modes** — `userMessage` (default) or `customMessage` via pi's messaging API
+- **External command support** — call external scripts/HTTP endpoints for dynamic continuation logic
+- **Spawn action** — run `pi -p` in background to generate continuation guidance
+- **Stagnation detection** — stops injecting when the agent is stuck on the same incomplete count
+- **Exponential backoff** — rate-limits retries on LLM errors (429, rate limits, etc.)
+- **Message stall guard** — prevents infinite loops from repeated identical messages
+- **Polling timer** — re-evaluates after cooldown even without agent_end events
+- **Completion summary control** — configurable `completionSummary` to suppress or enable the "all done" message (default: suppressed)
+
+## Installation
+
+### For Humans
+
+```bash
+npm install -g todo-enforcer
+```
+
+### For AI Agents (pi / OpenCode / Claude Code / Codex)
+
+Add to your `settings.json`:
+
+```jsonc
+{
+  "packages": ["todo-enforcer"]
+}
+```
+
+Or tell your agent:
+
+```
+Install and configure todo-enforcer by following:
+https://raw.githubusercontent.com/buihongduc132/todo-enforcer/refs/heads/main/README.md
+```
+
+### For pi (git-sourced)
+
+In `settings.json`:
+
+```jsonc
+{
+  "packages": ["https://github.com/buihongduc132/todo-enforcer"]
+}
+```
+
+### For pi (local path)
+
+In `settings.json`:
+
+```jsonc
+{
+  "packages": ["/path/to/todo-enforcer"]
+}
+```
+
+## Usage
+
+todo-enforcer auto-activates via pi's `agent_end` lifecycle hook. No manual invocation needed.
+
+### How It Works
+
+1. On each `agent_end` event, the enforcer reads the current todo state
+2. It evaluates rules in order — the first matching rule wins
+3. If a rule matches, it generates a prompt and delivers it to the agent
+4. A polling timer re-checks after the cooldown expires
+
+### Default Rules
+
+| Rule | Condition | Action |
+|------|-----------|--------|
+| `incomplete-tasks-remain` | Any pending/in_progress tasks | Inject continuation prompt |
+| `all-complete-celebration` | All tasks completed | Inject summary (disabled by default) |
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/enforcer-status` | Show current enforcer state, rules, and injection count |
+| `/enforcer-switch <rule1,rule2,...>` | Switch active rules for this session |
+| `/enforcer-switch reset` | Reset to config defaults |
+| `/enforcer-reset` | Reset all enforcer state for this session |
+
+### Keyboard Shortcut
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Shift+T` | Toggle enforcer enabled/disabled |
+
+## Configuration
+
+Create `~/.todo-enforcer.json` (global) or `.todo-enforcer.json` (project-level):
+
+```jsonc
+{
+  "enabled": true,
+  "maxInjections": 5,          // Max injections per session
+  "cooldownMs": 5000,          // Cooldown between injections (ms)
+  "completionSummary": false,  // Suppress "all done" message (default)
+  "detectStagnation": true,    // Stop injecting when stuck
+  "stagnationThreshold": 3,    // Consecutive idle events before stagnation
+  "backoff": {
+    "enabled": true,
+    "factor": 2,
+    "maxDelayMs": 3600000,
+    "errorPatterns": ["429", "rate limit", "No deployments available"]
+  },
+  "messageDelivery": {
+    "mode": "userMessage",     // "userMessage" or "customMessage"
+    "display": true,
+    "triggerTurn": true
+  },
+  "rules": [
+    {
+      "name": "incomplete-tasks-remain",
+      "condition": "has_incomplete",
+      "action": "prompt",
+      "prompt": "You have incomplete tasks. Continue working on them.\n\n[Status: {{completed_count}}/{{total_count}} completed, {{incomplete_count}} remaining]\n\nRemaining tasks:\n{{incomplete_list}}\n\nPick up where you left off."
+    },
+    {
+      "name": "all-complete-celebration",
+      "condition": "all_complete",
+      "action": "prompt",
+      "prompt": "All {{total_count}} tasks are complete. Great work.\n\nCompleted tasks:\n{{completed_list}}\n\nYou may now summarize the results or ask the user for next steps."
+    }
+  ]
+}
+```
+
+### Built-in Conditions
+
+| Condition | Description |
+|-----------|-------------|
+| `has_incomplete` | Any pending/in_progress tasks remain |
+| `all_complete` | Every non-deleted task is completed |
+| `has_in_progress` | At least one task is in_progress |
+| `none` | Never matches (disabled rule) |
+| `always` | Always matches |
+
+### Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{{incomplete_count}}` | Number of incomplete tasks |
+| `{{completed_count}}` | Number of completed tasks |
+| `{{total_count}}` | Total non-deleted tasks |
+| `{{incomplete_list}}` | Formatted list of incomplete tasks |
+| `{{completed_list}}` | Formatted list of completed tasks |
+| `{{latest_user_message}}` | Latest user message content |
+| `{{assistant_messages}}` | Recent assistant messages |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `prompt` | Inject a static template string |
+| `external` | Call an external command or HTTP endpoint |
+| `spawn` | Run `pi -p` in background with a template |
+| `noop` | Do nothing (for logging/future use) |
+
+## Architecture
+
+```
+todo-enforcer/
+├── src/
+│   ├── index.ts              ← Entry point — hooks, commands, shortcuts
+│   ├── config.ts             ← Config loader + types + template interpolation
+│   ├── conditions.ts         ← Built-in + custom condition evaluator
+│   ├── external-caller.ts    ← External command/HTTP executor
+│   ├── session-state.ts      ← Per-session state tracking
+│   ├── todo-snapshot.ts      ← Reads todo state from session branch
+│   ├── message-stall.ts      ← Repeated message + rate limit guard
+│   ├── type-guards.ts        ← Runtime type guards
+│   └── lib/
+│       ├── plugin-logger.ts  ← File-based structured logger
+│       ├── hooks-manager.ts  ← Hook registration and state
+│       └── types.ts          ← Shared types
+├── tests/                    ← Test suite (134 tests)
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:ci
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+MIT
+
+## Repository
+
+**GitHub**: [buihongduc132/todo-enforcer](https://github.com/buihongduc132/todo-enforcer)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "todo-enforcer",
+  "version": "1.0.0",
+  "description": "Todo continuation enforcer for pi-coding-agent — monitors todo state and injects prompts to keep agents working until all tasks complete",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ci": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit && vitest run"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "todo",
+    "enforcer",
+    "task-continuation",
+    "agent-productivity"
+  ],
+  "author": "buihongduc132",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/buihongduc132/todo-enforcer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/buihongduc132/todo-enforcer/issues"
+  },
+  "homepage": "https://github.com/buihongduc132/todo-enforcer#readme",
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": false
+    }
+  },
+  "files": [
+    "src/",
+    "todo-enforcer.example.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/conditions.ts

@@ -0,0 +1,79 @@
+/**
+ * conditions — Built-in and extensible condition evaluator
+ *
+ * Evaluates rule conditions against a TodoSnapshot.
+ * Custom conditions can be registered via registerCondition().
+ */
+// @ts-nocheck
+
+// 
+
+
+import { createPluginLogger } from "./lib/plugin-logger";
+import type { TodoSnapshot } from "./config";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type ConditionFn = (snapshot: TodoSnapshot) => boolean;
+
+// ─── Built-in conditions ────────────────────────────────────────────────────
+
+const logger = createPluginLogger("todo-enforcer");
+
+const builtinConditions: Record<string, ConditionFn> = {
+	has_incomplete: (s) => s.incompleteCount > 0,
+	all_complete: (s) => s.totalCount > 0 && s.incompleteCount === 0,
+	has_in_progress: (s) => s.inProgressCount > 0,
+	none: () => false,
+	always: () => true,
+};
+
+// ─── Registry ────────────────────────────────────────────────────────────────
+
+const customConditions: Map<string, ConditionFn> = new Map();
+
+/**
+ * Register a custom condition function.
+ * Custom conditions override built-in conditions of the same name.
+ */
+export function registerCondition(name: string, fn: ConditionFn): void {
+	customConditions.set(name, fn);
+}
+
+/**
+ * Evaluate a condition against a todo snapshot.
+ * Returns true if the condition matches.
+ */
+export function evaluateCondition(
+	conditionName: string,
+	snapshot: TodoSnapshot,
+): boolean {
+	// Custom conditions take priority
+	const custom = customConditions.get(conditionName);
+	if (custom) {
+		try {
+			return custom(snapshot);
+		} catch (err) {
+			logger.error(`Custom condition "${conditionName}" threw`, err);
+			return false;
+		}
+	}
+
+	const builtin = builtinConditions[conditionName];
+	if (builtin) {
+		return builtin(snapshot);
+	}
+
+	logger.warn(`Unknown condition: "${conditionName}" — treating as no-match`);
+	return false;
+}
+
+/**
+ * Get all registered condition names (built-in + custom).
+ */
+export function getRegisteredConditions(): string[] {
+	return [
+		...Object.keys(builtinConditions),
+		...Array.from(customConditions.keys()),
+	];
+}