molecule-ai/molecule-core
34
0
Fork 2
Code Issues 16 Pull Requests 2 Actions 49 Packages Projects Releases Wiki Activity
01deeb36cf
molecule-core/scripts
History
Hongming Wang 01deeb36cf fix(onboarding): address Claude Code MCP onboarding friction (#2934) 
Ryan's bug report (#2934) walked through ~45 min of debugging a stock
external-runtime install. This PR fixes the four items he flagged that
have a small surface, and stubs out the larger ones for follow-up.

Fixed in this PR
================

#1 — Python floor disclosure (README in publish bundle)
  Add an explicit "Requires Python ≥3.11" section that calls out the
  cryptic "Could not find a version that satisfies the requirement"
  failure mode; recommend `pipx install` over `pip install` so the
  binary lands on PATH automatically; show the explicit `pip install
  --user` alternative with the PATH caveat.

#3 — MOLECULE_WORKSPACE_TOKEN_FILE support (mcp_workspace_resolver.py)
  Add a third resolution step between the inline env var and the
  in-container CONFIGS_DIR fallback. Operators can write the bearer to
  a 0600 file (e.g. ~/.config/molecule/token) and point
  MOLECULE_WORKSPACE_TOKEN_FILE at it, keeping the secret out of
  ~/.zsh_history and out of plaintext in MCP-host configs like
  ~/.claude.json. Inline TOKEN still wins on conflict so rotation flows
  are predictable. README documents the safer option as the
  recommended path. 6 new tests pin every leg (file resolves, inline
  wins, missing/empty file falls through, blank env unset-equivalent,
  help text advertises it).

#4 — Push delivery 3-condition gating (README in publish bundle)
  Document that real-time push on Claude Code requires (a) the server
  to declare experimental.claude/channel (we do), (b) the server to be
  marketplace-plugin-sourced (operators must scaffold their own until
  the official marketplace lands — see #2934 follow-up), and (c) the
  --dangerously-load-development-channels flag on the claude
  invocation. Until any of the three is in place, delivery silently
  falls back to poll mode with no diagnostic. The README now says all
  of this explicitly so a new operator doesn't grep the binary for
  channel_enable to figure it out.

#8 — serverInfo.name mismatch (a2a_mcp_server.py)
  The server reported `serverInfo.name = "a2a-delegation"` while
  operators register it as `molecule` (the name in `claude mcp add
  molecule …`). Harmless on tool routing today but matters for any
  future Claude Code allowlist that gates push by hardcoded server
  name. Renamed to "molecule" with an inline comment explaining the
  invariant.

Deferred (separate issues to track)
===================================

#2 — covered transitively by #1's pipx recommendation; no separate fix.
#5 — `moleculesai/claude-code-plugin` marketplace repo (substantial new
     repo work; the README references it as a documented follow-up).
#6 — `molecule-mcp doctor` subcommand (substantial new CLI surface;
     mentioned in the README's push-vs-poll section as the planned
     diagnostic for silent push fallback).
#7 — `--dangerously-load-development-channels` rename — not in our
     control; that's Claude Code's flag.

Tests
=====
164/164 mcp_cli + a2a_mcp_server tests pass locally
(WORKSPACE_ID=00000000-0000-0000-0000-000000000001 pytest …) including
6 new TestTokenFileEnv cases. Wheel builds successfully via
scripts/build_runtime_package.py with the new README markers verified
in the output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 14:19:09 -07:00
..
demo-freeze-snapshots ops: demo-day freeze + rollback runbook 2026-05-01 12:04:30 -07:00
ops feat(ops): add sweep-aws-secrets janitor — orphan tenant bootstrap secrets 2026-05-03 02:38:08 -07:00
build_runtime_package.py fix(onboarding): address Claude Code MCP onboarding friction (#2934) 2026-05-05 14:19:09 -07:00
build-images.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
bundle-compile.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
canary-smoke.sh feat(canary): smoke harness + GHA verification workflow (Phase 2) 2026-04-19 03:30:19 -07:00
check-cascade-list-vs-manifest.sh feat(ci): structural drift gate for cascade list vs manifest (RFC #388 PR-3) 2026-05-03 03:52:39 -07:00
cleanup-rogue-workspaces.sh fix(provisioner): stop rogue config-missing restart loop (#17) 2026-04-14 07:32:58 -07:00
clone-manifest.sh fix(quickstart): wire up template/plugin registry via manifest.json 2026-04-23 14:55:34 -07:00
demo-day-runbook.md ops: demo-day freeze + rollback runbook 2026-05-01 12:04:30 -07:00
demo-freeze.sh ops: demo-day freeze + rollback runbook 2026-05-01 12:04:30 -07:00
demo-thaw.sh ops: demo-day freeze + rollback runbook 2026-05-01 12:04:30 -07:00
dev-start.sh fix(dev-start): detect missing Go and fall back to docker-compose platform 2026-04-29 20:04:37 -07:00
import-agent.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
lockdown-tenant-sg.sh feat(security): Phase 35.1 — SG lockdown script for tenant EC2 instances 2026-04-18 12:01:41 -07:00
measure-coordinator-task-bounds-runner.sh fix(harness-runner): switch from non-existent /heartbeat-history to /activity 2026-04-28 23:12:51 -07:00
measure-coordinator-task-bounds.sh docs: registry pattern + harness scripts READMEs 2026-04-28 22:19:40 -07:00
nuke-and-rebuild.sh fix(scripts): nuke-and-rebuild self-bootstraps templates; add E2E test 2026-04-26 14:37:04 -07:00
post-rebuild-setup.sh security: remove hardcoded API keys from post-rebuild-setup.sh 2026-04-20 13:02:52 -07:00
README.md docs(scripts): rename /heartbeat-history → /activity in README 2026-04-29 02:23:00 -07:00
refresh-workspace-images.sh feat(platform/admin): /admin/workspace-images/refresh + Docker SDK + GHCR auth 2026-04-26 10:17:21 -07:00
rollback-latest.sh fix(scripts): correct platform dir path + add ROOT isolation (shellcheck clean) 2026-04-22 15:42:24 +00:00
test_build_runtime_package.py chore: rewriter unit tests + drop misleading noqa on import inbox 2026-04-30 20:45:32 -07:00
test-a2a-cross-runtime.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
test-all-adapters.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
test-all-runtimes-a2a-e2e.sh test(e2e): wire SaaS auth headers (TENANT_ADMIN_TOKEN + TENANT_ORG_ID) 2026-05-02 04:36:23 -07:00
test-all.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
test-cross-agent-chat.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
test-hermes-plugin-e2e.sh test(e2e): unified A2A round-trip parity harness across all 4 runtimes 2026-05-02 04:36:23 -07:00
test-nuke-and-rebuild.sh fix(scripts): nuke-and-rebuild self-bootstraps templates; add E2E test 2026-04-26 14:37:04 -07:00
test-team-e2e.sh initial commit — Molecule AI platform 2026-04-13 11:55:37 -07:00
wheel_smoke.py feat(mcp): notifications/claude/channel for push-feel inbox UX 2026-04-30 20:10:01 -07:00

README.md

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) 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.