cortad 0.3.1-rc.8 → 0.3.1

package/lib/contact-text.mjs

@@ -0,0 +1,167 @@
+import { at, clip, has, num, plural } from "./words.mjs";
+
+// What `status` says between connect and a run: each endpoint a real request proved, with what the
+// hook saw inside those requests; each endpoint the read found that no request has reached; what a
+// run on the proven ones would be, and what it would write into. Every figure is one the agent can
+// check against its own request or a line of the code. A field the API leaves out prints nothing.
+
+const CARRIER = {
+  body: (k) => `the body field "${k}"`,
+  cookie: (k) => `the cookie "${k}"`,
+  header: (k) => `the header "${k}"`,
+  path: (k) => `the path segment {${k}}`,
+  history: (k) => `the earlier messages the client sends in "${k}"`,
+};
+const where = (x) => (x?.file || x?.path ? `${at(x.file ?? x.path, x.line)}: ` : "");
+const TIED = { sent: "the first request sent", got: "the first request got back" };
+
+// A door whose answer came on a second request: that request, what tied the two, and what the client
+// sent first in each turn, each as the agent's own requests showed it.
+function secondStepLine(s) {
+  if (!s?.request) return null;
+  const tie = s.tie?.key && TIED[s.tie.from] ? `, tied by the "${s.tie.key}" ${TIED[s.tie.from]}` : "";
+  const before = s.before?.length ? `; each turn first sent ${s.before.join(", ")}` : "";
+  return `The answer came on a second request, ${s.request}${tie}${before}.`;
+}
+
+function sessionLine(v) {
+  const s = v.session;
+  if (!s || !(v.requests > 1)) return null;
+  if (!s.held) return "No later request's prompt carried an earlier one.";
+  const by = CARRIER[s.carrier] && s.key ? CARRIER[s.carrier](s.key) : "nothing the request sent, so every caller shares what the app keeps";
+  return `A later request's prompt carried an earlier one, tied by ${by}.`;
+}
+
+// A prompt with none of the rules is said with the file its call is made from, and whether Cortad
+// read any rule there: "carried none" could not tell a gap in Cortad's read from one in the app.
+// `inFile`, the rules read from that file, is said when the server sends it.
+function rulesLine(r) {
+  if (!r || !has(r.of) || r.of === 0) return null;
+  if (!r.carried && r.at?.path && r.readThere === false) return `None of the ${plural(r.of, "rule")} Cortad read from your code are in the prompt this endpoint sent, and Cortad read no rule from ${r.at.path}, where the call is made; the prompt at ${at(r.at.path, r.at.line)} shows whether Cortad's read missed rules written there or your app sends this prompt without any.`;
+  if (!r.carried && r.at?.path && r.readThere === true) return `The prompt this endpoint sent from ${at(r.at.path, r.at.line)} holds none of the ${has(r.inFile) ? `${plural(r.inFile, "rule")} ` : "rules "}Cortad read from that file.`;
+  // A server from before `at` and `readThere` keeps its own words.
+  const reader = "at" in r || "readThere" in r ? "Cortad read" : "read";
+  const head = `The prompts carried ${r.carried ? num(r.carried) : "none"} of the ${plural(r.of, "rule")} ${reader} from your code`;
+  const example = (r.examples ?? [])[0];
+  return `${head}${example ? `, for example ${at(example.path, example.line)} "${clip(example.text, 160)}"` : ""}.`;
+}
+
+// Whose it is, as a sentence of its own: "Run waits, on the app's side:" read as a fault of the app's.
+const WHOSE = { ours: "That is on Cortad's side, not your app's.", theirs: "That is in your app." };
+// A door runs do not use yet, or one only Cortad's requests reached, and why.
+function standingLine(v) {
+  if (v.standing === "excluded") return `Runs leave this endpoint out: ${v.why}${WHOSE[v.side] ? ` ${WHOSE[v.side]}` : ""}`;
+  if (v.standing === "fallback") return `Answered only Cortad's own requests: ${v.why}`;
+  return null;
+}
+
+// Who the conversations through a signed-in endpoint act as: the customers the agent's requests signed in as.
+const accountsLine = (n) => (!has(n) ? null : n > 1 ? `Conversations are split across ${num(n)} accounts, one for each customer your requests signed in as.` : "All conversations act as one account.");
+
+// Where a trial takes each value the app's own client sets for its model.
+const appFieldLine = (f) => (f.from === "app" ? `"${f.field}" is set by your app${f.path ? ` at ${f.path}` : ""}.` : `"${f.field}" is only in your agent's request.`);
+
+// The message Cortad took from the last request, so a wrong field shows; the reply is the agent's
+// own, already read, and ten of them were the longest part of ulaim's status. One with no message
+// found keeps a short reply to know it by.
+function sampleLine(s) {
+  if (!s?.reply) return null;
+  const cut = s.cut ? "; the reply stopped before it finished" : "";
+  return s.ask ? `Last message: "${clip(s.ask, 160)}"${cut}.` : `Last reply: "${clip(s.reply, 80)}"${cut}.`;
+}
+
+function doorLines(v) {
+  const reached = `${plural(v.requests, "request")} reached ${v.model ?? "the model"}`;
+  const calls = has(v.modelCallsPerRequest) ? `, ${plural(v.modelCallsPerRequest, "model call")} each` : "";
+  const seconds = has(v.replySeconds) ? `, ${v.replySeconds} seconds a reply` : "";
+  const lines = [`  ${v.door}: ${reached}${calls}${seconds}.`];
+  const inner = [
+    standingLine(v),
+    v.askField ? `The message goes in "${v.askField}".` : null,
+    ...(v.appFields ?? []).map(appFieldLine),
+    secondStepLine(v.secondStep),
+    v.later ? "Your app takes the message at once and its model answers afterwards; Cortad grades the model's last answer to each message." : null,
+    sessionLine(v),
+    accountsLine(v.accounts),
+    ...(v.checks ?? []).map((said) => `Cortad's test conversation here: ${said}`),
+    rulesLine(v.rules),
+    v.tools?.length ? `Tools that ran: ${v.tools.join(", ")}.` : null,
+    v.passages ? `Passages handed to the model: ${num(v.passages)}.` : null,
+    ...(v.problems ?? []).map((p) => `Problem${where(p) ? ` at ${where(p)}` : ": "}${p.said}`),
+    sampleLine(v.sample),
+  ];
+  return [...lines, ...inner.filter(Boolean).map((l) => `    ${l}`)];
+}
+
+// What a run would play, take and cost, said to the person: the conversations it starts with (of
+// those planned, the ones that fit in one run's time), the follow-ups apart, the time at the widest it
+// goes and what it costs on their own keys, or that no price could be read. "Written" was said of
+// conversations the run writes as it starts: "44 of the 79 trials written" beside "Trials: 39 written".
+function readyLine(r) {
+  if (!r || !r.trials) return null;
+  const soFar = r.reading ? " so far" : "";
+  const plays = has(r.planned) && r.planned > r.trials ? `${num(r.trials)} of the ${plural(r.planned, "conversation")} planned${soFar}, as many as fit in one run's time` : `${plural(r.trials, "conversation")}${soFar}`;
+  // Follow-ups are played only where something breaks: said apart, never in the count above.
+  const followUps = r.followUps ? `, and up to ${num(r.followUps)} more where something breaks` : "";
+  // The run widens only while replies keep pace, and a one-at-a-time app holds it to one: the time is
+  // a range when that is slower, and where fewer conversations fit at that pace, how many is said.
+  const upTo = has(r.atOne?.minutes) && r.atOne.minutes > r.minutes ? r.atOne.minutes : null;
+  const atOne = has(r.atOne?.trials) && r.atOne.trials < r.trials ? ` If your app answers one request at a time, about ${num(r.atOne.trials)} of them fit in that time.` : "";
+  const minutes = has(r.minutes) && `in about ${upTo ? `${num(r.minutes)} to ${plural(upTo, "minute")}` : plural(r.minutes, "minute")}`;
+  const size = [has(r.replies) && `about ${plural(r.replies, "reply", "replies")}`, minutes].filter(Boolean).join(" ");
+  const usd = (x) => `$${x.toFixed(2)}`;
+  // Some endpoints had no published rate or token counts: the price covers the others and says so.
+  // A first run is priced at what it is expected to cost (`expected`, from factors measured on recorded
+  // first runs) and the most it costs (`upTo`); a server from before `expected` sends the most alone.
+  // After a run of the app's own, as what that run measured. An older server sends a range (`usdHigh`).
+  // Where some endpoints had no price, on how many.
+  const amount = () => `${r.upTo ? "up to" : "about"} ${usd(r.usd)}${has(r.usdHigh) ? ` to ${usd(r.usdHigh)}` : ""}`;
+  const some = r.pricedOn ? `, on the ${num(r.pricedOn.endpoints)} of ${plural(r.pricedOn.of, "endpoint")} Cortad could price` : "";
+  const onKey = `on your ${r.provider ? `${r.provider} ` : ""}key${r.model ? ` for ${r.model}` : ""}`;
+  const both = r.upTo && has(r.expected);
+  // No price is said, as the card says it (guide.ts quoteLine), never left out.
+  const cost = has(r.usd)
+    ? ` ${both ? `It is expected to cost ${usd(r.expected)}${soFar} ${onKey}, and the most it costs is ${usd(r.usd)}` : `It costs ${amount()}${soFar} ${onKey}`}${some}${r.estimated ? ", estimated from the length of the text since your provider sent no token counts" : ""}.`
+    : " It runs on your app's own model keys; Cortad could not price it from what your app's model calls reported.";
+  // No rules is a fact of a finished read: said while the code is still being read, it was false a minute later.
+  const rules = !has(r.rules) || (r.reading && r.rules === 0) ? "" : r.rules === 0 ? " No rules of your own were read from the code, so replies are checked against general standards only." : ` Every reply is checked against the ${plural(r.rules, "rule")} read from your code.`;
+  return `For the person: a run plays ${plays}${followUps}${size ? `: ${size}` : ""}.${atOne}${cost}${rules}${r.reading ? " Your code is still being read; the run waits for it and plays every conversation it adds." : ""}`;
+}
+
+// The endpoints no request has reached, as status lists them and reach sends them. `receipts`: doors
+// the App section says answered at once with their answer out of Cortad's sight, so not said here.
+export const unreached = (c, receipts = []) => {
+  const answered = new Set(receipts.map((x) => x.door));
+  return (c?.notCalled ?? []).filter((m) => !answered.has(`${m.method} ${m.path}`));
+};
+
+// One the server has no request for, or one listed on a field's name alone, is the agent's to send.
+// `signIn` and `failed`: what Cortad's own test request met there, said as the server words it.
+function unreachedLine(m) {
+  const said = [m.excluded, m.signIn && `${m.signIn}.`, m.failed, !m.excluded && (m.unsure || m.byHand) ? "By hand." : "", m.byHand, m.why].filter(Boolean).join(" ");
+  return `  ${m.method} ${m.path}${m.file ? `  ${at(m.file, m.line)}` : ""}${said ? `  ${said}` : ""}`;
+}
+
+// Cortad sends the rest itself, said only where the server has a request ready for one of them.
+function reachLine(missing) {
+  if (!missing.some((m) => m.request && !m.unsure)) return null;
+  const except = [missing.some((m) => m.unsure || m.byHand) && "marked by hand", missing.some((m) => m.excluded) && "left out of runs"].filter(Boolean);
+  return `Cortad sends each of them a test request${except.length ? `, except any ${except.join(" or ")}` : ""}.`;
+}
+
+// `data`: what the command did with the app's stores and services, said right under the run it is
+// about, so what a run writes into for real is read before Run is pressed.
+export function contactLines(c, data = [], receipts = []) {
+  const said = data.map((s) => `Data: ${s}`);
+  if (!c) return said;
+  const proven = c.proven ?? [];
+  // No request yet is said by the App line and by the next step, not a third time here.
+  const lines = proven.length ? [`Endpoints that answered (${num(proven.length)}):`, ...proven.flatMap(doorLines)] : [];
+  const missing = unreached(c, receipts);
+  if (missing.length) lines.push(`Endpoints found in your code that have not answered yet (${num(missing.length)}):`, ...missing.map(unreachedLine), ...[reachLine(missing)].filter(Boolean));
+  const ready = readyLine(c.ready);
+  if (ready) lines.push(ready);
+  // What holds Run is the server's next line (src/local/contact.ts heldLine), said once: printed here
+  // as well, ulaim's hold on its Qdrant was read twice in one status.
+  return [...lines, ...said];
+}

