@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/tasks/manifest.ts

@@ -0,0 +1,81 @@
+import type { PluginManifest } from '../../plugin-api/types';
+
+export const tasksManifest: PluginManifest = {
+  title: 'Scheduled Tasks',
+  summary:
+    "Schedule the agent to run on time-based triggers and deliver the result to the user's oracle chat room — runs happen in the background on the user's own oracle, not inline in the current conversation.",
+  whenToUse: [
+    "User wants to set up a reminder or recurring report ('every morning at 7', 'tomorrow at 5pm', 'remind me to …')",
+    'User wants the agent to monitor or track something on a schedule',
+    'User wants the agent to run a piece of work later, without sitting in the chat',
+    "User replies to a pending task-approval request ('yes, send it', 'no, drop it')",
+  ],
+  whenNotToUse: [
+    'One-shot action the user wants done right now — just do it inline',
+    'Real-time / streaming requirements — tasks run on a scheduled cadence, not on demand',
+  ],
+  examples: [
+    {
+      user: 'Every morning at 7 give me a one-paragraph crypto brief.',
+      thought:
+        'New recurring task. ALWAYS preview first so the user sees the schedule and confirms before anything is created.',
+      tool: 'preview_task',
+      args: {
+        title: 'Morning Crypto Brief',
+        intent:
+          'Summarize BTC, ETH, SOL movement over the last 24h. Highlight any moves > 5%. Keep it under 300 words, no trade recommendations.',
+        schedule: { kind: 'cron', cron: '0 7 * * *', timezone: 'UTC' },
+      },
+    },
+    {
+      user: 'Looks good, schedule it.',
+      thought:
+        'The user confirmed after seeing the preview. Create with the SAME title/intent/schedule.',
+      tool: 'create_task',
+      args: {
+        title: 'Morning Crypto Brief',
+        intent:
+          'Summarize BTC, ETH, SOL movement over the last 24h. Highlight any moves > 5%. Keep it under 300 words, no trade recommendations.',
+        schedule: { kind: 'cron', cron: '0 7 * * *', timezone: 'UTC' },
+        approval: 'never',
+      },
+    },
+    {
+      user: 'Every weekday at 9am post a LinkedIn update about our latest blog, but let me approve it before it goes out.',
+      thought:
+        "An action task — set approval to 'before-action' so each run asks the user in their room before it executes.",
+      tool: 'create_task',
+      args: {
+        title: 'Daily LinkedIn Update',
+        intent:
+          "Draft and publish a short LinkedIn post (under 120 words) about the company's latest blog article, with the article link.",
+        schedule: { kind: 'cron', cron: '0 9 * * 1-5', timezone: 'UTC' },
+        approval: 'before-action',
+      },
+    },
+    {
+      user: '(replying to an approval request) Yes — go ahead.',
+      thought:
+        'The user approved the pending run — record it; approval executes the run and delivers the result.',
+      tool: 'resolve_task_approval',
+      args: {
+        taskId: 'task_daily-linkedin-update_a1b2c3d4',
+        outcome: 'approved',
+      },
+    },
+    {
+      user: 'What tasks do I have?',
+      tool: 'list_my_tasks',
+      args: {},
+    },
+    {
+      user: 'Pause the crypto brief.',
+      tool: 'pause_task',
+      args: { taskId: 'task_morning-crypto-brief_a1b2c3d4' },
+    },
+  ],
+  category: 'automation',
+  visibility: 'on-demand',
+  stability: 'beta',
+  tags: ['scheduler', 'cron', 'automation', 'approval', 'background'],
+};

package/src/plugins/tasks/middleware.ts

