@cortad/connector 0.6.1 → 0.6.3

package/lib/mcp.mjs

@@ -1,6 +1,6 @@
 // The MCP face: newline-delimited JSON-RPC 2.0 on stdin and stdout, protocol 2025-06-18, no
 // dependency. stdout carries protocol messages and nothing else; everything a person might read
-// goes to stderr. The tools are the six doors of lib/doors.mjs; the names they replaced still
+// goes to stderr. The tools are the seven doors of lib/doors.mjs; the names they replaced still
 // answer, so an agent handed an older skill is told where to go instead of getting nothing.
 
 import { randomUUID } from "node:crypto";
@@ -11,12 +11,12 @@ export const PROTOCOL = "2025-06-18";
 // Codex keeps only the first 512 characters self-contained and Claude Code shares about 4 KB across
 // every server, so the first paragraph stands alone and the whole stays under 1,500 characters.
 export const instructions = (spec = "cortad") => [
-  "Cortad tests the AI in this repository, then watches it in production with the same questions: simulated users written from its code talk to the app on this machine, and each reply is asked its rules, journeys and standards. Connect the app with its start command after `--`; Cortad sends each chosen AI endpoint its test request and learns it from the answer. You send one message only where status says an endpoint needs a signed-in user. A run starts when the person presses Run simulation or asks you.",
-  `status says what to know right now. Tell the person what status found in three or four short, plain lines, leaving out file paths, endpoints, status codes and setting names unless they ask. Before you stop, start \`npx -y ${spec} wait\` as a background command: it returns when the next run or verify ends, with what it found. test is the one call after a change: say what you built and Cortad decides what kind of test that is. After a run, status gives you what their users ran into; tell the person what you would change, worst first, three problems at most, and nothing is edited before their go. On their go, one fix at a time: verify replays the failing conversations, says whether the failure is gone, and says how long the last fix for it held. status about production is the live app and what is wrong in it; connect connects it. dispute records a question that reads this app wrong, and tell sends the Cortad team a note.`,
+  "Cortad tests the AI in this repository and reads how it behaves with its users: simulated users written from its code talk to the app on this machine, and the live app's real conversations are read with the same questions. Connect the app with its start command after `--`; Cortad sends each chosen AI endpoint its test request and learns it from the answer. You send one message only where status says an endpoint needs a signed-in user. A run starts when the person presses Run simulation or asks you.",
+  `status says where things stand. Tell the person what status found in three or four short, plain lines, leaving out file paths, endpoints, status codes and setting names unless they ask. Before you stop, start \`npx -y ${spec} wait\` as a background command: it returns when the next run or verify ends. test is the one call after a change: say what you built. After a run, behavior says how the AI behaved with their users: tell the person persona by persona, in plain words, who they are, what they want, who achieved it, what the app did well and where it gave way; then what you would change and why that follows. Nothing is edited before their go. On their go, one fix at a time: verify replays the conversations a problem happened in and says whether the behavior moved. behavior with against compares two points and with history is the log; search finds conversations by meaning. connect connects the live app; tell sends a note, or says a question reads this app wrong.`,
 ].join("\n\n");
 export const INSTRUCTIONS = instructions();
 
-// Every name tools/call answers: the six doors and the names they replaced.
+// Every name tools/call answers: the seven doors and the names they replaced.
 const NAMES = new Set([...DOOR_NAMES, ...RETIRED]);
 
 const error = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });

package/lib/message-text.cjs

@@ -0,0 +1,48 @@
+// What one message says, whichever provider's shape it is in: OpenAI chat and Responses parts,
+// Anthropic and Bedrock blocks, Gemini parts. Text stays text; what is not text becomes a plain marker
+// ("[image]", "[file receipt.pdf]", "[tool call lookup_order {...}]") so a reader knows it was there.
+// The same rules as the SDKs' partText and the backend's src/ingest/message-text.ts.
+const ARGS_MAX = 300;
+
+const args = (v) => {
+  const s = typeof v === "string" ? v : JSON.stringify(v ?? {});
+  return s.length > ARGS_MAX ? `${s.slice(0, ARGS_MAX)}...` : s;
+};
+const named = (kind, name) => (typeof name === "string" && name ? `[${kind} ${name}]` : `[${kind}]`);
+const IMAGE = /^(?:image|image_url|input_image|image_file)$/;
+const FILE = /^(?:file|input_file|document)$/;
+const AUDIO = /^(?:audio|input_audio)$/;
+// A model's reasoning and a provider's own tools (a web search it ran, the page it fetched): not what was said.
+const INTERNAL = /^(?:thinking|redacted_thinking|reasoning|server_tool_use|mcp_tool_use|\w+_tool_result|(?:web_search|file_search|code_interpreter|image_generation|computer|mcp)_call)$/;
+const mime = (data) => String(data?.mimeType ?? data?.mime_type ?? "");
+
+function partText(part) {
+  if (typeof part === "string") return part;
+  if (!part || typeof part !== "object") return "";
+  const type = typeof part.type === "string" ? part.type : "";
+  if (INTERNAL.test(type)) return "";
+  if (typeof part.text === "string") return part.text;
+  if (typeof part.refusal === "string") return part.refusal;
+  if (IMAGE.test(type) || part.image) return "[image]";
+  if (AUDIO.test(type) || part.audio) return "[audio]";
+  if (FILE.test(type) || part.document) return named("file", part.file?.filename ?? part.filename ?? part.title ?? part.document?.name);
+  const inline = part.inlineData ?? part.inline_data ?? part.fileData ?? part.file_data;
+  if (inline) return /^image\//.test(mime(inline)) ? "[image]" : /^audio\//.test(mime(inline)) ? "[audio]" : named("file", mime(inline));
+  const call = type === "tool_use" || type === "function_call" ? part : part.toolUse ?? part.functionCall;
+  if (call) return `[tool call ${call.name ?? "?"} ${args(call.input ?? call.args ?? call.arguments)}]`;
+  if (type === "tool_result" || type === "function_call_output") return messageText(part.content ?? part.output);
+  const result = part.toolResult ?? part.functionResponse;
+  if (result) return messageText(result.content ?? result.response);
+  if (type === "message" || (!type && "content" in part)) return messageText(part.content);
+  return type ? `[${type}]` : "";
+}
+
+function messageText(content) {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map(partText).filter(Boolean).join("\n");
+  if (typeof content === "object") return partText(content) || JSON.stringify(content);
+  return String(content);
+}
+
+module.exports = { messageText };

