Cron: add scheduler, wakeups, and run history

2025-12-13 02:34:11 +00:00
parent 572d17f46b
commit f9409cbe43
26 changed files with 3401 additions and 342 deletions
--- a/src/gateway/protocol/index.ts
+++ b/src/gateway/protocol/index.ts
@@ -9,6 +9,21 @@ import {
  ChatSendParamsSchema,
  type ConnectParams,
  ConnectParamsSchema,
+  type CronAddParams,
+  CronAddParamsSchema,
+  type CronJob,
+  CronJobSchema,
+  type CronListParams,
+  CronListParamsSchema,
+  type CronRemoveParams,
+  CronRemoveParamsSchema,
+  type CronRunLogEntry,
+  type CronRunParams,
+  CronRunParamsSchema,
+  type CronRunsParams,
+  CronRunsParamsSchema,
+  type CronUpdateParams,
+  CronUpdateParamsSchema,
  ErrorCodes,
  type ErrorShape,
  ErrorShapeSchema,
@@ -36,6 +51,8 @@ import {
  StateVersionSchema,
  type TickEvent,
  TickEventSchema,
+  type WakeParams,
+  WakeParamsSchema,
 } from "./schema.js";

 const ajv = new (
@@ -54,6 +71,21 @@ export const validateRequestFrame =
  ajv.compile<RequestFrame>(RequestFrameSchema);
 export const validateSendParams = ajv.compile(SendParamsSchema);
 export const validateAgentParams = ajv.compile(AgentParamsSchema);
+export const validateWakeParams = ajv.compile<WakeParams>(WakeParamsSchema);
+export const validateCronListParams =
+  ajv.compile<CronListParams>(CronListParamsSchema);
+export const validateCronAddParams =
+  ajv.compile<CronAddParams>(CronAddParamsSchema);
+export const validateCronUpdateParams = ajv.compile<CronUpdateParams>(
+  CronUpdateParamsSchema,
+);
+export const validateCronRemoveParams = ajv.compile<CronRemoveParams>(
+  CronRemoveParamsSchema,
+);
+export const validateCronRunParams =
+  ajv.compile<CronRunParams>(CronRunParamsSchema);
+export const validateCronRunsParams =
+  ajv.compile<CronRunsParams>(CronRunsParamsSchema);
 export const validateChatHistoryParams = ajv.compile(ChatHistoryParamsSchema);
 export const validateChatSendParams = ajv.compile(ChatSendParamsSchema);
 export const validateChatEvent = ajv.compile(ChatEventSchema);
@@ -80,6 +112,14 @@ export {
  ChatEventSchema,
  SendParamsSchema,
  AgentParamsSchema,
+  WakeParamsSchema,
+  CronJobSchema,
+  CronListParamsSchema,
+  CronAddParamsSchema,
+  CronUpdateParamsSchema,
+  CronRemoveParamsSchema,
+  CronRunParamsSchema,
+  CronRunsParamsSchema,
  ChatHistoryParamsSchema,
  ChatSendParamsSchema,
  TickEventSchema,
@@ -105,4 +145,13 @@ export type {
  ChatEvent,
  TickEvent,
  ShutdownEvent,
+  WakeParams,
+  CronJob,
+  CronListParams,
+  CronAddParams,
+  CronUpdateParams,
+  CronRemoveParams,
+  CronRunParams,
+  CronRunsParams,
+  CronRunLogEntry,
 };
--- a/src/gateway/protocol/schema.ts
+++ b/src/gateway/protocol/schema.ts
@@ -203,6 +203,185 @@ export const AgentParamsSchema = Type.Object(
  { additionalProperties: false },
 );

+export const WakeParamsSchema = Type.Object(
+  {
+    mode: Type.Union([Type.Literal("now"), Type.Literal("next-heartbeat")]),
+    text: NonEmptyString,
+  },
+  { additionalProperties: false },
+);
+
+export const CronScheduleSchema = Type.Union([
+  Type.Object(
+    {
+      kind: Type.Literal("at"),
+      atMs: Type.Integer({ minimum: 0 }),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      kind: Type.Literal("every"),
+      everyMs: Type.Integer({ minimum: 1 }),
+      anchorMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      kind: Type.Literal("cron"),
+      expr: NonEmptyString,
+      tz: Type.Optional(Type.String()),
+    },
+    { additionalProperties: false },
+  ),
+]);
+
+export const CronPayloadSchema = Type.Union([
+  Type.Object(
+    {
+      kind: Type.Literal("systemEvent"),
+      text: NonEmptyString,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      kind: Type.Literal("agentTurn"),
+      message: NonEmptyString,
+      thinking: Type.Optional(Type.String()),
+      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
+      deliver: Type.Optional(Type.Boolean()),
+      channel: Type.Optional(
+        Type.Union([
+          Type.Literal("last"),
+          Type.Literal("whatsapp"),
+          Type.Literal("telegram"),
+        ]),
+      ),
+      to: Type.Optional(Type.String()),
+      bestEffortDeliver: Type.Optional(Type.Boolean()),
+    },
+    { additionalProperties: false },
+  ),
+]);
+
+export const CronIsolationSchema = Type.Object(
+  {
+    postToMain: Type.Optional(Type.Boolean()),
+    postToMainPrefix: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
+export const CronJobStateSchema = Type.Object(
+  {
+    nextRunAtMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    runningAtMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastRunAtMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastStatus: Type.Optional(
+      Type.Union([
+        Type.Literal("ok"),
+        Type.Literal("error"),
+        Type.Literal("skipped"),
+      ]),
+    ),
+    lastError: Type.Optional(Type.String()),
+    lastDurationMs: Type.Optional(Type.Integer({ minimum: 0 })),
+  },
+  { additionalProperties: false },
+);
+
+export const CronJobSchema = Type.Object(
+  {
+    id: NonEmptyString,
+    name: Type.Optional(Type.String()),
+    enabled: Type.Boolean(),
+    createdAtMs: Type.Integer({ minimum: 0 }),
+    updatedAtMs: Type.Integer({ minimum: 0 }),
+    schedule: CronScheduleSchema,
+    sessionTarget: Type.Union([Type.Literal("main"), Type.Literal("isolated")]),
+    wakeMode: Type.Union([Type.Literal("next-heartbeat"), Type.Literal("now")]),
+    payload: CronPayloadSchema,
+    isolation: Type.Optional(CronIsolationSchema),
+    state: CronJobStateSchema,
+  },
+  { additionalProperties: false },
+);
+
+export const CronListParamsSchema = Type.Object(
+  {
+    includeDisabled: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+);
+
+export const CronAddParamsSchema = Type.Object(
+  {
+    name: Type.Optional(Type.String()),
+    enabled: Type.Optional(Type.Boolean()),
+    schedule: CronScheduleSchema,
+    sessionTarget: Type.Union([Type.Literal("main"), Type.Literal("isolated")]),
+    wakeMode: Type.Union([Type.Literal("next-heartbeat"), Type.Literal("now")]),
+    payload: CronPayloadSchema,
+    isolation: Type.Optional(CronIsolationSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const CronUpdateParamsSchema = Type.Object(
+  {
+    id: NonEmptyString,
+    patch: Type.Partial(CronAddParamsSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const CronRemoveParamsSchema = Type.Object(
+  {
+    id: NonEmptyString,
+  },
+  { additionalProperties: false },
+);
+
+export const CronRunParamsSchema = Type.Object(
+  {
+    id: NonEmptyString,
+    mode: Type.Optional(
+      Type.Union([Type.Literal("due"), Type.Literal("force")]),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const CronRunsParamsSchema = Type.Object(
+  {
+    id: Type.Optional(NonEmptyString),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 5000 })),
+  },
+  { additionalProperties: false },
+);
+
+export const CronRunLogEntrySchema = Type.Object(
+  {
+    ts: Type.Integer({ minimum: 0 }),
+    jobId: NonEmptyString,
+    action: Type.Literal("finished"),
+    status: Type.Optional(
+      Type.Union([
+        Type.Literal("ok"),
+        Type.Literal("error"),
+        Type.Literal("skipped"),
+      ]),
+    ),
+    error: Type.Optional(Type.String()),
+    runAtMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    durationMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    nextRunAtMs: Type.Optional(Type.Integer({ minimum: 0 })),
+  },
+  { additionalProperties: false },
+);
+
 // WebChat/WebSocket-native chat methods
 export const ChatHistoryParamsSchema = Type.Object(
  {
@@ -256,6 +435,15 @@ export const ProtocolSchemas: Record<string, TSchema> = {
  AgentEvent: AgentEventSchema,
  SendParams: SendParamsSchema,
  AgentParams: AgentParamsSchema,
+  WakeParams: WakeParamsSchema,
+  CronJob: CronJobSchema,
+  CronListParams: CronListParamsSchema,
+  CronAddParams: CronAddParamsSchema,
+  CronUpdateParams: CronUpdateParamsSchema,
+  CronRemoveParams: CronRemoveParamsSchema,
+  CronRunParams: CronRunParamsSchema,
+  CronRunsParams: CronRunsParamsSchema,
+  CronRunLogEntry: CronRunLogEntrySchema,
  ChatHistoryParams: ChatHistoryParamsSchema,
  ChatSendParams: ChatSendParamsSchema,
  ChatEvent: ChatEventSchema,
@@ -276,6 +464,15 @@ export type PresenceEntry = Static<typeof PresenceEntrySchema>;
 export type ErrorShape = Static<typeof ErrorShapeSchema>;
 export type StateVersion = Static<typeof StateVersionSchema>;
 export type AgentEvent = Static<typeof AgentEventSchema>;
+export type WakeParams = Static<typeof WakeParamsSchema>;
+export type CronJob = Static<typeof CronJobSchema>;
+export type CronListParams = Static<typeof CronListParamsSchema>;
+export type CronAddParams = Static<typeof CronAddParamsSchema>;
+export type CronUpdateParams = Static<typeof CronUpdateParamsSchema>;
+export type CronRemoveParams = Static<typeof CronRemoveParamsSchema>;
+export type CronRunParams = Static<typeof CronRunParamsSchema>;
+export type CronRunsParams = Static<typeof CronRunsParamsSchema>;
+export type CronRunLogEntry = Static<typeof CronRunLogEntrySchema>;
 export type ChatEvent = Static<typeof ChatEventSchema>;
 export type TickEvent = Static<typeof TickEventSchema>;
 export type ShutdownEvent = Static<typeof ShutdownEventSchema>;