loopengine 0.1.68 → 0.1.70

package/README.md

@@ -121,6 +121,7 @@ code changes or redeploy needed for most of it:
 | **Tools** | Your hand-written tools, tools from integrations (e.g. [Composio](https://composio.dev)) and subagents, with whether each call runs on its own, asks first, or is denied. Build an HTTP tool or connect an integration without touching a file. |
 | **Skills** | Create, edit, and delete `SKILL.md` files for this agent directly in the browser — write the body, preview the rendered markdown, save. |
 | **Permissions** | Add, edit, and delete permission rules (actauth) — who, tool, decision — and choose what happens when no rule matches. |
+| **Schedules** | Messages the agent receives on a timer — once at a set time, or every N minutes/hours/days. Run now, pause, resume, cancel, see each run's result, and optionally send results through the agent's notifier. |
 | **Environment** | Every setting an installed ability reads, with its project-wide value and this agent's own value side by side, and which one the agent actually uses. A secret is never shown again once set. |
 
 Models and Integrations in the sidebar show which model providers have a
@@ -182,9 +183,14 @@ waiting with Approve/Deny buttons. The tab warns you when an agent has
 Every notification links to a **decision page**: a signed, single-use
 link (`/decide/<token>`, valid 7 days) where whoever got the message can
 approve, deny, edit the arguments or answer a question, with no login and
-no app of your own. So the quickest setup is Slack: paste a bot token,
-pick a channel, save; each approval arrives with an "Open to approve or
-deny" link.
+no app of your own. So the quickest setup is Slack: create the Slack app
+from the manifest the console shows, paste its bot token, pick a channel
+from the list, save; each approval arrives with an "Open to approve or
+deny" link. Add the app's signing secret too and the message also gets
+Approve/Deny buttons, handled by LoopEngine itself at
+`/hooks/slack/<agent>`, with no handler to deploy. Lark cards carry the
+same link. Links and buttons need the server to be reachable from where
+people click (a public HTTPS address or a tunnel).
 
 For a third-party app calling an agent over plain HTTP:
 
@@ -206,6 +212,30 @@ click, a webhook HMAC signature, a magic-link token) ship under
 live and durable, worked examples, and how resumption actually works
 under the hood.
 
+## Scheduled tasks
+
+The server runs one scheduler (`core/scheduler.ts`) that sends a message
+to an agent later — once (`run_at`) or on an interval (`every: "1h"`) —
+from the console's **Schedules** tab, the `GET/POST
+/agents/<name>/schedules` API, or the agent itself: every agent has
+built-in `system_schedule_task`, `system_list_scheduled_tasks`,
+`system_check_scheduled_task` and `system_cancel_scheduled_task` tools,
+so "remind me tomorrow at 9" just works. An
+agent can only schedule, see or cancel its own tasks, up to 25 active at
+a time (`LOOPENGINE_SCHEDULER_MAX_PER_AGENT`); `selfScheduling: false` in
+its config removes the tools. Tasks left by the old `lp-task-scheduler`
+ability are imported at start. Each run goes through the same
+path as an HTTP call: an approval goes wherever the Permissions tab sends
+it (and resumes the run once decided); with nowhere set, a call that
+needs approval is denied. Intervals keep their original slot (an hourly
+task created at 10:07 stays on :07); a run missed while the server was
+down fires once when it's back. Tasks live in `.scheduler/` (or
+`LOOPENGINE_SCHEDULER_DIR`); the tick is `LOOPENGINE_SCHEDULER_TICK_MS`
+(10 s); `LOOPENGINE_SCHEDULER=off` turns the loop off for this process.
+Behind a hosting platform, `GET /internal/activity` reports `nextWakeAt`
+and `POST /internal/scheduler/tick` fires whatever is due, so a stopped
+server can be woken in time.
+
 ## Ability system
 
 Giving an agent a new capability is usually three separate, hand-authored

package/dist/core/agent-config.d.ts

@@ -203,6 +203,8 @@ export type HttpNotifierConfig = {
         appId: string;
         appSecret: string;
         chatId: string;
+        publicUrl?: string;
+        buttons?: boolean;
     };
     events: HttpNotifierEvent[];
 } | {
@@ -397,6 +399,12 @@ export interface AgentConfig {
      * for `cli`/`http_stream`: both always get the library's own live
      * defaults, with nothing to configure. */
     httpNotifier?: HttpNotifierConfig;
+    /** Whether this agent gets the built-in scheduling tools
+     * (system_schedule_task and friends, core/system-tools/schedule.ts),
+     * which let it schedule messages to itself — reminders, recurring
+     * checks — and list or cancel its own scheduled tasks. Default true;
+     * false leaves them out of this agent's tools entirely. */
+    selfScheduling?: boolean;
     /** Fires once, fire-and-forget, at the start of every `runAgent()`/
      * `resumeAgent()` call on the `http` channel (or no channel at all —
      * see below) — the "someone triggered this agent" signal, for

package/dist/core/http-notifier.js

@@ -114,8 +114,8 @@ function buildResolved(httpNotifier) {
             break;
         }
         case 'lark': {
-            const { appId, appSecret, chatId } = httpNotifier.config;
-            const lark = new LarkNotifier({ appId, appSecret, chatId });
+            const { appId, appSecret, chatId, publicUrl, buttons } = httpNotifier.config;
+            const lark = new LarkNotifier({ appId, appSecret, chatId, publicUrl, buttons });
             resolved = {
                 approver: events.has('approval') ? lark : undefined,
                 questionHandler: events.has('question') ? lark : undefined,

package/dist/core/http-notify-triggers/lark.d.ts

@@ -9,11 +9,20 @@ export declare class LarkNotifier implements DurableApprover, DurableQuestionHan
     private readonly appId;
     private readonly appSecret;
     private readonly chatId;
+    private readonly publicUrl?;
+    private readonly buttons;
+    /** `publicUrl` / `buttons`: same meaning as SlackNotifier's — a decision
+     * link in each card when the server's address is known, and whether to
+     * add card buttons, which only work with a card-callback handler
+     * deployed (examples/notifier-handler/lark.ts). */
     constructor(options: {
         appId: string;
         appSecret: string;
         chatId: string;
+        publicUrl?: string;
+        buttons?: boolean;
     });
+    private decideLine;
     requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
         pendingId: string;
     };

package/dist/core/http-notify-triggers/lark.js

@@ -38,6 +38,8 @@
 // sending and receiving ever run in different processes), deliberately
 // not the approach used here.
 import { randomUUID } from 'node:crypto';
+import { decidePath } from '../approval-links.js';
+import { publicBaseUrl } from './webhook.js';
 /** Fixed id for the question form card's own input field — used both
  * when *building* the card (notifyPendingQuestion below) and when
  * *reading* the human's answer back out of the callback payload (the
@@ -62,10 +64,22 @@ export class LarkNotifier {
     appId;
     appSecret;
     chatId;
+    publicUrl;
+    buttons;
+    /** `publicUrl` / `buttons`: same meaning as SlackNotifier's — a decision
+     * link in each card when the server's address is known, and whether to
+     * add card buttons, which only work with a card-callback handler
+     * deployed (examples/notifier-handler/lark.ts). */
     constructor(options) {
         this.appId = options.appId;
         this.appSecret = options.appSecret;
         this.chatId = options.chatId;
+        this.publicUrl = options.publicUrl;
+        this.buttons = options.buttons ?? true;
+    }
+    decideLine(pendingId, kind) {
+        const base = publicBaseUrl(this.publicUrl);
+        return base ? `\n[${kind === 'approval' ? 'Open to approve or deny' : 'Open to answer'}](${base}${decidePath(pendingId, kind)})` : '';
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
@@ -80,16 +94,18 @@ export class LarkNotifier {
                             tag: 'div',
                             text: {
                                 tag: 'lark_md',
-                                content: `**tool:** ${tool}\n**args:** \`${JSON.stringify(args)}\`\n**scope:** ${scope.tenant}/${scope.environment}/${scope.agent}\n**reason:** ${reason}`,
+                                content: `**tool:** ${tool}\n**args:** \`${JSON.stringify(args)}\`\n**scope:** ${scope.tenant}/${scope.environment}/${scope.agent}\n**reason:** ${reason}${this.decideLine(pendingId, 'approval')}`,
                             },
                         },
