pi-sleep-agent 0.8.1 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,14 +6,14 @@
6
6
 
7
7
  Capture while agents work. Consolidate when they stop. Promote only what you approve.
8
8
 
9
- [![Tests](https://img.shields.io/badge/tests-127%20passing-c4f042?labelColor=111827&style=flat-square)](#install)
9
+ [![Tests](https://img.shields.io/badge/tests-177%20passing-c4f042?labelColor=111827&style=flat-square)](#install)
10
10
  [![Python](https://img.shields.io/badge/python-3.10%2B-369eff?labelColor=111827&style=flat-square)](https://www.python.org/)
11
11
  [![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-ffcb47?labelColor=111827&style=flat-square)](#install)
12
- [![Agents](https://img.shields.io/badge/agents-Pi%20%7C%20Claude-a78bfa?labelColor=111827&style=flat-square)](#supported-agents)
12
+ [![Agents](https://img.shields.io/badge/agent%20targets-9-a78bfa?labelColor=111827&style=flat-square)](#supported-agents)
13
13
 
14
14
  </div>
15
15
 
16
- Sleep adds a reviewable memory cycle to Pi, OmO, and Claude Code. It records useful observations during a session, turns them into provisional memory after the session, and keeps permanent memory behind an explicit human approval step.
16
+ Sleep adds a reviewable memory cycle to nine selectable coding-agent targets. It records useful observations during a session, turns them into provisional memory after the session, and keeps permanent memory behind an explicit human approval step.
17
17
 
18
18
  <p align="center">
19
19
  <img src=".github/assets/sleep-replay.png" alt="Terminal showing the sleep cycle: agents capture observations, sleep consolidates them into provisional memory, and only your promote makes them permanent" width="920" />
@@ -42,18 +42,83 @@ Requirements:
42
42
 
43
43
  - Python 3.10 or newer
44
44
  - Claude Code CLI for model-backed consolidation and replay
45
- - Pi, OmO, Claude Code, or any combination of them
45
+ - One or more supported coding agents from the table below
46
46
 
47
47
  ```bash
48
48
  ./install.sh --dry-run # show every change without writing
49
- ./install.sh # install the shared skill and Claude Code hooks
50
- ./install.sh --extension # also install the Pi/OmO extension
51
- ./install.sh --launchd # also schedule the nightly pass on macOS
49
+ ./install.sh # install skill + hooks; asks whether to add the
50
+ # nightly pass and the Pi/OmO extension (no flags needed)
51
+ ./install.sh --extension # also install the Pi/OmO extension (no prompt)
52
+ ./install.sh --nightly # also schedule the nightly pass (no prompt)
53
+ ./install.sh --launchd # alias for --nightly (macOS convention)
52
54
  ```
53
55
 
54
- The installer runs the test suite first, creates backups before configuration changes, and is safe to run again.
56
+ On Windows the entry point `./install.sh` becomes `python tools\install.py` (or
57
+ `py tools\install.py`); the flags are identical:
55
58
 
56
- ### Pi / OmO extension
59
+ ```bat
60
+ py tools\install.py --dry-run
61
+ py tools\install.py --extension --nightly
62
+ ```
63
+
64
+ **Which agents get the capture hooks is your choice.** A plain `install.py` on a
65
+ real terminal asks which coding agents to wire (multi-select, default Claude Code).
66
+ Scripts and CI can pick explicitly without a prompt:
67
+
68
+ ```bash
69
+ python3 tools/install.py --agents claude # Claude Code only (default)
70
+ python3 tools/install.py --agents claude,gemini,cursor # several verified hook formats
71
+ python3 tools/install.py --agents pi,oh-my-pi # extension targets stay independent
72
+ SLEEP_PROJECT=/path/to/project python3 tools/install.py --agents opencode
73
+ ```
74
+
75
+ Accepted keys are `claude`, `gemini`, `pi`, `oh-my-pi`, `cursor`, `opencode`,
76
+ `windsurf`, `codex`, and `cline`. The interactive prompt shows the same list.
77
+ Selecting one key never installs another key. The older `--extension` flag selects
78
+ `pi` only.
79
+
80
+ | Key | Surface written | Capability | Confidence |
81
+ |---|---|---|---|
82
+ | `claude` | `$CLAUDE_HOME/settings.json` | Prompt capture, tool capture, stop and compact consolidation | Verified |
83
+ | `gemini` | `~/.gemini/settings.json` | `BeforePrompt`, `AfterTool`, `SessionEnd` | Measured hook grammar |
84
+ | `pi` | `~/.omo/agent/extensions/sleep` | Full TypeScript extension capture and context injection | Verified |
85
+ | `oh-my-pi` | `~/.omp/agent/extensions/sleep` | Pi-lineage extension path | Best effort |
86
+ | `cursor` | `~/.cursor/hooks.json` | Tool capture and session-end consolidation | Documented native hooks |
87
+ | `opencode` | `<project>/.opencode/` | Tool capture and idle consolidation through a project plugin | Verified plugin grammar |
88
+ | `windsurf` | `~/.codeium/windsurf/hooks.json` | Prompt and code-write capture | Measured hook grammar |
89
+ | `codex` | `~/.codex/config.toml` | Completion notification only; no per-turn prompt capture | Documented, limited |
90
+ | `cline` | VS Code user `settings.json` | `request_created` capture only | Best effort |
91
+
92
+ OpenCode is project-scoped. Set `SLEEP_PROJECT` when the project is not the
93
+ current directory. The installer renders the repository path into the copied
94
+ plugin and registers `./.opencode/plugins` in that project's
95
+ `.opencode/opencode.json`.
96
+
97
+ Codex has no per-turn hook. Its `[notify]` integration can wake consolidation
98
+ when a run completes, but it cannot capture the prompt stream. If `[notify]`
99
+ already owns a different command, Sleep leaves it unchanged. Cline and Oh My Pi
100
+ are marked best effort because their public integration contracts are less stable.
101
+ A missing event should be reported with the affected agent, config path, and the
102
+ last lines from `~/.sleep/logs/`.
103
+
104
+ Amp, Antigravity, GitHub Copilot, Aider, and OpenHands are not installer targets.
105
+ Their available surfaces are respectively absent/unstable lifecycle hooks or
106
+ transcript/event-stream polling, which this installer does not impersonate as a
107
+ working command-hook integration.
108
+
109
+ The installer runs the test suite first, creates backups before configuration
110
+ changes, and is safe to run again. `--dry-run` does not modify existing links or
111
+ config files. Uninstall removes only exact Sleep-owned commands, preserves foreign
112
+ entries, and backs up JSON/TOML files before changing them. It is one Python
113
+ script and works on macOS, Linux, and Windows; per-platform scheduling is chosen
114
+ automatically:
115
+
116
+ - **macOS** - a LaunchAgent (`~/Library/LaunchAgents/com.aydinnyunus.sleep-nightly.plist`).
117
+ - **Linux** - a cron job (`crontab -l`, kept inside owned `# BEGIN/END aydinnyunus-sleep-nightly` markers).
118
+ - **Windows** - a Task Scheduler task via `schtasks /create /tn aydinnyunus-sleep-nightly`.
119
+
120
+
121
+ ### Pi / OmO and Oh My Pi extensions
57
122
 
58
123
  Pi and OmO require Sleep's user-installed extension for automatic integration:
59
124
 
@@ -61,12 +126,17 @@ Pi and OmO require Sleep's user-installed extension for automatic integration:
61
126
  ./install.sh --extension
62
127
  ```
63
128
 
64
- The installer links this repository's `extension/` directory to:
129
+ The installer links this repository's `extension/` directory to the selected
130
+ extension target only:
65
131
 
66
132
  ```text
67
- ~/.omo/agent/extensions/sleep
133
+ pi -> ~/.omo/agent/extensions/sleep
134
+ oh-my-pi -> ~/.omp/agent/extensions/sleep
68
135
  ```
69
136
 
137
+ Use `--agents oh-my-pi` for Oh My Pi. `--extension` remains an alias for selecting
138
+ `pi`; it does not install Oh My Pi implicitly.
139
+
70
140
  The extension loads on the next Pi or OmO session and performs three jobs:
71
141
 
72
142
  - captures user messages and relevant tool activity into T0,
@@ -136,6 +206,8 @@ To remove Sleep and restore the backed-up configuration:
136
206
  ./uninstall.sh
137
207
  ```
138
208
 
209
+ On Windows, `python tools\uninstall.py` (or `py tools\uninstall.py`).
210
+
139
211
  ## Quick start
140
212
 
141
213
  Check the installation:
@@ -202,7 +274,7 @@ A dream pass performs four steps:
202
274
 
203
275
  1. **Mine.** Find instructions you repeated across separate sessions in the same project. This step is deterministic and makes no model call.
204
276
  2. **Consolidate.** When the sleep gate passes, ask the configured model to turn recent T0 observations into provisional T1 candidates.
205
- 3. **Hygiene.** Run the read-only `doctor` scan and fold any findings (duplicate headings, near-duplicate candidates, or stale values when you pass `--stale <value>`) into the night's report.
277
+ 3. **Hygiene.** Run the read-only `doctor` scan and fold any findings (duplicate headings, near-duplicate candidates, records parked in quarantine awaiting review, or stale values when you pass `--stale <value>`) into the night's report.
206
278
  4. **Replay.** When replay is due, run selected tasks with provisional memory off and on, then write a comparison report.
207
279
 
208
280
  Every result stays reviewable. Candidates remain in T1 until you explicitly run `promote`.
@@ -246,7 +318,7 @@ Run the two dream components separately when you want more control:
246
318
  | `./sleep.py replay --run --limit 3` | Compare selected tasks with memory off and on |
247
319
  | `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
248
320
  | `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
249
- | `./sleep.py doctor` | Find duplicate or overlapping memory records, and flag provisional candidates not rediscovered for 4+ weeks (report only, never dropped) |
321
+ | `./sleep.py doctor` | Find duplicate or overlapping memory records, flag provisional candidates not rediscovered for 4+ weeks, and report records parked in quarantine awaiting a human (report only, never dropped or un-parked) |
250
322
  | `./sleep.py doctor --stale <value>` | Show which approved records still hold a stale value (e.g. a changed URL) |
251
323
  | `./sleep.py inject --project "$PWD"` | Print provisional context for the current project |
252
324
 
@@ -254,12 +326,12 @@ Run `./sleep.py <command> --help` for command-specific options.
254
326
 
255
327
  ## Supported agents
256
328
 
257
- | Agent | Integration |
258
- |---|---|
259
- | Claude Code | `UserPromptSubmit`, `PostToolUse`, `Stop`, and `PreCompact` hooks |
260
- | Pi / OmO | Required user-installed extension: `./install.sh --extension` |
261
-
262
- Both integrations share `$SLEEP_HOME`, so candidates reviewed from one client are visible to the other when the project scope matches.
329
+ The installer support matrix and confidence levels live in [Install](#install).
330
+ All selected integrations share `$SLEEP_HOME`, so candidates reviewed from one
331
+ client are visible to another when the project scope matches. Capture depth is not
332
+ identical: Claude, Gemini, Pi/OmO, OpenCode, Cursor, and Windsurf expose multiple
333
+ lifecycle boundaries; Codex is completion-only; Cline is request-created-only;
334
+ Oh My Pi is a best-effort Pi-lineage extension path.
263
335
 
264
336
  ## Configure unattended model calls
265
337
 
@@ -305,7 +377,7 @@ Additional safeguards:
305
377
  - Provisional memory is rendered as background, not as an instruction.
306
378
  - Secret-like values are replaced with redaction markers.
307
379
  - Prompt-injection and exfiltration shapes are moved to quarantine.
308
- - Mixed-project buffers fail closed instead of assigning facts to the wrong project.
380
+ - Mixed-project buffers are partitioned by project and consolidated separately; unaddressed records stay in T0.
309
381
  - Replay reports results but never promotes memory automatically.
310
382
  - Every model call has an explicit budget limit.
311
383
 
@@ -360,14 +432,15 @@ Use `--force` only when you intentionally want a model call.
360
432
 
361
433
  **The scheduled pass cannot reach the model**
362
434
 
363
- Confirm that `~/.sleep/env` exists, has mode `0600`, and contains the same provider settings used by your interactive shell. Then run `./sleep.py sleep --force` before relying on launchd.
435
+ Confirm that `~/.sleep/env` exists, has mode `0600`, and contains the same provider settings used by your interactive shell. Then run `./sleep.py sleep --force` before relying on the scheduled pass (launchd / cron / Task Scheduler).
364
436
 
365
437
  **A candidate appears in the wrong context**
366
438
 
367
- Run `./sleep.py show <id>` and check its `cwd`. Mixed-project batches are kept in T0 and return an error instead of producing candidates.
439
+ Run `./sleep.py show <id>` and check its `cwd`. Mixed-project batches are partitioned by canonical `cwd`; each project is consolidated independently, while records without a project address stay in T0.
368
440
 
369
441
  ## More documentation
370
442
 
443
+ - [Sleep: the reviewable-memory extension for coding agents](https://aydinnyunus.github.io/2026/11/01/sleep-agent-memory-extension/) (blog)
371
444
  - [Measured evidence and validation history](docs/EVIDENCE.md)
372
445
  - [Sleep Framework analysis](sleep-framework.md)
373
- - [Shared `/sleep` skill](skill/sleep/SKILL.md)
446
+ - [Shared `/sleep` skill](shared-skill/sleep/SKILL.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-sleep-agent",
3
- "version": "0.8.1",
3
+ "version": "0.8.2",
4
4
  "description": "A reviewable sleep and dream cycle for Pi agent memory.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -141,6 +141,24 @@ _RELAY_WEAK = [
141
141
  r"read-only code review\.|work in the git repo\b)"), "addressed to a role"),
142
142
  ]
143
143
 
144
+ # A skill's body reaches the hook as a typed prompt: the person invokes a slash command
145
+ # and the harness sends the skill text as the user turn, so it looks like authored speech
146
+ # while it is a program's instructions to a model. Measured 2026-11-01: the payload of
147
+ # ~/.claude-work/skills/ai-evaluator-pass/SKILL.md was captured twice as source=user and
148
+ # mined into a "preference" candidate; the shape gives it away. It is COMPOUND on purpose:
149
+ # a verdict token alone ("return PASS or FAIL") is something a person also types when they
150
+ # want a review, so it only counts together with a body-level constraint ("be concise",
151
+ # "do not edit files") that a slash-command payload carries and a person rarely does.
152
+ _RELAY_VERDICT = re.compile(
153
+ r"(?i)\b(?:return|respond with|answer|reply)\s+(?:pass|fail|ok|done)\b"
154
+ r"(?:\s*(?:or|/)\s*(?:pass|fail|ok|done)\b)?")
155
+ _RELAY_BODY_CONSTRAINT = re.compile(
156
+ r"(?i)\b(?:do not (?:edit|modify|write|create|touch)\s+(?:any\s+)?files?|be concise)\b")
157
+ _RELAY_COMPOUND = [
158
+ (lambda t: bool(_RELAY_VERDICT.search(t)) and bool(_RELAY_BODY_CONSTRAINT.search(t)),
159
+ "skill payload (verdict token + body constraint)"),
160
+ ]
161
+
144
162
 
145
163
  def machine_driven(environ: dict | None = None) -> str:
146
164
  """Name of an env marker proving this session was spawned by a host, else "".
@@ -163,6 +181,9 @@ def relay_reason(text: str, environ: dict | None = None) -> str | None:
163
181
  for pat, why in _RELAY_STRONG:
164
182
  if pat.search(t):
165
183
  return why
184
+ for pred, why in _RELAY_COMPOUND:
185
+ if pred(t):
186
+ return why
166
187
  if machine_driven(environ):
167
188
  for pat, why in _RELAY_WEAK:
168
189
  if pat.search(t):
package/sleepkit/store.py CHANGED
@@ -651,4 +651,17 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
651
651
  if sim >= 0.7:
652
652
  out.append({"issue": "candidate-duplicates-memory", "id": cid, "file": path,
653
653
  "similarity": round(sim, 2)})
654
+ # Quarantine is a wait-for-a-human state, not a resting state: entries parked there
655
+ # are held out of every future consolidation until someone reads them. `doctor`
656
+ # reporting "clean" while the queue holds parked records is the failure a user hits
657
+ # by asking exactly the question doctor answers ("is anything waiting on me?").
658
+ # Report the count and the newest ids; nothing is dropped or changed here.
659
+ # Path assembled without paths.home(): home() creates the whole tier skeleton as a
660
+ # side effect, and a read-only report that lays down directories is not read-only.
661
+ qdir = os.path.join(paths.SLEEP_HOME, ".quarantine")
662
+ if os.path.isdir(qdir):
663
+ parked = sorted(f for f in os.listdir(qdir) if f.endswith(".json"))
664
+ if parked:
665
+ out.append({"issue": "quarantine-awaiting-review", "count": len(parked),
666
+ "newest": [f[:-5] for f in parked[-3:]]})
654
667
  return out