@elizaos/plugin-personal-assistant 2.0.3-beta.5 → 2.0.3-beta.7

package/dist/actions/scheduled-task.js

@@ -0,0 +1,661 @@
+import { hasLifeOpsAccess } from "../lifeops/access.js";
+import { resolvePendingPromptsStore } from "../lifeops/pending-prompts/store.js";
+import { LifeOpsRepository } from "../lifeops/repository.js";
+import { getScheduledTaskRunner } from "../lifeops/scheduled-task/service.js";
+import { OWNER_OPERATION_VALIDATE } from "./life.js";
+const SUBACTIONS = [
+  "list",
+  "get",
+  "create",
+  "update",
+  "snooze",
+  "skip",
+  "complete",
+  "acknowledge",
+  "dismiss",
+  "cancel",
+  "reopen",
+  "history"
+];
+const SCHEDULED_TASK_KINDS = [
+  "reminder",
+  "checkin",
+  "followup",
+  "approval",
+  "recap",
+  "watcher",
+  "output",
+  "custom"
+];
+const SCHEDULED_TASK_STATUSES = [
+  "scheduled",
+  "fired",
+  "acknowledged",
+  "completed",
+  "skipped",
+  "expired",
+  "failed",
+  "dismissed"
+];
+const SCHEDULED_TASK_SUBJECT_KINDS = [
+  "entity",
+  "relationship",
+  "thread",
+  "document",
+  "calendar_event",
+  "self"
+];
+function normalizeSubaction(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim().toLowerCase();
+  return SUBACTIONS.includes(trimmed) ? trimmed : null;
+}
+function resolveSubaction(params) {
+  const aliasKeys = [
+    "action",
+    "subaction",
+    "op",
+    "operation"
+  ];
+  for (const key of aliasKeys) {
+    const candidate = params[key];
+    const normalized = normalizeSubaction(candidate);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+function normalizeKind(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim().toLowerCase();
+  return SCHEDULED_TASK_KINDS.includes(trimmed) ? trimmed : void 0;
+}
+function normalizeStatus(value) {
+  if (Array.isArray(value)) {
+    const values = value.map(
+      (entry) => typeof entry === "string" ? entry.trim().toLowerCase() : ""
+    ).filter(
+      (entry) => SCHEDULED_TASK_STATUSES.includes(entry)
+    );
+    return values.length > 0 ? values : void 0;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim().toLowerCase();
+    return SCHEDULED_TASK_STATUSES.includes(trimmed) ? trimmed : void 0;
+  }
+  return void 0;
+}
+function normalizeSubjectKind(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim().toLowerCase();
+  return SCHEDULED_TASK_SUBJECT_KINDS.includes(trimmed) ? trimmed : void 0;
+}
+function buildSubject(kind, id) {
+  if (!kind || typeof id !== "string" || id.trim().length === 0) {
+    return void 0;
+  }
+  return { kind, id: id.trim() };
+}
+function buildFilter(params) {
+  const filter = {};
+  const kind = normalizeKind(params.kind);
+  if (kind) filter.kind = kind;
+  const status = normalizeStatus(params.status);
+  if (status !== void 0) filter.status = status;
+  const subject = buildSubject(
+    normalizeSubjectKind(params.subjectKind),
+    params.subjectId
+  );
+  if (subject) filter.subject = subject;
+  if (params.ownerVisibleOnly === true) filter.ownerVisibleOnly = true;
+  return filter;
+}
+function makeRunnerScope(runtime, message) {
+  const agentId = runtime.agentId;
+  const runner = getScheduledTaskRunner(runtime, { agentId });
+  return {
+    runtime,
+    runner,
+    agentId,
+    roomId: typeof message.roomId === "string" ? message.roomId : null
+  };
+}
+function getParams(options) {
+  const raw = options?.parameters;
+  if (raw && typeof raw === "object") {
+    return raw;
+  }
+  return {};
+}
+function isTrigger(value) {
+  if (!value || typeof value !== "object") return false;
+  const kind = value.kind;
+  return kind === "once" || kind === "cron" || kind === "interval" || kind === "relative_to_anchor" || kind === "during_window" || kind === "event" || kind === "manual" || kind === "after_task";
+}
+async function handleList(scope, params) {
+  const tasks = await scope.runner.list(buildFilter(params));
+  return {
+    success: true,
+    text: `${tasks.length} scheduled task${tasks.length === 1 ? "" : "s"} match.`,
+    data: { subaction: "list", tasks }
+  };
+}
+async function handleGet(scope, params) {
+  const taskId = params.taskId?.trim();
+  if (!taskId) {
+    return {
+      success: false,
+      text: "I need a taskId to fetch a scheduled task.",
+      data: { subaction: "get", error: "MISSING_TASK_ID" }
+    };
+  }
+  const all = await scope.runner.list();
+  const task = all.find((entry) => entry.taskId === taskId) ?? null;
+  if (!task) {
+    return {
+      success: false,
+      text: `No scheduled task found with id ${taskId}.`,
+      data: { subaction: "get", error: "NOT_FOUND" }
+    };
+  }
+  return {
+    success: true,
+    text: `Found scheduled task ${task.taskId} (${task.kind}, ${task.state.status}).`,
+    data: { subaction: "get", task }
+  };
+}
+async function handleCreate(scope, params) {
+  const promptInstructions = typeof params.promptInstructions === "string" ? params.promptInstructions.trim() : "";
+  if (promptInstructions.length === 0) {
+    return {
+      success: false,
+      text: "I need promptInstructions describing what the scheduled task should do.",
+      data: { subaction: "create", error: "MISSING_PROMPT_INSTRUCTIONS" }
+    };
+  }
+  if (!isTrigger(params.trigger)) {
+    return {
+      success: false,
+      text: "I need a trigger (once / cron / interval / event / manual / \u2026) to schedule a task.",
+      data: { subaction: "create", error: "MISSING_TRIGGER" }
+    };
+  }
+  const kind = normalizeKind(params.kind) ?? "custom";
+  const priority = params.priority ?? "medium";
+  const subject = buildSubject(
+    normalizeSubjectKind(params.subjectKind),
+    params.subjectId
+  );
+  const metadata = {
+    ...params.metadata ?? {},
+    ...scope.roomId && params.completionCheck ? { pendingPromptRoomId: scope.roomId } : {}
+  };
+  const created = await scope.runner.schedule({
+    kind,
+    promptInstructions,
+    trigger: params.trigger,
+    priority,
+    ...params.contextRequest ? { contextRequest: params.contextRequest } : {},
+    ...params.shouldFire ? { shouldFire: params.shouldFire } : {},
+    ...params.completionCheck ? { completionCheck: params.completionCheck } : {},
+    ...params.escalation ? { escalation: params.escalation } : {},
+    ...params.output ? { output: params.output } : scope.roomId ? {
+      output: {
+        destination: "channel",
+        target: `in_app:${scope.roomId}`
+      }
+    } : {},
+    ...params.pipeline ? { pipeline: params.pipeline } : {},
+    ...Object.keys(metadata).length > 0 ? { metadata } : {},
+    ...params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : {},
+    respectsGlobalPause: params.respectsGlobalPause ?? true,
+    source: params.source ?? "user_chat",
+    createdBy: scope.agentId,
+    ownerVisible: params.ownerVisible ?? true,
+    ...subject ? { subject } : {}
+  });
+  return {
+    success: true,
+    text: `Scheduled ${kind} task ${created.taskId}.`,
+    data: { subaction: "create", task: created }
+  };
+}
+async function handleUpdate(scope, params) {
+  const taskId = params.taskId?.trim();
+  if (!taskId) {
+    return {
+      success: false,
+      text: "I need a taskId to update a scheduled task.",
+      data: { subaction: "update", error: "MISSING_TASK_ID" }
+    };
+  }
+  if (!params.patch || typeof params.patch !== "object") {
+    return {
+      success: false,
+      text: "I need a `patch` object describing the fields to update.",
+      data: { subaction: "update", error: "MISSING_PATCH" }
+    };
+  }
+  const updated = await scope.runner.apply(taskId, "edit", params.patch);
+  return {
+    success: true,
+    text: `Updated scheduled task ${taskId}.`,
+    data: { subaction: "update", task: updated }
+  };
+}
+async function handleSnooze(scope, params) {
+  const taskId = params.taskId?.trim();
+  if (!taskId) {
+    return {
+      success: false,
+      text: "I need a taskId to snooze a scheduled task.",
+      data: { subaction: "snooze", error: "MISSING_TASK_ID" }
+    };
+  }
+  const minutes = typeof params.minutes === "number" && Number.isFinite(params.minutes) ? params.minutes : void 0;
+  const untilIso = typeof params.untilIso === "string" && params.untilIso.trim().length > 0 ? params.untilIso.trim() : void 0;
+  if (minutes === void 0 && untilIso === void 0) {
+    return {
+      success: false,
+      text: "I need either `minutes` or `untilIso` to snooze.",
+      data: { subaction: "snooze", error: "MISSING_SNOOZE_TARGET" }
+    };
+  }
+  const snoozed = await scope.runner.apply(taskId, "snooze", {
+    ...minutes !== void 0 ? { minutes } : {},
+    ...untilIso ? { untilIso } : {}
+  });
+  await resolvePendingPromptsStore(scope.runtime).forgetTask(taskId);
+  return {
+    success: true,
+    text: `Snoozed scheduled task ${taskId}.`,
+    data: { subaction: "snooze", task: snoozed }
+  };
+}
+async function handleAcknowledge(scope, params) {
+  const taskId = params.taskId?.trim();
+  if (!taskId) {
+    return {
+      success: false,
+      text: "I need a taskId to acknowledge a scheduled task.",
+      data: { subaction: "acknowledge", error: "MISSING_TASK_ID" }
+    };
+  }
+  await scope.runner.apply(taskId, "acknowledge");
+  const updated = await scope.runner.evaluateCompletion(taskId, {
+    acknowledged: true
+  });
+  await resolvePendingPromptsStore(scope.runtime).forgetTask(taskId);
+  return {
+    success: true,
+    text: `Acknowledged scheduled task ${taskId}.`,
+    data: { subaction: "acknowledge", task: updated }
+  };
+}
+async function handleVerbWithReason(scope, params, verb, label) {
+  const taskId = params.taskId?.trim();
+  if (!taskId) {
+    return {
+      success: false,
+      text: `I need a taskId to ${label} a scheduled task.`,
+      data: { subaction: verb, error: "MISSING_TASK_ID" }
+    };
+  }
+  const updated = await scope.runner.apply(
+    taskId,
+    verb,
+    params.reason ? { reason: params.reason } : void 0
+  );
+  if (verb === "skip" || verb === "complete" || verb === "dismiss") {
+    await resolvePendingPromptsStore(scope.runtime).forgetTask(taskId);
+  }
+  return {
+    success: true,
+    text: `${label.charAt(0).toUpperCase()}${label.slice(1)}d scheduled task ${taskId}.`,
+    data: { subaction: verb, task: updated }
+  };
+}
+async function handleHistory(scope, params) {
+  const taskId = params.taskId?.trim();
+  if (!taskId) {
+    return {
+      success: false,
+      text: "I need a taskId to read history (the state log is partitioned per task).",
+      data: { subaction: "history", error: "MISSING_TASK_ID" }
+    };
+  }
+  const repo = new LifeOpsRepository(scope.runtime);
+  const limit = typeof params.limit === "number" && Number.isFinite(params.limit) && params.limit > 0 ? Math.floor(params.limit) : 100;
+  const entries = await repo.listScheduledTaskLog({
+    agentId: scope.agentId,
+    taskId,
+    ...params.sinceIso ? { sinceIso: params.sinceIso } : {},
+    ...params.untilHistoryIso ? { untilIso: params.untilHistoryIso } : {},
+    excludeRollups: params.includeRollups !== true,
+    limit
+  });
+  return {
+    success: true,
+    text: `${entries.length} scheduled-task log row${entries.length === 1 ? "" : "s"}.`,
+    data: { subaction: "history", entries }
+  };
+}
+const examples = [
+  [
+    {
+      name: "{{name1}}",
+      content: { text: "What follow-ups are scheduled for me right now?" }
+    },
+    {
+      name: "{{agentName}}",
+      content: {
+        text: "Listing scheduled tasks of kind=followup.",
+        action: "SCHEDULED_TASKS"
+      }
+    }
+  ],
+  [
+    {
+      name: "{{name1}}",
+      content: { text: "Snooze that reminder 30 minutes." }
+    },
+    {
+      name: "{{agentName}}",
+      content: {
+        text: "Snoozing the active reminder for 30 minutes.",
+        action: "SCHEDULED_TASKS"
+      }
+    }
+  ],
+  [
+    {
+      name: "{{name1}}",
+      content: { text: "Mark the daily check-in done." }
+    },
+    {
+      name: "{{agentName}}",
+      content: {
+        text: "Marking the check-in as completed.",
+        action: "SCHEDULED_TASKS"
+      }
+    }
+  ]
+];
+const scheduledTaskAction = {
+  name: "SCHEDULED_TASKS",
+  similes: [
+    "SCHEDULED_TASK",
+    "REMINDER_TASK",
+    "SCHEDULED_REMINDER",
+    "SCHEDULED_FOLLOWUP",
+    "TASK_SNOOZE",
+    "TASK_COMPLETE",
+    "TASK_ACKNOWLEDGE",
+    "TASK_DISMISS",
+    // ENTITY simile names; canonical execution surface is SCHEDULED_TASKS.
+    "ADD_FOLLOW_UP",
+    "COMPLETE_FOLLOW_UP",
+    "FOLLOW_UP_LIST",
+    "DAYS_SINCE",
+    "LIST_OVERDUE_FOLLOWUPS",
+    "MARK_FOLLOWUP_DONE",
+    "SET_FOLLOWUP_THRESHOLD",
+    // PRD action-catalog aliases. The PRD's NotificationIntent and
+    // event-decision flows fold onto SCHEDULED_TASKS with escalation policy.
+    // See packages/docs/action-prd-map.md.
+    "EVENT_SET_DECISION_DEADLINE",
+    "EVENT_TRACK_ASSET_DEADLINES",
+    "NOTIFICATION_CREATE_INTENT",
+    "NOTIFICATION_ACKNOWLEDGE",
+    "NOTIFICATION_ESCALATE"
+  ],
+  tags: [
+    "domain:lifeops",
+    "domain:reminders",
+    "resource:scheduled-item",
+    "resource:scheduled-task",
+    "capability:read",
+    "capability:write",
+    "capability:update",
+    "capability:delete",
+    "capability:schedule",
+    "surface:internal"
+  ],
+  description: "Owner scheduled-item surface backed by LifeOps ScheduledTask records. Kinds: reminder, checkin, followup, approval, recap, watcher, output, custom. Ops: list|get|create|update|snooze|skip|complete|acknowledge|dismiss|cancel|reopen|history.",
+  descriptionCompressed: "LifeOps scheduled items list|get|create|update|snooze|skip|complete|ack|dismiss|cancel|history",
+  routingHint: 'reminder/checkin/followup/approval/recap/watcher/output state ("snooze that reminder", "follow-ups today", "complete check-in", "scheduled-item history") -> SCHEDULED_TASKS; coding/project/agent task threads -> TASKS/plugin-task-coordinator; per-occurrence complete/skip/snooze next occurrence -> OWNER_REMINDERS/OWNER_TODOS/OWNER_ROUTINES',
+  contexts: [
+    "tasks",
+    "automation",
+    "reminders",
+    "followups",
+    "calendar",
+    "productivity"
+  ],
+  roleGate: { minRole: "OWNER" },
+  suppressPostActionContinuation: true,
+  validate: OWNER_OPERATION_VALIDATE,
+  parameters: [
+    {
+      name: "action",
+      description: "ScheduledTask op: list|get|create|update|snooze|skip|complete|acknowledge|dismiss|cancel|reopen|history.",
+      schema: { type: "string", enum: [...SUBACTIONS] }
+    },
+    {
+      name: "taskId",
+      description: "Target taskId for get/update/snooze/skip/complete/acknowledge/dismiss/cancel/reopen/history.",
+      schema: { type: "string" }
+    },
+    {
+      name: "kind",
+      description: "ScheduledTaskKind create/filter: reminder|checkin|followup|approval|recap|watcher|output|custom.",
+      schema: { type: "string" }
+    },
+    {
+      name: "status",
+      description: "List status filter string|string[]: scheduled|fired|acknowledged|completed|skipped|expired|failed|dismissed.",
+      schema: { type: "string" }
+    },
+    {
+      name: "subjectKind",
+      description: "ScheduledTaskSubject.kind: entity|relationship|thread|document|calendar_event|self.",
+      schema: { type: "string" }
+    },
+    {
+      name: "subjectId",
+      description: "ScheduledTaskSubject.id paired with subjectKind.",
+      schema: { type: "string" }
+    },
+    {
+      name: "ownerVisibleOnly",
+      description: "true: list ownerVisible tasks only.",
+      schema: { type: "boolean" }
+    },
+    {
+      name: "promptInstructions",
+      description: "create-only: promptInstructions stored on ScheduledTask.",
+      schema: { type: "string" }
+    },
+    {
+      name: "trigger",
+      description: "create-only: ScheduledTaskTrigger once/cron/interval/relative_to_anchor/during_window/event/manual/after_task.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "contextRequest",
+      description: "create-only: contextRequest facts/entities/relationships/recent task states/event payload.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "shouldFire",
+      description: "create-only: structural shouldFire gates; gate refs, no prompt text conditions.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "completionCheck",
+      description: "create-only: structural completionCheck: user_replied_within|user_acknowledged|subject_updated|health_signal_observed.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "output",
+      description: "create-only: output destination/target, e.g. channel -> in_app:<roomId>.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "pipeline",
+      description: "create-only: pipeline child ScheduledTask refs: onComplete|onSkip|onFail.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "escalation",
+      description: "create-only: escalation ladder/channel steps.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "metadata",
+      description: "create-only: structured task metadata.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "idempotencyKey",
+      description: "create-only: stable dedupe key for repeated schedules.",
+      schema: { type: "string" }
+    },
+    {
+      name: "priority",
+      description: "create-only: low|medium|high; default medium.",
+      schema: { type: "string", enum: ["low", "medium", "high"] }
+    },
+    {
+      name: "respectsGlobalPause",
+      description: "create-only: true skips during global pause.",
+      schema: { type: "boolean" }
+    },
+    {
+      name: "ownerVisible",
+      description: "create-only: true shows in owner views.",
+      schema: { type: "boolean" }
+    },
+    {
+      name: "source",
+      description: "create-only: source default_pack|user_chat|first_run|plugin.",
+      schema: { type: "string" }
+    },
+    {
+      name: "minutes",
+      description: "snooze-only: defer next fire N minutes.",
+      schema: { type: "number" }
+    },
+    {
+      name: "untilIso",
+      description: "snooze-only: defer next fire until ISO-8601 timestamp.",
+      schema: { type: "string" }
+    },
+    {
+      name: "reason",
+      description: "skip/complete/acknowledge/dismiss/reopen: reason on state log.",
+      schema: { type: "string" }
+    },
+    {
+      name: "patch",
+      description: "update-only: shallow patch editable ScheduledTask fields.",
+      schema: { type: "object", additionalProperties: true }
+    },
+    {
+      name: "sinceIso",
+      description: "history-only: occurredAtIso >= ISO-8601.",
+      schema: { type: "string" }
+    },
+    {
+      name: "untilHistoryIso",
+      description: "history-only: occurredAtIso <= ISO-8601.",
+      schema: { type: "string" }
+    },
+    {
+      name: "includeRollups",
+      description: "history-only: include daily rollups; default false/raw only.",
+      schema: { type: "boolean" }
+    },
+    {
+      name: "limit",
+      description: "history-only: row cap (default 100).",
+      schema: { type: "number" }
+    }
+  ],
+  examples,
+  handler: async (runtime, message, _state, options, callback) => {
+    if (!await hasLifeOpsAccess(runtime, message)) {
+      const text = "Scheduled-task control is restricted to the owner.";
+      await callback?.({ text });
+      return { text, success: false, data: { error: "PERMISSION_DENIED" } };
+    }
+    const params = getParams(options);
+    const subaction = resolveSubaction(params);
+    if (!subaction) {
+      return {
+        success: false,
+        text: "Tell me which task operation you want: list, get, create, update, snooze, skip, complete, acknowledge, dismiss, cancel, reopen, or history.",
+        data: { error: "MISSING_SUBACTION" }
+      };
+    }
+    const scope = makeRunnerScope(runtime, message);
+    let result;
+    switch (subaction) {
+      case "list":
+        result = await handleList(scope, params);
+        break;
+      case "get":
+        result = await handleGet(scope, params);
+        break;
+      case "create":
+        result = await handleCreate(scope, params);
+        break;
+      case "update":
+        result = await handleUpdate(scope, params);
+        break;
+      case "snooze":
+        result = await handleSnooze(scope, params);
+        break;
+      case "skip":
+        result = await handleVerbWithReason(scope, params, "skip", "skip");
+        break;
+      case "complete":
+        result = await handleVerbWithReason(
+          scope,
+          params,
+          "complete",
+          "complete"
+        );
+        break;
+      case "acknowledge":
+        result = await handleAcknowledge(scope, params);
+        break;
+      case "dismiss":
+      case "cancel":
+        result = await handleVerbWithReason(
+          scope,
+          params,
+          "dismiss",
+          "dismiss"
+        );
+        break;
+      case "reopen":
+        result = await handleVerbWithReason(scope, params, "reopen", "reopen");
+        break;
+      case "history":
+        result = await handleHistory(scope, params);
+        break;
+    }
+    if (result.text) {
+      await callback?.({
+        text: result.text,
+        source: "action",
+        action: "SCHEDULED_TASKS"
+      });
+    }
+    return result;
+  }
+};
+export {
+  scheduledTaskAction
+};
+//# sourceMappingURL=scheduled-task.js.map