@trevonistrevon/pi-loop 0.5.8 → 0.6.0

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.0"
+}

package/AGENTS.md

@@ -13,17 +13,60 @@
 ## Architecture
 ```
 src/
-├── index.ts              # Extension entry: 6 tools + /loop /loops commands + widget
-├── types.ts              # LoopKind, Trigger spec, LoopEntry, MonitorEntry, LoopConfig
-├── store.ts              # File-backed CRUD (.pi/loops/loops.json) with file locking
-├── scheduler.ts          # Timer-based cron scheduler with jitter + 7-day expiry
-├── trigger-system.ts     # Unified trigger engine: cron timers + pi event subscriptions + hybrid
-├── monitor-manager.ts    # ChildProcess tracking, output buffering, event emission, stop
-├── loop-parse.ts         # Human interval → cron expression, next-fire computation, jitter
+├── index.ts                          # Extension entry: tool/command registration, session wiring, native task fallback timer
+├── api.ts                            # Public subpath (@trevonistrevon/pi-loop/api): RPC channels/DTOs, TaskStore, scope resolvers
+├── types.ts                          # LoopKind, Trigger spec, LoopEntry, MonitorEntry, LoopConfig
+├── task-types.ts                     # TaskEntry, TaskStatus, TaskStoreData
+├── store.ts                          # File-backed CRUD (.pi/loops/loops.json) with file locking
+├── task-store.ts                     # File-backed CRUD for native fallback tasks (.pi/tasks/tasks.json)
+├── reducer-backed-store.ts           # Shared atomic-write + pid-lock persistence layer for reducer-driven stores
+├── coordinator.ts                    # ReducerSource/ReducerEvent/ReducerEffect plumbing shared by *-reducer/*-coordinator modules
+├── loop-reducer.ts                   # Pure loop state transitions, incl. maxFires/expiry checks
+├── monitor-reducer.ts                # Pure monitor state transitions
+├── notification-reducer.ts           # Pure pending-notification state transitions
+├── task-reducer.ts                   # Pure native task state transitions
+├── monitor-completion-coordinator.ts # Reduces monitor "onDone" completion into a fire effect
+├── task-backlog-coordinator.ts       # Reduces pending-task counts into auto-create/auto-clean effects
+├── scheduler.ts                      # Timer-based cron scheduler with jitter + 7-day expiry
+├── trigger-system.ts                 # Unified trigger engine: cron timers + pi event subscriptions + hybrid
+├── monitor-manager.ts                # ChildProcess tracking, output buffering, event emission, stop
+├── loop-parse.ts                     # Human interval → cron expression, next-fire computation, jitter
+├── rpc/                               # VENDORED — canonical copy shared verbatim with pi-orca; see "Cross-extension RPC" below
+│   ├── channels.ts                   # TASKS_RPC/SUBAGENTS_RPC/TASK_EVENTS channel constants + wire DTOs
+│   └── cross-extension-rpc.ts        # rpcCall (client), rpcProbe (detection), handleRpc (server), PROTOCOL_VERSION, RpcError
+├── runtime/                          # Extension-init-time wiring, one module per concern
+│   ├── loop-events.ts                # Auto-delete payload types for backlog-drained loops
+│   ├── monitor-ondone-runtime.ts     # Coordinator wiring for MonitorCreate's onDone → loop fire
+│   ├── native-task-rpc.ts            # tasks:rpc:* server: ping/pending/create/clean/update over the native TaskStore
+│   ├── notification-runtime.ts       # Pending-notification buffering + idle-driven delivery
+│   ├── scope.ts                      # PI_LOOP_SCOPE → loop/task store path resolution
+│   ├── session-runtime.ts            # Session-switch hooks, store (re)binding
+│   ├── task-backlog-runtime.ts       # Auto-create/auto-clean backlog worker evaluation
+│   ├── task-events.ts                # emitNativeTaskEvent: tasks:created/started/completed/reopened/updated/deleted
+│   ├── task-mutations.ts             # Shared mutation service: mutate → emit event → widget → backlog, used by RPC server and tools
+│   └── task-rpc.ts                   # Client bridge: probes pi-tasks, falls back to native TaskStore for autoTask/pending/clean
+├── tools/                            # Tool implementations
+│   ├── loop-tools.ts                 # LoopCreate/LoopList/LoopDelete
+│   ├── monitor-tools.ts              # MonitorCreate/MonitorList/MonitorStop
+│   ├── native-task-tools.ts          # TaskCreate/TaskList/TaskUpdate/TaskDelete (fallback only)
+│   └── tool-result.ts                # textResult() helper
+├── commands/
+│   ├── loop-command.ts               # /loop interactive loop creation
+│   └── tasks-command.ts              # /tasks native task viewer/manager
 └── ui/
-    └── widget.ts         # Persistent widget: active loops + monitors
+    └── widget.ts                     # Persistent widget: active loops + monitors + task summary
 ```
 
