@vellumai/assistant 0.11.2-dev.202608060508.a7ab7f7 → 0.11.2-dev.202608060701.ede4331

package/ARCHITECTURE.md

@@ -838,7 +838,7 @@ graph LR
         JOBS["memory_jobs<br/>───────────────<br/>Async task queue<br/>Types: embed, extract,<br/>summarize, backfill, cleanup<br/>Status: pending → running →<br/>completed | failed"]
         ATT["attachments<br/>───────────────<br/>base64-encoded file data<br/>mime_type, size_bytes<br/>Linked to messages via<br/>message_attachments join"]
         REM["reminders<br/>───────────────<br/>One-time scheduled reminders<br/>label, message, fireAt<br/>mode: notify | execute<br/>status: pending → fired | cancelled<br/>routing_intent: single_channel |<br/>multi_channel | all_channels<br/>routing_hints_json (free-form)"]
-        SCHED_JOBS["cron_jobs (recurrence schedules)<br/>───────────────<br/>Recurring schedule definitions<br/>cron_expression: cron or RRULE string<br/>schedule_syntax: 'cron' | 'rrule'<br/>timezone, message, next_run_at<br/>enabled, retry_count<br/>Legacy alias: scheduleJobs"]
+        SCHED_JOBS["cron_jobs (recurrence schedules)<br/>───────────────<br/>Recurring schedule definitions<br/>cron_expression: cron or RRULE string<br/>schedule_syntax: 'cron' | 'rrule'<br/>timezone, message, next_run_at<br/>enabled, retry_count<br/>source_key: plugin-declared provenance<br/>definition_hash, user_enabled<br/>Legacy alias: scheduleJobs"]
         SCHED_RUNS["cron_runs (schedule runs)<br/>───────────────<br/>Execution history per schedule<br/>job_id (FK → cron_jobs)<br/>status: ok | error<br/>duration_ms, output, error<br/>Legacy alias: scheduleRuns"]
         TASKS["tasks<br/>───────────────<br/>Reusable prompt templates<br/>title, Handlebars template<br/>inputSchema, contextFlags<br/>requiredTools, status"]
         TASK_RUNS["task_runs<br/>───────────────<br/>Execution history per task<br/>taskId (FK → tasks)<br/>conversationId, status<br/>startedAt, finishedAt, error"]
@@ -863,6 +863,59 @@ graph LR
 
 ---
 
+## Plugin-Declared Schedules: Declaration → Reconciler → cron_jobs
+
+Plugins contribute recurring schedules as a surface: directories under
+`<pluginDir>/schedules/`, each a `<name>/` holding `config.json` plus
+exactly one `index.md` (runs as `execute`) or `index.sh` (runs as `script`)
+entrypoint. Ambiguity fails closed: a file sitting directly under
+`schedules/`, zero/multiple/unsupported entrypoints, and malformed config
+produce per-schedule `DeclarationError`s without affecting siblings
+(`src/schedule/plugin-schedule-declarations.ts`).
+
+A level-based reconciler (`src/schedule/plugin-schedule-reconciler.ts`)
+converges declarations into ordinary `cron_jobs` rows keyed by the nullable
+`source_key` column (`plugin:<plugin>/<name>`). Rows with `source_key IS
+NULL` are imperative schedules the reconciler never touches. Triggers: a
+startup pass in `daemon/lifecycle.ts` (after plugin init, before the
+scheduler starts), the end of `reconcilePluginSourcesNow()` in
+`plugins/mtime-cache.ts` (install/uninstall/upgrade and sentinel-driven
+changes), the plugin enable/disable routes, and a 60s backstop sweep
+registered with the HTTP server's background sweeps.
+
+Reconcile lag never lets a disabled plugin run. The disable path writes a
+`.disabled` sentinel that only a reconcile pass turns into disarmed rows, so
+the scheduler re-reads the sentinel at fire time and records a skipped run
+instead of executing a claimed row whose plugin is off. Run-now applies the
+same boundary through `declarationExistsOnDisk`, which also covers a plugin
+whose manifest no longer parses, a declaration directory that is gone, and a
+plugin root or declaration directory resolving outside the tree it belongs to
+(the same `isInsidePluginRoot` containment the loader applies before importing
+a plugin).
+
+A declaration that stops parsing keeps its execute row armed on the message
+already stored in the row, but disarms its script rows: a script row fires its
+entrypoint by absolute path, so leaving it armed would run the very `index.sh`
+the parser rejected. Those rows re-arm on the pass after the declaration parses
+again.
+
+Ownership boundaries: the reconciler owns definition columns (expression,
+timezone, message/script, retry policy, `definition_hash`); the execution
+engine owns runtime columns (`next_run_at`, `status`, `last_*`,
+`retry_count`) and its latches are never overridden; the user owns
+`user_enabled`, a sticky override consulted when computing effective
+`enabled`. Nothing ever writes to plugin files. Execution itself is
+unchanged: declared rows fire through the same `claimDueSchedules` path as
+imperative ones.
+
+Consent and surfacing: CLI install/upgrade list declared schedules and
+prompt before finalizing; unattended daemon-route installs are covered by
+`schedule.declared` arrival notifications, with `schedule.definition_changed`
+and `schedule.definition_error` covering upgrades and broken declarations
+(events registered in `notifications/signal.ts`, deterministic templates in
+`notifications/copy-composer.ts`). Settings routes, CLI, and web render
+plugin-sourced rows read-only except the enabled toggle.
+
 ---
 
 ## Web Server — Connection Modes

