Scope agent cron operations to the calling agent by joshavant · Pull Request #96883 · openclaw/openclaw

joshavant · 2026-06-26T01:28:50Z

What Problem This Solves

Agent-originated cron tool operations now carry the calling agent identity through the Gateway cron API, so cron reads and mutations made from an agent tool session are limited to that same agent's jobs.

Why This Change Was Made

Cron APIs are also used by operator and internal flows, so this keeps the existing unscoped/operator behavior unchanged while adding an explicit scope only for agent-tool calls. The Gateway enforces the scope server-side, and the agent cron tool stamps newly created jobs with the calling agent before persistence.

User Impact

Existing cron configurations and operator-managed cron jobs should continue to work normally. The new scope is only applied to agent-tool cron calls; direct unscoped cron RPC callers retain the current global behavior.

Agent-tool cron calls can still create, list, update, run, inspect history for, and remove jobs owned by the calling agent. Attempts from that path to target another agent's jobs or session references are rejected.

If a running older Gateway rejects the new internal agent cron connection metadata, the agent-facing error now remains fail-closed and tells the user to restart the Gateway with openclaw gateway restart before retrying. Installer and Control UI update paths also surface an explicit manual Gateway restart/update command when an automatic handoff cannot be completed.

Evidence

pnpm build
git diff --check origin/main...HEAD
Focused local cron/protocol/tool tests:
- node scripts/run-vitest.mjs packages/gateway-protocol/src/cron-validators.test.ts src/gateway/server-methods/cron.validation.test.ts src/gateway/server.cron.test.ts src/agents/tools/cron-tool.test.ts src/agents/tools/cron-tool.flat-params.test.ts
Built Gateway runtime proof from current head (ed53735bc561fa51fba75e292071fedc88827a11):

$ node --input-type=module <built Gateway cron handler smoke>
PASS same-agent list scoped to caller: visible jobs=ops-job
PASS cross-agent list rejected: invalid cron.list params: agentId outside caller scope
PASS same-agent create allowed: created job agentId=ops
PASS cross-agent create rejected: invalid cron.add params: job agentId outside caller scope
PASS same-agent update allowed: updated job=ops-job enabled=false
PASS cross-agent update hidden: invalid cron.update params: id not found
PASS same-agent run allowed: enqueue jobId=ops-job mode=force
PASS cross-agent run hidden: invalid cron.run params: id not found
PASS same-agent remove allowed: removed=true
PASS cross-agent remove hidden: invalid cron.remove params: id not found
PASS unscoped operator list remains global: visible jobs=ops-job,research-job
PASS unscoped operator update can retarget agentId: updated job=ops-job agentId=research
Built Gateway cron handler smoke passed using dist/cron-BeauUpdR.js

Redacted focused test transcript from current head:

$ node scripts/run-vitest.mjs src/gateway/server-methods/cron.validation.test.ts src/agents/tools/cron-tool.test.ts -- --reporter=verbose
Gateway shard: Test Files 2 passed (2), Tests 130 passed (130)
Agent-tool shard: Test Files 1 passed (1), Tests 134 passed (134)
[test] passed 2 Vitest shards in 16.49s

Testbox changed check passed:
- provider: blacksmith-testbox
- id: tbx_01kw0rg2xd3ek7jdgkf411k3wq
Testbox focused cron/protocol/tool tests passed:
- provider: blacksmith-testbox
- id: tbx_01kw0rg159zn0myaxqvvxhxemm
Testbox QA Lab cron/reminder scenarios passed before the final rebase:
- provider: blacksmith-testbox
- id: tbx_01kw0qk6n3ye3v3e5gmx5x5y87
- scenarios: cron-single-run-no-duplicate, cron-natural-fire-no-duplicate, personal-reminder-roundtrip
Local built-Gateway smoke verified before the final rebase:
- unscoped/operator cron CRUD and list behavior remains global
- agent-tool cron CRUD/list is limited to the calling agent
- cross-agent job and session-target attempts are rejected
- callerScope is not persisted into stored cron jobs

Latest validation after restart/update guidance changes (543705877f):

Focused Gateway and agent Gateway tool tests passed:

$ node scripts/run-vitest.mjs src/gateway/call.test.ts src/gateway/client.test.ts src/agents/tools/gateway.test.ts
Gateway shard: Test Files 7 passed (7), Tests 639 passed (639)
Agent shard: Test Files 1 passed (1), Tests 40 passed (40)
[test] passed 2 Vitest shards

