Summary

Refs #52305. Companion to #80214 (cron-run remap at internal enqueue sites) and #71213 (prompt content layer, MERGED). Together with #80214, this PR is intended to close #52305: #78687 covers the external wake/system-event sessionKey surface, while #80214 covers internal cron-run exec/ACP/node-event/watchdog completion routing. The two PRs touch disjoint surfaces and can be reviewed independently.

Adds an optional sessionKey to the wake protocol so callers can target a specific session for system events / async-task completion relays instead of always hitting the agent's main session. Without this, the CLI surface for openclaw system event was main-session-only, and WakeParamsSchema left sessionKey opaque, which was the remaining external-callback gap clawsweeper called out on #52305.

Changes

1. Schema — WakeParamsSchema (src/gateway/protocol/schema/agent.ts): add sessionKey: Type.Optional(NonEmptyString). Empty / non-string is rejected at the validator boundary.
2. Wake handler (src/gateway/server-methods/cron.ts:179): forward sessionKey to context.cron.wake({...}) when provided.
3. CronService contract + impl (src/cron/service-contract.ts, src/cron/service.ts, src/cron/service/ops.ts, src/cron/service/timer.ts): thread optional sessionKey through wake() → wakeNow() → underlying wake(state, opts) ops. Whitespace-only keys are treated as omitted.
4. Gateway cron adapter (src/gateway/server-cron.ts): when only sessionKey is supplied (no agentId), enqueueSystemEvent now derives agentId from the session key — mirroring what requestHeartbeat's resolveCronWakeTarget already does. Without this, resolveCronSessionKey would treat a non-default agent's key as foreign and silently reroute to the default agent's main session, while heartbeat woke the correct session — an asymmetric bug. Caught by codex in P2 review on this branch and fixed before opening.
5. CLI (src/cli/system-cli.ts): add --session-key <sessionKey> option to openclaw system event. Whitespace-only values are treated as omitted to match server-side semantics.
6. Docs (docs/cli/system.md): describe the new flag, the safety fall-back (foreign-agent keys → agent's main session), and a callout for the next-heartbeat + --session-key timing exception (collapses to immediate targeted wake; addresses [P3] from clawsweeper review).

Out of scope

• The internal enqueue-site cron-run-key remap (cron:run:uuid → agent-main) is handled by fix(heartbeat): remap cron-run exec events to session keys #80214. This PR is only about the external contract surface; it doesn't touch exec-runtime / ACP / CLI watchdog enqueue sites.
• Adding sessionKey to other RPC surfaces. Only wake is in scope.
• Deeper schema-level shape validation (parseAgentSessionKey-style). Defer until there's evidence of misuse — resolveCronSessionKey's existing cross-agent fall-back covers the security concern.

Real behavior proof

• Behavior or issue addressed: external callers (mobile clients, the openclaw system event CLI, plugin SDKs) need a way to target a specific agent session for system-event/wake delivery. The pre-PR WakeParamsSchema typed only {mode, text} with additionalProperties: true, so sessionKey could be smuggled in but was opaque and unvalidated. The CLI's system event had no way at all to set it. Closing this gap means async-task completion relays from external systems can land in the originating agent's session instead of always hitting the agent's main session.

• Real environment tested: Local OpenClaw checkout on Linux 6.6.87.2 / WSL2 / Node v25.8.2, branched from current upstream/main at 95a1c91531 (post-v2026.5.6, includes the canvas-plugin refactor that consolidated apps/macos/Sources/OpenClawProtocol/GatewayModels.swift into apps/shared/OpenClawKit/). Gateway runs as systemd user service.

• Exact steps or command run after this patch: branched from current upstream/main, applied this PR's schema + CLI + wake-handler + cron-adapter changes, then ran the routing helpers directly via node --import tsx against the patched source to confirm session-key handling in the wake-routing layer for the three key shapes the cron adapter has to deal with (agent-prefixed channel, agent-prefixed cron-run, relative).

• Evidence after fix:

  $ openclaw status | grep -E "Update|Gateway service"
  │ Update               │ pnpm · up to date · npm latest 2026.5.6                                  │
  │ Gateway service      │ systemd user installed · enabled · running (pid 270001, state active)    │
  
  $ cat > /tmp/wake-routing-repro.ts << 'EOF'
  // Reproduces wake-routing decisions on the patched source using only
  // the helpers actually exported from src/routing/session-key.ts.
  import {
    scopedHeartbeatWakeOptions,
    resolveAgentIdFromSessionKey,
    classifySessionKeyShape,
  } from "/home/captain/openclaw-source/src/routing/session-key.js";
  
  const cases = [
    { label: "agent-prefixed channel  ", key: "agent:research:telegram:dm:42" },
    { label: "agent-prefixed cron-run ", key: "agent:research:cron:nightly:run:abc-123" },
    { label: "relative key            ", key: "discord:channel:ops" },
  ];
  for (const { label, key } of cases) {
    console.log(label, "shape=" + classifySessionKeyShape(key),
      "agentId=" + JSON.stringify(resolveAgentIdFromSessionKey(key)));
    console.log(label, "wake-options:",
      JSON.stringify(scopedHeartbeatWakeOptions(key, { reason: "exec-event" })));
  }
  EOF
  
  $ node --import tsx /tmp/wake-routing-repro.ts
  agent-prefixed channel   shape=agent agentId="research"
  agent-prefixed channel   wake-options: {"reason":"exec-event","sessionKey":"agent:research:telegram:dm:42"}
  agent-prefixed cron-run  shape=agent agentId="research"
  agent-prefixed cron-run  wake-options: {"reason":"exec-event","sessionKey":"agent:research:cron:nightly:run:abc-123"}
  relative key             shape=legacy_or_alias agentId="main"
  relative key             wake-options: {"reason":"exec-event"}

  Confirms (a) classifySessionKeyShape correctly tags agent-prefixed vs relative keys; (b) resolveAgentIdFromSessionKey extracts the agent id (research) for agent-prefixed shapes and falls back to the literal "main" for relative keys; (c) scopedHeartbeatWakeOptions passes agent-prefixed keys through to the heartbeat target, but drops the sessionKey (returns {reason} only) for relative keys — because the routing helper alone can't disambiguate which configured agent owns a relative key.

  That (c) observation is the asymmetry this PR's cron-adapter change in src/gateway/server-cron.ts corrects: resolveCronWakeTarget already called resolveAgentIdFromSessionKey and routed wakes to the resolving agent's queue. But enqueueSystemEvent in the same adapter went through resolveCronSessionKey, which on a multi-agent deployment where main is not the configured-default would treat a foreign agent's key as off-target and silently re-route the event to the default agent's main session. Wake fired on agent A; event landed in agent B. After this PR, both enqueueSystemEvent and resolveCronWakeTarget derive agentId the same way (via parseAgentSessionKey + resolveAgentIdFromSessionKey, then passed to the existing resolveCronAgent helper), so both sides agree on the target.

• Integration test (cbded2f): src/gateway/server-cron.test.ts now includes a test (derives agentId symmetrically for enqueue and wake when only an agent-prefixed sessionKey is supplied) that constructs the cron-adapter against a multi-agent config (primary default + ops non-default), drives cronDeps.enqueueSystemEvent and cronDeps.requestHeartbeat with the same foreign-agent session key (agent:ops:cron:nightly:run:abc-123), and asserts both observed outputs target agent:ops:... rather than falling back to primary. Without this PR's adapter change the assert on the enqueue side would fail because pre-PR's enqueueSystemEvent adapter ran resolveCronAgent(undefined) and rerouted to primary's main queue.

  $ pnpm vitest run src/gateway/server-cron.test.ts -t "symmetric"
   Test Files  1 passed (1)
        Tests  1 passed | 12 skipped (13)
     Start at  19:19:41
     Duration  28.26s (transform 20.09s, setup 1.89s, import 25.98s, tests 26ms, environment 0ms)
  

• Live gateway smoke: built the gateway from the rebased branch and ran it on a separate test instance (OPENCLAW_HOME=/tmp/oc-test-home, port 18790, OPENCLAW_SKIP_CHANNELS=1) with a multi-agent config — primary (default) + ops (non-default), shared ollama-cloud/kimi-k2.5 model, agents.defaults.heartbeat.every: "1h" so heartbeats are enabled for every agent (otherwise isHeartbeatEnabledForAgent only returns true for the configured-default agent). Then ran two system event calls back-to-back via the patched CLI:

  $ openclaw system event --url ws://127.0.0.1:18790 --token <redacted> \
      --session-key agent:ops:cron:demo:run:CASE_A \
      --text "case-A-marker" --mode now --json
  { "ok": true }
  
  $ openclaw system event --url ws://127.0.0.1:18790 --token <redacted> \
      --session-key agent:primary:cron:demo:run:CASE_B \
      --text "case-B-marker" --mode now --json
  { "ok": true }
  

  Gateway dispatch log on the test instance:

  20:33:39 [diagnostic]      lane enqueue: lane=session:agent:ops:cron:demo:run:case_a queueSize=1
  20:33:39 [diagnostic]      lane dequeue: lane=session:agent:ops:cron:demo:run:case_a waitMs=3 queueSize=0
  20:33:51 [agent/embedded]  pre-prompt: sessionKey=agent:ops:cron:demo:run:case_a … provider=ollama-cloud/kimi-k2.5
                             sessionFile=/tmp/oc-test-home/.openclaw/agents/ops/sessions/92947670-…jsonl
  20:34:09 [diagnostic]      lane task done: lane=session:agent:ops:cron:demo:run:case_a durationMs=30027
  
  20:34:18 [diagnostic]      lane enqueue: lane=session:agent:primary:cron:demo:run:case_b queueSize=1
  20:34:18 [diagnostic]      lane dequeue: lane=session:agent:primary:cron:demo:run:case_b waitMs=3 queueSize=0
  20:34:24 [agent/embedded]  pre-prompt: sessionKey=agent:primary:cron:demo:run:case_b … provider=ollama-cloud/kimi-k2.5
                             sessionFile=/tmp/oc-test-home/.openclaw/agents/primary/sessions/9689b924-…jsonl
  20:34:38 [diagnostic]      lane task done: lane=session:agent:primary:cron:demo:run:case_b durationMs=19782
  

  Two pieces of evidence in each block:

  1. Lane name — heartbeat-runner's command-queue lane is keyed by the resolved agent's session: session:agent:ops:… for the foreign-agent call, session:agent:primary:… for the default-agent call. Pre-PR, CASE_A's lane would have read session:agent:primary:cron:demo:run:case_a because the enqueue side fell back to resolveCronAgent(undefined) and rerouted to the configured default; the symmetric agentId derivation this PR adds is what makes CASE_A land at ops.
  2. Session file path — independent filesystem confirmation: agents/ops/sessions/…jsonl for CASE_A vs agents/primary/sessions/…jsonl for CASE_B. The event was actually filed under the originating agent's on-disk session store, not the configured-default's.

  Both runs completed successfully (lane task done after ~20–30s) against the live ollama-cloud/kimi-k2.5 provider, so this is end-to-end behavior including model dispatch, not just routing.

• Observed result after fix:

  • WakeParamsSchema now types sessionKey: NonEmptyString (optional). Empty string / non-string is rejected at the gateway boundary before reaching the cron service.
  • openclaw system event --session-key <key> --text foo forwards the key in the JSON-RPC payload (verified in src/cli/system-cli.test.ts); whitespace-only values are treated as omitted.
  • wake({mode: "now", text, sessionKey}) and wake({mode: "next-heartbeat", text, sessionKey}) both fire a targeted immediate heartbeat when sessionKey is supplied — codex review surfaced (round 5 of this PR's iteration) that an event-intent wake gets deferred as not-due by the heartbeat-runner and isn't retried, so an immediate wake is the only reliable path. Documented in the wake-fn comment block AND in docs/cli/system.md as a public timing-exception callout (addresses clawsweeper [P3]).
  • The gateway cron adapter routes both agent-prefixed and relative session keys through the same resolveCronAgent resolution for enqueue and wake, so they land in/wake the same target on multi-agent deployments where main exists but isn't the configured default. Pre-PR, resolveCronWakeTarget always derived agentId from resolveAgentIdFromSessionKey while enqueueSystemEvent did not, so wake could target agent:<resolving>:... while enqueue went to agent:<configured-default>:.... That asymmetry is now fixed.
  • Generated WakeParams Swift model (apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift) updated to expose the new field. The standalone apps/macos/Sources/OpenClawProtocol/GatewayModels.swift was deleted by upstream's canvas-plugin refactor (commit 330ba1fa31); after rebase only the shared one survives. pnpm protocol:check runs protocol:gen + protocol:gen:swift + git diff --exit-code — verified locally clean (exit 0) on the rebased branch with @openclaw/fs-safe@c7ccb99d installed.

• What was not tested:

  • This change is channel-agnostic — sessionKey is a typed field on the JSON-RPC schema, so any caller (mobile client, plugin SDK, channel webhook, native chat, the openclaw system event CLI itself) that targets a specific session benefits the same way. The live smoke above exercises the CLI surface; other callers share the same gateway/cron-adapter code path.

Test plan

• CLI test (src/cli/system-cli.test.ts): --session-key is forwarded in the JSON-RPC payload; omitted / whitespace-only values do not appear in the payload.
• Wake handler test (src/gateway/server-methods/cron.validation.test.ts): forwards sessionKey to context.cron.wake when present, omits when absent, schema rejects empty / non-string values.
• Timer wake test (src/cron/service/wake.test.ts): threads sessionKey to both enqueueSystemEvent and requestHeartbeat on both now and next-heartbeat modes (collapses to targeted-immediate when sessionKey is supplied so the runner doesn't drop the wake as not-due); whitespace-only keys treated as omitted.
• Cron-adapter integration test (src/gateway/server-cron.test.ts, commit cbded2f68f): with multi-agent config (default primary + non-default ops) and a foreign-agent session key, both enqueueSystemEvent and requestHeartbeat adapter call sites resolve agentId to ops symmetrically. Pre-PR this assert would fail on the enqueue side (rerouted to primary's main).
• Live gateway smoke from the rebased branch (multi-agent config, ollama-cloud/kimi-k2.5): --session-key flag advertised in CLI help, system event --session-key accepted by the wake RPC ({"ok": true}); foreign-agent call lands at session:agent:ops:… lane with sessionFile under agents/ops/sessions/…, default-agent call at session:agent:primary:… lane with sessionFile under agents/primary/sessions/…; both agent runs completed against the live provider.
• Real-behavior reproducer above documents observed routing for the three key shapes (agent-prefixed channel, agent-prefixed cron-run, relative).
• Existing wake({mode, text}) callers (no sessionKey) continue to default to agent-main session — verified by the omitted-when-absent tests above.
• pnpm protocol:check exit 0 locally on the rebased branch — Swift model regen matches the gen output.
• Codex review on the rebased branch addressed: [P3] timing-exception now documented in docs/cli/system.md; the proof block above uses only helpers actually exported from src/routing/session-key.ts.

Security Impact

• New permissions/capabilities? No.
• Secrets/tokens handling changed? No.
• New/changed network calls? No.
• Command/tool execution surface changed? No.
• Data access scope changed? Slightly — a wake caller can now target a specific session within an agent. The cross-agent safety check in resolveCronSessionKey is preserved: keys that don't belong to the resolving agent fall back to that agent's main session, so a caller cannot inject events into a different agent's queue.