package/lib/data.mjs

@@ -2,24 +2,21 @@
 // records by the hundred; written into the file your app keeps its real data in, they stay there
 // after the run. So an app started here runs against a copy of its database file, made in this
 // command's own temp folder and pointed at through the same variable, and the original is never
-// opened. What cannot be copied (a database server, a file your code names with no variable in
-// front of it, an app that was already running) is said before the first run, in one sentence.
+// opened. What cannot be copied (a file your code names with no variable in front of it, an app that
+// was already running) is said before the first run, in one sentence. A database server is copied
+// on its own server (lib/stores.mjs).
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { storesOf } from "./stores.mjs";
 
 const FILE_DB = /\.(?:db|sqlite3?|duckdb)$/i;
 // sqlite:///x.db (SQLAlchemy, relative), sqlite:////abs/x.db, sqlite+aiosqlite:///x.db, file:./dev.db (Prisma, libsql).
 const FILE_URL = /^(sqlite(?:\+\w+)?:\/\/\/|file:(?:\/\/(?=\/))?)([^?]*)(\?.*)?$/i;
-const SERVER_URL = /^(postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|mssql|sqlserver|cockroachdb)(?:\+\w+)?:\/\//i;
-const ENGINE = { postgres: "Postgres", postgresql: "Postgres", cockroachdb: "CockroachDB", mysql: "MySQL", mariadb: "MariaDB", mongodb: "MongoDB", "mongodb+srv": "MongoDB", mssql: "SQL Server", sqlserver: "SQL Server" };
 
