swarm-zap/WIP.md

# WIP.md

## Current focus
Google Workspace + n8n integration

## Goal
Use OpenClaw as the brain, n8n as the orchestration layer, and Google Workspace as a real execution surface for Gmail/Calendar workflows.

## Current status
Status: `in-progress`
Owner: `zap`
Started: `2026-03-12`

### Architecture decision
- Keep `openclaw-action` as the narrow authenticated ingress into n8n.
- Keep approval/state/logging in n8n.
- Use workflow static data for tiny internal state and recent operational breadcrumbs.
- Do not adopt n8n data tables as the default state store yet; revisit only when shared row-based data, UI browsing/editing, or richer querying becomes a real need.
- Use host-side `gog` execution for Google Workspace actions for now.
- Attach execution results back into n8n history so approval items become auditable records.
- Prefer this over broad n8n Google credential sprawl unless a later need clearly justifies it.

### Where n8n is a good fit here
- approval-gated actions and human-in-the-loop workflows
- cross-system glue / action-bus routing
- inbound event filtering, normalization, and dedupe
- notification fanout and formatting
- retries / backoff / rate-limit wrappers around brittle integrations
- fetch-and-normalize pipelines for URLs or provider payloads
- compact audit trail / operator history

### Where n8n is not the default
- primary long-term database
- heavy archival logging
- large or fast-growing datasets
- business logic that is clearer and safer in normal code

## What is already done

### n8n action bus
- [x] Live `openclaw-action` workflow exists and is active.
- [x] Core actions verified live:
  - `append_log`
  - `get_logs`
  - `notify`
  - `approval_queue_add`
  - `approval_queue_list`
  - `approval_queue_resolve`
  - `fetch_and_normalize_url`
  - `inbound_event_filter`
- [x] Approval-gated notification execution works live:
  - `send_notification_draft`
  - approve → real `notify`

### Google access
- [x] `gog` installed and authenticated for:
  - Gmail
  - Calendar
  - Drive
  - Contacts
  - Docs
  - Sheets
- [x] Local-only Gog automation env stored outside git at:
  - `/home/openclaw/.openclaw/credentials/gog.env`
- [x] Host bridge implemented:
  - `skills/n8n-webhook/scripts/resolve-approval-with-gog.py`
- [x] n8n history patch action implemented:
  - `approval_history_attach_execution`
- [x] Dry-run end-to-end bridge tests succeeded for:
  - Gmail draft creation
  - Calendar event creation
- [x] Headless non-interactive Gog execution works via the stored local env.
- [x] Direct real Gmail draft create test succeeded.
- [x] Direct real Gmail draft delete test succeeded.
- [x] Real n8n-routed Gmail draft test succeeded end-to-end (queue → approve via bridge → verify → delete).
  - approval id: `approval-mmnvjcak-qcuhbzqd`
  - draft id: `r348335896293726096`
  - subject: `[zap n8n e2e] Gmail draft test 20260312T194153Z`
- [x] Real n8n-routed Calendar event test succeeded end-to-end (queue → approve via bridge → verify → delete).
  - approval id: `approval-mmnvjyo5-uezhcw84`
  - event id: `il3ojkfnsnq3uhlepvrmaklpq4`
  - title: `[zap n8n e2e] Calendar test 20260312T194222Z`

## What is left

### Highest priority: prove the bridge with real Google writes
- [x] Real end-to-end Gmail draft via n8n path:
  1. queue `send_email_draft`
  2. approve via `resolve-approval-with-gog.py`
  3. verify draft exists in Gmail
  4. delete the test draft
- [x] Real end-to-end Calendar event via n8n path:
  1. queue `create_calendar_event`
  2. approve via bridge
  3. verify event exists in Calendar
  4. delete the test event

### Then expand useful Google actions
- [ ] Add `delete_email_draft`
- [ ] Add `list_email_drafts`
- [ ] Add `send_gmail_draft` / send-approved-email path
- [ ] Add `update_calendar_event`
- [ ] Add `delete_calendar_event`
- [ ] Add `list_upcoming_events`
- [ ] Decide whether Drive/Docs/Sheets need action-bus verbs next or can stay direct-tool only for now

### Then polish the operator experience
- [ ] Add a compact operator command/reference section for common approval flows
- [ ] Add one or two canned test payloads for real bridge verification flows
- [ ] Decide whether some Google actions should stay approval-gated by default
- [ ] Add low-noise reporting so history clearly shows:
  - queued
  - approved/rejected
  - executed
  - execution result id / draft id / event id

## Nice-to-have / future
- [ ] Evaluate whether native n8n Google nodes are worth adding later
- [ ] Add retry/backoff wrappers for fragile or rate-limited actions
- [ ] Expand notification fanout / routing rules if more channels become useful
- [ ] Add more inbound event normalization/filtering when new providers are wired in
- [ ] Revisit n8n data tables only if shared row-based operator data becomes useful
- [ ] If useful, sync this work into the LAN Gitea repo for safer backup/review and easier long-lived tracking

## Current recommendation
Execution should proceed in staged fresh sessions using `WIP.md` as the canonical state file.

Planned passes:
1. Gmail pass:
   - add `delete_email_draft`
   - add `list_email_drafts`
   - add `send_gmail_draft` / send-approved-email path
   - update `WIP.md` with evidence before ending the pass
2. Calendar pass:
   - add `update_calendar_event`
   - add `delete_calendar_event`
   - add `list_upcoming_events`
   - update `WIP.md` with evidence before ending the pass
3. Operator/polish pass:
   - decide approval defaults for each action
   - add low-noise execution/result reporting
   - add compact operator command/reference docs
   - add one or two canned recurring test payloads
   - update `WIP.md` with evidence before ending the pass

## Fresh-session proof refresh (2026-03-12 19:44Z)
- Re-ran both target proofs through the real approval-routed path in a clean implementation session.
- Gmail draft flow:
  - approval id: `approval-mmnvn4t2-w2rjlwz2`
  - draft id: `r-3319106208870238577`
  - subject: `[zap n8n e2e] Gmail draft test 20260312T194450Z`
  - verified via `gog gmail drafts get`
  - cleaned via `gog gmail drafts delete --force`
- Calendar flow:
  - approval id: `approval-mmnvn6i8-e9eq8gdf`
  - event id: `m7prri8vk2opuo6loq3qgtvsv4`
  - title: `[zap n8n e2e] Calendar test 20260312T194450Z`
  - verified via `gog calendar get primary <eventId>`
  - cleaned via `gog calendar delete primary <eventId> --force`

## Next-session handoff
For the next fresh implementation session, start from `HANDOFF.md` + `WIP.md` rather than from old chat context.

Immediate target:
- implement at least one new Gmail action and one new Calendar action
- verify through the same approval+bridge flow
- refresh WIP/memory/tasks and commit

## Relevant files
- `skills/n8n-webhook/assets/openclaw-action.workflow.json`
- `skills/n8n-webhook/scripts/call-action.sh`
- `skills/n8n-webhook/scripts/resolve-approval-with-gog.py`
- `skills/n8n-webhook/references/openclaw-action.md`
- `memory/2026-03-12.md`
- `/home/openclaw/.openclaw/credentials/gog.env` (local-only, not for git)

## Current branch / checkpoints
- branch: `feat/n8n-action-bus-v2`
- key commits:
  - `9dcc477` — expand action bus starter workflow
  - `dc990a1` — deploy and verify expanded action bus
  - `1eabaeb` — add approval-gated notification executor
  - `afa48a3` — bridge approvals to gog executors
  - `044e36f` — auto-load local gog automation env