@jskit-ai/agent 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@jskit-ai/agent",
-  "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"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.93",
+    "@ai-sdk/deepseek": "^3.0.72",
+    "ai": "^7.0.152",
+    "zod": "^4.6.7"
+  },
+  "description": "A working agent loop on the AI SDK: reasoning on every step, retries, tools, room inside a long turn, checks on every reply and summaries for a 1M-token window. No tables.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./server",
+            "summary": "The agent loop, its model calls, tool schemas, context limits, reply checks and table-free summaries."
+          }
+        ],
+        "capabilities": []
+      }
+    }
+  }
+}

package/src/server/callbacks.js

@@ -0,0 +1,13 @@
+/**
+ * Refuses a callback option that was given but is not a function, naming the entry and the option.
+ * An option left out has already taken its named default. A wrong value fails here, where the
+ * options arrive, instead of inside a model step, where the AI SDK drops the error.
+ * @param {string} entry
+ * @param {Record<string, unknown>} callbacks
+ */
+export function assertCallbacks(entry, callbacks) {
+  for (const [name, callback] of Object.entries(callbacks)) {
+    // readable-check: allow method-probe - input validation: the callbacks an application passes the agent engine
+    if (typeof callback !== "function") throw new TypeError(`${entry}: ${name} must be a function, or left out for its default.`);
+  }
+}

package/src/server/checks.js