-// What one value names: a database file (with how to write the value again for another path), a
-// database server, or nothing.
+// What one value names: a database file, with how to write the value again for another path, or nothing.
 export function databaseOf(value) {
   const v = String(value ?? "").trim();
   if (!v) return null;
-  const server = SERVER_URL.exec(v);
-  if (server) return { server: ENGINE[server[1].toLowerCase()] ?? server[1] };
   const url = FILE_URL.exec(v);
   if (url) {
     const path = decodeURIComponent(url[2]);
@@ -56,7 +53,7 @@ const sizeOf = (dir, cap) => {
 const DEFAULTED = /(?:os\.(?:environ\.get|getenv)|\bgetenv)\(\s*['"]([A-Za-z_]\w*)['"]\s*,\s*['"]([^'"\n]+)['"]|process\.env(?:\.([A-Za-z_]\w*)|\[\s*['"]([A-Za-z_]\w*)['"]\s*\])\s*(?:\?\?|\|\|)\s*['"]([^'"\n]+)['"]/g;
 // A database file opened by a path written in the code, with no variable in front of it.
 const OPENED = /(?:sqlite3\.connect|aiosqlite\.connect|duckdb\.connect|new\s+(?:sqlite3\.)?Database|create_(?:async_)?engine)\(\s*['"]([^'"\n]+)['"]/g;
-const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|php)$/;
+export const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|php)$/;
 // A test opens its own scratch file; that is not where the app keeps its data.
 export const TEST = /(?:^|\/)(?:tests?|__tests__|spec|e2e|fixtures?)\/|[._-](?:test|spec)\.[^/]+$|(?:^|\/)(?:test_[^/]+|conftest)\.py$/;
 // A folder bigger than this is not copied: said instead, so the person decides.
@@ -72,7 +69,7 @@ function scan(sources) {
     for (const m of text.matchAll(DEFAULTED)) {
       const name = m[1] ?? m[3] ?? m[4];
       const value = m[2] ?? m[5];
-      if (name && !(name in defaults) && databaseOf(value)) defaults[name] = value;
+      if (name && !(name in defaults) && (databaseOf(value) || storesOf({ [name]: value }).length)) defaults[name] = value;
     }
     for (const m of text.matchAll(OPENED)) { const db = databaseOf(m[1]); if (db?.path) opened.push({ file, path: db.path }); }
   }
@@ -90,7 +87,8 @@ function located(db, dirs, appDir) {
 }
 
 // values: the environment the app will start with, names to values. from: the env file each name
-// was read from, when there is one. Returns the variables to start the app with, and what to say.
+// was read from, when there is one. Returns the variables to start the app with, what to say, and
+// the settings with the code's own defaults beside them, which the stores are read from.
 export function keepData({ values, from = {}, appDir, root = appDir, work, sources = [], started = true }) {
   const { defaults, opened } = scan(sources);
   const all = { ...defaults, ...values };
@@ -104,24 +102,20 @@ export function keepData({ values, from = {}, appDir, root = appDir, work, sourc
     const folder = db ? null : dataFolder(name, value, from[name] ? [dirname(from[name])] : [], appDir, root);
     if (folder) {
       moved.add(folder);
-      if (!started) { said.push(`Your app was already running when this command started, so it writes to its own data folder, ${rel(folder)}/: trials write into it. Stop your app and run the command again to run against a copy.`); continue; }
-      if (sizeOf(folder, FOLDER_CAP) > FOLDER_CAP) { said.push(`Your data folder ${rel(folder)}/ (${name}) is over 1 GB, so it is not copied: trials write into it.`); continue; }
+      if (!started) { said.push(`Your app was already running when this command started, so it writes to its own data folder, ${rel(folder)}/: test conversations write into it. Stop your app and run the command again to run against a copy.`); continue; }
+      if (sizeOf(folder, FOLDER_CAP) > FOLDER_CAP) { said.push(`Your data folder ${rel(folder)}/ (${name}) is over 1 GB, so it is not copied: test conversations write into it.`); continue; }
       const to = join(work, "data", String(copied.length), basename(folder));
       cpSync(folder, to, { recursive: true });
       env[name] = to;
       copied.push({ name, from: folder, to });
-      said.push(`Your app runs against a copy of its data folder ${rel(folder)}/, through ${name}; the original is not touched.`);
+      said.push(`Your app runs against a copy of its data folder ${rel(folder)}/, through ${name}; the original is not touched, and the copy is deleted when this command ends and made again from the original at the next connect.`);
       continue;
     }
     if (!db) continue;
-    if (db.server) {
-      said.push(`Trials write into the ${db.server} database ${name} names: a database server cannot be copied here, so what a run creates stays in it. Point ${name} at a scratch database before a run if that one holds real data.`);
-      continue;
-    }
     const original = located(db, from[name] ? [dirname(from[name])] : [], appDir);
     moved.add(original);
     if (!started) {
-      said.push(`Your app was already running when this command started, so it writes to its own database, ${rel(original)}: trials write into it. Stop your app and run the command again to run against a copy.`);
+      said.push(`Your app was already running when this command started, so it writes to its own database, ${rel(original)}: test conversations write into it. Stop your app and run the command again to run against a copy.`);
       continue;
     }
     const to = join(work, "data", String(copied.length), basename(original));
@@ -130,14 +124,14 @@ export function keepData({ values, from = {}, appDir, root = appDir, work, sourc
     if (existsSync(original)) for (const tail of ["", "-wal", "-shm", "-journal"]) if (existsSync(original + tail)) copyFileSync(original + tail, to + tail);
     env[name] = db.write(to);
     copied.push({ name, from: original, to });
-    said.push(`Your app runs against a copy of ${rel(original)}, through ${name}; the original is not touched.`);
+    said.push(`Your app runs against a copy of ${rel(original)}, through ${name}; the original is not touched, and the copy is deleted when this command ends and made again from the original at the next connect.`);
   }
   for (const o of opened) {
     const path = resolve(dirname(o.file), o.path);
     const cwdPath = resolve(appDir, o.path);
     if ([path, cwdPath].some((p) => moved.has(p) || [...moved].some((m) => p.startsWith(m + "/")))) continue;
     moved.add(cwdPath);
-    said.push(`Your app opens ${o.path} by a path written in ${rel(o.file)}, with no variable to point it at a copy: trials write into that file.`);
+    said.push(`Your app opens ${o.path} by a path written in ${rel(o.file)}, with no variable to point it at a copy: test conversations write into that file.`);
   }
-  return { env, copied, said };
+  return { env, copied, said, values: all };
 }

package/lib/dissection-text.mjs

@@ -0,0 +1,232 @@
+import { clip, closeToCall, has, num, plural, upper } from "./words.mjs";
+
+// A finished run's dissection, as the server cut it (world-agent/dissection.ts): the run in a line,
+// what only running the app showed, what a code review would also have found, the gates a knock
+// found open, then what was held, not measured, and what the next run is paired against.
+
+// The findings printed whole, in the server's order, leaders first; the rest get a line each, so the
+// plan line and the next call at the end stay inside the page a client shows (PAGE_CHARS).
+const WHOLE_CHARS = 4500;
+// A quoted reply can hold a block of many lines; a finding's lines stay one line each.
+const flat = (s, n) => clip(String(s).replace(/\s+/g, " ").trim(), n);
+
+const pct = (x) => `${Math.round(x * 100)}%`;
+
+const LAYER_NAMES = { prompt: "prompt", flow: "flow around the model", tool: "tool", routing: "routing", limit: "model's output cap", service: "service your app depends on" };
+
+// "9 min 40 s", "45 s".
+export const durationSaid = (s) => (s >= 60 ? `${Math.floor(s / 60)} min ${Math.round(s % 60)} s` : `${Math.round(s)} s`);
+
+// What the run cost on their key and how long it took, in one sentence; empty when neither was measured.
+export function costSaid(d) {
+  const parts = [has(d.durationS) && `took ${durationSaid(d.durationS)}`, d.spent && spentSaid(d.spent)].filter(Boolean);
+  return parts.length ? `The run ${parts.join(" and ")}.` : "";
+}
+
+const spentSaid = (s) => (has(s.usd)
+  ? `spent $${s.usd.toFixed(2)} on your key over ${plural(s.calls, "model call")}`
+  : `made ${plural(s.calls, "model call")} on your key, not all of them priced`);
+
+function headLines(d) {
+  const r = d.run;
+  // The trials played are the run's own first line; this says what they ran on and what they cost.
+  const head = [r.model && `Your app answered on ${r.model}.`, costSaid(r)].filter(Boolean).join(" ");
+  const lines = head ? [head] : [];
+  if (r.replies?.n && has(r.replies.medianS)) lines.push(`Replies took ${r.replies.medianS} s at the median and ${r.replies.slowestS} s at the slowest, over ${plural(r.replies.n, "reply", "replies")}.`);
+  const t = d.tools;
+  // Unrecorded is not unused: the app started before the list of its tools reached it (usage's toolsRecorded).
+  if (t?.recorded === false) lines.push(`Calls to the ${plural(t.offered, "tool")} your app offers its model were not recorded in this run.`);
+  else if (t) lines.push(`${num(t.ran)} of ${plural(t.offered, "tool")} your app offers its model ran${t.neverRan.length ? `; never ran: ${t.neverRan.join(", ")}` : ""}.`);
+  return lines;
+}
+
+// `unseen`: the run did not record its tools, so none is said never to have run.
+function partLines(p, unseen) {
+  const lines = [`${p.id}  ${p.asks}`, `  ${upper(p.reach)}.`];
+  if (p.harm) lines.push(`  Harm: ${p.harm}.`);
+  if (p.at) lines.push(`  At ${p.at}`);
+  if (p.step) lines.push(`  Written by: ${p.step.replace(/^written by /, "")}.`);
+  if (p.tools) lines.push(`  Tools that ran behind these replies: ${p.tools.length ? p.tools.join(", ") : "none"}.`);
+  if (p.neverRan?.length && !unseen) lines.push(`  Needed by these asks and never run: ${p.neverRan.join(", ")}.`);
+  if (p.sameCause) lines.push(`  Same cause as ${p.sameCause}: one fix covers both. Verify ${p.sameCause} after the fix; the next run rechecks this one.`);
+  else if (p.layer) lines.push(`  Fix in the ${LAYER_NAMES[p.layer.name] ?? p.layer.name}: ${p.layer.said}.`);
+  const e = p.exchange;
+  if (e?.sent) lines.push(`  Sent: "${flat(e.sent, 200)}"`);
+  if (e?.broke) lines.push(`  Broke on: "${flat(e.broke, 240)}"`);
+  if (e?.after) lines.push(`  Then: "${flat(e.after, 200)}"`);
+  if (e?.note) lines.push(`    ${e.note}`);
+  // Where a fix belongs, not read: said after the exchange, never as a fix.
+  if (p.note) lines.push(`  ${p.note}`);
+  if (p.verify && !p.sameCause) lines.push(`  ${p.verify}`);
+  return lines;
+}
+
+// A run after a change leads with what moved, the way the landing page's demo says it, then what
+// it played and why, each moved behavior with the conversation that turned, the rest in one line,
+// and what the new conversations found.
+function changeLines(c, parts) {
+  const lines = [c.lead, ...(c.scope ? [c.scope] : [])];
+  for (const m of c.moved ?? []) {
+    lines.push(`${m.worse ? "Worse" : "Better"}: "${flat(m.asks, 160)}" ${m.said}.`);
+    if (m.at) lines.push(`  At ${m.at}`);
+    const p = m.proof;
+    if (p) {
+      lines.push(`  Conversation ${p.trial}${p.sent ? `, sent: "${flat(p.sent, 160)}"` : ""}`);
+      if (p.before) lines.push(`    Before: "${flat(p.before, 200)}"`);
+      if (p.now) lines.push(`    Now: "${flat(p.now, 200)}"`);
+    }
+  }
+  if (c.steady) lines.push(c.steady);
+  if (c.fresh?.length) lines.push("New findings on the conversations written for this change:", ...parts(c.fresh));
+  return lines;
+}
+
+export function dissectionLines(d) {
+  if (!d?.run) return [];
+  if (d.baseline && !d.unmeasured && !d.change) return firstRunLines(d);
+  const room = { left: WHOLE_CHARS, short: 0, unseen: d.tools?.recorded === false };
+  const parts = (ps) => ps.flatMap((p) => partOrLine(p, room));
+  const lines = [...(d.change ? changeLines(d.change, parts) : []), ...headLines(d)];
+  if (d.unmeasured) lines.push(`This run measured nothing. ${d.unmeasured} It is not counted against your plan; run again once that is fixed.`);
+  else lines.push(...brokeLines(d, room, "Found only by running your app:"));
+  lines.push(...inCodeLines(d, room), ...gateLines(d, room), ...shortLines(room));
+  for (const s of [d.held, d.notMeasured, d.next]) if (s) lines.push(s);
+  return lines;
+}
+
+function brokeLines(d, room, head) {
+  const lines = d.runOnly?.length ? [head, ...d.runOnly.flatMap((p) => partOrLine(p, room))] : ["Nothing broke that only running your app could show."];
+  return [...lines, ...(d.also ?? [])];
+}
+
+const section = (head, parts, room) => {
+  const lines = (parts ?? []).flatMap((p) => partOrLine(p, room));
+  return lines.length ? [head, ...lines] : [];
+};
+const inCodeLines = (d, room) => section("Also in the code; a code review would also find these:", d.inCode, room);
+const gateLines = (d, room) => section("Open gates, found by sending requests to your app's routes:", d.gates, room);
+const shortLines = (room) => [
+  ...(room.leaders?.length ? [`Also to act on, each shown in full by findings: ${room.leaders.join(", ")}.`] : []),
+  ...(room.short ? [`findings shows the last ${plural(room.short, "finding")} in full${room.unlisted ? `; ${num(room.unlisted)} of them are not listed here` : ""}.`] : []),
+];
+
+// The first run on a repository is the baseline: who the simulated users were, what they asked for,
+// how the app did on each journey with its interval, what held everywhere, then what broke. The
+// findings get the room the picture leaves, so the whole stays under a page.
+const FIRST_CHARS = 6000;
+const FIRST_LINES = 1600;
+const PEOPLE_SHOWN = 6;
+const JOURNEYS_SHOWN = 6;
+
+function firstRunLines(d) {
+  const b = d.baseline;
+  const said = { interval: false };
+  const picture = [baselineHead(b), ...peopleLines(b, said), ...journeyLines(b, said), ...heldEverywhereLines(b)];
+  const room = { left: Math.max(1200, FIRST_CHARS - picture.join("\n").length), short: 0, lines: FIRST_LINES, unseen: d.tools?.recorded === false };
+  return [
+    ...picture,
+    ...brokeLines(d, room, "What broke, found only by running your app:"),
+    ...gateLines(d, room),
+    ...inCodeLines(d, room),
+    ...shortLines(room),
+    ...notMeasuredLines(d, b),
+    ...headLines(d),
+    b.production
+      ? "Production is connected: field shows what your real users are doing and where your AI lets them down."
+      : "Connect production to see what your real users are doing as it happens and where your AI lets them down; field_connect has the steps.",
+  ];
+}
+
+function baselineHead(b) {
+  const head = `This was the first run, the baseline: ${plural(b.conversations, "conversation")} written from your code.`;
+  if (!b.writtenFor) return head;
+  const users = `${plural(b.users, "simulated user")} below`;
+  return b.writtenFor === b.conversations ? `${head} All of them came from the ${users}.`
+    : `${head} The ${users} had ${num(b.writtenFor)} of them; the other ${num(b.conversations - b.writtenFor)} were not written for any one user.`;
+}
+
+// "87 of 96 completed fully or partly (80 fully): 91% (83% to 95%)", saying once what the range is.
+function gotSaid(g, said) {
+  const done = g.full < g.k ? `completed fully or partly (${num(g.full)} fully)` : "completed fully";
+  const clause = said.interval ? "" : ", the likely range";
+  said.interval = true;
+  return `${num(g.k)} of ${num(g.of)} ${done}: ${pct(g.of ? g.k / g.of : 0)} (${pct(g.lo)} to ${pct(g.hi)}${clause})`;
+}
+
+function peopleLines(b, said) {
+  if (!b.people?.length) return [];
+  const line = (p) => {
+    const played = has(p.conversations) ? ` ${plural(p.conversations, "conversation")}${p.got ? `; ${gotSaid(p.got, said)}` : ""}.` : "";
+    return `  ${flat(p.who, 60)}: ${flat(p.wants, 80)}. Writes ${flat(p.writes, 50)}.${played}`;
+  };
+  const more = b.people.length - PEOPLE_SHOWN;
+  return ["The simulated users, as Cortad found them in your code:", ...b.people.slice(0, PEOPLE_SHOWN).map(line), ...(more > 0 ? [`  and ${plural(more, "more user")}.`] : [])];
+}
+
+function journeyLines(b, said) {
+  const j = b.journeys ?? { read: 0, rows: [], unplayed: [] };
+  const on = j.rows.reduce((n, r) => n + r.conversations, 0);
+  const head = j.read
+    ? `Cortad found ${plural(j.read, "journey")} in your code${on < b.conversations ? `; ${num(on)} of the ${plural(b.conversations, "conversation")} followed one of them` : ""}.`
+    : "Cortad found no journeys in your code, so the conversations are counted together.";
+  const lines = [head, "How the conversations ended, judged on each one's last reply:"];
+  const a = b.all;
+  if (a?.got || a?.frustrated || a?.askedForPerson) {
+    const parts = [a.got && gotSaid(a.got, said), a.unsure && closeToCall(a.unsure, said), a.frustrated && `${num(a.frustrated.k)} grew frustrated`, a.askedForPerson && `${num(a.askedForPerson.k)} asked for a person midway`].filter(Boolean);
+    // The line counts the conversations its own fraction is of: a conversation our simulated
+    // customer cut short still had a reply read, and "All 89 conversations: 67 of 90" said two counts.
+    lines.push(`  All ${plural(a.got?.of ?? b.conversations, "conversation")}: ${parts.join("; ")}.`);
+  }
+  for (const r of j.rows.slice(0, JOURNEYS_SHOWN)) {
+    const went = r.got ? `${gotSaid(r.got, said)}.` : `${plural(r.conversations, "conversation")}; where they ended is not known.`;
+    const most = r.failedMost.map((f) => `"${flat(f.asks, 100)}" in ${num(f.failed)} of ${num(f.of)}`).join("; ");
+    lines.push(`  ${flat(r.name, 40)}: ${went}${most ? ` Failed most: ${most}.` : ""}`);
+  }
+  const more = j.rows.length - JOURNEYS_SHOWN;
+  if (more > 0) lines.push(`  and ${plural(more, "more journey")}; findings numbers has each one.`);
+  return lines;
+}
+
+function heldEverywhereLines(b) {
+  if (!b.heldEverywhere?.length) return [];
+  return [
+    "Checks that passed in every conversation, each tested often enough to show it fails less than one time in five:",
+    ...b.heldEverywhere.map((h) => `  Passed in all ${plural(h.of, "conversation")} it was tested in, so at most ${pct(h.hi)} would fail: "${flat(h.asks, 100)}"`),
+    ...(b.heldEverywhereMore ? [`  and ${plural(b.heldEverywhereMore, "more check")}; findings numbers lists every check.`] : []),
+  ];
+}
+
+function notMeasuredLines(d, b) {
+  const unplayed = b.journeys?.unplayed ?? [];
+  const lines = [d.held, d.notMeasured, unplayed.length && `No conversation reached ${unplayed.length === 1 ? "this journey" : `these ${num(unplayed.length)} journeys`}: ${flat(unplayed.join(", "), 200)}.`].filter(Boolean);
+  return lines.length ? ["What the numbers leave out, and why:", ...lines.map((l) => `  ${l}`)] : [];
+}
+
+// `room.lines`: what the one-line findings may take; past it a finding that may lead, an open gate or
+// a crash among them, is named by its id alone, and any other is counted, not listed.
+function partOrLine(p, room) {
+  const whole = partLines(p, room.unseen);
+  const size = whole.join("\n").length;
+  if (!room.short && size <= room.left) {
+    room.left -= size;
+    return whole;
+  }
+  room.short += 1;
+  const line = `${p.id}  ${flat(p.asks, 140)} ${upper(p.reach)}.`;
+  if (line.length > (room.lines ?? Infinity)) {
+    if (p.leads) (room.leaders ??= []).push(p.id);
+    else room.unlisted = (room.unlisted ?? 0) + 1;
+    return [];
+  }
+  if (has(room.lines)) room.lines -= line.length;
+  return [line];
+}
+
+// A verify's plan says the same clauses on every finding; a page says each once.
+const BOILER = [/ until it can decide, up to [\d,]+ replays/g, / Only replays it can score count toward this month's verify conversations, at least one a round\./g];
+export function verifyOnceAPage(page) {
+  return BOILER.reduce((text, clause) => {
+    let first = true;
+    return text.replace(clause, (all) => (first ? ((first = false), all) : ""));
+  }, page);
+}

package/lib/document.mjs

@@ -0,0 +1,75 @@
+// A reply that is a document, not a sentence: flashcards, a quiz, a mindmap, notes with sections.
+// What the person sees is every item with its fields, so that is the reply. One rule with the
+// backend's src/customer/document.ts: ulaim's five flashcards were read as one card's back.
+
+const PROSE = /\S\s+\S/;
+// Fields the app keeps for itself: ids, flags, times. Never part of what the person reads.
+const META = /^(?:id|ID|uuid|_id|\w+_id|[a-z]\w*Id|success|ok|timestamp|createdAt|updatedAt|created_at|updated_at)$/;
+const REPLY_WORD = /^(?:reply|message|response|text|content|answer|output|result|chunk|token|delta|value)$/;
+const FENCED = /^\s*```(?:json)?\s*\n?([\s\S]*?)\n?\s*```\s*$/i;
+// A turn of a conversation names its side under one of these, or as its own type ({"type":"ai"}).
+const ROLE_KEY = /^(?:role|sender|from|author|speaker|who|side|type)$/i;
+// The backend's turns.ts sides: the person's, the app's, and neither.
+const SIDE = /^(?:user|human|learner|student|customer|client|person|visitor|guest|player|candidate|patient|member|caller|me|you|question|assistant|ai|bot|model|agent|npc|coach|tutor|teacher|mentor|advisor|expert|character|answer|gpt|llm|robot|system|developer|tool|function|event|log|meta|hint|error)$/i;
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isScalar = (v) => typeof v === "string" || typeof v === "number";
+const kept = (v) => v !== null && v !== undefined && typeof v !== "boolean" && v !== "" && !(Array.isArray(v) && !v.length) && !(isObject(v) && !Object.keys(v).length);
+const fields = (row) => Object.entries(row).filter(([k, v]) => !META.test(k) && kept(v));
+const isThread = (list) => list.length > 0 && list.every((t) => isObject(t) && Object.entries(t).some(([k, v]) => ROLE_KEY.test(k) && typeof v === "string" && SIDE.test(v)));
+const readAt = (v, keys) => keys.reduce((o, k) => (Array.isArray(o) ? o[Number(k) < 0 ? o.length + Number(k) : Number(k)] : isObject(o) ? o[k] : undefined), v);
+
+function proseLeaves(value) {
+  if (typeof value === "string") return PROSE.test(value) ? 1 : 0;
+  // A conversation is not a document: its reply is its newest turn.
+  if (Array.isArray(value)) return isThread(value) ? 0 : value.reduce((n, v) => n + proseLeaves(v), 0);
+  if (isObject(value)) return fields(value).reduce((n, [, v]) => n + proseLeaves(v), 0);
+  return 0;
+}
+
+export const isDocument = (value) => (Array.isArray(value) || isObject(value)) && proseLeaves(value) >= 2;
+
+const hang = (label, lines) => lines.map((line, i) => (i === 0 ? `${label} ${line}` : `${" ".repeat(label.length + 1)}${line}`));
+function lines(value) {
+  if (Array.isArray(value)) {
+    const items = value.filter(kept);
+    return items.every(isScalar) ? items.map((v) => `- ${v}`) : items.flatMap((v, i) => hang(`${i + 1}.`, lines(v)));
+  }
+  if (isObject(value)) return fields(value).flatMap(([k, v]) => (isScalar(v) ? [`${k}: ${v}`] : [`${k}:`, ...lines(v).map((l) => `  ${l}`)]));
+  return [String(value)];
+}
+
+// Every item on its own lines with its field names, in order.
+export const documentText = (value) => lines(value).join("\n");
+
+// A text that is a JSON document, bare or fenced as a model writes it, read whole; any other as it is.
+export function readable(text) {
+  const body = FENCED.exec(text)?.[1] ?? text;
+  if (!/^\s*[[{]/.test(body)) return text;
+  try {
+    const value = JSON.parse(body);
+    return isDocument(value) ? documentText(value) : text;
+  } catch {
+    return text;
+  }
+}
+
+// The document a path (a list of keys) into `value` lands in, read whole, or null when the path names
+// a reply of its own: a path through an entry of a list of records, a field beside other things said
+// that is not a chat envelope's answer field, or a list or object itself.
+export function documentAt(value, keys) {
+  if (!keys.length) return null;
+  const at = readAt(value, keys);
+  if ((Array.isArray(at) || isObject(at)) && isDocument(at)) return documentText(at);
+  for (let i = 0; i < keys.length; i++) {
+    const list = readAt(value, keys.slice(0, i));
+    if (!Array.isArray(list) || !/^-?\d+$/.test(String(keys[i]))) continue;
+    if (Number(keys[i]) < 0 || !list.some(isObject) || isThread(list)) return null;
+    const holder = i > 0 ? readAt(value, keys.slice(0, i - 1)) : list;
+    const whole = isObject(holder) && isDocument(holder) ? holder : list;
+    return isDocument(whole) ? documentText(whole) : null;
+  }
+  if (REPLY_WORD.test(String(keys.at(-1)))) return null;
+  const parent = readAt(value, keys.slice(0, -1));
+  return isObject(parent) && isDocument(parent) ? documentText(parent) : null;
+}

package/lib/env-secrets.mjs

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+
+// A model's or provider's name is how the app is configured, not a credential: status names it and
+// prices the run by it. A value under such a name that looks like a key stays masked all the same.
+const NAMES_A_MODEL = /(?:^|_)(?:MODEL|MODELS|MODEL_NAME|MODEL_ID|PROVIDER)$/i;
+const KEY_LIKE = /[A-Za-z0-9]{24,}/;
+
+// Values from your env files, read here and only here, so nothing a command prints can carry one.
+export function secretValues(envFiles) {
+  const values = new Set();
+  for (const file of envFiles) {
+    let text = "";
+    try { text = readFileSync(file, "utf8"); } catch { continue; }
+    for (const line of text.split("\n")) {
+      const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+      if (!m) continue;
+      const v = m[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+      if (NAMES_A_MODEL.test(m[1]) && !KEY_LIKE.test(v)) continue;
+      if (v.length >= 8 && !/^(true|false|localhost|development|production|\d+)$/i.test(v)) values.add(v);
+    }
+  }
+  return [...values].sort((a, b) => b.length - a.length);
+}
+
+export const maskWith = (text, values) => { let s = text; for (const v of values) s = s.split(v).join("[masked]"); return s; };
+
+// A process's output as it may be kept: masked with `values()`, read at each chunk since values are
+// learned while the app runs, and never cut inside one. A line goes to `write` once it ends; a line
+// longer than `max` goes on early, all but its last characters, as many as the longest value less
+// one, so a value the chunk ended inside is masked whole with the next. Nothing is added to it.
+export function maskedLines(values, write, max = 16_000) {
+  const decoder = new StringDecoder("utf8");
+  let carry = "";
+  return (chunk) => {
+    const text = carry + decoder.write(chunk);
+    const end = text.lastIndexOf("\n") + 1;
+    let out = maskWith(text.slice(0, end), values());
+    carry = text.slice(end);
+    if (carry.length > max) {
+      const masked = maskWith(carry, values());
+      const cut = Math.max(0, masked.length - Math.max(0, ...values().map((v) => v.length - 1)));
+      out += masked.slice(0, cut);
+      carry = masked.slice(cut);
+    }
+    if (out) write(out);
+  };
+}