@goodandready/dsh-cron 0.2.5 → 0.2.7

package/lib/external-api.js

@@ -0,0 +1,74 @@
+/**
+ * External REST surface under /dsh-cron/api/* (#54, ADR-0001).
+ *
+ * Everything a browser panel needs stays on the local, cross-origin-protected
+ * routes; this prefix exists for CI and host-side automation, so it is the only
+ * surface guarded by a bearer token. The token lives in the plugin settings as
+ * a masked value: an unconfigured token disables the surface (503) instead of
+ * leaving it open, and a wrong token is answered with 401.
+ *
+ * The operations themselves are shared with the panel routes (lib/api.js), so
+ * the confirmation gate for code-executing tasks and the config-owned refusals
+ * apply here exactly as they do over HTTP from the UI.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+import { sendJson } from './http-utils.js';
+import { handleExternalTaskRequest } from './api.js';
+
+/** Settings key that holds the bearer token. */
+export const API_TOKEN_SETTING_KEY = 'apiToken';
+
+/** Route prefix owned by this surface. */
+export const EXTERNAL_API_PREFIX = '/dsh-cron/api';
+
+/**
+ * Constant-time token comparison. Length is compared first because
+ * timingSafeEqual throws on buffers of different sizes; a length mismatch is
+ * not a secret worth hiding for a fixed-length token.
+ */
+export function tokenMatches(expected, provided) {
+  if (!expected || !provided) return false;
+  const a = Buffer.from(String(expected), 'utf8');
+  const b = Buffer.from(String(provided), 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Bearer token of a request, or an empty string when there is none. */
+export function readBearerToken(req) {
+  const header = String((req.headers && req.headers.authorization) || '');
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Guard the external prefix, then hand the request to the shared task
+ * operations. `getToken` is read per request so a settings change applies
+ * without a restart.
+ */
+export function createExternalApiHandler({ store, scheduler, getToken }) {
+  return async function handleExternalApi(req, res) {
+    const expected = typeof getToken === 'function' ? getToken() : '';
+    if (!expected) {
+      sendJson(res, 503, {
+        ok: false,
+        error: 'External API is disabled: set the "' + API_TOKEN_SETTING_KEY + '" setting to enable it',
+      });
+      return;
+    }
+    if (!tokenMatches(expected, readBearerToken(req))) {
+      sendJson(res, 401, { ok: false, error: 'Unauthorized' });
+      return;
+    }
+    const url = new URL(req.url, 'http://127.0.0.1');
+    // `url` must be inside the try: a malformed body (an unparseable schedule,
+    // for example) surfaces as a thrown error from the shared handlers, and an
+    // unhandled rejection here would answer nothing at all.
+    try {
+      await handleExternalTaskRequest({ store, scheduler, req, res, url });
+    } catch (err) {
+      sendJson(res, (err && err.statusCode) || 500, { ok: false, error: (err && err.message) || String(err) });
+    }
+  };
+}

package/lib/failure-inspector.js

@@ -0,0 +1,107 @@
+/**
+ * Failure inspector (#43): after a run fails, ask the model what went wrong and
+ * what to change in the task.
+ *
+ * The value is speed: instead of reading a stack trace or a wall of logs, the
+ * history entry carries a short diagnosis and a proposed prompt change the user
+ * can apply with one click. Nothing is applied automatically.
+ *
+ * Fail-open like the silent rule: no flag, no model, a failed call or an
+ * unreadable answer leave the run exactly as it was.
+ */
+
+import { askModel, parseJsonAnswer, resolveAskTarget } from './llm-ask.js';
+
+/** Agent-mediated tasks have a prompt worth revising. */
+export const INSPECTABLE_TASK_TYPES = ['llm', 'skill', 'workflow'];
+
+export function supportsInspection(task) {
+  const type = String((task && task.type) || 'llm');
+  return INSPECTABLE_TASK_TYPES.includes(type);
+}
+
+const SYSTEM_PROMPT = [
+  'You diagnose a failed scheduled agent task.',
+  'Answer with a single JSON object and nothing else:',
+  '{"diagnosis": "what went wrong, in one or two sentences", "suggestion": "a concrete improved prompt or configuration change", "confidence": "low"|"medium"|"high"}',
+  'Be specific and short. If the cause is unclear from the material, say so and set confidence to low.',
+].join(' ');
+
+export function buildInspectPrompt(task, runInfo) {
+  const error = String((runInfo && runInfo.error) || '').slice(0, 2000);
+  const output = String((runInfo && runInfo.output) || '').slice(0, 2000);
+  return [
+    `Task: ${task.title || 'scheduled task'} (type: ${task.type || 'llm'})`,
+    `Schedule: ${task.scheduleText || task.schedule || ''}`,
+    task.model ? `Model: ${task.model}` : '',
+    '',
+    'Current prompt:',
+    '```',
+    String(task.prompt || '').slice(0, 2000),
+    '```',
+    '',
+    `Result: ${(runInfo && runInfo.status) || 'error'}`,
+    'Error:',
+    '```',
+    error || '(no error text)',
+    '```',
+    output ? 'Last output:' : '',
+    output ? '```' : '',
+    output,
+    output ? '```' : '',
+  ].filter((line) => line !== '').join('\n');
+}
+
+/** Read a diagnosis out of a model answer; anything unusable is rejected. */
+export function readDiagnosis(text) {
+  const parsed = parseJsonAnswer(text);
+  if (!parsed || !parsed.diagnosis) return { ok: false, error: 'the model did not answer with a diagnosis' };
+  const confidence = ['low', 'medium', 'high'].includes(String(parsed.confidence || '').toLowerCase())
+    ? String(parsed.confidence).toLowerCase()
+    : 'low';
+  return {
+    ok: true,
+    diagnosis: String(parsed.diagnosis).slice(0, 1000),
+    suggestion: String(parsed.suggestion || '').slice(0, 2000),
+    confidence,
+  };
+}
+
+/**
+ * Inspect a failed run. Returns `{ inspected: true, diagnosis, suggestion,
+ * confidence }` or `{ inspected: false, error }` — never throws.
+ */
+export async function inspectFailure({ task, runInfo, ask, preferredModel, timeoutMs }) {
+  // Order matters: an inspection only ever concerns failed runs, so a healthy
+  // run must not produce a "no model available" warning.
+  const status = (runInfo && runInfo.status) || '';
+  if (status !== 'error' && status !== 'timeout') return { inspected: false };
+  if (!task || !task.inspectOnFailure) return { inspected: false };
+  if (!supportsInspection(task)) return { inspected: false, error: 'this task type has no prompt to revise' };
+  if (typeof ask !== 'function') return { inspected: false, error: 'no model is available for the inspection' };
+
+  try {
+    const result = await ask({
+      task,
+      prompt: buildInspectPrompt(task, runInfo),
+      system: SYSTEM_PROMPT,
+      preferredModel,
+      maxTokens: 400,
+      timeoutMs,
+    });
+    if (!result || !result.ok) return { inspected: false, error: (result && result.error) || 'the model call failed' };
+    const diagnosis = readDiagnosis(result.text);
+    if (!diagnosis.ok) return { inspected: false, error: diagnosis.error };
+    return { inspected: true, diagnosis: diagnosis.diagnosis, suggestion: diagnosis.suggestion, confidence: diagnosis.confidence };
+  } catch (err) {
+    return { inspected: false, error: (err && err.message) || String(err) };
+  }
+}
+
+/** Ask helper bound to a context, used by the scheduler. */
+export function makeInspectAsk(ctx) {
+  return async ({ prompt, system, preferredModel, maxTokens, timeoutMs, task }) => {
+    const target = resolveAskTarget(ctx, task || {}, preferredModel);
+    return askModel(ctx, { ...target, prompt, system, maxTokens, timeoutMs });
+  };
+}

package/lib/http-utils.js

@@ -85,3 +85,27 @@ export function pickPatchableFields(body, allowed) {
   }
   return patch;
 }
+
+export function sendJson(res, statusCode, data) {
+  res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+export function rejectCrossOrigin(req, res) {
+  if (isCrossOrigin(req)) {
+    sendJson(res, 403, { ok: false, error: 'Cross-origin request rejected' });
+    return true;
+  }
+  return false;
+}
+
+export 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. */