docs: document scheduled task tools - #168
Conversation
|
| Name | Type |
|---|---|
| @moonshot-ai/agent-core | Minor |
| @moonshot-ai/kimi-code | Minor |
| @moonshot-ai/migration-legacy | Patch |
Click here to learn what changesets are, and how to add one.
Click here if you're a maintainer who wants to add a changeset to this PR
commit: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e47de3f74f
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| To avoid synchronized fleet-wide fires on round minute marks, the scheduler applies a deterministic per-task jitter: recurring tasks shift forward by up to `min(10% of the period, 15 minutes)`; one-shot tasks landing on `:00` or `:30` shift earlier by up to 90 seconds. If the scheduler sleeps past several ideal fire times (laptop closed, long-running turn, etc.), it delivers only one fire when it wakes up — the prompt is wrapped in a `<cron-fire>` envelope carrying `coalescedCount` so the agent reacts to "I missed N checks; only the latest state matters" instead of running the prompt N times. Recurring tasks older than seven days fire one final time with `stale="true"` on the envelope and the system then auto-deletes the task; to keep the schedule running, just call `CronCreate` again. One-shot tasks are never marked stale. | ||
|
|
||
| **`CronList`** is read-only and takes no parameters. It returns one record per live task, each carrying `id`, `cron`, `humanSchedule`, the JSON-encoded `prompt` (truncated to ~200 UTF-8 bytes for context-window safety), `nextFireAt` (the post-jitter ISO timestamp the scheduler will actually fire on), `recurring`, `ageDays`, and `stale`. Records are separated by a line containing `---` in scheduling order. The empty case returns `cron_jobs: 0\nNo cron jobs scheduled.`. Use this to recall pending tasks after a context compaction, or to look up an `id` for `CronDelete`. |
There was a problem hiding this comment.
When a session has multiple cron jobs added out of chronological order, this says CronList records are in scheduling order, so users/models may treat the first record as the next due task. The implementation does not sort by nextFireAt: CronList maps this.manager.store.list(), and SessionCronStore.list() returns the backing Map in insertion order, so this should not promise scheduling order (the zh mirror has the same claim).
Useful? React with 👍 / 👎.
| | `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | Override the plugin marketplace JSON loaded by `/plugins`; useful for dev loopback servers, staging CDN files, or alternate marketplace directories | `https://cdn.kimi.com/kimi-code/plugins/marketplace.json`; also accepts `http://`, `file://` URLs, and local paths | | ||
| | `KIMI_SHELL_PATH` | Override the absolute path to Git Bash (`bash.exe`) on Windows; only needed when auto-detection fails on Windows | None | | ||
| | `KIMI_MODEL_MAX_COMPLETION_TOKENS` | Explicit hard cap for `max_completion_tokens` in a single-step LLM request. When unset, Kimi Code uses the safe remaining context window for models with a known context size. Set to `0` or a negative value to disable clamping entirely. **Currently effective only for providers of type `kimi`**; for Anthropic and other providers, use `[models.<alias>].max_output_size` instead (see [Config files](./config-files.md#models)) | Unset: computed from remaining context; unknown context falls back to `loop_control.reserved_context_size`, then 32000 | | ||
| | `KIMI_DISABLE_CRON` | Disable the scheduled-task tools entirely. Set to `1` to make `CronCreate` reject new schedules and short-circuit the scheduler's tick loop; existing tasks remain on disk but never fire while the variable is set. See [Scheduled tasks](../reference/tools.md#scheduled-tasks) | `1` to disable; unset by default | |
There was a problem hiding this comment.
When KIMI_DISABLE_CRON=1 is set, it only makes CronCreate reject new schedules and makes the scheduler tick return early; CronList remains default-approved and CronDelete has no kill-switch branch, so users can still inspect or delete persisted jobs. Saying this disables the scheduled-task tools entirely is misleading for operators who expect a complete tool block; please describe it as disabling creation/firing, or explicitly note that list/delete remain available.
Useful? React with 👍 / 👎.
| - `agents/agent-0/`, `agents/agent-1/`, etc.: subagent instance directories, each with its own `wire.jsonl`. Subagent ids are generated by a per-session incrementing counter (`agent-` followed by an integer starting from 0). | ||
| - `logs/kimi-code.log`: the diagnostic log for this session. It only appears after a recorded diagnostic event; an ordinary conversation may not create this file. | ||
| - `tasks/`: background task persistence directory. Each task stores its metadata (status, pid, exit code, etc.) in `tasks/<task_id>.json`, with stdout and stderr written to `tasks/<task_id>/output.log`. Task ids use a `bash-` or `agent-` prefix followed by 8 random alphanumeric characters (for example, `bash-a1b2c3d4`). | ||
| - `cron/`: scheduled task persistence directory. Each task scheduled through `CronCreate` is mirrored to `cron/<id>.json`, where `<id>` is 8 lowercase hex characters. `kimi resume` rehydrates these tasks back into the in-memory scheduler. Tasks remain scoped to the resumed session id and do not bleed into new sessions. See [Scheduled tasks](../reference/tools.md#scheduled-tasks) for the tool surface. |
There was a problem hiding this comment.
When a user forks a session that has live cron jobs, the fork gets a new session id but SessionStore.fork() copies the entire source session directory recursively, including cron/<id>.json, and Agent.resume() later calls cron.loadFromDisk(). That means those tasks do carry into the fork and can fire there too, so this blanket statement about not bleeding into new sessions understates a duplicate-reminder scenario; either exclude cron files during fork or document the fork behavior.
Useful? React with 👍 / 👎.
1 participant
Related Issue
There is no linked issue. PR #157 (
feat(agent-core): add session-scoped cron tools with persistence) introducedCronCreate/CronList/CronDeleteas built-in tools with a pending.changeset/cron-tools.md, but the user-facing docs had not been updated yet.Problem
After #157 landed, users browsing the docs site cannot discover the scheduled task feature. The built-in tools reference lists every other tool but is missing the three cron tools;
KIMI_DISABLE_CRONis not in the environment variables table; the session-data layout does not mention<sessionDir>/cron/<id>.jsoneven though tasks are persisted there; and there is no use-case example showing how a user phrases a request for a reminder or recurring task.What changed
Bilingual (en + zh) docs additions for the cron tools, plus a small wording adjustment on the pending changeset:
docs/en/reference/tools.md+docs/zh/reference/tools.md: new "Scheduled tasks" section after "Background tasks", covering the three tools' parameters, approval requirements, Plan-mode blocking, jitter, coalesce semantics, 7-day stale auto-expiration, and the session-scoped lifecycle.docs/en/configuration/env-vars.md+docs/zh/configuration/env-vars.md: addedKIMI_DISABLE_CRONto the Runtime switches table.docs/en/configuration/data-locations.md+docs/zh/configuration/data-locations.md: addedcron/<id>.jsonto the session directory tree and described howkimi resumerehydrates the scheduler.docs/en/guides/use-cases.md+docs/zh/guides/use-cases.md: new "Scheduled tasks and reminders" section with natural-language prompt examples (one-shot reminders, recurring schedules, delayed callbacks) so the feature is discoverable from the use-case index..changeset/cron-tools.md: expanded the release-note entry from a single implementation-flavored sentence to a user-facing description of what the feature lets users do.Docs-only, so no new changeset is needed per
gen-changesets.docs/*/release-notes/changelog.mdis not edited — it is regenerated by the post-releasesync-changelogflow. Locale anchors render correctly (#scheduled-tasks/#定时任务,#runtime-switches/#运行时开关);pnpm --filter docs run buildpasses locally.Checklist
gen-changesetsskill, or this PR needs no changeset.gen-docsskill, or this PR needs no doc update.