@happyvertical/smrt-jobs 0.51.37 → 0.51.38

package/README.md

@@ -229,3 +229,118 @@ the same queue without duplicate-claiming a pending row.
 - `@happyvertical/logger` -- structured logging
 - `@happyvertical/utils` -- ID generation utilities
 - Peer (optional): `@happyvertical/smrt-svelte`, `svelte`
+
+### Restartable MCP input
+
+For a workflow that must survive process restart, create the task with
+`continuation: { recordId, revision, inputKey }`. These are immutable references
+to an existing application review/action record, not approval or authority.
+Create the store with both `ownerId` and `tenantId`; task creation must match
+that active tenant. The application adapter must derive these values from its
+verified principal, never tool arguments.
+
+Configure `TaskRunner.authorizeMcpTask` to resolve live grants and validate the
+bound actor/tenant against the owning record. It is mandatory for continuation tasks and for every remote app-created task,
+and fails closed if absent or unavailable. Provider exceptions become the fixed
+`MCP task authorization denied` error before task persistence; internal provider
+details are never exposed through task status. It runs before each invocation;
+`context.task.assertAuthorized()` repeats it and checks worker ownership before
+apply. A permission snapshot must not be persisted in the job.
+
+`context.task.requestContinuation(binding, inputDescriptor)` stores one input
+round in the existing job row and suspends execution, releasing the worker.
+Waiting rows are not claimable until `updateTask()` atomically stores the first
+complete answer. A new worker starts the method from its beginning and retrieves
+the saved answer. Calls before this seam must be read-only or use the owning
+`runOnce`/action idempotency contract. The binding cannot change between rounds;
+use a new owning action/task for another review revision. JSON input is bounded
+to 64 KiB. Unknown response keys are ignored, incomplete responses do not wake
+the job, and repeated answers cannot overwrite the first accepted response.
+Once an answer is accepted, status is `working` while queued or resumed; the
+immutable response remains available for replay without asking for input again.
+
+`getContinuation(taskId)` exposes the waiting descriptor only through the same
+actor/tenant-scoped store. Use it in an explicitly declared authorized workflow
+tool or application form. It adds no fields to MCP `tasks/get`. The stateless
+HTTP adapter retains no callback; absent elicitation, offer the application's
+review URL/form. OpenAI MRTR is an optional protocol adapter responsibility and
+is not implemented by this job API. The legacy `requestInput()` remains a
+running-handler wait bounded by the job timeout and is not restartable.
+
+Continuation tasks and remote app-created tasks do not automatically retry errors or unknown external outcomes.
+Reconcile those through the owning action state's durable reservation/evidence
+API; never blindly resubmit. Cancellation guards subsequent cooperative work
+and terminal writes, but cannot retract an external side effect already sent.
+The owning apply transaction must revalidate immutable review/revision and
+idempotency. A host answer never creates final human approval; Iolaus continues
+to use its dedicated human review page.
+
+Persistence checks: `pnpm --filter @happyvertical/smrt-jobs test` and
+`pnpm --filter @happyvertical/smrt-jobs test:postgres`. The continuation suite
+also runs against a managed PostgreSQL database with:
+
+```sh
+node scripts/run-with-ci-postgres.mjs -- pnpm --filter @happyvertical/smrt-jobs test src/__tests__/mcp-continuation.optional.test.ts
+```
+
+Supply `CI_POSTGRES_BASE_URL` for a disposable test server; the wrapper creates
+and drops a synthetic database. Do not point destructive fixtures at user data.
+
+Generated stdio servers retain their existing trusted-local-process assumption:
+`SMRT_MCP_TENANT_ID` is a deployment scope and existing task owner namespace,
+not an authenticated human identity. The generated store now also passes the
+same active tenant used by task creation. Multi-user remote workflows require
+the verified application principal path and a live runner authorizer.
+
+The app integration exports `continueMcpWorkflow()` and
+`createMcpContinuationTool()` from `@happyvertical/smrt-app-mcp`.
+The first composes this job seam with an application's `applyReviewed` callback;
+that callback must invoke its owning immutable approval and idempotency API,
+not a raw mutation. The second declares a read-only workflow tool for a host
+without elicitation. Register that tool through the app server's existing
+`workflowTools` option. Supply a `storeFor(verifiedPrincipal)` bound to the same
+owner namespace and tenant used for task creation, and a live `authorize`
+callback. It returns text and structured form/review URL data; no iframe,
+subscription, or host-specific form implementation is required. Review URLs
+must use HTTPS, or HTTP on loopback for a local deployment, without credentials.
+
+
+Remote `createMcpAppServer` task stores always set `requireAuthorization: true`.
+This server-owned requirement is persisted separately from user invocation
+arguments; tool arguments cannot disable it. An ordinary remote task without
+continuation metadata must therefore configure the same live worker callback.
+The legacy input seam also checks current authority before waiting and after
+input returns. Applications must call `context.task.assertAuthorized()` again
+immediately before later side effects. Direct `McpTaskStore` callers default to
+trusted-local compatibility; set `requireAuthorization: true` for any remote
+or multi-user application. This default does not confer human identity.
+
+Shutdown includes any in-flight claim in the existing bounded drain and keeps
+the worker lease until that drain finishes. A claim returning after shutdown
+started is released without dispatch or consuming an attempt, even if the
+shutdown deadline has elapsed; the next incarnation may claim it normally.
+The same runner cannot restart while an earlier poll or handler is still draining.
+
+### Durable continuation ready-index rollout
+
+`_smrt_jobs_ready_idx` is an additive declared nonunique index on `(status,
+run_at)`, restricted to `status = 'pending' AND (task_input_requests IS NULL
+OR task_input_responses IS NOT NULL)`. Both `listReady()` and `claimReady()`
+use this exact eligibility predicate. Suspended already-due jobs remain pending,
+but SQLite/PostgreSQL exclude them from this index until an answer wakes them.
+The original `_smrt_jobs_status_run_at_idx` remains for other status/time reads.
+
+Deploy through the owning schema migration path: run `smrt db:migrate` before
+running the updated workers; for continuously written PostgreSQL queues use
+`smrt db:migrate --postgres-safe` so the index builds concurrently. No runtime
+task/runner API creates the index. The old schema remains functionally correct
+until migration, but polling can scan the suspended backlog. This changes no
+column or task status. DuckDB/JSON use the existing DDL strategy's full-index
+fallback and do **not** gain suspended-backlog exclusion; the readiness filter
+still preserves correctness on those engines.
+
+Task creation snapshots only validated `recordId`, `revision`, and `inputKey`
+values before any awaited enqueue work. Extra caller fields are not persisted,
+and later mutation of the caller's binding cannot change the durable review
+reference. Live authorization still checks the saved reference at execution
+and resume; the snapshot never grants approval.