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

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @jskit-ai/agent-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The opt-in parts of `@jskit-ai/agent`, for an app that adds them on purpose: the agent's own
+PostgreSQL tables (saved runs, goals, background summaries, commands) and its coding tools (files,
+commands in gVisor or a local process, a to-do list and notes, goals, asking the person). The loop
+itself, and why it works as it does, is in `@jskit-ai/agent`'s README.
+
+## What it adds
+
+| What | Export | Table |
+|---|---|---|
+| Each finished step saved while a reply runs; one a stopped server left is taken over by another | `createRuns`, `startResumer` | `agent_runs` |
+| Goals: a long job carries on by itself in rounds until it's complete, blocked or at a limit | `createGoals`, `goalTools`, `roundPrompt` | `agent_goals` |
+| Summaries between turns, in the background, claimed by one server | `createSummaries` | `agent_summaries`, `agent_summary_queue` |
+| A to-do card in the chat and private job notes, both in the state note at every turn | `planningTools`, `planningNotes`, `currentTodos` | the app's messages and conversations (`PLANNING_TABLES`) |
+| Commands in the workspace; one still running carries on in the background, its whole output a file | `createCommands`, `commandTools` | `agent_commands` |
+| Where commands run: gVisor (`runsc`), or a local process for development | `gvisorExecutor`, `localExecutor` | — |
+| Files: list, find, search, read in parts, write and edit, never outside the workspace | `fileTools`, `inWorkspace` | — |
+| Asking the person: a card with answers to pick from, or in the reply where the chat shows no cards | `askTools`, `askInReplyTools` | — |
+| All of these tools for one turn, each left out when what it needs isn't given | `defaultTools` | — |
+
+`migrations/agent_initial.cjs` creates the tables. Each factory takes the names it uses, so an app
+can rename them or add its own columns (`owner(row)` for goals, extra columns on a claimed run).
+
+## Wiring
+
+The factories take their collaborators by name, once, at startup:
+
+```js
+const runs = createRuns({ knex });
+const goals = createGoals({ knex, runs, notices, find, respond, claim: (row) => runs.claim(row.id), record });
+const summaries = createSummaries({ knex, model, app: "the app", history, notices });
+const commands = createCommands({ knex, executor: gvisorExecutor() });
+```
+
+`notices` is optional: `{ publish(channel, key, payload), subscribe(channel, key, listener) }`,
+where `subscribe` returns a function that stops listening (PostgreSQL LISTEN/NOTIFY, for example).
+With it, a new goal round or a queued summary wakes every server at once; without it, each server
+finds due work on its own timer. `goals.start()` and `summaries.start()` run those loops.
+
+For a turn, `defaultTools({ root, commands, knex, conversationId, post, goals:
+goals.operationsFor(row) })` gives the agent its tools; `post(messages)` adds cards to the chat and
+tells open pages.
+
+Settings: `AGENT_JOB_COST_USD` (what one job may spend; 5 dollars by default, 0 for none),
+`AGENT_RUNSC` (the gVisor binary) and `AGENT_RIPGREP` (ripgrep, with `grep` when it's missing).
+
+## Tests
+
+`npm test` runs every test file. The `*.postgres.test.js` files need a PostgreSQL test database and
+skip without one: set `DB_NAME` to the same value as `TEST_DB_NAME`, with the usual `DB_HOST`,
+`DB_PORT`, `DB_USER` and `DB_PASSWORD`. Each test makes a schema of its own with only this
+package's tables, and drops it afterwards. The gVisor command test also needs `runsc`.

package/migrations/agent_initial.cjs

@@ -0,0 +1,78 @@
+// The agent's own tables. Each row belongs to a conversation by `conversation_id`, without a
+// foreign key: the app says what a conversation is, adding the key (and any columns of its own)
+// in its own migration.
+exports.up = async function up(knex) {
+  // A reply in progress, one per conversation, with the steps it has taken so far (runs.js).
+  await knex.schema.createTable("agent_runs", (table) => {
+    table.bigInteger("conversation_id").primary();
+    table.timestamp("started_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("heartbeat_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.jsonb("steps");
+    table.jsonb("input");
+  });
+
+  // Goals and their rounds (goals.js); one open goal per conversation.
+  await knex.schema.createTable("agent_goals", (table) => {
+    table.bigIncrements("id").primary();
+    table.bigInteger("conversation_id").notNullable();
+    table.text("objective").notNullable();
+    table.string("status", 12).notNullable().defaultTo("active");
+    table.integer("rounds").notNullable().defaultTo(0);
+    table.integer("max_rounds").notNullable().defaultTo(24);
+    table.text("reason");
+    table.string("time_zone", 64).notNullable().defaultTo("UTC");
+    table.string("language", 40).notNullable().defaultTo("");
+    // When the next round is due (null: none queued), and until when a server holds it.
+    table.timestamp("round_at", { useTz: true });
+    table.timestamp("lease_until", { useTz: true });
+    table.integer("attempts").notNullable().defaultTo(0);
+    table.timestamp("created_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("updated_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+  });
+  await knex.raw("alter table agent_goals add constraint agent_goals_status check (status in ('active', 'paused', 'complete', 'blocked'))");
+  await knex.raw("create unique index ux_agent_goals_open on agent_goals (conversation_id) where status in ('active', 'paused')");
+  await knex.raw("create index ix_agent_goals_due on agent_goals (round_at) where round_at is not null");
+
+  // Summaries between turns (summaryStore.js), and the conversations waiting for one.
+  await knex.schema.createTable("agent_summaries", (table) => {
+    table.bigIncrements("id").primary();
+    table.bigInteger("conversation_id").notNullable();
+    // The newest message the summary covers; later messages are read as they are.
+    table.bigInteger("covers_up_to").notNullable();
+    table.text("summary").notNullable();
+    table.integer("messages").notNullable();
+    table.timestamp("created_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.index(["conversation_id", "id"], "ix_agent_summaries_latest");
+  });
+  await knex.schema.createTable("agent_summary_queue", (table) => {
+    table.bigInteger("conversation_id").primary();
+    table.timestamp("requested_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("run_after", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("lease_until", { useTz: true });
+    table.integer("attempts").notNullable().defaultTo(0);
+    table.text("last_error");
+    table.index(["run_after"], "ix_agent_summary_queue_due");
+  });
+
+  // Commands run with the default tools (tools/commands.js).
+  await knex.schema.createTable("agent_commands", (table) => {
+    table.bigIncrements("id").primary();
+    table.bigInteger("conversation_id").notNullable();
+    table.text("why").notNullable().defaultTo("");
+    table.text("script").notNullable();
+    table.string("status", 12).notNullable().defaultTo("running");
+    table.integer("exit_code");
+    table.text("output").notNullable().defaultTo("");
+    table.boolean("truncated").notNullable().defaultTo(false);
+    table.string("server", 128).notNullable();
+    table.timestamp("heartbeat_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("started_at", { useTz: true }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("ended_at", { useTz: true });
+    table.index(["conversation_id", "id"], "ix_agent_commands_conversation");
+  });
+  await knex.raw("alter table agent_commands add constraint agent_commands_status check (status in ('running', 'done', 'failed', 'timed_out', 'stopped'))");
+};
+
+exports.down = async function down(knex) {
+  for (const table of ["agent_commands", "agent_summary_queue", "agent_summaries", "agent_goals", "agent_runs"]) await knex.schema.dropTableIfExists(table);
+};

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@jskit-ai/agent-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "test": "node --test --test-concurrency=1"
+  },
+  "exports": {
+    "./server": "./src/server/index.js",
+    "./server/types": "./src/server/types.js"
+  },
+  "dependencies": {
+    "@jskit-ai/agent": "0.1.0",
+    "zod": "^4.6.7"
+  },
+  "description": "Opt-in parts of the agent: its own tables (saved runs, goals, summaries, commands) and coding tools (files, commands in gVisor or a local process, to-do list, notes, goals, asking the person). PostgreSQL.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "jskit": {
+        "tableOwnership": {
+          "tables": [
+            {
+              "tableName": "agent_runs"
+            },
+            {
+              "tableName": "agent_goals"
+            },
+            {
+              "tableName": "agent_summaries"
+            },
+            {
+              "tableName": "agent_summary_queue"
+            },
+            {
+              "tableName": "agent_commands"
+            }
+          ]
+        }
+      },
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./server",
+            "summary": "Saved runs and their resumer, goal rounds, background summaries, planning notes, the default coding tools and their executors."
+          },
+          {
+            "subpath": "./server/types",
+            "summary": "Types of the runs, goals, commands, notices and executors the server parts build or receive, for code that receives them."
+          }
+        ],
+        "capabilities": []
+      }
+    },
+    "migrations": {
+      "directories": [
+        "migrations"
+      ]
+    }
+  }
+}

