@jskit-ai/agent-runtime 0.0.0-stage → 0.1.0

package/src/server/planning.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { createTool } from "@jskit-ai/agent/server";
+
+// Keeping a long job in mind: a to-do list the person sees, as one card in the chat updated in
+// place, and private notes. Both are shown to the model at every turn (planningNotes), so they
+// outlast summaries, goal rounds and restarts.
+//
+// The list is a message of kind "todos" ({ list: conversation id, items: [{ text, status }],
+// updatedAt }) in the messages table; the notes are the conversation's `job_notes` (jsonb array).
+// `post(messages)` adds messages to the chat and tells open pages; `post([])` only tells them.
+export const PLANNING_TABLES = { messages: "agent_messages", conversations: "agent_conversations" };
+
+/** The conversation's newest to-do card, if any. */
+export function currentTodos(knex, conversationId, tables = PLANNING_TABLES) {
+  return knex(tables.messages).where({ kind: "todos" }).whereRaw("body->>'list' = ?", [String(conversationId)]).orderBy("id", "desc").first();
+}
+
+/**
+ * The to-do and notes tools, for one turn in one conversation; the to-do list only with `post`.
+ * @param {object} options
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} options.knex
+ * @param {number | string} options.conversationId
+ * @param {((messages: object[]) => Promise<unknown>) | null} [options.post]
+ * @param {typeof PLANNING_TABLES} [options.tables]
+ */
+export function planningTools({ knex, conversationId, post, tables = PLANNING_TABLES }) {
+  async function keepNotes({ notes }) {
+    await knex(tables.conversations).where({ id: conversationId }).update({ job_notes: JSON.stringify(notes) });
+    return { status: notes.length ? "saved" : "cleared" };
+  }
+
+  async function updateTodos({ items }) {
+    const doing = items.filter((item) => item.status === "doing");
+    if (doing.length > 1) return { error: `Only one item can be doing at a time; these are all doing: ${doing.map((item) => item.text).join("; ")}.` };
+    const card = await currentTodos(knex, conversationId, tables);
+    const body = { list: String(conversationId), items, updatedAt: new Date().toISOString() };
+    // A finished list stays as it was; the next job's list is a new card.
+    if (card && card.body.items.some((item) => item.status !== "done")) {
+      await knex(tables.messages).where({ id: card.id }).update({ body: knex.raw("body || ?::jsonb", [JSON.stringify(body)]) });
+      await post([]);
+    } else {
+      await post([{ kind: "todos", role: "bot", body }]);
+    }
+    const finished = items.every((item) => item.status === "done");
+    return { status: "saved", ...(finished ? { note: "Everything on the list is done: check the result, then reply with it." } : {}) };
+  }
+
+  return {
+    keepNotes: createTool(Object.freeze({
+      id: "keep_notes",
+      description: "Keep notes for the job in hand: facts you found and will need later in a long job (file names, record ids, what was decided, what's left to check). They're shown to you at every turn, even after the conversation is summarised. Send the whole list every time; send an empty list when the job is over. The person doesn't see them.",
+      inputSchema: z.object({ notes: z.array(z.string().min(1).max(300)).max(30) }),
+      execute: (input) => keepNotes(input)
+    })),
+    ...(post ? {
+      updateTodos: createTool(Object.freeze({
+        id: "update_todos",
+        description: "Write your to-do list for a job of more than three steps; the person sees it live as a card in the chat. Send the whole list every time: each item a short step, its status todo, doing or done, with exactly one item doing while you work. Tick an item off as soon as it's done. Skip it for quick answers.",
+        inputSchema: z.object({
+          items: z.array(z.object({
+            text: z.string().min(1).max(200),
+            status: z.enum(["todo", "doing", "done"])
+          })).min(1).max(20)
+        }),
+        execute: (input) => updateTodos(input)
+      }))
+    } : {})
+  };
+}
+
+/** The open to-do list and the notes, for the model's state note at every turn. */
+export async function planningNotes(knex, conversationId, tables = PLANNING_TABLES) {
+  const card = await currentTodos(knex, conversationId, tables);
+  const notes = (await knex(tables.conversations).where({ id: conversationId }).first("job_notes"))?.job_notes || [];
+  const mark = { todo: "[ ]", doing: "[doing]", done: "[x]" };
+  return [
+    card && card.body.items.some((item) => item.status !== "done")
+      ? `Your to-do list for this job (keep it up to date with update_todos):\n${card.body.items.map((item) => `${mark[item.status]} ${item.text}`).join("\n")}`
+      : "",
+    notes.length ? `Your notes for the job in hand (keep them up to date with keep_notes):\n${notes.map((note) => `- ${note}`).join("\n")}` : ""
+  ].filter(Boolean);
+}