package/lib/proxy.mjs

@@ -28,6 +28,9 @@ const SECRET_SETTING = /KEY|TOKEN|SECRET|PASSWORD/i;
 const HOP = /^(?:host|connection|keep-alive|transfer-encoding|upgrade|te|trailer|proxy-.*|content-length|accept-encoding)$/i;
 const REPLY_HOP = /^(?:connection|keep-alive|transfer-encoding|content-length|content-encoding)$/i;
 
+// A tunnel names its host alone: of Amazon's and Google's, only their model services.
+const modelHost = (h) => (/amazonaws\.com$/i.test(h) ? /^bedrock/i.test(h) : /googleapis\.com$/i.test(h) ? /generativelanguage|aiplatform/i.test(h) : MODEL_HOST.test(h));
+
 // The person's words in a request, a form's fields as much as JSON's.
 const asked = (raw) => (/^[^=&\s]+=[^&]*(?:&[^=&\s]+=[^&]*)*$/.test(raw) ? [...new URLSearchParams(raw).values()].flatMap(tied.sentencesIn) : tied.sentencesIn(raw));
 // A request whose reply said something of its own, to words the person sent, with no model call begun
@@ -167,6 +170,23 @@ export async function openProxy({ file, rulesFile, target, modelPort: wantedMode
   };
   // An app that hangs up while it sends a call ends that call, never this command.
   const model = createServer((req, res) => { relay(req, res).catch(() => res.destroy()); });
+  // HTTPS_PROXY: the app's TLS goes through as a sealed tunnel, so an address written in its code is
+  // seen and a signed request (Bedrock's SigV4) reaches its provider byte for byte. What a sealed
+  // call said and spent is not known here, so it counts as seen and writes no meter row.
+  model.on("connect", (req, socket, head) => {
+    const at = /^([^\s:]+|\[[^\]]+\]):(\d{1,5})$/.exec(req.url || "");
+    if (!at) { socket.end("HTTP/1.1 400 Bad Request\r\n\r\n"); return; }
+    const host = at[1].replace(/^\[|\]$/g, "");
+    if (modelHost(host) && ++calls === 1) onSeen();
+    const up = connect({ host, port: Number(at[2]) }, () => {
+      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      if (head?.length) up.write(head);
+      socket.pipe(up).pipe(socket);
+    });
+    const end = () => { socket.destroy(); up.destroy(); };
+    up.on("error", () => { if (!socket.destroyed) socket.end("HTTP/1.1 502 Bad Gateway\r\n\r\n"); end(); });
+    socket.on("error", end);
+  });
 
   const frontPort = await listen(front);
   const modelPort = await listen(model, wantedModelPort);
