@goodandready/dsh-cron 0.2.5 → 0.2.7

package/lib/index.js

@@ -52,6 +52,20 @@ export {
   IMPORT_STRATEGIES,
 };
 import { deliverRun, CHANNEL_IDS, resolveDeliveryTimeoutMs, MIN_DELIVERY_TIMEOUT_MS } from './channels.js';
+import { sendJson, rejectCrossOrigin, readBody } from './http-utils.js';
+import { recipeRecommendations, recipesByCategory } from './recipes.js';
+import { applyTaskPatch, describeTaskPatch } from './task-patch.js';
+import { makeAsk } from './silent-rule.js';
+
+// The REST surface lives in lib/api.js. It is IMPORTED (the plugin body calls
+// it) and re-exported for tests and tools that import it from the entry point —
+// a bare re-export creates no local binding and the plugin then fails to load
+// with "createCronApiHandler is not defined".
+import { createCronApiHandler } from './api.js';
+import { createMetricsHandler } from './metrics.js';
+import { applyConfigSync, isConfigOwned, configOwnedMessage } from './config-jobs.js';
+import { createExternalApiHandler, EXTERNAL_API_PREFIX } from './external-api.js';
+export { createCronApiHandler };
 
 export const name = '@goodandready/dsh-cron';
 export const inject = ['tools', 'webServer', 'settings', 'llm', 'agents', 'agentDefaultModel', 'credentials'];