package/src/server/runs.js

@@ -0,0 +1,105 @@
+// Replies in progress, one per conversation at a time, kept in the database so any server can see
+// them (one claimed per conversation, with a heartbeat). Each finished step is saved as it happens,
+// so a reply whose server stops (deploy, crash) is carried on from its last step by any server, as
+// Claude Code resumes from its transcript.
+//
+// The table has: conversation_id (unique), started_at, heartbeat_at, steps (jsonb), input (jsonb),
+// plus whatever `owner` columns the app adds (for example bot_id).
+// A run is stale once its heartbeat (every heartbeatMs) is older than staleSeconds.
+export const RUN_LIMITS = { staleSeconds: 60, heartbeatMs: 15000 };
+
+/**
+ * The replies in progress, in `table`.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} dependencies.knex
+ * @param {string} [dependencies.table]
+ * @param {typeof RUN_LIMITS} [dependencies.limits]
+ */
+export function createRuns({
+  knex,
+  table = "agent_runs",
+  limits = RUN_LIMITS
+}) {
+  const stale = (query) => query.where("heartbeat_at", "<", knex.raw(`now() - interval '${Number(limits.staleSeconds)} seconds'`));
+
+  /** Claims the conversation for one reply: a new run, or one whose server stopped beating. */
+  async function claim(conversationId, owner = {}) {
+    const [fresh] = await knex(table).insert({ conversation_id: conversationId, ...owner }).onConflict("conversation_id").ignore().returning("conversation_id");
+    if (fresh) return true;
+    const [taken] = await stale(knex(table).where({ conversation_id: conversationId }))
+      .update({ started_at: knex.fn.now(), heartbeat_at: knex.fn.now() }).returning("conversation_id");
+    return Boolean(taken);
+  }
+
+  function heartbeat(conversationId) {
+    return knex(table).where({ conversation_id: conversationId }).update({ heartbeat_at: knex.fn.now() });
+  }
+
+  function release(conversationId) {
+    return knex(table).where({ conversation_id: conversationId }).del();
+  }
+
+  /** What a reply saved so far: its steps and what started it. */
+  function saved(conversationId) {
+    return knex(table).where({ conversation_id: conversationId }).first("steps", "input");
+  }
+
+  function save(conversationId, steps, input) {
+    return knex(table).where({ conversation_id: conversationId }).update({ steps: JSON.stringify(steps), input: JSON.stringify(input), heartbeat_at: knex.fn.now() });
+  }
+
+  /**
+   * Replies left part-way by a stopped server, each taken over by this one (still stale when
+   * claimed, so two servers can't both take it). `resumable(query)` narrows which kinds count.
+   */
+  async function takeOverStalled({ resumable = (query) => query, count = 10 } = {}) {
+    const rows = await resumable(stale(knex(table).whereNotNull("steps"))).limit(count);
+    const taken = [];
+    for (const row of rows) {
+      const [mine] = await stale(knex(table).where({ conversation_id: row.conversation_id }))
+        .update({ started_at: knex.fn.now(), heartbeat_at: knex.fn.now() }).returning("*");
+      if (mine) taken.push(mine);
+    }
+    return taken;
+  }
+
+  return Object.freeze({
+    limits,
+    claim,
+    heartbeat,
+    release,
+    saved,
+    save,
+    takeOverStalled
+  });
+}
+
+/**
+ * Carries on, every `everyMs`, the replies stopped servers left; `resume(run)` restarts one.
+ * @param {object} dependencies
+ * @param {import("./types.js").AgentRuns} dependencies.runs
+ * @param {(run: object) => Promise<unknown>} dependencies.resume
+ * @param {(query: object) => object} [dependencies.resumable]
+ * @param {number} [dependencies.everyMs]
+ */
+export function startResumer({ runs, resume, resumable, everyMs = 30000 }) {
+  let stopped = false;
+  let running = null;
+  const tick = () => {
+    if (stopped || running) return;
+    running = runs.takeOverStalled({ resumable })
+      .then((taken) => Promise.all(taken.map((run) => resume(run))))
+      .catch((error) => console.error(`Resuming replies: ${error?.message || error}`))
+      .finally(() => { running = null; });
+  };
+  const timer = setInterval(tick, everyMs);
+  timer.unref();
+  tick();
+  return {
+    async drain(ms) {
+      stopped = true;
+      clearInterval(timer);
+      await Promise.race([running || Promise.resolve(), new Promise((resolve) => setTimeout(resolve, ms))]);
+    }
+  };
+}