+## Cross-extension RPC
+`src/rpc/` is a **vendored** module: the canonical copy is maintained here and copied verbatim into the sibling `pi-orca` repo. If you edit `channels.ts` or `cross-extension-rpc.ts`, copy the change to `pi-orca` and bump the `VENDOR_REV` comment at the top of both files in both repos — the two copies must never drift.
+
+The wire contract is request/reply over `pi.events`: a caller emits `{ requestId, ...params }` on a channel (e.g. `tasks:rpc:create`), the server replies on `<channel>:reply:<requestId>` with an envelope, `{success:true,data}` or `{success:false,error}`. `rpcCall` resolves/rejects that promise, `rpcProbe` swallows the rejection into `undefined` for presence detection, `handleRpc` is the server-side helper that turns a handler function into a channel subscription with automatic envelope wrapping. `PROTOCOL_VERSION` (currently `2`) is returned in ping replies so callers can gate on server capability.
+
+`pi-loop`'s native tasks RPC server (`src/runtime/native-task-rpc.ts`) registers at extension init — not behind the native-tool-registration fallback timer — so early cross-extension calls never race it. It stands down (silent no-op via `isEnabled`) once an external `pi-tasks` is detected.
+
+## Public API surface
+External consumers must import `@trevonistrevon/pi-loop/api` (`src/api.ts`), never a deep `src/...` path. The package `exports` map in `package.json` enforces this — deep imports fail to resolve. `src/api.ts` re-exports the RPC channel constants/DTOs, `rpcCall`/`rpcProbe`/`handleRpc`/`RpcError`/`PROTOCOL_VERSION`, `TaskStore`, `TaskEntry`/`TaskStatus`, `resolveLoopStorePath`/`resolveTaskStorePath`, and `NATIVE_TASKS_PROVIDER`. Anything not re-exported there is internal and may change without notice.
+
 ## Conventions (mirror pi-tasks)
 - No comments unless answering "why", never "what"
 - `debug(...)` helper gated on `PI_LOOP_DEBUG` env var, logs to stderr
@@ -61,10 +104,7 @@ All loops are idle-driven. Cron and hybrid loops track their next fire time but
 Monitor stdout/stderr lines are emitted as `pi.events("monitor:output", { monitorId, line, timestamp })`. Tool consumers subscribe to these events. Completion emits `"monitor:done"` / `"monitor:error"`.
 
 ## pi-tasks Integration
