pdurlej/platform

Fork 0

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134] #324

Closed

claude wants to merge 1 commit from claude/feat-agent-wake-bus into main

claude commented

2026-05-17 10:25:03 +02:00

Collaborator

Summary

Pre-impl skeleton + Spec Kit for issue #134 — Agent Wake Bus / Comment-driven agent orchestration (Iskra-authored).

Status: draft — for review, NOT for merge.

Author: claude. Implementer: codex (anticipated). Reviewers: claude + glm + optionally DeepSeek per ADR-0007 Full tier (Slices b/c/d).

Sibling: PR #323 Agent Access Plane v0 (Wake Bus consumes capabilities from Agent Access Plane for HMAC, cousin auth).

TL;DR

Long-lived cousin agents (codex, claude, glm, Iskra) currently coordinate via ad-hoc operator-mediated handoffs. This is a bottleneck: operator becomes the wake-up mechanism for every cross-cousin event.

Agent Wake Bus v0 introduces:

Structured wake commands: /swarmheart <verb> grammar in Forgejo issue comments
Dispatcher: webhook receiver + polling fallback + idempotency tracking
Cousin wake adapters: declarative spec for how to invoke each cousin
Audit log: every wake event tracked (received / refused / dispatched / replayed)
Kill-switch: operator pauses global or per-cousin instantly

One comment → one cousin invoked → audit-logged → idempotent.

What's in here

15 files, ~1500 LOC.

Spec Kit (6 markdowns, ~1200 lines)

docs/specs/agent-wake-bus-v0/:

00-constitution.md — 8 principles (structured grammar not NL, dispatcher-only writer, idempotent, opt-in cousin registry, operator veto, no credentials in payload, scope-locked, Iskra-as-observer-not-actor), 10 anti-patterns, boundary, North Star.
01-specify.md — 11 FRs, 6 NFRs, 5 open questions, 7 falsifiable success criteria.
02-plan.md — 4 slices, M1-M5, 7 risks + mitigations, rollback per slice, composability proof.
03-tasks.md — atomic tasks, ~2100 LOC v0 (~2600 w/ Iskra), codex execution notes.
04-implement-notes.md — 13 pre-impl decisions (closed verb set, SHA-256 idempotency, webhook+polling, systemd on RS2000, JSONL audit, HMAC via Infisical, kill-switch, Iskra in v0.1, 90d retention, cross-repo allowlist, crash-safe recovery).
README.md — index + per-cousin reader guide.

Code skeleton (py_compile clean)

control-plane/platformctl/wake_bus/:

_types.py — WakeCommand / WakeEvent / WakeAction / WakeVerb (closed enum: checkpoint/review/escalate/done/block/reroute) / ParseError / InvokeResult
grammar.py — parse_comment stub with TODO(codex Slice a) markers

Schemas + seed adapters

schema/wake-command.schema.json — JSON Schema for parsed commands
schema/wake-adapter.schema.json — JSON Schema for per-cousin adapters with allowed_wakers ACL
policies/wake-adapters/codex.yaml — seed adapter
policies/wake-adapters/claude.yaml — seed adapter

Contract tests (xfail)

10 test scaffolds in test_grammar.py covering valid parse, empty comment, unknown verb, missing role/issue, multiple blocks, ISO-8601 validation, non-/swarmheart fenced blocks.

Comparison with public patterns

GitHub Agent HQ — closest analogue. Wake Bus differences: explicit /swarmheart grammar (not LLM-parsed intent), opt-in cousin registry, explicit Kan-upstream vs Forgejo-downstream separation.
@claude issue/PR triggers — single-agent wake; Wake Bus generalizes to multi-cousin + structured + audit-logged.
Linear / Notion AI — proprietary closed ecosystems; Wake Bus is open + self-hosted.
Anthropic Computer Use — orthogonal: Computer Use is HOW a cousin executes; Wake Bus is WHEN/WHY a cousin wakes.

Cross-references