package/src/server/summaryStore.js

@@ -0,0 +1,195 @@
+import { SUMMARY_LIMITS, assertCallbacks, cutPoint, estimateTokens, transcriptText, writeSummary } from "@jskit-ai/agent/server";
+import { NO_NOTICES } from "./notices.js";
+
+/**
+ * Summaries between turns, in the background. A reply reads the conversation's newest summary and
+ * every message after it word for word. When that part grows past `compactAt`, the conversation is
+ * queued; one server claims it and summarises everything but the latest turns, folding in the
+ * previous summary. A summary replaces exactly the messages it covers, so anything said meanwhile
+ * stays as it was, and no reply waits for it. Summaries are written recall first: what was asked
+ * and decided, facts, what was done and promised, what's open. Sized for a 1-million-token window,
+ * close to DeepSeek Harness's 727k/127k: a chat is read word for word until it's far into the
+ * window, leaving room for one long turn's own steps on top.
+ *
+ * Tables: summaries (id, conversation_id, covers_up_to, summary, messages, created_at) and a queue
+ * (conversation_id unique, requested_at, run_after, lease_until, attempts, last_error).
+ *
+ * Hooks: `history(conversationId, { after })` gives { messages, inherited, toModel, named }: the
+ * stored messages after `after` (message ids), what a conversation inherits from one it continues
+ * (only needed before its first summary), the app's way of turning messages into model messages, and
+ * whether people's lines carry their names (groups and rooms). `track(conversationId, work)` meters
+ * the summary to whoever the conversation belongs to. `summarize({ previous, text })` may replace
+ * the model call. `track` and `summarize` are functions, or left out for their defaults. Without
+ * `notices`, each server finds queued conversations on its own timer.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} dependencies.knex
+ * @param {import("ai").LanguageModel} [dependencies.model]
+ * @param {string} [dependencies.app]
+ * @param {(conversationId: number | string, query: { after: number }) => Promise<{ messages: object[], inherited: object[], toModel: (messages: object[]) => Promise<object[]>, named?: boolean }>} dependencies.history
+ * @param {(conversationId: number | string, work: () => Promise<string>) => Promise<string>} [dependencies.track]
+ * @param {import("./types.js").AgentNotices | null} [dependencies.notices]
+ * @param {{ summaries: string, queue: string }} [dependencies.tables]
+ * @param {string} [dependencies.channel]
+ * @param {(input: { previous: string, text: string }) => Promise<string>} [dependencies.summarize]
+ * @param {typeof SUMMARY_LIMITS} [dependencies.limits]
+ */
+export function createSummaries({
+  knex,
+  model,
+  app = "the app",
+  history,
+  track = runSummaryUnmetered,
+  notices,
+  tables = { summaries: "agent_summaries", queue: "agent_summary_queue" },
+  channel = "agent-summaries",
+  summarize = (input) => writeSummary({ model, app, ...input, limits }),
+  limits = SUMMARY_LIMITS
+}) {
+  assertCallbacks("createSummaries", { track, summarize });
+  const channelNotices = notices ?? NO_NOTICES;
+
+  async function latest(conversationId) {
+    return knex(tables.summaries).where({ conversation_id: conversationId }).orderBy("id", "desc").first();
+  }
+
+  /** What a reply reads: the newest summary's text, and the id after which messages are read whole. */
+  async function current(conversationId) {
+    const row = await latest(conversationId);
+    return row ? { summary: row.summary, after: Number(row.covers_up_to) } : { summary: "", after: 0 };
+  }
+
+  /** After a reply: queue a summary when the part since the last one has grown too big. */
+  async function consider(conversationId) {
+    const { after } = await current(conversationId);
+    const { messages, inherited, toModel } = await history(conversationId, { after });
+    const size = estimateTokens(await toModel([...(after ? [] : inherited), ...messages]));
+    if (size <= limits.compactAt) return false;
+    await knex(tables.queue).insert({ conversation_id: conversationId }).onConflict("conversation_id").ignore();
+    await channelNotices.publish(channel, "all", {}).catch(() => {});
+    return true;
+  }
+
+  /** One summary: everything after the previous one up to the kept turns, folded into it. */
+  async function compact(conversationId) {
+    const previous = await latest(conversationId);
+    const after = previous ? Number(previous.covers_up_to) : 0;
+    const { messages, inherited, toModel, named = false } = await history(conversationId, { after });
+    const sizes = await Promise.all(messages.map(async (message) => estimateTokens(await toModel([message]))));
+    let cut = cutPoint(messages, sizes, limits);
+    if (!cut) return { skipped: "nothing to summarise yet" };
+    // A huge backlog is folded in a piece at a time, oldest first; the next run takes the rest.
+    let reading = estimateTokens(await toModel(previous ? [] : inherited));
+    for (let index = 0; index < cut; index += 1) {
+      reading += sizes[index];
+      if (reading > limits.readTokens && index > 0) {
+        cut = index;
+        break;
+      }
+    }
+    const folded = messages.slice(0, cut);
+    const modelMessages = await toModel([...(previous ? [] : inherited), ...folded]);
+    if (!previous && estimateTokens(modelMessages) < limits.minTokens) return { skipped: "too little to summarise" };
+    const summary = await track(conversationId, () => summarize({ previous: previous?.summary || "", text: transcriptText(modelMessages, { named }) }));
+    if (!summary) throw new Error("The summary came back empty.");
+    const coversUpTo = Number(folded.at(-1).id);
+    await knex.transaction(async (trx) => {
+      // Another server's newer summary wins; this one is dropped.
+      const newest = await trx(tables.summaries).where({ conversation_id: conversationId }).orderBy("id", "desc").forUpdate().first();
+      if (newest && Number(newest.covers_up_to) >= coversUpTo) return;
+      await trx(tables.summaries).insert({ conversation_id: conversationId, covers_up_to: coversUpTo, summary, messages: folded.length });
+      const old = await trx(tables.summaries).where({ conversation_id: conversationId }).orderBy("id", "desc").offset(limits.keepSummaries).pluck("id");
+      if (old.length) await trx(tables.summaries).whereIn("id", old).del();
+    });
+    return { coversUpTo, messages: folded.length };
+  }
+
+  /**
+   * Before a reply: if summarising fell behind and the part a reply reads is past
+   * `summariseNowAt`, summarise now, a few pieces at most, rather than let the oldest messages drop
+   * off unseen. A failure leaves the reply its last-resort cut (withinBudget, @jskit-ai/agent).
+   */
+  async function ensureWithin(conversationId) {
+    for (let piece = 0; piece < 4; piece += 1) {
+      const { after } = await current(conversationId);
+      const { messages, inherited, toModel } = await history(conversationId, { after });
+      if (estimateTokens(await toModel([...(after ? [] : inherited), ...messages])) <= limits.summariseNowAt) return;
+      const done = await compact(conversationId).catch((error) => {
+        console.error(`Summarising conversation ${conversationId} before a reply: ${error?.message || error}`);
+        return {};
+      });
+      if (!done.coversUpTo) return;
+    }
+  }
+
+  /** Claimed once across servers with a lease; a failure waits longer before the next try. */
+  async function claim() {
+    return knex.transaction(async (trx) => {
+      const due = await trx(tables.queue).where("run_after", "<=", trx.fn.now())
+        .where((query) => query.whereNull("lease_until").orWhere("lease_until", "<", trx.fn.now()))
+        .orderBy("requested_at").forUpdate().skipLocked().first();
+      if (!due) return null;
+      await trx(tables.queue).where({ conversation_id: due.conversation_id }).update({ lease_until: trx.raw(`now() + interval '${Number(limits.leaseMinutes)} minutes'`) });
+      return due;
+    });
+  }
+
+  async function runOne() {
+    const job = await claim();
+    if (!job) return false;
+    try {
+      await compact(job.conversation_id);
+      await knex(tables.queue).where({ conversation_id: job.conversation_id }).del();
+      // Still too long (a backlog folded in pieces)? Queue the next piece.
+      await consider(job.conversation_id);
+    } catch (error) {
+      const wait = Math.min(60, 2 ** job.attempts);
+      await knex(tables.queue).where({ conversation_id: job.conversation_id })
+        .update({ attempts: job.attempts + 1, lease_until: null, last_error: String(error?.message || error).slice(0, 500), run_after: knex.raw(`now() + interval '${wait} minutes'`) }).catch(() => {});
+    }
+    return true;
+  }
+
+  /** Every serving server runs this loop; a notice wakes it as soon as something is queued. */
+  function start({ everyMs = 15000 } = {}) {
+    let stopped = false;
+    let running = null;
+    const tick = () => {
+      if (running || stopped) return;
+      running = (async () => {
+        try {
+          for (let count = 0; !stopped && count < 20 && (await runOne()); count += 1);
+        } catch {
+          // The database is unreachable; the next tick tries again.
+        }
+      })().finally(() => {
+        running = null;
+      });
+    };
+    const timer = setInterval(tick, everyMs);
+    timer.unref();
+    const unsubscribe = channelNotices.subscribe(channel, "all", () => tick());
+    tick();
+    return {
+      async drain(ms) {
+        stopped = true;
+        clearInterval(timer);
+        unsubscribe();
+        await Promise.race([running, new Promise((resolve) => setTimeout(resolve, ms))]);
+      }
+    };
+  }
+
+  return Object.freeze({
+    current,
+    consider,
+    compact,
+    ensureWithin,
+    runOne,
+    start
+  });
+}
+
+/** Runs a summary's work without metering it. */
+function runSummaryUnmetered(_conversationId, work) {
+  return work();
+}

