hive-am 1.4.0 → 1.5.0

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) {

package/server/dist/skills/defaults.js

@@ -5,6 +5,7 @@ export const CHANNELS_SKILL_ID = 'default-channels';
 export const WAKEUPS_SKILL_ID = 'default-wakeups';
 /** Running the servers and containers of the colony. Its tools (`object_list`, `object_action`, `object_logs`) exist only for agents that have this skill. */
 export const OBJECTS_SKILL_ID = 'default-objects';
+export const DATABASES_SKILL_ID = 'default-databases';
 /**
  * How to react to messages in a chat. It is part of the "Chat channels" skill; agents that already had that skill get it added once
  * (see `migrateChannelSkill`). Telegram's list is the one in `connections/telegram.ts` (`TELEGRAM_REACTIONS`): keep them in step.
@@ -150,7 +151,40 @@ The resources of your own colony, or the ones that belong to no colony if you ar
 ## Care
 - Stopping or restarting a server or a container interrupts whoever is using it. If the person did not ask for it and the resource is running fine, ask first.
 - Logs can contain secrets (tokens, passwords, connection strings). Never repeat them in a chat; replace them with \`***\`.
-- Do not run the resource's command yourself from a terminal as a way around \`object_action\`: use the tool, so hive-am knows what is running.`,
+- Do not run the resource's command yourself from a terminal as a way around \`object_action\`: use the tool, so hive-am knows what is running.
+
+## Databases
+A **database** resource is not started or stopped: it is used. \`object_list\` shows its state, but to look inside it or run SQL you need the "Database management" skill.`,
+    },
+    {
+        slug: 'databases',
+        load: 'always',
+        name: 'Database management',
+        description: 'Look inside the database resources of the colony and use them: structure, queries, writes, saved queries, history, and (with Full access) their connection.',
+        content: `The colony you belong to can have **database resources** (MySQL or MariaDB, PostgreSQL, SQL Server, SQLite). You can look at their structure, run SQL, keep saved queries and, with Full access, change how they connect. hive-am opens a connection when you ask something and closes it right after.
+
+## Which databases are yours
+The ones of your own colony, or the ones that belong to no colony if you are in none, unless a person chose one agent to look after a database (then only that agent). Another colony's databases are not visible to you. Use the exact name that \`object_db_list\` shows. \`object_db_list\` answers even when you do not have the Colony resources skill.
+
+## How to work
+1. **Look before you run.** \`object_db_list\`, then \`object_db_schema\` (databases, tables and views), \`object_db_columns\` and \`object_db_describe\` (keys, indexes, foreign keys, row count), \`object_db_search\` (find a table or column by name), \`object_db_ddl\` (the CREATE statement) and \`object_db_sample\` (the first rows without writing SQL). \`object_db_explain\` shows the plan of a statement without running it.
+2. **Run SQL** with \`object_db_query\` (one statement: a read, a write or a DDL) or \`object_db_exec\` (several statements in ONE transaction: all are applied or none; MySQL commits by itself on a CREATE, ALTER or DROP, so those cannot be undone there). Another database of the same server: pass \`database\`.
+3. **Keep what is useful**: \`object_db_saved\` (list, add, update, remove named queries) and \`object_db_history\` (the last 200 queries, including the ones people ran). \`object_db_export\` writes a result as CSV or JSON to a file inside your own working folder (it never overwrites unless you say so).
+4. **A result is cut at the resource's row limit and a query at its time limit**: ask for fewer rows or columns instead of working around it. Never \`SELECT *\` from a big table without a \`LIMIT\` or a \`WHERE\`: it fills your context.
+
+## What you may do
+Your permission decides it (the \`readOnly\` setting of the resource is for people using its panel and does not apply to you):
+- **Read-only (plan)**: everything that looks and reads. The connection is read-only and only SELECT, WITH, SHOW, DESCRIBE and EXPLAIN pass.
+- **Edit files (acceptEdits)**: also INSERT, UPDATE, DELETE, CREATE and ALTER, scripts, saved queries, clearing the history, exports and \`object_db_sessions\`. **DROP and TRUNCATE are refused**, also inside a script (nothing of it runs).
+- **Full access (bypassPermissions)**: also DROP and TRUNCATE, \`object_db_config_set\` (host, port, user, password, database, SSL, driver properties, limits, name, colony, manager), \`object_db_create\`, \`object_db_delete\` and \`object_db_kill\`.
+
+## Care
+- **Writes and DDL are real and irreversible.** Think first: say what you are going to change and on which database, prefer a transaction (\`object_db_exec\`), try a \`SELECT\` with the same \`WHERE\` before an UPDATE or DELETE, and suggest a backup before anything that cannot be undone. A DELETE or UPDATE without a WHERE is the commonest mistake.
+- hive-am refuses DROP and TRUNCATE without Full access, but that is a guardrail, not a sandbox: it does not see a DELETE without a WHERE, a CALL, a PostgreSQL DO block or a stored procedure. The real boundary is what the database user is allowed to do: recommend a user with limited grants.
+- **Results can contain secrets** (password hashes, tokens, personal data). Never repeat them in a chat; replace them with \`***\`.
+- **Passwords are write-only.** You can set or replace one with \`object_db_create\` or \`object_db_config_set\`, but no tool will ever show you a stored one (\`object_db_config\` only says whether one is set). Never repeat a password, write it in a file, a note or a chat, or put it in a query that is not needed. If a person types one in a chat, use it once in the tool without echoing it, and prefer asking them to type it in the resource's panel. When you write SQL that sets a password (\`CREATE USER … IDENTIFIED BY\`), hive-am replaces the literal with \`***\` in the history and the logs.
+- Changing a connection (\`object_db_config_set\`) points hive-am at that server with those credentials. Do it only when asked.
+- \`object_db_kill\` cancels what another session is running: look at \`object_db_sessions\` first and do it only when asked.`,
     },
     {
         slug: 'git-workflow',

package/server/dist/skills/notebook.js

@@ -1,11 +1,13 @@
+import { randomUUID } from 'node:crypto';
 import { db } from '../db.js';
 import { DomainError } from '../errors.js';
 /**
- * An agent's notebook: Markdown it keeps for itself across conversations (see the «Notebook» default skill).
- * Lives in its own table so it never travels with the agent list. Every change bumps `version`; `seen` is the version the
- * agent's live conversation already contains, so the runtime knows when it must be re-sent (e.g. after the user edits it).
+ * A notebook: Markdown an agent keeps for itself across conversations (see the «Notebook» default skill). It is an object of its own with
+ * readers (`notebooks` and `notebook_readers`, created by db/migrations.ts): an agent and the clones made from it read and write the same one, and
+ * it goes away only with its last reader. It lives in its own table so it never travels with the agent list. Every change bumps `version`;
+ * `seen` belongs to the reader: it is the version that agent's live conversation already contains, so the runtime knows when the text must be
+ * re-sent to it (e.g. after the user, or another agent that shares the notebook, changed it).
  */
-// The table (agent_notebooks) is created by db/migrations.ts.
 /** It is prompt overhead on every turn, so it has a hard cap. */
 export const NOTEBOOK_MAX = 8000;
 const NOTE_MAX = 500;
@@ -37,19 +39,61 @@ const refuseSecret = (text) => {
         throw new NotebookError(`That looks like ${what}. Credentials are never stored in the notebook: leave it out (or describe where it lives, not its value).`);
 };
 const empty = () => ({ content: '', version: 0, seen: 0, updated_at: 0, updated_by: '' });
+/** The notebook an agent reads, with that agent's own `seen`. */
+const readerRow = (agentId) => db.prepare(`SELECT n.id, n.content, n.version, r.seen, n.updated_at, n.updated_by FROM notebook_readers r JOIN notebooks n ON n.id = r.notebook_id WHERE r.agent_id = ?`).get(agentId);
+/** The notebook the agent reads, created empty (version 0) when it has none yet. */
+function ensure(agentId) {
+    let row = readerRow(agentId);
+    if (!row) {
+        const id = randomUUID();
+        db.prepare('INSERT INTO notebooks (id) VALUES (?)').run(id);
+        db.prepare('INSERT INTO notebook_readers (agent_id, notebook_id, seen) VALUES (?,?,0)').run(agentId, id);
+        row = readerRow(agentId);
+    }
+    return row;
+}
 export const notebooks = {
-    get: (agentId) => db.prepare('SELECT content,version,seen,updated_at,updated_by FROM agent_notebooks WHERE agent_id=?').get(agentId) ?? empty(),
+    get: (agentId) => { const r = readerRow(agentId); return r ? { content: r.content, version: r.version, seen: r.seen, updated_at: r.updated_at, updated_by: r.updated_by } : empty(); },
+    /** The other agents that read the same notebook (empty for an ordinary notebook). */
+    sharedWith(agentId) {
+        const r = readerRow(agentId);
+        if (!r)
+            return [];
+        return db.prepare('SELECT a.id, a.name FROM notebook_readers x JOIN agents a ON a.id = x.agent_id WHERE x.notebook_id = ? AND x.agent_id <> ? ORDER BY a.name').all(r.id, agentId);
+    },
     /** The agent (or the user) replaced the text. `live`: the change happened inside the conversation the agent is running now. */
-    save(agentId, content, by, live) {
-        const cur = notebooks.get(agentId), version = cur.version + 1, t = Date.now();
-        const seen = live ? version : cur.seen;
-        db.prepare(`INSERT INTO agent_notebooks (agent_id,content,version,seen,updated_at,updated_by) VALUES (?,?,?,?,?,?)
-      ON CONFLICT(agent_id) DO UPDATE SET content=excluded.content, version=excluded.version, seen=excluded.seen, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
-            .run(agentId, content, version, seen, t, by);
+    save: db.transaction((agentId, content, by, live) => {
+        const row = ensure(agentId); // an agent that never had one gets its own
+        const version = row.version + 1;
+        db.prepare('UPDATE notebooks SET content=?, version=?, updated_at=?, updated_by=? WHERE id=?').run(content, version, Date.now(), by, row.id);
+        // Only the writer's own conversation already contains what it just wrote; the other readers are sent it on their next turn.
+        if (live)
+            db.prepare('UPDATE notebook_readers SET seen=? WHERE agent_id=?').run(version, agentId);
         return notebooks.get(agentId);
-    },
+    }),
     /** The runtime sent version `v` to the agent's conversation. */
-    markSeen: (agentId, v) => { db.prepare('UPDATE agent_notebooks SET seen=MAX(seen, ?) WHERE agent_id=?').run(v, agentId); },
+    markSeen: (agentId, v) => { db.prepare('UPDATE notebook_readers SET seen=MAX(seen, ?) WHERE agent_id=?').run(v, agentId); },
+    /**
+     * `to` starts reading the notebook of `from` (a clone sharing its source's notes): `from` gets one if it had none, and what `to` read before
+     * is dropped with its last reader. Its `seen` starts at 0, so its first turn is sent the text.
+     */
+    share: db.transaction((fromId, toId) => {
+        if (fromId === toId)
+            return;
+        const nb = ensure(fromId);
+        db.prepare('INSERT INTO notebook_readers (agent_id, notebook_id, seen) VALUES (?,?,0) ON CONFLICT(agent_id) DO UPDATE SET notebook_id=excluded.notebook_id, seen=0').run(toId, nb.id);
+        db.prepare('DELETE FROM notebooks WHERE id NOT IN (SELECT notebook_id FROM notebook_readers)').run(); // what `to` read before, if nobody else does
+    }),
+    /** Gives the agent its own copy of the notebook it shares, and leaves the shared one with the others. Does nothing for an agent that shares nothing. */
+    separate: db.transaction((agentId) => {
+        const row = readerRow(agentId);
+        if (!row || !notebooks.sharedWith(agentId).length)
+            return notebooks.get(agentId);
+        const id = randomUUID();
+        db.prepare('INSERT INTO notebooks (id, content, version, updated_at, updated_by) VALUES (?,?,?,?,?)').run(id, row.content, row.version, row.updated_at, row.updated_by);
+        db.prepare('UPDATE notebook_readers SET notebook_id=? WHERE agent_id=?').run(id, agentId); // `seen` stays: it still describes what this agent's conversation holds
+        return notebooks.get(agentId);
+    }),
     /** Edit from the UI. `version` (when given) must be the one the user was looking at. */
     edit(agentId, content, version) {
         const text = content.replace(/\r\n/g, '\n').trimEnd();