@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/tools/schedule-wakeup.mjs

@@ -0,0 +1,45 @@
+/**
+ * lib/engine/tools/schedule-wakeup.mjs — ScheduleWakeup {delaySeconds, prompt, reason}.
+ *
+ * Asks the session to start a turn of its own later (session-runtime/wakeup.mjs):
+ * the delay is clamped to 60–3600 seconds, a newer wakeup replaces the pending
+ * one, and the pending wakeup is kept in the transcript so a resumed session
+ * arms it again. Exists only in a `cohort session` (`sessionOnly`); a mutating
+ * tool to the permission engine.
+ *
+ * @module lib/engine/tools/schedule-wakeup
+ */
+
+import { WAKEUP_MAX_SECONDS, WAKEUP_MIN_SECONDS } from "../session-runtime/wakeup.mjs";
+
+/**
+ * @param {{scheduler:ReturnType<typeof import('../session-runtime/wakeup.mjs').createWakeupScheduler>}} o
+ */
+export function createScheduleWakeupTool({ scheduler }) {
+  return {
+    name: "ScheduleWakeup",
+    readOnly: false,
+    sessionOnly: true,
+    description:
+      `Have this session start again by itself after a delay, with the given prompt as its message. The delay is between ${WAKEUP_MIN_SECONDS} and ${WAKEUP_MAX_SECONDS} seconds (values outside are moved to the nearest limit). ` +
+      "Only one wakeup is pending at a time: scheduling another replaces it. Messages and events that arrive earlier are handled as usual; the wakeup still comes. Use it to check back on something or to resume idle work.",
+    input_schema: {
+      type: "object",
+      properties: {
+        delaySeconds: { type: "number", description: `Seconds from now (${WAKEUP_MIN_SECONDS}–${WAKEUP_MAX_SECONDS}).` },
+        prompt: { type: "string", description: "The message this session receives when it wakes." },
+        reason: { type: "string", description: "Why, in a few words (shown when it fires)." },
+      },
+      required: ["delaySeconds", "prompt", "reason"],
+    },
+    /** @param {{delaySeconds:number, prompt:string, reason:string}} input */
+    async run(input) {
+      if (input.prompt.trim() === "") return { ok: false, error: "The prompt is empty." };
+      const w = scheduler.schedule({ delaySeconds: input.delaySeconds, prompt: input.prompt, reason: input.reason });
+      const notes = [];
+      if (w.clamped) notes.push(`the delay was set to ${w.seconds} s (allowed: ${WAKEUP_MIN_SECONDS}–${WAKEUP_MAX_SECONDS})`);
+      if (w.replaced) notes.push(`it replaces the wakeup that was due at ${new Date(w.replaced.dueAt).toISOString()}`);
+      return { ok: true, content: `Wakeup scheduled in ${w.seconds} s (at ${new Date(w.dueAt).toISOString()}).${notes.length ? ` Note: ${notes.join("; ")}.` : ""}` };
+    },
+  };
+}

package/lib/engine/tools/schema.mjs