-When `@tintinweb/pi-tasks` is present, `LoopCreate` with `autoTask: true` fires an RPC to create a task. Communication via `pi.events`:
-- `tasks:rpc:ping` on init → detect pi-tasks presence
-- `tasks:ready` listener → late-binding detection
-- `tasks:rpc:create` → auto-create task when loop fires (if `autoTask: true`)
+`pi-loop` probes for `@tintinweb/pi-tasks` at init via `tasks:rpc:ping` (see "Cross-extension RPC" above) and again on a `tasks:ready` listener for late binding. When an external provider answers, `LoopCreate` with `autoTask: true` calls `tasks:rpc:create` to create a tracked task on fire. When no external provider answers, `pi-loop`'s own native RPC server (`src/runtime/native-task-rpc.ts`) serves all five verbs — `ping`/`pending`/`create`/`clean`/`update` — against the native `TaskStore`, and `autoTask: true` creates a native task directly instead of over RPC.
 
 ## /loop Self-Paced Mode
 When no interval is specified in `/loop prompt`, the loop runs in self-paced mode. The agent receives the prompt, acts on it, and uses `LoopCreate`/`LoopUpdate` to schedule the next iteration. The loop fires once, then the agent decides the next interval dynamically (matching Claude Code's dynamic interval behavior).

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## [0.6.0](https://github.com/trvon/pi-loop/compare/pi-loop-v0.5.8...pi-loop-v0.6.0) (2026-07-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* package exports map blocks deep src/ imports — consumers must use @trevonistrevon/pi-loop/api. tasks:updated now reports previousStatus at edit time, not pre-transition.
+
+### Features
+
+* add maxFires for self-limiting loops, event-driven prompt steering ([52b50f0](https://github.com/trvon/pi-loop/commit/52b50f0d2b8c0b1df6aa74b09a8561807b549fe6))
+* add native task fallback and compact task tracker ([6b5b6ff](https://github.com/trvon/pi-loop/commit/6b5b6fff53cc7810242e4f9081fe6d21b318c654))
+* add task decomposition guidance to TaskCreate prompt ([4c51e72](https://github.com/trvon/pi-loop/commit/4c51e72a7317e1433cdb5bed6cfc9dfa521b5bfb))
+* add tasks:rpc:clean RPC for sweeping done tasks ([73812ed](https://github.com/trvon/pi-loop/commit/73812ed4c3efeb08e97908e6de6435f65c768440))
+* auto-create task worker loop at backlog threshold ([430663a](https://github.com/trvon/pi-loop/commit/430663a8042560688e08bd08129ea57b190ccecc))
+* canonical rpc module + init-time task server ([7335eff](https://github.com/trvon/pi-loop/commit/7335eff6440452178ae9db3cb22a49098ad3953d))
+* generalize task backlog loop cleanup ([9132948](https://github.com/trvon/pi-loop/commit/9132948dc9e22cda32adf6e8c5e13a7203f9c864))
+* goal prompt and loading refinements ([b31df23](https://github.com/trvon/pi-loop/commit/b31df23c240f0bde7fb69fb8ea702429576276c7))
+* prune completed tasks after successful git commit ([cba120b](https://github.com/trvon/pi-loop/commit/cba120be3a7fcdf71b7f7649b414577412d26a94))
+* refining monitor interface ([66a6007](https://github.com/trvon/pi-loop/commit/66a60077093f40c258efeeb971f6f8db74e24f83))
+* show worker-loop hint when pending tasks reach 5+ ([74dbf2c](https://github.com/trvon/pi-loop/commit/74dbf2cbf7f55a4206762eee3731798527537ab5))
+* skip loop fires when autoTask loop has no pending tasks ([f2feb07](https://github.com/trvon/pi-loop/commit/f2feb079d5b520ed4c4dd0dc85d5b385efc45c45))
+* **tasks:** add native rpc update and backlog signals ([31d06f6](https://github.com/trvon/pi-loop/commit/31d06f61fce1333c359f0d38def7406474144f8b))
+* **tasks:** emit native task events with previousStatus tracking ([61b49ea](https://github.com/trvon/pi-loop/commit/61b49ea5703597b02754998269edfdc5b2018ebb))
+
+
+### Bug Fixes
+
+* add trigger validation, readOnly flag, and edge-case tests ([91baa07](https://github.com/trvon/pi-loop/commit/91baa07884bc20d760c7a3642c3ec462997fc0d3))
+* auto-delete worker loop when task backlog clears ([502fa10](https://github.com/trvon/pi-loop/commit/502fa106b8862c06648e6be373e5980d2af18f6f))
+* auto-expire monitor:done loops, buffer output, show completed monitors ([a3ec5de](https://github.com/trvon/pi-loop/commit/a3ec5de5847d67bddee9c572079b559b03e35f3f))
+* deduplicate loop follow-up messages to prevent flood ([1613511](https://github.com/trvon/pi-loop/commit/1613511a2453d346edb59919beed2bdb18c05f63))
+* delete done loops/monitors immediately instead of marking expired ([43f5220](https://github.com/trvon/pi-loop/commit/43f5220a3e6d807234e4bdb7611e44c0fa7468ec))
+* delete event maxFires loops immediately ([12335e7](https://github.com/trvon/pi-loop/commit/12335e75dcf8d17a2c887966cae180d2b2f848da))
+* deliver monitor onDone wakes without event dependency ([79d6a8b](https://github.com/trvon/pi-loop/commit/79d6a8b925aa98e8de0ea1b12addd5e0d2db0c47))
+* derive jitter ceiling from cron step, delete expired event loops ([6d13935](https://github.com/trvon/pi-loop/commit/6d13935e79d2367072bec027d5ef2cb430eff44a))
+* flush buffered worker wakes on agent end ([7a7dedf](https://github.com/trvon/pi-loop/commit/7a7dedf3ec7f16eb63edbfaf93e5dae9ed7a8f25))
+* harden TaskUpdate prompt to prevent taskId alias errors ([5dfefd9](https://github.com/trvon/pi-loop/commit/5dfefd96bb08c29d192de472c6224ac434394b6f))
+* **injection:** use before_agent_start message, not tool_result ([99a6317](https://github.com/trvon/pi-loop/commit/99a6317aabde8ce9d4f9e0c3065f42b6c6111259))
+* loop trigger fix ([619f32c](https://github.com/trvon/pi-loop/commit/619f32c48134d9cc1376a89a62a7c8d729321143))
+* **monitor:** make MonitorManager spawn-injectable, fix CI test timeouts ([f277646](https://github.com/trvon/pi-loop/commit/f277646b95369b43508fbbc8cc7eef5e37580781))
+* **monitor:** prune stopped/timed-out monitors ([a46f6e8](https://github.com/trvon/pi-loop/commit/a46f6e8f2b99fa39bd11ff22d1a34999e1ac4434))
+* only dedup recurring loop fires, always deliver one-shot events ([352e50e](https://github.com/trvon/pi-loop/commit/352e50e1de14ecd8d884b18a8e72572270ca90e9))
+* **persist:** expire event loops on session start, clean stale monitors ([7f0876d](https://github.com/trvon/pi-loop/commit/7f0876d821e93e663f43ec2d5351bc9a37223b4b))
+* recommend 5m default interval in LoopCreate task-continuation prompt ([1af3bcd](https://github.com/trvon/pi-loop/commit/1af3bcd35a2782f9fc333559d293c665db76c234))
+* release please fix ([16e2304](https://github.com/trvon/pi-loop/commit/16e2304ea3112664c12c65b4e098e04d390f93f0))
+* **reminders:** make loop reminder directive, not informational ([e21174d](https://github.com/trvon/pi-loop/commit/e21174df3d1d9403684e094f5763db33ed9cb732))
+* repair native task fallback compilation ([a8cef04](https://github.com/trvon/pi-loop/commit/a8cef04eabd8a8af404d27ffa756266ee6a188ec))
+* **runtime:** unref retention timer, swallow heartbeat pump errors ([602816b](https://github.com/trvon/pi-loop/commit/602816b3abb06859a0268c02119cc753de03decb))
+* scope native task files by session, prevent cross-session leakage ([0436710](https://github.com/trvon/pi-loop/commit/04367102414dd56f7668e1522b91c6f089490979))
+* **tasks:** gate late native RPC probes ([c97f4ad](https://github.com/trvon/pi-loop/commit/c97f4ad6800c00b9858c1a8e640f13e699e0c26a))
+* **tasks:** guard native fallback registration ([7d3b74a](https://github.com/trvon/pi-loop/commit/7d3b74abfa637bbe370ae232b8067e7bc5205ea1))
+* **trigger:** auto-expire non-recurring event loops ([178f9fd](https://github.com/trvon/pi-loop/commit/178f9fd6a6548a04307f3ed83935068a235c24d3))
+* use pi.hasPendingMessages() instead of bespoke tracking Set ([dab60d4](https://github.com/trvon/pi-loop/commit/dab60d46340fab04ae74b80044ad03b6b0ca9fe8))
+
+
+### Performance Improvements
+
+* **test:** replace real 6.1s waits with fake-timer advance in onDone tests ([c713ad3](https://github.com/trvon/pi-loop/commit/c713ad36f958d53e75c4c7d7fd723c06ee420543))
+
 ## [0.1.2]
 
 - Added `onDone` parameter to `MonitorCreate` — auto-creates a completion loop so the agent is notified when a background process finishes, no polling needed

package/CONTRIBUTING.md

@@ -19,19 +19,22 @@ npm install
 | `npm run lint:fix` | Auto-fix lint issues |
 | `npm test` | Run tests (`vitest run`) |
 | `npm run test:watch` | Watch mode |
+| `npm run test:coverage` | Run tests with coverage (used in CI) |
+| `npm run test:e2e` | Run `test/e2e/reminder-injection.sh` (self-skips without a local llama server) |
 | `npm run build` | Compile TypeScript |
 
 ## Architecture
 
-See `AGENTS.md` for the full architecture overview. Key modules:
+See `AGENTS.md` for the full architecture overview and directory tree, including `src/rpc/` (vendored cross-extension RPC) and `src/api.ts` (public `@trevonistrevon/pi-loop/api` subpath — the only supported import path for external consumers). Key modules:
 
-- **`src/index.ts`** — Extension entry: registers 6 tools + `/loop` `/loops` commands + widget lifecycle
+- **`src/index.ts`** — Extension entry: registers tools, `/loop` `/tasks` commands, widget lifecycle, cross-extension RPC server
 - **`src/types.ts`** — Core types: `LoopEntry`, `MonitorEntry`, `Trigger` variants
 - **`src/store.ts`** — File-backed CRUD with pid-based file locking (atomic write → rename)
 - **`src/scheduler.ts`** — Timer-based cron scheduler with per-loop jitter and 7-day expiry
 - **`src/trigger-system.ts`** — Unified engine: cron timers + pi event subscriptions + hybrid debounce
 - **`src/monitor-manager.ts`** — `ChildProcess` wrapper: stdout/stderr streaming as pi events
 - **`src/loop-parse.ts`** — Human interval parsing (`5m` → cron), cron matching, next-fire computation
+- **`src/runtime/native-task-rpc.ts`** — `tasks:rpc:*` server for the native fallback task store
 - **`src/ui/widget.ts`** — TUI widget rendering active loops + monitors above the editor
 
 ## Conventions
@@ -58,12 +61,19 @@ npm test            # Run once
 npm run test:watch  # Watch mode
 ```
 
+### Manual fixtures (not run in CI)
+
+- `benchmarks/experiment-sim.js` — synthetic monitor fixture: prints periodic `iteration N/M, loss=...` lines and handles `SIGTERM` with a checkpoint message. Used to manually exercise `MonitorCreate` streaming, `onDone`, and stop handling. Run with `node benchmarks/experiment-sim.js`. Not wired into CI by design — it's a fixture, not an assertion.
+- `test/e2e/reminder-injection.sh` (`npm run test:e2e`) — drives a real `pi` session against a local llama server to validate loop/reminder injection end to end. Requires a model server reachable at `localhost:2276`; the script checks for it and self-skips (exit 0) when absent. Never runs in CI — there is no llama server in the CI environment.
+
 ## Pull Request Workflow
 
 1. Fork, branch, implement
-2. Ensure `npm run typecheck`, `npm run lint`, and `npm test` all pass
+2. Ensure `npm run lint`, `npm run typecheck`, and `npm run test:coverage` all pass, then `npm run build`
 3. Open PR against `main`
 
+CI (`.github/workflows/ci.yml`) runs the same validation in this order on Node 20.x and 22.x: `lint` → `typecheck` → `test:coverage` → `build`.
+
 ## License
 
 By contributing, you agree that your contributions will be licensed under the MIT License.

package/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:22-alpine AS base
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+
+FROM node:20-alpine AS node20
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+
+FROM node:22-alpine AS node22
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .

package/README.md

@@ -81,9 +81,56 @@ If `pi-tasks` does not respond during startup detection, `pi-loop` registers a n
 - `TaskCreate`, `TaskList`, `TaskUpdate`, `TaskDelete`
 - `/tasks` interactive viewer
 - compact status-line task tracking
+- native task RPC replies on `tasks:rpc:ping`, `tasks:rpc:create`, `tasks:rpc:pending`, `tasks:rpc:clean`, and `tasks:rpc:update`
 
 This fallback is session-sticky: `pi-loop` decides once at startup whether `pi-tasks` or native tasks own task management for that session.
 
+### Task and backlog events
+
+`pi-loop` emits native task lifecycle events that other extensions can consume directly:
+
+- `tasks:created`
+- `tasks:started`
+- `tasks:completed`
+- `tasks:reopened`
+- `tasks:updated`
+- `tasks:deleted`
+
+Payloads carry `previousStatus`. Transition events (`tasks:started` /
+`tasks:completed` / `tasks:reopened`) report the status before the transition;
+`tasks:updated` (a details edit) reports the status current at edit time — so a
+combined status+details update never fabricates a second transition. (Changed
+in 0.6.0: the tool path previously reused the pre-transition status.)
+- `tasks:backlog_empty` — emitted when a task-backlog worker observes zero pending tasks and is about to auto-delete
+- `loops:autodeleted` — emitted for each loop that `pi-loop` auto-deletes, including backlog workers removed because the task queue drained
+
+### Cross-extension task RPC
+
+Other extensions can create and manage native tasks without importing `pi-loop` internals. `pi-loop` answers `ping` over `pi.events` from extension init; the other verbs unlock once the pi-tasks detection probe settles (a few seconds at most, immediate when no provider replies race it). The whole server stands down (silent no-op) once an external `pi-tasks` is detected:
+
+| Channel | Request | Reply |
+|---|---|---|
+| `tasks:rpc:ping` | `{}` | `{ version, provider }` |
+| `tasks:rpc:pending` | `{}` | `{ pending }` |
+| `tasks:rpc:create` | `{ subject, description, metadata? }` | `{ id, task }` |
+| `tasks:rpc:clean` | `{}` | `{ pruned }` |
+| `tasks:rpc:update` | `{ id, status?, subject?, description? }` | `{ task }` |
+
+Every request/reply pair follows the same contract: emit `{ requestId, ...params }` on the channel, receive an envelope on `<channel>:reply:<requestId>` — `{ success: true, data }` or `{ success: false, error }`.
+
+`@trevonistrevon/pi-loop/api` exports typed channel constants and a client helper so consumers don't hand-roll the envelope:
+
+```ts
+import { TASKS_RPC, rpcCall } from "@trevonistrevon/pi-loop/api";
+
+const { id, task } = await rpcCall(pi.events, TASKS_RPC.create, {
+  subject: "Fix deploy polling",
+  description: "Switch deploy check to event-driven loop",
+});
+```
+
+`rpcCall` rejects on failure or timeout instead of returning a sentinel; wrap it in `try/catch` if you want fallback behavior. Import only from `@trevonistrevon/pi-loop/api` — the package's `exports` map blocks deep `src/` imports.
+
 ## Status line
 
 `pi-loop` keeps a compact persistent status line in the TUI.