hive-am 1.0.0 → 1.1.0

package/server/dist/providers/opencode-server.js

@@ -0,0 +1,164 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from '../db.js';
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * One long-lived `opencode serve` per agent. A private server per turn (`opencode run --standalone`) boots from zero every time and its
+ * hive MCP server connects only after the model has already taken its first step, so the first `tools.hive.*` call always fails
+ * ("Unknown tool") and costs a whole extra model step. A server that stays up has hive connected before the message arrives, and
+ * the turn skips OpenCode's ~4 s boot too. The server reads the agent's config (permissions, MCP) once when it starts, so a change
+ * in that config restarts it; it stops by itself after a while without turns.
+ */
+const IDLE_MS = 5 * 60_000;
+/** Servers kept alive at once (each takes roughly 150 MB idle and 300 MB after a turn). The least recently used one is stopped to make room; `HIVE_AM_OPENCODE_SERVERS` changes it. */
+const MAX_SERVERS = Math.max(1, Number(process.env.HIVE_AM_OPENCODE_SERVERS) || 2);
+const START_TIMEOUT_MS = 20_000;
+const MCP_WAIT_MS = 10_000;
+const servers = new Map();
+export function stopOpencodeServer(agentId) {
+    const s = servers.get(agentId);
+    if (!s)
+        return;
+    servers.delete(agentId);
+    savePids();
+    if (s.idle)
+        clearTimeout(s.idle);
+    if (!s.proc.killed)
+        s.proc.kill('SIGTERM');
+}
+const stopAll = () => { for (const id of [...servers.keys()])
+    stopOpencodeServer(id); };
+process.on('exit', stopAll);
+// A signal (Ctrl+C, a `tsx watch` restart, a service manager) ends the process without an 'exit' event, which would leave the servers orphaned.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+    process.once(sig, () => { stopAll(); process.kill(process.pid, sig); });
+// If hive-am dies without any chance to clean up (kill -9, a crash), its servers survive it. They are listed on disk and stopped at the next start.
+const PIDFILE = join(DATA_DIR, 'opencode-servers.json');
+const savePids = () => { try {
+    writeFileSync(PIDFILE, JSON.stringify([...servers.values()].map((x) => x.proc.pid).filter(Boolean)));
+}
+catch { /* best effort */ } };
+function reapOrphans() {
+    if (!existsSync(PIDFILE))
+        return;
+    try {
+        for (const pid of JSON.parse(readFileSync(PIDFILE, 'utf8'))) {
+            try {
+                const cmd = execFileSync('ps', ['-p', String(pid), '-o', 'args='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+                if (/opencode/.test(cmd) && /serve --hostname 127\.0\.0\.1/.test(cmd))
+                    process.kill(pid, 'SIGTERM'); // only what is surely ours
+            }
+            catch { /* already gone */ }
+        }
+        writeFileSync(PIDFILE, '[]');
+    }
+    catch { /* unreadable list: nothing to do */ }
+}
+reapOrphans();
+const auth = (password) => ({ authorization: `Basic ${Buffer.from(`opencode:${password}`).toString('base64')}` });
+/** Waits until every MCP server the config asks for has finished connecting (connected or failed): no more "Unknown tool" at the first step. */
+async function mcpSettled(s, signal) {
+    const until = Date.now() + MCP_WAIT_MS;
+    while (Date.now() < until && !signal.aborted) {
+        try {
+            const r = await fetch(`${s.url}/api/mcp`, { headers: auth(s.password), signal: AbortSignal.timeout(2000) });
+            if (r.ok) {
+                const j = await r.json();
+                const list = Array.isArray(j?.data) ? j.data : [];
+                // Every server the config asks for must be listed (the list is empty until OpenCode starts connecting) and done connecting.
+                const done = (name) => { const m = list.find((x) => x?.name === name); return !!m?.status?.status && m.status.status !== 'connecting' && m.status.status !== 'pending'; };
+                if (s.mcp.every(done))
+                    return;
+            }
+        }
+        catch { /* not up yet */ }
+        await new Promise((r) => setTimeout(r, 150));
+    }
+}
+function launch(agentId, cwd, config, key, signal) {
+    const password = randomBytes(18).toString('base64url');
+    const proc = spawn('opencode', ['serve', '--hostname', '127.0.0.1', '--port', '0'], {
+        cwd, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, PWD: cwd, OPENCODE_CONFIG_CONTENT: JSON.stringify(config), OPENCODE_SERVER_PASSWORD: password },
+    });
+    const srv = { busy: 0, used: Date.now(), mcp: Object.keys(config?.mcp ?? {}), proc, url: '', password, key, ready: Promise.resolve() };
+    srv.ready = new Promise((resolve, reject) => {
+        let out = '';
+        const timer = setTimeout(() => reject(new Error('opencode serve did not start in time')), START_TIMEOUT_MS);
+        const onData = (d) => {
+            out = (out + d).slice(-2000);
+            const m = /listening on (http:\/\/\S+)/i.exec(out);
+            if (m && !srv.url) {
+                srv.url = m[1].replace(/\/$/, '');
+                clearTimeout(timer);
+                resolve();
+            }
+        };
+        proc.stdout.on('data', onData);
+        proc.stderr.on('data', onData); // keep draining so the pipes never fill up
+        proc.on('error', (e) => { clearTimeout(timer); reject(e); });
+        proc.on('exit', (c) => { clearTimeout(timer); if (!srv.url)
+            reject(new Error(`opencode serve exited with code ${c}`)); if (servers.get(agentId) === srv)
+            servers.delete(agentId); });
+    }).then(() => mcpSettled(srv, signal));
+    servers.set(agentId, srv);
+    savePids();
+    return srv;
+}
+/** The agent's server, started (or restarted when its config changed) and ready for a turn. Throws if it cannot start: callers fall back to a private server. */
+export async function opencodeServer(agentId, cwd, config, signal) {
+    const key = createHash('sha1').update(cwd + JSON.stringify(config)).digest('hex');
+    let s = servers.get(agentId);
+    if (s && (s.key !== key || s.proc.exitCode !== null)) {
+        stopOpencodeServer(agentId);
+        s = undefined;
+    }
+    if (!s) {
+        // Room for one more: stop the least recently used server that is not in the middle of a turn.
+        while (servers.size >= MAX_SERVERS) {
+            const idle = [...servers.entries()].filter(([, x]) => x.busy === 0).sort((a, b) => a[1].used - b[1].used)[0];
+            if (!idle)
+                break;
+            stopOpencodeServer(idle[0]);
+        }
+        s = launch(agentId, cwd, config, key, signal);
+    }
+    s.busy++;
+    s.used = Date.now();
+    if (s.idle) {
+        clearTimeout(s.idle);
+        s.idle = undefined;
+    }
+    const srv = s;
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        srv.busy = Math.max(0, srv.busy - 1);
+        srv.used = Date.now();
+        // After a burst (more agents running at once than the limit), the extra servers go as soon as their turn ends instead of lingering.
+        while (servers.size > MAX_SERVERS) {
+            const lru = [...servers.entries()].filter(([, x]) => x.busy === 0).sort((x, y) => x[1].used - y[1].used)[0];
+            if (!lru)
+                break;
+            stopOpencodeServer(lru[0]);
+        }
+        if (srv.busy === 0 && servers.get(agentId) === srv) {
+            srv.idle = setTimeout(() => { if (servers.get(agentId) === srv && srv.busy === 0)
+                stopOpencodeServer(agentId); }, IDLE_MS);
+            srv.idle.unref?.();
+        }
+    };
+    try {
+        await s.ready;
+    }
+    catch (e) {
+        release();
+        if (servers.get(agentId) === s)
+            stopOpencodeServer(agentId);
+        throw e;
+    }
+    return { url: s.url, password: s.password, release };
+}