@@ -181,6 +201,11 @@ export async function openProxy({ file, rulesFile, target, modelPort: wantedMode
     // The app's model settings, pointed here: each SDK's own, and any other of the app's that addresses a model.
     env(base) {
       const out = {};
+      // A proxy of the app's own stays; loopback is never tunnelled, so the settings above reach this proxy direct.
+      if (!base.HTTPS_PROXY && !base.https_proxy) {
+        out.HTTPS_PROXY = out.https_proxy = `http://127.0.0.1:${modelPort}`;
+        out.NO_PROXY = out.no_proxy = [base.NO_PROXY || base.no_proxy, "localhost,127.0.0.1,::1,host.docker.internal"].filter(Boolean).join(",");
+      }
       for (const [name, fallback] of Object.entries(DEFAULTS)) out[name] = via(base[name] || fallback);
       for (const [name, value] of Object.entries(base)) {
         if (name in out || SECRET_SETTING.test(name) || typeof value !== "string") continue;

package/lib/replay.mjs

@@ -363,7 +363,9 @@ function tally(totals, call, count) {
   t.completionTokens += count(call.completionTokens);
   // An answered call the provider sent no counts for: it was spent, and what it cost is not known.
   const status = count(call.status);
-  if (call.usage !== true && status > 0 && status < 400) t.unmetered += 1;
+  // Counted from its words (lib/wire.cjs estimateOf): priced, and said as an estimate.
+  if (call.estimated === true) t.estimated = (t.estimated ?? 0) + 1;
+  else if (call.usage !== true && status > 0 && status < 400) t.unmetered += 1;
   totals.set(key, t);
 }
 

package/lib/setup-live-text.mjs

@@ -0,0 +1,19 @@
+// What the waiting coding agent is handed when the person answers the setup card: the three steps,
+// in order, with nothing left to ask them. `origin`: the Cortad this command talks to where it is not
+// cortad.com, said on every step so each one reaches the same place.
+export function askedText({ messages, source }, spec, origin = null) {
+  const n = Number(messages).toLocaleString("en-US");
+  const npx = `${origin ? `CORTAD_ORIGIN=${origin} ` : ""}npx -y ${spec}`;
+  const run = (rest) => `${npx} intelligence${rest ? ` ${rest}` : ""}`;
+  const from = source
+    ? run(`history --from ${source} --messages ${messages}`)
+    : `the export described in the output of step 1, piped to ${run(`history --stdin --messages ${messages}`)}`;
+  return [
+    `The person asked Cortad, on the setup card, to read their users' newest ${n} messages. They have answered: do not ask them which source or how many.`,
+    `1. ${run("")}: it puts Cortad's keys in this folder's env. Skip the question it prints about history.`,
+    `2. ${from}`,
+    `3. ${run("")} again: it prints the change to make in this code. Make it on a new branch named cortad-intelligence, commit it, then run ${run("")} once more so the card sees the change. Show the person the diff; nothing live changes until they deploy.`,
+    `Then start ${npx} wait in the background again.`,
+    `next: ${run("")}`,
+  ].join("\n");
+}

package/lib/setup-live.mjs

@@ -0,0 +1,35 @@
+import { execFileSync } from "node:child_process";
+
+// What this folder tells the setup card in the browser: which history tool its env names, how far the
+// history send has got, and whether each code change is in the working tree yet. A report that does
+// not land changes nothing here, so it never fails the command it rides on.
+
+// Cortad in the backend: the SDK imported in the app's own code, not only installed.
+const SDK = String.raw`from ["']@cortad/sdk["']|require\(["']@cortad/sdk["']\)|from cortad import|^[[:space:]]*import cortad([^_[:alnum:]]|$)`;
+// Cortad's page script, where the app serves its pages.
+const TAG = String.raw`b\.cortad\.com/i/cortad\.js`;
+const NOT_CODE = [":(exclude)*package.json", ":(exclude)*lock*", ":(exclude)*requirements*.txt", ":(exclude)*pyproject.toml", ":(exclude).cortad"];
+
+const inTree = (root, pattern) => {
+  try {
+    execFileSync("git", ["-C", root, "grep", "-q", "-I", "-E", "--untracked", "-e", pattern, "--", ".", ...NOT_CODE], { stdio: "ignore", timeout: 15_000 });
+    return true;
+  } catch { return false; }
+};
+
+// Each change as the working tree holds it now, tracked or not yet committed; a folder that is not a
+// git checkout reads as neither.
+export const changesIn = (root) => ({ sdk: inTree(root, SDK), tag: inTree(root, TAG) });
+
+export async function report({ apiBase, token, fetchImpl = fetch }, body) {
+  if (!token) return false;
+  try {
+    const res = await fetchImpl(`${apiBase}/mcp/setup/live`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000),
+    });
+    return res.ok;
+  } catch { return false; }
+}

package/lib/start.mjs

@@ -219,3 +219,25 @@ export const SHOWN_COMMAND = 200;
 export const shownCommand = (cmd, mask = (text) => text) => (cmd == null ? cmd
   : mask(String(cmd)).replace(/\b([A-Za-z_][A-Za-z0-9_]*)=("[^"]*"|'[^']*'|\S+)/g, (whole, name, value) => (/^[\w.-]{1,24}$/.test(value) ? whole : `${name}=***`)).slice(0, SHOWN_COMMAND));
 
+// A container: the daemon runs the app, so nothing in this command's process family listens on its
+// port, and 127.0.0.1 inside it is the container itself.
+export const inContainer = (cmd = "") => /^\s*(?:sudo\s+)?(?:docker|podman)(?:-compose)?\b/.test(cmd);
+// The host ports a `docker run -p 3204:8080` publishes: where the app answers on this machine.
+export const publishedPorts = (cmd = "") => [...cmd.matchAll(/(?:^|\s)(?:-p|--publish)(?:\s+|=)(?:[\d.]+:)?(\d{2,5}):\d{2,5}\b/g)].map((m) => Number(m[1]));
+// The host ports a `docker compose up` publishes, read from the files it names with -f, else the ones
+// compose reads by default in `dir`: short syntax ("3000:3000", 127.0.0.1:8080:80) and long (published: 3000).
+const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"];
+export const composePorts = (cmd = "", dir = ".") => {
+  if (!/\bcompose\b/.test(cmd)) return [];
+  const named = [...cmd.matchAll(/(?:^|\s)(?:-f|--file)(?:\s+|=)(\S+)/g)].map((m) => m[1]);
+  const text = (named.length ? named : COMPOSE_FILES).map((f) => read(join(dir, f))).join("\n");
+  const short = [...text.matchAll(/^\s*-\s*["']?(?:[\d.]+:)?(\d{2,5}):\d{2,5}(?:\/tcp)?["']?\s*$/gm)];
+  const long = [...text.matchAll(/^\s*published:\s*["']?(\d{2,5})["']?\s*$/gm)];
+  return [...new Set([...short, ...long].map((m) => Number(m[1])))];
+};
+// The proxy's settings as a container reaches them: Docker Desktop, colima and OrbStack all route
+// host.docker.internal to this machine's loopback.
+export const forContainer = (env) => Object.fromEntries(Object.entries(env).map(([name, value]) => [name, value.replace("//127.0.0.1:", "//host.docker.internal:")]));
+// The settings a container command already hands through from this terminal (`-e NAME`, `--env NAME`):
+// those carry the proxy's address in with no change to the command.
+export const passedThrough = (cmd = "") => new Set([...cmd.matchAll(/(?:^|\s)(?:-e|--env)(?:\s+|=)([A-Za-z_][A-Za-z0-9_]*)(?=\s|$)/g)].map((m) => m[1]));

package/lib/text.mjs

@@ -264,7 +264,7 @@ function verifyLines(v) {
 
 export function nextCall(d) {
   if (!finished(d)) return `run_status ${d.jobId}`;
-  return d.kind === "verify" || d.findings > 0 ? "findings" : "status";
+  return d.kind === "verify" || d.status === "failed" || d.status === "canceled" ? "status" : `behavior ${d.jobId}`;
 }
 
 // One line to hand the person while a run plays: conversations done of the total, whose side any failed

package/lib/trace.cjs

@@ -744,7 +744,13 @@ if (FILE) {
         return compile.call(this, source, filename, ...rest);
       };
     }
-    if (TOOLS_FILE && typeof Module.registerHooks === "function") {
+    // Node 22 cannot run a sync load hook beside a loader's async one (tsx's `--import`): every ES
+    // module load throws "loadSync is not a function" and the app dies at start. Node 26 can. There,
+    // an ES module's tools go unwrapped and the sweep below says so in the app's log.
+    // ponytail: measured on 22 (fails) and 26 (works) only; 23 to 25 are treated as 22.
+    const asyncLoader = [...process.execArgv, ...(process.env.NODE_OPTIONS || "").split(/\s+/)].some((a) => /^--(?:import|(?:experimental-)?loader)\b/.test(a));
+    const mixes = Number(process.versions.node.split(".")[0]) >= 26;
+    if (TOOLS_FILE && typeof Module.registerHooks === "function" && (mixes || !asyncLoader)) {
       try {
         Module.registerHooks({
           load(url, context, nextLoad) {

package/lib/verbs.mjs

@@ -8,6 +8,8 @@ import { intelligence as setUp } from "./intelligence.mjs";
 import { reach as reachApp } from "./reach.mjs";
 import { fieldText, findingsText, finished, linesOf, notStartedText, refusedText, restartedText, runText, STARTING, startedText, statusText, testedLine, upWaitingText, waitingText } from "./text.mjs";
 import { incidentsText, intelligenceText, outcomesText, queryText } from "./intel-text.mjs";
+import { againstText, behaviorText, historyText, searchText } from "./behavior-text.mjs";
+import { askedText } from "./setup-live-text.mjs";
 
 // The ten things a coding agent may ask of Cortad, each a call to the API with this machine's key
 // and a rendering from lib/text.mjs; `reach` also sends to the app on this machine. The MCP tools
@@ -44,7 +46,7 @@ export const cappedAt = (n) => (Number.isSafeInteger(n) && n >= 1 ? { conversati
 // `spec` is the package the agent calls back, npx -y <spec>.
 // `appLog` is the file the connect command keeps the app's output in; its path is said here, on this
 // machine, beside a failure, and never sent.
-export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch, startApp, pending, root, writes = null, appLog = null, code = null, seen = () => {}, wasRead = () => false, spec = "cortad", now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch, startApp, pending, root, writes = null, appLog = null, code = null, seen = () => {}, wasRead = () => false, spec = "cortad", origin = null, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
   const call = async (method, path, body, timeoutMs = 30_000) => {
     const key = typeof token === "function" ? token() : token;
     if (!key) return { status: 0, ok: false, data: { error: NOT_CONNECTED } };
@@ -215,6 +217,11 @@ export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch,
     return [logSaid(appFailed(d)), back].filter(Boolean).reduce(withBack, runText(withTested(d, id)));
   };
 
+  const sinceConnect = (r) => {
+    const connected = Date.parse(runner()?.startedAt ?? "");
+    return !Number.isFinite(connected) || Date.parse(r.startedAt ?? "") >= connected;
+  };
+
   // `npx cortad wait`: returns when the next run or verify ends, started from the browser or by the
   // agent, with what it found. A coding agent starts it in the background and is woken when it exits; it is a shell
   // verb alone, since an MCP call is cut at about 60 seconds. A run playing when it starts is that run,
@@ -231,15 +238,23 @@ export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch,
       const res = id ? await call("GET", `/mcp/run/${encodeURIComponent(id)}?wait=${HOLD_S}`, undefined, (HOLD_S + 13) * 1000) : await call("GET", "/mcp/status?quiet=1");
       // A key that no longer opens this repository, or a run that is gone, does not come back by asking again.
       if ([401, 403, 404].includes(res.status)) return failed(res);
+      // The person answered the setup card: taken once, here, and handed to the agent this wakes.
+      if (res.ok && res.data?.setupAsk) {
+        const took = await call("POST", "/mcp/setup/live/take");
+        if (took.ok && took.data?.taken) return { text: askedText(took.data, spec, origin), data: took.data };
+        if (!took.ok) await sleep(WAIT_POLL_MS);
+        continue;
+      }
       if (res.ok && id && finished(res.data)) {
         const text = shown(res.data, id).replace(/\nnext: [^\n]*$/, "");
-        // A verify's verdict is read by run_status; a run's problems by findings.
-        return { text: `${text}\nnext: ${res.data.verify ? `run_status ${id}` : `findings ${res.data.jobId ?? id}`}`, data: res.data };
+        // A verify's verdict is read by run_status; how a run's users fared by behavior.
+        return { text: `${text}\nnext: ${res.data.verify ? `run_status ${id}` : `behavior ${res.data.jobId ?? id}`}`, data: res.data };
       }
       const r = res.ok && !id ? res.data?.run : null;
       // A verify is followed like a run: the agent that started it is woken at its end instead of
-      // polling run_status twelve times a round.
-      if (r?.jobId && (!finished(r) || !wasRead(r.jobId))) { id = r.jobId; continue; }
+      // polling run_status twelve times a round. A finished one nobody read is news only if it began
+      // under the connect command running now: one from before a restart is not the run the agent waits for.
+      if (r?.jobId && (!finished(r) || (!wasRead(r.jobId) && sinceConnect(r)))) { id = r.jobId; continue; }
       // A run being followed holds on the server; a failed call, or no run yet, is asked again later.
       if (!id || !res.ok) await sleep(WAIT_POLL_MS);
     }
@@ -336,7 +351,7 @@ export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch,
     if (res.ok && res.data?.joined) return { text: `A world is already being tested: ${res.data.jobId}.\nnext: world_status ${res.data.jobId}`, data: res.data };
     // What kind of test an ask gets is said only on an ask: a call that records the person's choice
     // of features, or allows a test account, starts nothing and is told nothing about worlds.
-    const why = res.ok ? (res.data?.unmatched ? "Nothing a world can plant is what that is about, so it is tested by a run: simulated users talk to the app on this machine." : "This app has no world, so it is tested by a run: simulated users talk to the app on this machine.") : "The world could not be asked, so it is tested by a run: simulated users talk to the app on this machine.";
+    const why = "This is tested by simulated users talking to the app on this machine.";
     const ran = await run({ conversations, features, account, asked: Boolean(ask) });
     return { ...ran, text: ask ? `${why}\n${ran.text}` : ran.text };
   };
@@ -372,6 +387,28 @@ export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch,
     return res.ok ? { text: `Subscribed. ${res.data.said}
 Secret, shown once: ${res.data.secret}`, data: res.data } : failed(res);
   };
+  // The people using the live app, for the agent: the map of tables, a ready answer, or its own ask.
+  // The answer is the server's JSON as it came, which an agent reads better than any table drawn here.
+  const users = async (body) => {
+    const res = await call("POST", "/mcp/users", body);
+    return res.ok ? { text: JSON.stringify(res.data), data: res.data } : failed(res);
+  };
+  // How the app behaved with its users at one point, one persona of it, two points against each
+  // other, or the log of every point (the server's agent-behavior/read.ts).
+  const behavior = async ({ at, persona, against, history } = {}) => {
+    const q = new URLSearchParams({ ...(at ? { at: String(at) } : {}), ...(persona ? { persona: String(persona) } : {}), ...(against ? { against: String(against) } : {}), ...(history ? { history: "1" } : {}) }).toString();
+    const res = await call("GET", `/mcp/behavior${q ? `?${q}` : ""}`);
+    if (!res.ok) { const out = failed(res); return { ...out, text: `${out.text}\nnext: behavior with history: true lists every point there is` }; }
+    const d = res.data;
+    return { text: d.history ? historyText(d) : d.against ? againstText(d) : behaviorText(d), data: d };
+  };
+  // Conversations found by what they mean, across simulations and production.
+  const search = async ({ query: asked, where, persona, limit } = {}) => {
+    if (typeof asked !== "string" || !asked.trim()) return { text: "Say what to look for: search with query, in words, such as \"students asking for a past exam paper\".\nnext: search", isError: true, code: "no_query" };
+    const body = { query: asked.trim().slice(0, 500), ...(where ? { where: String(where) } : {}), ...(persona ? { persona: String(persona).slice(0, 200) } : {}), ...(Number.isSafeInteger(limit) && limit >= 1 ? { limit: Math.min(limit, 50) } : {}) };
+    const res = await call("POST", "/mcp/search", body);
+    return res.ok ? { text: searchText(res.data, body.query), data: res.data } : failed(res);
+  };
   const query = async (ask) => {
     const res = await call("POST", "/mcp/query", ask);
     return res.ok ? { text: queryText(res.data), data: res.data } : { text: queryText(res.data ?? { error: res.text }), data: res.data };
@@ -398,7 +435,7 @@ Secret, shown once: ${res.data.secret}`, data: res.data } : failed(res);
   };
 
   // `post` and `changed` serve lib/cli.mjs; the MCP answers only the names in TOOLS.
-  return { status, reach, run, run_status: runStatus, wait, findings, verify, dispute, feedback, field_connect: fieldConnect, field, world, world_status: worldStatus, test, connect: fieldConnect, intelligence, incidents, outcomes, subscribe, query, post, changed };
+  return { status, reach, run, run_status: runStatus, wait, findings, verify, dispute, feedback, field_connect: fieldConnect, field, world, world_status: worldStatus, test, connect: fieldConnect, intelligence, incidents, outcomes, subscribe, query, users, behavior, search, post, changed };
 }
 
 const sizeOf = (path) => { try { return statSync(path).size; } catch { return 0; } };

package/lib/wire.cjs

@@ -5,6 +5,7 @@
 // and one recorder per process. Nothing here talks to a network.
 "use strict";
 const fs = require("node:fs");
+const { messageText } = require("./message-text.cjs");
 // Every value a trace row carries passes one mask, whichever path wrote it: a key inside a value
 // ("sk-...", a bearer token, a JWT) and what anyone wrote after "password is" or "token:". The
 // door row's sign-in headers are kept on purpose: the command replays them from this machine.
@@ -60,7 +61,7 @@ const partsOf = (text) => text.split(/\{[^}]*\}|\$\{[^}]*\}|%[sd]|<[^>]{1,40}>/)
 // the part cut off was graded as made up. A cut answer stands the passage questions down.
 const TOOL_TEXT = 12000, TOOLS_MAX = 12;
 const toolText = (name, full, extra = {}) => ({ name: String(name || "").slice(0, 80), text: full.slice(0, TOOL_TEXT), ...extra, ...(full.length > TOOL_TEXT ? { cut: true } : {}) });
-const textOf = (v) => (typeof v === "string" ? v : Array.isArray(v) ? v.map((p) => (p && typeof p === "object" ? (p.text || p.content || "") : String(p || ""))).filter(Boolean).join("\n") : v && typeof v === "object" ? JSON.stringify(v) : "");
+const textOf = messageText;
 // Only what came after the person's latest message belongs to this turn: a thread the app
 // resends whole carries every earlier turn's tool answers too.
 const list = (v) => (Array.isArray(v) ? v.filter((x) => x && typeof x === "object") : []);
@@ -653,6 +654,13 @@ const stoppedAtLimit = (e) => {
     || (e.type === "finish" && (e.finishReason === "length" || Boolean(e.finishReason && e.finishReason.unified === "length")));
 };
 const reasoningOf = (u) => n((u.output_tokens_details && u.output_tokens_details.reasoning_tokens) || (u.completion_tokens_details && u.completion_tokens_details.reasoning_tokens) || u.thoughtsTokenCount || (u.outputTokens && u.outputTokens.reasoning));
+// An answered reply the provider sent no counts for (Anthropic's OpenAI compatible stream sends
+// none) is counted from its text at four characters a token, the request whole as it was sent,
+// and marked estimated: a run cap and a price that counted nothing let any spend through.
+const CHARS_PER_TOKEN = 4;
+const estimateOf = (sent, events, status) => (status >= 200 && status < 400
+  ? { promptTokens: Math.ceil(String(sent || "").length / CHARS_PER_TOKEN), cachedTokens: 0, completionTokens: Math.ceil(replyText(events).length / CHARS_PER_TOKEN), estimated: true }
+  : { promptTokens: 0, cachedTokens: 0, completionTokens: 0 });
 // The output cap the app's request set, in each provider's field.
 const capOf = (b) => (b && typeof b === "object" ? n(b.max_tokens) || n(b.max_completion_tokens) || n(b.max_output_tokens) || n(b.maxOutputTokens) || n(b.generationConfig && b.generationConfig.maxOutputTokens) || n(b.inferenceConfig && b.inferenceConfig.maxTokens) || null : null);
 // A stream spreads its counts over events (Anthropic's input in the first, output in the last);
@@ -896,7 +904,7 @@ function makeRecorder({ row, rulesFile, onTurn = () => {}, onEnded = () => {} })
         }
         settle(ctx);
       }
-      row({ call: { at: Date.now(), ms: Date.now() - t0, host: String(host).replace(/:443$/, ""), model: String(askedFor(path, sent) || reply.model || "").slice(0, 160), ...answeredBy(askedFor(path, sent), reply.model), status, ...(reply.tokens || { promptTokens: 0, cachedTokens: 0, completionTokens: 0 }), usage: Boolean(reply.tokens), ...(EMBEDDING.test(path) ? { embedding: true } : {}), ...(ctx ? { ex: ctx.id } : {}), ...(ctx && (ctx.kept || ctx.turn) ? { reply: replyText(reply.events).slice(0, MODEL_WORDS) } : {}), ...(turn ? { turn } : {}), ...(rules ? { rules } : {}), ...(tools ? { tools } : {}), ...(called ? { called } : {}), ...(passages ? { passages } : {}), ...(caller ? { caller } : {}), ...(reply.limit ? { limit: { cap: capOf(asked), reasoning: reply.reasoning } } : {}), ...told } });
+      row({ call: { at: Date.now(), ms: Date.now() - t0, host: String(host).replace(/:443$/, ""), model: String(askedFor(path, sent) || reply.model || "").slice(0, 160), ...answeredBy(askedFor(path, sent), reply.model), status, ...(reply.tokens || estimateOf(sent, reply.events, status)), usage: Boolean(reply.tokens), ...(EMBEDDING.test(path) ? { embedding: true } : {}), ...(ctx ? { ex: ctx.id } : {}), ...(ctx && (ctx.kept || ctx.turn) ? { reply: replyText(reply.events).slice(0, MODEL_WORDS) } : {}), ...(turn ? { turn } : {}), ...(rules ? { rules } : {}), ...(tools ? { tools } : {}), ...(called ? { called } : {}), ...(passages ? { passages } : {}), ...(caller ? { caller } : {}), ...(reply.limit ? { limit: { cap: capOf(asked), reasoning: reply.reasoning } } : {}), ...told } });
     } catch { /* the command is gone */ }
   };
   return { tied, requestCtx, note, ended, meter };

package/local.mjs

@@ -38,7 +38,7 @@ import { finished, unseenText } from "./lib/text.mjs";
 import { lockHolds, makeLock } from "./lib/lock.mjs";
 import { AS_HEADER, CAPTURED, makeCapture } from "./lib/replay.mjs";
 import { sampleHere } from "./lib/sample.mjs";
-import { hookable, shownCommand, startPlan, workspaces } from "./lib/start.mjs";
+import { composePorts, forContainer, hookable, inContainer, passedThrough, publishedPorts, shownCommand, startPlan, workspaces } from "./lib/start.mjs";
 import { openProxy } from "./lib/proxy.mjs";
 import { liftedLimits } from "./lib/switches.mjs";
 import { downLine, makeHealth } from "./lib/health.mjs";
@@ -49,8 +49,13 @@ import { clientOriginOf, envOf, keysFromEnv } from "./lib/origins.mjs";
 import { forgetSignIn, keptSignIn, mintJwt, rememberSignIn, signUpAndIn, testAccount } from "./lib/sign-in.mjs";
 import { clientRequestOf } from "./lib/browser-rung.mjs";
 import { layerOf, layerSaid } from "./lib/layer.mjs";
+import { sourcesIn } from "./lib/history/sources.mjs";
+import { report as reportLive } from "./lib/setup-live.mjs";
 import { grpcCall } from "./lib/grpc.mjs";
 
+// A count with its noun agreeing: 1 prompt, 3 prompts.
+const counted = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`;
+
 const argv = process.argv.slice(2);
 // The two faces a coding agent uses after the first connect (lib/cli.mjs): the MCP server the
 // client starts on every session, and the same verbs as shell commands. Neither runs the connect
@@ -106,14 +111,16 @@ if (!trusted) fail(`refusing: ${origin.host} is not Cortad.`);
 const api = `${origin.origin}/api`;
 
 const root = process.cwd();
-const MANIFEST = ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "docker-compose.yml", "docker-compose.yaml", "Gemfile", "mix.exs"];
+const MANIFEST = ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "docker-compose.yml", "docker-compose.yaml", "Gemfile", "mix.exs", "pom.xml", "build.gradle", "build.gradle.kts", "composer.json", "Dockerfile"];
+// A .NET project is named for itself: Support.csproj, Shop.sln.
+const dotnetHere = () => { try { return readdirSync(root).some((f) => /\.(?:csproj|fsproj|sln)$/.test(f)); } catch { return false; } };
 // A repository whose root carries no manifest of its own is still a repository: crewai-examples
 // keeps one project per folder under crews/, and the whole of it was refused at the door. The root
 // is accepted when a project lives below it, and whenever the person says how the app starts or
 // where it answers: a single file with no manifest is an app too, and nothing here needs the manifest.
 const startSaid = argv.includes("--") || argv.includes("--start") || argv.includes("--port") || argv.includes("--token");
-if (!startSaid && !MANIFEST.some((f) => existsSync(join(root, f))) && !workspaces(root).length) {
-  fail(`no project here: this folder has no package.json or pyproject.toml, and neither does any folder in it. Run it from your repository's root, or say how your app starts: npx cortad <code> -- <your start command>`);
+if (!startSaid && !MANIFEST.some((f) => existsSync(join(root, f))) && !dotnetHere() && !workspaces(root).length) {
+  fail(`no project here: this folder has no project file (package.json, pyproject.toml, go.mod, pom.xml, Gemfile, composer.json, Cargo.toml, a .csproj), and neither does any folder in it. Run it from your repository's root, or say how your app starts: npx cortad <code> -- <your start command>`);
 }
 // Which project this is, as a hash of where it lives: the same folder coming back resumes the same
 // connection, and the path itself never leaves this machine.
@@ -682,7 +689,7 @@ async function startApp() {
   if (up.port) {
     keepStart({ cmd: typed, ...(wantedPort ? { port: wantedPort } : {}) });
     // A container never saw the proxy's settings: the one line that makes its model calls visible is said here.
-    if (proxy && IN_CONTAINER.test(typed)) say(containerLine());
+    if (proxy && inContainer(typed)) sayIf(containerLine());
     return { port: up.port, cmd: launched.cmd, lifted: raised };
   }
   if (up.tail) console.error(up.tail);
@@ -742,22 +749,26 @@ async function useProxy() {
   keepStart({ modelPort: proxy.modelPort });
   say("your app's model calls are seen through a local proxy on this machine, so the line of code that made each call is not known. During a run, its calls to other services go out as they would for a real customer: a conversation that books, charges or emails does it for real");
 }
+const sayIf = (line) => { if (line) say(line); };
 // An app run in a container: the proxy's settings never reach it, and 127.0.0.1 inside it is not this machine.
 const containerLine = () => {
   // Only the settings the app's own environment names, else the OpenAI one: every SDK's would be a list nobody reads.
   const hints = modelHints();
   const handed = proxy.env(hints);
   const named = Object.keys(handed).filter((name) => name in hints);
-  const settings = (named.length ? named : ["OPENAI_BASE_URL"]).map((name) => `${name}=${handed[name].replace("127.0.0.1", "host.docker.internal")}`);
+  const passed = passedThrough(launched?.cmd);
+  // A setting the command already hands the container from this terminal arrives on the proxy as it is.
+  const missing = (named.length ? named : ["OPENAI_BASE_URL"]).filter((name) => !passed.has(name));
+  if (!missing.length) return "";
+  const settings = missing.map((name) => `${name}=${forContainer(handed)[name]}`);
   return `your app runs in a container, where Cortad's hook cannot load: its replies are seen through the proxy, its model calls are not. To see them, give the container ${settings.length === 1 ? "this setting" : "these settings"} and start it again with this command (the same port on every connect of this folder): ${settings.join(", ")}`;
 };
-const IN_CONTAINER = /^\s*(?:sudo\s+)?(?:docker|podman)(?:-compose)?\b/;
 // The app answered, and the hook is not in it: it is started again with its model settings on the
 // proxy. One in a container would come back the same, so it is left up, seen at the front alone.
 async function startProxied(up, waitMs) {
   await useProxy();
-  if (IN_CONTAINER.test(launched?.cmd ?? "")) {
-    say(containerLine());
+  if (inContainer(launched?.cmd)) {
+    sayIf(containerLine());
     return up;
   }
   await stopTree(child.pid);
@@ -780,7 +791,7 @@ async function start(waitMs) {
   // for the session, and the hook. No env file is read into it: its own loader reads its own files, in
   // its own order, which is the only way a test file's placeholder key never outranks the real one.
   const base = { ...process.env, ...lifted };
-  child = spawnTied(cmd, { cwd: appDir, env: { ...base, ...(proxy ? proxy.env(modelHints()) : capture.env(base)), FORCE_COLOR: "0" } });
+  child = spawnTied(cmd, { cwd: appDir, env: { ...base, ...(proxy ? (inContainer(cmd) ? forContainer(proxy.env(modelHints())) : proxy.env(modelHints())) : capture.env(base)), FORCE_COLOR: "0" } });
   const mine = child;
   become("starting", { app: mine.pid ?? null });
   let seen = "";
@@ -821,7 +832,7 @@ async function start(waitMs) {
     // A container publishes its port through the daemon, so nothing in this command's own process
     // family listens on it and `ports` stays empty however long the wait runs. What the container
     // said is then the only evidence there is, and `answers` still has to agree before it is used.
-    const alsoSaid = IN_CONTAINER.test(cmdText) ? said : [];
+    const alsoSaid = inContainer(cmdText) ? [...publishedPorts(cmdText), ...composePorts(cmdText, appDir), ...said] : [];
     for (const port of [...new Set([...(wantedPort ? [wantedPort] : []), ...said.filter((p) => ports.includes(p)), ...ports, ...alsoSaid])]) {
       if (await answers(port)) {
         note.answered = true;
@@ -1047,7 +1058,7 @@ if (attach.data.upload === "layer") {
   const sentList = join(homeOf(project), "sent.json");
   try { mkdirSync(homeOf(project), { recursive: true, mode: 0o700 }); writeFileSync(sentList, JSON.stringify({ ...said, files: chosen.files.map((f) => ({ path: f, why: chosen.why.get(f) })), leftOut: chosen.dropped ?? [] }, null, 1), { mode: 0o600 }); } catch { /* the list is for reading; the send does not depend on it */ }
   const left = said.leftOut.files ? ` ${said.leftOut.files} large data and test files were left out to keep the upload under 16 MB; they are named in the list.` : "";
-  say(`sending the part of this code that is its AI, so simulated users can be written for it: ${said.prompts} prompts, ${said.modelCalls} model calls, ${said.evals} eval files, the routes that reach the model and the shapes they read. ${layer.set.size} of ${candidates.length} files; the list is at ${sentList}.${left} The rest of this folder is not sent.`);
+  say(`sending the part of this code that is its AI, so simulated users can be written for it: ${counted(said.prompts, 'prompt')}, ${counted(said.modelCalls, 'model call')}, ${counted(said.evals, 'eval file')}, the routes that reach the model and the shapes they read. ${layer.set.size} of ${candidates.length} files; the list is at ${sentList}.${left} The rest of this folder is not sent.`);
 } else {
   say(`sending this folder's code as this project has before: ${files.length} files, env files and keys left out.`);
 }
@@ -1121,6 +1132,12 @@ if (!sent.ok && sent.status !== 401 && sent.status !== 404) {
   sent = await sendTree();
 }
 if (!sent.ok) sent.err ? unreachable(sent.err) : fail(sent.data?.error ?? `upload failed (${sent.status})`);
+// Which history tool this folder's env names, by name only, so the setup card can say where its users'
+// messages will come from before the person is asked how many.
+{
+  const found = sourcesIn({ ...envOf(root), ...process.env }).map((s) => s.id);
+  if (found.length) void reportLive({ apiBase: api, token: readToken(project) }, { found });
+}
 // Their commit history follows the code: the commits newer than the ones Cortad holds, the whole
 // history the first time, each diff cut to the files above and to lines that carry no key
 // (lib/commits.mjs). It goes on after the connect is reported and never stops it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortad/connector",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Connects the AI app on your machine to Cortad for test conversations, and gives your coding agent the MCP and skill to run them.",
   "bin": {
     "cortad": "local.mjs"
@@ -9,6 +9,7 @@
   "files": [
     "README.md",
     "lib/app-port.mjs",
+    "lib/behavior-text.mjs",
     "lib/auto-reach.mjs",
     "lib/browser-rung.mjs",
     "lib/calls.mjs",
@@ -47,6 +48,8 @@
     "lib/replay.mjs",
     "lib/runner.mjs",
     "lib/sample.mjs",
+    "lib/setup-live.mjs",
+    "lib/setup-live-text.mjs",
     "lib/sign-in.mjs",
     "lib/spec.mjs",
     "lib/start-cause.mjs",
@@ -59,6 +62,7 @@
     "lib/trace.cjs",
     "lib/verbs.mjs",
     "lib/wire.cjs",
+    "lib/message-text.cjs",
     "lib/words.mjs",
     "lib/writes.mjs",
     "local.mjs",
@@ -72,6 +76,7 @@
     "lib/redact.mjs",
     "lib/history/contract.mjs",
     "lib/history/send.mjs",
+    "lib/history/sources.mjs",
     "lib/history/langfuse.mjs",
     "lib/intelligence-pair.mjs",
     "lib/history/langsmith.mjs",