{"_id":"@aiwayds/pi-kimi-cron","name":"@aiwayds/pi-kimi-cron","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aiwayds/pi-kimi-cron","version":"1.0.0","description":"Cron scheduling extension for Pi coding agent, inspired by Kimi Code's cron feature","keywords":["pi","pi-extension","cron","scheduling","kimi-code"],"type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"clean":"rm -rf dist","build":"tsc -p tsconfig.json","test":"node --test 'tests/**/*.test.ts'","prepublishOnly":"npm run clean && npm run build"},"peerDependencies":{"@earendil-works/pi-coding-agent":">=0.82.0","typebox":"^1.1.38"},"devDependencies":{"@earendil-works/pi-coding-agent":"^0.82.0","@types/node":"^24.12.4","typebox":"^1.1.38","typescript":"^5.9.3"},"author":{"name":"fliu56"},"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/fan56/pi-kimi-cron.git"},"engines":{"node":">=22.19.0"},"pi":{"extensions":["./index.ts"]},"gitHead":"2f69684a956a5a905235dffcf3eeade7e4cc6997","_id":"@aiwayds/pi-kimi-cron@1.0.0","bugs":{"url":"https://github.com/fan56/pi-kimi-cron/issues"},"homepage":"https://github.com/fan56/pi-kimi-cron#readme","_nodeVersion":"26.4.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-NeS0bLYIu/7DmTbRbZGs7sYJvzKU3JJmMLjekFBH94A7DUOOr1twPaAUZ8BOpqozKcl03KjShCu78FwKC+EVcA==","shasum":"095779e54de654cf08d8a58789beb85e77d63f9b","tarball":"https://registry.npmjs.org/@aiwayds/pi-kimi-cron/-/pi-kimi-cron-1.0.0.tgz","fileCount":8,"unpackedSize":153523,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCBjQbTkXYgsUjYXJ4MAL+ea6EUzDfYUhlajM9mKWHOQgIhAPc5MpZJjXjdysIPJRiLOUvZWy+gIrRnhCUgnZeUPPff"}]},"_npmUser":{"name":"aiwayds","email":"aiway.ds@qq.com"},"directories":{},"maintainers":[{"name":"aiwayds","email":"aiway.ds@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-kimi-cron_1.0.0_1785649755352_0.5654257980781565"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-02T05:49:15.179Z","1.0.0":"2026-08-02T05:49:15.524Z","modified":"2026-08-02T05:49:15.684Z"},"maintainers":[{"name":"aiwayds","email":"aiway.ds@qq.com"}],"description":"Cron scheduling extension for Pi coding agent, inspired by Kimi Code's cron feature","homepage":"https://github.com/fan56/pi-kimi-cron#readme","keywords":["pi","pi-extension","cron","scheduling","kimi-code"],"repository":{"type":"git","url":"git+https://github.com/fan56/pi-kimi-cron.git"},"author":{"name":"fliu56"},"bugs":{"url":"https://github.com/fan56/pi-kimi-cron/issues"},"license":"MIT","readme":"# @aiwayds/pi-kimi-cron\n\nCron scheduling extension for the [Pi](https://github.com/earendil-works/pi) coding agent. Schedule prompts to be injected into the conversation on a recurring schedule using standard 5-field cron expressions.\n\n## Acknowledgments\n\nThis extension is inspired by and based on the cron scheduling feature from\n[Kimi Code](https://github.com/MoonshotAI/kimi-code) by MoonshotAI.\n\nWe thank the Kimi Code team for open-sourcing their implementation, which made\nthis Pi adaptation possible. The original architecture, including the tick-loop\nscheduler, deterministic jitter, and prompt injection mechanism, was ported from\nKimi Code's `packages/agent-core/src/tools/cron/` module.\n\n## Usage\n\n### For Agents (Primary Use Case)\n\nThis extension is designed for **agent-first** usage. The LLM calls the tools directly:\n\n- `CronCreate` — Schedule a task with a cron expression\n- `CronDelete` — Remove a scheduled task\n- `CronList` — List all scheduled tasks\n\n### For Humans (Natural Language)\n\nHuman users interact via **natural language**. The LLM translates your intent into\ncron expressions:\n\n- \"每周一早上9点生成周报\" → `CronCreate({cron: \"0 9 * * 1\", prompt: \"生成周报\"})`\n- \"every day at 6pm check build status\" → `CronCreate({cron: \"0 18 * * *\", prompt: \"check build status\"})`\n- \"list my scheduled tasks\" → `CronList({})`\n\n## Installation\n\n```bash\nnpm install @aiwayds/pi-kimi-cron\n```\n\nThen register the extension with Pi (add to your Pi extension configuration):\n\n```ts\nimport cronSchedulerExtension from '@aiwayds/pi-kimi-cron';\n\nexport default cronSchedulerExtension;\n```\n\n`@earendil-works/pi-coding-agent` and `typebox` are peer dependencies — Pi provides both at runtime.\n\n## Tools\n\n| Tool | Description |\n| ------ | ------------- |\n| `CronCreate` | Create a scheduled task with a cron expression and prompt |\n| `CronDelete` | Delete a task by its 8-char hex id |\n| `CronList` | List all tasks with next fire times |\n\n### CronCreate parameters\n\n| Parameter | Type | Description |\n| ----------- | ------ | ------------- |\n| `cron` | string | 5-field cron expression, e.g. `\"*/5 * * * *\"` |\n| `prompt` | string | Prompt text injected when the task fires |\n| `recurring` | boolean (optional) | Repeat after firing (default `true`); `false` = one-shot |\n\n## Cron Syntax\n\nStandard 5-field cron: `minute hour day-of-month month day-of-week`\n\n```\n*/5 * * * *     every 5 minutes\n0 * * * *       every hour\n0 9 * * 1-5     weekdays at 9:00 AM\n0 18 * * *      daily at 6:00 PM\n0 0 1 * *       monthly on the 1st\n```\n\nSupported field syntax: `*`, lists (`1,3,5`), ranges (`1-5`), steps (`*/2`), and month/day names (`jan`, `mon`).\n\n## Examples\n\n```\nCronCreate({ cron: \"*/5 * * * *\", prompt: \"check the build status\" })\nCronCreate({ cron: \"0 9 * * 1\", prompt: \"生成周报\" })\nCronCreate({ cron: \"0 0 1 * *\", prompt: \"summarize last month\", recurring: false })\nCronList({})\nCronDelete({ id: \"a1b2c3d4\" })\n```\n\n## Configuration (Environment Variables)\n\n| Variable | Description |\n| ---------- | ------------- |\n| `PI_CRON_DEBUG=1` | Enable verbose scheduler logging to stderr |\n| `PI_CRON_NO_JITTER=1` | Disable deterministic per-task jitter |\n| `PI_CRON_CLOCK=fixed` | Use fixed clock (testing, requires `PI_CRON_CLOCK_FIXED_MS`) |\n| `PI_CRON_CLOCK=offset` | Use offset clock (testing, requires `PI_CRON_CLOCK_OFFSET_MS`) |\n\n## Persistence\n\nTasks are stored as JSON files at:\n\n```\n~/.pi/agent/cron/<session-id>/<8-hex-id>.json\n```\n\n## Limitations\n\n**Tasks only fire while Pi is running.** The scheduler uses an in-process `setInterval` tick loop (15s interval). When Pi exits, no tasks fire. On restart, tasks are rehydrated from disk and resume from their last fire time — missed fires are coalesced, not replayed.\n\n## Architecture\n\n```\nsrc/\n  index.ts               Extension entry point (tools + lifecycle hooks)\n  types.ts               CronTask interface\n  cron-expr.ts           5-field cron parser + next-fire calculator\n  jitter.ts              Deterministic per-task jitter\n  cron-fire-xml.ts       XML envelope renderer for fire injection\n  session-store.ts       In-memory task map\n  clock.ts               Clock sources (system / fixed / offset)\n  per-id-json-store.ts   Generic per-id JSON file store with atomic writes\n  persist.ts             Cron task persistence wrapper\n  scheduler.ts           Tick-loop engine (15s interval)\n```\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md","_rev":"1-282535dbf8e576f7c49cf4b418a92a80"}