RFC-001 — Scheduler: agentic cron for the Koder Stack

*uthor:*Koder Engineering *ate:*20260429 *tatus:*Accepted *odule:*servicesfoundationscheduler *rigin:*koderstack ticket #033 (RFC019), OpenClaw analysis 20260429 *enamed from:*RFC-019 (namespaced convention)

1. Summary

A firstparty scheduling service that runs agent prompts on a cronstyle recurrence (or one-shot at a future time), executes them in engines/sandbox (RFC-018), and dispatches results to a chosen output channel via Kode Relay.

Replaces the ad-hoc "I'll do it manually every Monday" pattern with a managed surface, the same way Claude Code's /schedule skill does for its own session — but clusterwide, multitenant, and integrated with Koder ID + Koder Hub auth.

2. Problem

Three classes of recurring agentic work exist in the Stack today and all use ad-hoc mechanisms:

1. *ps sweeps*— "every Monday, audit X, open tickets for drift"
2. *ealth probes*— "every 5 min, hit endpoint Y, alert if bad"
3. *neshot followups*— "in 2 weeks, evaluate the experiment we

   just shipped"

Today: Linux cron + bespoke shell scripts, or Claude Code's /schedule (singleuser, sessionscoped). Neither handles multi-tenancy, audit, or integration with the rest of the Stack.

3. Goals

• Job model: {prompt, cron, agent, sandbox, output_channel, retries}.
• Storage on kdb-next (jobs + execution history).
• Worker pool in a dedicated LXC, simple HA (active/standby leader

  election via existing kdb-next primitives).

• Dispatch via Kode Relay (#024) for output delivery to chat channels,

  SlackTelegramemail, etc.

• CLI kjob for human management; HTTP API for programmatic.

4. Non-Goals

• General-purpose distributed task queue (Celery, Sidekiq replacement).

  Scheduler is for agentic prompts specifically.

• Workflow orchestration (Airflow, Temporal). Single jobs only — chains

  belong to the agent's own logic.

5. Job Model

[job]
slug         = "weekly-stack-audit"
prompt       = "/k-housekeep"
agent        = "kode"               # or "kortex", "custom-agent-id"
schedule     = "0 9 * * MON"        # cron expr; or "@once 2026-05-15T10:00Z"
sandbox      = { backend = "docker", image = "koder-cli:latest" }
output       = { channel = "kode-chat:user-rpm32510" }
retries      = { max = 3, backoff = "exponential" }
timeout      = "30m"
enabled      = true

Stored in kdb-next table jobs, executions in job_runs.

6. Worker Pool

• Twonode LXC pair (`s.sched1, s.sched2`) with kdbnext leader

  election. Active node consumes the schedule queue; standby takes over on failure.

• Each job runs inside engines/sandbox with the declared backend.
• Stdoutstderr captured to `infraobserve/log with the jobrunid`

  for correlation.

7. Dispatch

When a job completes, the worker calls Kode Relay (engines/kode-relay, ticket #024) with:

POST /v1/dispatch
{
  "channel": "kode-chat:user-rpm32510",
  "message": {
    "title": "[weekly-stack-audit] completed",
    "body":  "<truncated stdout, link to full log>",
    "status": "success" | "failed" | "timeout"
  }
}

Relay handles channel-specific formatting (chat thread, Slack DM, Telegram message, email, webhook).

8. CLI

kjob create --slug NAME --prompt "..." --schedule "0 9 * * MON" --agent kode
kjob list
kjob inspect <slug>
kjob run-now <slug>
kjob disable <slug>
kjob enable <slug>
kjob delete <slug>
kjob runs <slug>          # execution history
kjob logs <run-id>

Per specs/binaries-and-cli/naming.kmd: binary kjob, install dir /opt/koder/scheduler/, D-Bus ID dev.koder.scheduler.

9. Scope of Change

• services/foundation/scheduler/ — new sector with worker, kdb tables,

  HTTP API, CLI

• kdb-next migrations: jobs, job_runs, job_dispatch_targets
• infra/linux/distro provisions s.sched-1 and s.sched-2 LXCs (per

  infrastructure spec — separate ticket)

• engines/kode-relay (RFC-002, ticket #024) consumed for dispatch —

  this scheduler RFC depends on Relay deployment going live

10. Execution Plan

11. Alternatives Considered

• *uild on Linux cron.*Rejected: no multi-tenancy, no audit, no

  prompt-aware semantics.

• *euse Claude Code's /schedule.*Rejected: single-user, session

  bound. The Stack-level scheduler runs without any user session attached.

• *se Temporal.io as the engine.*Rejected: Temporal optimizes for

  workflow orchestration with deterministic replay; agentic cron is a much simpler surface and Temporal would be massive overkill.

12. References

• engines/sandbox/docs/rfcs/RFC-001-sandbox-architecture.md — required
• Memory kode_relay — Relay status (CLI installed, deploy pending)
• Memory kode_naming — agent CLI is kode (consumed by --agent kode)
• policies/sdk-first.kmd — kjob is the canonical scheduling pattern