feat(plugins): ship SkillOpt-Sleep for Claude Code, Codex, and Copilot

Restructure into plugins/{claude-code,codex,copilot}/ — one engine, three thin shells, all calling the shared plugins/run-sleep.sh -> python -m skillopt_sleep. - claude-code/: existing plugin moved here; runner delegates to the shared launcher (fixes repo-root resolution after the move). - codex/: ~/.codex/prompts/sleep.md custom prompt + ~/.agents/skills SKILL.md + install.sh + AGENTS.md hint — Codex's documented, stable extension surfaces. - copilot/: a stdlib-only MCP server (mcp_server.py) exposing sleep_* tools, plus mcp-config.example.json and a copilot-instructions snippet. Verified end to end (initialize -> tools/list -> tools/call returns real engine output). - plugins/README.md overview table; main README News + a dedicated SkillOpt-Sleep section; pyproject lists skillopt_sleep as a first-class package. Decoupling emphasized throughout: open-source tool (skillopt_sleep/) with zero dependency on the research package. 29 tests pass; all three shells resolve. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
2026-06-08 14:31:52 +00:00
parent b02ffc2c99
commit f9db99853b
22 changed files with 576 additions and 31 deletions
@@ -7,6 +7,7 @@
 ---
 ## News 🔥🔥🔥
 - **[2026-06-08]** 😴 **SkillOpt-Sleep is here — plugins for Claude Code, Codex, and Copilot.** Give your local coding agent a nightly *sleep cycle*: it reviews your past sessions offline, replays your recurring tasks, and consolidates validated long-term memory + skills behind a held-out gate —越用越好用. Validated on the public [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1` benchmark with **real Claude and Codex** (deficient skills 0.00 → 1.00 on held-out, all 4 seeds). It's an **open-source tool decoupled from the paper code**. See [`plugins/`](plugins/) and the [SkillOpt-Sleep section](#-skillopt-sleep--越用越好用-the-deployment-time-companion) below.
 - **[2026-06-03]** 🎉 **[gbrain](https://github.com/garrytan/gbrain), [gbrain-evals](https://github.com/garrytan/gbrain-evals/blob/main/docs/benchmarks/2026-06-03-skillopt.md), and [darwin-skill](https://github.com/alchaincyf/darwin-skill) have all integrated SkillOpt.**
 - **[2026-06-02]** 🎉 **SkillOpt [v0.1.0](https://github.com/microsoft/SkillOpt/releases/tag/v0.1.0) is now available on [PyPI](https://pypi.org/project/skillopt/)!** Install with `pip install skillopt`. This initial release includes the full training loop (rollout → reflect → aggregate → select → update → evaluate), multi-backend support (OpenAI / Azure / Claude / Qwen / MiniMax), six built-in benchmarks, and WebUI dashboard.
@@ -50,6 +51,51 @@ https://github.com/user-attachments/assets/eb12d3bc-371c-467f-904d-91b61f339ed7
 ---
 ## 😴 SkillOpt-Sleep — 越用越好用, the deployment-time companion
 SkillOpt (above) trains a skill offline on a benchmark. **SkillOpt-Sleep**
 applies the same discipline to *your own daily usage*: it gives a local coding
 agent a nightly **sleep cycle** that reviews your past sessions, replays your
 recurring tasks on your own API budget, and consolidates what it learns into
 **validated** long-term memory and skills — behind a held-out gate, staged for
 your review. The agent gets better the more you use it, with no weight training.
 It synthesizes **SkillOpt** (validation-gated bounded text edits), **Claude
 Dreams** (offline consolidation; review-then-adopt), and the **agent sleep**
 idea (short-term experience → long-term competence). One "night":
 ```
 harvest session transcripts → mine recurring tasks → replay offline
   → consolidate (reflect → bounded edit → GATE on real held-out tasks)
   → stage proposal → (you) adopt
 ```
 **Plugins for three agents** (one engine, three thin shells — see [`plugins/`](plugins/)):
 | Platform | Folder | Install |
 |---|---|---|
 | **Claude Code** | [`plugins/claude-code`](plugins/claude-code) | `/plugin marketplace add ./plugins/claude-code` → `/sleep` |
 | **Codex** | [`plugins/codex`](plugins/codex) | `bash plugins/codex/install.sh` → `/sleep` |
 | **Copilot** | [`plugins/copilot`](plugins/copilot) | register `plugins/copilot/mcp_server.py` as an MCP server |
 **Validated on real models.** On the public
 [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1` benchmark,
 deficient skills go **0.00 → 1.00** on held-out sets with **both Claude and
 Codex** (all 4 seeds, including a real tool-use loop), cross-model transfer is
 positive, and the gate blocks regressions
 ([full results](docs/sleep/FINAL_REPORT.md)).
 > **Open-source tool, decoupled from the research.** The engine lives in the
 > top-level [`skillopt_sleep/`](skillopt_sleep) package with **zero dependency**
 > on the paper's `skillopt/` experiment code (the validation gate is vendored).
 > Controls — optional gate, multi-rollout contrastive reflection, token/time
 > budget, multi-objective reward, user preferences, optimizer/target split — are
 > documented in [`docs/sleep/CONTROLLABLE_DREAMING.md`](docs/sleep/CONTROLLABLE_DREAMING.md).
 Deterministic proof (no API key): `python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves`.
 ---
 ## Install
 ### Requirements
@@ -0,0 +1,74 @@
 # SkillOpt-Sleep — plugins for Claude Code, Codex, and Copilot
 One engine, three thin shells. **SkillOpt-Sleep** gives a local coding agent a
 nightly **sleep cycle**: it reviews your past sessions offline, replays your
 recurring tasks on your own API budget, and consolidates what it learns into
 **validated** long-term memory and skills — behind a held-out gate, staged for
 your review. Your agent gets better the more you use it, with no model-weight
 training.
 It synthesizes three ideas: **SkillOpt** (validation-gated bounded text
 optimization — the research in this repo), **Claude Dreams** (offline memory
 consolidation; input never mutated; review-then-adopt), and the **agent sleep**
 literature (short-term experience → long-term competence).
 > **This is an open-source tool, decoupled from the research code.** The engine
 > lives in the top-level [`skillopt_sleep/`](../skillopt_sleep) package and has
 > **zero dependency** on the paper's `skillopt/` experiment package (the
 > validation gate is vendored). You can ship/use it without the research stack.
 ## The three integrations
 | Platform | Folder | Mechanism | Status |
 |---|---|---|---|
 | **Claude Code** | [`claude-code/`](claude-code) | `.claude-plugin` + `/sleep` command + skill + hooks | full, installable |
 | **Codex** | [`codex/`](codex) | `~/.codex/prompts/sleep.md` + `~/.agents/skills` + `AGENTS.md` | full |
 | **Copilot** | [`copilot/`](copilot) | MCP server (`sleep_*` tools) + `copilot-instructions` | full (MCP) |
 All three call the **same** [`plugins/run-sleep.sh`](run-sleep.sh) → `python -m
 skillopt_sleep`, so behaviour is identical everywhere. Per-platform setup is in
 each folder's README.
 ## Quick start (Claude Code)
 ```bash
 git clone <repo-url> && cd SkillOpt-Sleep
 # Claude Code:
 /plugin marketplace add ./plugins/claude-code
 /plugin install skillopt-sleep@skillopt-sleep
 /sleep status
 ```
 Codex: `bash plugins/codex/install.sh`.
 Copilot: register `plugins/copilot/mcp_server.py` as an MCP server.
 ## What one "night" does
 ```
 harvest ~/.claude (or session) transcripts → mine recurring tasks → replay offline
   → consolidate (reflect → bounded edit → GATE on real held-out tasks)
   → stage proposal → (you) adopt
 ```
 Nothing live changes until you adopt; every adopt backs up first.
 ## Controls (work on all platforms)
 `--gate on|off` · `--rollouts-k K` (multi-rollout contrastive reflection) ·
 `--budget-tokens/--budget-minutes` · `--preferences "..."` · separate
 optimizer/target models (`--optimizer-model` / `--target-model`) · slow-update
 long-term memory. Full guide:
 [`../docs/sleep/CONTROLLABLE_DREAMING.md`](../docs/sleep/CONTROLLABLE_DREAMING.md).
 ## Does it actually work?
 Validated on the public
 [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1` benchmark
 with **real models on both Claude and Codex**: deficient skills go **0.00 →
 1.00** on held-out sets (all 4 seeds incl. a real tool-use loop), cross-model
 transfer is positive, and the gate blocks regressions. Full results:
 [`../docs/sleep/FINAL_REPORT.md`](../docs/sleep/FINAL_REPORT.md).
 Deterministic proof (no API key):
 ```bash
 python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves
 ```
@@ -0,0 +1,11 @@
 #!/usr/bin/env bash
 # Claude Code plugin runner — thin wrapper over the shared runner so all three
 # platform plugins share one engine launcher. The shared runner lives at
 # <repo>/plugins/run-sleep.sh and handles repo-root + interpreter resolution.
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # <repo>/plugins/claude-code/scripts
 SHARED="$(cd "$HERE/../.." && pwd)/run-sleep.sh"        # <repo>/plugins/run-sleep.sh
 if [ ! -f "$SHARED" ] && [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
  SHARED="$(cd "$CLAUDE_PLUGIN_ROOT/.." && pwd)/run-sleep.sh"
 fi
 exec bash "$SHARED" "$@"
@@ -0,0 +1,59 @@
 # SkillOpt-Sleep — Codex integration
 Give your **Codex** agent a nightly **sleep cycle**: it reviews past sessions
 offline, replays your recurring tasks on your own Codex budget, and consolidates
 what it learns into validated memory + skills behind a held-out gate. Same engine
 as the Claude Code plugin (`skillopt_sleep`), wrapped for Codex.
 > **Verified on Codex:** on the public
 > [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1`
 > benchmark, a deliberately deficient skill goes **0.00 → 1.00** on a held-out
 > set with the Codex backend (incl. the tool-use seed via a real tool loop).
 > See [`../../docs/sleep/FINAL_REPORT.md`](../../docs/sleep/FINAL_REPORT.md).
 ## What Codex supports (and what we use)
 Codex (`@openai/codex`) extends via **`AGENTS.md`** instructions, **skills** at
 `~/.agents/skills/<name>/SKILL.md`, and **custom prompts** at
 `~/.codex/prompts/<name>.md` (invoked as `/<name>`). This integration ships all
 three, plus a shared runner.
 ## Install
 ```bash
 git clone <repo-url> SkillOpt-Sleep
 cd SkillOpt-Sleep
 bash plugins/codex/install.sh          # installs the /sleep prompt + skill
 export SKILLOPT_SLEEP_REPO="$(pwd)"    # so the runner is found from anywhere
 ```
 Requires Python ≥ 3.10 and the `codex` CLI on PATH.
 ## Use
 ```text
 /sleep status      # what's happened
 /sleep dry-run     # safe preview, stages nothing
 /sleep run         # full cycle, stages a reviewed proposal (no live edits)
 /sleep adopt       # apply the staged proposal (with backup)
 ```
 Or call the engine directly:
 ```bash
 python -m skillopt_sleep run --project "$(pwd)" --backend codex
 ```
 Default backend is `mock` (no API spend). `--backend codex` uses your Codex
 budget for real improvement. All the controllable knobs (`--gate on|off`,
 `--rollouts-k`, `--budget-tokens`, `--preferences`, optimizer/target split) work
 identically — see [`../../docs/sleep/CONTROLLABLE_DREAMING.md`](../../docs/sleep/CONTROLLABLE_DREAMING.md).
 ## Notes / status
 - Codex's `exec` runs shell, so the real-tool-loop replay (e.g. the
  `tool_called: search` benchmark seed) works natively.
 - Codex's standalone *plugin-package manifest* format is not yet a stable public
  spec; this integration uses the documented `AGENTS.md` + skills + prompts
  mechanisms, which are stable. If/when a `codex plugin` package format ships,
  we'll add a one-file manifest.
