hive-am 1.3.0 → 1.5.0

package/server/dist/objects/index.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DATA_DIR, agents, resolved } from '../db.js';
-import { OBJECTS_SKILL_ID } from '../skills/defaults.js';
+import { DATABASES_SKILL_ID, OBJECTS_SKILL_ID } from '../skills/defaults.js';
 import { bus } from '../runtime.js';
 import { renderTemplate, listTemplates } from './templates.js';
 import { composeServiceAction, inspectDocker, recreateDocker, dockerLogs, dockerState, removeDocker, restartDocker, startDocker, stopDocker } from './docker.js';
@@ -10,7 +10,7 @@ import { dbColumns, dbQuery, dbSchema, dbState, dbTest, forgetDatabase } from '.
 import { addSaved, clearQueries, forgetQueries, listQueries, listSaved, recordQuery, removeSaved, updateSaved } from './db-history.js';
 import { exportCollection, parseHttpFile, createHttpFile, exportHttp, describeHttp, dropSession, inspectHttp, readHttpFile, runHttp, scanHttp, writeHttpFile, sessionClear, sessionOf, sessionSet, sessionView } from './http.js';
 import { ObjectError, parseDatabase } from './model.js';
-import { forgetServer, serverLogs, serverState, startServer, stopServer } from './runner.js';
+import { forgetServer, serverLogs, restartServer, serverState, startServer, stopServer } from './runner.js';
 import { forgetSupervision, resetSupervision, supervise } from './supervisor.js';
 import { maskConfig, objectsStore } from './store.js';
 export { ObjectError } from './model.js';
