@x12i/memorix-service 3.0.6 → 3.2.0

package/dist/routes/jobs.js

@@ -0,0 +1,888 @@
+import { randomUUID } from "node:crypto";
+import { evaluateWork, fingerprintPlan, previewWork, previewWorkSelector, promoteHeldRuns, recoverBatch, requeueRun, } from "@x12i/memorix-pipeline/v2";
+import { ServiceError } from "../errors.js";
+import { agentMatches, resolveConcreteOrgId, resolveJobsScope, toMemorixScope, } from "../jobs-scope.js";
+import { listExecutionTargets, parseExecutionTarget, resolveExecutionTarget, resolvePipelineIdAsTarget, } from "../execution-target.js";
+const PER_ORG_LIST_CAP = 200;
+const MERGED_LIST_CAP = 500;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseLimit(raw, fallback = 50, max = 200) {
+    const n = Number(raw ?? fallback);
+    if (!Number.isFinite(n) || n < 1)
+        return fallback;
+    return Math.min(Math.floor(n), max);
+}
+function createListAbstract(platform, scope) {
+    return async (input) => {
+        if (!platform.client) {
+            return { items: [] };
+        }
+        const ports = platform.portsFor(scope);
+        const listed = await ports.reader.listAbstract(scope, {
+            abstractType: input.abstractType,
+            filters: input.filters,
+            limit: input.limit,
+            cursor: input.cursor,
+        });
+        return {
+            items: listed.items.map((item) => ({
+                objectType: item.objectType,
+                recordId: item.recordId,
+                contentType: item.contentType || input.contentType,
+            })),
+            nextCursor: listed.nextCursor,
+        };
+    };
+}
+function createWorkEvaluatorDeps(platform, scope) {
+    const stores = platform.operationalStoresFor(scope.orgId);
+    const ledger = platform.pipelineLedgerFor(scope.orgId);
+    return {
+        orgId: scope.orgId,
+        agentIds: scope.agentIds,
+        ledger,
+        workDefinitions: stores.workDefinitions,
+        workEvaluations: stores.workEvaluations,
+        batches: stores.batches,
+        queueSettings: stores.queueSettings,
+        listAbstract: createListAbstract(platform, scope),
+        resolvePipeline: async (agentIds, pipelineId) => {
+            try {
+                const resolved = await resolvePipelineIdAsTarget(platform, {
+                    agentIds,
+                    orgId: scope.orgId,
+                    pipelineId,
+                });
+                return resolved.compiled;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+function parseWorkSelector(body) {
+    const rec = asRecord(body) ?? {};
+    const selector = asRecord(rec.selector) ?? rec;
+    const abstractType = String(selector.abstractType ?? "").trim();
+    if (!abstractType) {
+        throw new ServiceError("VALIDATION", "selector.abstractType required", 400);
+    }
+    const contentType = typeof selector.contentType === "string" && selector.contentType.trim()
+        ? selector.contentType.trim()
+        : undefined;
+    const filter = Array.isArray(selector.filter)
+        ? selector.filter
+        : undefined;
+    return { abstractType, contentType, filter };
+}
+async function resolveOrgIds(platform, scope) {
+    if (scope.orgId)
+        return [scope.orgId];
+    return platform.listKnownOperationalOrgIds();
+}
+function requireScopedOrg(scope, action) {
+    if (!scope.orgId) {
+        throw new ServiceError("SCOPE_INVALID", `${action} requires a concrete organization (not all)`, 400);
+    }
+    return scope.orgId;
+}
+function emptyCounts() {
+    return {
+        total: 0,
+        held: 0,
+        ready: 0,
+        leased: 0,
+        pending: 0,
+        running: 0,
+        succeeded: 0,
+        failed: 0,
+        cancelled: 0,
+        workDefinitions: 0,
+    };
+}
+function requireConfirm(body, action) {
+    const rec = asRecord(body);
+    if (rec?.confirm !== true) {
+        throw new ServiceError("CONFIRMATION_REQUIRED", `confirm:true required for ${action}`, 400);
+    }
+}
+async function resolveTargetOrThrow(platform, opts) {
+    let target;
+    try {
+        target = parseExecutionTarget(opts.body);
+    }
+    catch (err) {
+        throw new ServiceError("VALIDATION", err instanceof Error ? err.message : String(err), 400);
+    }
+    try {
+        return await resolveExecutionTarget(platform, {
+            agentIds: opts.agentIds,
+            orgId: opts.orgId,
+            target,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const notFound = /not found|No origin configured/i.test(message);
+        throw new ServiceError(notFound ? "NOT_FOUND" : "VALIDATION", message, notFound ? 404 : 400);
+    }
+}
+export async function registerJobsRoutes(app, platform) {
+    app.get("/api/jobs/v1/execution-targets", async (req) => {
+        const scope = resolveJobsScope(req);
+        const agentIds = scope.agentIds?.length ? scope.agentIds : ["*"];
+        const catalog = await listExecutionTargets(platform, {
+            agentIds,
+            orgId: scope.orgId,
+        });
+        return { scope, ...catalog };
+    });
+    app.get("/api/jobs/v1/overview", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgIds = await resolveOrgIds(platform, scope);
+        const counts = emptyCounts();
+        let stuckLeases = 0;
+        const failureRows = [];
+        const inProgressRows = [];
+        const completedRows = [];
+        const now = Date.now();
+        let settings = null;
+        for (const orgId of orgIds) {
+            const stores = platform.operationalStoresFor(orgId);
+            const ledger = platform.pipelineLedgerFor(orgId);
+            if (scope.orgId) {
+                settings = await stores.queueSettings.get(orgId);
+            }
+            const work = await stores.workDefinitions.list(orgId, {
+                limit: PER_ORG_LIST_CAP,
+            });
+            const filteredWork = work.filter((w) => agentMatches(w.agentIds, scope.agentIds));
+            counts.workDefinitions += filteredWork.length;
+            const workNameById = new Map(filteredWork.map((w) => [w.workId, w.name?.trim() || ""]));
+            const runs = await ledger.listRuns(orgId, { limit: PER_ORG_LIST_CAP });
+            for (const run of runs) {
+                if (!agentMatches(run.agentIds, scope.agentIds))
+                    continue;
+                counts.total += 1;
+                const admission = run.admission?.state ?? "ready";
+                if (admission === "held")
+                    counts.held += 1;
+                else if (admission === "ready")
+                    counts.ready += 1;
+                // Dual-read: published types may still say "claimed"; runtime normalizes to "leased".
+                else if (admission === "leased" || admission === "claimed") {
+                    counts.leased += 1;
+                }
+                if (run.status === "pending")
+                    counts.pending += 1;
+                else if (run.status === "running")
+                    counts.running += 1;
+                else if (run.status === "succeeded")
+                    counts.succeeded += 1;
+                else if (run.status === "failed")
+                    counts.failed += 1;
+                else if (run.status === "cancelled")
+                    counts.cancelled += 1;
+                const leaseExpiresAt = run.admission?.leaseExpiresAt;
+                if ((admission === "leased" || admission === "claimed") &&
+                    leaseExpiresAt &&
+                    Date.parse(leaseExpiresAt) < now) {
+                    stuckLeases += 1;
+                }
+                const workId = run.workId ?? null;
+                const workName = workId && workNameById.get(workId)
+                    ? workNameById.get(workId)
+                    : null;
+                const itemRef = run.itemRef
+                    ? {
+                        objectType: run.itemRef.objectType ?? undefined,
+                        recordId: run.itemRef.recordId ?? undefined,
+                        contentType: run.itemRef.contentType ?? undefined,
+                    }
+                    : null;
+                const row = {
+                    runId: run.runId,
+                    orgId,
+                    pipelineId: run.pipelineId,
+                    workId,
+                    workName,
+                    batchId: run.batchId ?? null,
+                    itemRef,
+                    status: run.status,
+                    updatedAt: run.updatedAt,
+                    error: run.error ?? null,
+                };
+                if (run.status === "failed")
+                    failureRows.push(row);
+                if (run.status === "running" || run.status === "pending") {
+                    inProgressRows.push(row);
+                }
+                if (run.status === "succeeded")
+                    completedRows.push(row);
+            }
+        }
+        const byUpdatedDesc = (a, b) => Date.parse(String(b.updatedAt ?? "")) - Date.parse(String(a.updatedAt ?? ""));
+        return {
+            scope,
+            settings,
+            counts,
+            stuckLeases,
+            recentFailures: failureRows.sort(byUpdatedDesc).slice(0, 20),
+            recentInProgress: inProgressRows.sort(byUpdatedDesc).slice(0, 20),
+            recentCompleted: completedRows.sort(byUpdatedDesc).slice(0, 20),
+            orgCount: orgIds.length,
+        };
+    });
+    app.get("/api/jobs/v1/settings", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "queue settings");
+        const stores = platform.operationalStoresFor(orgId);
+        const settings = await stores.queueSettings.get(orgId);
+        return { scope, settings };
+    });
+    app.get("/api/jobs/v1/work", async (req) => {
+        const scope = resolveJobsScope(req);
+        const q = req.query;
+        const enabled = q.enabled === "true" ? true : q.enabled === "false" ? false : undefined;
+        const limit = parseLimit(q.limit, 50, MERGED_LIST_CAP);
+        const orgIds = await resolveOrgIds(platform, scope);
+        const work = [];
+        for (const orgId of orgIds) {
+            if (work.length >= limit)
+                break;
+            const stores = platform.operationalStoresFor(orgId);
+            const listed = await stores.workDefinitions.list(orgId, {
+                enabled,
+                limit: Math.min(PER_ORG_LIST_CAP, limit - work.length),
+            });
+            for (const row of listed) {
+                if (!agentMatches(row.agentIds, scope.agentIds))
+                    continue;
+                work.push({ ...row, orgId: row.orgId ?? orgId });
+                if (work.length >= limit)
+                    break;
+            }
+        }
+        return { scope, work };
+    });
+    app.get("/api/jobs/v1/work/:workId", async (req) => {
+        const scope = resolveJobsScope(req);
+        const { workId } = req.params;
+        const orgId = resolveConcreteOrgId(scope, req.query);
+        const stores = platform.operationalStoresFor(orgId);
+        const work = await stores.workDefinitions.get(orgId, workId);
+        if (!work) {
+            throw new ServiceError("NOT_FOUND", `work ${workId} not found`, 404);
+        }
+        if (!agentMatches(work.agentIds, scope.agentIds)) {
+            throw new ServiceError("NOT_FOUND", `work ${workId} not found`, 404);
+        }
+        const evaluations = await stores.workEvaluations.listForWork(orgId, workId, 50);
+        return { scope, work: { ...work, orgId: work.orgId ?? orgId }, evaluations };
+    });
+    app.post("/api/jobs/v1/work/:workId/preview", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "work preview");
+        const { workId } = req.params;
+        const memorixScope = toMemorixScope(orgId, scope.agentIds);
+        const deps = createWorkEvaluatorDeps(platform, memorixScope);
+        try {
+            const preview = await previewWork(deps, workId);
+            return { scope, workId, preview };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(message)) {
+                throw new ServiceError("NOT_FOUND", message, 404);
+            }
+            throw new ServiceError("VALIDATION", message, 400);
+        }
+    });
+    app.get("/api/jobs/v1/batches", async (req) => {
+        const scope = resolveJobsScope(req);
+        const q = req.query;
+        const limit = parseLimit(q.limit, 50, MERGED_LIST_CAP);
+        const orgIds = await resolveOrgIds(platform, scope);
+        const batches = [];
+        for (const orgId of orgIds) {
+            if (batches.length >= limit)
+                break;
+            const stores = platform.operationalStoresFor(orgId);
+            const listed = await stores.batches.list(orgId, {
+                workId: q.workId,
+                limit: Math.min(PER_ORG_LIST_CAP, limit - batches.length),
+            });
+            for (const row of listed) {
+                batches.push({ ...row, orgId: row.orgId ?? orgId });
+                if (batches.length >= limit)
+                    break;
+            }
+        }
+        return { scope, batches };
+    });
+    app.get("/api/jobs/v1/batches/:batchId", async (req) => {
+        const scope = resolveJobsScope(req);
+        const { batchId } = req.params;
+        const orgId = resolveConcreteOrgId(scope, req.query);
+        const stores = platform.operationalStoresFor(orgId);
+        const ledger = platform.pipelineLedgerFor(orgId);
+        const batch = await stores.batches.get(orgId, batchId);
+        if (!batch) {
+            throw new ServiceError("NOT_FOUND", `batch ${batchId} not found`, 404);
+        }
+        const runs = (await ledger.listRuns(orgId, {
+            batchId,
+            limit: 200,
+        })).filter((run) => agentMatches(run.agentIds, scope.agentIds));
+        return {
+            scope,
+            batch: { ...batch, orgId: batch.orgId ?? orgId },
+            runs: runs.map((r) => ({ ...r, orgId: r.orgId ?? orgId })),
+        };
+    });
+    app.get("/api/jobs/v1/runs", async (req) => {
+        const scope = resolveJobsScope(req);
+        const q = req.query;
+        const limit = parseLimit(q.limit, 50, MERGED_LIST_CAP);
+        const status = q.status && q.status.includes(",")
+            ? q.status.split(",").map((s) => s.trim()).filter(Boolean)
+            : q.status;
+        const orgIds = await resolveOrgIds(platform, scope);
+        const runs = [];
+        for (const orgId of orgIds) {
+            if (runs.length >= limit)
+                break;
+            const ledger = platform.pipelineLedgerFor(orgId);
+            const listed = await ledger.listRuns(orgId, {
+                status,
+                workId: q.workId,
+                batchId: q.batchId,
+                pipelineId: q.pipelineId,
+                admissionState: q.admissionState,
+                objectType: q.objectType?.trim() || undefined,
+                recordId: q.recordId?.trim() || undefined,
+                limit: Math.min(PER_ORG_LIST_CAP, limit - runs.length),
+            });
+            for (const run of listed) {
+                if (!agentMatches(run.agentIds, scope.agentIds))
+                    continue;
+                runs.push({ ...run, orgId: run.orgId ?? orgId });
+                if (runs.length >= limit)
+                    break;
+            }
+        }
+        return { scope, runs };
+    });
+    app.get("/api/jobs/v1/runs/:runId", async (req) => {
+        const scope = resolveJobsScope(req);
+        const { runId } = req.params;
+        const orgId = resolveConcreteOrgId(scope, req.query);
+        const ledger = platform.pipelineLedgerFor(orgId);
+        const run = await ledger.getRun(orgId, runId);
+        if (!run) {
+            throw new ServiceError("NOT_FOUND", `run ${runId} not found`, 404);
+        }
+        if (!agentMatches(run.agentIds, scope.agentIds)) {
+            throw new ServiceError("NOT_FOUND", `run ${runId} not found`, 404);
+        }
+        const attempts = await ledger.listAttempts(orgId, runId);
+        const captured = run.capturedContextRef ?? null;
+        return {
+            scope,
+            runId,
+            status: run.status,
+            pipelineId: run.pipelineId,
+            workId: run.workId ?? null,
+            batchId: run.batchId ?? null,
+            attempts,
+            artifacts: captured ? [captured] : [],
+            capturedContextRef: captured,
+            run: { ...run, orgId: run.orgId ?? orgId },
+        };
+    });
+    app.get("/api/jobs/v1/information/preview", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "information preview");
+        const q = req.query;
+        const body = asRecord(req.body);
+        const selector = parseWorkSelector({
+            abstractType: body?.abstractType ?? q.abstractType,
+            contentType: body?.contentType ?? q.contentType,
+            filter: body?.filter,
+        });
+        const memorixScope = toMemorixScope(orgId, scope.agentIds);
+        const preview = await previewWorkSelector(createListAbstract(platform, memorixScope), selector, { limit: parseLimit(q.limit ?? body?.limit, 50) });
+        return { scope, selector, preview };
+    });
+    app.post("/api/jobs/v1/information/preview", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "information preview");
+        const body = asRecord(req.body) ?? {};
+        const selector = parseWorkSelector(body);
+        const memorixScope = toMemorixScope(orgId, scope.agentIds);
+        const preview = await previewWorkSelector(createListAbstract(platform, memorixScope), selector, { limit: parseLimit(body.limit, 50) });
+        return { scope, selector, preview };
+    });
+    // ── P4 writes ────────────────────────────────────────────────────────────
+    app.put("/api/jobs/v1/settings", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "update queue settings");
+        const body = asRecord(req.body) ?? {};
+        const stores = platform.operationalStoresFor(orgId);
+        const settings = await stores.queueSettings.save(orgId, {
+            queueMode: body.queueMode === "paused" || body.queueMode === "running"
+                ? body.queueMode
+                : undefined,
+            maxConcurrentRuns: typeof body.maxConcurrentRuns === "number"
+                ? body.maxConcurrentRuns
+                : undefined,
+            queueAdmissionIntervalMs: typeof body.queueAdmissionIntervalMs === "number"
+                ? body.queueAdmissionIntervalMs
+                : undefined,
+            batchRunMaxAttempts: typeof body.batchRunMaxAttempts === "number"
+                ? body.batchRunMaxAttempts
+                : undefined,
+            continuousRunMaxAttempts: typeof body.continuousRunMaxAttempts === "number"
+                ? body.continuousRunMaxAttempts
+                : undefined,
+        });
+        let promoted = 0;
+        if (settings.queueMode === "running") {
+            promoted = await promoteHeldRuns({
+                ledger: platform.pipelineLedgerFor(orgId),
+                orgId,
+                queueSettings: stores.queueSettings,
+            });
+        }
+        return { scope, settings, promoted };
+    });
+    app.post("/api/jobs/v1/work", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "create work");
+        if (!scope.agentIds?.length) {
+            throw new ServiceError("SCOPE_INVALID", "agentIds required to create work", 400);
+        }
+        const body = asRecord(req.body) ?? {};
+        const name = String(body.name ?? "").trim();
+        if (!name) {
+            throw new ServiceError("VALIDATION", "name required", 400);
+        }
+        const resolved = await resolveTargetOrThrow(platform, {
+            agentIds: scope.agentIds,
+            orgId,
+            body,
+        });
+        const selectionMode = body.selectionMode === "none" ? "none" : "items";
+        let selector;
+        if (selectionMode === "items") {
+            selector = parseWorkSelector(body.selector ?? body);
+        }
+        else if (body.selector != null || (asRecord(body)?.abstractType != null)) {
+            try {
+                selector = parseWorkSelector(body.selector ?? body);
+            }
+            catch {
+                selector = undefined;
+            }
+        }
+        const cadenceRec = asRecord(body.cadence) ?? {};
+        let cadence;
+        if (cadenceRec.kind === "schedule") {
+            const scheduleId = String(cadenceRec.scheduleId ?? "").trim();
+            if (!scheduleId) {
+                throw new ServiceError("VALIDATION", "cadence.scheduleId required", 400);
+            }
+            cadence = { kind: "schedule", scheduleId };
+        }
+        else {
+            const intervalMinutes = Number(cadenceRec.intervalMinutes ?? 15);
+            if (!Number.isFinite(intervalMinutes) || intervalMinutes < 1) {
+                throw new ServiceError("VALIDATION", "cadence.intervalMinutes required", 400);
+            }
+            cadence = { kind: "interval", intervalMinutes };
+        }
+        const policyRec = asRecord(body.policy) ?? {};
+        const priority = Number(policyRec.priority ?? 5);
+        if (!Number.isFinite(priority)) {
+            throw new ServiceError("VALIDATION", "policy.priority required", 400);
+        }
+        const now = new Date().toISOString();
+        const stores = platform.operationalStoresFor(orgId);
+        const work = await stores.workDefinitions.create({
+            workId: randomUUID(),
+            orgId,
+            agentIds: [...scope.agentIds],
+            name,
+            description: typeof body.description === "string" ? body.description : undefined,
+            enabled: body.enabled === false ? false : true,
+            pipelineId: resolved.pipelineId,
+            executionTarget: resolved.target,
+            selectionMode,
+            selector,
+            cadence,
+            policy: {
+                priority,
+                maxAttempts: typeof policyRec.maxAttempts === "number"
+                    ? policyRec.maxAttempts
+                    : undefined,
+                duplicate: asRecord(policyRec.duplicate),
+            },
+            inputTemplate: body.inputTemplate,
+            nextEvaluationAt: now,
+            createdAt: now,
+            updatedAt: now,
+        });
+        return { scope, work };
+    });
+    app.patch("/api/jobs/v1/work/:workId", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "update work");
+        const { workId } = req.params;
+        const body = asRecord(req.body) ?? {};
+        const stores = platform.operationalStoresFor(orgId);
+        const existing = await stores.workDefinitions.get(orgId, workId);
+        if (!existing || !agentMatches(existing.agentIds, scope.agentIds)) {
+            throw new ServiceError("NOT_FOUND", `work ${workId} not found`, 404);
+        }
+        const patch = { updatedAt: new Date().toISOString() };
+        if (typeof body.name === "string")
+            patch.name = body.name.trim();
+        if (typeof body.description === "string")
+            patch.description = body.description;
+        if (typeof body.enabled === "boolean")
+            patch.enabled = body.enabled;
+        if (body.executionTarget != null || typeof body.pipelineId === "string") {
+            const resolved = await resolveTargetOrThrow(platform, {
+                agentIds: existing.agentIds,
+                orgId,
+                body: {
+                    executionTarget: body.executionTarget,
+                    pipelineId: body.pipelineId,
+                },
+            });
+            patch.pipelineId = resolved.pipelineId;
+            patch.executionTarget = resolved.target;
+        }
+        if (body.selector)
+            patch.selector = parseWorkSelector(body.selector);
+        if (body.selectionMode === "none" || body.selectionMode === "items") {
+            patch.selectionMode = body.selectionMode;
+        }
+        if (body.cadence) {
+            const cadenceRec = asRecord(body.cadence) ?? {};
+            if (cadenceRec.kind === "schedule") {
+                patch.cadence = {
+                    kind: "schedule",
+                    scheduleId: String(cadenceRec.scheduleId ?? "").trim(),
+                };
+            }
+            else if (cadenceRec.kind === "interval") {
+                patch.cadence = {
+                    kind: "interval",
+                    intervalMinutes: Number(cadenceRec.intervalMinutes),
+                };
+            }
+        }
+        if (body.policy) {
+            const policyRec = asRecord(body.policy) ?? {};
+            patch.policy = {
+                ...existing.policy,
+                ...policyRec,
+                priority: Number(policyRec.priority ?? existing.policy.priority),
+            };
+        }
+        if (body.inputTemplate !== undefined)
+            patch.inputTemplate = body.inputTemplate;
+        const work = await stores.workDefinitions.patch(orgId, workId, patch);
+        return { scope, work };
+    });
+    app.delete("/api/jobs/v1/work/:workId", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "delete work");
+        const { workId } = req.params;
+        const stores = platform.operationalStoresFor(orgId);
+        const existing = await stores.workDefinitions.get(orgId, workId);
+        if (!existing || !agentMatches(existing.agentIds, scope.agentIds)) {
+            throw new ServiceError("NOT_FOUND", `work ${workId} not found`, 404);
+        }
+        await stores.workDefinitions.delete(orgId, workId);
+        return { scope, deleted: true, workId };
+    });
+    app.post("/api/jobs/v1/work/:workId/evaluate", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "evaluate work");
+        const { workId } = req.params;
+        const memorixScope = toMemorixScope(orgId, scope.agentIds ?? []);
+        const deps = createWorkEvaluatorDeps(platform, memorixScope);
+        try {
+            const evaluation = await evaluateWork(deps, workId);
+            return { scope, workId, evaluation };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(message)) {
+                throw new ServiceError("NOT_FOUND", message, 404);
+            }
+            throw new ServiceError("VALIDATION", message, 400);
+        }
+    });
+    app.post("/api/jobs/v1/work/:workId/actions/:action", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "work action");
+        const { workId, action } = req.params;
+        const stores = platform.operationalStoresFor(orgId);
+        const existing = await stores.workDefinitions.get(orgId, workId);
+        if (!existing || !agentMatches(existing.agentIds, scope.agentIds)) {
+            throw new ServiceError("NOT_FOUND", `work ${workId} not found`, 404);
+        }
+        if (action === "pause") {
+            const work = await stores.workDefinitions.patch(orgId, workId, {
+                enabled: false,
+                updatedAt: new Date().toISOString(),
+            });
+            return { scope, work, action };
+        }
+        if (action === "resume") {
+            const work = await stores.workDefinitions.patch(orgId, workId, {
+                enabled: true,
+                nextEvaluationAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            });
+            return { scope, work, action };
+        }
+        if (action === "evaluate-now") {
+            const memorixScope = toMemorixScope(orgId, scope.agentIds ?? []);
+            const evaluation = await evaluateWork(createWorkEvaluatorDeps(platform, memorixScope), workId);
+            return { scope, workId, action, evaluation };
+        }
+        throw new ServiceError("VALIDATION", `unknown action ${action}; use pause|resume|evaluate-now`, 400);
+    });
+    app.post("/api/jobs/v1/on-demand/single", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "on-demand single");
+        if (!scope.agentIds?.length) {
+            throw new ServiceError("SCOPE_INVALID", "agentIds required", 400);
+        }
+        const body = asRecord(req.body) ?? {};
+        const itemRec = asRecord(body.itemRef) ?? {};
+        const objectType = String(itemRec.objectType ?? "").trim();
+        const recordId = String(itemRec.recordId ?? "").trim();
+        const resolved = await resolveTargetOrThrow(platform, {
+            agentIds: scope.agentIds,
+            orgId,
+            body,
+        });
+        // Connector pulls do not require an information itemRef.
+        if (resolved.target.kind !== "connector" && (!objectType || !recordId)) {
+            throw new ServiceError("VALIDATION", "itemRef.objectType/recordId required", 400);
+        }
+        const itemRef = objectType && recordId
+            ? {
+                objectType,
+                recordId,
+                contentType: typeof itemRec.contentType === "string"
+                    ? itemRec.contentType
+                    : undefined,
+            }
+            : undefined;
+        const compiled = resolved.compiled;
+        const stores = platform.operationalStoresFor(orgId);
+        const settings = await stores.queueSettings.get(orgId);
+        const paused = settings.queueMode === "paused";
+        const ledger = platform.pipelineLedgerFor(orgId);
+        const run = await ledger.createRun({
+            orgId,
+            agentIds: scope.agentIds,
+            pipelineId: resolved.pipelineId,
+            version: String(compiled.version ?? "1"),
+            planFingerprint: fingerprintPlan(compiled),
+            capturedPlan: structuredClone(compiled),
+            trigger: "on-demand",
+            input: {
+                ...(asRecord(body.input) ?? {}),
+                ...(itemRef ? { itemRef } : {}),
+                executionTarget: resolved.target,
+            },
+            itemRef,
+            sourceType: "on-demand-single",
+            priority: typeof body.priority === "number" ? body.priority : 0,
+            admission: { state: paused ? "held" : "ready" },
+            attemptBudget: settings.batchRunMaxAttempts,
+            runKey: typeof body.idempotencyKey === "string"
+                ? `ondemand:${body.idempotencyKey}`
+                : undefined,
+        });
+        return { scope, run, executionTarget: resolved.target };
+    });
+    app.post("/api/jobs/v1/on-demand/batches", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "on-demand batch");
+        if (!scope.agentIds?.length) {
+            throw new ServiceError("SCOPE_INVALID", "agentIds required", 400);
+        }
+        const body = asRecord(req.body) ?? {};
+        const items = Array.isArray(body.itemRefs) ? body.itemRefs : [];
+        const resolved = await resolveTargetOrThrow(platform, {
+            agentIds: scope.agentIds,
+            orgId,
+            body,
+        });
+        if (resolved.target.kind !== "connector" && items.length === 0) {
+            throw new ServiceError("VALIDATION", "itemRefs[] required", 400);
+        }
+        const itemRefs = items.length > 0
+            ? items.map((raw) => {
+                const r = asRecord(raw) ?? {};
+                const objectType = String(r.objectType ?? "").trim();
+                const recordId = String(r.recordId ?? "").trim();
+                if (!objectType || !recordId) {
+                    throw new ServiceError("VALIDATION", "each itemRef needs objectType and recordId", 400);
+                }
+                return {
+                    objectType,
+                    recordId,
+                    contentType: typeof r.contentType === "string" ? r.contentType : undefined,
+                };
+            })
+            : [
+                {
+                    objectType: "_connector",
+                    recordId: resolved.target.kind === "connector"
+                        ? resolved.target.sourceId
+                        : "batch",
+                },
+            ];
+        const compiled = resolved.compiled;
+        const planFingerprint = fingerprintPlan(compiled);
+        const stores = platform.operationalStoresFor(orgId);
+        const settings = await stores.queueSettings.get(orgId);
+        const paused = settings.queueMode === "paused";
+        const nowIso = new Date().toISOString();
+        const batchId = randomUUID();
+        const batch = await stores.batches.create({
+            batchId,
+            orgId,
+            agentIds: [...scope.agentIds],
+            name: String(body.name ?? `on-demand:${nowIso}`),
+            pipelineId: resolved.pipelineId,
+            executionTarget: resolved.target,
+            source: "on-demand",
+            selectionKind: "cohort",
+            cohortItemRefs: itemRefs,
+            status: "queued",
+            counts: {
+                total: itemRefs.length,
+                pending: itemRefs.length,
+                running: 0,
+                succeeded: 0,
+                failed: 0,
+                cancelled: 0,
+            },
+            exclusions: [],
+            policy: { priority: typeof body.priority === "number" ? body.priority : 0 },
+            inputTemplate: body.input,
+            createdAt: nowIso,
+            updatedAt: nowIso,
+        });
+        const ledger = platform.pipelineLedgerFor(orgId);
+        const runs = [];
+        for (const itemRef of itemRefs) {
+            const run = await ledger.createRun({
+                orgId,
+                agentIds: scope.agentIds,
+                pipelineId: resolved.pipelineId,
+                version: String(compiled.version ?? "1"),
+                planFingerprint,
+                capturedPlan: structuredClone(compiled),
+                trigger: "batch",
+                input: {
+                    ...(asRecord(body.input) ?? {}),
+                    itemRef,
+                    executionTarget: resolved.target,
+                },
+                batchId,
+                itemRef,
+                sourceType: "on-demand-batch",
+                priority: typeof body.priority === "number" ? body.priority : 0,
+                admission: { state: paused ? "held" : "ready" },
+                attemptBudget: settings.batchRunMaxAttempts,
+            });
+            runs.push(run);
+        }
+        await stores.batches.patch(orgId, batchId, { status: "running" });
+        return { scope, batch, runs, executionTarget: resolved.target };
+    });
+    app.post("/api/jobs/v1/batches/:batchId/recover", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "batch recover");
+        requireConfirm(req.body, "batch recover");
+        const { batchId } = req.params;
+        const stores = platform.operationalStoresFor(orgId);
+        try {
+            const result = await recoverBatch({
+                orgId,
+                ledger: platform.pipelineLedgerFor(orgId),
+                batches: stores.batches,
+                queueSettings: stores.queueSettings,
+            }, batchId);
+            return { scope, ...result };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(message)) {
+                throw new ServiceError("NOT_FOUND", message, 404);
+            }
+            throw new ServiceError("VALIDATION", message, 400);
+        }
+    });
+    app.post("/api/jobs/v1/runs/:runId/cancel", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "cancel run");
+        requireConfirm(req.body, "cancel run");
+        const { runId } = req.params;
+        const ledger = platform.pipelineLedgerFor(orgId);
+        const run = await ledger.getRun(orgId, runId);
+        if (!run || !agentMatches(run.agentIds, scope.agentIds)) {
+            throw new ServiceError("NOT_FOUND", `run ${runId} not found`, 404);
+        }
+        if (run.status === "succeeded" ||
+            run.status === "failed" ||
+            run.status === "cancelled") {
+            return { scope, run };
+        }
+        const updated = await ledger.updateRun(orgId, runId, {
+            status: "cancelled",
+            finishedAt: new Date().toISOString(),
+            error: { code: "RUN_CANCELLED", message: "run cancelled" },
+        });
+        return { scope, run: updated };
+    });
+    app.post("/api/jobs/v1/runs/:runId/retry", async (req) => {
+        const scope = resolveJobsScope(req);
+        const orgId = requireScopedOrg(scope, "retry run");
+        requireConfirm(req.body, "retry run");
+        const { runId } = req.params;
+        const stores = platform.operationalStoresFor(orgId);
+        try {
+            const run = await requeueRun({
+                orgId,
+                ledger: platform.pipelineLedgerFor(orgId),
+                queueSettings: stores.queueSettings,
+            }, runId);
+            return { scope, run };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(message)) {
+                throw new ServiceError("NOT_FOUND", message, 404);
+            }
+            throw new ServiceError("VALIDATION", message, 400);
+        }
+    });
+}
+//# sourceMappingURL=jobs.js.map