@synapse-research/synapse 0.2.11 → 0.2.12

package/dist/public/synapse-plugin/skills/experiments/SKILL.md

@@ -33,10 +33,56 @@ Hand off to:
 If `synapse_get_assigned_experiments` returns empty, do not idle. Ask the user which path:
 
 1. **Execute an approved experiment** — list `pending_start` experiments in the project with `synapse_get_project_full_context` and ask which to start.
-2. **Flesh out a quick idea** — call `synapse_get_project_full_context`, then draft a plan with `synapse_create_experiment` (defaults to `pending_review`, or pass `status: "draft"` to keep refining).
+2. **Flesh out a quick idea** — call `synapse_get_project_full_context`, then draft a plan with `synapse_create_experiment` (defaults to `draft`; run a self-review sub-agent before pushing to `pending_review` per the "Create → Self-Review → Pending Review → Verbal Approve" section below).
 3. **Create the foundational experiment** — if the project has no completed experiments, offer the foundational template below.
 4. **Enter the autonomous loop** — hand off to **[autonomy](../autonomy/SKILL.md)** to propose and auto-dispatch the next experiment.
 
+## Create → Self-Review → Pending Review → Verbal Approve
+
+Every agent-created experiment goes through this sequence before reaching `pending_review`.
+
+1. `synapse_create_experiment(...)` — defaults to `draft`. The PostToolUse hook will remind you to run self-review next.
+2. Spawn a self-review sub-agent with the `Task` tool. Use a prompt similar to:
+   ```
+   Self-review experiment <experimentUuid> for project <projectUuid>.
+   Call synapse_get_experiment to read the plan. Then evaluate against the project's evaluationMethods:
+   - Is the objective specific and measurable?
+   - Is the methodology sound and reproducible?
+   - Do the success criteria align with the project's evaluation methods?
+   - Is the compute budget realistic given current availability (synapse_list_compute_nodes)?
+   Return a short verdict: "pass" or a bulleted list of concrete revisions.
+   Do NOT write back to Synapse — your verdict is consumed in-session by the main agent.
+   ```
+3. If the verdict surfaces issues, apply revisions with `synapse_update_experiment_plan({ experimentUuid, ... })`.
+4. `synapse_update_experiment_status({ experimentUuid, status: "pending_review" })` to push the draft into review.
+5. Present the self-review summary and the plan summary to the user in the terminal. Wait for a verbal answer.
+6. **On verbal approve:**
+   ```
+   synapse_review_experiment({
+     experimentUuid,
+     decision: "approved",
+     reviewNote: 'User verbally approved in terminal: "<exact words>"',
+   })
+   ```
+   That call atomically transitions to `pending_start`, writes the activity, and emits `task_assigned` so execution can begin.
+7. **On verbal reject:** summarize the user's revision request in second-person Chinese, including a quoted phrase from the user, and pass it as `reviewNote`:
+   ```
+   synapse_review_experiment({
+     experimentUuid,
+     decision: "rejected",
+     reviewNote: '用户口头要求修改：…（原话："…"）',
+   })
+   ```
+   The review tool writes the comment and emits `experiment_revision_requested` automatically — **do not** also call `synapse_add_comment`.
+8. After a reject, the experiment is back in `draft`. Revise per feedback, run self-review again, then resubmit to `pending_review`.
+9. **Full-auto mode** (set verbally via the `autonomy` skill, lives only in the current CC session): after step 4, skip steps 5–8 and immediately call `synapse_review_experiment` with the fixed full-auto template:
+   ```
+   reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.'
+   ```
+   If self-review timed out or errored: `'Self-review skipped: <reason>.'`. Full-auto **never pauses** on advisory self-review output — it only exits on user-stop or hard external errors.
+
+The `synapse_review_experiment` tool requires `admin` or `pi_agent` role. To run verbal-approve flows on Claude Code, configure the CC agent with one of those roles.
+
 ## Foundational First Experiment
 
 If the project has no completed experiments yet, the first experiment is not a normal research run — it is the project's baseline infrastructure. Drive it through three bundled deliverables before any comparison work:
@@ -51,20 +97,20 @@ If the project has a repo, commit all three onto the base branch (or a per-exper
 
 1. `synapse_checkin()` — refresh identity and assignments
 2. Author or fetch the experiment
-   - New plan: `synapse_create_experiment(...)` (defaults to `pending_review`, or `status: "draft"` to keep editing)
+   - New plan: `synapse_create_experiment(...)` (defaults to `draft`; run a self-review sub-agent and revise before pushing to `pending_review` per the section below)
    - Existing assignment: `synapse_get_assigned_experiments()` then `synapse_get_experiment({ experimentUuid })`
 3. If drafting or revising: `synapse_update_experiment_status({ status: "draft", liveStatus: "writing" })` + `synapse_update_experiment_plan(...)`, then `synapse_update_experiment_status({ status: "pending_review" })`
 4. Before execution: `synapse_list_compute_nodes({ onlyAvailable: true, researchProjectUuid })`
 5. Reserve compute: optional `synapse_reserve_gpus(...)` or inline via `synapse_start_experiment({ gpuUuids })`
 6. `synapse_start_experiment({ experimentUuid, workingNotes })` — moves to `in_progress`
 7. If remote compute: `synapse_get_node_access_bundle({ experimentUuid, nodeUuid })`, write the returned `privateKeyPemBase64` to a local PEM, `chmod 600`, SSH with the returned host/user/port
-8. If repo-backed: `synapse_get_repo_access` → clone → branch from the experiment's base branch
+8. If repo-backed: `synapse_get_repo_access` → clone → branch from the experiment's base branch (commit + push back to this repo at the end is mandatory)
 9. Run the workload in a persistent remote shell (`tmux`/`screen`) with unbuffered output (`python -u …` or `PYTHONUNBUFFERED=1`) so logs never stall a tool call
 10. Report progress with `synapse_report_experiment_progress` at milestones — `phase` ∈ `setup` | `training` | `evaluation` | `analysis`; `liveStatus` ∈ `checking_resources` | `queuing` | `running`
 11. For long runs (>30 min), schedule periodic progress updates (cron on the remote node, or the main agent polling and calling `synapse_report_experiment_progress` on a timer) so the card never looks dead
 12. Commit code/artifacts to the experiment branch or base branch; capture the commit SHA
 13. Finish with `synapse_submit_experiment_results({ outcome, experimentResults, branch, commitSha })` — `outcome` ∈ `success` | `failure` | `inconclusive`; on failure include the error and partial results
-14. If the flow asks for a dedicated report document: `synapse_save_experiment_report({ experimentUuid, title, content })` — do **not** post a full report as a comment
+14. **Always** follow `synapse_submit_experiment_results` with `synapse_save_experiment_report({ experimentUuid, title, content })` — write a full markdown writeup (objective, methodology, results, analysis, charts where relevant). Do **not** post the report as a comment, and do **not** treat this step as optional even for `failure` / `inconclusive` runs
 15. If revising per reviewer feedback, read the full thread first with `synapse_get_comments({ targetType: "experiment", targetUuid })` before editing the plan
 
 ## Core Rules
@@ -72,6 +118,8 @@ If the project has a repo, commit all three onto the base branch (or a per-exper
 - **Never assume a server-local SSH key path exists.** Always fetch the access bundle and write the PEM locally.
 - **One independent run per experiment card.** Do not bundle comparison runs, ablations, or parameter sweeps into a single experiment — create multiple cards.
 - **Match the project description's language.** If the project brief is in Chinese, write the plan, progress, and report in Chinese.
+- **If the project is repo-backed, you must commit back.** Whenever `synapse_get_repo_access` returns a configured repo, all experiment code, configs, and meaningful artifacts must be committed and pushed to that repo (on the experiment branch or merged to base), and the resulting `branch` + `commitSha` must be passed to `synapse_submit_experiment_results`. Local-only runs without a commit are not acceptable when a repo exists.
+- **Always save an experiment report after submitting results.** Every `synapse_submit_experiment_results` call must be immediately followed by `synapse_save_experiment_report({ experimentUuid, title, content })` with a full markdown writeup. This applies to `success`, `failure`, and `inconclusive` outcomes alike.
 - **Split plan / execution / report tools.** Use `synapse_update_experiment_plan` for plan edits, `synapse_report_experiment_progress` for live status, `synapse_submit_experiment_results` for completion, and `synapse_save_experiment_report` for the dedicated report. Do not substitute with comments.
 - **Revision stays durable.** When a reviewer sends an experiment back, flip to `draft`, revise, then move it back to `pending_review`; leave a reply via `synapse_add_comment` using `@[name](actorType:uuid)` format to notify the reviewer.
 - **Failures are data.** An experiment that crashes or shows a regression is still a valid submission: set `outcome: "failure"` (or `"inconclusive"`) and write up what happened in `experimentResults` and the report.

package/dist/public/synapse-plugin/skills/sessions/SKILL.md

@@ -130,7 +130,9 @@ synapse_get_assigned_experiments({
 # For any experiment still in_progress, read its latest state
 synapse_get_experiment({ experimentUuid })
 
-# Once all have completed, synthesize / propose follow-ups
+# Once all have completed, synthesize. If this is the assigned autonomous-loop
+# agent, propose follow-ups; otherwise use synapse_create_experiment for
+# user-directed terminal work.
 synapse_propose_experiment({ researchProjectUuid, title, description })
 ```
 

package/dist/public/synapse-plugin/skills/setup/SKILL.md

@@ -30,13 +30,33 @@ This skill does not cover day-to-day research or experiment execution. Hand off
 ## Recommended Flow
 
 1. Get an API key from the Synapse **Agents** page.
-2. Put Synapse MCP config at project level in `.mcp.json`.
-3. Restart Claude Code if needed.
+2. Set `SYNAPSE_URL` and `SYNAPSE_API_KEY` **in one place** (see "Where the credentials live" below).
+3. Restart Claude Code so it reloads MCP config and re-evaluates env.
 4. Call `synapse_checkin()` and confirm expected roles/tools are visible.
 
-## Project-Level MCP Template
+The plugin already ships its own `.mcp.json` (at `public/synapse-plugin/.mcp.json` inside the plugin bundle), so you do **not** need to copy a `.mcp.json` into your project. Installing the plugin makes the MCP server available; the only thing you supply is the env values.
 
-The plugin ships a project-level template at `public/synapse-plugin/.mcp.json`. The expected content is:
+## Where The Credentials Live (Important)
+
+The plugin's bundled `.mcp.json` carries `${SYNAPSE_URL}` and `${SYNAPSE_API_KEY}` placeholders. Claude Code substitutes them at MCP-server-startup time from your env. You only put the real values in **one** location:
+
+- **User-level Claude Code settings** — `~/.claude/settings.json`'s `env` block. Best for personal use across projects.
+  ```json
+  {
+    "env": {
+      "SYNAPSE_URL": "http://localhost:3000",
+      "SYNAPSE_API_KEY": "syn_..."
+    }
+  }
+  ```
+- **Project-level Claude Code settings** — `<project>/.claude/settings.json`'s `env` block. Best when several teammates share a project but each needs their own key (use `.claude/settings.local.json` for personal values; never commit the key).
+- **Shell environment** — `export SYNAPSE_URL=...; export SYNAPSE_API_KEY=...` in your shell rc, before launching Claude Code. Ad-hoc only.
+
+The plugin's bash hooks (`SessionStart`, `PostToolUse`, etc.) also read the same two env variables, so a single env source covers both the MCP server and the hook scripts.
+
+## Plugin's Own `.mcp.json` (For Reference)
+
+You don't need to edit or copy this file — the plugin ships and loads it automatically:
 
 ```json
 {
@@ -52,6 +72,20 @@ The plugin ships a project-level template at `public/synapse-plugin/.mcp.json`.
 }
 ```
 
+If you have a strong reason to override (e.g. add `X-Synapse-Project` filter headers for one project), you can add a `.mcp.json` at your project root that defines a different `synapse` server entry — Claude Code project-level config takes precedence.
+
+## Roles That Matter
+
+Set the agent's roles on the **Agents** page based on what you expect Claude Code to do:
+
+- `pre_research` — paper search, literature reading.
+- `research` — research-question CRUD.
+- `experiment` — create/start/report/submit experiments, compute tools.
+- `report` — document and synthesis tools.
+- `admin` / `pi_agent` — needed if Claude Code should call `synapse_review_experiment` to carry the user's verbal approve / reject from the terminal into Synapse. Without one of these, `/api/experiments/<uuid>/review` returns 403.
+
+If the same Claude Code agent should both execute experiments and verbally-approve them, give it both `experiment` and `admin` (or `pi_agent`).
+
 ## Verification
 
 Use:
@@ -64,6 +98,7 @@ If the connection is wrong, check:
 - the key starts with `syn_`
 - `SYNAPSE_URL` is reachable
 - Claude Code has reloaded the MCP config
+- the env variables actually reach the MCP server process (`echo $SYNAPSE_URL` from the same shell that launches Claude Code)
 - the agent has the roles needed for the tools you expect to use
 
 ## Reference

package/dist/public/synapse-plugin/skills/synapse/SKILL.md

@@ -104,7 +104,8 @@ Each stage skill repeats this onboarding prompt from its own perspective when en
 | Documents and synthesis | `synapse_get_documents`, `synapse_get_document`, `synapse_save_project_synthesis` |
 | Literature and deep research | `synapse_search_papers`, `synapse_add_related_work`, `synapse_get_related_works`, `synapse_get_deep_research_report` |
 | Research questions | `synapse_get_research_question` and research-question mutation tools when roles allow |
-| Experiments | `synapse_get_assigned_experiments`, `synapse_get_experiment`, `synapse_start_experiment`, `synapse_report_experiment_progress`, `synapse_submit_experiment_results`, `synapse_propose_experiment` |
+| Experiments | `synapse_get_assigned_experiments`, `synapse_get_experiment`, `synapse_create_experiment`, `synapse_start_experiment`, `synapse_report_experiment_progress`, `synapse_submit_experiment_results`, `synapse_propose_experiment` (autonomous loop only) |
+| PI/Admin review | `synapse_review_experiment` |
 | Compute | `synapse_list_compute_nodes`, `synapse_reserve_gpus`, `synapse_get_node_access_bundle` |
 | Collaboration | `synapse_add_comment`, `synapse_get_comments`, `synapse_search_mentionables` |
 | Task cleanup | `synapse_complete_task` except where a task-specific save/submit tool already clears state |

package/dist/public/synapse-plugin/skills/synapse/references/00-common-tools.md

@@ -61,7 +61,7 @@ Requires the `experiment` tool family.
 | `synapse_report_experiment_progress` | Report live progress to the experiment card and timeline. Supports `liveStatus` such as `queuing`, `checking_resources`, or `running`. |
 | `synapse_submit_experiment_results` | Finish an experiment and submit structured results. |
 | `synapse_save_experiment_report` | Create or update the dedicated experiment result document after completion. |
-| `synapse_propose_experiment` | Propose the next experiment during autonomous loop execution. Human-review mode creates `pending_review`; full-auto mode creates `pending_start` and auto-assigns it back to the agent. |
+| `synapse_propose_experiment` | Autonomous-loop only: propose the next experiment when the caller is the assigned loop agent. Human-review mode creates `pending_review`; full-auto mode creates `pending_start` and auto-assigns it back to the agent. Use `synapse_create_experiment` for user-directed terminal work. |
 | `synapse_list_compute_nodes` | List pools, nodes, GPUs, and access details. |
 | `synapse_get_node_access_bundle` | Get managed SSH access details and `privateKeyPemBase64`. |
 | `synapse_sync_node_inventory` | Sync node instance metadata and GPU inventory. |
@@ -70,6 +70,43 @@ Requires the `experiment` tool family.
 
 ---
 
+## PI / Admin Review
+
+Requires `admin`, `pi`, or `pi_agent`.
+
+| Tool | Description |
+|------|-------------|
+| `synapse_review_experiment` | Approve a pending experiment into `pending_start` or reject it back to `draft`. Use this for Claude Code terminal review flows. |
+
+### `reviewNote` Formatting
+
+`synapse_review_experiment` records `reviewNote` in:
+- the activity entry,
+- the recipient notification,
+- and (on reject) a comment authored by the actor.
+
+The wording matters because the actor is the agent — `reviewNote` is what makes the human voice visible in audit. Use these formats:
+
+- **Verbal approve (Claude Code terminal):**
+  ```
+  reviewNote: 'User verbally approved in terminal: "<exact words from the user>"'
+  ```
+- **Verbal reject (Claude Code terminal):** summarize the user's revision request in second-person Chinese, including a quoted phrase. Example:
+  ```
+  reviewNote: '用户口头要求修改：把 batch size 改回 32（原话："那个 batch size 改回 32 试试"）'
+  ```
+  The tool writes the comment and emits `experiment_revision_requested` automatically — **do not** also call `synapse_add_comment`.
+- **Claude Code full-auto auto-approve:**
+  ```
+  reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.'
+  ```
+  Or, if self-review failed:
+  ```
+  reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review skipped: <reason>.'
+  ```
+
+---
+
 ## Literature And Related Works
 
 Usually requires `pre_research`.

package/dist/public/synapse-plugin/skills/synapse/references/01-setup.md

@@ -28,27 +28,44 @@ If you do not have an API key yet:
 
 ## 2. MCP Server Configuration
 
-Synapse MCP uses the HTTP Streamable transport. Place this in `.mcp.json` at the project root or globally at `~/.claude/.mcp.json`.
+Synapse MCP uses the HTTP Streamable transport. **Once the Synapse plugin is installed in Claude Code, you do not need to write your own `.mcp.json`** — the plugin bundles one (at `public/synapse-plugin/.mcp.json`) and Claude Code loads it automatically.
 
-The plugin bundle also ships the same template at `public/synapse-plugin/.mcp.json` so teams can copy a project-level config into place instead of rewriting it from scratch.
-
-Replace `<BASE_URL>` with the Synapse address (for example `https://synapse.example.com` or `http://localhost:3000`).
+The bundled file uses env placeholders:
 
 ```json
 {
   "mcpServers": {
     "synapse": {
       "type": "http",
-      "url": "<BASE_URL>/api/mcp",
+      "url": "${SYNAPSE_URL}/api/mcp",
       "headers": {
-        "Authorization": "Bearer <your-api-key>"
+        "Authorization": "Bearer ${SYNAPSE_API_KEY}"
       }
     }
   }
 }
 ```
 
-Restart Claude Code after configuration so MCP picks up the new server.
+You only have to supply the env values, in **one** place. Example via `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "SYNAPSE_URL": "http://localhost:3000",
+    "SYNAPSE_API_KEY": "syn_..."
+  }
+}
+```
+
+Other equally valid sources for those env values:
+- `<project>/.claude/settings.json`'s `env` block (project scope; per-developer values can go in `.claude/settings.local.json`).
+- Shell environment (`export SYNAPSE_URL=...; export SYNAPSE_API_KEY=...`) before launching Claude Code.
+
+The plugin's bash hooks read the same two variables, so one env source covers both the MCP server and the hook scripts.
+
+If you really do need to override the bundled MCP entry (e.g. to add `X-Synapse-Project` filter headers for one project), drop a project-root `.mcp.json` with a `synapse` entry — Claude Code project-level config takes precedence.
+
+Restart Claude Code after editing env values so MCP picks them up.
 
 ### Optional: Project Filtering
 
@@ -88,9 +105,10 @@ A successful response includes your agent identity, roles, current assignments,
 
 If it fails, check:
 - Is the API key correct and does it start with `syn_`?
-- Is the URL reachable?
-- Did you restart Claude Code?
-- Does the agent have the roles needed for the tools you expect to use (`pre_research`, `research`, `experiment`, `report`, `admin`)?
+- Is the URL reachable from the machine running Claude Code?
+- Did you restart Claude Code after editing `.mcp.json` or `settings.json`?
+- Are the env variables actually visible to the MCP server process? `echo $SYNAPSE_URL` from the shell that launches Claude Code should print the value.
+- Does the agent have the roles needed for the tools you expect to use (`pre_research`, `research`, `experiment`, `report`, `admin`, `pi_agent`)? `synapse_review_experiment` requires `admin` or `pi_agent` specifically.
 
 ---
 

package/dist/public/synapse-plugin/skills/synapse/references/03-experiment-workflow.md

@@ -208,7 +208,7 @@ This is the detailed flow for moving an experiment through `in_progress` to `com
 
 9. **Monitoring — short runs** (a few minutes): skip the cron, report progress inline at setup / mid-training / evaluation / analysis transitions.
 
-10. **Commit code and artifacts** — commit configs, scripts, and meaningful artifacts to the experiment branch (or base branch) and capture the commit SHA to include in the submission.
+10. **Commit code and artifacts** — if `synapse_get_repo_access` shows the project is repo-backed, you **must** commit configs, scripts, and meaningful artifacts to the experiment branch (or base branch) **and push to the configured repo**. Capture the commit SHA so it can be passed to `synapse_submit_experiment_results` as `experimentResults.commit` (and `branch`). Local-only runs that never push back are not acceptable when a repo is configured.
 
 11. **Submit results**
 
@@ -227,7 +227,7 @@ This is the detailed flow for moving an experiment through `in_progress` to `com
 
     `outcome` is optional, typically `success`, `failure`, or `inconclusive`. Submitting moves the experiment to `completed`, refreshes the experiment result document, and triggers the project synthesis refresh.
 
-12. **Save the dedicated experiment report** — when the flow asks for a full writeup:
+12. **Save the dedicated experiment report** — every submission must be immediately followed by a markdown report. This is required for `success`, `failure`, and `inconclusive` outcomes:
 
     ```text
     synapse_save_experiment_report({
@@ -237,7 +237,7 @@ This is the detailed flow for moving an experiment through `in_progress` to `com
     })
     ```
 
-    Use python + a plotting library to generate charts and embed them in the markdown where they help. Do **not** post the report as a comment — always use `synapse_save_experiment_report` so the dedicated result document exists.
+    Use python + a plotting library to generate charts and embed them in the markdown where they help. Do **not** post the report as a comment — always use `synapse_save_experiment_report` so the dedicated result document exists. The plugin's `PostToolUse` hook on `synapse_submit_experiment_results` injects a reminder, but you should treat this step as part of the submit flow, not as something to wait for the hook to nag about.
 
 13. **Match the project description's language** — if the project brief is in Chinese, write plan, progress messages, and report in Chinese.
 
@@ -313,7 +313,7 @@ When a reviewer sends `pending_review` back to `draft`:
 8. Run workload in tmux + unbuffered python
 9. `synapse_report_experiment_progress()` at milestones
 10. `synapse_submit_experiment_results()` — success, failure, or inconclusive
-11. `synapse_save_experiment_report()` if a dedicated report is required
+11. `synapse_save_experiment_report()` — **always** runs immediately after submit, regardless of outcome
 12. `synapse_add_comment()` for durable findings and mention the reviewer
 
 For parallel multi-experiment dispatch (main agent orchestrates, sub-agents execute), see **[05-session-sub-agent.md](05-session-sub-agent.md)**.

package/dist/public/synapse-plugin/skills/synapse/references/05-session-sub-agent.md

@@ -184,7 +184,9 @@ synapse_get_assigned_experiments({
 # For any experiment still in_progress, read its latest state:
 synapse_get_experiment({ experimentUuid })
 
-# Once all have completed, synthesize and propose follow-ups:
+# Once all have completed, synthesize. If this is the assigned autonomous-loop
+# agent, propose follow-ups; otherwise use synapse_create_experiment for
+# user-directed terminal work.
 synapse_save_project_synthesis({ researchProjectUuid, title, content })
 synapse_propose_experiment({ researchProjectUuid, title, description })
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-research/synapse",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Synapse — AI Research Orchestration Platform (zero-dependency local mode)",
   "license": "AGPL-3.0",
   "bin": {