-                        {
-                            tag: 'action',
-                            actions: [
-                                { tag: 'button', text: { tag: 'plain_text', content: 'Approve' }, type: 'primary', value: { pendingId, decision: 'approve' } },
-                                { tag: 'button', text: { tag: 'plain_text', content: 'Deny' }, type: 'danger', value: { pendingId, decision: 'deny' } },
-                            ],
-                        },
+                        ...(this.buttons
+                            ? [{
+                                    tag: 'action',
+                                    actions: [
+                                        { tag: 'button', text: { tag: 'plain_text', content: 'Approve' }, type: 'primary', value: { pendingId, decision: 'approve' } },
+                                        { tag: 'button', text: { tag: 'plain_text', content: 'Deny' }, type: 'danger', value: { pendingId, decision: 'deny' } },
+                                    ],
+                                }]
+                            : []),
                     ],
                 };
                 await this.sendCard(token, card, pendingId);
@@ -114,19 +130,23 @@ export class LarkNotifier {
                     config: { wide_screen_mode: true },
                     header: { title: { tag: 'plain_text', content: `Question from ${agent}` } },
                     elements: [
-                        { tag: 'div', text: { tag: 'lark_md', content: question + (sessionId ? `\n_(session ${sessionId})_` : '') } },
-                        ...(optionButtons.length ? [{ tag: 'action', actions: optionButtons }] : []),
-                        {
-                            tag: 'form',
-                            name: 'answer_form',
-                            elements: [
-                                { tag: 'input', name: LARK_ANSWER_FIELD_TAG, placeholder: { tag: 'plain_text', content: 'Or type your own answer…' } },
+                        { tag: 'div', text: { tag: 'lark_md', content: question + (sessionId ? `\n_(session ${sessionId})_` : '') + this.decideLine(pendingId, 'question') } },
+                        ...(this.buttons
+                            ? [
+                                ...(optionButtons.length ? [{ tag: 'action', actions: optionButtons }] : []),
                                 {
-                                    tag: 'action',
-                                    actions: [{ tag: 'button', text: { tag: 'plain_text', content: 'Send' }, type: 'primary', action_type: 'form_submit', value: { pendingId } }],
+                                    tag: 'form',
+                                    name: 'answer_form',
+                                    elements: [
+                                        { tag: 'input', name: LARK_ANSWER_FIELD_TAG, placeholder: { tag: 'plain_text', content: 'Or type your own answer…' } },
+                                        {
+                                            tag: 'action',
+                                            actions: [{ tag: 'button', text: { tag: 'plain_text', content: 'Send' }, type: 'primary', action_type: 'form_submit', value: { pendingId } }],
+                                        },
+                                    ],
                                 },
-                            ],
-                        },
+                            ]
+                            : []),
                     ],
                 };
                 await this.sendCard(token, card, pendingId);