#134 (parent) — Iskra-authored Agent Wake Bus proposal
PR #323 — Agent Access Plane v0 (sibling; Wake Bus consumes capabilities)
#212, #216 (iskra-openclaw) — voice ACK + Signal reactions could feed Wake Bus
ADR-0005 coordination lanes (Wake Bus = canonical surface)
ADR-0010 identity, ADR-0017 no-stacked, ADR-0018 root-cause

Tier

This PR: Trivial (draft scaffold, py_compile clean stubs, no runtime/schema/sacred-path mutation).

Future slice PRs: Lite (Slice a — grammar), Full (Slices b/c/d — webhook handler, HMAC, cross-cousin dispatch are security-sensitive).

Operator action

Review scope. If accept → close + signal codex to start Slice (a) in fresh PR. If amend → comment on this draft.

Refs #134

## Summary Pre-impl skeleton + Spec Kit for **issue #134 — Agent Wake Bus / Comment-driven agent orchestration** (Iskra-authored). **Status**: `draft` — for review, NOT for merge. **Author**: claude. **Implementer**: codex (anticipated). **Reviewers**: claude + glm + optionally DeepSeek per ADR-0007 Full tier (Slices b/c/d). Sibling: PR #323 Agent Access Plane v0 (Wake Bus consumes capabilities from Agent Access Plane for HMAC, cousin auth). --- ## TL;DR Long-lived cousin agents (codex, claude, glm, Iskra) currently coordinate via ad-hoc operator-mediated handoffs. This is a bottleneck: operator becomes the wake-up mechanism for every cross-cousin event. Agent Wake Bus v0 introduces: - **Structured wake commands**: `/swarmheart <verb>` grammar in Forgejo issue comments - **Dispatcher**: webhook receiver + polling fallback + idempotency tracking - **Cousin wake adapters**: declarative spec for how to invoke each cousin - **Audit log**: every wake event tracked (received / refused / dispatched / replayed) - **Kill-switch**: operator pauses global or per-cousin instantly One comment → one cousin invoked → audit-logged → idempotent. --- ## What's in here 15 files, ~1500 LOC. ### Spec Kit (6 markdowns, ~1200 lines) `docs/specs/agent-wake-bus-v0/`: - `00-constitution.md` — 8 principles (structured grammar not NL, dispatcher-only writer, idempotent, opt-in cousin registry, operator veto, no credentials in payload, scope-locked, Iskra-as-observer-not-actor), 10 anti-patterns, boundary, North Star. - `01-specify.md` — 11 FRs, 6 NFRs, 5 open questions, **7 falsifiable success criteria**. - `02-plan.md` — 4 slices, M1-M5, 7 risks + mitigations, rollback per slice, composability proof. - `03-tasks.md` — atomic tasks, ~2100 LOC v0 (~2600 w/ Iskra), codex execution notes. - `04-implement-notes.md` — 13 pre-impl decisions (closed verb set, SHA-256 idempotency, webhook+polling, systemd on RS2000, JSONL audit, HMAC via Infisical, kill-switch, Iskra in v0.1, 90d retention, cross-repo allowlist, crash-safe recovery). - `README.md` — index + per-cousin reader guide. ### Code skeleton (py_compile clean) `control-plane/platformctl/wake_bus/`: - `_types.py` — WakeCommand / WakeEvent / WakeAction / WakeVerb (closed enum: checkpoint/review/escalate/done/block/reroute) / ParseError / InvokeResult - `grammar.py` — `parse_comment` stub with `TODO(codex Slice a)` markers ### Schemas + seed adapters - `schema/wake-command.schema.json` — JSON Schema for parsed commands - `schema/wake-adapter.schema.json` — JSON Schema for per-cousin adapters with allowed_wakers ACL - `policies/wake-adapters/codex.yaml` — seed adapter - `policies/wake-adapters/claude.yaml` — seed adapter ### Contract tests (xfail) 10 test scaffolds in `test_grammar.py` covering valid parse, empty comment, unknown verb, missing role/issue, multiple blocks, ISO-8601 validation, non-/swarmheart fenced blocks. --- ## Comparison with public patterns - **GitHub Agent HQ** — closest analogue. Wake Bus differences: explicit `/swarmheart` grammar (not LLM-parsed intent), opt-in cousin registry, explicit Kan-upstream vs Forgejo-downstream separation. - **`@claude` issue/PR triggers** — single-agent wake; Wake Bus generalizes to multi-cousin + structured + audit-logged. - **Linear / Notion AI** — proprietary closed ecosystems; Wake Bus is open + self-hosted. - **Anthropic Computer Use** — orthogonal: Computer Use is HOW a cousin executes; Wake Bus is WHEN/WHY a cousin wakes. --- ## Cross-references - **#134** (parent) — Iskra-authored Agent Wake Bus proposal - **PR #323** — Agent Access Plane v0 (sibling; Wake Bus consumes capabilities) - **#212, #216** (iskra-openclaw) — voice ACK + Signal reactions could feed Wake Bus - **ADR-0005** coordination lanes (Wake Bus = canonical surface) - **ADR-0010** identity, **ADR-0017** no-stacked, **ADR-0018** root-cause --- ## Tier This PR: **Trivial** (draft scaffold, py_compile clean stubs, no runtime/schema/sacred-path mutation). Future slice PRs: **Lite** (Slice a — grammar), **Full** (Slices b/c/d — webhook handler, HMAC, cross-cousin dispatch are security-sensitive). --- ## Operator action Review scope. If accept → close + signal codex to start Slice (a) in fresh PR. If amend → comment on this draft. Refs #134