@@ -0,0 +1,36 @@
 #!/usr/bin/env bash
 # Install the SkillOpt-Sleep Codex integration into the user's ~/.codex and
 # ~/.agents directories. Idempotent; prints what it does.
 set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
 AGENTS_SKILLS="${HOME}/.agents/skills"
 echo "[install] repo: $REPO_ROOT"
 # 1) custom /sleep prompt
 mkdir -p "$CODEX_HOME/prompts"
 cp "$REPO_ROOT/plugins/codex/prompts/sleep.md" "$CODEX_HOME/prompts/sleep.md"
 echo "[install] /sleep prompt   -> $CODEX_HOME/prompts/sleep.md"
 # 2) user-level skill
 mkdir -p "$AGENTS_SKILLS/skillopt-sleep"
 cp "$REPO_ROOT/plugins/codex/skills/skillopt-sleep/SKILL.md" "$AGENTS_SKILLS/skillopt-sleep/SKILL.md"
 echo "[install] skill           -> $AGENTS_SKILLS/skillopt-sleep/SKILL.md"
 # 3) record the repo location so the runner is found from anywhere
 echo "[install] add to your shell profile:"
 echo "    export SKILLOPT_SLEEP_REPO=\"$REPO_ROOT\""
 # 4) optional: append an AGENTS.md hint (only if the user opts in)
 cat <<EOF
 [install] Optional — add this to ~/.codex/AGENTS.md so Codex always knows the tool:
  ## SkillOpt-Sleep
  An offline self-improvement cycle is available. To run it:
  \`bash "$REPO_ROOT/plugins/run-sleep.sh" status\`. Use \`/sleep\` for the guided flow.
 Done. Try:  /sleep status
 EOF
@@ -0,0 +1,21 @@
 # /sleep — SkillOpt-Sleep for Codex
 #
 # Custom prompt: copy this file to ~/.codex/prompts/sleep.md and invoke with
 # `/sleep` in the Codex CLI. ($ARGUMENTS is the text after /sleep.)
 Run the SkillOpt-Sleep offline self-evolution cycle. Action: $ARGUMENTS
 (empty → "status").
 Use the bundled runner via shell:
    bash "${SKILLOPT_SLEEP_REPO:?set SKILLOPT_SLEEP_REPO to the repo root}/plugins/run-sleep.sh" $ARGUMENTS --project "$(pwd)"
 Then:
 - For `run`/`dry-run`: read the staged `report.md` and show the held-out
  baseline → candidate score and the proposed edits. `run` only stages a
  proposal; nothing live changes until `adopt`.
 - For `adopt`: confirm which files were updated and that a backup was written.
 - Never edit the user's AGENTS.md / skills yourself; only `adopt` does that.
 Default backend is `mock` (no API spend). Add `--backend codex` for real
 improvement on the user's Codex budget.
@@ -0,0 +1,49 @@
 ---
 name: skillopt-sleep
 description: Nightly offline self-evolution for a Codex agent. Reviews past sessions, replays recurring tasks, and consolidates validated memory + skills behind a held-out gate. Use when the user wants Codex to learn from past usage, run a "sleep"/"dream" cycle, or schedule offline self-optimization.
 ---
 # SkillOpt-Sleep (Codex skill)
 This skill drives the `skillopt_sleep` engine — an offline "sleep cycle" that
 makes a Codex agent better at the user's recurring work without retraining.
 ## When to use
 Trigger when the user wants to: review past sessions, learn their preferences,
 consolidate feedback into long-term memory/skills, run a nightly/offline
 self-improvement cycle, or adopt a staged proposal.
 ## How to run it
 Invoke the bundled runner via shell (Codex `exec` has shell access). The runner
 finds the engine and a Python ≥ 3.10 automatically:
 ```bash
 # point at the repo if it isn't auto-detected from CWD:
 export SKILLOPT_SLEEP_REPO=/path/to/SkillOpt-Sleep
 bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" <action> --project "$(pwd)"
 ```
 `<action>` ∈ `status | dry-run | run | adopt | harvest`. Use `--backend codex`
 for real improvement on the user's own Codex budget (default `mock` = no spend).
 ## Steps
 1. Run the requested action; capture stdout.
 2. For `run`/`dry-run`: read the staged `report.md` it prints and show the user
   the held-out baseline → candidate score and the exact proposed edits.
 3. `run` only **stages** a proposal under `<project>/.skillopt-sleep/staging/`;
   nothing live changes until `adopt`. Offer `/sleep adopt`.
 4. Never hand-edit the user's `AGENTS.md` / skills yourself — only `adopt` does,
   and it backs up first.
 ## Validate
 ```bash
 python -m skillopt_sleep.experiments.run_gbrain --backend codex \
  --seeds brief-writer --data-root /path/to/gbrain-evals/eval/data/skillopt-v1 \
  --nights 2 --limit-replay 3 --limit-holdout 3
 ```
 A deficient skill goes 0.00 → 1.00 on a held-out set; the optimizer's edits are
 gated on real-task performance.
@@ -0,0 +1,67 @@
 # SkillOpt-Sleep — GitHub Copilot integration
 Give **Copilot** (CLI or VS Code) a nightly **sleep cycle** via a tiny **MCP
 server** that exposes the `skillopt_sleep` engine as tools. MCP is GitHub's
 supported way to extend Copilot, so this works across Copilot CLI, VS Code, and
 other MCP clients with the same server.
 ## What's here
 | File | Purpose |
 |---|---|
 | `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |
 | `mcp-config.example.json` | drop-in MCP server config |
 | `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |
 ## Install
 Requires Python ≥ 3.10. No third-party packages — the server is pure stdlib.
 1. **Register the MCP server.** Add the server to your Copilot MCP config
   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).
   Use `mcp-config.example.json` as a template — set `SKILLOPT_SLEEP_REPO` to
   this repo's path:
   ```json
   {
     "mcpServers": {
       "skillopt-sleep": {
         "command": "python3",
         "args": ["/abs/path/SkillOpt-Sleep/plugins/copilot/mcp_server.py"],
         "env": { "SKILLOPT_SLEEP_REPO": "/abs/path/SkillOpt-Sleep" }
       }
     }
   }
   ```
 2. **(Optional) Tell Copilot about it.** Append
   `copilot-instructions.snippet.md` to your repo's
   `.github/copilot-instructions.md` so Copilot reaches for the tools when the
   user asks to "run the sleep cycle".
 ## Use
 Ask Copilot things like *"run the sleep cycle"*, *"what did the last sleep
 propose?"*, *"adopt the staged sleep proposal"*. Copilot calls the MCP tools:
 `sleep_status`, `sleep_dry_run`, `sleep_run`, `sleep_adopt`, `sleep_harvest`.
 Each tool takes optional `project`, `backend` (`mock`/`claude`/`codex`), and
 `scope` arguments. Default backend is `mock` (no API spend).
 ## Verify the server directly (no Copilot needed)
 ```bash
 printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | SKILLOPT_SLEEP_REPO="$(pwd)" python3 plugins/copilot/mcp_server.py
 ```
 You should see the server info and the five `sleep_*` tools.
 ## Notes / status
 - MCP is the stable, official Copilot extension surface, so this is the most
  portable of the three integrations (one server → CLI + IDE).
 - The engine and all its controls (gate on/off, multi-rollout, budget,
  preferences, optimizer/target split) are identical across platforms — see
  [`../../docs/sleep/CONTROLLABLE_DREAMING.md`](../../docs/sleep/CONTROLLABLE_DREAMING.md).
@@ -0,0 +1,25 @@
 <!--
 Copy this block into your repo's .github/copilot-instructions.md so Copilot
 knows the SkillOpt-Sleep tools exist. (Copilot reads copilot-instructions.md
 automatically as ambient guidance.)
 -->
 ## SkillOpt-Sleep (offline self-evolution)
 This project has SkillOpt-Sleep available via an MCP server (`skillopt-sleep`).
 It gives the agent a nightly "sleep cycle": it reviews past sessions, replays
 recurring tasks offline, and consolidates validated memory + skills behind a
 held-out gate.
 When the user asks to "run the sleep cycle", "review my past sessions", "learn
 my preferences", or "make the agent improve from past usage", use the MCP tools:
 - `sleep_status` — what's happened + the latest staged proposal
 - `sleep_dry_run` — safe preview, stages nothing
 - `sleep_run` — full cycle, stages a reviewed proposal (nothing live changes)
 - `sleep_adopt` — apply the staged proposal (backs up first)
 - `sleep_harvest` — list mined recurring tasks
 Always show the user the held-out baseline → candidate score and the proposed
 edits before suggesting `sleep_adopt`. Never hand-edit the user's memory/skill
 files; only `sleep_adopt` does that, with a backup.
@@ -0,0 +1,11 @@
 {
  "mcpServers": {
    "skillopt-sleep": {
      "command": "python3",
      "args": ["plugins/copilot/mcp_server.py"],
      "env": {
        "SKILLOPT_SLEEP_REPO": "${workspaceFolder}"
      }
    }
  }
 }
@@ -0,0 +1,128 @@
 #!/usr/bin/env python3
 """SkillOpt-Sleep — minimal MCP server (stdio, stdlib-only).
 Exposes the sleep engine as MCP tools so any MCP-capable client (GitHub Copilot
 CLI / VS Code, Claude Desktop, etc.) can drive it. No third-party deps: speaks
 JSON-RPC 2.0 over stdio with just the handful of MCP methods clients need.
 Tools exposed:
  - sleep_status   : how many nights have run + the latest staged proposal
  - sleep_dry_run  : harvest+mine+replay, report only (no staging)
  - sleep_run      : full cycle, stages a proposal (nothing live changes)
  - sleep_adopt    : apply the latest staged proposal (with backup)
  - sleep_harvest  : debug — list mined recurring tasks
 Each tool shells out to `python -m skillopt_sleep <action> ...` and returns its
 stdout. Configure your client to launch:  python plugins/copilot/mcp_server.py
 """
 from __future__ import annotations
 import json
 import os
 import subprocess
 import sys
 REPO_ROOT = os.environ.get("SKILLOPT_SLEEP_REPO") or os.path.abspath(
    os.path.join(os.path.dirname(__file__), "..", "..")
 )
 PROTOCOL_VERSION = "2024-11-05"
 TOOLS = [
    {"name": "sleep_status", "action": "status",
     "description": "Show how many SkillOpt-Sleep nights have run and the latest staged proposal."},
    {"name": "sleep_dry_run", "action": "dry-run",
     "description": "Preview a sleep cycle (harvest+mine+replay) without staging anything."},
    {"name": "sleep_run", "action": "run",
     "description": "Run a full sleep cycle; stages a reviewed proposal. Nothing live changes until adopt."},
    {"name": "sleep_adopt", "action": "adopt",
     "description": "Apply the latest staged proposal to CLAUDE.md/SKILL.md (backs up first)."},
    {"name": "sleep_harvest", "action": "harvest",
     "description": "Debug: list the recurring tasks mined from recent sessions."},
 ]
 _BY_NAME = {t["name"]: t for t in TOOLS}
 _TOOL_SCHEMA = {
    "type": "object",
    "properties": {
        "project": {"type": "string", "description": "Project dir to evolve (default: cwd)."},
        "backend": {"type": "string", "enum": ["mock", "claude", "codex"],
                     "description": "mock = no API spend (default); claude/codex = real."},
        "scope": {"type": "string", "enum": ["invoked", "all"]},
    },
    "additionalProperties": False,
 }
 def _run_engine(action: str, args: dict) -> str:
    py = sys.executable or "python3"
    cmd = [py, "-m", "skillopt_sleep", action]
    if args.get("project"):
        cmd += ["--project", str(args["project"])]
    if args.get("backend"):
        cmd += ["--backend", str(args["backend"])]
    if args.get("scope"):
        cmd += ["--scope", str(args["scope"])]
    try:
        proc = subprocess.run(cmd, cwd=REPO_ROOT, capture_output=True, text=True, timeout=3600)
    except Exception as e:  # noqa: BLE001
        return f"[error] failed to run engine: {e}"
    out = (proc.stdout or "").strip()
    err = (proc.stderr or "").strip()
    return out + (("\n[stderr]\n" + err) if err else "")
 def _result(id_, result):
    return {"jsonrpc": "2.0", "id": id_, "result": result}
 def _error(id_, code, message):
    return {"jsonrpc": "2.0", "id": id_, "error": {"code": code, "message": message}}
 def handle(req: dict):
    method = req.get("method")
    id_ = req.get("id")
    if method == "initialize":
        return _result(id_, {
            "protocolVersion": PROTOCOL_VERSION,
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "skillopt-sleep", "version": "0.1.0"},
        })
    if method in ("notifications/initialized", "initialized"):
        return None  # notification, no response
    if method == "tools/list":
        return _result(id_, {"tools": [
            {"name": t["name"], "description": t["description"], "inputSchema": _TOOL_SCHEMA}
            for t in TOOLS
        ]})
    if method == "tools/call":
        params = req.get("params") or {}
        name = params.get("name")
        tool = _BY_NAME.get(name)
        if not tool:
            return _error(id_, -32602, f"unknown tool: {name}")
        text = _run_engine(tool["action"], params.get("arguments") or {})
        return _result(id_, {"content": [{"type": "text", "text": text}]})
    if method == "ping":
        return _result(id_, {})
    return _error(id_, -32601, f"method not found: {method}")
 def main() -> int:
    for line in sys.stdin:
        line = line.strip()
        if not line:
            continue
        try:
            req = json.loads(line)
        except Exception:
            continue
        resp = handle(req)
        if resp is not None:
            sys.stdout.write(json.dumps(resp) + "\n")
            sys.stdout.flush()
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,46 @@
 #!/usr/bin/env bash
 # SkillOpt-Sleep shared runner — used by all platform plugins (Claude Code,
 # Codex, Copilot). Resolves the repo root (which contains the skillopt_sleep
 # package), picks a Python >= 3.10, and execs the engine CLI.
 #
 # Usage: run-sleep.sh <run|dry-run|status|adopt|harvest|...> [args...]
 set -euo pipefail
 # This script lives at <repo>/plugins/run-sleep.sh, so the repo root (which
 # holds skillopt_sleep/) is one level up. CLAUDE_PLUGIN_ROOT (if set by Claude
 # Code) points at the plugin dir; the engine is then two levels above it.
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 if [ -d "$SCRIPT_DIR/../skillopt_sleep" ]; then
  REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -d "$CLAUDE_PLUGIN_ROOT/../../skillopt_sleep" ]; then
  REPO_ROOT="$(cd "$CLAUDE_PLUGIN_ROOT/../.." && pwd)"
 elif [ -n "${SKILLOPT_SLEEP_REPO:-}" ] && [ -d "$SKILLOPT_SLEEP_REPO/skillopt_sleep" ]; then
  REPO_ROOT="$SKILLOPT_SLEEP_REPO"
 else
  # last resort: search upward from CWD
  d="$PWD"
  while [ "$d" != "/" ]; do
    [ -d "$d/skillopt_sleep" ] && { REPO_ROOT="$d"; break; }
    d="$(dirname "$d")"
  done
 fi
 if [ -z "${REPO_ROOT:-}" ]; then
  echo "[sleep] ERROR: could not locate the skillopt_sleep package. Set SKILLOPT_SLEEP_REPO to the repo root." >&2
  exit 1
 fi
 PY=""
 for cand in python3.12 python3.11 python3.10 python3; do
  if command -v "$cand" >/dev/null 2>&1; then
    ver="$("$cand" -c 'import sys; print("%d%d" % sys.version_info[:2])' 2>/dev/null || echo 0)"
    if [ "${ver:-0}" -ge 310 ]; then PY="$cand"; break; fi
  fi
 done
 if [ -z "$PY" ]; then
  echo "[sleep] ERROR: need Python >= 3.10 (found none)." >&2
  exit 1
 fi
 if [ "$#" -eq 0 ]; then set -- status; fi
 cd "$REPO_ROOT"
 exec "$PY" -m skillopt_sleep "$@"
@@ -64,7 +64,9 @@ Repository = "https://github.com/microsoft/SkillOpt"
 Issues = "https://github.com/microsoft/SkillOpt/issues"
 [tool.setuptools.packages.find]
-include = ["skillopt*", "scripts*"]
+# skillopt* = the research package; skillopt_sleep = the open-source Sleep tool
 # (decoupled, zero dependency on the research code).
 include = ["skillopt", "skillopt.*", "skillopt_sleep", "skillopt_sleep.*", "scripts*"]
 [tool.ruff]
 line-length = 120
@@ -1,30 +0,0 @@
 #!/usr/bin/env bash
 # SkillOpt-Sleep runner — invokes the skillopt_sleep engine with a suitable
 # Python interpreter, from the repo that contains this plugin.
 #
 # Usage: sleep.sh <run|dry-run|status|adopt|harvest> [extra args...]
 set -euo pipefail
 # Resolve the repo root: the plugin lives at <repo>/skillopt-sleep-plugin,
 # so the engine package is at <repo>/skillopt_sleep. CLAUDE_PLUGIN_ROOT points
 # at the plugin dir when run by Claude Code; fall back to this script's dir.
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 REPO_ROOT="$(cd "$PLUGIN_ROOT/.." && pwd)"
 # Pick an interpreter that satisfies SkillOpt's 3.10+ requirement.
 PY=""
 for cand in python3.12 python3.11 python3.10 python3; do
  if command -v "$cand" >/dev/null 2>&1; then
    ver="$("$cand" -c 'import sys; print("%d%d" % sys.version_info[:2])' 2>/dev/null || echo 0)"
    if [ "${ver:-0}" -ge 310 ]; then PY="$cand"; break; fi
  fi
 done
 if [ -z "$PY" ]; then
  echo "[sleep] ERROR: need Python >= 3.10 (found none). Install one and retry." >&2
  exit 1
 fi
 if [ "$#" -eq 0 ]; then set -- status; fi
 cd "$REPO_ROOT"
 exec "$PY" -m skillopt_sleep "$@"