@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.
- package/dist/env-registry.js +19 -3
- package/dist/index.d.ts +6 -1
- package/dist/index.js +6 -1
- package/dist/portal-admin.d.ts +24 -0
- package/dist/portal-admin.js +12 -0
- package/dist/tech-call-agenda.d.ts +57 -0
- package/dist/tech-call-agenda.js +94 -0
- package/dist/tech-call-note-landed.d.ts +43 -0
- package/dist/tech-call-note-landed.js +93 -0
- package/dist/tech-call-prep.d.ts +94 -0
- package/dist/tech-call-prep.js +460 -0
- package/dist/tech-call-update-pass.d.ts +142 -0
- package/dist/tech-call-update-pass.js +707 -0
- package/dist/tech-call-verify.d.ts +191 -0
- package/dist/tech-call-verify.js +673 -0
- package/package.json +1 -1
- package/templates/env.example +3 -0
- package/templates/workspace-root/AGENT.md +2 -1
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +27 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +5 -0
- package/templates/workspace-root/skills/linear/SKILL.md +13 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +48 -19
|
@@ -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(/&/g, "&")
|
|
231
|
+
.replace(/</g, "<")
|
|
232
|
+
.replace(/>/g, ">")
|
|
233
|
+
.replace(/ /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