package/src/server/tools/ask.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { createTool } from "@jskit-ai/agent/server";
+
+// What the model sees of the ask_user tool, whichever way the chat shows the question.
+const ASK_USER = Object.freeze({
+  id: "ask_user",
+  description: "Ask the person a question you need answered before you can go on, with a few answers to pick from when there are obvious ones; then end your reply and wait. Only for what you can't reasonably decide or find out yourself.",
+  inputSchema: z.object({
+    question: z.string().min(3).max(1000),
+    options: z.array(z.string().min(1).max(100)).max(6).optional()
+  })
+});
+
+/**
+ * Asking the person something only they can decide, in a chat that shows questions as cards: the
+ * question is a card with the answers to pick from, and the answer is the person's next message.
+ * @param {object} options
+ * @param {(messages: object[]) => Promise<unknown>} options.post Shows messages in the chat.
+ */
+export function askTools({ post }) {
+  async function askUser({ question, options = [] }) {
+    await post([{ kind: "question", role: "bot", body: { question, options } }]);
+    return { status: "asked", note: "The person sees the question. End your reply now in one short line, and carry on when they answer." };
+  }
+
+  return {
+    askUser: createTool(Object.freeze({
+      ...ASK_USER,
+      execute: (input) => askUser(input)
+    }))
+  };
+}
+
+/**
+ * Asking the person something only they can decide, in a chat that shows no question cards: the
+ * question goes in the reply, and the answer is the person's next message.
+ */
+export function askInReplyTools() {
+  function askUser() {
+    return { status: "ask in your reply", note: "Put the question in your reply, end it there, and carry on when they answer." };
+  }
+
+  return {
+    askUser: createTool(Object.freeze({
+      ...ASK_USER,
+      execute: () => askUser()
+    }))
+  };
+}