package/server/dist/providers/opencode.js

@@ -5,6 +5,7 @@ import { spawnLines, safeJson } from './spawn.js';
 import { dispatchMcpConfigOpencode } from '../mcp-config.js';
 import { opencodeSessionDir } from '../history/opencode.js';
 import { withInstructions } from './preamble.js';
+import { opencodeServer, stopOpencodeServer } from './opencode-server.js';
 /**
  * What OpenCode may do for each permission level. It has no such modes, so they are written as its own rules (a `deny` holds even with `--auto`):
  * read-only changes nothing; editing changes files of the project (including .env, never .git or keys), runs no commands and stays in the agent's folder
@@ -29,60 +30,85 @@ export function opencodePermissions(level) {
 export async function* runOpencode(o) {
     const { agent } = o;
     const args = ['run', '--format', 'json', '--thinking', '--auto'];
-    // `opencode run` normally talks to OpenCode's background service, which ignores the config we pass through the
-    // environment. A private (standalone) server reads it, which we need for the `dispatch` MCP and to deny `question`.
-    args.splice(1, 0, '--standalone');
     // Sessions created while the folder was wrong (older hive-am builds) would keep running there; start fresh instead.
     const recorded = agent.session_id ? opencodeSessionDir(agent.session_id) : null;
     const resume = agent.session_id && (!recorded || recorded === agent.cwd) ? agent.session_id : null;
     if (resume)
         args.push('-s', resume);
+    // The reasoning level goes as the model's `#variant` (low / medium / high).
     if (agent.model)
-        args.push('-m', agent.model);
+        args.push('-m', o.effort && !agent.model.includes('#') ? `${agent.model}#${o.effort}` : agent.model);
     const prompt = withInstructions(o.prompt, o.instructions, !!resume, o.refreshInstructions);
-    args.push(prompt);
     // Turns are non-interactive: OpenCode's `question` tool would be dismissed and end the turn with exit code 1, so
     // deny it and the agent asks in plain text instead.
     const config = { permission: { question: 'deny', ...opencodePermissions(agent.permission) }, ...(o.mcpCaps.length ? dispatchMcpConfigOpencode(agent.id, o.mcpCaps) : {}) };
     const env = { OPENCODE_CONFIG_CONTENT: JSON.stringify(config) };
+    // `opencode run` normally talks to OpenCode's shared background service, which ignores the config we pass through the environment.
+    // We need that config (the `hive` MCP, `question` denied, the permission rules), so the turn goes to a server of this agent that
+    // started with it and keeps hive connected between turns. If that server cannot start, a private one-off server is used instead.
+    let access = null;
+    // Only agents answering an external chat gain enough from it (somebody is waiting for a reply and the first `channel_reply` would fail); every other agent keeps the one-off server and costs nothing between turns.
+    if (o.mcpCaps.includes('channel') && !process.env.HIVE_AM_OPENCODE_STANDALONE) {
+        try {
+            access = await opencodeServer(agent.id, agent.cwd, config, o.signal);
+        }
+        catch (e) {
+            console.warn(`[opencode] no persistent server for ${agent.name}, using a private one: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    if (access) {
+        args.splice(1, 0, '--server', access.url);
+        env.OPENCODE_SERVER_PASSWORD = access.password;
+    }
+    else
+        args.splice(1, 0, '--standalone');
+    args.push(prompt);
+    // Stopping a turn must really stop the model: a client that is killed would leave the server working on, so the server goes down with it.
+    if (access)
+        o.signal.addEventListener('abort', () => stopOpencodeServer(agent.id), { once: true });
     const seen = new Map();
     const toolStarted = new Set();
     let sawSession = false;
-    for await (const line of spawnLines({ cmd: 'opencode', args, cwd: agent.cwd, env, signal: o.signal })) {
-        const ev = safeJson(line);
-        if (!ev)
-            continue;
-        if (ev.sessionID && !sawSession) {
-            sawSession = true;
-            yield { t: 'session', sessionId: ev.sessionID };
-        }
-        const p = ev.part;
-        if (!p)
-            continue;
-        if (p.type === 'text' || p.type === 'reasoning') {
-            const text = p.text ?? '';
-            const prev = seen.get(p.id) ?? 0;
-            if (text.length > prev) {
-                seen.set(p.id, text.length);
-                yield { t: p.type === 'text' ? 'text' : 'thinking', delta: text.slice(prev) };
+    try {
+        for await (const line of spawnLines({ cmd: 'opencode', args, cwd: agent.cwd, env, signal: o.signal })) {
+            const ev = safeJson(line);
+            if (!ev)
+                continue;
+            if (ev.sessionID && !sawSession) {
+                sawSession = true;
+                yield { t: 'session', sessionId: ev.sessionID };
             }
-        }
-        else if (p.type === 'step-finish') {
-            const tk = p.tokens;
-            if (tk)
-                yield { t: 'usage', cost: p.cost || undefined, usage: { input: tk.input, output: tk.output, reasoning: tk.reasoning, cacheRead: tk.cache?.read, cacheWrite: tk.cache?.write } };
-        }
-        else if (p.type === 'tool') {
-            const st = p.state ?? {};
-            if (!toolStarted.has(p.callID ?? p.id)) {
-                toolStarted.add(p.callID ?? p.id);
-                yield { t: 'tool', id: p.callID ?? p.id, name: p.tool ?? p.name ?? 'tool', input: st.input };
+            const p = ev.part;
+            if (!p)
+                continue;
+            if (p.type === 'text' || p.type === 'reasoning') {
+                const text = p.text ?? '';
+                const prev = seen.get(p.id) ?? 0;
+                if (text.length > prev) {
+                    seen.set(p.id, text.length);
+                    yield { t: p.type === 'text' ? 'text' : 'thinking', delta: text.slice(prev) };
+                }
             }
-            if (st.status === 'completed' || st.status === 'error') {
-                const out = typeof st.output === 'string' ? st.output : Array.isArray(st.content) ? st.content.map((c) => c.text ?? '').join('\n') : '';
-                yield { t: 'tool_result', id: p.callID ?? p.id, output: out, error: st.status === 'error' };
+            else if (p.type === 'step-finish') {
+                const tk = p.tokens;
+                if (tk)
+                    yield { t: 'usage', cost: p.cost || undefined, usage: { input: tk.input, output: tk.output, reasoning: tk.reasoning, cacheRead: tk.cache?.read, cacheWrite: tk.cache?.write } };
+            }
+            else if (p.type === 'tool') {
+                const st = p.state ?? {};
+                if (!toolStarted.has(p.callID ?? p.id)) {
+                    toolStarted.add(p.callID ?? p.id);
+                    yield { t: 'tool', id: p.callID ?? p.id, name: p.tool ?? p.name ?? 'tool', input: st.input };
+                }
+                if (st.status === 'completed' || st.status === 'error') {
+                    const out = typeof st.output === 'string' ? st.output : Array.isArray(st.content) ? st.content.map((c) => c.text ?? '').join('\n') : '';
+                    yield { t: 'tool_result', id: p.callID ?? p.id, output: out, error: st.status === 'error' };
+                }
             }
         }
     }
+    finally {
+        access?.release();
+    }
     yield { t: 'done', ok: true };
 }

package/server/dist/runtime.js

@@ -19,6 +19,7 @@ export const liveTurn = (id) => states.get(id)?.live ?? null;
 export const queueDepth = (id) => states.get(id)?.queued ?? 0;
 /** The channel message the agent is answering right now, if the running turn came from one. */
 export const liveOrigin = (id) => states.get(id)?.live?.origin;
