@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/context/stream-input.mjs

@@ -0,0 +1,159 @@
+/**
+ * lib/engine/context/stream-input.mjs — `--input-format stream-json` on stdin.
+ *
+ * One JSON object per line:
+ *
+ *   {"type":"user","message":{"role":"user","content":"…"}}          a user turn
+ *   {"type":"user","message":{"role":"user","content":[{"type":"text","text":"…"}]}}
+ *   {"type":"control","subtype":"compact","custom_instructions":"…"}  compact now
+ *
+ * The first user message is the run's prompt (unless one was given with -p).
+ * Everything after it is queued and drained by the context manager at the
+ * next turn boundary: a compact control compacts the conversation before the
+ * next model request; a later user message is appended as the next user turn.
+ * A control line that arrives before the first user message applies before the
+ * first request. Unparseable lines are reported and skipped. Anything still
+ * queued when the model finishes is dropped with a warning (a headless run
+ * ends when the model stops).
+ *
+ * `parseStreamInputLine` is pure; `createStreamInput` reads an async iterable
+ * (process.stdin) in the background.
+ *
+ * @module lib/engine/context/stream-input
+ */
+
+/**
+ * @typedef {{kind:'user', message:{role:'user', content:Array<{type:'text', text:string}>}, text:string}
+ *   | {kind:'control', subtype:string, customInstructions?:string}
+ *   | {kind:'invalid', error:string}
+ *   | {kind:'empty'}} StreamInputItem
+ */
+
+/** @param {string} line @returns {StreamInputItem} */
+export function parseStreamInputLine(line) {
+  const s = String(line ?? "").trim();
+  if (s === "") return { kind: "empty" };
+  let o;
+  try {
+    o = JSON.parse(s);
+  } catch {
+    return { kind: "invalid", error: `not JSON: ${s.slice(0, 80)}` };
+  }
+  if (!o || typeof o !== "object") return { kind: "invalid", error: "not a JSON object" };
+  if (o.type === "control") {
+    if (typeof o.subtype !== "string") return { kind: "invalid", error: "a control message needs a subtype" };
+    /** @type {StreamInputItem} */
+    const item = { kind: "control", subtype: o.subtype };
+    if (typeof o.custom_instructions === "string" && o.custom_instructions.trim() !== "") item.customInstructions = o.custom_instructions.trim();
+    return item;
+  }
+  if (o.type === "user") {
+    const content = o.message?.content ?? o.content;
+    const blocks =
+      typeof content === "string"
+        ? [{ type: /** @type {'text'} */ ("text"), text: content }]
+        : Array.isArray(content)
+          ? content.filter((b) => b && b.type === "text" && typeof b.text === "string").map((b) => ({ type: /** @type {'text'} */ ("text"), text: b.text }))
+          : [];
+    const text = blocks.map((b) => b.text).join("\n\n");
+    if (text.trim() === "") return { kind: "invalid", error: "a user message needs text content" };
+    return { kind: "user", message: { role: "user", content: blocks }, text };
+  }
+  return { kind: "invalid", error: `unsupported message type ${JSON.stringify(o.type)}` };
+}
+
+/**
+ * @param {AsyncIterable<Buffer|string> & {destroy?:()=>void}} source
+ * @param {{onInvalid?:(error:string)=>void, parse?:(line:string)=>StreamInputItem}} [o]  `parse`: default `parseStreamInputLine`
+ */
+export function createStreamInput(source, { onInvalid = () => {}, parse = parseStreamInputLine } = {}) {
+  /** @type {StreamInputItem[]} */
+  const queue = [];
+  /** @type {Array<() => void>} */
+  let waiters = [];
+  let ended = false;
+  let closed = false;
+  const wake = () => {
+    const w = waiters;
+    waiters = [];
+    for (const f of w) f();
+  };
+  const push = (/** @type string */ line) => {
+    const item = parse(line);
+    if (item.kind === "empty") return;
+    if (item.kind === "invalid") onInvalid(item.error);
+    else queue.push(item);
+    wake();
+  };
+  void (async () => {
+    let buffer = "";
+    try {
+      for await (const chunk of source) {
+        if (closed) break;
+        buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+          push(buffer.slice(0, nl));
+          buffer = buffer.slice(nl + 1);
+        }
+      }
+      if (buffer.trim() !== "") push(buffer);
+    } catch (e) {
+      onInvalid(`reading input failed: ${e instanceof Error ? e.message : e}`);
+    } finally {
+      ended = true;
+      wake();
+    }
+  })();
+
+  return {
+    /**
+     * The first queued user message, waiting for one if needed.
+     * @returns {Promise<{ok:true, text:string, message:any}|{ok:false}>}
+     */
+    async nextUser() {
+      for (;;) {
+        const i = queue.findIndex((q) => q.kind === "user");
+        if (i !== -1) {
+          const [item] = queue.splice(i, 1);
+          const u = /** @type {{kind:'user', message:any, text:string}} */ (item);
+          return { ok: true, text: u.text, message: u.message };
+        }
+        if (ended || closed) return { ok: false };
+        await new Promise((r) => waiters.push(() => r(undefined)));
+      }
+    },
+    /** Take everything queued so far. */
+    drain() {
+      return /** @type {Array<{kind:'user', message:any}|{kind:'control', subtype:string, customInstructions?:string}>} */ (queue.splice(0, queue.length));
+    },
+    /**
+     * Take the control messages at the head of the queue — those that arrived
+     * before the next queued user message — and leave user messages queued.
+     * Multi-turn input (cli.mjs): each user message is its own turn, and a
+     * control applies before the turn of the user message that follows it.
+     */
+    drainControls() {
+      let n = 0;
+      while (n < queue.length && queue[n].kind === "control") n++;
+      return /** @type {Array<{kind:'control', subtype:string, customInstructions?:string}>} */ (queue.splice(0, n));
+    },
+    /** Control messages still queued (none follows them: the input ended). */
+    get pendingControls() {
+      return queue.filter((q) => q.kind === "control").length;
+    },
+    get pending() {
+      return queue.length;
+    },
+    /** Stop reading (releases stdin so the process can exit). */
+    close() {
+      closed = true;
+      wake();
+      try {
+        source.destroy?.();
+      } catch {
+        /* already closed */
+      }
+    },
+  };
+}

