@happyvertical/smrt-jobs 0.40.61 → 0.40.63

package/AGENTS.md

@@ -109,6 +109,32 @@ transitions and monotonic checkpoints in
 
 Mixin that adds `bg()` and `background()` to any SmrtObject. Uses WeakMap for collection caching per DB instance.
 
+## Background policy (`background-policy.ts`, S5 audit #1402)
+
+Three opt-in guards, all owned **and enforced here**. Other packages apply the
+eligibility marker (`reports`, `support`, `fields`, the MCP conformance
+fixture), but nothing outside this package acts on it — `TaskRunner` is the only
+reader. In particular `@happyvertical/smrt-agents` has no reference to any of
+these guards and does not depend on this package, so marking a method does not
+change what the agents runtime will dispatch.
+
+- `clampRetries()` / `MAX_JOB_RETRIES` (25): a requested retry count above the
+  ceiling is clamped, not rejected.
+- `assertWithinTenantCreationCap(tenantId, current, cap)` /
+  `DEFAULT_TENANT_JOB_CAP` (10 000): throws `TenantJobCapExceededError` when the
+  tenant's count of non-terminal jobs is already at or above the cap. Applied in
+  `SmrtJobCollection.enqueueJob()` (`smrt-job.ts`), which is the single choke
+  point for the builder and `ScheduleRunner`; a `null` tenant and a `cap <= 0`
+  both skip the check. Deliberately not serialized — concurrent enqueues can
+  overshoot by the number of in-flight creators (see the method's own comment).
+- `@backgroundEligible()` / `markBackgroundEligible()` /
+  `isBackgroundEligibleMethod()`: an allowlist of methods `TaskRunner` may
+  dispatch, enforced at exactly one call site (`runner.ts`, after the method
+  lookup). **Restrictive, not enabling** — a class with no marked methods allows
+  any of its methods, and the first mark makes the set exhaustive, excluding
+  every sibling method. Adding the decorator to one method of an existing class
+  is therefore a behaviour change for the rest of it.
+
 ## Gotchas
 
 - **Cron not timezone-aware**: cron fields match the server's **local** time, not UTC (set `TZ` for UTC); no missed-run catch-up (fire-once-forward)

package/README.md

@@ -117,6 +117,25 @@ runner.on('job:failed', (job, error) => { /* ... */ });
 process.on('SIGTERM', () => runner.stop());
 ```
 
+### Back MCP task operations with durable jobs
+
+`McpTaskStore` persists the MCP `io.modelcontextprotocol/tasks` lifecycle on
+the same `_smrt_jobs` row that executes the operation. `createTask()` creates a
+correlated job, `getTask()` maps its queue state, and `cancelTask()` cancels
+that exact job without leaving a second record behind. Long-running task
+actions can request client input through `JobExecutionContext.task`:
+
+```typescript
+async generate(options: Record<string, never>, context: JobExecutionContext) {
+  const { tone } = await context.task!.requestInput({ tone: { type: 'string' } });
+  return this.render(tone);
+}
+```
+
+Run a `TaskRunner` for the `mcp-tasks` queue in application deployments. Task
+cancellation is cooperative: the job row becomes cancelled immediately and a
+running handler must observe its context before doing further side effects.
+
 ### Liveness-safe job execution
 
 `TaskRunner` records heartbeat telemetry, but recovery keys on a worker

package/dist/background-policy.d.ts

@@ -14,8 +14,14 @@
  *   opt-in allowlist of methods that may be invoked by the runner. The runner's
  *   dispatch is already bounded to existing prototype methods (no eval / dynamic
  *   import), but a class can further restrict which of its methods are reachable
- *   from a persisted job row. This same marker is intended to be consumed by the
- *   agents package, which dispatches methods through an equivalent path.
+ *   from a persisted job row.
+ *
+ * All three live in and are enforced by this package (`@happyvertical/smrt-jobs`).
+ * Other packages apply the marker (`smrt-reports`, `smrt-support`,
+ * `smrt-fields`), but the only thing that reads it is `TaskRunner`'s dispatch in
+ * `runner.ts`. `@happyvertical/smrt-agents` neither imports nor honours it, and
+ * does not depend on this package. Marking a method does **not** make it
+ * background-eligible anywhere outside the jobs runner.
  */
 /**
  * Hard ceiling on retry attempts a caller may request via `.retries(n)` /
@@ -60,9 +66,9 @@ export declare function assertWithinTenantCreationCap(tenantId: string | null |
  */
 export interface BackgroundEligibleClass {
     /**
-     * Method names that may be invoked by the job/agent runner. When present
-     * (even if empty), it is treated as an exhaustive allowlist. When absent,
-     * the runner falls back to its default behaviour (any existing method).
+     * Method names that may be invoked by `TaskRunner`. When present (even if
+     * empty), it is treated as an exhaustive allowlist. When absent, the runner
+     * falls back to its default behaviour (any existing method).
      */
     backgroundEligibleMethods?: ReadonlyArray<string> | ReadonlySet<string>;
 }
@@ -73,8 +79,9 @@ export interface BackgroundEligibleClass {
  * Once any method is marked, the runner refuses to dispatch a job whose
  * `method` is not in the set — turning the dispatch surface from "any prototype
  * method" into an explicit contract. Use this when applying the
- * {@link backgroundEligible} decorator is inconvenient (or in non-decorator
- * code, including the agents package).
+ * {@link backgroundEligible} decorator is inconvenient. Non-decorator code can
+ * skip the helper entirely and declare the static array directly, as
+ * `smrt-fields` does in `usage-learning.ts`.
  *
  * @param ctor - The class constructor to annotate.
  * @param methods - Method names to allow.
@@ -83,11 +90,16 @@ export declare function markBackgroundEligible(ctor: object, ...methods: string[
 /**
  * Decorator: mark a method as background-eligible.
  *
+ * This is **restrictive, not enabling**. Without it, `TaskRunner` will dispatch
+ * any existing prototype method; the first `@backgroundEligible()` on a class
+ * closes that surface and turns the set into an exhaustive allowlist, so every
+ * *other* method on that class stops being reachable from a persisted job row.
+ * Adding it to one method of an existing class is therefore a behaviour change
+ * for its siblings — mark all the methods you dispatch, or none of them.
+ *
  * This is a legacy (`experimentalDecorators`) method decorator — the mode the
  * SMRT monorepo compiles with. Applying it (one or more times) builds up the
- * static `backgroundEligibleMethods` allowlist on the owning class. Once any
- * method is marked, the runner will refuse to dispatch a job whose `method` is
- * not in the set.
+ * static `backgroundEligibleMethods` allowlist on the owning class.
  *
  * @example
  * ```ts

package/dist/background-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background-policy.d.ts","sourceRoot":"","sources":["../src/background-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;aAEhC,QAAQ,EAAE,MAAM;aAChB,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;gBAFf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM;CAQlC;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,IAAI,CAKN;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,GAAG,OAAO,EAAE,MAAM,EAAE,GACnB,IAAI,CASN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,KAE9B,QAAQ,MAAM,EACd,aAAa,MAAM,GAAG,MAAM,EAC5B,aAAa,kBAAkB,KAC9B,kBAAkB,GAAG,SAAS,CAOlC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,GACZ,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAK5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAIT"}
+{"version":3,"file":"background-policy.d.ts","sourceRoot":"","sources":["../src/background-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;aAEhC,QAAQ,EAAE,MAAM;aAChB,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;gBAFf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM;CAQlC;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,IAAI,CAKN;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,GAAG,OAAO,EAAE,MAAM,EAAE,GACnB,IAAI,CASN;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,KAE9B,QAAQ,MAAM,EACd,aAAa,MAAM,GAAG,MAAM,EAC5B,aAAa,kBAAkB,KAC9B,kBAAkB,GAAG,SAAS,CAOlC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,GACZ,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAK5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAIT"}