+export const liveSource = (id) => states.get(id)?.live?.source;
 /** Whether the turn running now is the agent's own conversation (not work delegated to it by an orchestrator). */
 export const liveIsDirect = (id) => states.get(id)?.live?.source === 'user';
 /** Queue a prompt for an agent. Turns for one agent run strictly one at a time. */
@@ -71,7 +72,7 @@ async function execute(agentId, prompt, source, from, dispatchId, origin) {
         const stream = runners[agent.provider]({
             agent, prompt, signal: controller.signal,
             instructions, refreshInstructions,
-            mcpCaps: mcpCaps(agent),
+            mcpCaps: mcpCaps(agent), effort: origin?.effort,
         });
         for await (const ev of stream) {
             if (ev.t === 'session') {

package/server/dist/schedules.js

@@ -0,0 +1,241 @@
+import { randomUUID } from 'node:crypto';
+import { agents, db } from './db.js';
+import { CronError, minGapMinutes, nextCron, nextRuns, parseCron, serverTimezone, validTimezone } from './cron.js';
+import { adapterFor } from './connections/manager.js';
+import { deliverScheduled } from './connections/router.js';
+import { connections, threads } from './connections/store.js';
+import { liveOrigin, liveSource, queueDepth, sendTurn } from './runtime.js';
+/**
+ * Recurring schedules an agent sets for itself ("every weekday at 9, check the QA logs and tell me"). Like a wake-up, a run reaches the agent
+ * in the place where the schedule was made: the same chat thread, or its own web conversation. Cost is bounded: a minimum interval between runs,
+ * a limit per agent, no catching up after an outage (a missed run is skipped, never replayed) and no run while the agent is already behind.
+ */
+export class ScheduleError extends Error {
+}
+const MS_PER_MINUTE = Number(process.env.HIVE_AM_WAKE_MS_PER_MINUTE) || 60_000; // tests shrink a "minute" (only for "every N minutes")
+export const MIN_INTERVAL_MINUTES = Number(process.env.HIVE_AM_SCHEDULE_MIN_MINUTES) || 15;
+export const MAX_PER_AGENT = 10;
+const MISSED_GRACE_MS = 5 * 60_000; // a run later than this (the server was down) is skipped
+const BUSY_QUEUE = 2; // skip a run when this many messages already wait for the agent
+const KEEP_RUNS = 50;
+const MAX_TIMER_MS = 2_147_483_647;
+db.exec(`
+CREATE TABLE IF NOT EXISTS agent_schedules (
+  id TEXT PRIMARY KEY, agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  connection_id TEXT, thread_id TEXT REFERENCES threads(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL, expr TEXT NOT NULL, tz TEXT NOT NULL, note TEXT NOT NULL,
+  enabled INTEGER NOT NULL DEFAULT 1, next_due INTEGER, created_at INTEGER NOT NULL,
+  last_fired_at INTEGER, fire_count INTEGER NOT NULL DEFAULT 0, last_status TEXT, last_detail TEXT
+);
+CREATE TABLE IF NOT EXISTS schedule_runs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, schedule_id TEXT NOT NULL REFERENCES agent_schedules(id) ON DELETE CASCADE,
+  fired_at INTEGER NOT NULL, status TEXT NOT NULL, detail TEXT, duration_ms INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_schedule_runs ON schedule_runs (schedule_id, id);`);
+// Who asked (only kept when it was in a group): each run mentions them. Older databases get the columns here.
+for (const col of ['req_id TEXT', 'req_name TEXT']) {
+    try {
+        db.exec(`ALTER TABLE agent_schedules ADD COLUMN ${col}`);
+    }
+    catch { /* already there */ }
+}
+const fromRow = (r) => ({ ...r, enabled: !!r.enabled });
+const store = {
+    get: (id) => { const r = db.prepare('SELECT * FROM agent_schedules WHERE id=?').get(id); return r ? fromRow(r) : undefined; },
+    all: () => db.prepare('SELECT * FROM agent_schedules ORDER BY created_at').all().map(fromRow),
+    forAgent: (agentId) => db.prepare('SELECT * FROM agent_schedules WHERE agent_id=? ORDER BY created_at').all(agentId).map(fromRow),
+    remove: (id) => db.prepare('DELETE FROM agent_schedules WHERE id=?').run(id).changes > 0,
+    setNext: (id, next) => db.prepare('UPDATE agent_schedules SET next_due=? WHERE id=?').run(next, id),
+    setEnabled: (id, on, next) => db.prepare('UPDATE agent_schedules SET enabled=?, next_due=? WHERE id=?').run(on ? 1 : 0, next, id),
+    record(id, status, detail, durationMs, firedAt) {
+        db.prepare('INSERT INTO schedule_runs (schedule_id,fired_at,status,detail,duration_ms) VALUES (?,?,?,?,?)').run(id, firedAt, status, detail, durationMs);
+        db.prepare(`DELETE FROM schedule_runs WHERE schedule_id=? AND id NOT IN (SELECT id FROM schedule_runs WHERE schedule_id=? ORDER BY id DESC LIMIT ${KEEP_RUNS})`).run(id, id);
+        db.prepare('UPDATE agent_schedules SET last_status=?, last_detail=?, last_fired_at=?, fire_count=fire_count+? WHERE id=?').run(status, detail, firedAt, status === 'delivered' ? 1 : 0, id);
+    },
+    runs: (id, limit = KEEP_RUNS) => db.prepare('SELECT id,fired_at,status,detail,duration_ms FROM schedule_runs WHERE schedule_id=? ORDER BY id DESC LIMIT ?').all(id, limit),
+};
+const hhmm = (t, tz) => new Date(t).toLocaleString('en-GB', { timeZone: tz, weekday: 'short', day: '2-digit', month: 'short', hour: '2-digit', minute: '2-digit' });
+export const describe = (s) => s.kind === 'every' ? `every ${s.expr} min` : `${s.expr} (${s.tz})`;
+/** Next run after `after`. "every N" keeps its rhythm from the previous due time instead of drifting by the run time. */
+function computeNext(s, after, from) {
+    if (s.kind === 'cron')
+        return nextCron(s.expr, s.tz, after);
+    const step = Number(s.expr) * MS_PER_MINUTE;
+    let t = (from ?? after) + step;
+    if (t <= after)
+        t += Math.ceil((after - t + 1) / step) * step;
+    return t;
+}
+// ---- timers ----
+const timers = new Map();
+function arm(s) {
+    const old = timers.get(s.id);
+    if (old)
+        clearTimeout(old);
+    timers.delete(s.id);
+    if (!s.enabled || s.next_due === null)
+        return;
+    const delay = Math.max(0, Math.min(s.next_due - Date.now(), MAX_TIMER_MS));
+    const t = setTimeout(() => { if (s.next_due !== null && s.next_due - Date.now() > 1000)
+        arm(store.get(s.id) ?? s);
+    else
+        void fire(s.id); }, delay);
+    t.unref?.();
+    timers.set(s.id, t);
+}
+const disarm = (id) => { const t = timers.get(id); if (t)
+    clearTimeout(t); timers.delete(id); };
+function text(s, web) {
+    const tool = web ? '' : ' with channel_reply';
+    return `${web ? '🔔 ' : ''}Scheduled task (${describe(s)}${s.req_name ? `, asked by ${s.req_name}` : ''}). Your note: ${s.note}\n\n${s.req_name ? `hive-am mentions ${s.req_name} at the start of your first reply, so do not mention them yourself. ` : ''}Do what the note says now and tell the person the result${tool}. If there is nothing worth reporting, say so in one line. You can see or stop your schedules with schedule_list / schedule_cancel.`;
+}
+async function fire(id) {
+    timers.delete(id);
+    const s = store.get(id);
+    if (!s || !s.enabled)
+        return;
+    const now = Date.now(), due = s.next_due ?? now;
+    const next = computeNext(s, now, s.kind === 'every' ? due : null);
+    store.setNext(id, next); // the next run is fixed before anything else can fail
+    arm({ ...s, next_due: next });
+    const skip = (status, detail) => store.record(id, status, detail, null, now);
+    const agent = agents.get(s.agent_id);
+    if (!agent) {
+        store.remove(id);
+        return;
+    }
+    if (now - due > MISSED_GRACE_MS)
+        return skip('skipped_missed', `due ${hhmm(due, s.tz)}, ${Math.round((now - due) / 60000)} min late (the server was down)`);
+    if (queueDepth(agent.id) >= BUSY_QUEUE)
+        return skip('skipped_busy', 'the agent already had messages waiting');
+    const started = Date.now();
+    try {
+        if (s.thread_id) {
+            const conn = connections.get(s.connection_id ?? ''), thread = threads.get(s.thread_id);
+            if (!conn || !thread) {
+                store.remove(id);
+                disarm(id);
+                return;
+            }
+            if (!conn.enabled)
+                return skip('skipped_disabled', 'the connection is disabled');
+            if (conn.agent_id !== s.agent_id) {
+                store.setEnabled(id, false, null);
+                disarm(id);
+                return skip('skipped_reassigned', 'the connection now belongs to another agent; the schedule was paused');
+            }
+            if (thread.muted)
+                return skip('skipped_muted', 'the thread is muted');
+            const adapter = adapterFor(conn.id);
+            if (!adapter)
+                return skip('skipped_disabled', 'the connection was not running');
+            store.record(id, 'delivered', null, null, started);
+            await deliverScheduled(conn, adapter, thread, text(s, false), s.req_id ? { id: s.req_id, name: s.req_name || 'you' } : undefined);
+        }
+        else {
+            store.record(id, 'delivered', null, null, started);
+            await sendTurn(agent.id, text(s, true), 'user');
+        }
+        db.prepare('UPDATE schedule_runs SET duration_ms=? WHERE schedule_id=? AND fired_at=? AND status=?').run(Date.now() - started, id, started, 'delivered');
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        db.prepare('UPDATE schedule_runs SET status=?, detail=? WHERE schedule_id=? AND fired_at=? AND status=?').run('failed', msg, id, started, 'delivered');
+        db.prepare('UPDATE agent_schedules SET last_status=?, last_detail=?, fire_count=MAX(0,fire_count-1) WHERE id=?').run('failed', msg, id);
+        console.warn(`[schedules] run of "${s.note.slice(0, 40)}" failed: ${msg}`);
+    }
+}
+/** Arms every saved schedule (called once at startup). A run missed while the server was down is skipped, not replayed. */
+export function armSchedules() {
+    for (const s of store.all()) {
+        if (!s.enabled)
+            continue;
+        if (s.next_due !== null && s.next_due < Date.now())
+            void fire(s.id);
+        else
+            arm(s);
+    }
+}
+export function createSchedule(agentId, input) {
+    if (!agents.get(agentId))
+        throw new ScheduleError('Unknown agent');
+    if (liveSource(agentId) === 'dispatch')
+        throw new ScheduleError('Schedules are not available while you work on a task delegated by an orchestrator.');
+    const note = String(input.note ?? '').trim();
+    if (!note)
+        throw new ScheduleError('Say in the note what to do at each run.');
+    if (note.length > 400)
+        throw new ScheduleError('The note is too long (400 characters at most).');
+    const tz = input.timezone === undefined || input.timezone === '' ? serverTimezone() : String(input.timezone);
+    if (!validTimezone(tz))
+        throw new ScheduleError(`Unknown time zone "${tz}". Use an IANA name such as America/Mexico_City.`);
+    const hasCron = input.cron !== undefined && String(input.cron).trim() !== '', hasEvery = input.every_minutes !== undefined && input.every_minutes !== null;
+    if (hasCron === hasEvery)
+        throw new ScheduleError('Give either "cron" (for example "0 9 * * MON-FRI") or "every_minutes", not both and not neither.');
+    let kind, expr, first;
+    const now = Date.now();
+    if (hasCron) {
+        kind = 'cron';
+        expr = String(input.cron).trim();
+        try {
+            parseCron(expr);
+        }
+        catch (e) {
+            throw new ScheduleError(e instanceof CronError ? e.message : String(e));
+        }
+        const gap = minGapMinutes(expr, tz, now);
+        if (gap < MIN_INTERVAL_MINUTES)
+            throw new ScheduleError(`Runs would be only ${gap} min apart; the minimum is ${MIN_INTERVAL_MINUTES} min. Choose a less frequent schedule.`);
+        first = nextCron(expr, tz, now);
+    }
+    else {
+        kind = 'every';
+        const m = Number(input.every_minutes);
+        if (!Number.isFinite(m) || m < MIN_INTERVAL_MINUTES || m > 60 * 24 * 31)
+            throw new ScheduleError(`every_minutes must be between ${MIN_INTERVAL_MINUTES} and ${60 * 24 * 31}.`);
+        expr = String(Math.round(m));
+        first = now + Math.round(m) * MS_PER_MINUTE;
+    }
+    if (first === null)
+        throw new ScheduleError('That schedule never runs.');
+    const origin = liveOrigin(agentId), thread = origin ? threads.get(origin.threadId) : undefined;
+    if (origin && !thread)
+        throw new ScheduleError('The thread no longer exists.');
+    const mine = store.forAgent(agentId);
+    if (mine.length >= MAX_PER_AGENT)
+        throw new ScheduleError(`You already have ${MAX_PER_AGENT} schedules. Cancel one with schedule_cancel first.`);
+    const dup = mine.find((x) => x.kind === kind && x.expr === expr && x.tz === tz && x.note.toLowerCase() === note.toLowerCase() && x.thread_id === (thread?.id ?? null));
+    if (dup)
+        return { schedule: dup, next: kind === 'cron' ? nextRuns(expr, tz, now, 3).map((t) => hhmm(t, tz)) : [hhmm(dup.next_due ?? first, tz)], where: thread ? 'thread' : 'chat' };
+    const id = randomUUID();
+    db.prepare('INSERT INTO agent_schedules (id,agent_id,connection_id,thread_id,kind,expr,tz,note,enabled,next_due,created_at,req_id,req_name) VALUES (?,?,?,?,?,?,?,?,1,?,?,?,?)')
+        .run(id, agentId, origin?.connectionId ?? null, thread?.id ?? null, kind, expr, tz, note, first, now, origin?.group && origin.userId ? origin.userId : null, origin?.group && origin.userId ? origin.userName : null);
+    const schedule = store.get(id);
+    arm(schedule);
+    return { schedule, next: kind === 'cron' ? nextRuns(expr, tz, now, 3).map((t) => hhmm(t, tz)) : [hhmm(first, tz)], where: thread ? 'thread' : 'chat' };
+}
+export function listFor(agentId) {
+    return store.forAgent(agentId).map((s) => ({ id: s.id, schedule: describe(s), note: s.note, enabled: s.enabled, next: s.next_due ? hhmm(s.next_due, s.tz) : null, last: s.last_status }));
+}
+export function cancelFor(agentId, id) {
+    const s = store.get(id);
+    if (!s || s.agent_id !== agentId)
+        throw new ScheduleError('You have no schedule with that id. Use schedule_list to see yours.');
+    disarm(id);
+    return store.remove(id);
+}
+export function listAll() {
+    return store.all().map((s) => ({ ...s, agent_name: agents.get(s.agent_id)?.name ?? '?', place: s.thread_id ? (threads.get(s.thread_id)?.title || 'chat') : '', description: describe(s) }));
+}
+export const runsOf = (id) => store.runs(id);
+export function setEnabled(id, on) {
+    const s = store.get(id);
+    if (!s)
+        return undefined;
+    const next = on ? computeNext(s, Date.now(), null) : null;
+    store.setEnabled(id, on, next);
+    const u = store.get(id);
+    arm(u);
+    return u;
+}
+export function removeSchedule(id) { disarm(id); return store.remove(id); }