forked from molecule-ai/molecule-core
499fed5080
PR #2265 renamed the harness trace endpoint and event name; sync the cross-repo scripts/README.md to match. Closes #2270 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
50 lines
2.9 KiB
Markdown
50 lines
2.9 KiB
Markdown
# scripts/
|
|
|
|
Operational and one-off scripts for molecule-core. Most are
|
|
self-documenting — see the header comments in each file.
|
|
|
|
## RFC #2251 coordinator task-bound harnesses
|
|
|
|
There are three related scripts; pick the right one:
|
|
|
|
| Script | Purpose | Targets |
|
|
|---|---|---|
|
|
| `measure-coordinator-task-bounds.sh` | **Canonical** v1 harness for the RFC #2251 / Issue 4 reproduction. Provisions a PM coordinator + Researcher child via `claude-code-default` + `langgraph` templates, sends a synthesis-heavy A2A kickoff, observes elapsed time + activity trace. | OSS-shape platform — localhost or any `/workspaces`-shaped endpoint. Has tenant/admin-token guards for non-localhost runs. |
|
|
| `measure-coordinator-task-bounds-runner.sh` | Generalised runner for the same measurement contract but with **arbitrary template + secret + model combinations** (Hermes/MiniMax, etc.). Useful for cross-runtime variants without modifying the canonical harness. | Same as above (local or SaaS via `MODE=saas`). |
|
|
| `measure-coordinator-task-bounds.sh` (in [molecule-controlplane](https://github.com/Molecule-AI/molecule-controlplane)) | **Production-shape** variant that bootstraps a real staging tenant via `POST /cp/admin/orgs`, then runs the same measurement against `<slug>.staging.moleculesai.app`. | Staging controlplane only — refuses to run against production. |
|
|
|
|
See `reference_harness_pair_pattern` (auto-memory) for when to use which
|
|
and the cross-repo design rationale.
|
|
|
|
### Common safety pattern across all three
|
|
|
|
- **Cleanup trap** on EXIT/INT/TERM auto-deletes provisioned resources.
|
|
- **`DRY_RUN=1`** prints plan + auth fingerprint, exits before any
|
|
state mutation. Run this before pointing at staging or any shared
|
|
infrastructure.
|
|
- **Non-target guard** refuses arbitrary endpoints (the controlplane
|
|
variant is locked to `staging-api.moleculesai.app`; the OSS variant
|
|
requires explicit auth + tenant scoping for non-localhost PLATFORM).
|
|
- **Cleanup failures emit `cleanup_*_failed` events** with remediation
|
|
hints; no silenced curl. ADMIN_TOKEN expiring mid-run surfaces as a
|
|
structured event rather than a silent leak.
|
|
|
|
### Activity trace caveat
|
|
|
|
If `activity_trace.raw == "<endpoint_unavailable>"`, the per-workspace
|
|
`/activity` endpoint isn't wired on the target build — the bound
|
|
measurement is INCONCLUSIVE on the platform-ceiling question. Either
|
|
wire the endpoint or replace with the equivalent Datadog query. Note
|
|
that `/activity` accepts a `since_secs` query parameter; see the
|
|
endpoint handler for the supported range.
|
|
|
|
## Other scripts
|
|
|
|
- `cleanup-rogue-workspaces.sh` — emergency teardown for leaked
|
|
workspaces. Prompts for confirmation. Pair with the harnesses if a
|
|
cleanup trap fails (see `cleanup_*_failed` events).
|
|
- `canary-smoke.sh` — quick smoke test for canary releases.
|
|
- `dev-start.sh` — local-dev platform bring-up.
|
|
|
|
The rest are self-documenting in their header comments.
|