@@ -70,6 +84,8 @@ export const Config = z.object({
   // --- Delivery channels (#20-#23, #26, #28, #47) ---
   template: z.string().default('').description('Global notification template; placeholders: {title} {status} {output} {error} {duration} {schedule} {time} {tokens} {cost}'),
   channelTemplates: z.object({}).default({}).description('Per-channel template overrides keyed by channel id'),
+  silentRuleModel: z.string().default('').description('Model used to evaluate a task silent rule (empty = the task model)'),
+  inspectorModel: z.string().default('').description('Model used to diagnose failed runs (empty = the task model)'),
   deliveryTimeoutMs: z.number().min(MIN_DELIVERY_TIMEOUT_MS).default(15000).description('Per-channel delivery timeout in ms (minimum 1000); a slower endpoint is recorded as a failure and does not block other channels or the next tick'),
   discordWebhookUrl: z.string().default('').description('Discord webhook URL'),
   slackWebhookUrl: z.string().default('').description('Slack incoming webhook URL'),
@@ -84,35 +100,22 @@ export const Config = z.object({
   giteaBaseUrl: z.string().default('').description('Gitea base URL for alert issues'),
   giteaRepo: z.string().default('').description('Gitea repository (owner/name) for alert issues'),
   giteaTokenRef: z.string().default('').description('Credential name for the Gitea API token'),
+  // --- Declarative jobs (#50, ADR-0001) ---
+  // The array is intentionally permissive: each entry is validated on its own
+  // with a precise message (see lib/config-jobs.js), so one broken entry cannot
+  // reject the whole profile config. Declared jobs are owned by the config:
+  // they are created or updated at startup, and removed when they disappear
+  // from the file. Tasks created in the UI, over the API or by an agent tool
+  // are never touched.
+  jobs: z.array(z.any()).default([]).description('Static jobs owned by the config; each entry needs id, title, schedule and (for agent types) prompt'),
+  // --- External REST API (#54, ADR-0001) ---
+  apiToken: z.string().role('secret').default('').description('Bearer token for the external /dsh-cron/api/* surface (empty = the surface answers 503)'),
 });
 
 
-function sendJson(res, statusCode, data) {
-  res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(data));
-}
-
-function rejectCrossOrigin(req, res) {
-  if (isCrossOrigin(req)) {
-    sendJson(res, 403, { ok: false, error: 'Cross-origin request rejected' });
-    return true;
-  }
-  return false;
-}
-
-async function readBody(req, res) {
-  try {
-    return { body: await parseJsonBody(req) };
-  } catch (err) {
-    sendJson(res, err.statusCode || 400, { ok: false, error: err.message });
-    return { error: true };
-  }
-}
-
-/** Settings keys synchronized between the store and the settings service. */
 export const SETTINGS_SYNC_KEYS = [
   'botToken', 'botTokenRef', 'chatId', 'notifyTelegram', 'onlyOnFailure', 'kanbanBaseUrl',
-  'template', 'channelTemplates', 'deliveryTimeoutMs',
+  'template', 'channelTemplates', 'deliveryTimeoutMs', 'silentRuleModel', 'inspectorModel',
   'discordWebhookUrl', 'slackWebhookUrl',
   'ntfyUrl', 'ntfyTopic', 'ntfyTokenRef',
   'barkServerUrl', 'barkKey',
@@ -120,6 +123,7 @@ export const SETTINGS_SYNC_KEYS = [
   'pushplusUrl',
   'ttsBaseUrl',
   'giteaBaseUrl', 'giteaRepo', 'giteaTokenRef',
+  'apiToken',
 ];
 
 /**
@@ -181,341 +185,6 @@ export function sanitizeSettingsPayload(body) {
   return payload;
 }
 
-/**
- * Shared implementation for the /dsh-cron/tasks... and /dsh-cron/action...
- * route families — the #66 alias is kept alive by the same code path instead
- * of a duplicated handler.
- *
- * IMPORTANT: prefix routes must be registered WITHOUT a trailing slash —
- * with one, the core degrades matching to exact-path equality and every
- * deeper path unrouted (#96). Exported for unit tests.
- */
-export function createCronApiHandler(store, scheduler, collection) {
-  return async function handleCronApi(req, res) {
-    try {
-      const url = new URL(req.url, 'http://127.0.0.1');
-      const parts = url.pathname.split('/').filter(Boolean);
-      const scope = parts[1]; // 'tasks' | 'action'
-      const id = parts[2];
-      const action = parts[3];
-
-      // Collection level: /dsh-cron/tasks (list + create)
-      if (!id) {
-        if (scope === 'action' || !collection) {
-          sendJson(res, 405, { ok: false, error: 'Method not allowed' });
-          return;
-        }
-        if (req.method === 'GET') {
-          const status = url.searchParams.get('status') || 'all';
-          const query = url.searchParams.get('query') || '';
-          const list = store.list({ status, query }).map((t) => ({
-            ...t,
-            running: scheduler.isRunning(t.id),
-            runningSince: scheduler.runningSince(t.id),
-          }));
-          const stats = store.getAggregatedStats();
-          sendJson(res, 200, { ok: true, tasks: list, recommendations: collection.recommendations, stats });
-          return;
-        }
-        if (req.method === 'POST') {
-          if (rejectCrossOrigin(req, res)) return;
-          const { body, error } = await readBody(req, res);
-          if (error) return;
-          if (!body.title || !body.schedule || !body.prompt) {
-            sendJson(res, 400, { ok: false, error: 'Fields title, schedule and prompt are required' });
-            return;
-          }
-          const taskType = normalizeTaskType(body.type);
-          if (CODE_EXECUTING_TYPES.includes(taskType) && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
-            sendJson(res, 403, { ok: false, error: `Creating ${taskType} tasks over HTTP requires the x-dsh-cron-confirm: script header` });
-            return;
-          }
-          const typeError = validateTaskType(taskType, body);
-          if (typeError) {
-            sendJson(res, 400, { ok: false, error: typeError });
-            return;
-          }
-          const parsed = parseScheduleExpression(body.schedule);
-          // A client-supplied id must not shadow the collection routes under
-          // /dsh-cron/tasks, otherwise that task could never be fetched or
-          // deleted again (#42 review finding).
-          if (body.id && RESERVED_TASK_IDS.includes(String(body.id))) {
-            sendJson(res, 400, { ok: false, error: `Task id "${body.id}" is reserved` });
-            return;
-          }
-          const current = body.id ? store.get(body.id) : null;
-          const resolvedStatus = body.status || (current ? current.status : 'active');
-
-          const task = store.set({
-            id: body.id,
-            title: body.title,
-            schedule: parsed.cronPattern || body.schedule,
-            scheduleText: body.scheduleText || parsed.humanText,
-            prompt: body.prompt,
-            type: taskType,
-            delivery: body.delivery || 'current',
-            status: resolvedStatus,
-            provider: body.provider || undefined,
-            model: body.model || undefined,
-            notifyTelegram: body.notifyTelegram !== undefined ? Boolean(body.notifyTelegram) : (current ? current.notifyTelegram : false),
-            onlyOnFailure: body.onlyOnFailure !== undefined ? Boolean(body.onlyOnFailure) : (current ? current.onlyOnFailure : false),
-            timeoutSeconds: body.timeoutSeconds !== undefined ? Number(body.timeoutSeconds) : (current ? current.timeoutSeconds : 1800),
-            overlapPolicy: body.overlapPolicy || (current ? current.overlapPolicy : 'skip'),
-            kanbanMode: body.kanbanMode || (current ? current.kanbanMode : 'none'),
-            timezone: body.timezone !== undefined ? String(body.timezone).trim() : (current ? current.timezone : ''),
-            misfirePolicy: ['skip', 'runOnce', 'catchUpAll'].includes(body.misfirePolicy) ? body.misfirePolicy : (current ? (current.misfirePolicy || 'skip') : 'skip'),
-            maxRetries: body.maxRetries !== undefined ? Math.max(0, Number(body.maxRetries) || 0) : (current ? (Number(current.maxRetries) || 0) : 0),
-            retryBackoffMs: body.retryBackoffMs !== undefined ? Math.max(1000, Number(body.retryBackoffMs) || 30000) : (current ? (Number(current.retryBackoffMs) || 30000) : 30000),
-            permissionPreset: ['default', 'read-only', 'workspace-write', 'full'].includes(body.permissionPreset) ? body.permissionPreset : (current ? (current.permissionPreset || 'default') : 'default'),
-            env: body.env && typeof body.env === 'object' ? body.env : (current ? current.env : undefined),
-            cwd: body.cwd !== undefined ? String(body.cwd).trim() : (current ? current.cwd : ''),
-            channels: Array.isArray(body.channels)
-              ? body.channels.filter((c) => CHANNEL_IDS.includes(c))
-              : (current ? current.channels : undefined),
-            template: body.template !== undefined ? String(body.template) : (current ? current.template : ''),
-            workspaceId: body.workspaceId !== undefined ? String(body.workspaceId).trim() : (current ? current.workspaceId : ''),
-            worktree: body.worktree !== undefined ? Boolean(body.worktree) : (current ? Boolean(current.worktree) : false),
-            keepWorktree: body.keepWorktree !== undefined ? Boolean(body.keepWorktree) : (current ? Boolean(current.keepWorktree) : false),
-            httpMethod: body.httpMethod ? String(body.httpMethod).toUpperCase() : (current ? current.httpMethod : 'GET'),
-            httpUrl: body.httpUrl !== undefined ? String(body.httpUrl).trim() : (current ? current.httpUrl : ''),
-            httpHeaders: body.httpHeaders !== undefined ? body.httpHeaders : (current ? current.httpHeaders : undefined),
-            httpBody: body.httpBody !== undefined ? String(body.httpBody) : (current ? current.httpBody : ''),
-            sshProfileId: body.sshProfileId !== undefined ? String(body.sshProfileId).trim() : (current ? current.sshProfileId : ''),
-            sshTarget: body.sshTarget !== undefined ? String(body.sshTarget).trim() : (current ? current.sshTarget : ''),
-            sshPort: body.sshPort !== undefined ? Number(body.sshPort) || 0 : (current ? current.sshPort : 0),
-            sshKeyPath: body.sshKeyPath !== undefined ? String(body.sshKeyPath).trim() : (current ? current.sshKeyPath : ''),
-            dockerImage: body.dockerImage !== undefined ? String(body.dockerImage).trim() : (current ? current.dockerImage : ''),
-            pythonPath: body.pythonPath !== undefined ? String(body.pythonPath).trim() : (current ? current.pythonPath : ''),
-            nodePath: body.nodePath !== undefined ? String(body.nodePath).trim() : (current ? current.nodePath : ''),
-            skillName: body.skillName !== undefined ? String(body.skillName).trim() : (current ? current.skillName : ''),
-            workflowName: body.workflowName !== undefined ? String(body.workflowName).trim() : (current ? current.workflowName : ''),
-            oneShot: Boolean(parsed.isOneShot || body.oneShot),
-          });
-          if (task.status === 'active') {
-            scheduler.scheduleTask(task);
-          } else {
-            scheduler.pauseTask(task.id);
-          }
-          sendJson(res, 200, { ok: true, task });
-          return;
-        }
-        sendJson(res, 405, { ok: false, error: 'Method not allowed' });
-        return;
-      }
-
-      // Item level: /dsh-cron/{tasks|action}/:id[/:action]
-      if (req.method !== 'GET' && rejectCrossOrigin(req, res)) return;
-
-      // Export/import are collection operations that live under /tasks/:id/…,
-      // so they are matched before the generic id handling below.
-      if (id === 'export' && req.method === 'GET') {
-        const doc = buildTaskExport(store.list({ status: 'all' }));
-        sendJson(res, 200, { ok: true, document: doc, count: doc.tasks.length });
-        return;
-      }
-
-      if (id === 'import' && req.method === 'POST') {
-        const { body, error } = await readBody(req, res);
-        if (error) return;
-        const strategy = IMPORT_STRATEGIES.includes(body && body.strategy) ? body.strategy : 'skip';
-        const checked = validateImportDocument(body && body.document);
-        if (!checked.ok) {
-          sendJson(res, 400, { ok: false, error: checked.error });
-          return;
-        }
-        // The import file is external input: importing code-executing tasks
-        // needs the same explicit confirmation that creating one over HTTP
-        // needs, otherwise a hand-edited file would bypass that gate (#86).
-        if (hasCodeExecutingTask(checked.tasks) && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
-          sendJson(res, 403, {
-            ok: false,
-            error: `Importing code-executing tasks over HTTP requires the ${SCRIPT_CONFIRM_HEADER}: script header`,
-          });
-          return;
-        }
-        const existingIds = store.list({ status: 'all' }).map((x) => x.id);
-        const plan = planImport(checked.tasks, existingIds, strategy);
-        if (body && body.dryRun) {
-          sendJson(res, 200, {
-            ok: true,
-            dryRun: true,
-            strategy: plan.strategy,
-            summary: { add: plan.add.length, replace: plan.replace.length, skip: plan.skip.length },
-            codeExecuting: hasCodeExecutingTask(plan.add.concat(plan.replace)),
-          });
-          return;
-        }
-        // Every imported task is paused (the file's status is ignored) and every
-        // id that replaced an existing task is disarmed: writing "paused" to the
-        // store does not stop an already-armed croner job, so the scheduler must
-        // be told explicitly. The writes are rolled back if one of them throws,
-        // so a failed import cannot leave the store half-updated.
-        const imported = [];
-        const rollback = [];
-        const disarm = [];
-        try {
-          for (const task of plan.add) {
-            const before = store.get(task.id);
-            const created = store.set({ ...task, id: task.id || randomUUID(), status: 'paused', updatedAt: Date.now() });
-            imported.push(created);
-            rollback.push({ id: created.id, previous: before || null });
-            disarm.push(created.id);
-          }
-          for (const task of plan.replace) {
-            const before = store.get(task.id);
-            if (!before) continue;
-            const replaced = store.set({ ...task, id: task.id, status: 'paused', updatedAt: Date.now() });
-            imported.push(replaced);
-            rollback.push({ id: replaced.id, previous: before });
-            disarm.push(replaced.id);
-          }
-        } catch (writeErr) {
-          for (const entry of rollback.reverse()) {
-            try {
-              if (entry.previous) store.set(entry.previous);
-              else store.delete(entry.id);
-            } catch (_) {}
-          }
-          sendJson(res, 500, { ok: false, error: `Import failed and was rolled back: ${writeErr.message}` });
-          return;
-        }
-        // Disarm outside the write transaction: pauseTask is idempotent and a
-        // failure here must not undo a successful import.
-        for (const id of disarm) {
-          try { scheduler.pauseTask(id); } catch (err) { console.error('[dsh-cron] import: could not pause task', id + ':', err.message); }
-        }
-        sendJson(res, 200, {
-          ok: true,
-          imported: imported.length,
-          summary: { add: plan.add.length, replace: plan.replace.length, skip: plan.skip.length },
-          tasks: imported,
-        });
-        return;
-      }
-
-      if (req.method === 'GET' && (action === 'history' || !action)) {
-        const limit = parseInt(url.searchParams.get('limit') || '20', 10);
-        sendJson(res, 200, { ok: true, history: store.getHistory(id, limit) });
-        return;
-      }
-
-      if (req.method === 'POST' && action === 'run') {
-        if (!store.get(id)) {
-          sendJson(res, 404, { ok: false, error: 'Task not found' });
-          return;
-        }
-        await scheduler.triggerManualRun(id);
-        sendJson(res, 200, { ok: true, task: store.get(id) });
-        return;
-      }
-
-      if (req.method === 'POST' && action === 'duplicate') {
-        const source = store.get(id);
-        if (!source) {
-          sendJson(res, 404, { ok: false, error: 'Task not found' });
-          return;
-        }
-        const copy = buildDuplicateTask(source, { id: randomUUID() });
-        store.set(copy);
-        // A copy starts paused: it must never fire on its own before the user
-        // reviews the schedule (a duplicated one-shot may point at a past time).
-        scheduler.pauseTask(copy.id);
-        sendJson(res, 200, { ok: true, task: copy });
-        return;
-      }
-
-      if (req.method === 'POST' && action === 'pause') {
-        const task = scheduler.pauseTask(id);
-        if (!task) {
-          sendJson(res, 404, { ok: false, error: 'Task not found' });
-          return;
-        }
-        sendJson(res, 200, { ok: true, task });
-        return;
-      }
-
-      if (req.method === 'POST' && action === 'resume') {
-        const task = scheduler.resumeTask(id);
-        if (!task) {
-          sendJson(res, 404, { ok: false, error: 'Task not found' });
-          return;
-        }
-        sendJson(res, 200, { ok: true, task });
-        return;
-      }
-
-      if (req.method === 'POST' && (action === 'toggle' || (!action && url.searchParams.get('action') === 'toggle'))) {
-        const current = store.get(id);
-        if (!current) {
-          sendJson(res, 404, { ok: false, error: 'Task not found' });
-          return;
-        }
-        const task = scheduler.toggleTask(id);
-        sendJson(res, 200, { ok: true, task });
-        return;
-      }
-
-      if (req.method === 'PATCH') {
-        const current = store.get(id);
-        if (!current) {
-          sendJson(res, 404, { ok: false, error: 'Task not found' });
-          return;
-        }
-        const { body, error } = await readBody(req, res);
-        if (error) return;
-        // Whitelist patchable fields so stats/timestamps stay server-owned (#90)
-        const patchData = pickPatchableFields(body, PATCHABLE_TASK_FIELDS);
-        if (patchData.type !== undefined) {
-          patchData.type = normalizeTaskType(patchData.type);
-          const switchingToCode = CODE_EXECUTING_TYPES.includes(patchData.type)
-            && !CODE_EXECUTING_TYPES.includes(current.type);
-          if (switchingToCode && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
-            sendJson(res, 403, { ok: false, error: `Switching a task to the ${patchData.type} type over HTTP requires the x-dsh-cron-confirm: script header` });
-            return;
-          }
-          const typeError = validateTaskType(patchData.type, { ...current, ...patchData });
-          if (typeError) {
-            sendJson(res, 400, { ok: false, error: typeError });
-            return;
-          }
-        }
-        if (patchData.schedule) {
-          const parsed = parseScheduleExpression(patchData.schedule);
-          patchData.schedule = parsed.cronPattern || patchData.schedule;
-          patchData.scheduleText = body.scheduleText || parsed.humanText;
-          patchData.oneShot = Boolean(parsed.isOneShot || body.oneShot);
-        }
-        const task = store.set({ ...current, ...patchData, id });
-        if (task.status === 'active') {
-          scheduler.scheduleTask(task);
-        } else {
-          scheduler.pauseTask(id);
-        }
-        sendJson(res, 200, { ok: true, task });
-        return;
-      }
-
-      if (req.method === 'DELETE' || (req.method === 'POST' && action === 'delete')) {
-        const current = store.get(id);
-        if (current) {
-          scheduler.pauseTask(id);
-          store.delete(id);
-        }
-        sendJson(res, 200, { ok: true });
-        return;
-      }
-
-      sendJson(res, 405, { ok: false, error: 'Method not allowed' });
-    } catch (err) {
-      sendJson(res, err.statusCode || 500, { ok: false, error: err.message });
-    }
-  };
-}
-
-/**
- * Single implementation behind the cron_create_task / cron_schedule_task
- * alias pair (#70, #92). Exported for unit tests.
- */
 export function executeCreateTask(store, scheduler, args) {
   const taskType = normalizeTaskType(args.type);
   const typeError = validateTaskType(taskType, args);
@@ -578,6 +247,10 @@ export const createTaskParameters = {
   type: { type: 'string', enum: TASK_TYPES, description: 'Task type: llm | script | node | python | http | ssh | docker | skill | workflow' },
   delivery: { type: 'string', enum: ['current', 'isolated'], description: 'Run mode: current (in the current chat) or isolated (separate session)' },
   provider: { type: 'string', description: 'Model provider (optional)' },
+  inspectOnFailure: { type: 'boolean', description: 'Diagnose failed runs with a model and store the diagnosis with the run (agent tasks)' },
+  silentRule: { type: 'string', description: 'Plain-language condition for staying silent on a successful run (script/node/python/http tasks)' },
+  fallbackModel: { type: 'string', description: 'Model tried once more when the primary model fails (llm/skill/workflow tasks)' },
+  fallbackProvider: { type: 'string', description: 'Provider for the fallback model (defaults to the task provider)' },
   model: { type: 'string', description: 'Model (optional)' },
   timezone: { type: 'string', description: 'IANA time zone for the schedule, e.g. "Europe/Berlin" (optional, default = server local)' },
   notifyTelegram: { type: 'boolean', description: 'Send the run report to Telegram' },
@@ -631,6 +304,7 @@ export function apply(ctx, config) {
     maxConcurrent: config && config.maxConcurrent,
     defaultTimezone: config && config.defaultTimezone,
     resolveSecrets: (settings) => resolveTelegramSecrets(ctx, settings),
+    askModel: makeAsk(ctx),
     deliver: (task, runInfo, settings) => deliverRun({
       task,
       runInfo,
@@ -667,6 +341,18 @@ export function apply(ctx, config) {
     }
   });
 
+  // #50: jobs declared in the profile config belong to the config. The sync
+  // runs before the scheduler starts and also when the section is gone: a
+  // config that dropped its jobs must still retire the tasks it used to own.
+  // A broken entry is reported and skipped, never fatal.
+  try {
+    const configJobs = Array.isArray(config && config.jobs) ? config.jobs : [];
+    const summary = applyConfigSync({ store, scheduler, entries: configJobs });
+    console.log('[dsh-cron] config jobs synced: ' + JSON.stringify(summary));
+  } catch (err) {
+    console.error('[dsh-cron] config job sync failed:', err.message);
+  }
+
   scheduler.start();
 
   // Heartbeat / dead man's snitch (#16): an optional periodic GET ping so an
@@ -688,35 +374,8 @@ export function apply(ctx, config) {
     };
   }, 'dsh-cron: lifecycle');
 
-  const recommendations = [
-    {
-      id: 'rec_daily_digest',
-      title: 'Daily digest',
-      schedule: '0 8 * * 1-5',
-      scheduleText: 'Weekdays at 08:00',
-      prompt: 'Prepare a brief morning digest: review the list of active tasks, open Gitea tickets and outline the key priorities for today.',
-      description: 'Start every weekday with a summary of calendar, unread mail and priorities',
-      icon: 'bell'
-    },
-    {
-      id: 'rec_weekly_review',
-      title: 'Weekly review',
-      schedule: '0 16 * * 5',
-      scheduleText: 'Fridays at 16:00',
-      prompt: 'Prepare a weekly report on the work done: the list of closed tasks, created PRs and the current status of ongoing projects.',
-      description: 'Every Friday create a short report on the completed work',
-      icon: 'clipboard'
-    },
-    {
-      id: 'rec_monitor_status',
-      title: 'Follow-up monitor',
-      schedule: '0 9 * * 1-5',
-      scheduleText: 'Weekdays at 09:00',
-      prompt: 'Review recent project activity, build statuses and flag everything that requires developer attention.',
-      description: 'Review recent project activity and flag anything that needs your attention',
-      icon: 'activity'
-    }
-  ];
+  // #48: the recipe hub is the single source of the panel's suggestions.
+  const recommendations = recipeRecommendations();
 
   // 1. REST API — collection (list/create) + item actions in one prefix
   // handler per route family; registered WITHOUT the trailing slash (#96)
@@ -733,6 +392,27 @@ export function apply(ctx, config) {
     handler: createCronApiHandler(store, scheduler, null)
   }), 'dsh-cron: /action/:id/:action');
 
+  // GET /dsh-cron/metrics (#53) — Prometheus text exposition
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-cron/metrics',
+    handler: createMetricsHandler({ store, scheduler })
+  }), 'dsh-cron: /metrics');
+
+  // External REST API under /dsh-cron/api/* (#54, ADR-0001): the only surface
+  // guarded by a bearer token, so CI and host automation can drive the
+  // scheduler without a browser session. The token is read per request, so a
+  // settings change applies without a restart.
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: EXTERNAL_API_PREFIX,
+    handler: createExternalApiHandler({
+      store,
+      scheduler,
+      getToken: () => store.getSettings().apiToken || ''
+    })
+  }), 'dsh-cron: /api[...]');
+
   // GET /dsh-cron/models
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
@@ -783,6 +463,25 @@ export function apply(ctx, config) {
     }
   }), 'dsh-cron: /settings');
 