package/src/server/tools/commands.js

@@ -0,0 +1,175 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { createTool, textPart } from "@jskit-ai/agent/server";
+
+// Commands in the workspace, through an executor (executors.js). One still running after
+// `foregroundSeconds` carries on in the background on this server, with a heartbeat, and the model
+// follows it with check_command; `onEnd(command)` hears when it ends. Every command is a row in the
+// commands table, so check_command works from any server. Its result shows the start and the end
+// of the output; all of it (up to `outputFull`) is a file, outputDir/<conversation>/<run>.log, that
+// read_command_output reads in parts and the next commands can read too (as Claude Code keeps
+// large outputs). Point outputDir at storage every server shares when there are several.
+//
+// The table has: id, conversation_id, why, script, status (running, done, failed, timed_out,
+// stopped), exit_code, output, truncated, server, heartbeat_at, started_at, ended_at.
+export const COMMAND_LIMITS = { foregroundSeconds: 120, maxSeconds: 1800, outputHead: 8000, outputTail: 8000, outputFull: 16 * 1024 * 1024, heartbeatSeconds: 20, staleSeconds: 90 };
+
+/**
+ * The commands of every conversation, in `table`, run through `executor`.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} dependencies.knex
+ * @param {import("../types.js").AgentExecutor} dependencies.executor
+ * @param {string} [dependencies.table]
+ * @param {string} [dependencies.outputDir]
+ * @param {(command: object) => unknown} [dependencies.onEnd]
+ * @param {typeof COMMAND_LIMITS} [dependencies.limits]
+ * @param {string} [dependencies.server]
+ */
+export function createCommands({
+  knex,
+  executor,
+  table = "agent_commands",
+  outputDir = path.join(os.tmpdir(), "agent-runs"),
+  onEnd = ignoreEnd,
+  limits = COMMAND_LIMITS,
+  server = `${os.hostname()}:${process.pid}`
+}) {
+  const live = new Map();
+  const logOf = (conversationId, id) => path.join(outputDir, String(conversationId), `${id}.log`);
+
+  function view(row) {
+    return {
+      run: String(row.id),
+      status: row.status,
+      ...(row.exit_code === null || row.exit_code === undefined ? {} : { exitCode: row.exit_code }),
+      output: row.output || "",
+      ...(row.truncated ? { truncated: true, wholeOutput: `The output was cut. All of it is in ${logOf(row.conversation_id, row.id)} (grep, tail and sed work on it), or read it in parts with read_command_output, run ${row.id}.` } : {})
+    };
+  }
+
+  async function run({ conversationId, cwd, why, script, seconds = limits.maxSeconds }) {
+    if (!executor.available()) return { error: "Commands can't run on this server (its sandbox isn't installed)." };
+    const [row] = await knex(table).insert({ conversation_id: conversationId, why, script, status: "running", server, heartbeat_at: knex.fn.now() }).returning("*");
+    const log = logOf(conversationId, row.id);
+    await mkdir(path.dirname(log), { recursive: true });
+    const whole = createWriteStream(log);
+    // The output as it comes: all of it to the file, and its start and end for the result.
+    const shown = limits.outputHead + limits.outputTail;
+    let kept = "";
+    let tail = "";
+    let size = 0;
+    const take = (chunk) => {
+      const text = chunk.toString("utf8");
+      if (size < limits.outputFull) whole.write(chunk);
+      size += text.length;
+      if (kept.length < shown) kept += text;
+      tail = (tail + text).slice(-limits.outputTail);
+    };
+    const child = await executor.spawn({ script, cwd, mounts: [{ source: path.dirname(log) }] });
+    child.stdout.on("data", take);
+    child.stderr.on("data", take);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+    }, Math.min(seconds, limits.maxSeconds) * 1000);
+    const beat = setInterval(() => knex(table).where({ id: row.id }).update({ heartbeat_at: knex.fn.now() }).catch(() => {}), limits.heartbeatSeconds * 1000);
+    live.set(row.id, child);
+    const ended = new Promise((resolve) => child.on("close", (code) => resolve(code)))
+      .then(async (code) => {
+        clearTimeout(timer);
+        clearInterval(beat);
+        live.delete(row.id);
+        await new Promise((resolve) => whole.end(resolve));
+        const truncated = size > shown;
+        const output = truncated ? `${kept.slice(0, limits.outputHead)}\n… (${size - shown} characters cut) …\n${tail}` : kept;
+        const status = timedOut ? "timed_out" : code === 0 ? "done" : "failed";
+        const [done] = await knex(table).where({ id: row.id }).update({ status, exit_code: code, output, truncated, ended_at: knex.fn.now() }).returning("*");
+        await Promise.resolve(onEnd(done)).catch(() => {});
+        return done;
+      });
+    const finished = await Promise.race([ended, new Promise((resolve) => setTimeout(resolve, limits.foregroundSeconds * 1000, null))]);
+    if (finished) return view(finished);
+    return { run: String(row.id), status: "running", output: kept.slice(0, limits.outputHead), note: "It's still going and carries on in the background; follow it with check_command." };
+  }
+
+  /** A running command whose server stopped beating has stopped with it. */
+  async function check(conversationId, id) {
+    if (!/^\d+$/u.test(String(id))) return { error: "Give the run number from run_command." };
+    const row = await knex(table).where({ id, conversation_id: conversationId }).first();
+    if (!row) return { error: "There's no such command in this conversation." };
+    if (row.status === "running" && !live.has(row.id) && Date.now() - new Date(row.heartbeat_at).getTime() > limits.staleSeconds * 1000) {
+      const [stopped] = await knex(table).where({ id: row.id, status: "running" }).update({ status: "stopped", output: `${row.output || ""}\n(The server running it stopped, so the command stopped too.)`, ended_at: knex.fn.now() }).returning("*");
+      return view(stopped || row);
+    }
+    return view(row);
+  }
+
+  async function wholeOutput(conversationId, id, fromLine = 1) {
+    const row = await knex(table).where({ id, conversation_id: conversationId }).first();
+    if (!row) return { error: "There's no such command in this conversation." };
+    if (row.status === "running") return { error: "It's still running; check_command shows its output so far." };
+    if (!row.truncated) return { note: "Its output wasn't cut, so the result already showed all of it.", output: row.output };
+    const whole = await readFile(logOf(conversationId, row.id), "utf8").catch(() => null);
+    if (whole === null) return { error: "Its whole output isn't on this server any more." };
+    const { lines, shown } = textPart(whole, fromLine);
+    return { run: String(row.id), lines, output: shown };
+  }
+
+  /** On shutdown: commands still running here stop, and say so. */
+  async function stop() {
+    for (const child of live.values()) child.kill();
+  }
+
+  return Object.freeze({
+    run,
+    check,
+    wholeOutput,
+    stop,
+    limits
+  });
+}
+
+function ignoreEnd() {}
+
+/**
+ * The command tools, for one turn in one conversation.
+ * @param {object} options
+ * @param {import("../types.js").AgentCommands} options.commands
+ * @param {number | string} options.conversationId
+ * @param {string} options.root The workspace, where commands run.
+ */
+export function commandTools({ commands, conversationId, root }) {
+  /** The whole output of a run, looked up only by its number from run_command or check_command. */
+  async function readOutput({ run, from_line: fromLine = 1 }) {
+    return /^\d+$/u.test(run) ? commands.wholeOutput(conversationId, run, fromLine) : { error: "Give the run number from run_command or check_command." };
+  }
+
+  return {
+    runCommand: createTool(Object.freeze({
+      id: "run_command",
+      description: `Run a bash script in the workspace: build, test, run programs, use git and the usual Unix tools with pipes and loops. Check what you made and fix errors by running again. A command still running after ${Math.round(commands.limits.foregroundSeconds / 60)} minutes carries on in the background; follow it with check_command.`,
+      inputSchema: z.object({
+        why: z.string().min(3).max(160).describe("What it does, in a few plain words, e.g. Running the tests"),
+        script: z.string().min(1).max(20000).describe("The bash script"),
+        seconds: z.number().int().min(5).max(commands.limits.maxSeconds).optional().describe("Most it may take in total; default 30 minutes")
+      }),
+      execute: ({ why, script, seconds }) => commands.run({ conversationId, cwd: root, why, script, seconds })
+    })),
+    checkCommand: createTool(Object.freeze({
+      id: "check_command",
+      description: "See how a command that went on in the background is doing: its status and output so far.",
+      inputSchema: z.object({ run: z.string().min(1).max(30) }),
+      execute: ({ run }) => commands.check(conversationId, run)
+    })),
+    readCommandOutput: createTool(Object.freeze({
+      id: "read_command_output",
+      description: "Read the whole output of a command whose result was cut (it says so), in parts: give the run number, and from_line to carry on where the last part stopped.",
+      inputSchema: z.object({ run: z.string().min(1).max(30), from_line: z.number().int().min(1).optional() }),
+      execute: (input) => readOutput(input)
+    }))
+  };
+}