Focused Control UI and installer tests passed:

$ node scripts/run-vitest.mjs ui/src/ui/controllers/config.test.ts test/scripts/install-cli.test.ts test/scripts/install-sh.test.ts test/scripts/install-ps1.test.ts
Tooling shard: Test Files 3 passed (3), Tests 82 passed, 9 skipped
UI shard: Test Files 1 passed (1), Tests 45 passed
[test] passed 2 Vitest shards

Live source-Gateway cron path passed with isolated state:

live source-gateway cron path ok
{"jobId":"39d00071-33f0-4309-9293-b4ed329dcc8f","cliListed":true,"scopedRejectedForeign":true}

Live older-Gateway rejection probe passed and surfaced restart guidance:

live stale-gateway cron warning ok
The running Gateway is from an older OpenClaw build and rejected current agent cron connection metadata. Restart the Gateway with `openclaw gateway restart`, then retry.

Control UI browser proof passed with a mocked Gateway update handoff response:

control-ui update handoff browser proof ok
updateRunRequests=1
alertText="Update skipped: managed-service-handoff-unavailable. Run `openclaw update --yes` from a shell outside the Gateway process."

Static/local checks passed:
- git diff --check
- bash -n scripts/install.sh && bash -n scripts/install-cli.sh
- node scripts/run-tsgo.mjs -b tsconfig.projects.json
Local pwsh was not installed, so direct install.ps1 parse was skipped locally; the PowerShell installer Vitest coverage above passed.
Testbox changed check passed after the latest commit:
- provider: blacksmith-testbox
- id: tbx_01kw2sxj346th07qtc8akrez78
Autoreview passed after the latest commit:

autoreview clean: no accepted/actionable findings reported
overall: patch is correct (0.87)

Final production-path validation after b9b90fef12:

Added repeatable packaged Docker cron CLI smoke coverage via pnpm test:docker:cron-cli, covering cron status, add, list, show, disable, enable, run --wait, runs, and rm through the packaged CLI against a packaged Gateway.
Added direct agent/openclaw-tools caller identity regression proof in src/agents/openclaw-tools.gateway-caller-identity.test.ts.
Added ACPX openclaw-tools bridge upgrade-survivor coverage and changed-lane routing so that related plugin bridge configuration is exercised across recent stable baselines.
Focused local regression tests passed:

node scripts/run-vitest.mjs test/scripts/upgrade-survivor-config-recipe.test.ts test/scripts/upgrade-survivor-assertions.test.ts test/scripts/docker-e2e-plan.test.ts test/scripts/docker-e2e-observability.test.ts test/scripts/test-projects.test.ts test/scripts/package-acceptance-workflow.test.ts src/agents/openclaw-tools.gateway-caller-identity.test.ts
Tooling shard: Test Files 6 passed, Tests 266 passed
Agent shard: Test Files 1 passed, Tests 1 passed

Testbox pnpm build passed:
- provider: blacksmith-testbox
- id: tbx_01kw307fpaght5rr6f3t002wg3
Testbox strict live ACP bind cron proof passed with Codex after Docker env forwarding was added:
- provider: blacksmith-testbox
- id: tbx_01kw31d4xg3n89qekrfsjta017
Testbox MCP sibling notification/cleanup proof passed:
- provider: blacksmith-testbox
- id: tbx_01kw31wm36fwch2mxkbcv0ztfz
Testbox update/restart auth path passed:
- provider: blacksmith-testbox
- id: tbx_01kw323nafqv6vmwrajq84qhch
Testbox published upgrade-survivor ACPX bridge matrix passed for the last four stable baselines (2026.6.10, 2026.6.9, 2026.6.8, 2026.6.6):
- provider: blacksmith-testbox
- id: tbx_01kw32h1kwbp8ajzxz02xvjkfq
Testbox packaged cron CLI Docker smoke passed after the smoke was hardened to seed an approved local CLI device before Gateway startup:
- provider: blacksmith-testbox
- id: tbx_01kw3919zh8b7enbjm060b2kgt
Testbox broad changed test gate passed after the final proof additions:
- provider: blacksmith-testbox
- id: tbx_01kw395dv0sb7367f1dse79wtz
Testbox changed check passed after the final proof additions:
- provider: blacksmith-testbox
- id: tbx_01kw39kt3tde4ns1wd6cz7q9bw
Local hygiene/review gates passed after the final proof additions:
- bash -n scripts/e2e/cron-cli-docker.sh
- node scripts/run-vitest.mjs test/scripts/docker-e2e-observability.test.ts -- --reporter=verbose
- git diff --check
- autoreview clean: no accepted/actionable findings reported

