ref(scheduler): Extract scheduler plugin package (#429)

Move scheduler behavior into a dedicated `@sentry/junior-scheduler`
trusted plugin package. Apps now opt into scheduled tasks with
`schedulerPlugin()`, while core keeps the generic heartbeat, dispatch,
and plugin-state primitives.

**Plugin Boundary**

The scheduler package owns schedule tools, recurrence math, prompt
framing, durable scheduler state, and heartbeat dispatch.
`@sentry/junior` no longer registers scheduler hooks by default.

**Trusted Plugin API**

Expose plugin state locking, set-if-not-exists writes, and
`AgentPluginToolInputError` so scheduler can preserve its idempotency
and model-repairable validation behavior outside core.

**Release And Docs**

Add the scheduler package to workspace dependencies, release metadata,
CI packaging, docs, tests, and eval harness wiring.

---------

Co-authored-by: GPT-5 Codex <codex@openai.com>

Author: dcramer

.craft.yml

@@ -26,6 +26,9 @@ targets:
   - name: npm
     id: "@sentry/junior-notion"
     includeNames: /^sentry-junior-notion-\d.*\.tgz$/
+  - name: npm
+    id: "@sentry/junior-scheduler"
+    includeNames: /^sentry-junior-scheduler-\d.*\.tgz$/
   - name: npm
     id: "@sentry/junior-sentry"
     includeNames: /^sentry-junior-sentry-\d.*\.tgz$/

.github/workflows/ci.yml

@@ -58,6 +58,7 @@ jobs:
           pnpm --filter @sentry/junior-hex pack --pack-destination artifacts
           pnpm --filter @sentry/junior-linear pack --pack-destination artifacts
           pnpm --filter @sentry/junior-notion pack --pack-destination artifacts
+          pnpm --filter @sentry/junior-scheduler pack --pack-destination artifacts
           pnpm --filter @sentry/junior-sentry pack --pack-destination artifacts
           ls -la artifacts
 

CONTRIBUTING.md

@@ -67,6 +67,7 @@ This repo uses Craft for manual lockstep npm releases of:
 - `@sentry/junior-hex`
 - `@sentry/junior-linear`
 - `@sentry/junior-notion`
+- `@sentry/junior-scheduler`
 - `@sentry/junior-sentry`
 
 Run `pnpm release:check` before changing release package lists so `.craft.yml`, CI,

README.md

@@ -30,4 +30,5 @@ Start here:
 | `@sentry/junior-hex`           | Hex plugin package for data warehouse query workflows                        |
 | `@sentry/junior-linear`        | Linear plugin package for issue workflows                                    |
 | `@sentry/junior-notion`        | Notion plugin package for page search workflows                              |
+| `@sentry/junior-scheduler`     | Scheduler plugin package for scheduled Junior tasks                          |
 | `@sentry/junior-sentry`        | Sentry plugin package for issue workflows                                    |

apps/example/README.md

@@ -28,12 +28,12 @@ Copy `.env.example` and set:
 - `AI_VISION_MODEL` (optional, enables image-understanding; unset disables vision features)
 - `AI_WEB_SEARCH_MODEL` (optional, overrides the `webSearch` tool model; defaults to a search-tuned model)
 - `JUNIOR_SECRET` (required outside `pnpm dev`; the local wrapper supplies a dev-only secret when unset)
-- `JUNIOR_SCHEDULER_SECRET` or `CRON_SECRET` (optional for `pnpm dev`; the local wrapper supplies a dev-only secret when both are unset)
+- `JUNIOR_SCHEDULER_SECRET` or `CRON_SECRET` (optional for `pnpm dev`; the local wrapper supplies a dev-only heartbeat secret when both are unset)
 - `NOTION_TOKEN` (optional, enables the bundled Notion plugin)
 
 ## Wiring
 
 - `plugin-packages.ts` is the single source of truth for installed plugin packages in this app
 - `nitro.config.ts` passes that list to `juniorNitro()` so plugin content is copied into the build output
 - `server.ts` passes the same list to `createApp()` so local dev does not depend on Nitro's virtual config path for plugin discovery
-- root `pnpm dev` starts a local heartbeat loop that calls `/api/internal/heartbeat` every minute, matching the production cron pulse used by the built-in scheduler plugin; it also defaults `JUNIOR_BASE_URL` to the local server when unset so signed internal callbacks can recover scheduled dispatches
+- root `pnpm dev` starts a local heartbeat loop that calls `/api/internal/heartbeat` every minute, matching the production cron pulse used for trusted plugin heartbeats and stale dispatch recovery; it also defaults `JUNIOR_BASE_URL` to the local server when unset so signed internal callbacks can recover dispatched runs

package.json

@@ -22,7 +22,7 @@
     "test:watch": "pnpm --filter @sentry/junior test:watch",
     "evals": "pnpm --filter @sentry/junior-evals evals",
     "evals:record": "pnpm --filter @sentry/junior-evals evals:record",
-    "typecheck": "pnpm --filter @sentry/junior typecheck && pnpm --filter @sentry/junior-testing typecheck && pnpm --filter @sentry/junior-example typecheck",
+    "typecheck": "pnpm --filter @sentry/junior-plugin-api typecheck && pnpm --filter @sentry/junior-scheduler typecheck && pnpm --filter @sentry/junior typecheck && pnpm --filter @sentry/junior-testing typecheck && pnpm --filter @sentry/junior-example typecheck",
     "skills:check": "pnpm --filter @sentry/junior skills:check"
   },
   "simple-git-hooks": {

packages/docs/src/content/docs/contribute/releasing.md

@@ -19,6 +19,7 @@ Junior uses lockstep package releases for:
 - `@sentry/junior-hex`
 - `@sentry/junior-linear`
 - `@sentry/junior-notion`
+- `@sentry/junior-scheduler`
 - `@sentry/junior-sentry`
 
 ## Package release

packages/docs/src/content/docs/extend/index.md

@@ -54,12 +54,9 @@ my-junior-plugin/
 For reuse across apps or teams, package plugin manifests and any bundled skills as npm packages and install them next to `@sentry/junior`.
 
 ```bash
-pnpm add @sentry/junior @sentry/junior-agent-browser @sentry/junior-datadog @sentry/junior-github @sentry/junior-hex @sentry/junior-linear @sentry/junior-notion @sentry/junior-sentry
+pnpm add @sentry/junior @sentry/junior-agent-browser @sentry/junior-datadog @sentry/junior-github @sentry/junior-hex @sentry/junior-linear @sentry/junior-notion @sentry/junior-scheduler @sentry/junior-sentry
 ```
 
-Junior also includes the built-in [Scheduler Plugin](/extend/scheduler-plugin/)
-for reminders and recurring Slack tasks. It does not require a separate package.
-
 List the plugin packages in `juniorNitro` so they are bundled at build time and available at runtime:
 
 ```ts title="nitro.config.ts"
@@ -78,6 +75,7 @@ export default defineConfig({
           "@sentry/junior-hex",
           "@sentry/junior-linear",
           "@sentry/junior-notion",
+          "@sentry/junior-scheduler",
           "@sentry/junior-sentry",
         ],
       },
@@ -115,18 +113,20 @@ If you publish your own package with bundled skills, include both `plugin.yaml`
 
 Some packaged plugins also export trusted runtime hooks for deterministic
 behavior that cannot live in skill prose or `plugin.yaml`. For example, the
-GitHub plugin registers runtime code that installs a sandbox Git hook,
-configures global Git defaults, and injects commit attribution env before bash
-commands run.
+scheduler plugin registers schedule-management tools and heartbeat behavior, and
+the GitHub plugin installs a sandbox Git hook, configures global Git defaults,
+and injects commit attribution env before bash commands run.
 
 Trusted hooks are explicit app code:
 
 ```ts title="server.ts"
 import { createApp } from "@sentry/junior";
 import { githubPlugin } from "@sentry/junior-github";
+import { schedulerPlugin } from "@sentry/junior-scheduler";
 
 const app = await createApp({
   plugins: [
+    schedulerPlugin(),
     githubPlugin({
       botNameEnv: "GITHUB_APP_BOT_NAME",
       botEmailEnv: "GITHUB_APP_BOT_EMAIL",
@@ -331,7 +331,7 @@ Then install it in the host app:
 pnpm add @acme/junior-example
 ```
 
-The `juniorNitro({ plugins: { packages: [...] } })` module includes `app/**/*` and the declared plugin package content in the deployed function bundle. The plugin list is automatically available at runtime via `createApp()` for declarative manifest behavior. Plugins that export trusted runtime hooks, such as `@sentry/junior-github`, must also be registered from app code.
+The `juniorNitro({ plugins: { packages: [...] } })` module includes `app/**/*` and the declared plugin package content in the deployed function bundle. The plugin list is automatically available at runtime via `createApp()` for declarative manifest behavior. Plugins that export trusted runtime hooks, such as `@sentry/junior-scheduler` and `@sentry/junior-github`, must also be registered from app code.
 
 ## Validate extensions
 

packages/docs/src/content/docs/extend/scheduler-plugin.md

@@ -1,8 +1,8 @@
 ---
 title: Scheduler Plugin
-description: Enable and verify Junior's built-in scheduled task support.
+description: Enable and verify Junior's scheduled task support.
 type: tutorial
-summary: Configure the built-in scheduler plugin so Slack users can create reminders and recurring tasks.
+summary: Configure the scheduler plugin so Slack users can create reminders and recurring tasks.
 prerequisites:
   - /start-here/quickstart/
   - /start-here/slack-app-setup/
@@ -12,20 +12,39 @@ related:
   - /operate/reliability-runbooks/
 ---
 
-The scheduler plugin is built into `@sentry/junior`. It registers Slack tools for creating, listing, updating, deleting, and running scheduled tasks, then uses Junior's internal heartbeat to dispatch due work back to the configured Slack conversation.
+The scheduler plugin lives in `@sentry/junior-scheduler`. It registers Slack tools for creating, listing, updating, deleting, and running scheduled tasks, then uses Junior's internal heartbeat to dispatch due work back to the configured Slack conversation.
 
 ## Runtime setup
 
-No plugin package install is required. `createApp()` registers the trusted scheduler plugin automatically:
+Install the package next to `@sentry/junior`:
+
+```bash
+pnpm add @sentry/junior-scheduler
+```
+
+Register the trusted plugin in app code:
 
 ```ts title="server.ts"
 import { createApp } from "@sentry/junior";
+import { schedulerPlugin } from "@sentry/junior-scheduler";
 
-const app = await createApp();
+const app = await createApp({
+  plugins: [schedulerPlugin()],
+});
 
 export default app;
 ```
 
+List the package in `juniorNitro()` as well so Nitro bundles the manifest:
+
+```ts title="nitro.config.ts"
+juniorNitro({
+  plugins: {
+    packages: ["@sentry/junior-scheduler"],
+  },
+});
+```
+
 The scaffolded `vercel.json` includes the internal heartbeat route:
 
 ```json title="vercel.json"
@@ -47,14 +66,14 @@ If you manage routes manually, call the heartbeat route on a one-minute cadence:
 
 ## Configure environment variables
 
-Set one scheduler route secret:
+Set one heartbeat route secret:
 
-| Variable                                   | Required   | Purpose                                                                                       |
-| ------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------- |
-| `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET` | Production | Bearer token for internal scheduler and heartbeat routes. Use `CRON_SECRET` with Vercel Cron. |
-| `JUNIOR_TIMEZONE`                          | No         | Default IANA timezone for schedule authoring. Defaults to `America/Los_Angeles`.              |
+| Variable                                   | Required   | Purpose                                                                            |
+| ------------------------------------------ | ---------- | ---------------------------------------------------------------------------------- |
+| `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET` | Production | Bearer token for the internal heartbeat route. Use `CRON_SECRET` with Vercel Cron. |
+| `JUNIOR_TIMEZONE`                          | No         | Default IANA timezone for schedule authoring. Defaults to `America/Los_Angeles`.   |
 
-Local development can run without a scheduler route secret when you call the dev server directly. Production deployments should set `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET`.
+Local development can run without a heartbeat route secret when you call the dev server directly. Production deployments should set `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET`.
 
 ## Verify
 
@@ -80,4 +99,4 @@ For recurring or non-reminder scheduled work, Junior should show the proposed ta
 
 ## Next step
 
-Read [Build a Plugin](/extend/build-a-plugin/) for the trusted `tools(ctx)` and `heartbeat(ctx)` APIs that the built-in scheduler uses.
+Read [Build a Plugin](/extend/build-a-plugin/) for the trusted `tools(ctx)` and `heartbeat(ctx)` APIs that the scheduler uses.

packages/docs/src/content/docs/reference/api/functions/createApp.md

@@ -7,7 +7,7 @@ title: "createApp"
 
 > **createApp**(`options?`): `Promise`\<`Hono`\<`BlankEnv`, `BlankSchema`, `"/"`\>\>
 
-Defined in: [app.ts:180](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L180)
+Defined in: [app.ts:179](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L179)
 
 Create a Hono app with all Junior routes.