package/src/server/tools/defaults.js

@@ -0,0 +1,30 @@
+import { goalTools } from "../goals.js";
+import { planningTools } from "../planning.js";
+import { askInReplyTools, askTools } from "./ask.js";
+import { commandTools } from "./commands.js";
+import { fileTools } from "./files.js";
+
+/**
+ * The tools an agent has unless it's given others, for one turn in one conversation: the
+ * workspace's files (`root`), commands there (`commands`, from createCommands), a to-do list and
+ * notes (`knex`, `tables`; the to-do card needs `post`), goals (`goals`, from
+ * goals.operationsFor) and asking the person (a question card with `post`, otherwise in the reply).
+ * Each other part is left out when what it needs isn't given.
+ * @param {object} options
+ * @param {string} options.root
+ * @param {import("../types.js").AgentCommands | null} [options.commands]
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex | null} [options.knex]
+ * @param {number | string} options.conversationId
+ * @param {((messages: object[]) => Promise<unknown>) | null} [options.post]
+ * @param {import("../types.js").AgentGoalOperations | null} [options.goals]
+ * @param {typeof import("../planning.js").PLANNING_TABLES} [options.tables]
+ */
+export function defaultTools({ root, commands = null, knex = null, conversationId, post = null, goals = null, tables }) {
+  return {
+    ...fileTools({ root }),
+    ...(commands ? commandTools({ commands, conversationId, root }) : {}),
+    ...(knex ? planningTools({ knex, conversationId, post, tables }) : {}),
+    ...(goals ? goalTools(goals) : {}),
+    ...(post ? askTools({ post }) : askInReplyTools())
+  };
+}