Additional packaged cron lifecycle soak:

Testbox packaged Gateway cron lifecycle soak passed:
- provider: blacksmith-testbox
- id: tbx_01kw3dndfsbm8p1wz7rbv4jc2w
- covered: natural periodic command cron execution, one-shot command cron execution after Gateway restart, disabled cron no-rerun wait window, edited command payload execution, removal/absence checks after a second Gateway restart, and final cleanup through the packaged CLI/Gateway path.

clawsweeper · 2026-06-26T01:29:48Z

Codex review: needs maintainer review before merge. Reviewed June 26, 2026, 10:31 PM ET / 02:31 UTC.

Summary
The PR threads agent identity through Gateway cron calls, scopes cron RPC operations to the calling agent, wires managed ACPX openclaw-tools MCP sessions with a session key, and adds restart/update proof coverage.

PR surface: Source +916, Tests +1471, Config +1, Other +328. Total +2716 across 59 files.

Reproducibility: yes. at source level: current main creates the MCP cron tool without a session key, sends agent Gateway cron calls without agent identity, and cron handlers mutate by job id without caller scope. I did not run a local failing scenario in this read-only pass.

Review metrics: 3 noteworthy metrics.

Gateway Connect Auth Surface: 1 optional auth field added. agentRuntimeIdentityToken changes client/server compatibility and mixed-version failure behavior before merge.
Managed MCP Env Surface: 1 required managed env value added. OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY changes startup expectations for the managed openclaw-tools MCP server path.
Scoped Cron RPC Surface: 7 methods scoped. list, get, add, update, remove, run, and runs now depend on trusted caller identity for agent-tool calls.

Stored data model
Persistent data-model change detected: migration/backfill/repair: test/scripts/docker-e2e-plan.test.ts, migration/backfill/repair: test/scripts/upgrade-survivor-assertions.test.ts, migration/backfill/repair: test/scripts/upgrade-survivor-config-recipe.test.ts, serialized state: src/gateway/agent-runtime-identity-token.test.ts, serialized state: src/gateway/agent-runtime-identity-token.ts, serialized state: test/scripts/upgrade-survivor-config-recipe.test.ts, and 12 more. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: partial_overlap
Canonical: #71712
Summary: This PR is a scoped mitigation for the broader agent-facing scheduling authority RFC, not a complete implementation of playbooks, quotas, expiry, provenance receipts, or execution lineage.

Members:

canonical: [RFC] Agent-facing scheduling API with non-forgeable provenance #71712 - The open RFC tracks the broader scheduling authority and provenance design that this PR only partially mitigates.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

[P1] The new Gateway connect auth field intentionally fails closed against older Gateways, so mixed-version local backend cron calls can stop until the Gateway is restarted or updated.
[P1] OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY becomes required for the managed openclaw-tools MCP server path; managed ACPX injects it, but direct unmanaged invocation needs an explicit support or documentation decision.
[P1] The PR changes a model-mediated cron authorization boundary, where mistakes could expose another agent's jobs, hide same-agent jobs, or deny valid operations.
[P1] The broader scheduling-authority RFC remains open for playbooks, quotas, expiry policy, provenance receipts, and execution lineage, so this PR should be treated as an interim mitigation.

Maintainer options:

Accept The Scoped Gateway Identity Contract (recommended)
Maintainers can approve the internal auth field, fail-closed mixed-version behavior, and server-side cron scope as the intended interim security boundary.
Document Or Preserve Unmanaged MCP Behavior
Before merge, maintainers can document that direct openclaw-tools MCP invocation requires the session-key env or preserve an explicit non-agent mode.
Pause For The Scheduling RFC
If this mitigation should wait for playbooks, quotas, provenance receipts, and execution-lineage decisions, pause this PR and route the decision through the broader scheduling RFC.

Next step before merge