@@ -0,0 +1,219 @@
+/**
+ * The task approval gate — the Workers port of the Node runtime's task-room
+ * middleware. On every model call it checks whether any of the current user's
+ * tasks is waiting on a `before-action` approval and, when one is, appends a
+ * system-prompt hint so the model treats the user's reply as the decision.
+ *
+ * Differences from Node, by design of the Workers approval flow:
+ *   - There are no dedicated task rooms or room→session bindings — pending
+ *     approvals live on the task records themselves (`pendingApprovalAt`), so
+ *     the gate reads them straight off `OracleTasksSurface.list()`.
+ *   - The gate never resolves an approval itself: on Workers, resolving an
+ *     approval EXECUTES the run (a full agent turn), which does not belong
+ *     inside a model-call wrapper. Plain yes/no replies are still classified
+ *     deterministically (`classifyReplyFast`) — the classification shapes the
+ *     hint, and the model records the decision through the
+ *     `resolve_task_approval` tool.
+ *
+ * Never short-circuits the model and never posts to Matrix — system-prompt
+ * hints only. Any internal error degrades to a plain pass-through.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+import { createMiddleware, type AgentMiddleware } from 'langchain';
+import type { Logger, OracleTasksSurface } from '../../plugin-api/types';
+import { pendingApprovalOf } from '../../tasks/store';
+
+const APPROVE = new Set([
+  'yes',
+  'y',
+  'yes please',
+  'approve',
+  'approved',
+  'approve it',
+  'i approve',
+  'ok',
+  'okay',
+  'ok do it',
+  'okay do it',
+  'do it',
+  'go',
+  'go ahead',
+  'send',
+  'send it',
+  'yes send it',
+  'ship',
+  'ship it',
+  'lgtm',
+  'looks good',
+  'sure',
+  'confirm',
+  'confirmed',
+  'proceed',
+]);
+
+const REJECT = new Set([
+  'no',
+  'n',
+  'nope',
+  'no thanks',
+  'cancel',
+  'cancel it',
+  'reject',
+  'rejected',
+  'reject it',
+  'i reject',
+  'decline',
+  'declined',
+  'stop',
+  "don't",
+  'dont',
+  "don't send",
+  'dont send',
+  "don't send it",
+  'discard',
+  'discard it',
+  'abort',
+]);
+
+export type FastReply = 'approved' | 'rejected' | 'other';
+
+/**
+ * EXACT-match classification of a reply to a pending approval. Normalization
+ * is lowercase + punctuation-to-space + whitespace collapse; anything that is
+ * not a verbatim member of the approve/reject sets is `'other'` — no prefix
+ * or length heuristics, so "ok so what does this do" never reads as approval.
+ */
+export function classifyReplyFast(text: string): FastReply {
+  const normalized = text
+    .toLowerCase()
+    .replace(/[.!?,;:]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (APPROVE.has(normalized)) return 'approved';
+  if (REJECT.has(normalized)) return 'rejected';
+  return 'other';
+}
+
+/**
+ * The hint to append when tasks are awaiting approval, or undefined when
+ * nothing is pending. Exported for direct unit testing.
+ */
+export async function computeApprovalHint(
+  surface: OracleTasksSurface,
+  lastHumanReply: string,
+): Promise<string | undefined> {
+  const records = await surface.list();
+  const pending = records.filter(
+    (record) =>
+      record.status === 'active' && pendingApprovalOf(record) !== undefined,
+  );
+  if (pending.length === 0) return undefined;
+
+  const decision = classifyReplyFast(lastHumanReply);
+  const only = pending.length === 1 ? pending[0] : undefined;
+  if (only && decision === 'approved') {
+    return (
+      `\n\n[Task approval gate] The user's reply APPROVES the pending run of task ${only.id} ("${only.title}"). ` +
+      'Call `resolve_task_approval` with outcome "approved" NOW — approval executes the run and delivers its result — then confirm to the user.'
+    );
+  }
+  if (only && decision === 'rejected') {
+    return (
+      `\n\n[Task approval gate] The user's reply DECLINES the pending run of task ${only.id} ("${only.title}"). ` +
+      'Call `resolve_task_approval` with outcome "declined" — nothing must be executed — then acknowledge briefly.'
+    );
+  }
+  const listing = pending
+    .map((record) => `${record.id} ("${record.title}")`)
+    .join(', ');
+  return (
+    `\n\n[Task approval gate] ${pending.length} task run(s) are waiting for the user's approval: ${listing}. ` +
+    'If this reply decides one of them (possibly with tweaks), call `resolve_task_approval` with the outcome — "approved" executes the run (pass requested tweaks in `note`), "declined" drops it. ' +
+    'Otherwise answer normally and remind the user of the pending approval.'
+  );
+}
+
+/** Defensive read of `{ user: { did } }` off the untyped invoke context. */
+export function userDidFromContext(context: unknown): string | undefined {
+  if (!context || typeof context !== 'object' || !('user' in context)) {
+    return undefined;
+  }
+  const { user } = context;
+  if (!user || typeof user !== 'object' || !('did' in user)) return undefined;
+  const { did } = user;
+  return typeof did === 'string' && did.length > 0 ? did : undefined;
+}
+
+/** Text of the latest HumanMessage — string content or joined text parts. */
+export function lastHumanText(messages: BaseMessage[]): string | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || message.type !== 'human') continue;
+    return textOfContent(message.content);
+  }
+  return null;
+}
+
+function textOfContent(content: unknown): string | null {
+  if (typeof content === 'string') {
+    const trimmed = content.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  if (!Array.isArray(content)) return null;
+  const parts: unknown[] = content;
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (typeof part === 'string') {
+      texts.push(part);
+      continue;
+    }
+    if (
+      part !== null &&
+      typeof part === 'object' &&
+      'text' in part &&
+      typeof part.text === 'string'
+    ) {
+      texts.push(part.text);
+    }
+  }
+  const joined = texts.join(' ').trim();
+  return joined.length > 0 ? joined : null;
+}
+
+export interface TaskApprovalGateOptions {
+  /**
+   * Per-user surface lookup. The plugin stashes each request's `ctx.tasks`
+   * keyed by user DID (see `tasks.plugin.ts`) because middlewares are built
+   * once at boot while the surface is per-user.
+   */
+  surfaceFor: (userDid: string) => OracleTasksSurface | undefined;
+  logger?: Logger;
+}
+
+export function createTaskApprovalGateMiddleware(
+  options: TaskApprovalGateOptions,
+): AgentMiddleware {
+  return createMiddleware({
+    name: 'TaskApprovalGateMiddleware',
+    wrapModelCall: async (request, handler) => {
+      let hint: string | undefined;
+      try {
+        const did = userDidFromContext(request.runtime.context);
+        const surface = did ? options.surfaceFor(did) : undefined;
+        if (surface) {
+          const text = lastHumanText(request.messages);
+          if (text) hint = await computeApprovalHint(surface, text);
+        }
+      } catch (err) {
+        options.logger?.warn(
+          `[TaskApprovalGate] gate errored — passing through: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (!hint) return handler(request);
+      return handler({
+        ...request,
+        systemMessage: request.systemMessage.concat(hint),
+      });
+    },
+  });
+}