@installagent/sdk 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,673 @@
1
+ // `ia tech-call verify <slug>` — the transcript check. Every material claim in
2
+ // a client's engagement docs (docs/01-04, onboarding.html) must trace to a
3
+ // quote in a call transcript or in the client's Slack channel. A claim with no
4
+ // such quote gets an UNVERIFIED mark and a line on a list. It never blocks.
5
+ //
6
+ // Why: the lead-close kickoff once drafted a whole spec from the intake
7
+ // profile (a build the client never asked for), and nothing compared the docs
8
+ // with the recording. This is that comparison, as a command.
9
+ //
10
+ // The model proposes; the code decides. One model call lists the claims and,
11
+ // for each, a verdict and a quote. Then `checkClaims` looks for every quote in
12
+ // the sources as a literal string (case, spaces and punctuation ignored). A
13
+ // quote that is not there makes the claim UNVERIFIED, whatever the model said.
14
+ // So the model can miss a claim, but it cannot pass one.
15
+ //
16
+ // Read-only by default. `write` changes the working tree only: marks in the
17
+ // docs and one evidence file. It never commits and never touches the registry.
18
+ import { execFile } from "node:child_process";
19
+ import { existsSync } from "node:fs";
20
+ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
21
+ import { join, resolve } from "node:path";
22
+ import { promisify } from "node:util";
23
+ import { GEMINI_API_KEY_ENV, redactContactDetails, removeMoney } from "./build-estimate.js";
24
+ import { readManifestKey } from "./client-manifest.js";
25
+ import { FATHOM_API_KEY_ENV } from "./fathom-webhook.js";
26
+ import { SLUG_PATTERN } from "./new-client.js";
27
+ import { parseNoteFrontmatter } from "./tech-call-note-landed.js";
28
+ const run = promisify(execFile);
29
+ export const VERIFY_MODEL = "gemini-3.8-flash";
30
+ export const SLACK_BOT_TOKEN_ENV = "SLACK_BOT_TOKEN";
31
+ const GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta";
32
+ const FATHOM_API_BASE = "https://api.fathom.ai/external/v1";
33
+ const MODEL_TIMEOUT_MS = 180_000;
34
+ /** The docs the check reads. Marks go into these four; onboarding.html is list-only. */
35
+ export const VERIFY_DOCS = [
36
+ "docs/01-overview.md",
37
+ "docs/02-tech-spec.md",
38
+ "docs/03-client-onboarding.md",
39
+ "docs/04-access-checklist.md",
40
+ ];
41
+ /** The client reads these on the portal: a mark there is a hidden comment. */
42
+ const CLIENT_READ_DOCS = new Set(["docs/01-overview.md", "docs/03-client-onboarding.md"]);
43
+ const ONBOARDING = "onboarding.html";
44
+ const ONBOARDING_MAX_CHARS = 20_000;
45
+ const NOTE_FILE = /^(\d{4}-\d{2}-\d{2})(-[a-z0-9-]+)?\.md$/;
46
+ export class NoTranscriptError extends Error {
47
+ }
48
+ // ---------------------------------------------------------------------------
49
+ // Pure: matching
50
+ /** Lower case, letters and digits only, single spaces. What "the same words" means here. */
51
+ export function normalizeForMatch(text) {
52
+ return text
53
+ .toLowerCase()
54
+ .replace(/[‘’]/g, "'")
55
+ .replace(/[^a-z0-9]+/g, " ")
56
+ .trim();
57
+ }
58
+ /** A transcript without `[HH:MM:SS] Speaker:` prefixes, normalized, as one string. */
59
+ function transcriptHaystack(text) {
60
+ return normalizeForMatch(text
61
+ .split(/\r?\n/)
62
+ .filter((line) => !line.startsWith("#") && !line.startsWith(">"))
63
+ .map((line) => line.replace(/^\[[\d:]+\]\s*/, "").replace(/^[^:]{1,60}:\s/, ""))
64
+ .join(" "));
65
+ }
66
+ /** A quote must be at least this many words: "yes" or "the portal" proves nothing. */
67
+ export const MIN_QUOTE_WORDS = 4;
68
+ /** `[HH:MM:SS]` of the transcript line where the quote starts, or "". */
69
+ export function quoteTimestamp(transcript, quote) {
70
+ const head = normalizeForMatch(quote).split(" ").slice(0, 6).join(" ");
71
+ if (!head)
72
+ return "";
73
+ for (const line of transcript.split(/\r?\n/)) {
74
+ const stamp = /^\[([\d:]+)\]/.exec(line);
75
+ if (stamp && normalizeForMatch(line).includes(head))
76
+ return `[${stamp[1]}]`;
77
+ }
78
+ return "";
79
+ }
80
+ /**
81
+ * Where a quote really is: the call (and timestamp) or Slack — or nothing.
82
+ * Literal containment after normalization, so a paraphrase does not count.
83
+ */
84
+ export function findQuote(quote, sources) {
85
+ const needle = normalizeForMatch(quote);
86
+ if (needle.split(" ").filter(Boolean).length < MIN_QUOTE_WORDS)
87
+ return null;
88
+ for (const transcript of sources.transcripts) {
89
+ if (transcriptHaystack(transcript.text).includes(needle)) {
90
+ const stamp = quoteTimestamp(transcript.text, quote);
91
+ return { source: "transcript", at: `${transcript.call}${stamp ? ` ${stamp}` : ""}` };
92
+ }
93
+ }
94
+ for (const message of sources.slack ?? []) {
95
+ if (normalizeForMatch(message).includes(needle)) {
96
+ return { source: "slack", at: /^\[(\d{4}-\d{2}-\d{2})\]/.exec(message)?.[1] ?? "" };
97
+ }
98
+ }
99
+ return null;
100
+ }
101
+ const KINDS = new Set([
102
+ "scope",
103
+ "stack",
104
+ "person",
105
+ "access",
106
+ "commitment",
107
+ "number",
108
+ "other",
109
+ ]);
110
+ /**
111
+ * The model's answer → the final claims. `supported` and `contradicted` both
112
+ * need a quote that is really in a source; without one the claim is
113
+ * UNVERIFIED and the note says why.
114
+ */
115
+ export function checkClaims(raw, sources) {
116
+ const rows = (raw.claims ?? [])
117
+ .map((claim) => ({
118
+ doc: String(claim.doc ?? "").trim(),
119
+ line: Number.isInteger(claim.line) && claim.line > 0 ? claim.line : 0,
120
+ text: String(claim.text ?? "").trim(),
121
+ kind: (KINDS.has(String(claim.kind)) ? claim.kind : "other"),
122
+ verdict: String(claim.verdict ?? ""),
123
+ quote: String(claim.quote ?? "").trim(),
124
+ }))
125
+ .filter((claim) => claim.doc && claim.text)
126
+ .sort((a, b) => a.doc.localeCompare(b.doc) || a.line - b.line);
127
+ return rows.map((claim, index) => {
128
+ const id = `c-${String(index + 1).padStart(2, "0")}`;
129
+ const base = { id, doc: claim.doc, line: claim.line, text: claim.text, kind: claim.kind };
130
+ const wanted = claim.verdict === "supported" || claim.verdict === "contradicted";
131
+ if (!wanted) {
132
+ return {
133
+ ...base,
134
+ verdict: "unverified",
135
+ source: "none",
136
+ quote: "",
137
+ at: "",
138
+ };
139
+ }
140
+ const found = claim.quote ? findQuote(claim.quote, sources) : null;
141
+ if (!found) {
142
+ return {
143
+ ...base,
144
+ verdict: "unverified",
145
+ source: "none",
146
+ quote: "",
147
+ at: "",
148
+ note: claim.quote
149
+ ? `the model said ${claim.verdict}, but its quote is not in a transcript or in Slack`
150
+ : `the model said ${claim.verdict} with no quote`,
151
+ };
152
+ }
153
+ return {
154
+ ...base,
155
+ verdict: claim.verdict,
156
+ source: found.source,
157
+ quote: claim.quote,
158
+ at: found.at,
159
+ };
160
+ });
161
+ }
162
+ /** Promises: kept only when the quote is really in a source. */
163
+ export function checkPromises(raw, sources) {
164
+ const out = [];
165
+ for (const promise of raw.promises ?? []) {
166
+ const text = String(promise.text ?? "").trim();
167
+ const quote = String(promise.quote ?? "").trim();
168
+ const found = quote ? findQuote(quote, sources) : null;
169
+ if (!text || !found)
170
+ continue;
171
+ out.push({ text, quote, at: found.at, scope: String(promise.scope ?? "").trim() });
172
+ }
173
+ return out;
174
+ }
175
+ // ---------------------------------------------------------------------------
176
+ // Pure: marks
177
+ const VISIBLE_MARK = / \*\*\[(?:UNVERIFIED|CONTRADICTED) c-\d+\]\*\*/g;
178
+ const HIDDEN_MARK = / <!-- (?:UNVERIFIED|CONTRADICTED): c-\d+ -->/g;
179
+ /** A doc with every mark of this command removed. */
180
+ export function stripMarks(text) {
181
+ return text.replace(VISIBLE_MARK, "").replace(HIDDEN_MARK, "");
182
+ }
183
+ /**
184
+ * A doc with a mark on the line of each claim that is not supported. Marks
185
+ * are rebuilt from the claims on every run (old ones are stripped first), so a
186
+ * second run never stacks them. Never touched: the generated
187
+ * ACCESS_STATUS_TABLE block (ci/sync.mjs owns it) and lines the claim does not
188
+ * name. A table row keeps its closing pipe after the mark.
189
+ */
190
+ export function applyMarks(doc, text, claims) {
191
+ const hidden = CLIENT_READ_DOCS.has(doc);
192
+ const lines = stripMarks(text).split("\n");
193
+ let generated = false;
194
+ const guarded = lines.map((line) => {
195
+ if (line.includes("ACCESS_STATUS_TABLE:START"))
196
+ generated = true;
197
+ const inside = generated;
198
+ if (line.includes("ACCESS_STATUS_TABLE:END"))
199
+ generated = false;
200
+ return inside;
201
+ });
202
+ for (const claim of claims) {
203
+ if (claim.doc !== doc || claim.verdict === "supported" || claim.line < 1)
204
+ continue;
205
+ const at = claim.line - 1;
206
+ const line = lines[at];
207
+ if (line === undefined || !line.trim() || guarded[at])
208
+ continue;
209
+ const word = claim.verdict === "contradicted" ? "CONTRADICTED" : "UNVERIFIED";
210
+ const mark = hidden ? ` <!-- ${word}: ${claim.id} -->` : ` **[${word} ${claim.id}]**`;
211
+ const row = /^(\s*\|.*?)(\s*\|\s*)$/.exec(line);
212
+ lines[at] = row ? `${row[1]}${mark}${row[2]}` : `${line.replace(/\s+$/, "")}${mark}`;
213
+ }
214
+ return lines.join("\n");
215
+ }
216
+ /** A doc as `<line number>| <text>` — what the model sees, so it can name a line. */
217
+ export function numberLines(text) {
218
+ return stripMarks(text)
219
+ .split("\n")
220
+ .map((line, index) => `${index + 1}| ${line}`)
221
+ .join("\n");
222
+ }
223
+ /** onboarding.html → its visible text, one block per line, scripts and styles dropped. */
224
+ export function htmlText(html) {
225
+ return html
226
+ .replace(/<(script|style)[\s\S]*?<\/\1>/gi, " ")
227
+ .replace(/<!--[\s\S]*?-->/g, " ")
228
+ .replace(/<\/(p|div|li|h[1-6]|tr|section|td|th)>/gi, "\n")
229
+ .replace(/<[^>]+>/g, " ")
230
+ .replace(/&amp;/g, "&")
231
+ .replace(/&lt;/g, "<")
232
+ .replace(/&gt;/g, ">")
233
+ .replace(/&nbsp;/g, " ")
234
+ .split("\n")
235
+ .map((line) => line.replace(/\s+/g, " ").trim())
236
+ .filter(Boolean)
237
+ .join("\n");
238
+ }
239
+ // ---------------------------------------------------------------------------
240
+ // Pure: the prompt and the evidence file
241
+ const VERIFY_SCHEMA = {
242
+ type: "OBJECT",
243
+ properties: {
244
+ claims: {
245
+ type: "ARRAY",
246
+ items: {
247
+ type: "OBJECT",
248
+ properties: {
249
+ doc: { type: "STRING" },
250
+ line: { type: "INTEGER" },
251
+ text: { type: "STRING" },
252
+ kind: { type: "STRING" },
253
+ verdict: { type: "STRING" },
254
+ source: { type: "STRING" },
255
+ quote: { type: "STRING" },
256
+ },
257
+ required: ["doc", "line", "text", "kind", "verdict", "quote"],
258
+ },
259
+ },
260
+ promises: {
261
+ type: "ARRAY",
262
+ items: {
263
+ type: "OBJECT",
264
+ properties: {
265
+ text: { type: "STRING" },
266
+ quote: { type: "STRING" },
267
+ scope: { type: "STRING" },
268
+ },
269
+ required: ["text", "quote", "scope"],
270
+ },
271
+ },
272
+ },
273
+ required: ["claims", "promises"],
274
+ };
275
+ export function buildVerifyPrompt(input) {
276
+ return [
277
+ `You check a client's engagement documents against what was really said. The documents were
278
+ drafted by a model and edited by people. Some claims in them have no basis in any call.
279
+
280
+ TASK 1 - claims. List every MATERIAL claim the documents make about THIS client: what we are
281
+ building (scope), their tools and systems (stack), their people and roles (person), what access
282
+ exists or was granted (access), what either side agreed to do (commitment), and figures (number).
283
+ Skip headings, our own process text that is the same for every client, template instructions,
284
+ and placeholders. One claim per document line; if a line holds two claims, list the weaker one.
285
+ For each claim give:
286
+ - doc: the document path exactly as given; line: the line number shown before "|" (0 for onboarding.html)
287
+ - text: the claim in one short sentence; kind: scope | stack | person | access | commitment | number | other
288
+ - verdict: "supported" when a source says it; "contradicted" when a source says otherwise;
289
+ "unverified" when no source says it. An inference from the company's industry is unverified.
290
+ - quote: for supported and contradicted, the EXACT words from a transcript or a Slack message
291
+ that the verdict rests on - copied character for character, at least ${MIN_QUOTE_WORDS} words, at most 40,
292
+ from ONE speaker turn or ONE message. Do not join two places. Do not fix grammar. For
293
+ unverified, an empty string. A quote that is not literally in a source is thrown away.
294
+
295
+ TASK 2 - promises. List what an Install Agent person told the client we WILL do or what the
296
+ client WILL get (a deliverable, a behaviour, a timeline, something included). For each: text
297
+ (one sentence), quote (exact words, same rules), and scope: the claim text from TASK 1 that
298
+ covers it in the documents, or an empty string when the documents do not hold it.
299
+
300
+ Return only the JSON object.`,
301
+ ...input.docs.map((doc) => `=== DOCUMENT ${doc.path} ===\n${doc.text}`),
302
+ ...input.sources.transcripts.map((transcript) => `=== TRANSCRIPT of the call filed as ${transcript.call} ===\n${transcript.text}`),
303
+ input.sources.slack
304
+ ? `=== SLACK (the client's channel) ===\n${input.sources.slack.join("\n") || "(no messages)"}`
305
+ : "=== SLACK === not read for this run.",
306
+ ].join("\n\n");
307
+ }
308
+ /**
309
+ * The second pass: ONE transcript, promises only. The first call has every
310
+ * document and every transcript in front of it and spends its attention on the
311
+ * claims; asked in the same breath, it lists the sales promises and skips the
312
+ * ones a technician made an hour into the tech call. A promise nobody wrote
313
+ * down is the thing this pass exists to catch.
314
+ */
315
+ export function buildPromisesPrompt(input) {
316
+ return [
317
+ `Read this call transcript turn by turn. The Install Agent people are the ones who sell or
318
+ deliver the service; the client is the other side. List EVERY place where an Install Agent
319
+ person tells the client:
320
+ - what we WILL do or build, or when;
321
+ - what the client WILL get, see or receive;
322
+ - what is INCLUDED, free, or a bonus;
323
+ - what will NOT change, or what the client will NOT have to do;
324
+ - how the client will be able to do something later (for example change something themselves).
325
+ Go through the WHOLE call, to the last minute: promises made late in a call are the ones that
326
+ get lost. Do not list what the client says they will do. Do not list small talk.
327
+ For each promise give:
328
+ - text: the promise in one sentence;
329
+ - quote: the EXACT words from ONE speaker turn, copied character for character, at least
330
+ ${MIN_QUOTE_WORDS} words and at most 40. A quote that is not literally in the transcript is thrown away;
331
+ - scope: the sentence in the documents below that covers this promise, or an empty string when
332
+ the documents do not hold it.
333
+ Return the JSON object with "promises" filled and "claims" as an empty array.`,
334
+ ...input.docs.map((doc) => `=== DOCUMENT ${doc.path} ===\n${doc.text}`),
335
+ `=== TRANSCRIPT of the call filed as ${input.transcript.call} ===\n${input.transcript.text}`,
336
+ ].join("\n\n");
337
+ }
338
+ /** Promises from several passes as one list: in call order, one per place in a call. */
339
+ export function mergePromises(lists) {
340
+ const seen = new Set();
341
+ const out = [];
342
+ for (const promise of lists.flat()) {
343
+ const key = `${promise.at}|${normalizeForMatch(promise.quote).split(" ").slice(0, 5).join(" ")}`;
344
+ // Two passes that quote the same turn are the same promise.
345
+ if (seen.has(key) || (promise.at.includes("[") && seen.has(promise.at)))
346
+ continue;
347
+ seen.add(key);
348
+ if (promise.at.includes("["))
349
+ seen.add(promise.at);
350
+ out.push(promise);
351
+ }
352
+ return out.sort((a, b) => a.at.localeCompare(b.at));
353
+ }
354
+ // The evidence file lives in the client's build repo: no email, no phone, and
355
+ // no dollar amount (a sales call names our fees; they never belong in a repo).
356
+ const cell = (text) => removeMoney(redactContactDetails(text))
357
+ .replace(/\s*\n\s*/g, " ")
358
+ .replace(/\|/g, "\\|");
359
+ const short = (text, max) => text.length > max ? `${text.slice(0, max - 1)}…` : text;
360
+ /** The evidence file. Quotes are short and carry no email or phone. */
361
+ export function renderVerifyEvidence(result) {
362
+ const count = (verdict) => result.claims.filter((c) => c.verdict === verdict).length;
363
+ const rows = (verdict) => result.claims
364
+ .filter((claim) => claim.verdict === verdict)
365
+ .map((claim) => `| ${claim.id} | \`${claim.doc}${claim.line ? `:${claim.line}` : ""}\` | ${claim.kind} | ${cell(short(claim.text, 200))} | ${claim.quote
366
+ ? `${claim.at} "${cell(short(claim.quote, 160))}"`
367
+ : cell(claim.note ?? "no source")} |`);
368
+ const table = (verdict, last) => {
369
+ const body = rows(verdict);
370
+ return body.length
371
+ ? [`| Id | Where | Kind | Claim | ${last} |`, "|---|---|---|---|---|", ...body].join("\n")
372
+ : "None.";
373
+ };
374
+ return [
375
+ `# Transcript check — ${result.slug} — ${result.date}`,
376
+ "",
377
+ `> \`ia tech-call verify ${result.slug}\`${result.ref ? ` on \`${result.ref}\`` : ""}, model ${result.model}.`,
378
+ `> Sources: transcripts ${result.sources.transcripts.join(", ") || "none"}; Slack: ${result.sources.slack}.`,
379
+ "> The model lists claims and quotes. The command keeps a quote only when it is literally in a source.",
380
+ "> A missed claim is possible; a passed claim with no quote is not. This list does not block anything.",
381
+ "",
382
+ `**${result.claims.length} claims:** ${count("supported")} supported, ${count("unverified")} unverified, ${count("contradicted")} contradicted. **${result.promises.length} promises**, ${result.promises.filter((p) => !p.scope).length} with no scope item.`,
383
+ "",
384
+ "## Contradicted — the call says otherwise",
385
+ "",
386
+ table("contradicted", "What the source says"),
387
+ "",
388
+ "## Unverified — no source says it",
389
+ "",
390
+ table("unverified", "Why"),
391
+ "",
392
+ "## Promises made on a call",
393
+ "",
394
+ result.promises.length
395
+ ? [
396
+ "| When | Promise | Words | Scope item in the docs |",
397
+ "|---|---|---|---|",
398
+ ...result.promises.map((promise) => `| ${promise.at} | ${cell(short(promise.text, 200))} | "${cell(short(promise.quote, 160))}" | ${promise.scope ? cell(short(promise.scope, 120)) : "**NONE — a promise with no scope**"} |`),
399
+ ].join("\n")
400
+ : "None found.",
401
+ "",
402
+ ].join("\n");
403
+ }
404
+ async function gitShow(repoDir, ref, path) {
405
+ try {
406
+ const { stdout } = await run("git", ["-C", repoDir, "show", `${ref}:${path}`], {
407
+ maxBuffer: 64 * 1024 * 1024,
408
+ });
409
+ return stdout;
410
+ }
411
+ catch {
412
+ return null;
413
+ }
414
+ }
415
+ async function gitList(repoDir, ref, dir) {
416
+ try {
417
+ const { stdout } = await run("git", ["-C", repoDir, "ls-tree", "--name-only", `${ref}:${dir}`]);
418
+ return stdout.split("\n").filter(Boolean);
419
+ }
420
+ catch {
421
+ return [];
422
+ }
423
+ }
424
+ async function fathomTranscript(recordingId, apiKey, fetchImpl) {
425
+ const res = await fetchImpl(`${FATHOM_API_BASE}/recordings/${encodeURIComponent(recordingId)}/transcript`, {
426
+ headers: { "X-Api-Key": apiKey },
427
+ });
428
+ if (!res.ok)
429
+ return "";
430
+ const body = (await res.json().catch(() => null));
431
+ return (body?.transcript ?? [])
432
+ .map((turn) => {
433
+ const text = (turn.text ?? "").trim();
434
+ return text
435
+ ? `[${turn.timestamp ?? "--:--:--"}] ${turn.speaker?.display_name ?? "Speaker"}: ${text}`
436
+ : "";
437
+ })
438
+ .filter(Boolean)
439
+ .join("\n");
440
+ }
441
+ /**
442
+ * Every call transcript on record for the client: the `<note>.transcript.md`
443
+ * files beside the notes, and for a note without one, Fathom by `fathom_id`.
444
+ */
445
+ export async function loadTranscripts(slug, options, fetchImpl) {
446
+ const registry = join(resolve(options.workspaceDir), "team-clients");
447
+ const dir = `clients/${slug}/calls`;
448
+ const ref = options.registryRef;
449
+ const names = ref
450
+ ? await gitList(registry, ref, dir)
451
+ : existsSync(join(registry, dir))
452
+ ? await readdir(join(registry, dir))
453
+ : [];
454
+ const read = (name) => ref
455
+ ? gitShow(registry, ref, `${dir}/${name}`)
456
+ : readFile(join(registry, dir, name), "utf8").catch(() => null);
457
+ const fathomKey = options.fathomApiKey ?? process.env[FATHOM_API_KEY_ENV];
458
+ const out = [];
459
+ for (const name of names.filter((n) => NOTE_FILE.test(n)).sort()) {
460
+ const date = NOTE_FILE.exec(name)?.[1] ?? "";
461
+ if (options.call && date > options.call)
462
+ continue;
463
+ const call = name.replace(/\.md$/, "");
464
+ let text = names.includes(`${call}.transcript.md`)
465
+ ? ((await read(`${call}.transcript.md`)) ?? "")
466
+ : "";
467
+ if (!text.trim() && fathomKey) {
468
+ const id = parseNoteFrontmatter((await read(name)) ?? "").fathom_id;
469
+ if (id)
470
+ text = await fathomTranscript(id, fathomKey, fetchImpl).catch(() => "");
471
+ }
472
+ if (text.trim())
473
+ out.push({ call, text: text.trim() });
474
+ }
475
+ return out;
476
+ }
477
+ /** The last messages of the client's Slack channel, oldest first, or the reason there are none. */
478
+ async function loadSlack(channelName, token, fetchImpl) {
479
+ const call = async (method, params) => {
480
+ const res = await fetchImpl(`https://slack.com/api/${method}?${new URLSearchParams(params)}`, {
481
+ headers: { Authorization: `Bearer ${token}` },
482
+ });
483
+ return (await res.json().catch(() => ({ ok: false, error: "bad response" })));
484
+ };
485
+ let cursor = "";
486
+ let channelId = "";
487
+ for (let page = 0; page < 10 && !channelId; page++) {
488
+ const list = await call("users.conversations", {
489
+ types: "public_channel,private_channel",
490
+ exclude_archived: "true",
491
+ limit: "200",
492
+ ...(cursor ? { cursor } : {}),
493
+ });
494
+ if (!list.ok)
495
+ return { messages: null, note: `not read (Slack: ${list.error ?? "error"})` };
496
+ channelId = list.channels?.find((channel) => channel.name === channelName)?.id ?? "";
497
+ cursor = list.response_metadata?.next_cursor ?? "";
498
+ if (!cursor)
499
+ break;
500
+ }
501
+ if (!channelId)
502
+ return { messages: null, note: `not read (the bot is not in #${channelName})` };
503
+ const history = await call("conversations.history", { channel: channelId, limit: "200" });
504
+ if (!history.ok)
505
+ return { messages: null, note: `not read (Slack: ${history.error ?? "error"})` };
506
+ const messages = (history.messages ?? [])
507
+ .filter((message) => !message.subtype && message.text?.trim())
508
+ .reverse()
509
+ .map((message) => {
510
+ const day = new Date(Number(message.ts ?? 0) * 1000).toISOString().slice(0, 10);
511
+ return `[${day}] ${(message.text ?? "").replace(/\s+/g, " ").trim()}`;
512
+ });
513
+ return { messages, note: `#${channelName}, ${messages.length} message(s)` };
514
+ }
515
+ async function askGeminiJson(prompt, apiKey, model, fetchImpl) {
516
+ const res = await fetchImpl(`${GEMINI_API_BASE}/models/${encodeURIComponent(model)}:generateContent`, {
517
+ method: "POST",
518
+ headers: { "Content-Type": "application/json", "x-goog-api-key": apiKey },
519
+ signal: AbortSignal.timeout(MODEL_TIMEOUT_MS),
520
+ body: JSON.stringify({
521
+ contents: [{ role: "user", parts: [{ text: prompt }] }],
522
+ generationConfig: {
523
+ responseMimeType: "application/json",
524
+ responseSchema: VERIFY_SCHEMA,
525
+ temperature: 0,
526
+ },
527
+ }),
528
+ });
529
+ const body = (await res.json().catch(() => null));
530
+ if (!res.ok)
531
+ throw new Error(`Gemini answered HTTP ${res.status}: ${body?.error?.message ?? "no detail"}`);
532
+ return (body?.candidates?.[0]?.content?.parts ?? []).map((part) => part.text ?? "").join("");
533
+ }
534
+ /** The model's text → the raw answer, or null when it is not the shape asked for. */
535
+ export function parseVerifyAnswer(text) {
536
+ try {
537
+ const parsed = JSON.parse(text.replace(/^```(?:json)?\s*|\s*```$/g, ""));
538
+ return Array.isArray(parsed?.claims) && Array.isArray(parsed?.promises) ? parsed : null;
539
+ }
540
+ catch {
541
+ return null;
542
+ }
543
+ }
544
+ export async function techCallVerify(slug, options) {
545
+ if (!SLUG_PATTERN.test(slug)) {
546
+ throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
547
+ }
548
+ if (options.write && options.ref) {
549
+ throw new Error("--write changes the working tree, so it cannot be used with --ref");
550
+ }
551
+ const fetchImpl = options.fetchImpl ?? fetch;
552
+ const repoDir = options.repoDir
553
+ ? resolve(options.repoDir)
554
+ : join(resolve(options.workspaceDir), "clients", `client-${slug}`);
555
+ if (!existsSync(repoDir)) {
556
+ throw new Error(`${repoDir} not found — clone the client repo first (\`ia sync\`)`);
557
+ }
558
+ const ref = options.ref ?? null;
559
+ const read = (path) => ref ? gitShow(repoDir, ref, path) : readFile(join(repoDir, path), "utf8").catch(() => null);
560
+ const texts = new Map();
561
+ for (const path of VERIFY_DOCS) {
562
+ const text = await read(path);
563
+ if (text?.trim())
564
+ texts.set(path, text);
565
+ }
566
+ if (texts.size === 0) {
567
+ throw new Error(`client-${slug}${ref ? ` at ${ref}` : ""} has no docs/01-04 — nothing to check (a kickoff that waits for its call note writes none)`);
568
+ }
569
+ const onboarding = await read(ONBOARDING);
570
+ const docs = [...texts].map(([path, text]) => ({ path, text: numberLines(text) }));
571
+ if (onboarding?.trim() && !onboarding.includes("REPLACE_WITH_CLIENT_NAME")) {
572
+ docs.push({ path: ONBOARDING, text: htmlText(onboarding).slice(0, ONBOARDING_MAX_CHARS) });
573
+ }
574
+ const transcripts = options.transcripts ?? (await loadTranscripts(slug, options, fetchImpl));
575
+ if (transcripts.length === 0) {
576
+ throw new NoTranscriptError(`no transcript for "${slug}"${options.call ? ` up to ${options.call}` : ""}: no calls/<date>.transcript.md in team-clients, and Fathom gave none (is ${FATHOM_API_KEY_ENV} set?)`);
577
+ }
578
+ let slack = null;
579
+ let slackNote = "not read (--no-slack)";
580
+ if (options.slackMessages !== undefined) {
581
+ slack = options.slackMessages;
582
+ slackNote = slack ? `${slack.length} message(s)` : "not read";
583
+ }
584
+ else if (!options.noSlack) {
585
+ const token = options.slackToken ?? process.env[SLACK_BOT_TOKEN_ENV];
586
+ const clientMd = (await read("CLIENT.md")) ?? "";
587
+ const channel = (readManifestKey(clientMd, "slack_channel") ?? `#client-${slug}`).replace(/^#/, "");
588
+ if (!token)
589
+ slackNote = `not read (${SLACK_BOT_TOKEN_ENV} is not set)`;
590
+ else {
591
+ const loaded = await loadSlack(channel, token, fetchImpl).catch((error) => ({
592
+ messages: null,
593
+ note: `not read (${error instanceof Error ? error.message : "error"})`,
594
+ }));
595
+ slack = loaded.messages;
596
+ slackNote = loaded.note;
597
+ }
598
+ }
599
+ const sources = { transcripts, slack };
600
+ const model = options.model ?? VERIFY_MODEL;
601
+ const ask = options.askModel ??
602
+ ((prompt) => {
603
+ const apiKey = options.apiKey ?? process.env[GEMINI_API_KEY_ENV];
604
+ if (!apiKey)
605
+ throw new Error(`${GEMINI_API_KEY_ENV} is not set — run \`ia env fill\` (team-techs vault)`);
606
+ return askGeminiJson(prompt, apiKey, model, fetchImpl);
607
+ });
608
+ const prompt = buildVerifyPrompt({ docs, sources });
609
+ // One retry: a reply that is not the shape asked for is usually a cut-off answer.
610
+ let raw = parseVerifyAnswer(await ask(prompt));
611
+ if (!raw)
612
+ raw = parseVerifyAnswer(await ask(prompt));
613
+ if (!raw)
614
+ throw new Error("the model's reply is not {claims, promises}, twice — nothing was changed");
615
+ const claims = checkClaims(raw, sources);
616
+ // Second pass, one call per transcript, promises only. Fail-soft: a pass that
617
+ // fails loses its extra promises, never the claims.
618
+ const promiseLists = [checkPromises(raw, sources)];
619
+ for (const transcript of transcripts) {
620
+ try {
621
+ const answer = parseVerifyAnswer(await ask(buildPromisesPrompt({ docs, transcript })));
622
+ if (answer)
623
+ promiseLists.push(checkPromises(answer, { transcripts: [transcript], slack: null }));
624
+ }
625
+ catch {
626
+ // The first call's promises stand.
627
+ }
628
+ }
629
+ const promises = mergePromises(promiseLists);
630
+ const date = (options.now ?? new Date()).toISOString().slice(0, 10);
631
+ const sourceSummary = { transcripts: transcripts.map((t) => t.call), slack: slackNote };
632
+ const evidence = renderVerifyEvidence({
633
+ slug,
634
+ date,
635
+ ref,
636
+ model,
637
+ claims,
638
+ promises,
639
+ sources: sourceSummary,
640
+ });
641
+ let written = null;
642
+ if (options.write) {
643
+ written = [];
644
+ for (const [path, text] of texts) {
645
+ const next = applyMarks(path, text, claims);
646
+ if (next !== text) {
647
+ await writeFile(join(repoDir, path), next);
648
+ written.push(path);
649
+ }
650
+ }
651
+ const evidencePath = `evidence/${date}-transcript-check.md`;
652
+ await mkdir(join(repoDir, "evidence"), { recursive: true });
653
+ await writeFile(join(repoDir, evidencePath), evidence);
654
+ written.push(evidencePath);
655
+ }
656
+ return {
657
+ slug,
658
+ ref,
659
+ model,
660
+ docs: docs.map((doc) => doc.path),
661
+ claims,
662
+ promises,
663
+ counts: {
664
+ supported: claims.filter((c) => c.verdict === "supported").length,
665
+ unverified: claims.filter((c) => c.verdict === "unverified").length,
666
+ contradicted: claims.filter((c) => c.verdict === "contradicted").length,
667
+ promisesWithoutScope: promises.filter((p) => !p.scope).length,
668
+ },
669
+ sources: sourceSummary,
670
+ written,
671
+ evidence,
672
+ };
673
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.14.0",
3
+ "version": "0.16.0",
4
4
  "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",