package/lib/engine/guard.mjs

@@ -0,0 +1,152 @@
+/**
+ * lib/engine/guard.mjs — the checks every tool call passes before it runs.
+ *
+ * For one call, in order:
+ *   1. permissions (permissions.mjs): a deny — a deny rule, plan mode, dontAsk —
+ *      refuses the call here; nothing else runs.
+ *   2. in-process gates (hooks.mjs registry, e.g. the outbound send gate):
+ *      a refusal refuses the call. Gates hold in every mode, bypass included.
+ *   3. PreToolUse command hooks: a block refuses the call with the hook's
+ *      reason. A hook's `updatedInput` replaces the input, which then goes back
+ *      through steps 1 and 2. A hook's `permissionDecision` of "allow" settles
+ *      a permission `ask`; "ask" turns an allow into an ask.
+ *   4. an `ask` still standing is refused with a message saying how to allow
+ *      it: there is no one to ask in a headless run. A Notification hook fires.
+ *   5. the call is allowed: the gates' commits run (the send counter), and a
+ *      commit that fails refuses the call. A call refused at any earlier step
+ *      therefore never spends a send against the caps.
+ * After the tool runs, PostToolUse hooks may add feedback for the model.
+ *
+ * Every refusal is recorded in `denials` in the headless result's
+ * `permission_denials` shape: {tool_name, tool_use_id, tool_input}.
+ *
+ * A hook's `continue:false` asks for the run to end; `stopReason` holds it and
+ * the loop stops after the current batch.
+ *
+ * @module lib/engine/guard
+ */
+
+import { evaluatePermission, headlessAskDenial } from "./permissions.mjs";
+import { createPathResolver } from "./context/real-path.mjs";
+
+/**
+ * @param {object} p
+ * @param {string} p.mode
+ * @param {import('./permissions.mjs').RuleSet} p.rules
+ * @param {string} p.cwd
+ * @param {string|null} [p.homedir]
+ * @param {string[]} [p.additionalDirectories]
+ * @param {string[]} [p.configDirs]
+ * @param {((p:string)=>string|null)|null} [p.resolvePath]  CF-19: where a path really leads (default: the real file system)
+ * @param {ReturnType<typeof import('./hooks.mjs').createGateRegistry>} p.gates
+ * @param {ReturnType<typeof import('./hooks.mjs').createHookRunner>|null} [p.hooks]
+ * @param {((q:{toolName:string, input:unknown, reason:string, toolUseId:string, signal?:AbortSignal}) => Promise<'allow'|'deny'>)|null} [p.ask]
+ *   W4-A1: someone to ask (the `cohort session` terminal). A standing `ask` is put to it instead of
+ *   being refused; anything but "allow" (or a throw) refuses the call. Null = headless (step 4).
+ */
+export function createToolGuard({ mode, rules, cwd, homedir = null, additionalDirectories = [], configDirs = [], gates, hooks = null, ask = null, resolvePath = createPathResolver() }) {
+  /** @type {Array<{tool_name:string, tool_use_id:string, tool_input:unknown}>} */
+  const denials = [];
+  /** @type {string|null} */
+  let stopReason = null;
+
+  // CF-19: path rules and the engine-config protection follow symlinks (context/real-path.mjs).
+  const permit = (/** @type {any} */ tool, /** @type {any} */ input) =>
+    evaluatePermission({ toolName: tool.name, input, readOnly: Boolean(tool.readOnly), isMcp: Boolean(tool.mcp), mode, rules, cwd, homedir, additionalDirectories, configDirs, resolvePath });
+
+  const refuse = (/** @type {{id:string, name:string}} */ call, /** @type {unknown} */ input, /** @type string */ error) => {
+    denials.push({ tool_name: call.name, tool_use_id: call.id, tool_input: input });
+    return { ok: /** @type {false} */ (false), error };
+  };
+
+  /**
+   * @param {{id:string, name:string}} call @param {any} tool @param {any} input
+   * @returns {Promise<{ok:true, commits:Array<{gate:string, commit:import('./hooks.mjs').GateCommit}>}|{ok:false, error:string}>}
+   */
+  const gate = async (call, tool, input) => {
+    const g = await gates.evaluate({ toolName: tool.name, toolInput: input, toolUseId: call.id, mcp: tool.mcp ?? null });
+    return g.allow ? { ok: true, commits: g.commits ?? [] } : refuse(call, input, `Blocked by the ${g.gate} gate: ${g.reason}`);
+  };
+
+  return {
+    denials,
+    get stopReason() {
+      return stopReason;
+    },
+
+    /**
+     * @param {{call:{id:string, name:string}, tool:any, input:Record<string,unknown>, signal?:AbortSignal}} p
+     * @returns {Promise<{ok:true, input:Record<string,unknown>, context:string|null}|{ok:false, error:string}>}
+     */
+    async before({ call, tool, input, signal }) {
+      let decision = permit(tool, input);
+      if (decision.behavior === "deny") return refuse(call, input, `Permission denied: ${decision.reason}.`);
+      const g = await gate(call, tool, input);
+      if (!g.ok) return g;
+      let commits = g.commits;
+
+      let finalInput = input;
+      let context = null;
+      if (hooks) {
+        const h = await hooks.preToolUse({ toolName: tool.name, toolInput: input, toolUseId: call.id, signal });
+        if (h.stopReason) stopReason ??= h.stopReason;
+        if (h.decision === "block") return refuse(call, input, `Blocked by a PreToolUse hook: ${h.reason}`);
+        context = h.additionalContext;
+        if (h.updatedInput) {
+          finalInput = h.updatedInput;
+          decision = permit(tool, finalInput);
+          if (decision.behavior === "deny") return refuse(call, finalInput, `Permission denied: ${decision.reason} (after a hook changed the input).`);
+          const g2 = await gate(call, tool, finalInput);
+          if (!g2.ok) return g2;
+          commits = g2.commits; // the verdict on the input that will actually run
+        }
+        if (h.decision === "allow" && decision.behavior === "ask") decision = { behavior: "allow", reason: h.reason || "allowed by a PreToolUse hook" };
+        else if (h.decision === "ask" && decision.behavior === "allow") decision = { behavior: "ask", reason: h.reason || "a PreToolUse hook requires approval" };
+      }
+
+      if (decision.behavior === "ask") {
+        if (hooks) await hooks.notification({ message: `${tool.name} needs approval: ${decision.reason}`, notificationType: "permission_prompt" });
+        if (!ask) return refuse(call, finalInput, headlessAskDenial(tool.name, decision));
+        let answer = "deny";
+        try {
+          answer = await ask({ toolName: tool.name, input: finalInput, reason: decision.reason, toolUseId: call.id, signal });
+        } catch {
+          answer = "deny";
+        }
+        if (answer !== "allow") {
+          return refuse(call, finalInput, `Permission to use ${tool.name} was not given (${decision.reason}). Do not retry the same call; continue without it or ask how to proceed.`);
+        }
+      }
+      for (const c of commits) {
+        let res;
+        try {
+          res = c.commit();
+        } catch (e) {
+          res = { ok: false, reason: `the ${c.gate} gate failed (${e instanceof Error ? e.message : e}); failing closed` };
+        }
+        if (!res.ok) return refuse(call, finalInput, `Blocked by the ${c.gate} gate: ${res.reason}`);
+      }
+      return { ok: true, input: finalInput, context };
+    },
+
+    /**
+     * @param {{call:{id:string, name:string}, tool:any, input:unknown, result:{ok:boolean, content?:string, error?:string}, signal?:AbortSignal}} p
+     * @returns {Promise<string|null>} text to append to the tool result
+     */
+    async after({ call, tool, input, result, signal }) {
+      if (!hooks) return null;
+      const h = await hooks.postToolUse({
+        toolName: tool.name,
+        toolInput: input,
+        toolUseId: call.id,
+        toolResponse: result.ok ? { content: result.content } : { error: result.error, is_error: true },
+        signal,
+      });
+      if (h.stopReason) stopReason ??= h.stopReason;
+      const parts = [];
+      if (h.feedback) parts.push(`[PostToolUse hook feedback]\n${h.feedback}`);
+      if (h.additionalContext) parts.push(`[PostToolUse hook context]\n${h.additionalContext}`);
+      return parts.length ? parts.join("\n\n") : null;
+    },
+  };
+}