forked from molecule-ai/molecule-core
Hongming Wang
aab93de291
Addresses items 4, 5, 7 from the self-review of the batch merge. PR A (#228) covered items 1, 2, 3, 6 on the Go side. ## workspace-template/main.py — idle loop hardening - Replace asyncio.get_event_loop() with asyncio.get_running_loop() — the former is deprecated in 3.12+ and emits a DeprecationWarning on every idle fire. - Replace hardcoded urlopen timeout=600 with IDLE_FIRE_TIMEOUT_SECONDS clamped to max(60, min(300, idle_interval_seconds)). Long cadence workspaces no longer hold dangling requests open for 10 minutes; the cap adapts automatically when the interval is short. - Type the exception handling: split HTTPError (has .code) from URLError (connection-level) from the generic catch-all. Log status + error class separately so operators can grep for specific failure modes instead of a bare "post failed". - Fire-and-forget no longer loses exceptions. run_in_executor Future now has an add_done_callback that logs the outcome, so a panic in _post_sync surfaces as "Idle loop: post failed — status=None err=..." instead of Python's default "Task exception was never retrieved" warning burried in stderr. ## org-templates/molecule-dev/org.yaml — discoverability Added idle_prompt + idle_interval_seconds to the defaults: block with explanatory comments. Without this, users had to read main.py to discover the feature. ## docs/runbooks/admin-auth.md — new Documents the three middleware variants (AdminAuth strict, CanvasOrBearer soft, WorkspaceAuth per-id), the exact contract of each, and the three-question test for adding a new route to CanvasOrBearer. Also flags the session-cookie follow-up as Phase H. Referenced PRs: #138, #164, #165, #166, #167, #168, #190, #194, #203, #228. No code deltas in platform/ beyond the Python + YAML + docs changes. Full pytest suite unchanged except the pre-existing test_hermes_smoke flake that fails in full-suite but passes in isolation (test isolation bug, not introduced by this PR). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
docs/
This directory serves two purposes:
- Markdown content — everything under
architecture/,agent-runtime/,api-protocol/,development/,frontend/,plugins/,product/, etc. This is what agents and humans read. - VitePress site —
.vitepress/config.ts,package.json,package-lock.json. These drive the rendered documentation site.
Local preview
cd docs
npm install
npm run dev # preview on http://localhost:5173
npm run build # static build to docs/.vitepress/dist/
Conventions
- New top-level docs must be linked from
PLAN.md,README.md, andCLAUDE.md— otherwise agents can't find them (see.claude/memoryfeedback_cross_reference_docs.md). edit-history/YYYY-MM-DD.mdis append-only log of significant changes; don't rewrite history.archive/holds one-shot analyses and retired docs — kept for context but not maintained.
Why site tooling lives here (not in docs-site/)
VitePress expects its config at <root>/.vitepress/config.ts where <root> is also the content directory. Splitting tooling into a sibling docs-site/ would require a non-trivial srcDir shim and break relative links in .vitepress/config.ts. Keeping both together is the pragmatic choice; this README is the tradeoff ledger.