@oqtopus-team/pi-qdash 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@oqtopus-team/pi-qdash",
+  "version": "0.1.0",
+  "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "OQTOPUS Team <oqtopus-team@googlegroups.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oqtopus-team/pi-qdash.git"
+  },
+  "homepage": "https://github.com/oqtopus-team/pi-qdash#readme",
+  "bugs": "https://github.com/oqtopus-team/pi-qdash/issues",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "qdash"
+  ],
+  "files": [
+    "extensions",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@oqtopus-team/qdash-client": "^0.1.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/qdash.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "typebox": "^1.0.55",
+    "typescript": "^5.8.0"
+  }
+}

package/skills/qdash/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: qdash
+description: Query a running QDash instance from pi via the pi-qdash extension and @oqtopus-team/qdash-client. Use when inspecting chips, metrics, task results, tasks, projects, files, flows, executions, forum posts, provenance, or QDash profile/configuration.
+---
+
+# QDash
+
+Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
+
+## Preferred tools
+
+1. `qdash_config_info` — check profile names and non-secret connection settings.
+2. Prefer dedicated read-only tools when they match the task:
+   - `qdash_list_chips`, `qdash_get_default_chip`
+   - `qdash_get_chip_metrics`, `qdash_list_chip_qubits`, `qdash_list_chip_couplings`
+   - `qdash_list_cryostats`, `qdash_list_cooldowns`
+   - `qdash_get_cooldown_wiring`, `qdash_wiring_insights`, `qdash_list_cooldown_wiring_events`
+   - `qdash_get_timeseries`, `qdash_plot_timeseries`
+   - `qdash_list_task_results`, `qdash_get_task_result`
+   - `qdash_list_issues`
+   - `qdash_list_flows`, `qdash_get_flow`
+   - `qdash_list_executions`, `qdash_get_execution`
+   - `qdash_list_ai_reviews`, `qdash_get_provenance_stats`
+   - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies`
+   - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`
+   - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
+3. Use harness overview tools for status and triage:
+   - `qdash_investigate` for natural-language requests to investigate or compare recent calibration, target history, figures, failures, issues, and Forum context
+   - `qdash_compare_calibration` for read-only before/after comparison of repeated target calibration results
+   - `qdash_dashboard`
+   - `qdash_dashboard_insights`
+   - `qdash_recent_calibration_summary`
+   - `qdash_recommend_next_action`
+   - `qdash_triage_overview`
+4. Use agent calibration workflow tools when the user explicitly wants an agent workflow:
+   - `qdash_create_agent_session`
+   - `qdash_get_agent_session`
+   - `qdash_submit_agent_action`
+   - `qdash_get_agent_action`, `qdash_list_agent_actions`, `qdash_wait_agent_action`
+   - `qdash_list_agent_action_candidates`
+   - `qdash_execute_agent_action`
+   - `qdash_commit_agent_candidate`, `qdash_commit_agent_campaign_candidates`
+   - `qdash_get_agent_candidate_commit`, `qdash_apply_agent_candidate_commit`, `qdash_wait_agent_candidate_apply`
+5. Use `qdash_query` for common read-only QDash operations not covered by a dedicated tool:
+   - `chips`, `default_chip`, `metrics_config`, `chip_metrics`
+   - `chip_qubits`, `chip_qubit`, `chip_couplings`, `chip_coupling`
+   - `cryostats`, `cryostat`, `cooldowns`, `cooldown`, `cooldown_wiring_events`
+   - `timeseries`, `task_results`, `task_result`, `task_note`, `task_result_issues`
+   - `qubit_latest`, `qubit_history`, `coupling_latest`, `coupling_history`
+   - `tasks`, `task_knowledge`, `task_knowledge_markdown`
+   - `projects`, `project`, `files_tree`, `file_content`, `git_status`
+   - `issues`, `issue_knowledge`
+   - `flows`, `flow`, `flow_templates`, `flow_template`, `flow_helper_files`, `flow_helper_file`
+   - `executions`, `execution`, `ai_reviews`, `ai_review_runs`, `ai_review_run`
+   - `forum_posts`, `provenance_stats`, `provenance_history`, `provenance_changes`, `provenance_lineage`, `provenance_impact`
+6. `qdash_raw_get` — read-only GET endpoints not covered by `qdash_query`.
+
+## Session context
+
+Use these commands to make pi behave like a QDash-specific harness with persistent session-local context:
+
+```text
+/qdash-use-profile <profile>
+/qdash-use-chip [chip_id]
+/qdash-use-target qid <qid> | coupling <coupling_id>
+/qdash-use-agent-session <session_id>
+/qdash-context
+/qdash-dashboard [limit]
+/qdash-wiring-insights
+/qdash-refresh [limit]
+/qdash-clear-context
+```
+
+Prefer the current context when the user has already selected a profile/chip/session. Tools use that context when parameters are omitted.
+
+For cryostat wiring requests, start with `qdash_get_cooldown_wiring`. Pass `cooldownId` when the user names one; otherwise pass `cryoId`, or omit both to resolve the active/newest cooldown from the current/default chip. Prefer the compact `wiring.markdown`; request raw blocks only when structural or embedded BlockNote data is necessary, and request history when investigating wiring changes. Set `includeInsights` or call `qdash_wiring_insights` when the user asks what is characteristic, unusual, or worth checking in attenuation; summarize control/readout totals and affected qubits/MUXes instead of dumping the raw table.
+
+## Configuration
+
+The extension uses `@oqtopus-team/qdash-client` and supports:
+
+- `QDASH_*` environment variables (`QDASH_BASE_URL`, `QDASH_API_TOKEN`, `QDASH_PROJECT_ID`, etc.)
+- `$XDG_CONFIG_HOME/qdash/config.ini`
+- `~/.config/qdash/config.ini`
+- explicit `profile` / `configPath` parameters
+
+If `QDASH_BASE_URL` is set and no profile is specified, the tools default to environment variables. Otherwise they use profile `default`.
+
+## Evidence curation workflow
+
+When the user wants to preserve an investigated observation in QDash forum/notes:
+
+1. Inspect the task result, task figure, timeseries/history, and related forum context first.
+2. Summarize the observation as evidence, not as an automatic calibration decision.
+3. Prefer replying to an existing target/coupling forum thread when one exists.
+4. Use `qdash_create_forum_evidence_reply` for task-result evidence so figures are embedded as QDash UI image blocks (`/api/executions/figure?path=...`) and visible in the forum.
+5. Include task and execution QDash Web URLs in the reply.
+6. When mentioning history or trends, include links to representative historical task results.
+7. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
+8. Ask for confirmation before creating/updating the forum post.
+
+## Safety
+
+- Never print tokens, passwords, Cloudflare Access secrets, or full profile contents.
+- Treat write/operational endpoints (agent session/action creation, candidate commits, forum create/update, flow execute, git push/pull, re-execute, admin/auth APIs) as sensitive and ask the user before any write workflow.
+- Write-oriented QDash tools are approval-gated. In interactive pi, let the extension prompt for confirmation. In non-interactive runs, set `confirmWrite: true` only after explicit user confirmation.
+- Use `qdash_investigate` for natural-language requests to investigate, compare, or understand a target or recent calibration; it is read-only and combines recent results with target, Forum, issue, and recommendation context.
+- Use `qdash_compare_calibration` when the user asks what changed between recent calibration experiments; treat differences as evidence, not automatic approval to commit/apply parameters.
+- Use `qdash_recent_calibration_figure` when the user asks to see recent experiment images without a task ID.
+- Prefer summarizing large responses with counts, IDs, time ranges, and notable values.

