loopengine 0.1.68 → 0.1.70

package/dist/core/scheduler.js

@@ -0,0 +1,359 @@
+// Scheduled tasks: "send this message to that agent later — once, or
+// every N minutes". One scheduler per server, started at boot by
+// adapters/http.ts, which also supplies how a task actually fires (the
+// same turn path as POST /agents/:name/messages, so approvals, notifiers
+// and decision links behave exactly as they do for any HTTP call).
+//
+// Everything a tool or the console needs — create, list, pause, cancel —
+// works on the store directly (below), so it works whether or not this
+// process is the one running the loop; the loop picks changes up on its
+// next tick.
+//
+// `every` is anchored: an hourly task created at 10:07 keeps firing at
+// :07, however long each run takes. A run missed while the server was
+// down fires once when it's back, then the schedule moves to the next
+// future slot (no burst of catch-up runs).
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { KeyedMutex } from './session-store.js';
+const HISTORY_LIMIT = 20;
+const EVERY_PATTERN = /^(\d+)\s*(s|m|h|d)$/;
+const EVERY_UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** Shortest allowed interval, so a typo can't hammer the model. */
+const MIN_EVERY_MS = 30_000;
+export class ScheduleError extends Error {
+}
+export function parseEvery(every) {
+    const match = EVERY_PATTERN.exec(every.trim());
+    if (!match)
+        throw new ScheduleError(`"${every}" is not a valid interval — use a number followed by s/m/h/d, e.g. "30m", "1h", "1d"`);
+    const ms = Number(match[1]) * EVERY_UNIT_MS[match[2]];
+    if (ms < MIN_EVERY_MS)
+        throw new ScheduleError(`"${every}" is too short — the shortest interval is 30s`);
+    return ms;
+}
+/** The first anchored slot strictly after `nowMs`. */
+function nextAnchoredSlot(anchorMs, intervalMs, nowMs) {
+    if (nowMs < anchorMs)
+        return anchorMs;
+    return anchorMs + (Math.floor((nowMs - anchorMs) / intervalMs) + 1) * intervalMs;
+}
+/** Human-readable schedule, for lists and messages. */
+export function describeSchedule(schedule) {
+    return 'run_at' in schedule ? `once at ${schedule.run_at}` : `every ${schedule.every}`;
+}
+const fileMutex = new KeyedMutex();
+/** One JSON file per task under `<dir>/tasks/` — one server process. */
+export class FileSchedulerStore {
+    dir;
+    constructor(dir) {
+        this.dir = path.join(dir, 'tasks');
+    }
+    file(taskId) {
+        if (!/^[A-Za-z0-9_-]+$/.test(taskId))
+            throw new ScheduleError(`invalid task id "${taskId}"`);
+        return path.join(this.dir, `${taskId}.json`);
+    }
+    async list() {
+        if (!existsSync(this.dir))
+            return [];
+        const tasks = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                tasks.push(JSON.parse(readFileSync(path.join(this.dir, name), 'utf8')));
+            }
+            catch {
+                // mid-write or removed between readdir and read
+            }
+        }
+        return tasks.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    }
+    async get(taskId) {
+        const file = this.file(taskId);
+        return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined;
+    }
+    async put(task) {
+        mkdirSync(this.dir, { recursive: true });
+        const file = this.file(task.task_id);
+        writeFileSync(file + '.tmp', JSON.stringify(task, null, 2));
+        renameSync(file + '.tmp', file);
+    }
+    async remove(taskId) {
+        rmSync(this.file(taskId), { force: true });
+    }
+    async update(taskId, fn) {
+        return fileMutex.run(taskId, async () => {
+            const next = fn(await this.get(taskId));
+            if (next)
+                await this.put(next);
+            return next;
+        });
+    }
+}
+let store;
+/** The process-wide store: `.scheduler/` in the project, or
+ * LOOPENGINE_SCHEDULER_DIR. */
+export function getSchedulerStore() {
+    store ??= new FileSchedulerStore(process.env.LOOPENGINE_SCHEDULER_DIR || path.join(process.cwd(), '.scheduler'));
+    return store;
+}
+export function setSchedulerStore(next) {
+    store = next;
+}
+export async function createScheduledTask(input, nowMs = Date.now()) {
+    if (!input.agent)
+        throw new ScheduleError('agent is required');
+    if (!input.message?.trim())
+        throw new ScheduleError('message is required');
+    let schedule;
+    let nextRunMs;
+    if (typeof input.schedule?.run_at === 'string' && input.schedule.run_at) {
+        const runAtMs = Date.parse(input.schedule.run_at);
+        if (Number.isNaN(runAtMs))
+            throw new ScheduleError(`"${input.schedule.run_at}" is not a valid ISO 8601 timestamp`);
+        schedule = { run_at: new Date(runAtMs).toISOString() };
+        nextRunMs = runAtMs;
+    }
+    else if (typeof input.schedule?.every === 'string' && input.schedule.every) {
+        const intervalMs = parseEvery(input.schedule.every);
+        nextRunMs = nowMs + intervalMs;
+        schedule = { every: input.schedule.every.trim(), anchor: new Date(nextRunMs).toISOString() };
+    }
+    else {
+        throw new ScheduleError('schedule must be { "run_at": "<ISO timestamp>" } or { "every": "<interval, e.g. 1h>" }');
+    }
+    const task = {
+        task_id: randomUUID(),
+        task_name: input.task_name?.trim() || undefined,
+        agent: input.agent,
+        message: input.message,
+        schedule,
+        status: 'scheduled',
+        created_at: new Date(nowMs).toISOString(),
+        next_run_at: new Date(nextRunMs).toISOString(),
+        run_count: 0,
+        notify: input.notify || undefined,
+        history: [],
+    };
+    await getSchedulerStore().put(task);
+    return task;
+}
+export async function listScheduledTasks(filter = {}) {
+    return (await getSchedulerStore().list()).filter((t) => (!filter.agent || t.agent === filter.agent) && (!filter.status || t.status === filter.status));
+}
+export async function getScheduledTask(taskId) {
+    return getSchedulerStore().get(taskId);
+}
+function mustExist(task, taskId) {
+    if (!task)
+        throw new ScheduleError(`no scheduled task "${taskId}"`);
+    return task;
+}
+/** Stops future runs; history stays. A run already waiting on an
+ * approval isn't retracted. */
+export async function cancelScheduledTask(taskId) {
+    return mustExist(await getSchedulerStore().update(taskId, (t) => !t ? t : t.status === 'awaiting_approval' ? { ...t, cancel_after_run: true } : { ...t, status: 'cancelled', next_run_at: undefined }), taskId);
+}
+export async function pauseScheduledTask(taskId) {
+    return mustExist(await getSchedulerStore().update(taskId, (t) => (t && t.status === 'scheduled' ? { ...t, status: 'paused', next_run_at: undefined } : t)), taskId);
+}
+export async function resumeScheduledTask(taskId, nowMs = Date.now()) {
+    return mustExist(await getSchedulerStore().update(taskId, (t) => {
+        if (!t || t.status !== 'paused')
+            return t;
+        return { ...t, status: 'scheduled', next_run_at: new Date(nextRunAfter(t, nowMs) ?? nowMs).toISOString() };
+    }), taskId);
+}
+/** Fires the task on the next tick, without changing its schedule. A
+ * finished one-off task runs once more. */
+export async function runScheduledTaskNow(taskId, nowMs = Date.now()) {
+    return mustExist(await getSchedulerStore().update(taskId, (t) => {
+        if (!t || t.status === 'running' || t.status === 'awaiting_approval' || t.status === 'cancelled')
+            return t;
+        return { ...t, status: 'scheduled', next_run_at: new Date(nowMs).toISOString(), run_now_from: t.status === 'paused' || t.status === 'done' ? t.status : undefined };
+    }), taskId);
+}
+export async function deleteScheduledTask(taskId) {
+    await getSchedulerStore().remove(taskId);
+}
+/** 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 async function nextScheduledWakeAt() {
+    const due = (await getSchedulerStore().list()).filter((t) => t.status === 'scheduled' && t.next_run_at).map((t) => t.next_run_at);
+    return due.sort()[0];
+}
+function nextRunAfter(task, nowMs) {
+    if ('run_at' in task.schedule)
+        return undefined;
+    const intervalMs = parseEvery(task.schedule.every);
+    const anchorMs = task.schedule.anchor ? Date.parse(task.schedule.anchor) : Date.parse(task.created_at) + intervalMs;
+    return nextAnchoredSlot(anchorMs, intervalMs, nowMs);
+}
+/** 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 async function importLegacyScheduledTasks(dir) {
+    const legacyDir = path.join(dir, '.tasks');
+    if (!existsSync(legacyDir))
+        return 0;
+    let imported = 0;
+    for (const name of readdirSync(legacyDir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        const file = path.join(legacyDir, name);
+        try {
+            const old = JSON.parse(readFileSync(file, 'utf8'));
+            if (!(await getSchedulerStore().get(old.task_id))) {
+                const task = { ...old, history: old.history ?? [], run_count: old.run_count ?? 0 };
+                if ('every' in task.schedule && !task.schedule.anchor && task.next_run_at)
+                    task.schedule = { ...task.schedule, anchor: task.next_run_at };
+                await getSchedulerStore().put(task);
+                imported++;
+            }
+            renameSync(file, file + '.migrated');
+        }
+        catch (err) {
+            console.error(`[loopengine] could not import legacy scheduled task ${file}:`, err);
+        }
+    }
+    return imported;
+}
+/** lp-task-scheduler 1.x kept tasks under
+ * generated/scheduled-tasks/<agent>/.tasks/ (or SCHEDULER_STORE_DIR) and
+ * ran its own timer; scheduling is built in now, so the server imports
+ * those once at start. */
+async function importLegacyAbilityTasks() {
+    const dirs = new Set();
+    const root = path.join(process.cwd(), 'generated', 'scheduled-tasks');
+    if (existsSync(root)) {
+        dirs.add(root);
+        for (const name of readdirSync(root))
+            if (name !== '.tasks')
+                dirs.add(path.join(root, name));
+    }
+    if (process.env.SCHEDULER_STORE_DIR)
+        dirs.add(path.resolve(process.env.SCHEDULER_STORE_DIR));
+    for (const dir of dirs) {
+        const n = await importLegacyScheduledTasks(dir);
+        if (n)
+            console.log(`[loopengine] imported ${n} scheduled task(s) from ${dir}`);
+    }
+}
+export class Scheduler {
+    fire;
+    tickMs;
+    onSettled;
+    inFlight = new Set();
+    timer;
+    constructor(options) {
+        this.fire = options.fire;
+        this.tickMs = options.tickMs ?? (Number(process.env.LOOPENGINE_SCHEDULER_TICK_MS) || 10_000);
+        this.onSettled = options.onSettled;
+    }
+    /** Imports tasks left by the old lp-task-scheduler ability, recovers
+     * runs a restart cut off, then ticks every `tickMs`. */
+    async start() {
+        await importLegacyAbilityTasks();
+        for (const task of await getSchedulerStore().list()) {
+            if (task.status === 'running')
+                await this.settle(task.task_id, new Date().toISOString(), { status: 'error', error: 'The server restarted while this run was in progress.' });
+        }
+        await this.tick();
+        this.timer = setInterval(() => void this.tick().catch((err) => console.error('[loopengine] scheduler tick failed:', err)), this.tickMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    /** How many runs are executing right now (for idle-shutdown checks). */
+    get running() {
+        return this.inFlight.size;
+    }
+    /** Fires every task that's due. Safe to call any time (a host's wake-up
+     * request calls it directly). */
+    async tick(nowMs = Date.now()) {
+        let fired = 0;
+        for (const task of await getSchedulerStore().list()) {
+            if (task.status !== 'scheduled' || !task.next_run_at || Date.parse(task.next_run_at) > nowMs || this.inFlight.has(task.task_id))
+                continue;
+            fired++;
+            this.inFlight.add(task.task_id);
+            void this.run(task.task_id).finally(() => this.inFlight.delete(task.task_id));
+        }
+        return fired;
+    }
+    async run(taskId) {
+        const ranAt = new Date().toISOString();
+        const claimed = await getSchedulerStore().update(taskId, (t) => (t && t.status === 'scheduled' ? { ...t, status: 'running' } : t));
+        if (!claimed || claimed.status !== 'running')
+            return;
+        const sessionId = `sched-${taskId.slice(0, 8)}-${claimed.run_count + 1}-${Date.now().toString(36)}`;
+        try {
+            const outcome = await this.fire(claimed, sessionId);
+            if (outcome.kind === 'pending') {
+                await getSchedulerStore().update(taskId, (t) => t && {
+                    ...t,
+                    status: 'awaiting_approval',
+                    next_run_at: undefined,
+                    pending: { ran_at: ranAt, session_id: sessionId, pending_ids: outcome.pendingIds },
+                    // Cancelled while this run was starting: finish this run, then stop.
+                    cancel_after_run: t.cancel_after_run || t.status === 'cancelled' || undefined,
+                });
+                return;
+            }
+            await this.settle(taskId, ranAt, { status: 'ok', result: outcome.text, session_id: sessionId });
+        }
+        catch (err) {
+            await this.settle(taskId, ranAt, { status: 'error', error: err instanceof Error ? err.message : String(err), session_id: sessionId });
+        }
+    }
+    /** 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. */
+    async settleFromResume(sessionId, outcome) {
+        if (!sessionId.startsWith('sched-'))
+            return;
+        const task = (await getSchedulerStore().list()).find((t) => t.pending?.session_id === sessionId);
+        if (!task)
+            return;
+        if (outcome.pendingIds?.length) {
+            await getSchedulerStore().update(task.task_id, (t) => t && t.pending && { ...t, pending: { ...t.pending, pending_ids: outcome.pendingIds } });
+            return;
+        }
+        await this.settle(task.task_id, task.pending.ran_at, { status: 'ok', result: outcome.text, session_id: sessionId });
+    }
+    async settle(taskId, ranAt, run) {
+        const nowMs = Date.now();
+        const entry = { ran_at: ranAt, ...run };
+        const settled = await getSchedulerStore().update(taskId, (t) => {
+            if (!t)
+                return t;
+            const history = [...t.history, entry].slice(-HISTORY_LIMIT);
+            const base = {
+                ...t,
+                run_count: t.run_count + 1,
+                last_run_at: ranAt,
+                last_status: run.status,
+                last_result: run.result,
+                last_error: run.error,
+                pending: undefined,
+                history,
+                run_now_from: undefined,
+                cancel_after_run: undefined,
+            };
+            if (t.cancel_after_run || t.status === 'cancelled')
+                return { ...base, status: 'cancelled', next_run_at: undefined };
+            // A "run now" of a paused or finished task goes back to how it was.
+            if (t.run_now_from)
+                return { ...base, status: t.run_now_from, next_run_at: undefined };
+            const next = nextRunAfter(t, nowMs);
+            return next === undefined ? { ...base, status: 'done', next_run_at: undefined } : { ...base, status: 'scheduled', next_run_at: new Date(next).toISOString() };
+        });
+        if (settled)
+            this.onSettled?.(settled, entry);
+    }
+}

package/dist/core/slack-interactions.d.ts

@@ -0,0 +1,59 @@
+export declare const SLACK_ANSWER_BLOCK_ID = "answer_block";
+export declare const SLACK_ANSWER_ACTION_ID = "answer_input";
+/** https://api.slack.com/authentication/verifying-requests-from-slack —
+ * rejects anything older than five minutes, so a captured request can't
+ * be replayed later. */
+export declare function verifySlackRequest(rawBody: string, timestamp: string | undefined, signature: string | undefined, signingSecret: string, nowMs?: number): boolean;
+export type SlackInteraction = {
+    type: 'decide';
+    pendingId: string;
+    decision: 'approve' | 'deny';
+    responseUrl?: string;
+    user?: string;
+} | {
+    type: 'answer';
+    pendingId: string;
+    answer: string;
+    responseUrl?: string;
+    user?: string;
+} | {
+    type: 'open_answer';
+    pendingId: string;
+    triggerId: string;
+} | {
+    type: 'ignore';
+};
+/** Reads Slack's form-encoded `payload=<json>` body into the one thing
+ * it asks for. Anything unrecognized is `ignore`. */
+export declare function parseSlackInteraction(rawBody: string): SlackInteraction;
+/** Opens the free-text answer modal for "Other…". Slack's trigger_id
+ * expires three seconds after the click, so call this before anything slow. */
+export declare function openSlackAnswerModal(botToken: string, triggerId: string, pendingId: string): Promise<void>;
+/** Replaces the original message (its buttons included) with what
+ * happened, so nobody clicks a decision that's already made. */
+export declare function replyInSlack(responseUrl: string, text: string): Promise<void>;
+/** What to say in Slack after a decision, from the resolve route's own
+ * response body. */
+export declare function slackOutcomeText(kind: 'approve' | 'deny' | 'answer', status: number, body: {
+    alreadyResolved?: boolean;
+    resolved?: boolean;
+    text?: string;
+    error?: string;
+    pending?: unknown[];
+}, user?: string): string;
+export interface SlackChannel {
+    id: string;
+    name: string;
+    isPrivate: boolean;
+    isMember: boolean;
+}
+/** Channels the bot can see — needs the channels:read (and, for private
+ * channels, groups:read) scope. */
+export declare function listSlackChannels(botToken: string): Promise<SlackChannel[]>;
+/** A Slack app manifest for one agent's notifier: a bot that can post and
+ * read the channel list, with interactivity pointed at this server.
+ * Paste it into api.slack.com/apps → Create New App → From a manifest. */
+export declare function slackAppManifest(options: {
+    agentName: string;
+    interactivityUrl: string;
+}): Record<string, unknown>;

package/dist/core/slack-interactions.js

@@ -0,0 +1,168 @@
+// What the server needs to handle Slack button clicks itself (POST
+// /hooks/slack/<agent> in adapters/http.ts), so a Slack notifier's
+// Approve/Deny and answer buttons work with no handler of your own to
+// deploy: request verification, reading the interaction payload, the
+// "Other…" answer modal, replying in the original message, listing
+// channels for the console's channel picker, and the app manifest the
+// console shows for creating the Slack app.
+//
+// Same button contract SlackNotifier (core/http-notify-triggers/slack.ts)
+// sends: action_id approve|deny with the pendingId as value,
+// answer_option with {pendingId, answer}, open_answer_modal with the
+// pendingId, and the modal's answer under ANSWER_BLOCK_ID/ANSWER_ACTION_ID.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const SLACK_ANSWER_BLOCK_ID = 'answer_block';
+export const SLACK_ANSWER_ACTION_ID = 'answer_input';
+/** https://api.slack.com/authentication/verifying-requests-from-slack —
+ * rejects anything older than five minutes, so a captured request can't
+ * be replayed later. */
+export function verifySlackRequest(rawBody, timestamp, signature, signingSecret, nowMs = Date.now()) {
+    if (!timestamp || !signature)
+        return false;
+    const age = Math.abs(nowMs / 1000 - Number(timestamp));
+    if (!Number.isFinite(age) || age > 60 * 5)
+        return false;
+    const expected = Buffer.from(`v0=${createHmac('sha256', signingSecret).update(`v0:${timestamp}:${rawBody}`).digest('hex')}`);
+    const actual = Buffer.from(signature);
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+/** Reads Slack's form-encoded `payload=<json>` body into the one thing
+ * it asks for. Anything unrecognized is `ignore`. */
+export function parseSlackInteraction(rawBody) {
+    const raw = new URLSearchParams(rawBody).get('payload');
+    if (!raw)
+        return { type: 'ignore' };
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        return { type: 'ignore' };
+    }
+    const user = payload.user?.id;
+    if (payload.type === 'view_submission' && payload.view?.private_metadata) {
+        const answer = payload.view.state?.values?.[SLACK_ANSWER_BLOCK_ID]?.[SLACK_ANSWER_ACTION_ID]?.value ?? '';
+        return { type: 'answer', pendingId: payload.view.private_metadata, answer, user };
+    }
+    if (payload.type !== 'block_actions')
+        return { type: 'ignore' };
+    const action = payload.actions?.[0];
+    if (!action?.value)
+        return { type: 'ignore' };
+    switch (action.action_id) {
+        case 'approve':
+        case 'deny':
+            return { type: 'decide', pendingId: action.value, decision: action.action_id, responseUrl: payload.response_url, user };
+        case 'answer_option': {
+            try {
+                const { pendingId, answer } = JSON.parse(action.value);
+                return pendingId && typeof answer === 'string' ? { type: 'answer', pendingId, answer, responseUrl: payload.response_url, user } : { type: 'ignore' };
+            }
+            catch {
+                return { type: 'ignore' };
+            }
+        }
+        case 'open_answer_modal':
+            return payload.trigger_id ? { type: 'open_answer', pendingId: action.value, triggerId: payload.trigger_id } : { type: 'ignore' };
+        default:
+            return { type: 'ignore' };
+    }
+}
+/** Opens the free-text answer modal for "Other…". Slack's trigger_id
+ * expires three seconds after the click, so call this before anything slow. */
+export async function openSlackAnswerModal(botToken, triggerId, pendingId) {
+    const res = await fetch('https://slack.com/api/views.open', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${botToken}`, 'content-type': 'application/json; charset=utf-8' },
+        body: JSON.stringify({
+            trigger_id: triggerId,
+            view: {
+                type: 'modal',
+                callback_id: 'answer_modal',
+                private_metadata: pendingId,
+                title: { type: 'plain_text', text: 'Your answer' },
+                submit: { type: 'plain_text', text: 'Send' },
+                blocks: [
+                    {
+                        type: 'input',
+                        block_id: SLACK_ANSWER_BLOCK_ID,
+                        label: { type: 'plain_text', text: 'Answer' },
+                        element: { type: 'plain_text_input', action_id: SLACK_ANSWER_ACTION_ID, multiline: true },
+                    },
+                ],
+            },
+        }),
+    });
+    const body = (await res.json());
+    if (!body.ok)
+        throw new Error(`views.open failed: ${body.error}`);
+}
+/** Replaces the original message (its buttons included) with what
+ * happened, so nobody clicks a decision that's already made. */
+export async function replyInSlack(responseUrl, text) {
+    await fetch(responseUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ replace_original: true, text }),
+    });
+}
+/** What to say in Slack after a decision, from the resolve route's own
+ * response body. */
+export function slackOutcomeText(kind, status, body, user) {
+    const who = user ? ` by <@${user}>` : '';
+    if (status >= 400)
+        return `:warning: Couldn't record that: ${body.error ?? `HTTP ${status}`}`;
+    if (body.alreadyResolved)
+        return 'Already decided elsewhere.';
+    const what = kind === 'approve' ? ':white_check_mark: Approved' : kind === 'deny' ? ':no_entry: Denied' : ':speech_balloon: Answered';
+    if (body.resolved)
+        return `${what}${who}. Still waiting on another decision in the same turn.`;
+    if (body.pending?.length)
+        return `${what}${who}. The agent needs another decision; a new message is on its way.`;
+    return `${what}${who}.${body.text ? `\n>${body.text.replace(/\n/g, '\n>')}` : ''}`;
+}
+/** Channels the bot can see — needs the channels:read (and, for private
+ * channels, groups:read) scope. */
+export async function listSlackChannels(botToken) {
+    const channels = [];
+    let cursor = '';
+    for (let page = 0; page < 10; page++) {
+        const params = new URLSearchParams({ types: 'public_channel,private_channel', exclude_archived: 'true', limit: '200' });
+        if (cursor)
+            params.set('cursor', cursor);
+        const res = await fetch(`https://slack.com/api/conversations.list?${params}`, { headers: { Authorization: `Bearer ${botToken}` } });
+        const body = (await res.json());
+        if (!body.ok) {
+            const reasons = {
+                missing_scope: 'The bot token is missing the channels:read scope; reinstall the app from the manifest',
+                invalid_auth: 'Slack rejected the bot token; copy the Bot User OAuth Token (xoxb-...) again',
+                not_authed: 'Enter the bot token first',
+                token_revoked: 'This bot token was revoked; reinstall the app and copy the new one',
+            };
+            throw new Error(reasons[body.error ?? ''] ?? `Slack said: ${body.error}`);
+        }
+        for (const c of body.channels ?? [])
+            channels.push({ id: c.id, name: c.name, isPrivate: Boolean(c.is_private), isMember: Boolean(c.is_member) });
+        cursor = body.response_metadata?.next_cursor ?? '';
+        if (!cursor)
+            break;
+    }
+    return channels.sort((a, b) => Number(b.isMember) - Number(a.isMember) || a.name.localeCompare(b.name));
+}
+/** A Slack app manifest for one agent's notifier: a bot that can post and
+ * read the channel list, with interactivity pointed at this server.
+ * Paste it into api.slack.com/apps → Create New App → From a manifest. */
+export function slackAppManifest(options) {
+    const name = `LoopEngine ${options.agentName}`.slice(0, 35);
+    return {
+        display_information: { name, description: `Approval requests and questions from the ${options.agentName} agent` },
+        features: { bot_user: { display_name: name, always_online: true } },
+        oauth_config: { scopes: { bot: ['chat:write', 'channels:read', 'groups:read'] } },
+        settings: {
+            interactivity: { is_enabled: true, request_url: options.interactivityUrl },
+            org_deploy_enabled: false,
+            socket_mode_enabled: false,
+            token_rotation_enabled: false,
+        },
+    };
+}

package/dist/core/system-tools/index.d.ts

@@ -1,3 +1,4 @@
 import type { ToolDefinition } from '../agent-config.js';
 export declare const systemTools: ToolDefinition[];
+export { createScheduleTools } from './schedule.js';
 export { createAskUserTool, listQuestions, answerQuestion, findQuestion, CliQuestionHandler, WebchatQuestionHandler, isDurableQuestionHandler, type PendingQuestion, } from './ask_user.js';

package/dist/core/system-tools/index.js

@@ -9,4 +9,5 @@
 // re-exported here instead of an instance.
 import { readFile } from './read_file.js';
 export const systemTools = [readFile];
+export { createScheduleTools } from './schedule.js';
 export { createAskUserTool, listQuestions, answerQuestion, findQuestion, CliQuestionHandler, WebchatQuestionHandler, isDurableQuestionHandler, } from './ask_user.js';

package/dist/core/system-tools/schedule.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from '../agent-config.js';
+export declare function createScheduleTools(agentName: string): ToolDefinition[];