@@ -59,7 +59,7 @@ function clusterState(o) {
 async function serverStateSupervised(o) {
     const cfg = o.config;
     const base = await serverState(o.id, cfg);
-    return supervise(o, cfg, base, { start: () => startServer(o.id, cfg), restart: async () => { await stopServer(o.id, cfg); await startServer(o.id, cfg); } });
+    return supervise(o, cfg, base, { start: () => startServer(o.id, cfg), restart: () => restartServer(o.id, cfg) });
 }
 export async function stateOf(o) {
     const s = o.kind === 'server' ? await serverStateSupervised(o)
@@ -113,10 +113,8 @@ async function act(o, action) {
             await startServer(o.id, c);
         else if (action === 'stop')
             await stopServer(o.id, c);
-        else {
-            await stopServer(o.id, c);
-            await startServer(o.id, c);
-        }
+        else
+            await restartServer(o.id, c);
     }
     else {
         const c = o.config;
@@ -363,15 +361,19 @@ export const dbSavedUpdate = (id, savedId, p) => {
 export const dbSavedRemove = (id, savedId) => { dbOf(id); if (!removeSaved(id, savedId))
     throw new ObjectError('Saved query not found'); return listSaved(id); };
 /** Only these can be looked after by an agent: it starts, stops and restarts them. */
-const MANAGEABLE = ['server', 'docker', 'cluster'];
-/** An agent without the "Colony resources" skill gets it when it is made the manager of something: without it the tools are not offered. */
-function ensureSkill(agentId) {
+const MANAGEABLE = ['server', 'docker', 'cluster', 'database'];
+/**
+ * An agent without the skill that goes with a resource gets it when it is made its manager: without it the tools are not offered.
+ * A database goes with "Database management"; the other kinds with "Colony resources".
+ */
+function ensureSkill(agentId, kind) {
     const ag = agents.get(agentId);
     if (!ag)
         throw new ObjectError('That agent no longer exists');
-    if (resolved(ag).skill_ids.includes(OBJECTS_SKILL_ID))
+    const skill = kind === 'database' ? DATABASES_SKILL_ID : OBJECTS_SKILL_ID;
+    if (resolved(ag).skill_ids.includes(skill))
         return false;
-    agents.setSkills(agentId, [...ag.skill_ids, OBJECTS_SKILL_ID]);
+    agents.setSkills(agentId, [...ag.skill_ids, skill]);
     return true;
 }
 /** Chooses the one agent that looks after a resource (`null` leaves it to the agents of its colony). */
@@ -380,7 +382,7 @@ export function setObjectManager(id, agentId) {
     if (!MANAGEABLE.includes(o.kind))
         throw new ObjectError('This kind of resource is not looked after by agents');
     const a = agentId ? String(agentId) : null;
-    const skillAdded = a ? ensureSkill(a) : false;
+    const skillAdded = a ? ensureSkill(a, o.kind) : false;
     objectsStore.setManager(id, a);
     changed();
     return { object: viewOf(o), skillAdded };
@@ -393,12 +395,16 @@ export function setAgentObjects(agentId, objectIds) {
         throw new ObjectError('Choose the resources');
     const want = new Set(objectIds.map(String));
     const managers = objectsStore.managers();
+    const kinds = new Set();
     for (const id of want) {
         const o = get(id);
         if (!MANAGEABLE.includes(o.kind))
             throw new ObjectError('This kind of resource is not looked after by agents');
+        kinds.add(o.kind === 'database' ? 'database' : 'other');
     }
-    const skillAdded = want.size > 0 ? ensureSkill(agentId) : false;
+    let skillAdded = false;
+    for (const k of kinds)
+        skillAdded = ensureSkill(agentId, k === 'database' ? 'database' : 'server') || skillAdded;
     for (const [oid, aid] of managers)
         if (aid === agentId && !want.has(oid))
             objectsStore.setManager(oid, null);

package/server/dist/objects/runner.js

@@ -139,6 +139,26 @@ export async function stopServer(id, cfg) {
             await sleep(100);
     }
 }
+/**
+ * Stop, then start again. With a port, the old listener must be gone before the new one starts: otherwise the check on the port would
+ * report "running" for the old process (a stop command that does not really stop the service) while the new one failed to bind.
+ */
+export async function restartServer(id, cfg) {
+    await stopServer(id, cfg);
+    if (cfg.port) {
+        const grace = cfg.stopTimeoutSec ? cfg.stopTimeoutSec * 1000 : STOP_GRACE_MS;
+        let waited = 0;
+        while (await listening(cfg.port) && waited < grace) {
+            await sleep(300);
+            waited += 300;
+        }
+        if (await listening(cfg.port)) {
+            note(id, `port ${cfg.port} is still in use after stopping: not starting it again. Check that the stop command really stops the service`);
+            throw new ObjectError(`Port ${cfg.port} is still in use after stopping, so it was not started again. Check that the stop command really stops the service.`);
+        }
+    }
+    await startServer(id, cfg);
+}
 /** Lines the object printed. `after` is a byte offset from an earlier call; without it the last `tail` lines come back. */
 export function serverLogs(id, o) {
     const { log } = files(id);

package/server/dist/objects/supervisor.js

@@ -54,8 +54,8 @@ export async function supervise(o, cfg, state, act) {
         if (S.startedAt !== saved?.startedAt) {
             S.startedAt = saved?.startedAt ?? 0;
             S.fails = 0;
-            S.lastCheck = 0;
-        }
+            S.lastCheck = now;
+        } // a new start: the first check comes one interval later, not right away
         if (now - S.lastCheck >= (cfg.health.intervalSec ?? 15) * 1000) {
             S.lastCheck = now;
             const r = await check(cfg, cfg.health);

package/server/dist/providers/kiro.js

@@ -1,3 +1,4 @@
+import { learnEfforts } from '../efforts.js';
 import { spawnJson } from './spawn.js';
 import { withInstructions } from './preamble.js';
 import { writeFileSync, mkdirSync } from 'node:fs';
@@ -37,7 +38,8 @@ export async function* runKiro(o) {
     if (o.effort)
         args.push('--effort', o.effort);
     const prompt = withInstructions(o.prompt, o.instructions, !!agent.session_id, o.refreshInstructions);
-    args.push(prompt);
+    // After `--` so a message that begins with a dash is the prompt and never an option; nothing may be pushed after it.
+    args.push('--', prompt);
     let sawSession = false;
     const open = new Set();
     for await (const ev of spawnJson({ cmd: 'kiro-cli', args, cwd: agent.cwd, signal: o.signal })) {
@@ -46,6 +48,10 @@ export async function* runKiro(o) {
             sawSession = true;
             yield { t: 'session', sessionId: d.sessionId };
         }
+        // The turn's metadata says which reasoning levels the model takes: remembered per model, so the agent form offers only those.
+        if (ev.type === 'metadata' && agent.model && Array.isArray(d.reasoning?.effortLevels) && d.reasoning.effortLevels.length) {
+            learnEfforts('kiro', { [agent.model]: d.reasoning.effortLevels.filter((l) => typeof l === 'string').map((l) => ({ id: l })) });
+        }
         if (ev.type === 'metadata' && (d.meteringUsage || d.contextUsagePercentage !== undefined)) {
             const credits = (d.meteringUsage ?? []).reduce((n, m) => n + (m.value ?? 0), 0);
             yield { t: 'usage', durationMs: d.turnDurationMs, usage: { credits: credits || undefined, contextPct: d.contextUsagePercentage } };

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

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { DATA_DIR } from '../db.js';
 import { createHash, randomBytes } from 'node:crypto';
 import { learnWindows } from '../context.js';
+import { learnEfforts } from '../efforts.js';
 /**
  * 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
@@ -63,7 +64,14 @@ let windowsAt = 0;
  * Reads the context window of every model from OpenCode's catalog, using this turn's server, any running one or a short-lived one
  * (about 4 s and 150 MB, once). At most once an hour, and a failure waits ten minutes: OpenCode 1.x has no catalog endpoint at all.
  */
-export async function learnOpencodeWindows(cwd, access) {
+export function learnOpencodeWindows(cwd, access) {
+    if (learning)
+        return learning; // a read is under way (a turn and the agent form can ask at the same time): both wait for it
+    learning = readCatalog(cwd, access).finally(() => { learning = null; });
+    return learning;
+}
+let learning = null;
+async function readCatalog(cwd, access) {
     if (Date.now() - windowsAt < 60 * 60_000)
         return;
     windowsAt = Date.now();
@@ -107,6 +115,8 @@ export async function learnOpencodeWindows(cwd, access) {
         if (!list.length)
             throw new Error('the model catalog stayed empty');
         learnWindows('opencode', Object.fromEntries(list.map((m) => [`${m.providerID}/${m.id}`, Number(m.limit?.context)])));
+        // Every model carries the variants it takes (`id` goes after `#`, `settings.reasoningEffort` is the level it stands for); a model with none takes no effort.
+        learnEfforts('opencode', Object.fromEntries(list.map((m) => [`${m.providerID}/${m.id}`, (Array.isArray(m.variants) ? m.variants : []).map((v) => ({ id: String(v?.id), level: typeof v?.settings?.reasoningEffort === 'string' ? v.settings.reasoningEffort : undefined }))])));
     }
     catch {
         windowsAt = Date.now() - 50 * 60_000; /* try again in ten minutes */

package/server/dist/providers/opencode.js

@@ -2,7 +2,7 @@ import { DATA_DIR } from '../db.js';
 import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 const INBOX_ROOT = join(DATA_DIR, 'inbox');
-import { spawnJson } from './spawn.js';
+import { spawnJson, StalledError } from './spawn.js';
 import { dispatchMcpConfigOpencode } from '../mcp-config.js';
 import { opencodeSessionDir } from '../history/opencode.js';
 import { withInstructions } from './preamble.js';
@@ -93,7 +93,8 @@ export async function* runOpencode(o) {
     }
     else if (has('--standalone'))
         args.splice(1, 0, '--standalone'); // 1.x always runs its own server
-    args.push(prompt);
+    // After `--` so a message that begins with a dash is the prompt and never an option; nothing may be pushed after it.
+    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 });
@@ -144,7 +145,7 @@ export async function* runOpencode(o) {
             throw new Error(failure);
     }
     catch (e) {
-        if (failure && !o.signal.aborted)
+        if (failure && !o.signal.aborted && !(e instanceof StalledError))
             throw new Error(failure); // OpenCode's own reason says more than "exited with code 1"
         throw e;
     }

package/server/dist/providers/spawn.js

@@ -1,6 +1,12 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
+/** A CLI that prints nothing for this long has hung (a long turn is fine as long as it keeps emitting). */
+const STALL_MS = () => Number(process.env.HIVE_AM_TURN_STALL_MS) || 10 * 60_000;
+const quietFor = (ms) => ms >= 60_000 ? `${Math.round(ms / 6000) / 10} minutes` : `${Math.round(ms / 100) / 10} seconds`;
 const KILL_GRACE_MS = Number(process.env.HIVE_AM_KILL_GRACE_MS) || 5000;
+/** The CLI hung and was cut off; adapters must not replace this reason with an error the dying CLI printed. */
+export class StalledError extends Error {
+}
 /** Spawns a CLI and yields its stdout lines. Throws with stderr tail if it exits non-zero and nothing aborted it. */
 export async function* spawnLines(o) {
     const child = spawn(o.cmd, o.args, {
@@ -21,6 +27,15 @@ export async function* spawnLines(o) {
         hardKill.unref?.();
     };
     o.signal.addEventListener('abort', kill, { once: true });
+    // Silence, not length: the timer restarts on every stdout line and, when it fires, ends the CLI like a Stop would, but the turn fails with its own text.
+    let stalled = false;
+    let stallTimer;
+    const armStall = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => { stalled = true; kill(); }, STALL_MS());
+        stallTimer.unref?.();
+    };
+    armStall();
     let stderr = '';
     child.stderr.on('data', (d) => { stderr = (stderr + d).slice(-4000); });
     const exit = new Promise((res) => {
@@ -28,7 +43,7 @@ export async function* spawnLines(o) {
         // 'exit' (not 'close'): a daemon the CLI forks (e.g. opencode's background service) can keep
         // inheriting our stdout pipe forever, so 'close' would never fire. Drain briefly, then cut the pipe.
         child.on('exit', (c) => { if (hardKill)
-            clearTimeout(hardKill); setTimeout(() => child.stdout.destroy(), 250); res(c); });
+            clearTimeout(hardKill); setTimeout(() => { child.stdout.destroy(); child.stderr.destroy(); }, 250); res(c); });
     });
     child.stdin.on('error', () => { });
     if (o.stdin !== undefined)
@@ -36,15 +51,23 @@ export async function* spawnLines(o) {
     else
         child.stdin.end();
     try {
-        for await (const line of createInterface({ input: child.stdout }))
+        // readline only ends on the stream's 'end'; a stream we destroy (the exit handler above) emits 'close' alone, so close it ourselves.
+        const rl = createInterface({ input: child.stdout });
+        child.stdout.on('close', () => rl.close());
+        for await (const line of rl) {
+            armStall();
             if (line.trim())
                 yield line;
+        }
     }
     finally {
+        clearTimeout(stallTimer);
         o.signal.removeEventListener('abort', kill);
         kill();
     }
     const code = await exit;
+    if (stalled && !o.signal.aborted)
+        throw new StalledError(`${o.cmd} stopped answering (nothing on stdout for ${quietFor(STALL_MS())})`);
     if (code !== 0 && !o.signal.aborted)
         throw new Error(`${o.cmd} exited with code ${code}${stderr ? `: ${stderr.trim().slice(-600)}` : ''}`);
 }
@@ -56,13 +79,24 @@ export function safeJson(line) {
         return null;
     }
 }
-/** The JSON objects a CLI prints, one per line; lines that are not JSON (banners, warnings) are skipped. */
+/**
+ * The JSON objects a CLI prints, one per line; lines that are not JSON (banners, warnings) are skipped.
+ * A CLI that exits cleanly having printed only prose (its usage text, say) has not answered: that is an error carrying its first line.
+ */
 export async function* spawnJson(o) {
+    let events = 0;
+    let firstNoise = '';
     for await (const line of spawnLines(o)) {
         const ev = safeJson(line);
-        if (ev)
+        if (ev) {
+            events++;
             yield ev;
+        }
+        else
+            firstNoise ||= line.trim();
     }
+    if (!events && firstNoise && !o.signal.aborted)
+        throw new Error(`${o.cmd} produced no events, it printed: ${firstNoise.slice(0, 300)}`);
 }
 /** The text of a tool result, which CLIs send as a string, a list of blocks or any other JSON. */
 export function flattenText(c) {

package/server/dist/retention.js

@@ -0,0 +1,50 @@
+import { db } from './db.js';
+import { historySig } from './history/index.js';
+import { RETENTION_DAYS } from './connections/files.js';
+/**
+ * What hive-am keeps of its own record, and for how long. Three tables only ever grew: the messages of channel conversations, the log of
+ * delegations and the list of known conversations. The conversations themselves live in each CLI's own store and are never touched here:
+ * only hive-am's copy (the row that lists them) goes. A row is removed only when it is past its cap AND old enough, so nothing recent is lost.
+ */
+export const KEEP_THREAD_MESSAGES = 500; // the newest of each thread...
+export const MESSAGE_DAYS = 30; // ...and anything younger than this, whatever the count
+export const KEEP_DISPATCHES = 200; // the screen shows 50
+export const KEEP_DELEGATIONS = 50; // delegated conversations per agent (a read-only log), kept while younger than SESSION_FORGET_DAYS
+export const SESSION_FORGET_DAYS = 90; // a conversation not used for this long, and that the CLI no longer has, is forgotten
+// Received files live RETENTION_DAYS (connections/files.ts, 14): the record of a file on a message goes with the file.
+const DAY = 86_400_000;
+export function retentionPass({ now = Date.now() } = {}) {
+    const forgetBefore = now - SESSION_FORGET_DAYS * DAY;
+    // A direct conversation goes only when it is old AND its transcript is gone. `historySig` is null for a failed read too: the age is what makes that harmless.
+    const gone = [];
+    const old = db.prepare("SELECT s.agent_id, s.session_id, s.provider, s.cwd FROM agent_sessions s WHERE s.kind='direct' AND s.last_seen < ? AND s.session_id IS NOT (SELECT session_id FROM agents WHERE id=s.agent_id)")
+        .all(forgetBefore);
+    for (const s of old)
+        if (historySig({ provider: s.provider, cwd: s.cwd }, s.session_id) === null)
+            gone.push(s);
+    return db.transaction(() => {
+        const out = { messages: 0, dispatches: 0, sessions: 0, files: 0 };
+        // Messages: beyond the newest KEEP_THREAD_MESSAGES of their thread and older than the window.
+        const cut = db.prepare('SELECT id FROM thread_messages WHERE thread_id=? ORDER BY id DESC LIMIT 1 OFFSET ?');
+        const drop = db.prepare('DELETE FROM thread_messages WHERE thread_id=? AND id<? AND ts<?');
+        for (const { thread_id } of db.prepare('SELECT DISTINCT thread_id FROM thread_messages').all()) {
+            const edge = cut.get(thread_id, KEEP_THREAD_MESSAGES - 1);
+            if (edge)
+                out.messages += drop.run(thread_id, edge.id, now - MESSAGE_DAYS * DAY).changes;
+        }
+        // The record of a received file goes with the file.
+        out.files = db.prepare('UPDATE thread_messages SET files=NULL WHERE files IS NOT NULL AND ts<?').run(now - RETENTION_DAYS * DAY).changes;
+        // Delegations: all but the newest KEEP_DISPATCHES (one that is still running is never one of them).
+        out.dispatches = db.prepare("DELETE FROM dispatches WHERE status<>'running' AND id IN (SELECT id FROM dispatches ORDER BY created_at DESC, id DESC LIMIT -1 OFFSET ?)").run(KEEP_DISPATCHES).changes;
+        // Delegated conversations: past the newest KEEP_DELEGATIONS of their agent and not used for SESSION_FORGET_DAYS.
+        out.sessions += db.prepare(`DELETE FROM agent_sessions WHERE kind='delegation' AND last_seen<? AND (agent_id, session_id) IN (
+      SELECT agent_id, session_id FROM (SELECT agent_id, session_id, ROW_NUMBER() OVER (PARTITION BY agent_id ORDER BY last_seen DESC, session_id) AS n FROM agent_sessions WHERE kind='delegation') WHERE n>?)`)
+            .run(forgetBefore, KEEP_DELEGATIONS).changes;
+        // Direct conversations the CLI no longer has (the current one of an agent was left out above, and is checked again here).
+        const del = db.prepare("DELETE FROM agent_sessions WHERE agent_id=? AND session_id=? AND kind='direct' AND session_id IS NOT (SELECT session_id FROM agents WHERE id=?)");
+        for (const g of gone)
+            out.sessions += del.run(g.agent_id, g.session_id, g.agent_id).changes;
+        return out;
+    })();
+}
+export const retentionTouched = (r) => r.messages + r.dispatches + r.sessions + r.files > 0;

package/server/dist/runtime.js

@@ -4,6 +4,7 @@ import { agents, dispatches, resolved } from './db.js';
 import { composeInstructions, mcpCaps, notebookBlock } from './instructions.js';
 import { runners } from './providers/index.js';
 import { notebooks } from './skills/notebook.js';
+import { resolveEffort } from './efforts.js';
 export const bus = new EventEmitter();
 bus.setMaxListeners(0);
 const emit = (m) => bus.emit('msg', m);
@@ -22,6 +23,19 @@ 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';
+/**
+ * The reasoning effort a turn asks for: the one a connection sets for its own turns, else the agent's. One that does not apply to the agent's
+ * model (it changed, or the model never had that level) falls back to the CLI's own default, with a line in the log, instead of failing the turn.
+ */
+function effortOf(agent, fromOrigin) {
+    const asked = fromOrigin || agent.effort;
+    if (!asked)
+        return undefined;
+    const use = resolveEffort(agent.provider, agent.model, asked);
+    if (!use)
+        console.warn(`[effort] ${agent.name}: "${asked}" does not apply to ${agent.model || 'the default model'} (${agent.provider}): the turn runs at the CLI's own default`);
+    return use || undefined;
+}
 /** Queue a prompt for an agent. Turns for one agent run strictly one at a time. */
 export function sendTurn(agentId, prompt, source = 'user', from, dispatchId, origin) {
     const s = st(agentId);
@@ -34,36 +48,46 @@ export function sendTurn(agentId, prompt, source = 'user', from, dispatchId, ori
 async function execute(agentId, prompt, source, from, dispatchId, origin) {
     const s = st(agentId);
     s.queued--;
-    const raw = agents.get(agentId);
-    if (!raw)
-        return { ok: false, text: '', error: 'Agent no longer exists' };
-    const agent = resolved(raw);
-    if (!agent.cwd)
-        return { ok: false, text: '', error: 'This agent has no working folder. Set one on the agent or on its colony.' };
-    const delegated = source === 'dispatch';
-    if (delegated) {
-        // Every delegation gets its own native session, so the agent's direct conversation never fills up with delegated work.
-        agent.session_id = null;
+    let raw;
+    let agent;
+    let delegated = false;
+    try {
+        raw = agents.get(agentId);
+        if (!raw)
+            return { ok: false, text: '', error: 'Agent no longer exists' };
+        agent = resolved(raw);
+        if (!agent.cwd)
+            return { ok: false, text: '', error: 'This agent has no working folder. Set one on the agent or on its colony.' };
+        delegated = source === 'dispatch';
+        if (delegated) {
+            // Every delegation gets its own native session, so the agent's direct conversation never fills up with delegated work.
+            agent.session_id = null;
+        }
+        else if (raw.session_id && raw.session_cwd && raw.session_cwd !== agent.cwd) {
+            // Native sessions are tied to the folder they started in; if the folder changed, start a fresh one.
+            agents.setSession(raw, null);
+            agent.session_id = null;
+            emit({ kind: 'agents_changed' });
+        }
     }
-    else if (raw.session_id && raw.session_cwd && raw.session_cwd !== agent.cwd) {
-        // Native sessions are tied to the folder they started in; if the folder changed, start a fresh one.
-        agents.setSession(raw, null);
-        agent.session_id = null;
-        emit({ kind: 'agents_changed' });
+    catch (e) {
+        // Preparing a turn can fail too (a damaged row, a database write): that is this turn's error, not a rejected promise nobody waits for.
+        return { ok: false, text: '', error: e instanceof Error ? e.message : String(e) };
     }
     const turnId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
     const controller = new AbortController();
-    s.controller = controller;
-    s.live = { turnId, prompt, events: [], source, origin };
-    agents.setStatus(agentId, 'running');
-    emit({ kind: 'turn_start', agentId, turnId, prompt, source, from, channel: origin && { platform: origin.platform, place: origin.place, user: origin.userName } });
-    emit({ kind: 'status', agentId, status: 'running', queued: s.queued });
     let text = '';
     let summary;
     let error;
+    let events = 0;
     let hash = '', nbVersion = 0;
     const push = (event) => { s.live?.events.push(event); emit({ kind: 'event', agentId, turnId, event }); };
     try {
+        s.controller = controller;
+        s.live = { turnId, prompt, events: [], source, origin };
+        agents.setStatus(agentId, 'running');
+        emit({ kind: 'turn_start', agentId, turnId, prompt, source, from, channel: origin && { platform: origin.platform, place: origin.place, user: origin.userName } });
+        emit({ kind: 'status', agentId, status: 'running', queued: s.queued });
         // Composing the instructions can fail too (a damaged skill row...): that is this turn's error, and it must not leave the agent "running" forever.
         const base = composeInstructions(agent, delegated);
         nbVersion = notebooks.get(agentId).version;
@@ -74,9 +98,11 @@ async function execute(agentId, prompt, source, from, dispatchId, origin) {
         const stream = runners[agent.provider]({
             agent, prompt, signal: controller.signal,
             instructions, refreshInstructions,
-            mcpCaps: mcpCaps(agent), effort: origin?.effort,
+            mcpCaps: mcpCaps(agent), effort: effortOf(agent, origin?.effort),
         });
         for await (const ev of stream) {
+            if (ev.t !== 'done')
+                events++;
             if (ev.t === 'session') {
                 if (delegated) {
                     agents.recordSession(agent, ev.sessionId, 'delegation', from, prompt);
@@ -107,6 +133,11 @@ async function execute(agentId, prompt, source, from, dispatchId, origin) {
             push({ t: 'error', message: error });
         }
     }
+    // A turn with no event of any kind (no session, text, tool or usage) never reached the model: it is not an empty answer.
+    if (!events && !error && !controller.signal.aborted) {
+        error = 'The agent produced no events, so the turn did not run';
+        push({ t: 'error', message: error });
+    }
     if (controller.signal.aborted && !error)
         push({ t: 'done', ok: false, summary: 'Stopped' });
     s.controller = null;

package/server/dist/services/agents.js

@@ -1,4 +1,6 @@
-import { agents, db, resolved } from '../db.js';
+import { agents, colonies, db, resolved } from '../db.js';
+import { notebooks } from '../skills/notebook.js';
+import { checkEffort } from '../efforts.js';
 import { channelPermissionError } from '../connections/rules.js';
 import { liveTurn, notifyAgentsChanged, stopAgent } from '../runtime.js';
 import { findRepo } from '../git/repo.js';
@@ -20,9 +22,14 @@ function create(p) {
     notifyAgentsChanged();
     return a;
 }
+/** An effort that does not apply to the provider and model is refused (an empty one always applies). */
+const checkAgentEffort = (provider, model, effort) => { const why = checkEffort(provider, model, effort); if (why)
+    throw bad(why); };
 export function createAgent(p) {
     const name = trimmed(p.name);
     uniqueName(name);
+    if (p.effort !== undefined && p.provider)
+        checkAgentEffort(p.provider, p.model ?? '', p.effort);
     return create({ ...p, name, cwd: p.cwd ?? '' });
 }
 /** A new agent that starts from a type: the type lends everything but name, description, folder and colony. */
@@ -31,13 +38,51 @@ export function spawnFromType(t, p) {
     uniqueName(name);
     return create({
         name, description: p.description ?? t.description, role: t.role, type_id: t.id, provider: t.provider, model: t.model,
+        effort: checkEffort(t.provider, t.model, t.effort) === null ? t.effort : '', // a type whose level the model no longer takes starts at the default
         system_prompt: t.system_prompt, permission: t.permission, cwd: p.cwd ?? '', skill_ids: t.skill_ids, skill_loads: t.skill_loads, colony_id: p.colony_id ?? null,
     });
 }
+/**
+ * A separate agent with the same configuration as `sourceId`: it runs in parallel with it (the turns of one agent are serialized, so conversations at the
+ * same time need separate agents) and READS THE SAME NOTEBOOK. It copies what the agent is (description, role, type, provider, model, prompt, permission,
+ * folder, overrides, browser, skills and, for an orchestrator, its team) and nothing it has done or is attached to: not its conversation or sessions,
+ * connections, wake-ups, schedules, watches, delegations or managed resources. Its colony is the source's unless another is given.
+ */
+export function cloneAgent(sourceId, p) {
+    const src = agentOrFail(sourceId);
+    const name = trimmed(typeof p.name === 'string' ? p.name : '');
+    if (!name)
+        throw bad('Give the clone a name');
+    uniqueName(name);
+    const colony = p.colony_id === undefined ? src.colony_id : p.colony_id ? String(p.colony_id) : null;
+    if (colony && !colonies.get(colony))
+        throw bad('That colony no longer exists');
+    const clone = create({
+        name, description: src.description, role: src.role, type_id: src.type_id, provider: src.provider, model: src.model, effort: src.effort, system_prompt: src.system_prompt,
+        permission: src.permission, cwd: src.cwd, overrides: src.overrides, browser: src.browser, skill_ids: src.skill_ids, skill_loads: src.skill_loads,
+        worker_ids: src.role === 'orchestrator' ? src.worker_ids : [], colony_id: colony, cloned_from: src.id,
+    });
+    try {
+        notebooks.share(src.id, clone.id);
+    }
+    catch (e) {
+        agents.remove(clone.id);
+        throw e;
+    } // never leave a clone that does not read the notebook of its source
+    notifyAgentsChanged();
+    return agents.get(clone.id);
+}
 export function updateAgent(id, p) {
     const cur = agentOrFail(id);
     if (p.name && p.name.toLowerCase() !== cur.name.toLowerCase())
         uniqueName(p.name, id);
+    // The effort has to apply to the provider and model the agent will have. One that is sent is checked; one that was saved and no longer applies
+    // (the provider or the model changed) falls back to the CLI's default instead of failing every turn.
+    const provider = p.provider ?? cur.provider, model = p.model ?? cur.model;
+    if (p.effort !== undefined)
+        checkAgentEffort(provider, model, p.effort);
+    else if (cur.effort && checkEffort(provider, model, cur.effort) !== null)
+        p = { ...p, effort: '' };
     // Changing provider invalidates the native session pointer. (A changed folder is detected when the next turn starts.)
     // All-or-nothing: a change that would leave a linked agent in Plan mode is rolled back.
     const a = db.transaction(() => {
@@ -68,6 +113,13 @@ export function sessionToRead(a, requested) {
     return sid;
 }
 /** Only the agent's own conversations can be made current; delegated ones are read-only. */
+/** True when an OpenCode conversation started under a different permission than the agent has now: OpenCode keeps the tools a session started with. */
+export function permissionStale(a) {
+    if (a.provider !== 'opencode' || !a.session_id)
+        return false;
+    const row = agents.sessions(a.id).find((s) => s.session_id === a.session_id);
+    return !!row && row.permission !== null && row.permission !== a.effective.permission;
+}
 export function resumeSession(a, sessionId) {
     if (!agents.sessions(a.id).some((s) => s.session_id === sessionId && s.kind !== 'delegation'))
         throw bad('Only the agent’s own conversations can be made current. Delegated sessions are read-only.');

package/server/dist/services/notebook.js

@@ -1,13 +1,17 @@
 import { agents, resolved } from '../db.js';
 import { mcpCaps } from '../instructions.js';
 import { liveOrigin } from '../runtime.js';
-import { NOTEBOOK_MAX } from '../skills/notebook.js';
+import { NOTEBOOK_MAX, notebooks } from '../skills/notebook.js';
 import { NOTEBOOK_SKILL_ID } from '../skills/defaults.js';
 import { bad } from '../http/errors.js';
-/** Who a note came from, so it can be audited: the date plus, for chat turns, where and who. */
+/**
+ * Who a note came from, so it can be audited: the date plus, for chat turns, where and who. In a notebook that several agents share it also
+ * says which agent wrote it: "who wrote this" is what tells a useful note from a mystery.
+ */
 export function noteSource(agentId) {
     const day = new Date().toISOString().slice(0, 10), o = liveOrigin(agentId);
-    return o ? `${day} · ${o.platform}: ${o.userName}` : day;
+    const who = notebooks.sharedWith(agentId).length ? agents.get(agentId)?.name : undefined;
+    return [day, who, o ? `${o.platform}: ${o.userName}` : ''].filter(Boolean).join(' · ');
 }
 /** The agent behind a notebook tool call: it must exist and have the Notebook skill. */
 export function notebookAgent(from) {