Skip to content

feat: OpenClaw integration v0 design + schemas + SOUL.md#811

Closed
garrytan wants to merge 20 commits into
mainfrom
garrytan/openclaw-plan
Closed

feat: OpenClaw integration v0 design + schemas + SOUL.md#811
garrytan wants to merge 20 commits into
mainfrom
garrytan/openclaw-plan

Conversation

@garrytan

@garrytan garrytan commented Apr 5, 2026

Copy link
Copy Markdown
Owner

Summary

Full OpenClaw integration: design doc + implementation of all three phases.
"Two runtimes, one brain" — OpenClaw (Wintermute) is the always-on orchestrator,
gstack (Claude Code) is the deep-work coding engine. Shared memory, dispatch
protocol, Clawvisor security gateway.

Phase 1 (already done via multi-host infra):

  • Generator-native OpenClaw skill output via hosts/openclaw.ts + adapter
  • SOUL.md builder identity for OpenClaw agents
  • JSON Schema contracts for all shared file formats
  • COMPATIBILITY.md with schema evolution rules
  • OpenClaw host config: triggers, min_openclaw_version

Phase 2 (shared layer):

  • Bidirectional learnings bridge (gstack JSONL <-> OpenClaw markdown memory)
  • Weekly activity index (~/.gstack/activity/activity-YYYY-WNN.jsonl)
  • Checkpoint handoff with resume_prompt for zero-context-reconstruction
  • Shared routing config reader (gstack-routing-config)

Phase 3 (remote dispatch):

  • gstack-dispatch-daemon — Bun process that accepts dispatch files, validates
    schemas, spawns Claude Code with scoped permissions, enforces TTL, manages
    concurrency, smart retry (rate_limit/tool_failure get 1 retry), audit logging
  • gstack-dispatch-install — launchd/systemd service installer
  • gstack-bridge skill — teaches OpenClaw agents the full dispatch protocol

Pre-Landing Review

No application code paths changed that affect existing functionality. New code
(daemon, bridge skill, learnings bridge) is additive. Pre-Landing Review: No issues found.

Test Coverage

All 71+ host-config tests pass. Golden fixtures regenerated. No existing tests
broken by these additions. New code is infrastructure (daemon, shell scripts) that
requires E2E testing with a live Claude Code session — test specs defined in the
eng review plan.

Test plan

  • bun test passes (all tests, 0 failures)
  • Golden file regression tests pass
  • Skill freshness checks pass

🤖 Generated with Claude Code

garrytan and others added 11 commits April 4, 2026 16:08
Architecture for gstack + OpenClaw (Wintermute) as complementary runtimes
with shared memory, dispatch protocol, and Clawvisor security gateway.

Key components: generator-native OpenClaw skill output, bidirectional
learnings store, dispatch daemon, session handoff with resume_prompt,
symmetric Clawvisor callback path, JSON Schema contracts for all shared
file formats, weekly activity index rotation, and gstack-bridge skill
for OpenClaw instances.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Persistent agent personality file for gstack on OpenClaw. Captures the
builder ethos: completeness, search-before-building, direct voice, and
structured dispatch reporting.

hosts/openclaw.ts already references this via staticFiles config.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
From CEO + eng review findings:
1. bypassPermissions -> acceptEdits (security critical)
2. Add source_signature HMAC field to dispatch schema
3. Full daemon architecture (process model, file watcher, output parsing)
4. Dispatch audit log specification
5. launchd/systemd daemon lifecycle
6. resume_prompt maxLength: 4096
7. Standardize callback_url (URI, not file path)
8. Effort estimates: 7h -> 12-18h (daemon alone is 4-8h)
9. Clawvisor fallback/local-only mode
10. Token storage: keychain/0600 file, not plaintext config

Also adds target_agent field (universal dispatch, accepted expansion)
and smart retry error taxonomy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds min_openclaw_version (1.8.0) and voice-triggers->triggers rename
to OpenClaw host config. Syncs version to 0.15.6.0.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Golden files drifted from multi-host merge + DX review skill addition.
Regenerated from current gen-skill-docs output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…e contracts

Four schemas for the OpenClaw dispatch protocol:
- dispatch.schema.json (task dispatch with target_agent, source_signature)
- completion.schema.json (session completion report with retry_count)
- handoff.schema.json (cross-runtime context transfer with resume_prompt)
- activity-entry.schema.json (weekly activity index entries)

COMPATIBILITY.md defines breaking vs non-breaking changes so future
contributors don't guess under pressure.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions

github-actions Bot commented Apr 5, 2026

Copy link
Copy Markdown

E2E Evals: ✅ PASS

2/2 tests passed | $.06 total cost | 12 parallel runners

Suite Result Status Cost
e2e-browse 1/1 $0.03
e2e-browse 1/1 $0.03

12x ubicloud-standard-2 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite

garrytan and others added 9 commits April 4, 2026 22:10
…files

When ~/.openclaw/ exists, gstack-learnings-log writes a parallel markdown
copy to ~/.openclaw/workspace/memory/gstack-{slug}.md. OpenClaw agents
can read these directly as memory entries.

gstack-learnings-search reads back from OpenClaw memory files (*.md in
~/.openclaw/workspace/memory/) and includes them in unified search
results alongside native JSONL learnings. Cross-pollination.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Timeline-log now writes completed events to weekly rollup files at
~/.gstack/activity/activity-YYYY-WNN.jsonl. Wintermute answering
"what did I ship this week" reads one file, not 6 months of history.

Only completed events go to the activity index (not started events).
Old weeks are immutable. ls ~/.gstack/activity/ gives the full timeline.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New bin/gstack-routing-config with check and read commands. Reads from
~/.gstack/routing.yaml (shared config) or falls back to ## Skill routing
section in CLAUDE.md/AGENTS.md. Both runtimes use the same routing table.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… transfer

/checkpoint now writes a handoff file to ~/.gstack/handoff/ alongside the
checkpoint. Includes resume_prompt field — the exact prompt to resume the
session in a fresh Claude Code instance. Wintermute reads this and passes
it straight into the next session. Zero context reconstruction.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bun process that watches ~/.gstack/dispatch/ for dispatch files, validates
against schema, spawns Claude Code with acceptEdits permissions, enforces
TTL, manages concurrency (default 2), and reports completion via Clawvisor
callback or local disk.

Smart retry: rate_limit and tool_failure get one retry. context_overflow
strips learnings and retries. logic_error escalates immediately.

Includes heartbeat file, audit log, orphan detection, graceful shutdown,
and queue management with FIFO ordering.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
macOS: creates ~/Library/LaunchAgents/ plist with KeepAlive.
Linux: creates ~/.config/systemd/user/ service with Restart=always.
Supports --uninstall to remove the service cleanly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
SKILL.md for OpenClaw agents that covers the full integration: dispatch
file creation, completion report parsing, handoff reading with
resume_prompt, activity timeline queries, learnings sync, and daemon
management. Ships to ClawHub alongside other gstack skills.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Main landed Security Wave 1 at v0.15.7.0. Our OpenClaw integration
moves to v0.15.8.0. Both entries preserved in CHANGELOG.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@garrytan

garrytan commented Apr 5, 2026

Copy link
Copy Markdown
Owner Author

I accidentally over-engineered this and will not be landing this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant