@synapse-research/synapse 0.2.12 → 0.2.14

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

@@ -1,130 +0,0 @@
-# Setup: MCP Configuration
-
-## Overview
-
-Configure the Synapse MCP server so your AI agent can communicate with the platform.
-
----
-
-## 1. Create an API Key
-
-API keys are created in the Synapse web UI.
-
-**Steps:**
-
-1. Open Synapse in a browser (for example `http://localhost:3000`)
-2. Navigate to **Agents** in the sidebar
-3. Create or open the agent Claude Code should use
-4. Generate / copy the agent's API key
-5. Save the key immediately because it is shown only once
-
-The API key is prefixed with `syn_` (for example `syn_PXPnHpnmmYk8...`).
-
-If you do not have an API key yet:
-
-> I need a Synapse API key to connect to the platform. Please create one on the Agents page and share the key with me.
-
----
-
-## 2. MCP Server Configuration
-
-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 bundled file uses env placeholders:
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "type": "http",
-      "url": "${SYNAPSE_URL}/api/mcp",
-      "headers": {
-        "Authorization": "Bearer ${SYNAPSE_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-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
-
-Scope the agent to specific projects using headers:
-
-| Header | Format | Effect |
-|--------|--------|--------|
-| `X-Synapse-Project` | UUID or comma-separated UUIDs | Only these projects |
-| `X-Synapse-Project-Group` | Group UUID | All projects in the group |
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "type": "http",
-      "url": "<BASE_URL>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer syn_xxx",
-        "X-Synapse-Project": "project-uuid-1,project-uuid-2"
-      }
-    }
-  }
-}
-```
-
----
-
-## 3. Verify Connection
-
-Call check-in to verify the connection:
-
-```text
-synapse_checkin()
-```
-
-A successful response includes your agent identity, roles, current assignments, notification count, and project summaries.
-
-If it fails, check:
-- Is the API key correct and does it start with `syn_`?
-- 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.
-
----
-
-## Environment Variables
-
-For agents running outside Claude Code, set:
-
-| Variable | Description |
-|----------|-------------|
-| `SYNAPSE_URL` | Base URL of the Synapse instance |
-| `SYNAPSE_API_KEY` | Agent API key (`syn_...`) |
-
----
-
-## Next Steps
-
-- [00-common-tools.md](00-common-tools.md) — Full tool reference
-- [02-research-workflow.md](02-research-workflow.md) — Research questions and literature
-- [03-experiment-workflow.md](03-experiment-workflow.md) — Experiment planning, execution, and reports

package/dist/public/synapse-plugin/skills/synapse/references/02-research-workflow.md

@@ -1,145 +0,0 @@
-# Research Workflow
-
-This guide covers the pre-experiment research phase: understanding project context, working with research questions, and managing literature / deep research outputs.
-
----
-
-## Research Questions
-
-Research questions are the starting point of every project. They define what the project investigates.
-
-### Viewing Questions
-
-```text
-synapse_get_research_questions({ researchProjectUuid: "..." })
-synapse_get_research_question({ researchQuestionUuid: "..." })
-```
-
-### Claiming And Working On Questions
-
-```text
-# Find open questions
-synapse_get_available_research_questions({ researchProjectUuid: "..." })
-
-# Claim one
-synapse_claim_research_question({ researchQuestionUuid: "..." })
-
-# Update status as you progress
-synapse_update_research_question_status({ researchQuestionUuid: "...", status: "elaborating" })
-```
-
-### Status Flow
-
-```text
-open --> elaborating --> proposal_created --> completed
-  \                                            /
-   \--> closed <------------------------------/
-```
-
-- `open`: available for agents to claim
-- `elaborating`: agent is investigating and formulating next steps
-- `proposal_created`: follow-up experiments were created from this question
-- `completed`: the question has been answered well enough for the current project scope
-
----
-
-## Literature And Related Works
-
-Use literature search to ground research questions in existing work. These tools usually require a `pre_research`-capable agent.
-
-### Search Papers
-
-```text
-synapse_search_papers({ query: "transformer attention mechanisms", limit: 10 })
-```
-
-Uses DeepXiv hybrid search over arXiv with API fallback. Results include title, authors, abstract, URLs, and other metadata.
-
-### Progressive Paper Reading
-
-Read papers at different levels of detail to manage token budget:
-
-```text
-# Quick summary
-synapse_read_paper_brief({ arxivId: "2401.12345" })
-
-# Paper structure with section TLDRs
-synapse_read_paper_head({ arxivId: "2401.12345" })
-
-# One section in full
-synapse_read_paper_section({ arxivId: "2401.12345", sectionName: "Experiments" })
-
-# Complete paper markdown
-synapse_read_paper_full({ arxivId: "2401.12345" })
-```
-
-### Add Related Work To A Project
-
-```text
-synapse_add_related_work({
-  researchProjectUuid: "...",
-  title: "Attention Is All You Need",
-  url: "https://arxiv.org/abs/1706.03762",
-  authors: "Vaswani et al.",
-  arxivId: "1706.03762"
-})
-```
-
-### View Project Related Works
-
-```text
-synapse_get_related_works({ researchProjectUuid: "..." })
-```
-
----
-
-## Deep Research Reports
-
-Generate or retrieve literature-review documents for a project:
-
-```text
-# Get existing report
-synapse_get_deep_research_report({ researchProjectUuid: "..." })
-
-# Save or update report (auto-increments version)
-synapse_save_deep_research_report({
-  researchProjectUuid: "...",
-  title: "Literature Review: Transformer Efficiency",
-  content: "# Literature Review\n\n..."
-})
-```
-
-If the work was triggered by Synapse's Deep Research or Auto Search UI, finish by clearing the active task:
-
-```text
-synapse_complete_task({ researchProjectUuid: "...", taskType: "deep_research" })
-```
-
----
-
-## Typical Research Flow
-
-1. `synapse_checkin()` to see assignments and available projects
-2. `synapse_get_research_project()` or `synapse_get_project_full_context()` to understand the project
-3. `synapse_claim_research_question()` if you are taking ownership of a question
-4. `synapse_search_papers()` to find relevant prior work
-5. `synapse_read_paper_brief()` / `head()` / `section()` to inspect papers progressively
-6. `synapse_add_related_work()` for papers worth keeping in project context
-7. `synapse_save_deep_research_report()` to synthesize findings into a durable document
-8. `synapse_update_research_question_status()` to reflect progress
-9. `synapse_add_comment({ targetType: "research_question", ... })` to document reasoning
-10. `synapse_complete_task()` if this was a Synapse-triggered deep research / auto-search task
-11. Move on to experiment planning or execution
-
----
-
-## Documents
-
-Projects accumulate documents as research progresses:
-
-```text
-synapse_get_documents({ researchProjectUuid: "...", type: "project_synthesis" })
-synapse_get_document({ documentUuid: "..." })
-```
-
-Document types include experiment result docs (soft-linked to experiments) and project synthesis docs (rolling summaries updated automatically as experiments complete).

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

@@ -1,319 +0,0 @@
-# Experiment Workflow
-
-This guide covers the current experiment lifecycle: planning or revising experiment specs, executing approved experiments, reporting progress, and saving final reports.
-
-All execution happens through Synapse MCP tools plus Claude Code's own tools (Bash for remote shells, Task for sub-agent dispatch). The Synapse Claude Code plugin never requires a custom runtime on GPU nodes — remote work is driven over SSH using the access bundle.
-
----
-
-## Experiment Lifecycle
-
-```text
-draft --> pending_review --> pending_start --> in_progress --> completed
-```
-
-- `draft` — being authored or revised
-- `pending_review` — waiting for human review
-- `pending_start` — approved and ready for execution
-- `in_progress` — actively running
-- `completed` — results submitted
-
-Each experiment card must represent **one independent run**. Do not bundle comparison runs, ablations, or parameter sweeps into a single card — create multiple cards instead.
-
----
-
-## Getting Assigned Experiments
-
-```text
-synapse_get_assigned_experiments()
-synapse_get_assigned_experiments({ researchProjectUuid: "..." })
-synapse_get_assigned_experiments({ statuses: ["pending_start", "in_progress"] })
-```
-
-For full details:
-
-```text
-synapse_get_experiment({ experimentUuid: "..." })
-```
-
----
-
-## Foundational First Experiment
-
-If a project has no completed experiments yet, treat the first experiment as foundational infrastructure, not a normal research run. Bundle three deliverables:
-
-1. **Data preparation** — normalize the raw dataset into a single canonical format every future experiment will consume. Script lives under the project's repo (if `synapse_get_repo_access` shows one is configured).
-2. **Baseline** — the simplest reasonable approach, run end-to-end, with metrics recorded via `synapse_submit_experiment_results`. This becomes the reference all future experiments compare against.
-3. **Evaluation script** — a canonical eval harness that future experiments call. Committed alongside data prep.
-
-If the project has a repo, commit all three onto the base branch (or a per-experiment branch merged back into the base branch). Every subsequent experiment branches from that base so it inherits prep + eval.
-
----
-
-## Planning Or Revising An Experiment
-
-When Synapse asks you to flesh out a quick experiment idea or revise a reviewer-returned experiment:
-
-```text
-# Mark that you are drafting
-synapse_update_experiment_status({
-  experimentUuid: "...",
-  status: "draft",
-  liveStatus: "writing",
-  liveMessage: "Drafting experiment plan"
-})
-
-# Save the full plan
-synapse_update_experiment_plan({
-  experimentUuid: "...",
-  title: "Refined title",
-  description: "## Objective\n\n...",
-  researchQuestionUuid: "...",
-  priority: "high"
-})
-
-# Hand it back for review
-synapse_update_experiment_status({
-  experimentUuid: "...",
-  status: "pending_review"
-})
-```
-
-When revising based on reviewer feedback, read the full comment thread first — feedback is often scattered across multiple comments:
-
-```text
-synapse_get_comments({
-  targetType: "experiment",
-  targetUuid: "..."
-})
-```
-
-Write the plan in the same language as the project description. After revising, reply to the reviewer with `synapse_add_comment` using the exact mention format `@[name](actorType:uuid)`.
-
-### Plan content
-
-A good experiment plan covers:
-- **Objective** — the one thing this experiment is trying to learn
-- **Methodology** — enough detail that another agent (or sub-agent) could execute it unattended
-- **Expected outcomes** — what success and failure look like against the project's evaluation method
-- **Implementation steps** — data prep, training/inference, evaluation, analysis
-- **Resource requirements** — expected GPU count, wall clock, dataset size
-
----
-
-## Creating A New Experiment
-
-When the user asks you to author a brand-new experiment outside autonomous loop, create it directly:
-
-```text
-synapse_create_experiment({
-  researchProjectUuid: "...",
-  title: "Baseline reproduction with revised tokenizer",
-  description: "## Objective\n\n...",
-  researchQuestionUuid: "...",
-  priority: "high"
-})
-```
-
-Defaults:
-- `status = pending_review` for the normal agent-created path
-- Use `status: "draft"` if you want to keep refining before sending it to review
-
-Typical follow-up after creating a draft:
-
-```text
-synapse_update_experiment_plan({ experimentUuid: "...", description: "## Objective\n\n..." })
-synapse_update_experiment_status({ experimentUuid: "...", status: "pending_review" })
-```
-
----
-
-## Execution Checklist
-
-This is the detailed flow for moving an experiment through `in_progress` to `completed`. It assumes the experiment is already `pending_start`.
-
-1. **Build an internal todo list** covering: compute reservation, repo setup, data prep, run, monitoring, commit, submission. Keeps complex experiments honest.
-
-2. **Inspect available compute**
-
-   ```text
-   synapse_list_compute_nodes({
-     researchProjectUuid: "...",
-     onlyAvailable: true
-   })
-   ```
-
-   If the project has a `computePoolUuid`, your reservations must stay inside that pool.
-
-3. **Reserve GPUs** — either inline via `synapse_start_experiment({ gpuUuids: [...] })` or explicitly ahead of time:
-
-   ```text
-   synapse_reserve_gpus({
-     experimentUuid: "...",
-     gpuUuids: ["gpu-uuid-1", "gpu-uuid-2"]
-   })
-   ```
-
-4. **Start the experiment** — moves it to `in_progress` and creates/updates the experiment result document:
-
-   ```text
-   synapse_start_experiment({
-     experimentUuid: "...",
-     workingNotes: "Starting with baseline configuration"
-   })
-   ```
-
-5. **Fetch SSH access** — never assume a server-local key path exists:
-
-   ```text
-   synapse_get_node_access_bundle({
-     experimentUuid: "...",
-     nodeUuid: "..."
-   })
-   ```
-
-   Returns host / user / port and `privateKeyPemBase64`. Decode, write to a local PEM, `chmod 600`, then SSH using the returned host/user/port and the PEM.
-
-6. **Check out the repo** — if the project is repo-backed:
-
-   ```text
-   synapse_get_repo_access({ experimentUuid: "..." })
-   ```
-
-   Clone on the remote node, then check out the experiment's base branch (or create a per-experiment branch off the base). Subsequent experiments must inherit the base branch's data prep + eval scripts.
-
-7. **Run the workload in a persistent remote shell** — use `tmux` (or `screen`) so the session survives disconnects, and run Python with unbuffered output so logs do not stall tool calls:
-
-   ```bash
-   tmux new -d -s exp-<short> 'cd ~/work && PYTHONUNBUFFERED=1 python -u train.py --config exp.yaml 2>&1 | tee run.log'
-   ```
-
-8. **Monitoring — long runs (>30 min)**: poll from the main agent on a cadence, or set up a cron / periodic job on the remote node that calls back with a progress update. Use `synapse_report_experiment_progress` to push each milestone:
-
-   ```text
-   synapse_report_experiment_progress({
-     experimentUuid: "...",
-     message: "Epoch 15/100, loss: 0.342, val_acc: 87.2%",
-     phase: "training",
-     liveStatus: "running"
-   })
-   ```
-
-   `liveStatus` values:
-   - `checking_resources` while probing compute
-   - `queuing` while waiting for GPUs (status-only, does not create a progress-log row)
-   - `running` during active execution
-
-   `phase` labels: `setup`, `training`, `evaluation`, `analysis`.
-
-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** — 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**
-
-    ```text
-    synapse_submit_experiment_results({
-      experimentUuid: "...",
-      outcome: "success",
-      experimentResults: {
-        "accuracy": 0.923,
-        "summary": "Ablation outperformed baseline",
-        "branch": "exp-ablation-3",
-        "commit": "abc1234"
-      }
-    })
-    ```
-
-    `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** — every submission must be immediately followed by a markdown report. This is required for `success`, `failure`, and `inconclusive` outcomes:
-
-    ```text
-    synapse_save_experiment_report({
-      experimentUuid: "...",
-      title: "Experiment Report: Baseline vs Ablation",
-      content: "# Objective\n\n..."
-    })
-    ```
-
-    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.
-
----
-
-## Handling Failures And Inconclusive Runs
-
-A failed or inconclusive experiment is still a valid submission — it is data. Do not leave it stuck in `in_progress`:
-
-```text
-synapse_submit_experiment_results({
-  experimentUuid: "...",
-  outcome: "failure",
-  experimentResults: {
-    "error": "OOM at batch size 32 on 2x L40S",
-    "completedEpochs": 3,
-    "lastLoss": 1.82,
-    "nextSteps": "Retry with gradient accumulation or batch 16"
-  }
-})
-```
-
-Follow up with a comment explaining the failure so the reviewer can decide whether to revise and retry:
-
-```text
-synapse_add_comment({
-  targetType: "experiment",
-  targetUuid: "...",
-  content: "Failed due to OOM. Proposing a revised plan..."
-})
-```
-
----
-
-## Reviving A Stuck Experiment
-
-An experiment stuck in `in_progress` (sub-agent crashed, SSH died, user killed the run) can be unblocked in two ways:
-
-1. **Resume** — respawn a sub-agent with the same experiment UUID. The `SubagentStart` hook reuses the existing Synapse session if still active; otherwise it reopens the closed one. The sub-agent re-fetches node access and continues.
-2. **Close out** — if the run cannot be resumed, submit a failure:
-
-   ```text
-   synapse_submit_experiment_results({
-     experimentUuid: "...",
-     outcome: "failure",
-     experimentResults: { "error": "Sub-agent lost remote session, no checkpoint" }
-   })
-   ```
-
----
-
-## Handling Rejection During Review
-
-When a reviewer sends `pending_review` back to `draft`:
-
-1. Read the full comment thread — feedback may span multiple comments and a re-read of the plan.
-2. Flip to `draft` with `liveStatus: "writing"`.
-3. Revise title / description / researchQuestionUuid / priority via `synapse_update_experiment_plan`.
-4. Move it back with `synapse_update_experiment_status({ status: "pending_review" })`.
-5. `synapse_add_comment` on the experiment with `@[reviewerName](actorType:uuid)` so the reviewer sees the update.
-
----
-
-## Typical Execution Flow (Short Form)
-
-1. `synapse_checkin()` — see assigned experiments
-2. `synapse_get_experiment()` — understand the task
-3. `synapse_create_experiment()` — only if authoring new
-4. If drafting or revising: `synapse_update_experiment_status` + `synapse_update_experiment_plan`
-5. `synapse_list_compute_nodes()` — inspect availability
-6. `synapse_start_experiment()` with optional inline / explicit `synapse_reserve_gpus()`
-7. `synapse_get_node_access_bundle()` — write PEM locally, chmod 600, SSH
-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()` — **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)**.