package/skills/qdash-calibration/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: qdash-calibration
+description: Guide conservative autonomous QDash calibration workflows from pi. Use when the user asks to calibrate, tune, recover failed calibration tasks, run agent calibration sessions, or decide the next calibration action for qubits/couplings.
+license: Apache-2.0
+compatibility: pi-coding-agent >=0.74, pi-qdash extension, QDash agent-session APIs
+metadata:
+  domain: quantum-calibration
+  owner: pi-qdash
+  maturity: experimental
+  safety_level: operational-write-gated
+  default_mode: one-target-one-action
+  source_of_truth: pi-qdash skill until QDash task-knowledge operation is finalized
+  preferred_qubit_recovery_recipe: CheckRabi -> CheckChevron -> Configure -> CheckRabi
+  requires_confirmation_for:
+    - agent session creation
+    - task execution
+    - parameter commit
+    - backend apply
+  related_qdash_tasks:
+    - CheckRabi
+    - CheckChevron
+    - Configure
+    - CheckReadoutFrequency
+    - ReadoutClassification
+---
+
+# QDash Calibration Agent
+
+This skill defines how pi should behave as a conservative calibration agent. It is operational guidance for the agent; long-lived physics/task knowledge may later move to QDash task-knowledge, but until that process is settled, keep practical calibration recipes here.
+
+## Core principles
+
+- Work one target at a time: one qubit or one coupling per action/session when possible.
+- Diagnose before changing parameters.
+- Prefer read-only inspection first: dashboard, failed task results, history, figures, forum posts, and task knowledge when available.
+- Use narrow agent session policies with the smallest allowed task/action/parameter scope.
+- Do not commit or apply parameter candidates until a validation task succeeds and the user explicitly confirms.
+- Avoid blind parameter sweeps. If two conservative probes fail, step back to a diagnostic task.
+- Record useful lessons as task-knowledge cases or as updates to this skill.
+
+## Standard workflow
+
+1. Establish context:
+   - profile and chip
+   - failed task(s)
+   - qid/coupling_id
+   - recent executions and open forum/issue context
+2. Read evidence:
+   - `qdash_list_task_results`
+   - `qdash_get_task_result`
+   - `qdash_get_task_figures` when figures exist
+   - forum posts for the target when relevant
+3. Make a one-step plan.
+4. Ask for confirmation before write/operational actions.
+5. Create a scoped agent session.
+6. Run one action.
+7. Inspect the result.
+8. Continue only if the next step is clearly supported.
+
+## Qubit recovery rules
+
+### CheckRabi returns non-finite frequency, NaN, or low R²
+
+Do not repeatedly perturb `control_amplitude`, `readout_amplitude`, or `shots` without diagnosis.
+
+Canonical recovery sequence:
+
+```text
+CheckRabi -> CheckChevron -> Configure -> CheckRabi
+```
+
+Recommended sequence:
+
+1. Inspect the failed `CheckRabi` result, recent history, and figures.
+2. Run `CheckChevron` on the same qid.
+3. If `CheckChevron` completes and gives plausible `qubit_frequency` and `control_amplitude`, run `Configure` to refresh backend/box configuration with the current calibration context.
+4. Retry `CheckRabi` with the `CheckChevron` estimates as non-committing overrides.
+5. If successful, inspect candidates and only then consider committing/applying parameters with explicit user confirmation.
+6. If still failing after `Configure`, request human review and inspect raw/figure data.
+
+Known successful pattern:
+
+- Q33 on mackerel / `144Qv1`, 2026-07-14:
+  - repeated `CheckRabi` failures with `non-finite frequency: nan`
+  - `CheckChevron` succeeded and estimated:
+    - `qubit_frequency = 4.186021437949582 GHz`
+    - `control_amplitude = 0.196626929963469 a.u.`
+  - `Configure` completed
+  - `CheckRabi` then completed with the CheckChevron estimates:
+    - `rabi_frequency = 12.664970037417886 MHz`
+    - `control_amplitude = 0.19406572753680693 a.u.`
+
+### CheckChevron interpretation and suggestions
+
+If `CheckChevron` completes:
+
+- Clear vertex/fringes: use estimated `qubit_frequency` and `control_amplitude`, then run `Configure -> CheckRabi` for validation.
+- Faint fringes: suspect insufficient drive, readout fidelity, or initialization/readout contrast; suggest readout diagnostics before parameter commits.
+- No visible chevron: inspect readout path first (`CheckReadoutFrequency`, `ReadoutClassification`) or request human review.
+- Asymmetric/double chevron: suspect TLS, higher-level transitions, AC Stark shift, or frequency collision; avoid committing simple Rabi outputs without review.
+
+If `CheckChevron` fails:
+
+1. Stop the autonomous recovery path. Do not continue to `Configure -> CheckRabi` automatically.
+2. Inspect and show the figures with `qdash_get_task_figures`.
+3. Classify the failure message and input/output parameters.
+4. Suggest the next diagnostic, but require user confirmation before another operational action.
+
+Common failed-Chevron suggestions:
+
+- `Qubit frequency too low/high`, boundary hit, or fitted frequency outside normal operating range:
+  - Treat the Chevron estimate as unsafe.
+  - Do not commit/apply candidates.
+  - Do not run `Configure -> CheckRabi` from this estimate.
+  - Suggest `CheckQubitSpectroscopy`, coarse frequency search review, or human figure review.
+- Abnormally large `coarse_control_amplitude`:
+  - Suspect the coarse search latched onto a wrong transition, poor readout contrast, or an invalid operating point.
+  - Suggest spectroscopy/readout diagnostics rather than stronger drive.
+- Failed fit but visually plausible chevron:
+  - Ask the user to inspect figures.
+  - Consider adjusted scan bounds only with explicit user guidance.
+- Faint/washed-out chevron:
+  - Suggest `ReadoutClassification`, `CheckReadoutFrequency`, and initialization/readout checks.
+
+Known failed pattern:
+
+- Q35 on mackerel / `144Qv1`, 2026-07-14:
+  - repeated `CheckRabi` failures with `non-finite frequency: nan`
+  - `CheckChevron` failed with `Qubit frequency too low for qid=35: 2.759894 GHz < 3.0 GHz`
+  - input `coarse_qubit_frequency = 2.894185298591617 GHz`
+  - input `coarse_control_amplitude = 0.5623413251903492 a.u.`
+  - Suggested action: stop, inspect figures, and investigate spectroscopy/coarse frequency/readout state before any Configure/Rabi retry.
+
+### CheckT2Echo failures
+
+- Compare with recent `CheckT1` and `CheckRamsey`.
+- If `T2_echo` is much shorter than `2*T1`, suspect noise/refocusing issues.
+- Verify π/π/2 pulses before treating echo as a pure coherence problem.
+
+## Coupling / two-qubit recovery rules
+
+For `ZX90InterleavedRandomizedBenchmarking` or two-qubit validation failures, do not rerun RB first. Walk back through prerequisites:
+
+1. `CheckCrossResonance`
+2. `CreateZX90`
+3. `CheckZX90`
+4. `CheckBellState`
+5. `CheckBellStateTomography`
+6. then RB validation
+
+If CR rotation is weak, inspect qubit detuning/frequency collisions and coupling history before increasing CR amplitude.
+
+## Session policy guidelines
+
+For diagnostic-only actions:
+
+- `allowed_actions`: `run_task`, `request_human`, `complete_session`
+- `allow_reconfigure`: `false`, except sessions explicitly intended to run `Configure`
+- `max_actions`: small, typically 3–6
+
+For `CheckRabi` after `CheckChevron`, allow only the specific qid and bounded overrides:
+
+- `qubit_frequency`: narrow GHz range around the Chevron estimate
+- `control_amplitude`: conservative range around the Chevron estimate
+
+Do not include broad parameter ranges unless the user explicitly requests exploratory calibration.
+
+## Commit/apply rules
+
+- Listing candidates is read-only and encouraged after a successful task.
+- Commit/apply requires explicit user confirmation.
+- Prefer validating with the downstream check task before committing.
+- Never apply candidates from a failed authoritative task.
+
+## When to stop
+
+Stop and request human review when:
+
+- two diagnostic tasks disagree strongly
+- the same target fails after `CheckChevron` and `Configure`
+- figures suggest TLS, frequency collision, leakage, or multi-level behavior
+- the next action would require broad parameter sweeps or hardware-risky changes