Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* CoS Autonomous Jobs Routes
*/
import { Router } from 'express';
import { addTask, reviveBlockedTask } from '../services/cosTaskStore.js';
import { forceSpawnTask } from '../services/cos.js';
import * as autonomousJobs from '../services/autonomousJobs.js';
import { checkJobGate, hasGate, getRegisteredGates } from '../services/jobGates.js';
import { computeNextJobRun } from '../services/autonomousJobs/scheduler.js';
import { parseCronToNextRun, isValidRecurrence } from '../services/eventScheduler.js';
import { getUserTimezone } from '../services/userTimezone.js';
import { asyncHandler, ServerError, failValidation } from '../lib/errorHandler.js';
import { createCosJobSchema, updateCosJobSchema, triggerCosJobSchema } from '../lib/validation.js';
import { getTaskDataInputCatalog } from '../lib/taskDataInputCatalog.js';
import { generatedJobTaskFields } from '../lib/autonomousJobTask.js';
import { describeReaimedValues } from '../lib/jobFormFields.js';
const router = Router();
// Validate a 5-field cron expression for job create/update. Throws a 400
// ServerError on a malformed field count or an unparseable expression.
function validateCronExpression(cronExpression) {
const parts = cronExpression.trim().split(/\s+/);
if (parts.length !== 5) {
throw new ServerError('cronExpression must be a 5-field cron expression (minute hour dayOfMonth month dayOfWeek)', { status: 400, code: 'VALIDATION_ERROR' });
}
let nextRun;
try {
nextRun = parseCronToNextRun(cronExpression, new Date(), 'UTC');
} catch (err) {
throw new ServerError(`Invalid cronExpression: ${err?.message || 'unable to parse'}`, { status: 400, code: 'VALIDATION_ERROR' });
}
if (nextRun === null) {
throw new ServerError('Invalid cronExpression: no valid run time could be determined', { status: 400, code: 'VALIDATION_ERROR' });
}
}
function validateRecurrenceRule(rule) {
if (!isValidRecurrence(rule)) {
throw new ServerError('Invalid cron recurrence rule', { status: 400, code: 'VALIDATION_ERROR' });
}
}
// GET /api/cos/jobs - Get all autonomous jobs
router.get('/jobs', asyncHandler(async (req, res) => {
const jobs = await autonomousJobs.getAllJobs();
const stats = await autonomousJobs.getJobStats();
const recurrenceJobs = jobs.filter(job => job.cronSchedule);
const timezone = recurrenceJobs.length ? await getUserTimezone() : null;
const jobsWithGates = jobs.map(j => {
const nextRun = j.cronSchedule && isValidRecurrence(j.cronSchedule)
? computeNextJobRun(j, timezone)
: null;
return {
...j,
hasGate: hasGate(j.id),
...(j.cronSchedule ? { nextRunAt: Number.isFinite(nextRun) ? new Date(nextRun).toISOString() : null } : {})
};
});
res.json({ jobs: jobsWithGates, stats, registeredGates: getRegisteredGates(), dataInputCatalog: getTaskDataInputCatalog() });
}));
// GET /api/cos/jobs/due - Get jobs that are due to run
router.get('/jobs/due', asyncHandler(async (req, res) => {
const due = await autonomousJobs.getDueJobs();
res.json({ due });
}));
// GET /api/cos/jobs/intervals - Get available interval options
router.get('/jobs/intervals', (req, res) => {
res.json({ intervals: autonomousJobs.INTERVAL_OPTIONS });
});
// GET /api/cos/jobs/allowed-commands - Get allowed commands for shell jobs
router.get('/jobs/allowed-commands', (req, res) => {
res.json({ commands: autonomousJobs.getAllowedCommands() });
});
// GET /api/cos/jobs/gates - Get all registered LLM gates
router.get('/jobs/gates', asyncHandler(async (req, res) => {
const gateIds = getRegisteredGates();
const settled = await Promise.allSettled(
gateIds.map(async (id) => {
const result = await checkJobGate(id);
return { jobId: id, ...result };
})
);
const results = settled.map((s, i) =>
s.status === 'fulfilled'
? s.value
: { jobId: gateIds[i], shouldRun: true, reason: `Gate error (fail-open): ${s.reason?.message || s.reason}`, error: true }
);
res.json({ gates: results });
}));
// POST /api/cos/jobs/:id/gate-check - Check a job's LLM gate without running
router.post('/jobs/:id/gate-check', asyncHandler(async (req, res) => {
const result = await checkJobGate(req.params.id);
res.json({ jobId: req.params.id, hasGate: hasGate(req.params.id), ...result });
}));
// GET /api/cos/jobs/:id - Get a single job
router.get('/jobs/:id', asyncHandler(async (req, res) => {
const job = await autonomousJobs.getJob(req.params.id);
if (!job) {
throw new ServerError('Job not found', { status: 404, code: 'NOT_FOUND' });
}
res.json(job);
}));
// POST /api/cos/jobs - Create a new autonomous job
router.post('/jobs', asyncHandler(async (req, res) => {
const parsedJob = createCosJobSchema.safeParse(req.body);
if (!parsedJob.success) failValidation(parsedJob);
const { name, description, category, type, interval, intervalMs, scheduledTime, cronExpression, cronSchedule, enabled, priority, autonomyLevel, promptTemplate, dataInputs, formFields, formValues, command, triggerAction, appId, taskMetadata, providerId, model, effort } = parsedJob.data;
if (type === 'shell' && !command?.trim()) {
throw new ServerError('command is required for shell jobs', { status: 400, code: 'VALIDATION_ERROR' });
}
if (!type || type === 'agent') {
if (!promptTemplate) {
throw new ServerError('promptTemplate is required for agent jobs', { status: 400, code: 'VALIDATION_ERROR' });
}
}
if (cronExpression) {
validateCronExpression(cronExpression);
}
if (cronSchedule) validateRecurrenceRule(cronSchedule);
// This hand-off is an ALLOWLIST, not a spread: a field added to the schema and
// missed here is silently dropped — the request still succeeds and the job is
// still created, just without it. Keep both lists in step.
const job = await autonomousJobs.createJob({
name, description, category, type, interval, intervalMs, scheduledTime, cronExpression, cronSchedule,
enabled, priority, autonomyLevel, promptTemplate, dataInputs, formFields, formValues, command, triggerAction, appId, taskMetadata, providerId, model, effort
});
res.json({ success: true, job });
}));
// PUT /api/cos/jobs/:id - Update a job
router.put('/jobs/:id', asyncHandler(async (req, res) => {
const parsedJobUpdate = updateCosJobSchema.safeParse(req.body);
if (!parsedJobUpdate.success) failValidation(parsedJobUpdate);
const { name, description, category, type, interval, intervalMs, scheduledTime, cronExpression, cronSchedule,
enabled, priority, autonomyLevel, promptTemplate, dataInputs, formFields, formValues, command, triggerAction, weekdaysOnly, appId, taskMetadata, providerId, model, effort } = parsedJobUpdate.data;
if (cronExpression) {
validateCronExpression(cronExpression);
}
if (cronSchedule) validateRecurrenceRule(cronSchedule);
// Same allowlist hazard as the create path above — `updateJob` skips only
// `undefined`, so a key missing HERE reads as "preserve", and an edit that
// clears a field looks like it saved while the old value stays on disk.
const job = await autonomousJobs.updateJob(req.params.id, {
name, description, category, type, interval, intervalMs, scheduledTime, cronExpression, cronSchedule,
enabled, priority, autonomyLevel, promptTemplate, dataInputs, formFields, formValues, command, triggerAction, weekdaysOnly, appId, taskMetadata, providerId, model, effort
});
if (!job) {
throw new ServerError('Job not found', { status: 404, code: 'NOT_FOUND' });
}
res.json({ success: true, job });
}));
// POST /api/cos/jobs/:id/toggle - Toggle job enabled/disabled
router.post('/jobs/:id/toggle', asyncHandler(async (req, res) => {
const job = await autonomousJobs.toggleJob(req.params.id);
if (!job) {
throw new ServerError('Job not found', { status: 404, code: 'NOT_FOUND' });
}
res.json({ success: true, job });
}));
// POST /api/cos/jobs/:id/trigger - Manually trigger a job now
router.post('/jobs/:id/trigger', asyncHandler(async (req, res) => {
const job = await autonomousJobs.getJob(req.params.id);
if (!job) {
throw new ServerError('Job not found', { status: 404, code: 'NOT_FOUND' });
}
const parsedTrigger = triggerCosJobSchema.safeParse(req.body || {});
if (!parsedTrigger.success) failValidation(parsedTrigger);
const { formValues: runFormValues } = parsedTrigger.data;
// Shell jobs execute the command directly
if (autonomousJobs.isShellJob(job)) {
const result = await autonomousJobs.executeShellJob(job);
return res.json({ success: result.success !== false, type: 'shell', status: 'completed', ...result });
}
// Script jobs run their built-in handler directly. This is the manual
// "Run now" path — the user explicitly requested it, so mark it foreground
// (`manual: true`) and any fan-out handler reports failures individually
// rather than coalescing them as unattended background work.
if (autonomousJobs.isScriptJob(job)) {
const result = await autonomousJobs.executeScriptJob(job, { manual: true });
return res.json({ success: (result?.success ?? true) !== false, type: 'script', status: 'completed', ...(result || {}) });
}
// Generate task and add to CoS internal task queue
// Job execution is recorded via the job:spawned event when the agent actually starts
// Manual triggers always bypass approval — the user explicitly requested execution
// A one-off run configuration re-aims THIS run only: the values are merged
// over the stored ones for prompt assembly and the job on disk is left alone,
// so the card's inputs are an ad-hoc dial rather than a silent edit. Merged
// (not replaced) so a field the caller didn't render keeps its saved value.
const jobForRun = runFormValues
? { ...job, formValues: { ...job.formValues, ...runFormValues } }
: job;
const task = await autonomousJobs.generateTaskFromJob(jobForRun);
const generated = generatedJobTaskFields(task);
// A re-aimed run is different work, and `addTask` dedupes on the description's
// first line + app — which the run configuration, appended to the END of the
// prompt, never reaches. Name the changed values there so aiming the same
// on-demand job somewhere else isn't swallowed as a duplicate of the run
// already queued (and reported to the caller as a success).
// Diff the MERGED values the run will actually use, not the request body: a
// caller that sends only the field it changed leaves the rest to the stored
// values, and diffing the partial body would report those as cleared.
const reaimed = runFormValues ? describeReaimedValues(job.formFields, job.formValues, jobForRun.formValues) : '';
// Forward the app scope + git-workflow options from the generated task's
// metadata. addTask maps these top-level keys back onto metadata; without
// them an app-scoped job triggered manually would run in the PortOS root
// (the scheduled path emits the full task object via task:ready and is unaffected).
const taskResult = await addTask({
// The generator's own field projection — the app scope, the git-workflow
// options, the provider/model/effort pins, the job:spawned markers and the
// no-change-success contract — so a manual trigger queues exactly what the
// scheduled path emits. Shared with the quota-burn lane
// (`quotaBurnInvoke.js`), which layers a different approval posture on top.
...generated,
...(reaimed ? { description: `${generated.description} — ${reaimed}` } : {}),
context: `Manually triggered autonomous job: ${job.name}`,
approvalRequired: false
}, 'internal', { suppressDequeue: true });
if (!taskResult?.id) {
res.json({
success: false,
type: 'agent',
status: 'skipped',
reason: 'Task was not queued (may be duplicate or blocked)'
});
return;
}
if (taskResult.duplicate) {
// A manual trigger is an explicit retry: a failure-blocked twin is revived
// with a fresh retry budget (#2614) instead of silently pointing the user
// at a task that will never run; an active twin is surfaced as-is.
if (taskResult.status === 'blocked') {
await reviveBlockedTask(taskResult.id, { priority: task.priority, metadata: task.metadata }, 'internal');
res.json({ success: true, type: 'agent', status: 'queued', taskId: taskResult.id, revived: true });
return;
}
res.json({
success: true,
type: 'agent',
status: 'skipped',
reason: 'An equivalent task is already queued',
taskId: taskResult.id,
duplicate: true
});
return;
}
// A manual trigger is an explicit Run now action, so use the same force-spawn
// path as the task-list play button. The ordinary `tasks:changed` listener
// intentionally applies autonomous scheduling gates to internal tasks and can
// leave this freshly-created task pending until a later evaluation or manual
// start. Keep the task queued when the spawn cannot proceed (for example, no
// capacity), but report the actionable reason instead of claiming it started.
const spawnResult = await forceSpawnTask(taskResult.id);
if (spawnResult?.error) {
res.json({
success: false,
type: 'agent',
status: 'skipped',
reason: spawnResult.error,
taskId: taskResult.id
});
return;
}
res.json({ success: true, type: 'agent', status: 'queued', started: true, taskId: taskResult.id });
}));
// DELETE /api/cos/jobs/:id - Delete a job
router.delete('/jobs/:id', asyncHandler(async (req, res) => {
const deleted = await autonomousJobs.deleteJob(req.params.id);
if (!deleted) {
throw new ServerError('Job not found', { status: 404, code: 'NOT_FOUND' });
}
res.json({ success: true });
}));
export default router;