package/dist/core/notifier-file.d.ts

@@ -17,6 +17,10 @@ export interface NotifierFile {
 }
 /** The env var each channel's secret is read from, per agent. */
 export declare const NOTIFIER_SECRET_VARS: Record<NotifierFileChannel, string>;
+/** Optional: a Slack app's signing secret, per agent. Set, it turns on
+ * Approve/Deny buttons in Slack, handled by the server itself at
+ * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
+export declare const NOTIFIER_SLACK_SIGNING_SECRET_VAR = "LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET";
 export declare class NotifierFileError extends Error {
 }
 export declare function notifierFilePath(dir: string): string;

package/dist/core/notifier-file.js

@@ -17,6 +17,10 @@ export const NOTIFIER_SECRET_VARS = {
     slack: 'LOOPENGINE_NOTIFIER_SLACK_BOT_TOKEN',
     lark: 'LOOPENGINE_NOTIFIER_LARK_APP_SECRET',
 };
+/** Optional: a Slack app's signing secret, per agent. Set, it turns on
+ * Approve/Deny buttons in Slack, handled by the server itself at
+ * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
+export const NOTIFIER_SLACK_SIGNING_SECRET_VAR = 'LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET';
 const CHANNELS = ['webhook', 'slack', 'lark'];
 const EVENTS = ['approval', 'question', 'run_start', 'run_finish'];
 export class NotifierFileError extends Error {
@@ -95,10 +99,19 @@ export function notifierConfigFromFile(file, env) {
         case 'webhook':
             return { config: { channel: 'webhook', config: { webhookUrl: file.url, webhookSecret: secret, publicUrl: file.publicUrl }, events: file.events } };
         case 'slack':
-            // No interactive buttons: a console-configured Slack notifier has
-            // no interactivity endpoint behind it; the decision link replaces them.
-            return { config: { channel: 'slack', config: { botToken: secret, channelId: file.channelId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
+            // Buttons only once the agent has a signing secret, i.e. the Slack
+            // app's interactivity points at /hooks/slack/<agent>; otherwise the
+            // decision link does the job.
+            return {
+                config: {
+                    channel: 'slack',
+                    config: { botToken: secret, channelId: file.channelId, publicUrl: file.publicUrl, buttons: Boolean(env.get(NOTIFIER_SLACK_SIGNING_SECRET_VAR)) },
+                    events: file.events,
+                },
+            };
         case 'lark':
-            return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId }, events: file.events } };
+            // No card buttons: nothing built in handles Lark's card callbacks yet,
+            // so a console-configured Lark notifier relies on the decision link.
+            return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
     }
 }

package/dist/core/run-agent.js

@@ -19,7 +19,7 @@ import { recordUsage } from './usage.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
 import { loadGatewayToolsFromDir } from './gateway-tools.js';
-import { systemTools, createAskUserTool, CliQuestionHandler, isDurableQuestionHandler } from './system-tools/index.js';
+import { systemTools, createAskUserTool, createScheduleTools, CliQuestionHandler, isDurableQuestionHandler } from './system-tools/index.js';
 import { resolveHttpNotifier } from './http-notifier.js';
 import { CRASH_RECOVERY_CONTINUATION } from './session-store.js';
 export { systemTools } from './system-tools/index.js';
@@ -296,9 +296,14 @@ async function buildTurnContext(config, modelCall, options) {
     // (options.onEvent's own fallback) — see RunAgentOptions.onQuestionPending's
     // own doc comment for why those two are deliberately not the same thing.
     const askUserTool = createAskUserTool({ agent: config.name, sessionId: options.sessionId }, options.onQuestionPending);
+    // Bound to this agent: it can schedule, list and cancel only its own
+    // tasks (see core/system-tools/schedule.ts). AgentConfig.selfScheduling
+    // false leaves them out.
+    const scheduleTools = config.selfScheduling === false ? [] : createScheduleTools(config.name);
     const tools = dedupeToolsByName([
         ...systemTools,
         askUserTool,
+        ...scheduleTools,
         ...(config.tools ?? (await loadDefaultTools(config))),
         ...(await loadSubagentAsTools(config)),
         ...(await loadGatewayToolsFromDir(join(process.cwd(), 'agents', config.name))),
@@ -390,7 +395,7 @@ async function buildTurnContext(config, modelCall, options) {
     // ('ask' or 'deny', see loadRules' own doc comment) would otherwise
     // catch it, since neither system tool ever appears in an agent's own
     // actauth.yml.
-    const systemToolInstances = new Set([...systemTools, askUserTool]);
+    const systemToolInstances = new Set([...systemTools, askUserTool, ...scheduleTools]);
     const toolSchemas = tools.map(({ name, description, input_schema }) => ({
         name,
         description,

package/dist/core/scheduler.d.ts

@@ -0,0 +1,143 @@
+export type Schedule = {
+    run_at: string;
+} | {
+    every: string;
+    anchor?: string;
+};
+export type ScheduledTaskStatus = 'scheduled' | 'running' | 'awaiting_approval' | 'paused' | 'done' | 'cancelled';
+export interface ScheduledTaskRun {
+    ran_at: string;
+    status: 'ok' | 'error';
+    result?: string;
+    error?: string;
+    session_id?: string;
+}
+export interface ScheduledTask {
+    task_id: string;
+    task_name?: string;
+    agent: string;
+    message: string;
+    schedule: Schedule;
+    status: ScheduledTaskStatus;
+    created_at: string;
+    next_run_at?: string;
+    run_count: number;
+    last_run_at?: string;
+    last_status?: 'ok' | 'error';
+    last_result?: string;
+    last_error?: string;
+    /** Set while a run is paused on an approval or question. */
+    pending?: {
+        ran_at: string;
+        session_id: string;
+        pending_ids: string[];
+    };
+    /** Send each run's result through the agent's notifier. */
+    notify?: boolean;
+    history: ScheduledTaskRun[];
+    /** Set by "run now" on a paused or finished task, so it goes back to
+     * that status after the extra run. */
+    run_now_from?: 'paused' | 'done';
+    /** Set by cancelling a run that's waiting on an approval: cancelled
+     * once that run finishes. */
+    cancel_after_run?: boolean;
+}
+export declare class ScheduleError extends Error {
+}
+export declare function parseEvery(every: string): number;
+/** Human-readable schedule, for lists and messages. */
+export declare function describeSchedule(schedule: Schedule): string;
+export interface SchedulerStore {
+    list(): Promise<ScheduledTask[]>;
+    get(taskId: string): Promise<ScheduledTask | undefined>;
+    put(task: ScheduledTask): Promise<void>;
+    remove(taskId: string): Promise<void>;
+    /** Runs `fn` with exclusive access to one task (read, change, write). */
+    update(taskId: string, fn: (task: ScheduledTask | undefined) => ScheduledTask | undefined): Promise<ScheduledTask | undefined>;
+}
+/** One JSON file per task under `<dir>/tasks/` — one server process. */
+export declare class FileSchedulerStore implements SchedulerStore {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    list(): Promise<ScheduledTask[]>;
+    get(taskId: string): Promise<ScheduledTask | undefined>;
+    put(task: ScheduledTask): Promise<void>;
+    remove(taskId: string): Promise<void>;
+    update(taskId: string, fn: (task: ScheduledTask | undefined) => ScheduledTask | undefined): Promise<ScheduledTask | undefined>;
+}
+/** The process-wide store: `.scheduler/` in the project, or
+ * LOOPENGINE_SCHEDULER_DIR. */
+export declare function getSchedulerStore(): SchedulerStore;
+export declare function setSchedulerStore(next: SchedulerStore): void;
+export interface CreateScheduledTaskInput {
+    agent: string;
+    message: string;
+    schedule: {
+        run_at?: unknown;
+        every?: unknown;
+    };
+    task_name?: string;
+    notify?: boolean;
+}
+export declare function createScheduledTask(input: CreateScheduledTaskInput, nowMs?: number): Promise<ScheduledTask>;
+export declare function listScheduledTasks(filter?: {
+    agent?: string;
+    status?: ScheduledTaskStatus;
+}): Promise<ScheduledTask[]>;
+export declare function getScheduledTask(taskId: string): Promise<ScheduledTask | undefined>;
+/** Stops future runs; history stays. A run already waiting on an
+ * approval isn't retracted. */
+export declare function cancelScheduledTask(taskId: string): Promise<ScheduledTask>;
+export declare function pauseScheduledTask(taskId: string): Promise<ScheduledTask>;
+export declare function resumeScheduledTask(taskId: string, nowMs?: number): Promise<ScheduledTask>;
+/** Fires the task on the next tick, without changing its schedule. A
+ * finished one-off task runs once more. */
+export declare function runScheduledTaskNow(taskId: string, nowMs?: number): Promise<ScheduledTask>;
+export declare function deleteScheduledTask(taskId: string): Promise<void>;
+/** When the next task is due — for a host that stops idle servers and
+ * needs to wake this one in time (GET /internal/activity). */
+export declare function nextScheduledWakeAt(): Promise<string | undefined>;
+/** Moves the old lp-task-scheduler's task files (`<dir>/.tasks/*.json`)
+ * into this store once, renaming each to `.json.migrated`. Returns how
+ * many it imported. */
+export declare function importLegacyScheduledTasks(dir: string): Promise<number>;
+/** How a task fires — supplied by the server. `done`: the agent replied;
+ * `pending`: the run is paused on approvals/questions (see settleFromResume). */
+export type FireTask = (task: ScheduledTask, sessionId: string) => Promise<{
+    kind: 'done';
+    text: string;
+} | {
+    kind: 'pending';
+    pendingIds: string[];
+}>;
+export declare class Scheduler {
+    private readonly fire;
+    private readonly tickMs;
+    private readonly onSettled?;
+    private readonly inFlight;
+    private timer?;
+    constructor(options: {
+        fire: FireTask;
+        tickMs?: number;
+        onSettled?: (task: ScheduledTask, run: ScheduledTaskRun) => void;
+    });
+    /** Imports tasks left by the old lp-task-scheduler ability, recovers
+     * runs a restart cut off, then ticks every `tickMs`. */
+    start(): Promise<void>;
+    stop(): void;
+    /** How many runs are executing right now (for idle-shutdown checks). */
+    get running(): number;
+    /** Fires every task that's due. Safe to call any time (a host's wake-up
+     * request calls it directly). */
+    tick(nowMs?: number): Promise<number>;
+    private run;
+    /** A paused run resumed after a decision (adapters/http.ts calls this
+     * from the resolve path): settle it, or record the next decision it's
+     * now waiting on. */
+    settleFromResume(sessionId: string, outcome: {
+        text: string;
+        pendingIds?: string[];
+    }): Promise<void>;
+    private settle;
+}