@@ -0,0 +1,144 @@
+/**
+ * lib/engine/tools/schema.mjs — tool-input validation and repair (pure).
+ *
+ * A small JSON-Schema subset: exactly what the built-in tool schemas use
+ * (object / string / number / integer / boolean / array, `enum`, `required`,
+ * `minimum`/`maximum`). It is not a general validator and does not pretend to
+ * be one; adding a heavier dependency for it is out of bounds (maestro is
+ * zero-dep by architecture).
+ *
+ * Open-weight models get tool arguments nearly right more often than exactly
+ * right, so validation COERCES the harmless cases before it refuses:
+ *   · a numeric string for a number/integer ("40" → 40)
+ *   · "true"/"false" for a boolean
+ * Unknown properties are dropped, not refused — refusing them costs a turn and
+ * teaches nothing.
+ *
+ * `repairToolJson` is the other half: argument text that did not parse as JSON
+ * gets one conservative repair pass (code fences, trailing commas, unbalanced
+ * closing brackets) before the loop reports the error back to the model.
+ *
+ * @module lib/engine/tools/schema
+ */
+
+/**
+ * @param {any} schema  an object schema
+ * @param {unknown} input
+ * @returns {{ ok:true, value: Record<string, unknown> } | { ok:false, error: string }}
+ */
+export function validateInput(schema, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, error: "input must be a JSON object" };
+  }
+  const props = schema?.properties || {};
+  const out = {};
+  const problems = [];
+  for (const key of schema?.required || []) {
+    if (/** @type any */ (input)[key] === undefined || /** @type any */ (input)[key] === null) {
+      problems.push(`missing required parameter "${key}"`);
+    }
+  }
+  for (const [key, raw] of Object.entries(input)) {
+    const spec = props[key];
+    if (!spec || raw === undefined || raw === null) continue;
+    const r = coerce(spec, raw);
+    if (!r.ok) problems.push(`parameter "${key}" ${r.error}`);
+    else out[key] = r.value;
+  }
+  if (problems.length > 0) return { ok: false, error: problems.join("; ") };
+  return { ok: true, value: out };
+}
+
+/** @param {any} spec @param {unknown} v @returns {{ok:true, value:unknown}|{ok:false, error:string}} */
+function coerce(spec, v) {
+  switch (spec.type) {
+    case "string":
+      if (typeof v !== "string") return { ok: false, error: "must be a string" };
+      if (Array.isArray(spec.enum) && !spec.enum.includes(v)) {
+        return { ok: false, error: `must be one of ${spec.enum.map((e) => JSON.stringify(e)).join(", ")}` };
+      }
+      return { ok: true, value: v };
+    case "number":
+    case "integer": {
+      const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+      if (!Number.isFinite(n)) return { ok: false, error: `must be a ${spec.type}` };
+      if (spec.type === "integer" && !Number.isInteger(n)) return { ok: false, error: "must be an integer" };
+      if (typeof spec.minimum === "number" && n < spec.minimum) return { ok: false, error: `must be ≥ ${spec.minimum}` };
+      if (typeof spec.maximum === "number" && n > spec.maximum) return { ok: false, error: `must be ≤ ${spec.maximum}` };
+      return { ok: true, value: n };
+    }
+    case "boolean":
+      if (typeof v === "boolean") return { ok: true, value: v };
+      if (v === "true" || v === "false") return { ok: true, value: v === "true" };
+      return { ok: false, error: "must be a boolean" };
+    case "array":
+      if (!Array.isArray(v)) return { ok: false, error: "must be an array" };
+      return { ok: true, value: v };
+    case "object":
+      if (!v || typeof v !== "object" || Array.isArray(v)) return { ok: false, error: "must be an object" };
+      return { ok: true, value: v };
+    default:
+      return { ok: true, value: v };
+  }
+}
+
+/**
+ * One conservative repair pass over tool-argument text that failed to parse.
+ * Never guesses at content — only at framing.
+ *
+ * @param {string} raw
+ * @returns {{ ok:true, value: Record<string, unknown> } | { ok:false, error: string }}
+ */
+export function repairToolJson(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return { ok: false, error: "empty tool arguments" };
+  let s = raw.trim();
+  // A fenced block: ```json { … } ```
+  const fence = s.match(/^```[a-zA-Z]*\s*([\s\S]*?)\s*```$/);
+  if (fence) s = fence[1].trim();
+  // Leading prose before the object ("Here are the args: {…}").
+  const first = s.indexOf("{");
+  if (first > 0) s = s.slice(first);
+  // Trailing commas before a closer.
+  s = s.replace(/,\s*([}\]])/g, "$1");
+  const attempt = tryObject(s);
+  if (attempt) return { ok: true, value: attempt };
+  // Unbalanced closers (a truncated stream tail), outside strings only.
+  const closed = closeBrackets(s);
+  if (closed !== null) {
+    const again = tryObject(closed);
+    if (again) return { ok: true, value: again };
+  }
+  return { ok: false, error: "tool arguments are not valid JSON and could not be repaired" };
+}
+
+/** @param {string} s */
+function tryObject(s) {
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+  } catch {
+    return null; // not parseable yet; the caller tries the next repair
+  }
+}
+
+/** @param {string} s @returns {string|null} */
+function closeBrackets(s) {
+  const stack = [];
+  let inString = false;
+  let escaped = false;
+  for (const ch of s) {
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{" || ch === "[") stack.push(ch === "{" ? "}" : "]");
+    else if (ch === "}" || ch === "]") {
+      if (stack.pop() !== ch) return null;
+    }
+  }
+  if (inString || stack.length === 0) return null;
+  return s + stack.reverse().join("");
+}

package/lib/engine/tools/send-message.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/engine/tools/send-message.mjs — SendMessage {to, message, summary?}.
+ *
+ * Local peer messaging for `cohort session` (W4-A1): the message goes to the
+ * named session's control socket (session-runtime/registry.mjs finds it) and
+ * arrives there as a user turn tagged "[from <this session>] …" — at once when
+ * the recipient is idle ("delivered"), after its current work otherwise
+ * ("queued"). A name with no live session is "not_found".
+ *
+ * This is NOT an outbound org send: nothing leaves the machine, so the
+ * in-process send gate (hooks.mjs, `messaging_send` & co.) does not screen it.
+ * It is a mutating tool to the permission engine (an allow rule, bypass, or an
+ * interactive approval), and it exists only in a session, never in a subagent
+ * (`sessionOnly`).
+ *
+ * @module lib/engine/tools/send-message
+ */
+
+import { isValidSessionName } from "../session-runtime/registry.mjs";
+import { sendControl } from "../session-runtime/socket.mjs";
+
+export const MAX_MESSAGE_CHARS = 100_000;
+
+/**
+ * @param {{selfName:string, registry:{get:(name:string)=>any, list:()=>any[]}, send?:typeof sendControl}} o
+ */
+export function createSendMessageTool({ selfName, registry, send = sendControl }) {
+  const liveNames = () =>
+    registry
+      .list()
+      .map((e) => e.name)
+      .filter((n) => n !== selfName);
+  return {
+    name: "SendMessage",
+    readOnly: false,
+    sessionOnly: true,
+    description:
+      "Send a message to another agent session running on this machine, addressed by its session name (ListAgents shows who is running). " +
+      "The recipient gets it as a new message that starts with [from <your session name>]; if it is in the middle of work, the message waits until that work ends. " +
+      "The answer is one of: delivered (it is being worked on now), queued (it will be worked on next), not_found (no session by that name is running). " +
+      "Replies, if any, arrive later as messages from that session. Nothing is sent outside this machine.",
+    input_schema: {
+      type: "object",
+      properties: {
+        to: { type: "string", description: "The recipient's session name." },
+        message: { type: "string", description: "The full message. The recipient sees only this, so include what it needs." },
+        summary: { type: "string", description: "A few words describing the message, shown in the recipient's terminal." },
+      },
+      required: ["to", "message"],
+    },
+    /** @param {{to:string, message:string, summary?:string}} input */
+    async run(input) {
+      const to = input.to.trim();
+      if (!isValidSessionName(to)) return { ok: false, error: `"${input.to}" is not a session name.` };
+      if (to === selfName) return { ok: false, error: "That is this session's own name; a message to yourself is not sent." };
+      if (input.message.trim() === "") return { ok: false, error: "The message is empty." };
+      if (input.message.length > MAX_MESSAGE_CHARS) return { ok: false, error: `The message is longer than ${MAX_MESSAGE_CHARS} characters; shorten it or point to a file.` };
+      const notFound = () => {
+        const live = liveNames();
+        return { ok: /** @type {false} */ (false), error: `not_found: no session named "${to}" is running on this machine. Running: ${live.join(", ") || "none"}.` };
+      };
+      const entry = registry.get(to);
+      if (!entry) return notFound();
+      const r = await send(entry.socketPath, { type: "user", message: input.message, from: selfName, ...(input.summary ? { summary: input.summary } : {}) });
+      if (!r.ok) {
+        if (r.error.code === "not_running") return notFound();
+        return { ok: false, error: `The message to ${to} may not have arrived: ${r.error.message}.` };
+      }
+      const status = r.response?.status;
+      if (r.response?.ok && (status === "delivered" || status === "queued")) {
+        return { ok: true, content: JSON.stringify({ status, to }) };
+      }
+      if (status === "ended") return notFound();
+      return { ok: false, error: `${to} did not accept the message: ${r.response?.error ?? "no reason given"}.` };
+    },
+  };
+}

package/lib/engine/tools/session.mjs

@@ -0,0 +1,70 @@
+/**
+ * lib/engine/tools/session.mjs — the tools that hold per-run state.
+ *
+ * The registry (tools/index.mjs) holds stateless built-ins. These are created
+ * per run, because they share state with it:
+ *
+ *   NotebookEdit                      stateless, listed here so the registry's
+ *                                     order (a prompt-cache prefix) stays put
+ *   TodoWrite                         the run's task list
+ *   Task, Agent, TaskOutput, TaskStop subagents (agents/runtime.mjs)
+ *   BashOutput, KillShell             background shells (bash-background.mjs)
+ *
+ * and the registry's Bash is replaced by the session Bash (persistent working
+ * directory, run_in_background). Order in the tool list: built-ins, Skill,
+ * then these in the order above, then MCP tools.
+ *
+ * `--tools` selection: a session tool is exposed when named; BashOutput and
+ * KillShell come with Bash, TaskOutput and TaskStop with Task or Agent.
+ *
+ * @module lib/engine/tools/session
+ */
+
+import { createBashOutputTool, createKillShellTool, createSessionBash, createShellManager } from "./bash-background.mjs";
+import { notebookEditTool } from "./notebook-edit.mjs";
+import { createTodoWriteTool } from "./todo.mjs";
+
+export const SESSION_TOOL_NAMES = Object.freeze(["NotebookEdit", "TodoWrite", "Task", "Agent", "TaskOutput", "TaskStop", "BashOutput", "KillShell", "Workflow", "WorkflowStatus"]);
+
+/**
+ * Which session tools a `--tools` list exposes (null = every one). Pure.
+ * @param {string[]|null} names
+ * @returns {Set<string>|null}
+ */
+export function wantedSessionTools(names) {
+  if (names == null) return null;
+  const set = new Set(names.filter((n) => SESSION_TOOL_NAMES.includes(n)));
+  if (names.includes("Bash")) {
+    set.add("BashOutput");
+    set.add("KillShell");
+  }
+  if (set.has("Task") || set.has("Agent")) {
+    set.add("TaskOutput");
+    set.add("TaskStop");
+  }
+  if (set.has("Workflow")) set.add("WorkflowStatus");
+  return set;
+}
+
+/**
+ * @param {{cwd:string, env:NodeJS.ProcessEnv, spillDir:string, todoState:ReturnType<typeof import('./todo.mjs').createTodoState>,
+ *          onShellExit?:(summary:any)=>void, envPassthrough?:string[]}} o  `onShellExit`: a background shell ended on its own (CF-50);
+ *   `envPassthrough`: extended-shape secrets background shells keep (CF-22)
+ */
+export function createSessionToolkit({ cwd, env, spillDir, todoState, onShellExit, envPassthrough = [] }) {
+  const shells = createShellManager({ spillDir, env, onExit: onShellExit, passthrough: envPassthrough });
+  const bash = createSessionBash({ shells, projectCwd: cwd });
+  return {
+    shells,
+    bash,
+    /** The registry's tools with Bash replaced by the session Bash, order kept. @param {any[]} tools */
+    withSessionBash: (tools) => tools.map((t) => (t.name === "Bash" ? bash : t)),
+    /**
+     * @param {{wanted:Set<string>|null, agentTools:any[], workflowTools?:any[]}} p  workflowTools: Workflow, WorkflowStatus (W4-A2), appended
+     */
+    tools: ({ wanted, agentTools, workflowTools = [] }) =>
+      [notebookEditTool, createTodoWriteTool(todoState), ...agentTools, createBashOutputTool(shells), createKillShellTool(shells), ...workflowTools].filter((t) => wanted === null || wanted.has(t.name)),
+    /** Kill every background shell. */
+    dispose: () => shells.killAll(),
+  };
+}

package/lib/engine/tools/todo.mjs

@@ -0,0 +1,144 @@
+/**
+ * lib/engine/tools/todo.mjs — the TodoWrite tool and the run's task list.
+ *
+ * Input contract: `{ todos: [{ content, status: pending|in_progress|completed, activeForm? }] }`.
+ * Each call replaces the whole list.
+ *
+ * Validation refuses what cannot be a list (a non-array, an item without
+ * content, an unknown status). Several items in progress at once is allowed
+ * but answered with a warning: one item in progress keeps the list honest.
+ *
+ * The list lives in the run's state: the CLI appends every change to the
+ * session transcript as `{type:'todos', sessionId, ts, todos}` (so `--resume`
+ * restores it), reports it in stream-json (`cohort_todos`) and in the result
+ * (`cohort.todos`). A subagent gets its own list, which is not persisted.
+ *
+ * `validateTodos` and `todosFromRecords` are pure.
+ *
+ * @module lib/engine/tools/todo
+ */
+
+import { readFileSync } from "node:fs";
+import { parseTranscript } from "../session/store.mjs";
+
+export const TODO_STATUSES = Object.freeze(["pending", "in_progress", "completed"]);
+
+/**
+ * @typedef {{content:string, status:'pending'|'in_progress'|'completed', activeForm?:string}} Todo
+ */
+
+/**
+ * @param {unknown} raw
+ * @returns {{ok:true, todos:Todo[], warnings:string[]}|{ok:false, error:string}}
+ */
+export function validateTodos(raw) {
+  if (!Array.isArray(raw)) return { ok: false, error: "todos must be an array" };
+  /** @type {Todo[]} */
+  const todos = [];
+  const problems = [];
+  raw.forEach((item, i) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      problems.push(`todos[${i}] must be an object`);
+      return;
+    }
+    const content = typeof item.content === "string" ? item.content.trim() : "";
+    if (content === "") problems.push(`todos[${i}].content must be a non-empty string`);
+    if (!TODO_STATUSES.includes(item.status)) problems.push(`todos[${i}].status must be one of ${TODO_STATUSES.join(", ")}`);
+    if (item.activeForm !== undefined && typeof item.activeForm !== "string") problems.push(`todos[${i}].activeForm must be a string`);
+    /** @type {Todo} */
+    const todo = { content, status: item.status };
+    if (typeof item.activeForm === "string" && item.activeForm.trim() !== "") todo.activeForm = item.activeForm.trim();
+    todos.push(todo);
+  });
+  if (problems.length > 0) return { ok: false, error: problems.join("; ") };
+  const inProgress = todos.filter((t) => t.status === "in_progress").length;
+  const warnings = inProgress > 1 ? [`${inProgress} items are in_progress; keep exactly one item in progress and finish it before starting the next.`] : [];
+  return { ok: true, todos, warnings };
+}
+
+/** The most recent list recorded in a transcript's records. @param {any[]} records @returns {Todo[]} */
+export function todosFromRecords(records) {
+  for (let i = records.length - 1; i >= 0; i--) {
+    const r = records[i];
+    if (r?.type === "todos" && Array.isArray(r.todos)) {
+      const v = validateTodos(r.todos);
+      return v.ok ? v.todos : [];
+    }
+  }
+  return [];
+}
+
+/** The list a resumed session had. Never throws. @param {string} transcriptPath */
+export function loadSessionTodos(transcriptPath) {
+  try {
+    return todosFromRecords(parseTranscript(readFileSync(transcriptPath, "utf8")).records);
+  } catch {
+    return []; // no transcript yet, or unreadable: start with an empty list
+  }
+}
+
+/**
+ * @param {{initial?:Todo[], onChange?:(todos:Todo[])=>void}} [o]
+ */
+export function createTodoState({ initial = [], onChange = () => {} } = {}) {
+  let todos = [...initial];
+  return {
+    get todos() {
+      return todos;
+    },
+    /** @param {Todo[]} next */
+    set(next) {
+      todos = next;
+      onChange(next);
+    },
+  };
+}
+
+/** @param {Todo[]} todos */
+function summary(todos) {
+  const n = (/** @type string */ s) => todos.filter((t) => t.status === s).length;
+  return `${todos.length} item${todos.length === 1 ? "" : "s"}: ${n("completed")} completed, ${n("in_progress")} in progress, ${n("pending")} pending`;
+}
+
+/**
+ * @param {ReturnType<typeof createTodoState>} state
+ * @returns {import('./index.mjs').Tool & {forChild:()=>any}}
+ */
+export function createTodoWriteTool(state) {
+  return {
+    name: "TodoWrite",
+    // Changes nothing outside this run's own state.
+    readOnly: true,
+    description:
+      "Keep a short task list for multi-step work, so progress stays visible. Each call sends the whole list and replaces the previous one. " +
+      "Mark an item in_progress before starting it and completed as soon as it is done; keep one item in progress at a time. " +
+      "`activeForm` is an optional present-tense phrasing of the item (\"Running the tests\").",
+    input_schema: {
+      type: "object",
+      properties: {
+        todos: {
+          type: "array",
+          description: "The complete task list.",
+          items: {
+            type: "object",
+            properties: {
+              content: { type: "string", description: "The task, in imperative form." },
+              status: { type: "string", enum: [...TODO_STATUSES] },
+              activeForm: { type: "string", description: "The task in present-continuous form." },
+            },
+            required: ["content", "status"],
+          },
+        },
+      },
+      required: ["todos"],
+    },
+    async run(input) {
+      const v = validateTodos(input.todos);
+      if (!v.ok) return { ok: false, error: `The task list was not saved: ${v.error}.` };
+      state.set(v.todos);
+      const warn = v.warnings.length ? `\n\nWarning: ${v.warnings.join(" ")}` : "";
+      return { ok: true, content: `Task list saved (${summary(v.todos)}).${warn}` };
+    },
+    forChild: () => createTodoWriteTool(createTodoState()),
+  };
+}