[P1] Maintainer review is needed to accept the new Gateway auth, managed MCP env, and fail-closed upgrade contracts; there is no narrow automation repair to queue.

Security
Cleared: No concrete supply-chain, workflow, dependency-source, or unrelated secret-handling regression was found; the intended authorization-boundary change remains explicit merge risk.

Review details

Best possible solution:

Land this scoped mitigation only after maintainers accept the internal Gateway auth field, managed MCP session-key env contract, and fail-closed mixed-version behavior while keeping the broader scheduling RFC open.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level: current main creates the MCP cron tool without a session key, sends agent Gateway cron calls without agent identity, and cron handlers mutate by job id without caller scope. I did not run a local failing scenario in this read-only pass.

Is this the best way to solve the issue?

Mostly yes: the mitigation is enforced at tool assembly, the local Gateway client, Gateway handshake, ACPX managed bridge, and cron handlers. The remaining question is maintainer acceptance of the compatibility and security-boundary contracts, not a narrow code defect.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 552ec2b49d4a.

Label changes

Label justifications:

P1: The PR changes an agent cron authorization boundary that can affect real model-mediated scheduling workflows.
merge-risk: 🚨 compatibility: The diff adds Gateway connect auth and managed MCP startup expectations that mixed-version or unmanaged setups may notice.
merge-risk: 🚨 security-boundary: The diff changes server-side authorization for agent cron jobs, where mistakes can expose, hide, or mutate another agent's scheduled jobs.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live terminal output, Testbox run IDs, broad changed gates, upgrade-survivor proof, packaged Docker cron CLI proof, and a packaged cron lifecycle soak for the changed cron/Gateway/MCP behavior.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live terminal output, Testbox run IDs, broad changed gates, upgrade-survivor proof, packaged Docker cron CLI proof, and a packaged cron lifecycle soak for the changed cron/Gateway/MCP behavior.

Evidence reviewed

PR surface:

Source +916, Tests +1471, Config +1, Other +328. Total +2716 across 59 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	25	1305	389	+916
Tests	21	1548	77	+1471
Docs	0	0	0	0
Config	1	1	0	+1
Generated	0	0	0	0
Other	12	347	19	+328
Total	59	3201	485	+2716

What I checked:

Repository policy applied: Root and scoped AGENTS.md guidance was read; auth/session state, MCP/plugin seams, fail-closed behavior, setup/startup checks, and compatibility/default changes are treated as merge-risk surfaces. (AGENTS.md:31, 552ec2b49d4a)
Current main lacks MCP caller identity: Current main creates the openclaw-tools MCP cron tool without an agent session key, so that path cannot identify the calling agent. (src/mcp/openclaw-tools-serve.ts:14, 552ec2b49d4a)
Current main agent Gateway calls are unscoped: Current main agent Gateway calls pass approval/device metadata but no agent runtime identity for cron RPCs. (src/agents/tools/gateway.ts:269, 552ec2b49d4a)
Current main cron handlers trust job ids and caller-supplied filters: Current main cron list/get/add/update paths do not derive a trusted caller scope from the connected client before listing, creating, reading, or mutating jobs. (src/gateway/server-methods/cron.ts:378, 552ec2b49d4a)
PR adds local agent runtime identity token: PR head mints and verifies a purpose-scoped HMAC token carrying agentId and sessionKey from local socket credentials. (src/gateway/agent-runtime-identity-token.ts:82, b9b90fef1202)
PR accepts identity only from local backend clients: The Gateway handshake rejects agent runtime identity tokens from remote or non-backend clients and stores verified identity on the connected client. (src/gateway/server/ws-connection/message-handler.ts:1869, b9b90fef1202)

Likely related people:

vincentkoc: Recent commits touched Gateway cron validation, Gateway client behavior, ACPX runtime, and cron handler surfaces adjacent to this PR. (role: recent area contributor; confidence: high; commits: f236217d5b1f, aa396007937b, 300b09b33ff8; files: src/gateway/server-methods/cron.ts, src/agents/tools/cron-tool.ts, extensions/acpx/src/runtime.ts)
steipete: History shows the original OpenClaw tools ACPX exposure plus ACPX process-state and MCP server refactors near the changed MCP bridge surface. (role: feature-history and adjacent safety contributor; confidence: high; commits: c2ac1e3ef4e0, 61ab68f5c904, 05c3325b0acc; files: src/mcp/openclaw-tools-serve.ts, extensions/acpx/src/runtime.ts)
obviyus: Recent cron-tool policy work around default toolsAllow markers is close to the model-facing cron tool behavior this PR changes. (role: recent cron tool policy contributor; confidence: medium; commits: 17066f2d7c01; files: src/agents/tools/cron-tool.ts)
yu-xin-c: The compact cron list response work is adjacent to the list scoping and compact-list fallback paths changed here. (role: cron list feature contributor; confidence: medium; commits: ca1a53aca4ba; files: src/gateway/server-methods/cron.ts, src/agents/tools/cron-tool.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

…files + finish conflict cleanup Phase-2 silent-keep-ours review (merge=ours discards upstream's changes with no conflict). 3 parallel reviewers triaged the 17 guarded prod files upstream touched; grafted the 14 with real value, several of which fixed features the partial merge left BROKEN (backend/consumers merged, producer discarded): - agent-tools.before-tool-call.ts: unify the before_tool_call marker Symbols onto the net-new before-tool-call-metadata.js (the partial merge created a split-brain where 5 modules read a different Symbol set → marker copy silently no-op'd). - message-handler.ts + openclaw-tools.ts: restore the openclaw#96883 agent-runtime cron scoping (verify agentRuntimeIdentity token / establish the ambient identity); consumers had merged but both producers were discarded → feature inert. - skills.ts + agents-models-skills schema + app-render/app/app-view-state: wire the ClawHub risk-acknowledge install end-to-end (backend + controller + view merged; the gateway handler, schema gate, and the UI onClawHubInstall args were missing → acknowledge button re-failed). - edit/edit-diff/write/apply-patch: adopt upstream's no-op edit/write/patch = terminal result (the upstream tests had merged and were red; now green). - bash-tools.exec-runtime.ts: finalize the sandbox exec on spawn-failure paths (was leaking; only clean exit finalized). - google-shared.ts: only promote toolCall→toolUse on stopReason===stop (a MAX_TOKENS-truncated partial call must not become an executable turn). - subagent-registry.ts: let wakeOnDescendantSettle orchestrators reach the wake path past the yield gate. KEEP (no graft): bash-tools.exec.ts (fork superseded the deferral machinery), sandbox.ts (already converged). Also finished the merge conflict cleanup: drop the unused upstream assistant- message-update helpers from agent-loop.ts (fork uses only removeNonExecutableToolCalls) and the unused assignTransportErrorDetails import. tsgo:core/extensions at the pre-merge baseline (error-set diff); missing-export scan clean; edit/write/apply-patch + exec-runtime + gateway-caller-identity tests green. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* Scope agent cron operations to caller * Scope OpenClaw tools MCP cron by session * Address cron scope review feedback * Preserve unscoped cron update retargeting * Move cron caller identity into gateway context * Clarify Gateway restart guidance * Add cron caller identity regression proof

The Gateway caller-identity pattern established in openclaw/openclaw#96883 is the seam this RFC's session-scoped attribution builds on. Co-Authored-By: Claude Opus 4 <[email protected]>

Scope agent cron operations to caller

71a6ee8

openclaw-barnacle Bot added app: web-ui App: web-ui gateway Gateway runtime agents Agent runtime and tooling size: XL maintainer Maintainer-authored PR labels Jun 26, 2026

Scope OpenClaw tools MCP cron by session

6ff3a87

openclaw-barnacle Bot added the extensions: acpx label Jun 26, 2026

joshavant added 2 commits June 25, 2026 21:47

Address cron scope review feedback

1f60f84

Preserve unscoped cron update retargeting

ed53735

openclaw-barnacle Bot added the scripts Repository scripts label Jun 26, 2026

clawsweeper Bot mentioned this pull request Jun 27, 2026

[Feature]: Add before_persistence_write hook for durable state changes #48509

Open

clawsweeper Bot mentioned this pull request Jul 13, 2026

fix: keep command cron jobs operator-scoped [AI] #106057

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Scope agent cron operations to the calling agent#96883

Scope agent cron operations to the calling agent#96883
joshavant merged 7 commits into
mainfrom
fix/agent-cron-scope

joshavant commented Jun 26, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

joshavant commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

joshavant commented Jun 26, 2026 •

edited

Loading

clawsweeper Bot commented Jun 26, 2026 •

edited

Loading