package/src/server/executors.js

@@ -0,0 +1,97 @@
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+// Where commands run. An executor's `spawn({ script, cwd, mounts })` starts `bash -c script` in
+// `cwd` and resolves to its child process (stdout, stderr, "close"; `kill()` ends all of it).
+// `mounts` are other folders the command may read ({ source }). Neither executor passes this
+// server's environment on, so no key or password reaches a command.
+const ENV = { PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin", HOME: "/tmp", TMPDIR: "/tmp", LANG: "C.UTF-8", LC_ALL: "C.UTF-8", TERM: "dumb" };
+const onPath = (program) => (program.includes("/") ? existsSync(program) : ENV.PATH.split(":").some((dir) => existsSync(path.join(dir, program))));
+
+// gVisor (the default): the command runs on gVisor's own kernel, rootless and with no network. It
+// sees this machine's programs read-only, an empty /tmp, empty stand-ins for the folders that hold
+// people's and services' own files (`hide`), and can change only the workspace, at the same path
+// as outside. Needs gVisor's runsc (https://gvisor.dev): AGENT_RUNSC, or on the PATH.
+export const GVISOR = {
+  runsc: process.env.AGENT_RUNSC || "runsc",
+  hide: ["/home", "/root", "/run", "/var", "/srv", "/mnt", "/media", "/etc/ssh"],
+  scratch: "1g",
+  processes: 256,
+  processMemory: 2 * 1024 ** 3
+};
+
+export function gvisorExecutor(settings = {}) {
+  const { runsc, hide, scratch, processes, processMemory } = { ...GVISOR, ...settings };
+  const limit = (type, value) => ({ type, hard: value, soft: value });
+  const bind = (source, readonly) => ({ destination: source, type: "bind", source, options: ["rbind", readonly ? "ro" : "rw"] });
+  const tmpfs = (destination, options = []) => ({ destination, type: "tmpfs", source: "tmpfs", options });
+
+  return {
+    kind: "gvisor",
+    available: () => onPath(runsc),
+    async spawn({ script, cwd, mounts = [] }) {
+      const id = `agent-${randomUUID()}`;
+      const dir = await mkdtemp(path.join(os.tmpdir(), "agent-run-"));
+      const state = ["--root", path.join(dir, "state")];
+      await writeFile(path.join(dir, "config.json"), JSON.stringify({
+        ociVersion: "1.0.0",
+        process: {
+          user: { uid: 0, gid: 0 },
+          args: ["/bin/bash", "-c", script],
+          env: Object.entries(ENV).map(([key, value]) => `${key}=${value}`),
+          cwd,
+          noNewPrivileges: true,
+          capabilities: { bounding: [], effective: [], inheritable: [], permitted: [], ambient: [] },
+          rlimits: [limit("RLIMIT_NPROC", processes), limit("RLIMIT_AS", processMemory), limit("RLIMIT_CORE", 0)]
+        },
+        root: { path: "/", readonly: true },
+        hostname: "agent",
+        mounts: [
+          { destination: "/proc", type: "proc", source: "proc" },
+          tmpfs("/dev"),
+          tmpfs("/tmp", [`size=${scratch}`, "mode=1777"]),
+          ...hide.filter((folder) => existsSync(folder)).map((folder) => tmpfs(folder, ["size=1m"])),
+          bind(cwd, false),
+          ...mounts.map((mount) => bind(mount.source, true))
+        ],
+        linux: { namespaces: [{ type: "pid" }, { type: "network" }, { type: "ipc" }, { type: "uts" }, { type: "mount" }] }
+      }));
+      const child = spawn(runsc, ["--rootless", "--network=none", "--ignore-cgroups", "--overlay2=root:memory", ...state, "run", "--bundle", dir, id], { env: ENV, stdio: ["ignore", "pipe", "pipe"] });
+      const kill = child.kill.bind(child);
+      child.kill = () => {
+        execFile(runsc, [...state, "kill", id, "KILL"], () => {});
+        return kill("SIGKILL");
+      };
+      child.once("close", () => execFile(runsc, [...state, "delete", "-force", id], () => rm(dir, { recursive: true, force: true }).catch(() => {})));
+      return child;
+    }
+  };
+}
+
+/**
+ * The local process (opt in): bash in the workspace, with this machine's programs and no sandbox,
+ * for a trusted machine or a container of its own.
+ */
+export function localExecutor() {
+  return {
+    kind: "local",
+    available: () => true,
+    async spawn({ script, cwd }) {
+      const child = spawn("/bin/bash", ["-c", script], { cwd, env: ENV, stdio: ["ignore", "pipe", "pipe"], detached: true });
+      // The command and everything it started.
+      child.kill = () => {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+          // Already ended.
+        }
+        return true;
+      };
+      return child;
+    }
+  };
+}