package/openapi.yaml

@@ -24245,14 +24245,43 @@ paths:
                             description:
                               Registered tool names from `tools/<name>.{ts,js}` (filenames derived to tool names, e.g. `create-issue` →
                               `create_issue`).
+                          schedules:
+                            type: array
+                            items:
+                              type: object
+                              properties:
+                                name:
+                                  type: string
+                                  description: "Schedule name: the declaration directory's name."
+                                cadence:
+                                  type: string
+                                  description: Raw schedule `expression` string from the declaration's config.
+                                mode:
+                                  type: string
+                                  enum:
+                                    - execute
+                                    - script
+                                  description: "`execute` for a markdown prompt entrypoint, `script` for `index.sh`."
+                              required:
+                                - name
+                                - cadence
+                                - mode
+                              additionalProperties: false
+                            description:
+                              Schedules declared under `schedules/`, each a `<name>/` directory with `config.json` plus one entrypoint.
+                              Display surface only; files directly under `schedules/` and unsupported declarations are
+                              omitted.
                         required:
                           - skills
                           - hooks
                           - tools
+                          - schedules
                         additionalProperties: false
                         description: Surfaces the installed copy contributes, read from its on-disk tree.
                       - type: "null"
-                    description: Surfaces the installed copy contributes (skills, hooks, tools); null when the plugin is not installed.
+                    description:
+                      Surfaces the installed copy contributes (skills, hooks, tools, schedules); null when the plugin is not
+                      installed.
                 required:
                   - name
                   - installed
@@ -25598,6 +25627,20 @@ paths:
                           anyOf:
                             - type: string
                             - type: "null"
+                        sourceKey:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                          description:
+                            Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                            schedules
+                        userEnabled:
+                          anyOf:
+                            - type: boolean
+                            - type: "null"
+                          description:
+                            User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                            applies. Always null for user-created schedules.
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -25632,6 +25675,8 @@ paths:
                         - reuseConversation
                         - wakeConversationId
                         - workflowName
+                        - sourceKey
+                        - userEnabled
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -25815,6 +25860,20 @@ paths:
                         anyOf:
                           - type: string
                           - type: "null"
+                      sourceKey:
+                        anyOf:
+                          - type: string
+                          - type: "null"
+                        description:
+                          Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                          schedules
+                      userEnabled:
+                        anyOf:
+                          - type: boolean
+                          - type: "null"
+                        description:
+                          User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                          applies. Always null for user-created schedules.
                       isOneShot:
                         type: boolean
                       isDeferred:
@@ -25849,6 +25908,8 @@ paths:
                       - reuseConversation
                       - wakeConversationId
                       - workflowName
+                      - sourceKey
+                      - userEnabled
                       - isOneShot
                       - isDeferred
                     additionalProperties: false
@@ -25984,6 +26045,20 @@ paths:
                           anyOf:
                             - type: string
                             - type: "null"
+                        sourceKey:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                          description:
+                            Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                            schedules
+                        userEnabled:
+                          anyOf:
+                            - type: boolean
+                            - type: "null"
+                          description:
+                            User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                            applies. Always null for user-created schedules.
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26018,6 +26093,8 @@ paths:
                         - reuseConversation
                         - wakeConversationId
                         - workflowName
+                        - sourceKey
+                        - userEnabled
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26150,6 +26227,20 @@ paths:
                         anyOf:
                           - type: string
                           - type: "null"
+                      sourceKey:
+                        anyOf:
+                          - type: string
+                          - type: "null"
+                        description:
+                          Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                          schedules
+                      userEnabled:
+                        anyOf:
+                          - type: boolean
+                          - type: "null"
+                        description:
+                          User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                          applies. Always null for user-created schedules.
                       isOneShot:
                         type: boolean
                       isDeferred:
@@ -26184,6 +26275,8 @@ paths:
                       - reuseConversation
                       - wakeConversationId
                       - workflowName