@@ -0,0 +1,101 @@
+import { REASONING, generateOnce } from "./model.js";
+
+// Checks on a finished reply. Each can send the reply back once, carrying on from its own steps;
+// `checkTexts(app)` words the note the model gets, signed by the app.
+
+export function checkTexts(app) {
+  return {
+    stoppedShort: `(Check from ${app}: your reply ended by saying what you'd do next, and then stopped, so the person is left waiting. Carry on now with your tools and finish the job, then reply with the result. If you can't, say plainly why.)`,
+    markup: `(Check from ${app}: your last message contained raw markup, such as a tool call written out as text or special tokens, so nothing in it ran and the person can't read it. Carry on now: call the tools properly to do what's left, then reply in plain words.)`,
+    unsupported: (claims) => `(Check from ${app}: your reply says ${claims.map((claim) => `"${claim}"`).join(", ")}, but no tool in this reply did that, so it hasn't happened. Do it now with the right tool, or answer again without saying it's done.)`,
+    resumed: "(This reply was interrupted part-way, when the server running it stopped. Your steps so far are above and what they did stays done. Carry on from where you got to, without redoing them, and finish the job.)"
+  };
+}
+
+// --- Stopping short: a short reply that ends by announcing its next step, with no result.
+const ANNOUNCES_NEXT = /(?:\b(?:let me|let's|I'll|I will|I'm going to|now I'll|next,? I'll|one moment|give me a (?:moment|second|sec)|just a (?:moment|second|sec))\b[^.!?\n]{0,160}[.…:>]*|\bfirst\.)\s*$/iu;
+const REPORTS_RESULT = /\b(?:done|here(?:'s| is| are)|saved|I've|I have|made|ready|finished|let me know|if you(?:'d)? (?:like|want)|say the word)\b/iu;
+/** A plan of a paragraph or two counts too ("…then verify it before switching it in."). */
+export const stoppedShort = (text) => text.length < 600 && ANNOUNCES_NEXT.test(text) && !REPORTS_RESULT.test(text);
+
+/** A reply's steps without its closing words, to carry on from. */
+export function withoutClosingWords(transcript) {
+  const last = transcript.at(-1);
+  const saidOnly = last?.role === "assistant" && (typeof last.content === "string" || last.content.every((part) => part.type === "text"));
+  return saidOnly ? transcript.slice(0, -1) : transcript;
+}
+
+// --- Raw model markup: DeepSeek's own tokens (<｜begin▁of▁sentence｜>), tool calls written out as
+// text (<invoke>, <parameter>, ｜DSML｜) and the blocks that come with them (budget, safety). Its
+// presence means the step was malformed.
+export const LEAKED_MARKUP = /<[｜|]{1,2}[^<>\n]{0,80}?[｜|]{1,2}>|｜DSML｜|<\/?(?:invoke|parameter|tool_call|function_calls|tools|ds_safety)\b|<budget:/u;
+const CJK = /[㐀-鿿豈-﫿]/gu;
+
+/**
+ * The reply as people may see it: the markup and what it wraps taken out. After one of DeepSeek's
+ * tokens, the rest of that line goes too when it's in a script the reply otherwise isn't in.
+ */
+export function withoutMarkup(text) {
+  const source = String(text || "");
+  if (!LEAKED_MARKUP.test(source)) return source;
+  // Judged on the lines without one of its tokens, so the junk itself doesn't count.
+  const others = source.split("\n").filter((line) => !/<[｜|]{1,2}[^<>\n]{0,80}?[｜|]{1,2}>/u.test(line)).join("\n");
+  const foreign = (others.match(CJK) || []).length <= others.length * 0.05;
+  return source
+    .replace(/<budget:[^>]*>[\s\S]*?<\/budget:[^>]*>/gu, "")
+    .replace(/<ds_safety>[\s\S]*?<\/ds_safety>/gu, "")
+    .replace(/<(?:[｜|]*DSML[｜|]*\s*)?invoke\b[\s\S]*?(?:<\/(?:[｜|]*DSML[｜|]*\s*)?invoke>|$)/gu, "")
+    .replace(/<(?:[｜|]*DSML[｜|]*\s*)?parameter\b[\s\S]*?(?:<\/(?:[｜|]*DSML[｜|]*\s*)?parameter>|$)/gu, "")
+    .replace(/<[｜|]{1,2}[^<>\n]{0,80}?[｜|]{1,2}>([^\n]*)/gu, (match, rest) => (foreign && CJK.test(rest) ? "" : match))
+    .replace(/<[｜|]{1,2}[^<>\n]{0,80}?[｜|]{1,2}>[ \t]*/gu, "")
+    .replace(/<\/?(?:[｜|]*DSML[｜|]*\s*)?(?:tool_call|function_calls|tools|invoke|parameter)\b[^>\n]*>?/gu, "")
+    .replace(/[｜|]*DSML[｜|]*[^\n]*/gu, "")
+    .split("\n")
+    // What's left of a call in DeepSeek's token form ("runCommand｜｜invoke｜｜…") and lone brackets.
+    .filter((line) => !line.includes("｜") && !/^\s*[<>/]+\s*$/u.test(line))
+    .join("\n")
+    .replace(/\n{3,}/gu, "\n\n")
+    .trim();
+}
+
+// --- Unsupported claims: a reply that says it did something is compared with what its tools did,
+// in one short call. Only claims about this reply's own actions count; plans, offers, questions
+// and things done earlier don't.
+const CLAIMS_ACTION = /\b(?:I(?:'ve| have)?|it's|it is|they're|they are|all|both|now|done|is|are|was|were)\b[^.!?\n]{0,60}\b(?:created|made|saved|sent|added|updated|changed|removed|deleted|moved|renamed|booked|scheduled|set up|attached|uploaded|published|installed|fixed|written|wrote|built|drafted|replied|invited|cancelled|archived|forwarded)\b/iu;
+export const reportsActions = (text) => CLAIMS_ACTION.test(String(text || ""));
+
+/** What a reply's tools did, briefly, from its transcript and the app's own records of it. */
+export function toolRecord(transcript = [], events = [], app = "The app") {
+  const brief = (value, size = 240) => {
+    const text = typeof value === "string" ? value : JSON.stringify(value ?? "");
+    return text.length > size ? `${text.slice(0, size)}…` : text;
+  };
+  const lines = [];
+  for (const message of transcript) {
+    for (const part of Array.isArray(message.content) ? message.content : []) {
+      if (part.type === "tool-call") lines.push(`called ${part.toolName}(${brief(part.input ?? part.args ?? {})})`);
+      // readable-check: allow no-dual-shape - data: a tool result's output is { type, value } in model messages and the bare value in transcripts stored before that
+      if (part.type === "tool-result") lines.push(`  ${part.toolName} answered: ${brief(part.output?.value ?? part.output ?? part.result)}`);
+    }
+  }
+  for (const event of events) lines.push(`${app} recorded: ${event}`);
+  return lines.join("\n") || "(no tool ran in this reply)";
+}
+
+const CLAIMS_CHECKER = [
+  "You check an assistant's reply against a record of what its tools did while writing that reply.",
+  "List each statement in the reply that says something was done in this reply (made, saved, sent, attached, added, changed, deleted, booked, set up, fixed, run, tested) that the record doesn't support.",
+  "A claim is supported if a tool call and its answer in the record show it happened. Ignore plans, offers, questions, advice, facts about the person, things said to have happened earlier in the conversation, and descriptions of what a file or app contains.",
+  "Reply with JSON only: {\"unsupported\": [\"short quote of each unsupported claim\"]}, with [] when every claim is supported."
+].join("\n");
+
+export async function unsupportedClaims({ model, reply, record }) {
+  try {
+    const text = await generateOnce({ model, system: CLAIMS_CHECKER, messages: [{ role: "user", content: `Tool record:\n${record}\n\nReply:\n${String(reply).slice(0, 6000)}` }], reasoning: REASONING.off, maxOutputTokens: 400 });
+    const parsed = JSON.parse(String(text || "").replace(/^\s*```(?:json)?|```\s*$/gu, "").trim());
+    return Array.isArray(parsed.unsupported) ? parsed.unsupported.map(String).filter(Boolean).slice(0, 5) : [];
+  } catch {
+    // The check is a safety net: when it can't run, the reply goes as it is.
+    return [];
+  }
+}

package/src/server/context.js

@@ -0,0 +1,84 @@
+import { SUMMARY_LIMITS } from "./summaries.js";
+import { estimateTokens } from "./text.js";
+
+// Context for the model's 1-million-token window. Between turns, a conversation is summarised
+// (summaries.js); what's after the summary is read word for word.
+
+// Should summarising fall behind, the oldest messages give way past this size, and the model is
+// told; never silently. It leaves a long turn's own steps room in the window.
+export const HISTORY_MAX_TOKENS = 600000;
+
+export function withinBudget(history, maxTokens = HISTORY_MAX_TOKENS) {
+  let tokens = estimateTokens(history);
+  let start = 0;
+  while (start < history.length - 1 && tokens > maxTokens) tokens -= estimateTokens([history[start++]]);
+  if (!start) return history;
+  // A cut never starts on a tool result whose call was cut.
+  while (start < history.length - 1 && history[start].role === "tool") start += 1;
+  console.error(`A reply's history was cut by ${start} messages: summarising didn't keep up.`);
+  return [{ role: "system", content: "(The earliest part of this conversation isn't shown: it was too long to read and couldn't be summarised just now. If you need something from it, say so rather than guess.)" }, ...history.slice(start)];
+}
+
+export function summaryNote(summary) {
+  return `Summary of the earlier part of this conversation (those messages are no longer shown; it was written for you, not by the person). If you need a detail that isn't here, say so or look it up; never invent it.\n\n${summary}`;
+}
+
+// Room inside one long turn (as Claude Code's context editing and DeepSeek Harness's result pruning
+// do): before each model call, past `trimAt` estimated tokens, the oldest tool results (never the
+// newest `keepRecent`) give way to a one-line note until the request is under `trimTo`. Calls and
+// the model's words stay. Results once left out stay out for the rest of the turn, so the prompt's
+// start changes rarely and the cache keeps hitting. Stored history is untouched.
+export const TURN_LIMITS = { trimAt: 700000, trimTo: 500000, keepRecent: 20 };
+
+const partTokens = (part) => Math.ceil(JSON.stringify(part).length / 4);
+
+export function trimOldResults(messages, left = new Set(), limits = TURN_LIMITS) {
+  const results = messages.flatMap((message) => (message.role === "tool" && Array.isArray(message.content) ? message.content.filter((part) => part.type === "tool-result") : []));
+  const total = messages.reduce((sum, message) => sum + (Array.isArray(message.content) ? message.content.reduce((inner, part) => inner + partTokens(part), 0) : Math.ceil(String(message.content || "").length / 4)), 0);
+  if (total > limits.trimAt) {
+    let size = total;
+    for (const part of results.slice(0, Math.max(0, results.length - limits.keepRecent))) {
+      if (size <= limits.trimTo) break;
+      if (left.has(part.toolCallId)) continue;
+      left.add(part.toolCallId);
+      size -= partTokens(part);
+    }
+  }
+  if (!left.size) return messages;
+  return messages.map((message) => (message.role === "tool" && Array.isArray(message.content)
+    ? { ...message, content: message.content.map((part) => (part.type === "tool-result" && left.has(part.toolCallId)
+      ? { ...part, output: { type: "text", value: `(This older result of ${part.toolName} was left out to save room. Run the tool again if you need it.)` } }
+      : part)) }
+    : message));
+}
+
+// An earlier turn's tool result, as later turns read it: past `OLD_RESULT_CHARS` it's cut, saying
+// so (a whole page or file isn't needed twice; the model can look again). The same cut every
+// time, so the prompt cache isn't disturbed.
+export const OLD_RESULT_CHARS = 6000;
+export function clipOldResult(message) {
+  if (message.role !== "tool" || !Array.isArray(message.content)) return message;
+  return {
+    ...message,
+    content: message.content.map((part) => {
+      if (part.type !== "tool-result") return part;
+      // readable-check: allow no-dual-shape - data: a tool result's output is { type, value } in model messages and the bare value in transcripts stored before that
+      const text = typeof part.output?.value === "string" ? part.output.value : JSON.stringify(part.output?.value ?? part.output ?? null);
+      return text.length > OLD_RESULT_CHARS ? { ...part, output: { type: "text", value: `${text.slice(0, OLD_RESULT_CHARS)}… [the rest of this result is no longer shown]` } } : part;
+    })
+  };
+}
+
+// The sizes above are for a window of about a million tokens. For a model with a smaller one
+// (`contextTokens`), each shrinks in proportion: when to summarise, how much is kept word for
+// word, where a long turn's old results give way and the last-resort cut.
+export const WINDOW_TOKENS = 1048576;
+export function windowLimits(contextTokens = WINDOW_TOKENS) {
+  const share = Math.min(1, Math.max(0.01, Number(contextTokens) / WINDOW_TOKENS || 1));
+  const scaled = (limits, keys) => ({ ...limits, ...Object.fromEntries(keys.map((key) => [key, Math.floor(limits[key] * share)])) });
+  return {
+    history: Math.floor(HISTORY_MAX_TOKENS * share),
+    turn: scaled(TURN_LIMITS, ["trimAt", "trimTo"]),
+    summaries: scaled(SUMMARY_LIMITS, ["compactAt", "summariseNowAt", "keepTokens", "minTokens", "readTokens"])
+  };
+}

package/src/server/index.js

@@ -0,0 +1,11 @@
+// @jskit-ai/agent: a working agent loop on the AI SDK. See README.md.
+export { createTool, modelTools } from "./tool.js";
+export { toolSchema } from "./schema.js";
+export { chatModel, generateOnce, REASONING, LOOP_OUTPUT_TOKENS, MODEL_RETRIES } from "./model.js";
+export { runLoop, cleanTranscript, REPLY_DEADLINE_MS } from "./loop.js";
+export { estimateTokens, textPart, READ_LIMIT, sameGist, stripNotes } from "./text.js";
+export { withinBudget, summaryNote, trimOldResults, clipOldResult, windowLimits, TURN_LIMITS, HISTORY_MAX_TOKENS, OLD_RESULT_CHARS, WINDOW_TOKENS } from "./context.js";
+export { checkTexts, stoppedShort, withoutClosingWords, LEAKED_MARKUP, withoutMarkup, reportsActions, toolRecord, unsupportedClaims } from "./checks.js";
+export { compactMessages, writeSummary, transcriptText, cutPoint, SUMMARY_LIMITS } from "./summaries.js";
+export { hearWhileWorking, remindOnRepeat } from "./turn.js";
+export { assertCallbacks } from "./callbacks.js";

package/src/server/loop.js

@@ -0,0 +1,192 @@
+import { generateText, stepCountIs, streamText } from "ai";
+import { assertCallbacks } from "./callbacks.js";
+import { LOOP_OUTPUT_TOKENS, MODEL_RETRIES, REASONING, generateOnce } from "./model.js";
+import { TURN_LIMITS, summaryNote, trimOldResults } from "./context.js";
+import { sameGist, stripNotes } from "./text.js";
+import { modelTools } from "./tool.js";
+
+// How long one reply may run before it stops and reports (AGENT_REPLY_MINUTES, default 15).
+export const REPLY_DEADLINE_MS = (Number(process.env.AGENT_REPLY_MINUTES) || 15) * 60 * 1000;
+
+/**
+ * The agent loop: call the model, run the tools it asks for, feed the results back, until it
+ * answers without a tool call, runs out of steps or reaches its deadline. Every step reasons; old
+ * tool results give way inside a long turn; each finished step can be saved. A reply always ends
+ * with a message: one that stops early ends with the model's own account of where it got to.
+ *
+ * `history` is the conversation as model messages. The summary, the state note and any other
+ * system messages in it go into the system prompt, after the instructions, in that order.
+ * Returns { text, transcript, unfinished?, account? }; `unfinished` (out of steps or time) means the
+ * job can carry on from here, and `account` is the account the reply ends with, when it ends with
+ * one, so a check that sends a reply back can leave the engine's own words alone. With `onText(text)` the reply streams: each step's words so far, as they
+ * come. `onStep(step)` hears each finished step. Aborting `signal` (the person pressed Stop, or a
+ * tool's outcome is unknown) ends the run at once with the signal's reason, without an account.
+ * When `throwIf(error, steps)` says so, a failed call ends the run with its error instead of an
+ * account (an app that shows errors itself, when nothing was done yet). Each callback option is a
+ * function, or left out for its named default; anything else is refused with a TypeError naming it.
+ */
+export async function runLoop({
+  model, name, instructions, history, tools = {}, summary = "", state = "", maxSteps,
+  onSteps = saveNoSteps, onStep = ignoreStep, onText = null, signal = null, carriesOn = false, quietIfEmpty = false, clean = stripNotes, throwIf = neverThrow,
+  reasoning = REASONING.on, maxOutputTokens = LOOP_OUTPUT_TOKENS, turnLimits = TURN_LIMITS, deadlineMs = REPLY_DEADLINE_MS
+}) {
+  assertCallbacks("runLoop", { onSteps, onStep, clean, throwIf });
+  const messages = [...history];
+  // A transcript cut mid-way must not start with a tool result.
+  while (messages.length && messages[0].role === "tool") messages.shift();
+  if (summary) messages.unshift({ role: "system", content: summaryNote(summary) });
+  if (state) messages.splice(Math.max(0, messages.length - 1), 0, { role: "system", content: state });
+  const system = [instructions, ...messages.filter((message) => message.role === "system").map((message) => message.content)];
+  const conversation = messages.filter((message) => message.role !== "system");
+
+  // Each step reports only its own messages; the run's transcript is all of them, in order.
+  const done = [];
+  const generated = [];
+  const left = new Set();
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(), deadlineMs);
+  let result = null;
+  let stopped = "";
+  try {
+    const call = {
+      model,
+      instructions: systemPrompt(model, system),
+      messages: conversation,
+      tools: modelTools(tools),
+      stopWhen: stepCountIs(maxSteps),
+      providerOptions: reasoning,
+      maxOutputTokens,
+      maxRetries: MODEL_RETRIES,
+      abortSignal: signal ? AbortSignal.any([deadline.signal, signal]) : deadline.signal,
+      prepareStep: ({ messages: current }) => {
+        const trimmed = trimOldResults(current, left, turnLimits);
+        return trimmed === current ? {} : { messages: trimmed };
+      },
+      onStepFinish: async (step) => {
+        done.push(step);
+        generated.push(...(step.response?.messages || []));
+        await onStep(step);
+        await onSteps(cleanTranscript(generated)).catch((error) => console.error(`Saving ${name}'s steps: ${error?.message || error}`));
+      }
+    };
+    result = onText ? await streamed(call, onText) : await generateText(call);
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason ?? error;
+    if (throwIf(error, done)) throw error;
+    stopped = deadline.signal.aborted ? "it was taking too long" : "something went wrong on my side";
+    console.error(`${name}'s reply stopped: ${error?.message || error}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  const transcript = result ? cleanTranscript(generated) : [];
+  let text = result ? clean(replyText(transcript) || result.text) : "";
+  const outOfSteps = result && (result.finishReason === "tool-calls" || done.length >= maxSteps);
+  if (outOfSteps) stopped = "I reached the most steps I take in one go";
+  if (result && deadline.signal.aborted) stopped = "it was taking too long";
+  const resumable = Boolean(outOfSteps || deadline.signal.aborted);
+  // One that may only chime in (a group follow-up) may say nothing at all.
+  let account = "";
+  if (stopped || (!text && !quietIfEmpty)) {
+    account = await sumUp({ model, name, conversation, steps: done, reason: stopped || "I didn't write anything at the end", carriesOn: carriesOn && resumable, clean });
+    text = [text, account].filter(Boolean).join("\n\n");
+    transcript.push({ role: "assistant", content: account });
+  }
+  return { text, transcript, ...(resumable ? { unfinished: stopped } : {}), ...(account ? { account } : {}) };
+}
+
+/** A run whose steps nobody saves. */
+async function saveNoSteps() {}
+
+/** A run whose finished steps nobody hears. */
+function ignoreStep() {}
+
+/** A run whose failed call always ends with an account, never with its error. */
+function neverThrow() {
+  return false;
+}
+
+/** A streamed run: each step's words go to `onText` as they come; the result is read at the end. */
+async function streamed(call, onText) {
+  const stream = streamText({ ...call, onError: () => {} });
+  let text = "";
+  for await (const part of stream.fullStream) {
+    if (part.type === "error") throw part.error;
+    if (part.type === "start-step") text = "";
+    if (part.type === "text-delta" && part.text) await onText((text += part.text));
+  }
+  return { finishReason: await stream.finishReason, text: await stream.text };
+}
+
+/**
+ * The system prompt as each format takes it: one message in the OpenAI style, parts joined by a
+ * blank line; separate blocks in the Anthropic format.
+ */
+function systemPrompt(model, parts) {
+  const present = parts.filter(Boolean);
+  return String(model.provider || "").startsWith("anthropic") ? present.map((content) => ({ role: "system", content })) : present.join("\n\n");
+}
+
+/**
+ * A reply's stored transcript keeps its tool calls and results; reasoning and provider
+ * bookkeeping are dropped.
+ */
+export function cleanTranscript(messages = []) {
+  return messages.map((message) => ({
+    role: message.role,
+    content: Array.isArray(message.content)
+      ? message.content.filter((part) => part.type !== "reasoning").map(({ providerOptions, ...part }) => part)
+      : message.content
+  }));
+}
+
+/**
+ * The words of a reply: each step's text a paragraph, leaving out a step that repeats an earlier
+ * one's opening, or says again in other words what a later one says (the later one is the answer).
+ */
+function replyText(transcript) {
+  const opening = (text) => text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim().slice(0, 60);
+  return transcript
+    .filter((message) => message.role === "assistant")
+    .flatMap((message) => (Array.isArray(message.content) ? message.content.filter((part) => part.type === "text").map((part) => part.text) : [message.content]))
+    .map((text) => String(text || "").trim())
+    .filter(Boolean)
+    .filter((text, index, all) => all.findIndex((other) => opening(other) === opening(text)) === index)
+    .filter((text, index, all) => !all.slice(index + 1).some((later) => sameGist(text, later)))
+    .join("\n\n");
+}
+
+/** What the steps did, briefly, for the account of a reply that stopped early. */
+function stepLog(steps) {
+  const brief = (value) => {
+    const text = typeof value === "string" ? value : JSON.stringify(value ?? "");
+    return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+  };
+  return steps.slice(-20).flatMap((step) => [
+    ...(step.toolCalls || []).map((call) => `- called ${call.toolName}(${brief(call.input ?? call.args)})`),
+    ...(step.toolResults || []).map((answer) => `  → ${brief(answer.output ?? answer.result)}`),
+    ...(String(step.text || "").trim() ? [`- said: ${brief(step.text)}`] : [])
+  ]).join("\n") || "(no steps finished)";
+}
+
+async function sumUp({ model, name, conversation, steps, reason, carriesOn, clean }) {
+  const asked = [...conversation].reverse().find((message) => message.role === "user");
+  try {
+    const text = clean(await generateOnce({
+      model,
+      system: [
+        `You are ${name}, a personal assistant bot. You were working on the person's request but stopped early because ${reason}.`,
+        carriesOn
+          ? "Write one short chat message: what you did, where things stand now, and what's left, which you're carrying on with by yourself in the background now (they don't need to do anything)."
+          : "Write one short chat message: what you did, where things stand now, what's left, and that they can ask you to carry on.",
+        "Only mention what the log shows actually happened. Never claim a step the log doesn't show, and never ask for passwords."
+      ].join("\n"),
+      messages: [{ role: "user", content: `The request: ${typeof asked?.content === "string" ? asked.content.slice(0, 1500) : "(see the log)"}\n\nWhat happened:\n${stepLog(steps)}` }]
+    }));
+    if (text) return text;
+  } catch {
+    // The plain account below still tells the person.
+  }
+  return carriesOn
+    ? `I paused because ${reason}, and I'm carrying on from where things are by myself now.`
+    : `I stopped before finishing, because ${reason}. Ask me to carry on and I'll pick it up from where things are.`;
+}

package/src/server/model.js

@@ -0,0 +1,43 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createDeepSeek } from "@ai-sdk/deepseek";
+import { generateText } from "ai";
+
+/**
+ * A provider's chat model. With an Anthropic-style address (DeepSeek's own API) it's called in
+ * that format, as Claude Code calls it, so signed reasoning goes back on every step; otherwise in
+ * the OpenAI style (Together AI, DeepSeek), where reasoning goes back as reasoning_content.
+ */
+export function chatModel({ apiKey, model, baseURL, anthropicURL = "", fetch: fetchImpl }) {
+  const client = anthropicURL
+    ? createAnthropic({ apiKey, baseURL: anthropicURL, fetch: fetchImpl })
+    : createDeepSeek({ apiKey, baseURL, fetch: fetchImpl });
+  return client(model);
+}
+
+// Reasoning, written for both formats (each reads only its own options). On: adaptive thinking at
+// high effort, so the model spends a lot on a hard step and almost nothing on "hi"; the OpenAI-style
+// client thinks when no setting is sent. Off: for quick one-shot calls.
+export const REASONING = {
+  on: { anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "high" } },
+  off: { deepseek: { thinking: { type: "disabled" } }, anthropic: { thinking: { type: "disabled" } } }
+};
+
+// A loop step may write a long answer: the Anthropic format needs a cap, and its default is small.
+export const LOOP_OUTPUT_TOKENS = 32000;
+
+// Failed model calls are tried again with growing waits (2, 4, 8… seconds), about two minutes in
+// all, before a reply gives up and says so.
+export const MODEL_RETRIES = 6;
+
+/** One call without tools, such as a summary or a short label; returns its text. */
+export async function generateOnce({ model, system, messages, reasoning = REASONING.off, maxOutputTokens }) {
+  const result = await generateText({
+    model,
+    ...(system ? { system } : {}),
+    messages,
+    providerOptions: reasoning,
+    maxRetries: MODEL_RETRIES,
+    ...(maxOutputTokens ? { maxOutputTokens } : {})
+  });
+  return result.text;
+}

package/src/server/schema.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+
+// A tool's input schema as the model is shown it. DeepSeek models get the limits of strings,
+// numbers and arrays written into the field's description ("constraints: maximum length 200")
+// instead of as JSON Schema keywords. This is the form every evaluation was measured with, so it
+// stays exactly so. Input is still checked against the original schema.
+const STRING_LIMITS = {
+  minLength: (value) => `minimum length ${value}`,
+  maxLength: (value) => `maximum length ${value}`,
+  pattern: (value) => `input must match this regex ${value}`
+};
+const FORMATS = new Set(["email", "uri", "url", "uuid", "cuid", "emoji"]);
+const NUMBER_LIMITS = {
+  minimum: (value) => `greater than or equal to ${value}`,
+  exclusiveMinimum: (value) => `greater than ${value}`,
+  maximum: (value) => `lower than or equal to ${value}`,
+  exclusiveMaximum: (value) => `lower than ${value}`,
+  multipleOf: (value) => `multiple of ${value}`
+};
+const REWRAPPED = new Set(["object", "array", "string", "number", "integer"]);
+// A whole number's implicit range isn't a limit anyone set.
+const SAFE = Number.MAX_SAFE_INTEGER;
+const ARRAY_LIMITS = {
+  minItems: (value) => `minimum length ${value}`,
+  maxItems: (value) => `maximum length ${value}`
+};
+
+function describe(node, constraints) {
+  if (!constraints.length) return node;
+  const { description, ...rest } = node;
+  return { ...rest, description: `${description ? `${description}\n` : ""}constraints: ${constraints.join(", ")}` };
+}
+
+function rewrite(node) {
+  if (Array.isArray(node)) return node.map(rewrite);
+  if (!node || typeof node !== "object") return node;
+  let out = Object.fromEntries(Object.entries(node).map(([key, value]) => [key, typeof value === "object" ? rewrite(value) : value]));
+  if (out.type === "string") {
+    const constraints = [];
+    // A format (email, url) stands for its own pattern.
+    const formatted = FORMATS.has(out.format);
+    for (const [key, value] of Object.entries(out)) {
+      if (STRING_LIMITS[key]) {
+        if (!(key === "pattern" && formatted)) constraints.push(STRING_LIMITS[key](value));
+        delete out[key];
+      } else if (key === "format" && formatted) {
+        constraints.push(`a valid ${value === "uri" ? "url" : value}`);
+        delete out[key];
+      }
+    }
+    out = describe(out, constraints);
+  } else if (out.type === "number" || out.type === "integer") {
+    const constraints = [];
+    for (const [key, value] of Object.entries(out)) {
+      if (!NUMBER_LIMITS[key]) continue;
+      if (out.type !== "integer" || Math.abs(value) !== SAFE) constraints.push(NUMBER_LIMITS[key](value));
+      delete out[key];
+    }
+    out = describe(out, constraints);
+  } else if (out.type === "object") {
+    // An object of named fields is closed; one with no fields (a record) states that none is required.
+    if (out.properties && !("additionalProperties" in out)) out.additionalProperties = false;
+    // An optional text, number, list, object or either-or field with a description of its own is
+    // written description first.
+    const required = new Set(out.required || []);
+    for (const [key, field] of Object.entries(out.properties || {})) {
+      if (!required.has(key) && node.properties[key].description !== undefined && (REWRAPPED.has(field.type) || field.anyOf)) {
+        const { description, ...rest } = field;
+        out.properties[key] = { description, ...rest };
+      }
+    }
+    if (!Object.keys(out.properties || {}).length) out.required ??= [];
+  } else if (out.type === "array") {
+    const constraints = [];
+    for (const [key, value] of Object.entries(out)) {
+      if (ARRAY_LIMITS[key]) {
+        constraints.push(ARRAY_LIMITS[key](value));
+        delete out[key];
+      }
+    }
+    out = describe(out, constraints);
+  }
+  return out;
+}
+
+export function toolSchema(schema) {
+  return rewrite(z.toJSONSchema(schema, { target: "draft-7", io: "input", unrepresentable: "any" }));
+}