package/src/server/goals.js

@@ -0,0 +1,312 @@
+import { z } from "zod";
+import { assertCallbacks, createTool } from "@jskit-ai/agent/server";
+import { NO_NOTICES } from "./notices.js";
+
+// Goals and goal rounds, after DeepSeek Harness (MIT; P3–P5 in @jskit-ai/agent's
+// docs/deepseek-harness.md). For a job of several steps the model opens a goal; whenever its turn
+// ends while the goal is active, another round is queued telling it to check the real state and
+// carry on, until it marks the goal complete with evidence, or blocked (not before round 3), or a
+// limit is reached: rounds, or what the job may spend (AGENT_JOB_COST_USD, 5 dollars by default, 0
+// for none). The person's own message always comes first. Rounds are claimed through the database
+// with a lease, so any server carries them on.
+//
+// The table has: id, conversation_id, objective, status (active, paused, complete, blocked), rounds,
+// max_rounds, reason, time_zone, language, round_at, lease_until, attempts, created_at, updated_at,
+// plus whatever `owner(row)` columns the app adds.
+const JOB_COST = process.env.AGENT_JOB_COST_USD;
+export const GOAL_LIMITS = { maxRounds: 24, minRoundsBeforeBlocked: 3, leaseSeconds: 120, retryMs: 5000, costUsd: JOB_COST === undefined || JOB_COST === "" ? 5 : Number(JOB_COST) };
+
+const OPEN = ["active", "paused"];
+
+export function roundPrompt(goal) {
+  return [
+    "<goal_round>",
+    `Objective: ${JSON.stringify(goal.objective)}`,
+    `Round: ${goal.rounds}/${goal.max_rounds}`,
+    "",
+    "Continue working toward the objective in this same conversation. Treat the current files, tool results and saved state as authoritative; inspect them instead of assuming earlier narration is still current. Make concrete progress and verify the result. Before claiming completion, gather evidence that the whole objective is achieved, read the current goal with get_goal, and mark it complete with update_goal. If work remains, leave the goal active for the next round. Mark it blocked only for a real blocker that needs the person.",
+    "</goal_round>"
+  ].join("\n");
+}
+
+const COMPLETE_NOTE = "The goal is marked complete and this run is ending. Write the closing message to the person now: state the outcome, summarise what was done and how it was verified, and point to the concrete results (files, apps, records). Report only what this conversation's tool results actually establish; when a detail isn't established, say so instead of inventing it. Note anything they should review or do next. Don't call any more tools.";
+const BLOCKED_NOTE = "The goal is marked blocked and this run is ending. Write the closing message to the person now: what was completed, the concrete blocking condition, what you tried, and exactly what you need from them. Don't call any more tools.";
+
+/**
+ * The goal tools, for one turn: `operations` is what goals.operationsFor(row, …) returns.
+ * @param {import("./types.js").AgentGoalOperations} operations
+ */
+export function goalTools(operations) {
+  return {
+    createGoal: createTool(Object.freeze({
+      id: "create_goal",
+      description: "Set up a goal that keeps you working on the person's request across automatic rounds until it's done. Use it whenever their request is a job with several steps (building or changing an app, working on files, a multi-step errand), even if they didn't say \"goal\"; not for a quick answer. Then start working on it straight away.",
+      inputSchema: z.object({ objective: z.string().min(5).max(2000).describe("The whole job, with what counts as done") }),
+      execute: ({ objective }) => operations.create(objective.trim())
+    })),
+    getGoal: createTool(Object.freeze({
+      id: "get_goal",
+      description: "Read the current goal: its objective, status and round.",
+      inputSchema: z.object({}),
+      execute: () => operations.get()
+    })),
+    updateGoal: createTool(Object.freeze({
+      id: "update_goal",
+      description: "Change the goal: complete (only with evidence that the whole objective is achieved), blocked (a real blocker only the person can remove; not before 3 rounds of trying), pause, or edit its objective.",
+      inputSchema: z.object({
+        action: z.enum(["complete", "blocked", "pause", "edit"]),
+        objective: z.string().max(2000).optional(),
+        reason: z.string().max(1000).optional().describe("For blocked: what's blocking and what you need")
+      }),
+      execute: (input) => operations.update(input)
+    }))
+  };
+}
+
+/**
+ * Goals in `table`, and their rounds. Hooks: `find(goal)` the conversation a goal is in (null when
+ * it's gone); `respond(row, options)` runs one reply there; `claim(row)` takes the conversation's
+ * reply slot (runs.claim); `record(row, { text, detail })` shows an event line; `notify(row, event)`
+ * tells open pages; `owner(row)` extra columns for a new goal; `spent(goal)` what the job has cost
+ * so far; `track(goal, work)` meters it; `background(work)` keeps a round going after the turn
+ * that queued it. Each optional hook is a function, or left out for its named default. Without
+ * `notices`, each server finds due rounds on its own timer.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} dependencies.knex
+ * @param {import("./types.js").AgentRuns} dependencies.runs
+ * @param {string} [dependencies.table]
+ * @param {string} [dependencies.channel]
+ * @param {import("./types.js").AgentNotices | null} [dependencies.notices]
+ * @param {typeof GOAL_LIMITS} [dependencies.limits]
+ * @param {(goal: object) => Promise<object | null>} dependencies.find
+ * @param {(row: object, options: { timeZone: string, language: string, prompt: string, goalTurn: boolean }) => Promise<unknown>} dependencies.respond
+ * @param {(row: object) => Promise<boolean>} dependencies.claim
+ * @param {(row: object, event: { text: string, detail: string }) => Promise<unknown>} dependencies.record
+ * @param {(row: object, event: object) => Promise<unknown>} [dependencies.notify]
+ * @param {(row: object) => object} [dependencies.owner]
+ * @param {(goal: object) => Promise<number>} [dependencies.spent]
+ * @param {(goal: object, work: () => Promise<unknown>) => Promise<unknown>} [dependencies.track]
+ * @param {(work: Promise<unknown>) => unknown} [dependencies.background]
+ */
+export function createGoals({
+  knex,
+  runs,
+  table = "agent_goals",
+  channel = "agent-goals",
+  notices,
+  limits = GOAL_LIMITS,
+  find,
+  respond,
+  claim,
+  record,
+  notify = notifyNoPages,
+  owner = noOwnerColumns,
+  spent = nothingSpent,
+  track = runUnmetered,
+  background = leaveRunning
+}) {
+  assertCallbacks("createGoals", { notify, owner, spent, track, background });
+  const channelNotices = notices ?? NO_NOTICES;
+  const wake = () => channelNotices.publish(channel, "all", {}).catch(() => {});
+  const openGoal = (conversationId) => knex(table).where({ conversation_id: conversationId }).whereIn("status", OPEN).first();
+  const view = (goal) => goal && { objective: goal.objective, status: goal.status, rounds: goal.rounds, maxRounds: goal.max_rounds, ...(goal.reason ? { reason: goal.reason } : {}) };
+
+  /**
+   * What the goal tools do, for one turn in one conversation. Only a turn started by the person can
+   * open a goal; another bot's request or a routine can't (DSH P5).
+   */
+  function operationsFor(row, { human = false, timeZone = "UTC", language = "" } = {}) {
+    return {
+      async create(objective) {
+        if (!human) return { error: "A goal can only be set up in reply to the person's own message." };
+        const existing = await openGoal(row.conversation_id);
+        if (existing) return { error: "There's already a goal here; read it with get_goal, or update it.", goal: view(existing) };
+        const [goal] = await knex(table).insert({
+          ...owner(row), conversation_id: row.conversation_id,
+          objective: objective.slice(0, 2000), max_rounds: limits.maxRounds, time_zone: timeZone, language
+        }).returning("*");
+        await record(row, { text: "Working on a goal", detail: `Goal set: ${goal.objective}` });
+        return { status: "created", goal: view(goal), note: "Work on it now. If this turn ends before it's done, you'll get another round to carry on." };
+      },
+      async get() {
+        const goal = await openGoal(row.conversation_id);
+        return goal ? { goal: view(goal) } : { goal: null };
+      },
+      async update({ action, objective, reason }) {
+        const goal = await openGoal(row.conversation_id);
+        if (!goal) return { error: "There's no open goal here." };
+        if (action === "edit") {
+          if (!objective) return { error: "Give the new objective." };
+          await knex(table).where({ id: goal.id }).update({ objective: objective.slice(0, 2000), updated_at: knex.fn.now() });
+          return { status: "edited" };
+        }
+        if (action === "pause") {
+          await knex(table).where({ id: goal.id }).update({ status: "paused", round_at: null, updated_at: knex.fn.now() });
+          return { status: "paused", note: "Rounds stop until the person asks you to carry on." };
+        }
+        if (action === "blocked") {
+          if (goal.rounds < limits.minRoundsBeforeBlocked) {
+            return { error: `blocked needs at least ${limits.minRoundsBeforeBlocked} rounds of real attempts; this is round ${goal.rounds}. Keep working.` };
+          }
+          await knex(table).where({ id: goal.id }).update({ status: "blocked", reason: String(reason || "").slice(0, 1000), round_at: null, updated_at: knex.fn.now() });
+          await record(row, { text: "Goal blocked", detail: `Blocked: ${goal.objective}. ${reason || ""}` });
+          return { status: "blocked", note: BLOCKED_NOTE };
+        }
+        if (action === "complete") {
+          await knex(table).where({ id: goal.id }).update({ status: "complete", round_at: null, updated_at: knex.fn.now() });
+          await record(row, { text: "Goal complete", detail: `Complete: ${goal.objective}` });
+          return { status: "complete", note: COMPLETE_NOTE };
+        }
+        return { error: "Use edit, pause, complete or blocked." };
+      }
+    };
+  }
+
+  /** Opens a goal for a request whose reply ran out of steps or time, so it carries on by itself. */
+  function openFor(row, request, options) {
+    return operationsFor(row, { ...options, human: true }).create(`Finish what the person asked: ${String(request).slice(0, 1500)}`);
+  }
+
+  /** A goal that stops at a limit says so plainly, so the person can ask for more. */
+  async function stopAt(goal, reason, detail) {
+    await knex(table).where({ id: goal.id }).update({ status: "blocked", reason, round_at: null, updated_at: knex.fn.now() });
+    const row = await find(goal);
+    if (row) {
+      await record(row, { text: "Stopped working on the goal", detail: `${detail}: ${goal.objective}. Ask to carry on to continue.` });
+      await notify(row, { type: "messages" });
+    }
+  }
+
+  /** After any turn in a conversation: an active goal gets its next round, unless a limit is reached. */
+  async function afterTurn(conversationId) {
+    const goal = await knex(table).where({ conversation_id: conversationId, status: "active" }).first();
+    if (!goal) return;
+    if (goal.rounds >= goal.max_rounds) {
+      await stopAt(goal, `Goal reached its limit of ${goal.max_rounds} rounds.`, `Stopped after ${goal.max_rounds} rounds without finishing`);
+      return;
+    }
+    if (limits.costUsd > 0 && await spent(goal) >= limits.costUsd) {
+      await stopAt(goal, `Goal reached its cost limit of $${limits.costUsd}.`, `Stopped at the job's cost limit ($${limits.costUsd}) without finishing`);
+      return;
+    }
+    await knex(table).where({ id: goal.id }).whereNull("round_at").update({ round_at: knex.fn.now(), updated_at: knex.fn.now() });
+    wake();
+    background(runDue());
+  }
+
+  /** The person carrying on with a paused goal makes it active again. */
+  async function resume(conversationId) {
+    await knex(table).where({ conversation_id: conversationId, status: "paused" }).update({ status: "active", updated_at: knex.fn.now() });
+  }
+
+  async function claimDue() {
+    return knex.transaction(async (trx) => {
+      const due = await trx(table).where({ status: "active" }).whereNotNull("round_at").where("round_at", "<=", trx.fn.now())
+        .where((query) => query.whereNull("lease_until").orWhere("lease_until", "<", trx.fn.now()))
+        .orderBy("round_at").forUpdate().skipLocked().first();
+      if (!due) return null;
+      const [leased] = await trx(table).where({ id: due.id }).update({ lease_until: trx.raw(`now() + interval '${limits.leaseSeconds} seconds'`) }).returning("*");
+      return leased;
+    });
+  }
+
+  async function round(goal) {
+    const row = await find(goal);
+    if (!row) {
+      await knex(table).where({ id: goal.id }).update({ status: "paused", round_at: null, lease_until: null });
+      return;
+    }
+    // A person's reply (or anything else) running here goes first; the round waits.
+    if (!await claim(row)) {
+      await knex(table).where({ id: goal.id }).update({ lease_until: null, round_at: knex.raw(`now() + interval '${limits.retryMs / 1000} seconds'`) });
+      return;
+    }
+    const keep = setInterval(() => {
+      knex(table).where({ id: goal.id }).update({ lease_until: knex.raw(`now() + interval '${limits.leaseSeconds} seconds'`) }).catch(() => {});
+      runs.heartbeat(row.conversation_id).catch(() => {});
+    }, runs.limits.heartbeatMs);
+    const [current] = await knex(table).where({ id: goal.id }).update({ rounds: goal.rounds + 1, round_at: null, updated_at: knex.fn.now() }).returning("*");
+    try {
+      await notify(row, { type: "working", working: true, status: "Carrying on with the goal" });
+      await track(goal, () => respond(row, { timeZone: goal.time_zone, language: goal.language, prompt: roundPrompt(current), goalTurn: true }));
+      await knex(table).where({ id: goal.id }).update({ lease_until: null, attempts: 0 });
+    } catch (error) {
+      // An error stops the rounds (DSH: disarm); the person can ask to carry on.
+      console.error(`Goal ${goal.id} round failed: ${error?.message || error}`);
+      await knex(table).where({ id: goal.id }).update({ status: "paused", reason: String(error?.message || error).slice(0, 500), lease_until: null, round_at: null });
+    } finally {
+      clearInterval(keep);
+      await runs.release(row.conversation_id).catch(() => {});
+      await notify(row, { type: "messages" });
+      await notify(row, { type: "working", working: false });
+    }
+    await afterTurn(goal.conversation_id);
+  }
+
+  let running = null;
+  function runDue() {
+    if (running) return running;
+    running = (async () => {
+      try {
+        for (let count = 0; count < 100; count += 1) {
+          const goal = await claimDue();
+          if (!goal) break;
+          await round(goal);
+        }
+      } catch (error) {
+        console.error(`Goals: ${error?.message || error}`);
+      } finally {
+        running = null;
+      }
+    })();
+    return running;
+  }
+
+  function start({ everyMs = 5000 } = {}) {
+    let stopped = false;
+    const tick = () => { if (!stopped) background(runDue()); };
+    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 || Promise.resolve(), new Promise((resolve) => setTimeout(resolve, ms))]);
+      }
+    };
+  }
+
+  return Object.freeze({
+    operationsFor,
+    openFor,
+    afterTurn,
+    resume,
+    runDue,
+    start,
+    openGoal
+  });
+}
+
+async function notifyNoPages() {}
+
+/** A job whose cost nobody meters has spent nothing. */
+async function nothingSpent() {
+  return 0;
+}
+
+/** Runs a goal round's work without metering it. */
+function runUnmetered(_goal, work) {
+  return work();
+}
+
+/** Leaves a round's work running in this process after the turn that queued it. */
+function leaveRunning(work) {
+  return work;
+}
+
+function noOwnerColumns() {
+  return {};
+}