+                      - sourceKey
+                      - userEnabled
                       - isOneShot
                       - isDeferred
                     additionalProperties: false
@@ -26376,6 +26469,20 @@ paths:
                           anyOf:
                             - type: string
                             - type: "null"
+                        sourceKey:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                          description:
+                            Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                            schedules
+                        userEnabled:
+                          anyOf:
+                            - type: boolean
+                            - type: "null"
+                          description:
+                            User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                            applies. Always null for user-created schedules.
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26410,6 +26517,8 @@ paths:
                         - reuseConversation
                         - wakeConversationId
                         - workflowName
+                        - sourceKey
+                        - userEnabled
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26545,6 +26654,20 @@ paths:
                           anyOf:
                             - type: string
                             - type: "null"
+                        sourceKey:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                          description:
+                            Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                            schedules
+                        userEnabled:
+                          anyOf:
+                            - type: boolean
+                            - type: "null"
+                          description:
+                            User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                            applies. Always null for user-created schedules.
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26579,6 +26702,8 @@ paths:
                         - reuseConversation
                         - wakeConversationId
                         - workflowName
+                        - sourceKey
+                        - userEnabled
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26590,7 +26715,9 @@ paths:
     post:
       operationId: schedules_by_id_run_post
       summary: Run schedule now
-      description: Trigger an immediate execution of a schedule.
+      description:
+        Trigger an immediate execution of a schedule. A plugin-sourced schedule is rejected with a 400 when its
+        plugin is disabled or no longer declares it.
       tags:
         - schedules
       parameters:
@@ -26714,6 +26841,20 @@ paths:
                           anyOf:
                             - type: string
                             - type: "null"
+                        sourceKey:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                          description:
+                            Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                            schedules
+                        userEnabled:
+                          anyOf:
+                            - type: boolean
+                            - type: "null"
+                          description:
+                            User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                            applies. Always null for user-created schedules.
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26748,6 +26889,8 @@ paths:
                         - reuseConversation
                         - wakeConversationId
                         - workflowName
+                        - sourceKey
+                        - userEnabled
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26884,7 +27027,7 @@ paths:
     post:
       operationId: schedules_by_id_toggle_post
       summary: Toggle schedule
-      description: Enable or disable a schedule.
+      description: Enable or disable a schedule. On a plugin-managed schedule this records the user's override (userEnabled).
       tags:
         - schedules
       parameters:
@@ -27020,6 +27163,20 @@ paths:
                           anyOf:
                             - type: string
                             - type: "null"
+                        sourceKey:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                          description:
+                            Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created
+                            schedules
+                        userEnabled:
+                          anyOf:
+                            - type: boolean
+                            - type: "null"
+                          description:
+                            User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
+                            applies. Always null for user-created schedules.
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -27054,6 +27211,8 @@ paths:
                         - reuseConversation
                         - wakeConversationId
                         - workflowName
+                        - sourceKey
+                        - userEnabled
                         - isOneShot
                         - isDeferred
                       additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608060508.a7ab7f7",
+  "version": "0.11.2-dev.202608060701.ede4331",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/db-schedule-syntax-migration.test.ts