+  // GET /dsh-cron/recipes (#48): the built-in recipe catalog.
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-cron/recipes',
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+          return;
+        }
+        const categories = recipesByCategory();
+        const recipes = categories.reduce((acc, category) => acc.concat(category.recipes), []);
+        sendJson(res, 200, { ok: true, categories, recipes });
+      } catch (err) {
+        sendJson(res, err.statusCode || 500, { ok: false, error: err.message });
+      }
+    }
+  }), 'dsh-cron: /recipes');
+
   // GET /dsh-cron/heartbeat (#16): liveness probe for external monitors.
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
@@ -943,6 +642,10 @@ export function apply(ctx, config) {
       render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
+      // A config-owned task cannot be paused from here either: the next start
+      // would resume it, and the agent would have reported a change that never
+      // happened (#50 review finding).
+      if (isConfigOwned(store.get(args.id))) return { success: false, message: configOwnedMessage(args.id) };
       const task = scheduler.pauseTask(args.id);
       if (!task) return { success: false, message: 'Task not found' };
       return { success: true, message: `Task "${task.title}" paused` };
@@ -967,6 +670,7 @@ export function apply(ctx, config) {
       render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
+      if (isConfigOwned(store.get(args.id))) return { success: false, message: configOwnedMessage(args.id) };
       const task = scheduler.resumeTask(args.id);
       if (!task) return { success: false, message: 'Task not found' };
       return { success: true, message: `Task "${task.title}" resumed (${task.scheduleText})` };
@@ -991,12 +695,96 @@ export function apply(ctx, config) {
       render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
+      // Deleting a config-owned task would also drop its run history, and the
+      // task would come back at the next start without it.
+      if (isConfigOwned(store.get(args.id))) return { success: false, message: configOwnedMessage(args.id) };
       scheduler.pauseTask(args.id);
       const ok = store.delete(args.id);
       return { success: ok, message: ok ? 'Task deleted' : 'Task not found' };
     }
   }));
 