package/src/server/index.js

@@ -0,0 +1,11 @@
+// @jskit-ai/agent-runtime: the agent's own tables and its coding extras, for an app that adds them
+// on purpose. See README.md.
+export { createRuns, startResumer, RUN_LIMITS } from "./runs.js";
+export { createGoals, goalTools, roundPrompt, GOAL_LIMITS } from "./goals.js";
+export { createSummaries } from "./summaryStore.js";
+export { planningTools, planningNotes, currentTodos, PLANNING_TABLES } from "./planning.js";
+export { defaultTools } from "./tools/defaults.js";
+export { fileTools, inWorkspace, FILE_LIMITS } from "./tools/files.js";
+export { createCommands, commandTools, COMMAND_LIMITS } from "./tools/commands.js";
+export { askInReplyTools, askTools } from "./tools/ask.js";
+export { gvisorExecutor, localExecutor, GVISOR } from "./executors.js";

package/src/server/notices.js

@@ -0,0 +1,17 @@
+/**
+ * Notices for an app that has none: what is published reaches no one, and no one is ever told
+ * anything, so each loop wakes only on its own timer.
+ * @type {import("./types.js").AgentNotices}
+ */
+export const NO_NOTICES = Object.freeze({
+  publish: publishToNoOne,
+  subscribe: listenToNoOne
+});
+
+async function publishToNoOne() {}
+
+function listenToNoOne() {
+  return stopListening;
+}
+
+function stopListening() {}