@mono-agent/cron-adapter 0.13.0 → 0.14.0

package/README.md

@@ -1,8 +1,18 @@
 # @mono-agent/cron-adapter
 
+Schedule recurring agent work from host config, Markdown job files, or a custom
+programmatic host without moving runtime or delivery ownership into the adapter.
+
 ## Category
 
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
 Category: `communication`
+Tier: `core`
+Catalog responsibility: Invokes agent responders from cron schedules with configurable skip, queue, or replace overlap policies.
+
+<!-- package-metadata:end -->
 
 ## Responsibility
 
@@ -10,12 +20,58 @@ Cron-based scheduled invocation adapter for agent hosts. It parses configured cr
 
 ## Install / Usage
 
+### Config-first host
+
+`@mono-agent/agent-app` already depends on this package. A normal agent folder
+does not install the adapter separately; declare jobs in `mono-agent.config.json`
+and let the host load and start them:
+
+```json
+{
+  "cron": {
+    "jobs": [
+      {
+        "id": "daily-check",
+        "enabled": true,
+        "expression": "0 9 * * *",
+        "timezone": "UTC",
+        "prompt": "Run the daily check.",
+        "conversationId": "cron:daily-check"
+      }
+    ]
+  }
+}
+```
+
 ```bash
-pnpm --filter @mono-agent/cron-adapter run build
+mono-agent validate
+mono-agent start --foreground
 ```
 
+The config-first host pins every configured job to `overlap: "skip"`: a tick
+that overlaps an active run of the same job is skipped. There is no cron config
+field for queueing or replacing active runs.
+
+### Programmatic use
+
+Install the adapter directly only when building a custom host:
+
+```bash
+pnpm add @mono-agent/cron-adapter
+```
+
+<!-- doc-test:typescript -->
 ```ts
-import { startCronAdapter } from "@mono-agent/cron-adapter";
+import {
+  startCronAdapter,
+  type CronAdapterOptions,
+} from "@mono-agent/cron-adapter";
+
+const responder: CronAdapterOptions["responder"] = {
+  async respond(request) {
+    return { text: `Scheduled request received: ${request.text}` };
+  },
+};
 
 const cron = startCronAdapter({
   responder,
@@ -29,6 +85,8 @@ const cron = startCronAdapter({
     },
   ],
 });
+
+process.once("SIGINT", () => cron.stop());
 ```
 
 Only future ticks after startup are scheduled. Direct programmatic `startCronAdapter` callers can choose `overlap: "skip" | "queue" | "replace"` (default `"skip"`). In queue mode, `maxQueueDepth` is a soft overflow threshold: the default `overflow: "preserve"` warns but keeps every firing and can grow past it. Select `overflow: "coalesce"` or `"drop-oldest"` to bound pending memory.
@@ -70,8 +128,53 @@ Summarize yesterday across my channels and post a short digest.
 - The folder is resolved against the host working directory from `cron.dir` / `MONO_AGENT_CRON_DIR` (default `cron/`). A missing folder is not an error.
 - Folder jobs are merged with config jobs; a duplicate `id` across sources is a hard error.
 
+The single-job environment form uses the fixed id `default`; it supports
+`MONO_AGENT_CRON_ENABLED`, `MONO_AGENT_CRON_EXPRESSION`,
+`MONO_AGENT_CRON_TIMEZONE`, `MONO_AGENT_CRON_PROMPT`,
+`MONO_AGENT_CRON_CONVERSATION_ID`, notification fields, `MODEL`, and `EFFORT`.
+There is no `MONO_AGENT_CRON_ID`. Use `cron.jobs[]`,
+`MONO_AGENT_CRON_JOBS_JSON`, or a Markdown filename/frontmatter id when a stable
+custom job id is required.
+
+## Architecture
+
+### Data flow
+
+The request lifecycle is:
+
+1. `config.ts` loads inline, environment, and directory-backed jobs, rejects
+   duplicate ids, and projects enabled entries through `toCronJobs`.
+2. `cron-expression.ts` validates the five-field expression and resolves the
+   next timezone-aware firing; hashed fields use the job id as their seed.
+3. `scheduler.ts` admits the firing under the selected overlap policy, creates
+   an abortable `AgentRequestBase`, and invokes the host-owned responder.
+4. The scheduler emits a typed `CronJobResult`; the host decides whether to log,
+   persist, or deliver that result. `stop()` clears timers, queues, and active
+   runs.
+
+### Package structure
+
+| Source module | Responsibility |
+| --- | --- |
+| [`config.ts`](https://github.com/robertsreberski/mono-agent/blob/main/packages/cron-adapter/src/config.ts) | Config/env layering, directory merge, redaction, and enabled-job projection. |
+| [`jobs-dir.ts`](https://github.com/robertsreberski/mono-agent/blob/main/packages/cron-adapter/src/jobs-dir.ts) | Markdown frontmatter parsing and deterministic folder loading. |
+| [`cron-expression.ts`](https://github.com/robertsreberski/mono-agent/blob/main/packages/cron-adapter/src/cron-expression.ts) | Shared expression and timezone validation. |
+| [`scheduler.ts`](https://github.com/robertsreberski/mono-agent/blob/main/packages/cron-adapter/src/scheduler.ts) | Timers, overlap/overflow policy, cancellation, watchdogs, and results. |
+| [`index.ts`](https://github.com/robertsreberski/mono-agent/blob/main/packages/cron-adapter/src/index.ts) | Supported public package surface. |
+
 ## Public API
 
+### Start here
+
+| API | Use it for |
+| --- | --- |
+| `loadCronAdapterConfig` | Load and validate config, env, and optional `cron/*.md` jobs. |
+| `toCronJobs` | Drop disabled config entries and produce scheduler-ready jobs. |
+| `startCronAdapter` | Start future scheduling in a custom host and obtain `stop()`. |
+| `validateCronExpression` | Validate user input with the scheduler's parser. |
+| `loadCronJobsFromDirectory` / `parseCronJobMarkdown` | Build custom directory-backed authoring flows. |
+| `CronJobResult` | Handle every terminal and overlap/queue result explicitly. |
+
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
@@ -117,8 +220,17 @@ This adapter depends on `cron-parser` plus shared `@mono-agent/agent-contracts`
 
 It does not build prompts, run models, persist missed runs or pending firings, catch up after restart, expose UI, or define core agent settings. Its programmatic overlap queue is in-memory only; durable scheduling state can be added later by a host-level persistence package.
 
+## Related Documentation
+
+- [Cron channel guide](https://mono-agent-docs.vercel.app/channels/cron/)
+- [Cron digest and proactive-notify playbook](https://mono-agent-docs.vercel.app/playbooks/cron-digest-proactive-notify/)
+- [Sessions and concurrency](https://mono-agent-docs.vercel.app/runtime/sessions-concurrency/)
+- [Environment-variable precedence](https://mono-agent-docs.vercel.app/config/env-vars/)
+
 ## Verification
 
+Run the package-local build, typecheck, and behavior tests:
+
 ```bash
 pnpm --filter @mono-agent/cron-adapter run build
 pnpm --filter @mono-agent/cron-adapter run typecheck

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/cron-adapter",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Cron-based scheduled invocation adapter for agent responders.",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -26,7 +26,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mono-agent/agent-contracts": "0.13.0",
+    "@mono-agent/agent-contracts": "0.14.0",
     "cron-parser": "^5.5.0"
   },
   "publishConfig": {