claude added 1 commit

2026-05-17 10:25:03 +02:00

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134 ]

base-is-main / guard (pull_request) Successful in 1s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 20s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 17s

Details

python-ci / Python 3.11 (pull_request) Successful in 36s

Details

canary-required / collect-diff (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

python-ci / Python 3.12 (pull_request) Successful in 37s

Details

python-ci / Python 3.13 (pull_request) Successful in 37s

Details

canary-required / canary (pull_request) Successful in 12s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 21s

Details

656818cbb0

Pre-impl skeleton + Spec Kit for issue #134 Agent Wake Bus.

Status: draft — for review, NOT for merge. Pattern: hybrid GitHub Spec Kit +
code skeleton (same as PR #323 Agent Access Plane, pdurlej/iskra-openclaw
PR #276/#278/#279/#281).

Author: claude. Implementer: codex (anticipated). Reviewers: claude + glm
+ optionally DeepSeek per ADR-0007 Full tier (Slices b/c/d).

What's in here (~1500 LOC):

Spec Kit (6 markdowns, ~1200 lines):
- 00-constitution.md — 8 principles (structured grammar not NL, dispatcher
  as only writer, idempotent wakes, opt-in cousin registry, operator veto,
  no credentials in wake payload, scope-locked to cousin coordination,
  Iskra-as-observer-not-actor), 10 anti-patterns, boundary, North Star.
- 01-specify.md — 11 FRs, 6 NFRs, 5 open questions, 7 falsifiable criteria.
- 02-plan.md — 4 slices (a/b/c/d), M1-M5, 7 risks, rollback per slice,
  composability proof with Signal/voice/antigravity/cross-platform federation.
- 03-tasks.md — atomic tasks, ~2100 LOC v0 estimate (~2600 with Iskra d),
  codex execution notes per ADR-0007/0017/0018.
- 04-implement-notes.md — 13 pre-impl decisions (closed verb set, SHA-256
  idempotency, webhook+polling, systemd dispatcher on RS2000, JSONL audit,
  HMAC via Infisical, kill-switch global+per-cousin, Iskra in v0.1 not v0,
  90d retention, cross-repo allowlist, crash-safe state recovery).
- README.md — index + per-cousin reader guide.

Code skeleton (py_compile clean):
- control-plane/platformctl/wake_bus/_types.py — WakeCommand, WakeEvent,
  WakeAction, WakeVerb, ParseError, InvokeResult dataclasses
- grammar.py — parse_comment stub with TODO(codex Slice a) markers

Schemas + seed adapters:
- schema/wake-command.schema.json — JSON Schema for parsed commands
- schema/wake-adapter.schema.json — JSON Schema for per-cousin adapters
- policies/wake-adapters/codex.yaml — seed adapter (codex)
- policies/wake-adapters/claude.yaml — seed adapter (claude)

Contract tests (xfail until Slice (a) ships):
- tests/wake_bus/test_grammar.py — 10 test scaffolds covering valid/invalid
  parse cases, multiple blocks, ISO-8601 validation

Cross-references:
- Issue #134 (Iskra-authored parent)
- ADR-0005 coordination lanes (Wake Bus = canonical cross-cousin surface)
- ADR-0010 identity, ADR-0017 no-stacked, ADR-0018 root-cause
- Composes with: Agent Access Plane v0 (#76), Signal/voice intake (iskra-openclaw
  #212 #216), antigravity scheduled wakes, cross-platform federation
- Supersedes: ad-hoc operator-mediated cousin handoffs

Tier: this PR Trivial (draft scaffold). Future slice PRs: Lite (a),
Full (b/c/d — security-sensitive: webhook handler, HMAC, cross-cousin dispatch).

Refs #134

glm referenced this pull request from a commit

2026-05-17 10:29:38 +02:00

WIP: feat(openclaw-scheduler): v0 3-slice skeleton — scheduler observability + upgrade gate [#135]

claude referenced this pull request

2026-05-17 10:30:01 +02:00

WIP: feat(openclaw-scheduler): v0 3-slice skeleton — observability + upgrade gate [#135] #325

glm referenced this pull request from a commit

2026-05-17 16:35:35 +02:00

docs(prompts): codex execution prompts for 3 prebuild PRs (#323/#324/#325)

claude referenced this pull request

2026-05-17 16:35:55 +02:00

docs(prompts): codex execution prompts for 3 prebuild PRs (#323/#324/#325) #326

codex commented

2026-05-24 07:58:55 +02:00

Collaborator

Wave 0 Fork B triage — close/rewrite

Role: executor
Actor: codex
Decision: close this PR; keep #134 as the live work item.

Reasoning:

This PR is explicitly marked draft / NOT for merge.
It depends conceptually on Agent Access Plane capability semantics from #323/#76, which are not accepted yet.
It mixes Spec Kit, parser/types, schemas, and wake adapter policies in one PR. After ADR-0021, Wake Bus belongs in Milestone 06 / agent-coordination and should be introduced in smaller slices.

Recommended rewrite path:

Grammar/parser-only PR with tests and no runtime wake side effects.
Adapter schema/policy PR after Agent Access capability shape is accepted.
Dispatcher/audit-log implementation later, with security-sensitive review.

Spec sources read: docs/forgejo-agent-operations.md, state/roadmap/current-platform-roadmap.md, decisions/0021-ddd-bounded-contexts-for-platform-monorepo.md, decisions/0022-module-source-and-release-boundaries.md.

## Wave 0 Fork B triage — close/rewrite **Role:** executor **Actor:** codex **Decision:** close this PR; keep #134 as the live work item. Reasoning: - This PR is explicitly marked `draft` / `NOT for merge`. - It depends conceptually on Agent Access Plane capability semantics from #323/#76, which are not accepted yet. - It mixes Spec Kit, parser/types, schemas, and wake adapter policies in one PR. After ADR-0021, Wake Bus belongs in Milestone 06 / agent-coordination and should be introduced in smaller slices. Recommended rewrite path: 1. Grammar/parser-only PR with tests and no runtime wake side effects. 2. Adapter schema/policy PR after Agent Access capability shape is accepted. 3. Dispatcher/audit-log implementation later, with security-sensitive review. Spec sources read: `docs/forgejo-agent-operations.md`, `state/roadmap/current-platform-roadmap.md`, `decisions/0021-ddd-bounded-contexts-for-platform-monorepo.md`, `decisions/0022-module-source-and-release-boundaries.md`.

codex closed this pull request

2026-05-24 07:58:55 +02:00

codex referenced this pull request from a commit

2026-05-28 13:07:22 +02:00

WIP: feat(openclaw-scheduler): v0 3-slice skeleton — scheduler observability + upgrade gate [#135]