@@ -58,7 +58,10 @@ describe("schedule_syntax column migration", () => {
         capabilities_json TEXT,
         description TEXT NOT NULL DEFAULT '',
         created_at INTEGER NOT NULL,
-        updated_at INTEGER NOT NULL
+        updated_at INTEGER NOT NULL,
+        source_key TEXT,
+        definition_hash TEXT,
+        user_enabled INTEGER
       )
     `);
 

package/src/__tests__/emit-signal-routing-intent.test.ts

@@ -5,7 +5,7 @@ const enforceRoutingIntentMock = mock();
 const updateDecisionMock = mock();
 const runDeterministicChecksMock = mock();
 const createEventMock = mock();
-const updateEventDedupeKeyMock = mock();
+const setEventDedupeKeyMock = mock();
 const dispatchDecisionMock = mock();
 const isPlatformClientConfiguredMock = mock();
 
@@ -77,8 +77,7 @@ mock.module("../notifications/deterministic-checks.js", () => ({
 
 mock.module("../notifications/events-store.js", () => ({
   createEvent: (...args: unknown[]) => createEventMock(...args),
-  updateEventDedupeKey: (...args: unknown[]) =>
-    updateEventDedupeKeyMock(...args),
+  setEventDedupeKey: (...args: unknown[]) => setEventDedupeKeyMock(...args),
 }));
 
 mock.module("../notifications/runtime-dispatch.js", () => ({
@@ -104,7 +103,7 @@ beforeEach(() => {
   updateDecisionMock.mockReset();
   runDeterministicChecksMock.mockReset();
   createEventMock.mockReset();
-  updateEventDedupeKeyMock.mockReset();
+  setEventDedupeKeyMock.mockReset();
   dispatchDecisionMock.mockReset();
   isPlatformClientConfiguredMock.mockReset();
 

package/src/__tests__/mtime-cache.test.ts

@@ -14,6 +14,7 @@ import {
   mkdirSync,
   readFileSync,
   rmSync,
+  symlinkSync,
   utimesSync,
   writeFileSync,
 } from "node:fs";
@@ -507,17 +508,17 @@ describe("workspace hooks (<workspace>/hooks/)", () => {
     writePackageJson(dir, { ...SIMPLE_PKG, name: "ordering-plugin" });
     writeHook(
       dir,
-      "pre-model-call",
+      "conversation-deleted",
       `export default () => ({ tag: "plugin" });`,
     );
     writeWorkspaceHook(
-      "pre-model-call",
+      "conversation-deleted",
       `export default () => ({ tag: "workspace" });`,
     );
 
     await populateCacheAtBoot();
 
-    const hooks = await getUserHooksFor("pre-model-call");
+    const hooks = await getUserHooksFor("conversation-deleted");
     expect(hooks).toHaveLength(2);
     const results = hooks.map((fn) =>
       (fn as unknown as () => { tag: string })(),
@@ -1004,4 +1005,65 @@ describe("plugin root validation (ATL-983)", () => {
     // The evil plugin's init hook must NOT have run.
     expect(existsSync(evilMarker)).toBe(false);
   });
+
+  test("a symlinked plugin root escaping the plugins dir is not activated at boot", async () => {
+    // A real plugin outside the plugins directory, linked in under a name the
+    // boot scan reads. Hook resolution follows the link, so discovery is the
+    // only thing between boot and code from anywhere on disk.
+    const escapee = join(ROOT, "outside", "escapee");
+    mkdirSync(escapee, { recursive: true });
+    writePackageJson(escapee, { ...SIMPLE_PKG, name: "escapee" });
+    const escapeeMarker = join(ROOT, "escapee-init.log");
+    rmSync(escapeeMarker, { force: true });
+    writeMarkerHook(escapee, "init", escapeeMarker, "init");
+    writeHook(
+      escapee,
+      "user-prompt-submit",
+      `export default () => ({ tag: "escapee" });`,
+    );
+    symlinkSync(escapee, join(PLUGINS_DIR, "escapee"));
+
+    // A contained plugin in the same scan, so a boot that discovered nothing
+    // at all cannot pass this test.
+    const keeper = freshPluginDir("keeper");
+    writePackageJson(keeper, { ...SIMPLE_PKG, name: "keeper" });
+    writeHook(
+      keeper,
+      "user-prompt-submit",
+      `export default () => ({ tag: "keeper" });`,
+    );
+
+    await populateCacheAtBoot();
+
+    expect(
+      (await getUserHooksFor("user-prompt-submit")).map(
+        (fn) => (fn as unknown as () => { tag: string })().tag,
+      ),
+    ).toEqual(["keeper"]);
+    expect(existsSync(escapeeMarker)).toBe(false);
+  });
+
+  test("a symlinked plugin root staying inside the plugins dir is activated at boot", async () => {
+    // A symlinked plugin root is supported (see `plugins/source-fingerprint.ts`)
+    // as long as it resolves inside the plugins directory. The link target sits
+    // in a dot-prefixed store directory, which carries no package.json and is
+    // therefore not an install of its own.
+    const target = join(PLUGINS_DIR, ".store", "alias");
+    mkdirSync(target, { recursive: true });
+    writePackageJson(target, { ...SIMPLE_PKG, name: "alias" });
+    writeHook(
+      target,
+      "user-prompt-submit",
+      `export default () => ({ tag: "alias" });`,
+    );
+    symlinkSync(target, join(PLUGINS_DIR, "alias"));
+
+    await populateCacheAtBoot();
+
+    expect(
+      (await getUserHooksFor("user-prompt-submit")).map(
+        (fn) => (fn as unknown as () => { tag: string })().tag,
+      ),
+    ).toEqual(["alias"]);
+  });
 });

package/src/__tests__/notification-schedule-notify-dedup.test.ts

@@ -3,7 +3,7 @@
  * deduplicated against prior firings of the same schedule.
  *
  * The scheduler supplies a unique per-firing dedupeKey
- * (`schedule:notify:<id>:<timestamp>`) so `updateEventDedupeKey` is never
+ * (`schedule:notify:<id>:<timestamp>`) so `setEventDedupeKey` is never
  * called for schedule signals and `checkDedupe` never finds a matching
  * row when the LLM decision engine generates a stable key like
  * `schedule:notify:<id>`.