+  ctx.tools.register(defineTool({
+    name: 'cron_get_task',
+    description: 'Read the full configuration of one scheduled task, including fields that are not visible in the task list',
+    parameters: {
+      id: { type: 'string', description: 'Task identifier', required: true }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' },
+          task: { type: 'object', additionalProperties: true }
+        }
+      },
+      render: (_args, val) => [{ type: 'text', text: val.message }]
+    },
+    execute: async (args) => {
+      const task = store.get(args.id);
+      if (!task) return { success: false, message: 'Task not found' };
+      const summary = [
+        `Task "${task.title}" (${task.id})`,
+        `type: ${task.type || 'llm'}`,
+        `schedule: ${task.scheduleText || task.schedule}`,
+        `status: ${task.status}`,
+        task.type === 'llm' || !task.type ? `model: ${task.model || '(default)'}${task.fallbackModel ? ` (fallback: ${task.fallbackModel})` : ''}` : null,
+        `channels: ${Array.isArray(task.channels) && task.channels.length ? task.channels.join(', ') : '(legacy flags)'}`,
+        `prompt: ${String(task.prompt || '').slice(0, 500)}`,
+      ].filter(Boolean).join(String.fromCharCode(10));
+      return { success: true, message: summary, task };
+    }
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'cron_update_task',
+    description: 'Change an existing scheduled task. Ask the user what to change first. Switching a task to a code-executing type (script/node/python/ssh/docker) is refused unless confirmCodeSwitch is set, which requires the user to have agreed explicitly. Only the documented task fields can be changed.',
+    parameters: {
+      id: { type: 'string', description: 'Task identifier', required: true },
+      confirmCodeSwitch: { type: 'boolean', description: 'Set to true only after the user explicitly agreed to switch this task into a type that executes code' },
+      title: { type: 'string', description: 'New title' },
+      schedule: { type: 'string', description: 'New schedule (cron expression or interval)' },
+      prompt: { type: 'string', description: 'New prompt or command' },
+      type: { type: 'string', enum: TASK_TYPES, description: 'New execution type' },
+      model: { type: 'string', description: 'New model for agent tasks' },
+      fallbackModel: { type: 'string', description: 'New fallback model' },
+      provider: { type: 'string', description: 'New provider' },
+      channels: { type: 'array', items: { type: 'string', enum: CHANNEL_IDS }, description: 'New delivery channels' },
+      template: { type: 'string', description: 'New message template' },
+      onlyOnFailure: { type: 'boolean', description: 'Deliver only on failures' },
+      timeoutSeconds: { type: 'number', description: 'New execution timeout in seconds' },
+      overlapPolicy: { type: 'string', enum: ['skip', 'queue', 'replace'], description: 'New overlap policy' },
+      maxRetries: { type: 'number', description: 'New retry count' },
+      kanbanMode: { type: 'string', enum: ['none', 'on_failure', 'always'], description: 'New Kanban policy' },
+      timezone: { type: 'string', description: 'New IANA time zone' },
+      cwd: { type: 'string', description: 'New working directory' },
+      env: { type: 'object', additionalProperties: true, description: 'New environment variables (KEY: value)' }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' }
+        }
+      },
+      render: (_args, val) => [{ type: 'text', text: val.message }]
+    },
+    execute: async (args) => {
+      const { id, confirmCodeSwitch, ...patch } = args || {};
+      if (!id) return { success: false, message: 'A task id is required' };
+      const result = applyTaskPatch({ store, scheduler, id, body: patch, allowCodeSwitch: confirmCodeSwitch === true });
+      if (!result.ok) return { success: false, message: result.error };
+      return {
+        success: true,
+        message: `Task "${result.task.title}" updated (${result.task.scheduleText || result.task.schedule}). Changed: ${describeTaskPatch(result.task, result.patch)}`,
+      };
+    }
+  }));
+
   ctx.tools.register(defineTool({
     name: 'cron_run_task',
     description: 'Trigger a task immediately, out of band',