@installagent/sdk 0.2.0 → 0.4.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/agent-mirror.d.ts +69 -0
- package/dist/agent-mirror.js +275 -0
- package/dist/claude-hours.d.ts +134 -0
- package/dist/claude-hours.js +638 -0
- package/dist/client-drive.d.ts +3 -0
- package/dist/client-drive.js +2 -2
- package/dist/client-linear-create.d.ts +10 -0
- package/dist/client-linear-create.js +30 -3
- package/dist/env-fill.js +21 -4
- package/dist/env-registry.d.ts +4 -0
- package/dist/env-registry.js +54 -2
- package/dist/git.d.ts +31 -0
- package/dist/git.js +59 -0
- package/dist/google-service-account.d.ts +20 -0
- package/dist/google-service-account.js +49 -0
- package/dist/hours-estimate.d.ts +43 -0
- package/dist/hours-estimate.js +159 -0
- package/dist/hours-export-schedule.d.ts +35 -0
- package/dist/hours-export-schedule.js +188 -0
- package/dist/hours-ledger.d.ts +137 -0
- package/dist/hours-ledger.js +926 -0
- package/dist/index.d.ts +14 -3
- package/dist/index.js +14 -3
- package/dist/portal-admin.d.ts +68 -0
- package/dist/portal-admin.js +64 -1
- package/dist/sync-repos.d.ts +7 -0
- package/dist/sync-repos.js +10 -1
- package/dist/template-sync.d.ts +10 -9
- package/dist/template-sync.js +14 -9
- package/dist/triage-backfill.d.ts +37 -0
- package/dist/triage-backfill.js +211 -0
- package/dist/triage-enable.d.ts +90 -0
- package/dist/triage-enable.js +428 -0
- package/dist/triage-gates.d.ts +252 -0
- package/dist/triage-gates.js +951 -0
- package/dist/workspace-push.d.ts +39 -0
- package/dist/workspace-push.js +78 -0
- package/dist/workspace-status.d.ts +37 -0
- package/dist/workspace-status.js +114 -0
- package/package.json +1 -1
- package/templates/env.example +6 -2
- package/templates/workspace-root/.claude/settings.json +12 -1
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
- package/templates/workspace-root/skills/CLAUDE.md +6 -1
- package/templates/workspace-root/skills/README.md +17 -2
- package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
- package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
- package/templates/workspace-root/skills/client-latest/SKILL.md +124 -82
- package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
- package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
- package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
|
@@ -0,0 +1,951 @@
|
|
|
1
|
+
import { access, readdir, readFile, writeFile } from "node:fs/promises";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { GOOGLE_SERVICE_ACCOUNT_KEY_ENV } from "./client-drive.js";
|
|
4
|
+
import { GoogleServiceAccountAuthError, getServiceAccountAccessToken, } from "./google-service-account.js";
|
|
5
|
+
import { SLUG_PATTERN } from "./new-client.js";
|
|
6
|
+
import { PORTAL_ADMIN_SECRET_ENV, PortalRequestError, portalReadTriageRecords, } from "./portal-admin.js";
|
|
7
|
+
// The gate tooling for the email-triage rollout (agents/email-*-triage/sop.md
|
|
8
|
+
// + skills/email-triage-rollout). Every number a gate needs comes out of the
|
|
9
|
+
// client's classification record — the one durable population the SOP
|
|
10
|
+
// samples from — so two technicians reading the same record get the same
|
|
11
|
+
// report, the same sample, the same verdict shape.
|
|
12
|
+
//
|
|
13
|
+
// The record lives in the portal (`triage_classifications`, read over the
|
|
14
|
+
// admin API) for a client whose agent is registered as a triage agent, and in
|
|
15
|
+
// a per-client Google Sheet for the clients from before that move. Both
|
|
16
|
+
// sources arrive as the same header + rows table, so every gate computes the
|
|
17
|
+
// same way whichever one it read.
|
|
18
|
+
//
|
|
19
|
+
// PII posture is inherited from the record sheet itself: sender DOMAIN and
|
|
20
|
+
// message ID only. Nothing here ever fetches a message body or a subject; the
|
|
21
|
+
// technician opens each sampled message_id in the client's own mailbox.
|
|
22
|
+
export const SHEETS_API_BASE_URL = "https://sheets.googleapis.com/v4/spreadsheets";
|
|
23
|
+
/** Read-only — this tool never writes to a client's sheet. */
|
|
24
|
+
export const SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets.readonly";
|
|
25
|
+
export const TRIAGE_STAGES = ["soak", "label", "organize", "full"];
|
|
26
|
+
export const TRIAGE_LANES = ["Critical", "Today", "Later", "Noise"];
|
|
27
|
+
/** Gmail template: `disposition` → lane. `action` splits on `priority` (see laneFor). */
|
|
28
|
+
export const GMAIL_LANE_BY_DISPOSITION = {
|
|
29
|
+
action: "Today",
|
|
30
|
+
reply_draft: "Today",
|
|
31
|
+
file: "Later",
|
|
32
|
+
archive: "Noise",
|
|
33
|
+
};
|
|
34
|
+
/** `action` mail with one of these priorities is Critical rather than Today. */
|
|
35
|
+
export const CRITICAL_PRIORITIES = ["critical", "urgent", "high"];
|
|
36
|
+
/**
|
|
37
|
+
* Outlook template: `category` → lane, keyed on the normalised category name
|
|
38
|
+
* (lower-case, letters and digits only) so "New Lead" and "NewLead" agree.
|
|
39
|
+
* Categories a client adds at gate A are passed in via `laneOverrides`.
|
|
40
|
+
*/
|
|
41
|
+
export const OUTLOOK_LANE_BY_CATEGORY = {
|
|
42
|
+
irsnotice: "Critical",
|
|
43
|
+
suspiciousfinancial: "Critical",
|
|
44
|
+
newlead: "Today",
|
|
45
|
+
clienttaxmatter: "Today",
|
|
46
|
+
clientinsurancematter: "Today",
|
|
47
|
+
invoice: "Today",
|
|
48
|
+
notifications: "Noise",
|
|
49
|
+
newsletter: "Noise",
|
|
50
|
+
spam: "Noise",
|
|
51
|
+
salespitch: "Noise",
|
|
52
|
+
professionaldevelopment: "Later",
|
|
53
|
+
};
|
|
54
|
+
/** Outlook `urgency` / `importance` values that lift a message to Critical. */
|
|
55
|
+
export const CRITICAL_URGENCIES = ["high", "urgent", "critical"];
|
|
56
|
+
/** Gate thresholds, exactly as sop.md states them. Change the SOP and this together. */
|
|
57
|
+
export const TRIAGE_GATES = {
|
|
58
|
+
/** Gate A: recorded classifications before a taxonomy can be proposed. */
|
|
59
|
+
soakMinRows: 200,
|
|
60
|
+
/** Gate A: review-lane share above which the taxonomy does not fit the mail. */
|
|
61
|
+
soakMaxReviewLaneRate: 0.2,
|
|
62
|
+
/** Gates B and C: sample size drawn from the current stage's rows. */
|
|
63
|
+
sampleSize: 50,
|
|
64
|
+
/** Gates B and C: minimum share of sampled rows with the correct label/category. */
|
|
65
|
+
minPrecision: 0.9,
|
|
66
|
+
/** Gates B and C: maximum review-lane share across the stage window. */
|
|
67
|
+
maxReviewLaneRate: 0.15,
|
|
68
|
+
};
|
|
69
|
+
export const GMAIL_HEADERS = [
|
|
70
|
+
"recorded_at",
|
|
71
|
+
"stage",
|
|
72
|
+
"message_id",
|
|
73
|
+
"thread_id",
|
|
74
|
+
"sender_domain",
|
|
75
|
+
"disposition",
|
|
76
|
+
"priority",
|
|
77
|
+
"confidence",
|
|
78
|
+
"labels",
|
|
79
|
+
"review_lane",
|
|
80
|
+
];
|
|
81
|
+
export const OUTLOOK_HEADERS = [
|
|
82
|
+
"recorded_at",
|
|
83
|
+
"stage",
|
|
84
|
+
"message_id",
|
|
85
|
+
"conversation_id",
|
|
86
|
+
"sender_domain",
|
|
87
|
+
"category",
|
|
88
|
+
"importance",
|
|
89
|
+
"urgency",
|
|
90
|
+
"confidence",
|
|
91
|
+
"needs_review",
|
|
92
|
+
"reply_recommended",
|
|
93
|
+
"flagged",
|
|
94
|
+
];
|
|
95
|
+
// ─── Loading ───────────────────────────────────────────────────────────────
|
|
96
|
+
function assertSlug(slug) {
|
|
97
|
+
if (slug.startsWith("client-")) {
|
|
98
|
+
throw new Error(`pass the bare slug ("${slug.slice("client-".length)}"), not "${slug}" — the repo prefix is added for you`);
|
|
99
|
+
}
|
|
100
|
+
if (!SLUG_PATTERN.test(slug)) {
|
|
101
|
+
throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
/** Minimal RFC 4180 reader: quoted fields, doubled quotes, CRLF or LF. Exported for tests. */
|
|
105
|
+
export function parseCsv(text) {
|
|
106
|
+
const rows = [];
|
|
107
|
+
let row = [];
|
|
108
|
+
let field = "";
|
|
109
|
+
let inQuotes = false;
|
|
110
|
+
const src = text.startsWith("") ? text.slice(1) : text;
|
|
111
|
+
for (let i = 0; i < src.length; i += 1) {
|
|
112
|
+
const ch = src[i];
|
|
113
|
+
if (inQuotes) {
|
|
114
|
+
if (ch === '"') {
|
|
115
|
+
if (src[i + 1] === '"') {
|
|
116
|
+
field += '"';
|
|
117
|
+
i += 1;
|
|
118
|
+
}
|
|
119
|
+
else {
|
|
120
|
+
inQuotes = false;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
else {
|
|
124
|
+
field += ch;
|
|
125
|
+
}
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
if (ch === '"')
|
|
129
|
+
inQuotes = true;
|
|
130
|
+
else if (ch === ",") {
|
|
131
|
+
row.push(field);
|
|
132
|
+
field = "";
|
|
133
|
+
}
|
|
134
|
+
else if (ch === "\n" || ch === "\r") {
|
|
135
|
+
if (ch === "\r" && src[i + 1] === "\n")
|
|
136
|
+
i += 1;
|
|
137
|
+
row.push(field);
|
|
138
|
+
rows.push(row);
|
|
139
|
+
row = [];
|
|
140
|
+
field = "";
|
|
141
|
+
}
|
|
142
|
+
else
|
|
143
|
+
field += ch;
|
|
144
|
+
}
|
|
145
|
+
if (field.length > 0 || row.length > 0) {
|
|
146
|
+
row.push(field);
|
|
147
|
+
rows.push(row);
|
|
148
|
+
}
|
|
149
|
+
return rows.filter((r) => r.some((cell) => cell.trim() !== ""));
|
|
150
|
+
}
|
|
151
|
+
const SHEET_ID_IN_URL = /\/spreadsheets\/d\/([\w-]+)/;
|
|
152
|
+
/**
|
|
153
|
+
* Find the record sheet ID in the client repo's exported workflow JSON: the
|
|
154
|
+
* Google Sheets append node whose documentId is a real spreadsheet URL (not
|
|
155
|
+
* the `REPLACE_ME_RECORD_SHEET_ID` placeholder). Exported for tests.
|
|
156
|
+
*/
|
|
157
|
+
export async function resolveRecordSheetId(workspaceDir, slug) {
|
|
158
|
+
const workflowsDir = join(workspaceDir, "clients", `client-${slug}`, "workflows");
|
|
159
|
+
let files;
|
|
160
|
+
try {
|
|
161
|
+
files = (await readdir(workflowsDir)).filter((f) => f.endsWith(".json"));
|
|
162
|
+
}
|
|
163
|
+
catch {
|
|
164
|
+
return undefined;
|
|
165
|
+
}
|
|
166
|
+
for (const file of files.sort()) {
|
|
167
|
+
let parsed;
|
|
168
|
+
try {
|
|
169
|
+
parsed = JSON.parse(await readFile(join(workflowsDir, file), "utf8"));
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
continue;
|
|
173
|
+
}
|
|
174
|
+
const nodes = parsed?.nodes ?? [];
|
|
175
|
+
for (const node of nodes) {
|
|
176
|
+
if (node.type !== "n8n-nodes-base.googleSheets")
|
|
177
|
+
continue;
|
|
178
|
+
const params = node.parameters;
|
|
179
|
+
const value = params?.documentId?.value ?? "";
|
|
180
|
+
if (value.includes("REPLACE_ME"))
|
|
181
|
+
continue;
|
|
182
|
+
const match = value.match(SHEET_ID_IN_URL);
|
|
183
|
+
if (match)
|
|
184
|
+
return match[1];
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
return undefined;
|
|
188
|
+
}
|
|
189
|
+
async function fetchSheetValues(sheetId, options) {
|
|
190
|
+
const key = options.serviceAccountKey ?? process.env[GOOGLE_SERVICE_ACCOUNT_KEY_ENV];
|
|
191
|
+
if (!key) {
|
|
192
|
+
throw new GoogleServiceAccountAuthError(`Google service-account key required to read the record sheet — set ${GOOGLE_SERVICE_ACCOUNT_KEY_ENV} ` +
|
|
193
|
+
"(the full key JSON), pass serviceAccountKey, or use --csv with a downloaded export");
|
|
194
|
+
}
|
|
195
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
196
|
+
const now = options.now ?? Date.now;
|
|
197
|
+
const { accessToken, clientEmail } = await getServiceAccountAccessToken(key, SHEETS_SCOPE, fetchImpl, now);
|
|
198
|
+
const url = new URL(`${SHEETS_API_BASE_URL}/${sheetId}/values/${encodeURIComponent("A:Z")}`);
|
|
199
|
+
url.searchParams.set("majorDimension", "ROWS");
|
|
200
|
+
const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${accessToken}` } });
|
|
201
|
+
if (res.status === 403 || res.status === 404) {
|
|
202
|
+
throw new GoogleServiceAccountAuthError(`Google Sheets refused spreadsheet ${sheetId} (HTTP ${res.status}) — share the record sheet ` +
|
|
203
|
+
`with ${clientEmail} as Viewer (sop.md § Preconditions), or use --csv with a downloaded export.`);
|
|
204
|
+
}
|
|
205
|
+
if (!res.ok) {
|
|
206
|
+
throw new Error(`Sheets values.get on ${sheetId} failed: HTTP ${res.status}`);
|
|
207
|
+
}
|
|
208
|
+
const body = (await res.json());
|
|
209
|
+
return body.values ?? [];
|
|
210
|
+
}
|
|
211
|
+
function normaliseKey(value) {
|
|
212
|
+
return value.toLowerCase().replace(/[^a-z0-9]/g, "");
|
|
213
|
+
}
|
|
214
|
+
/** The public map keyed the way the template writes it; lookups go through normaliseKey. */
|
|
215
|
+
const GMAIL_LANE_BY_NORMALISED_DISPOSITION = Object.fromEntries(Object.entries(GMAIL_LANE_BY_DISPOSITION).map(([k, v]) => [normaliseKey(k), v]));
|
|
216
|
+
/** Which template wrote this header row. Exported for the backfill. */
|
|
217
|
+
export function detectProvider(header) {
|
|
218
|
+
const set = new Set(header.map((h) => h.trim()));
|
|
219
|
+
if (set.has("disposition") && set.has("thread_id"))
|
|
220
|
+
return "gmail";
|
|
221
|
+
if (set.has("category") && set.has("conversation_id"))
|
|
222
|
+
return "outlook";
|
|
223
|
+
throw new Error("this is not an email-triage record sheet — row 1 must be the template's header row. " +
|
|
224
|
+
`Gmail: ${GMAIL_HEADERS.join(" | ")}. Outlook: ${OUTLOOK_HEADERS.join(" | ")}. ` +
|
|
225
|
+
`Got: ${header.join(" | ") || "(empty)"}`);
|
|
226
|
+
}
|
|
227
|
+
/** Exported for tests and for the SOP's lane table. */
|
|
228
|
+
export function laneFor(provider, cells, laneOverrides = {}) {
|
|
229
|
+
const overrides = {};
|
|
230
|
+
for (const [k, v] of Object.entries(laneOverrides))
|
|
231
|
+
overrides[normaliseKey(k)] = v;
|
|
232
|
+
if (provider === "gmail") {
|
|
233
|
+
const disposition = normaliseKey(cells.disposition ?? "");
|
|
234
|
+
const override = overrides[disposition];
|
|
235
|
+
if (override)
|
|
236
|
+
return { lane: override, mapped: true };
|
|
237
|
+
const base = GMAIL_LANE_BY_NORMALISED_DISPOSITION[disposition];
|
|
238
|
+
if (!base)
|
|
239
|
+
return { lane: "Later", mapped: false };
|
|
240
|
+
if (disposition === "action" &&
|
|
241
|
+
CRITICAL_PRIORITIES.includes(normaliseKey(cells.priority ?? ""))) {
|
|
242
|
+
return { lane: "Critical", mapped: true };
|
|
243
|
+
}
|
|
244
|
+
return { lane: base, mapped: true };
|
|
245
|
+
}
|
|
246
|
+
const category = normaliseKey(cells.category ?? "");
|
|
247
|
+
const override = overrides[category];
|
|
248
|
+
const base = override ?? OUTLOOK_LANE_BY_CATEGORY[category];
|
|
249
|
+
const urgent = CRITICAL_URGENCIES.includes(normaliseKey(cells.urgency ?? "")) ||
|
|
250
|
+
CRITICAL_URGENCIES.includes(normaliseKey(cells.importance ?? ""));
|
|
251
|
+
if (!base)
|
|
252
|
+
return { lane: urgent ? "Critical" : "Later", mapped: false };
|
|
253
|
+
if (urgent && base !== "Noise")
|
|
254
|
+
return { lane: "Critical", mapped: true };
|
|
255
|
+
return { lane: base, mapped: true };
|
|
256
|
+
}
|
|
257
|
+
function toRecordRows(provider, header, body, laneOverrides) {
|
|
258
|
+
const keys = header.map((h) => h.trim());
|
|
259
|
+
const unmapped = new Set();
|
|
260
|
+
const rows = [];
|
|
261
|
+
for (const line of body) {
|
|
262
|
+
const cells = {};
|
|
263
|
+
keys.forEach((k, i) => {
|
|
264
|
+
cells[k] = (line[i] ?? "").trim();
|
|
265
|
+
});
|
|
266
|
+
const recordedAt = new Date(cells.recorded_at ?? "");
|
|
267
|
+
if (Number.isNaN(recordedAt.getTime()) || !cells.message_id)
|
|
268
|
+
continue; // not a record row
|
|
269
|
+
const internal = provider === "gmail" ? (cells.disposition ?? "") : (cells.category ?? "");
|
|
270
|
+
const reviewCell = provider === "gmail" ? cells.review_lane : cells.needs_review;
|
|
271
|
+
const { lane, mapped } = laneFor(provider, cells, laneOverrides);
|
|
272
|
+
if (!mapped && internal)
|
|
273
|
+
unmapped.add(internal);
|
|
274
|
+
rows.push({
|
|
275
|
+
recordedAt,
|
|
276
|
+
stage: (cells.stage ?? "").toLowerCase(),
|
|
277
|
+
messageId: cells.message_id,
|
|
278
|
+
senderDomain: (cells.sender_domain ?? "").toLowerCase(),
|
|
279
|
+
internal,
|
|
280
|
+
labels: provider === "gmail"
|
|
281
|
+
? (cells.labels ?? "")
|
|
282
|
+
.split("|")
|
|
283
|
+
.map((l) => l.trim())
|
|
284
|
+
.filter(Boolean)
|
|
285
|
+
: [],
|
|
286
|
+
confidence: cells.confidence ?? "",
|
|
287
|
+
reviewLane: (reviewCell ?? "").toLowerCase() === "yes",
|
|
288
|
+
lane,
|
|
289
|
+
});
|
|
290
|
+
}
|
|
291
|
+
return { rows, unmapped };
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* The record SHEET as a table: a CSV export, `--sheet`, or the sheet the
|
|
295
|
+
* client repo's workflow export writes to. Never the portal — the backfill
|
|
296
|
+
* reads a sheet with this. `note` says why the portal was not the source.
|
|
297
|
+
*/
|
|
298
|
+
export async function readRecordSheetTable(slug, options, note) {
|
|
299
|
+
assertSlug(slug);
|
|
300
|
+
const suffix = note ? ` (${note})` : "";
|
|
301
|
+
if (options.csv) {
|
|
302
|
+
return {
|
|
303
|
+
table: parseCsv(await readFile(options.csv, "utf8")),
|
|
304
|
+
source: `CSV export ${options.csv}`,
|
|
305
|
+
};
|
|
306
|
+
}
|
|
307
|
+
const sheetId = options.sheetId ?? (await resolveRecordSheetId(options.workspaceDir ?? ".", slug));
|
|
308
|
+
if (!sheetId) {
|
|
309
|
+
throw new Error(`no record found for "${slug}"${note ? ` — ${note}` : ""}, and clients/client-${slug}/workflows/*.json ` +
|
|
310
|
+
"has no Google Sheets node with a real spreadsheet URL (still REPLACE_ME_RECORD_SHEET_ID?). " +
|
|
311
|
+
"Pass --sheet <id> or --csv <file>.");
|
|
312
|
+
}
|
|
313
|
+
return {
|
|
314
|
+
table: await fetchSheetValues(sheetId, options),
|
|
315
|
+
source: `record sheet ${sheetId}${suffix}`,
|
|
316
|
+
};
|
|
317
|
+
}
|
|
318
|
+
const PORTAL_PAGE_LIMIT = 5000;
|
|
319
|
+
/** 500k rows — far past any client; only there so a server bug cannot loop forever. */
|
|
320
|
+
const PORTAL_MAX_PAGES = 100;
|
|
321
|
+
/**
|
|
322
|
+
* The record from the portal, when the org has a triage agent. A 404 (no such
|
|
323
|
+
* org, or no triage agent under it) is "not in the portal" — the caller falls
|
|
324
|
+
* back to the sheet. Any other refusal stops the command.
|
|
325
|
+
*/
|
|
326
|
+
async function readPortalTable(slug, options, window) {
|
|
327
|
+
if (options.portal === false)
|
|
328
|
+
return { skipped: "portal not checked" };
|
|
329
|
+
const portalOptions = {
|
|
330
|
+
...options.portal,
|
|
331
|
+
...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
|
|
332
|
+
};
|
|
333
|
+
if (!(portalOptions.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV])) {
|
|
334
|
+
return { skipped: `portal not checked: ${PORTAL_ADMIN_SECRET_ENV} is not set` };
|
|
335
|
+
}
|
|
336
|
+
const rows = [];
|
|
337
|
+
let after;
|
|
338
|
+
let meta;
|
|
339
|
+
for (let page = 0; page < PORTAL_MAX_PAGES; page += 1) {
|
|
340
|
+
let result;
|
|
341
|
+
try {
|
|
342
|
+
result = await portalReadTriageRecords({
|
|
343
|
+
org: slug,
|
|
344
|
+
agent: options.agent,
|
|
345
|
+
since: window.since,
|
|
346
|
+
until: window.until,
|
|
347
|
+
after,
|
|
348
|
+
limit: PORTAL_PAGE_LIMIT,
|
|
349
|
+
}, portalOptions);
|
|
350
|
+
}
|
|
351
|
+
catch (error) {
|
|
352
|
+
if (error instanceof PortalRequestError && error.status === 404) {
|
|
353
|
+
return { skipped: `the portal has no triage agent for ${slug}` };
|
|
354
|
+
}
|
|
355
|
+
throw error;
|
|
356
|
+
}
|
|
357
|
+
meta = { org: result.org, agent: result.agent, provider: result.provider };
|
|
358
|
+
rows.push(...result.rows);
|
|
359
|
+
if (!result.next)
|
|
360
|
+
break;
|
|
361
|
+
after = result.next;
|
|
362
|
+
}
|
|
363
|
+
if (!meta)
|
|
364
|
+
return { skipped: `the portal has no triage agent for ${slug}` };
|
|
365
|
+
const header = [...(meta.provider === "gmail" ? GMAIL_HEADERS : OUTLOOK_HEADERS)];
|
|
366
|
+
return {
|
|
367
|
+
found: {
|
|
368
|
+
table: [header, ...rows.map((row) => header.map((key) => row[key] ?? ""))],
|
|
369
|
+
source: `portal ${meta.org}/${meta.agent} (triage_classifications)`,
|
|
370
|
+
},
|
|
371
|
+
};
|
|
372
|
+
}
|
|
373
|
+
function parseInstant(value, flag) {
|
|
374
|
+
if (value === undefined)
|
|
375
|
+
return undefined;
|
|
376
|
+
const date = value instanceof Date ? value : new Date(value);
|
|
377
|
+
if (Number.isNaN(date.getTime()))
|
|
378
|
+
throw new Error(`${flag} must be an ISO date — got "${value}"`);
|
|
379
|
+
return date;
|
|
380
|
+
}
|
|
381
|
+
function windowFilterOf(options) {
|
|
382
|
+
return {
|
|
383
|
+
since: parseInstant(options.since, "--since"),
|
|
384
|
+
until: parseInstant(options.until, "--until"),
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
function describeWindowFilter(window) {
|
|
388
|
+
const parts = [
|
|
389
|
+
window.since ? `≥ ${window.since.toISOString()}` : "",
|
|
390
|
+
window.until ? `< ${window.until.toISOString()}` : "",
|
|
391
|
+
].filter(Boolean);
|
|
392
|
+
return parts.length ? `, recorded_at ${parts.join(", ")}` : "";
|
|
393
|
+
}
|
|
394
|
+
async function loadRecords(slug, options) {
|
|
395
|
+
assertSlug(slug);
|
|
396
|
+
const window = windowFilterOf(options);
|
|
397
|
+
let record;
|
|
398
|
+
if (options.csv || options.sheetId) {
|
|
399
|
+
record = await readRecordSheetTable(slug, options);
|
|
400
|
+
}
|
|
401
|
+
else {
|
|
402
|
+
const portal = await readPortalTable(slug, options, window);
|
|
403
|
+
record =
|
|
404
|
+
"found" in portal ? portal.found : await readRecordSheetTable(slug, options, portal.skipped);
|
|
405
|
+
}
|
|
406
|
+
const { table } = record;
|
|
407
|
+
const source = `${record.source}${describeWindowFilter(window)}`;
|
|
408
|
+
if (table.length === 0) {
|
|
409
|
+
throw new Error(`${source} is empty — the header row must be row 1 (sop.md § Preconditions)`);
|
|
410
|
+
}
|
|
411
|
+
const [header, ...body] = table;
|
|
412
|
+
const provider = detectProvider(header);
|
|
413
|
+
const expected = new Set(provider === "gmail" ? GMAIL_HEADERS : OUTLOOK_HEADERS);
|
|
414
|
+
const unexpectedHeaders = header.map((h) => h.trim()).filter((h) => h && !expected.has(h));
|
|
415
|
+
const { rows, unmapped } = toRecordRows(provider, header, body, options.laneOverrides);
|
|
416
|
+
const inWindow = rows.filter((r) => (!window.since || r.recordedAt >= window.since) &&
|
|
417
|
+
(!window.until || r.recordedAt < window.until));
|
|
418
|
+
inWindow.sort((a, b) => a.recordedAt.getTime() - b.recordedAt.getTime());
|
|
419
|
+
return {
|
|
420
|
+
provider,
|
|
421
|
+
rows: inWindow,
|
|
422
|
+
source,
|
|
423
|
+
unexpectedHeaders,
|
|
424
|
+
unmappedInternal: [...unmapped].sort(),
|
|
425
|
+
};
|
|
426
|
+
}
|
|
427
|
+
function windowOf(rows) {
|
|
428
|
+
if (rows.length === 0)
|
|
429
|
+
return { from: "", to: "", days: 0 };
|
|
430
|
+
const from = rows[0].recordedAt;
|
|
431
|
+
const to = rows[rows.length - 1].recordedAt;
|
|
432
|
+
const days = Math.max(1, Math.ceil((to.getTime() - from.getTime()) / 86_400_000) || 1);
|
|
433
|
+
return { from: from.toISOString(), to: to.toISOString(), days };
|
|
434
|
+
}
|
|
435
|
+
function dayKey(d) {
|
|
436
|
+
return d.toISOString().slice(0, 10);
|
|
437
|
+
}
|
|
438
|
+
function countBy(items, key) {
|
|
439
|
+
const counts = new Map();
|
|
440
|
+
for (const item of items) {
|
|
441
|
+
const k = key(item);
|
|
442
|
+
counts.set(k, (counts.get(k) ?? 0) + 1);
|
|
443
|
+
}
|
|
444
|
+
return counts;
|
|
445
|
+
}
|
|
446
|
+
function share(n, total) {
|
|
447
|
+
return total === 0 ? 0 : n / total;
|
|
448
|
+
}
|
|
449
|
+
function pct(value) {
|
|
450
|
+
return `${(value * 100).toFixed(1)}%`;
|
|
451
|
+
}
|
|
452
|
+
function mdTable(headers, rows) {
|
|
453
|
+
const line = (cells) => `| ${cells.map(String).join(" | ")} |`;
|
|
454
|
+
return [line(headers), `|${headers.map(() => "---").join("|")}|`, ...rows.map(line)].join("\n");
|
|
455
|
+
}
|
|
456
|
+
function reviewLaneRate(rows) {
|
|
457
|
+
return share(rows.filter((r) => r.reviewLane).length, rows.length);
|
|
458
|
+
}
|
|
459
|
+
function laneCounts(rows) {
|
|
460
|
+
const counts = countBy(rows, (r) => r.lane);
|
|
461
|
+
return TRIAGE_LANES.map((lane) => ({
|
|
462
|
+
lane,
|
|
463
|
+
count: counts.get(lane) ?? 0,
|
|
464
|
+
share: share(counts.get(lane) ?? 0, rows.length),
|
|
465
|
+
}));
|
|
466
|
+
}
|
|
467
|
+
/** Refuse to overwrite an evidence file that already exists (same day, same client). */
|
|
468
|
+
async function writeEvidence(path, content, force) {
|
|
469
|
+
if (!force) {
|
|
470
|
+
try {
|
|
471
|
+
await access(path);
|
|
472
|
+
throw new Error(`${path} already exists — today's evidence file is already written. Re-run with --force to replace it.`);
|
|
473
|
+
}
|
|
474
|
+
catch (error) {
|
|
475
|
+
if (error instanceof Error && error.message.includes("already exists"))
|
|
476
|
+
throw error;
|
|
477
|
+
}
|
|
478
|
+
}
|
|
479
|
+
await writeFile(path, content, "utf8");
|
|
480
|
+
}
|
|
481
|
+
async function evidenceDir(workspaceDir, slug) {
|
|
482
|
+
const dir = join(workspaceDir, "clients", `client-${slug}`, "evidence");
|
|
483
|
+
try {
|
|
484
|
+
await access(dir);
|
|
485
|
+
}
|
|
486
|
+
catch {
|
|
487
|
+
throw new Error(`${dir} does not exist — scaffold the build repo first (ia new-client ${slug}); evidence/ is part of the template`);
|
|
488
|
+
}
|
|
489
|
+
return dir;
|
|
490
|
+
}
|
|
491
|
+
export async function triageSoakReport(slug, options = {}) {
|
|
492
|
+
const stage = options.stage ?? "soak";
|
|
493
|
+
if (!TRIAGE_STAGES.includes(stage)) {
|
|
494
|
+
throw new Error(`--stage must be one of ${TRIAGE_STAGES.join(" / ")} — got "${String(stage)}"`);
|
|
495
|
+
}
|
|
496
|
+
const loaded = await loadRecords(slug, options);
|
|
497
|
+
const rows = loaded.rows.filter((r) => r.stage === stage);
|
|
498
|
+
const total = rows.length;
|
|
499
|
+
const window = windowOf(rows);
|
|
500
|
+
const perDayCounts = countBy(rows, (r) => dayKey(r.recordedAt));
|
|
501
|
+
const days = [...perDayCounts.entries()].sort((a, b) => a[1] - b[1]);
|
|
502
|
+
const quietest = days[0] ? { day: days[0][0], count: days[0][1] } : null;
|
|
503
|
+
const busiest = days.at(-1)
|
|
504
|
+
? { day: days.at(-1)?.[0] ?? "", count: days.at(-1)?.[1] ?? 0 }
|
|
505
|
+
: null;
|
|
506
|
+
const domainCounts = [...countBy(rows, (r) => r.senderDomain || "(none)").entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
|
|
507
|
+
const top = domainCounts.slice(0, 20);
|
|
508
|
+
const tail = domainCounts.slice(20);
|
|
509
|
+
const senderDomains = top.map(([domain, count]) => ({
|
|
510
|
+
domain,
|
|
511
|
+
count,
|
|
512
|
+
share: share(count, total),
|
|
513
|
+
}));
|
|
514
|
+
const longTail = { domains: tail.length, messages: tail.reduce((s, [, n]) => s + n, 0) };
|
|
515
|
+
const laneByInternal = (internal) => {
|
|
516
|
+
const counts = countBy(rows.filter((r) => r.internal === internal), (r) => r.lane);
|
|
517
|
+
return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
|
|
518
|
+
};
|
|
519
|
+
const mix = [...countBy(rows, (r) => r.internal || "(blank)").entries()]
|
|
520
|
+
.sort((a, b) => b[1] - a[1])
|
|
521
|
+
.map(([internal, count]) => ({
|
|
522
|
+
internal,
|
|
523
|
+
count,
|
|
524
|
+
share: share(count, total),
|
|
525
|
+
lane: internal === "(blank)" ? "Later" : laneByInternal(internal),
|
|
526
|
+
}));
|
|
527
|
+
const lanes = laneCounts(rows);
|
|
528
|
+
const reviewRate = reviewLaneRate(rows);
|
|
529
|
+
const actionRows = rows.filter((r) => r.lane === "Critical" || r.lane === "Today").length;
|
|
530
|
+
const actionLaneLoadPerDay = window.days === 0 ? 0 : actionRows / window.days;
|
|
531
|
+
// Proposed taxonomy: Gmail = topic labels (a message can carry several);
|
|
532
|
+
// Outlook = categories. Each with the lane its messages mostly fall into.
|
|
533
|
+
let taxonomy;
|
|
534
|
+
if (loaded.provider === "gmail") {
|
|
535
|
+
const labelLane = new Map();
|
|
536
|
+
for (const r of rows) {
|
|
537
|
+
for (const label of r.labels) {
|
|
538
|
+
const m = labelLane.get(label) ?? new Map();
|
|
539
|
+
m.set(r.lane, (m.get(r.lane) ?? 0) + 1);
|
|
540
|
+
labelLane.set(label, m);
|
|
541
|
+
}
|
|
542
|
+
}
|
|
543
|
+
taxonomy = [...labelLane.entries()]
|
|
544
|
+
.map(([name, m]) => {
|
|
545
|
+
const count = [...m.values()].reduce((s, n) => s + n, 0);
|
|
546
|
+
const lane = [...m.entries()].sort((a, b) => b[1] - a[1])[0][0];
|
|
547
|
+
return { name, count, share: share(count, total), lane };
|
|
548
|
+
})
|
|
549
|
+
.sort((a, b) => b.count - a.count);
|
|
550
|
+
}
|
|
551
|
+
else {
|
|
552
|
+
taxonomy = mix
|
|
553
|
+
.filter((m) => m.internal !== "(blank)")
|
|
554
|
+
.map((m) => ({ name: m.internal, count: m.count, share: m.share, lane: m.lane }));
|
|
555
|
+
}
|
|
556
|
+
const openQuestions = [];
|
|
557
|
+
const unlabelled = loaded.provider === "gmail" ? rows.filter((r) => r.labels.length === 0) : [];
|
|
558
|
+
if (unlabelled.length > 0) {
|
|
559
|
+
const topUnlabelled = [...countBy(unlabelled, (r) => r.senderDomain || "(none)").entries()]
|
|
560
|
+
.sort((a, b) => b[1] - a[1])
|
|
561
|
+
.slice(0, 5)
|
|
562
|
+
.map(([d, n]) => `${d} (${n})`);
|
|
563
|
+
openQuestions.push(`${unlabelled.length} messages carry no topic label — is a category missing? Top senders: ${topUnlabelled.join(", ")}.`);
|
|
564
|
+
}
|
|
565
|
+
for (const internal of loaded.unmappedInternal) {
|
|
566
|
+
openQuestions.push(`"${internal}" has no client-facing lane yet (counted as Later). Add it with --lane "${internal}=Critical|Today|Later|Noise".`);
|
|
567
|
+
}
|
|
568
|
+
const heavyTail = tail.filter(([, n]) => n >= 10);
|
|
569
|
+
if (heavyTail.length > 0) {
|
|
570
|
+
openQuestions.push(`${heavyTail.length} sender domain(s) below the top 20 still sent 10+ messages — check each has a home in the taxonomy.`);
|
|
571
|
+
}
|
|
572
|
+
if (loaded.unexpectedHeaders.length > 0) {
|
|
573
|
+
openQuestions.push(`The sheet has columns the template does not write (${loaded.unexpectedHeaders.join(", ")}) — was it hand-edited?`);
|
|
574
|
+
}
|
|
575
|
+
openQuestions.push("Sender roster gaps: which VIPs / key phrases from the client's list did NOT appear in the window?");
|
|
576
|
+
openQuestions.push("Mail whose importance depends on business context we do not have — list the message_ids to ask about.");
|
|
577
|
+
const rowsOk = total >= TRIAGE_GATES.soakMinRows;
|
|
578
|
+
const reviewLaneOk = reviewRate <= TRIAGE_GATES.soakMaxReviewLaneRate;
|
|
579
|
+
const blockers = [];
|
|
580
|
+
if (!rowsOk)
|
|
581
|
+
blockers.push(`${total} recorded classifications — gate A needs ≥ ${TRIAGE_GATES.soakMinRows}`);
|
|
582
|
+
if (!reviewLaneOk) {
|
|
583
|
+
blockers.push(`review lane ${pct(reviewRate)} — above ${pct(TRIAGE_GATES.soakMaxReviewLaneRate)}: the taxonomy does not fit the mail yet. Fix the taxonomy, never the confidence floor.`);
|
|
584
|
+
}
|
|
585
|
+
blockers.push("client approval of the lane names + taxonomy, in writing, in their channel (manual)");
|
|
586
|
+
if (loaded.provider === "gmail") {
|
|
587
|
+
blockers.push("Gmail labels created and every REPLACE_ME_LABEL_ID_* filled (manual)");
|
|
588
|
+
}
|
|
589
|
+
else {
|
|
590
|
+
blockers.push("destination folders created, every REPLACE_ME_OUTLOOK_FOLDER_ID_* filled, HARD_BLOCK_CATEGORIES read out to the client (manual)");
|
|
591
|
+
}
|
|
592
|
+
const gateA = { rowsOk, reviewLaneOk, ready: rowsOk && reviewLaneOk, blockers };
|
|
593
|
+
const now = options.now ?? Date.now;
|
|
594
|
+
const today = new Date(now()).toISOString().slice(0, 10);
|
|
595
|
+
const markdown = renderSoakReport({
|
|
596
|
+
slug,
|
|
597
|
+
provider: loaded.provider,
|
|
598
|
+
source: loaded.source,
|
|
599
|
+
stage,
|
|
600
|
+
window,
|
|
601
|
+
volume: { total, perDay: window.days === 0 ? 0 : total / window.days, busiest, quietest },
|
|
602
|
+
senderDomains,
|
|
603
|
+
longTail,
|
|
604
|
+
mix,
|
|
605
|
+
lanes,
|
|
606
|
+
reviewLaneRate: reviewRate,
|
|
607
|
+
actionLaneLoadPerDay,
|
|
608
|
+
taxonomy,
|
|
609
|
+
openQuestions,
|
|
610
|
+
gateA,
|
|
611
|
+
today,
|
|
612
|
+
});
|
|
613
|
+
const result = {
|
|
614
|
+
slug,
|
|
615
|
+
provider: loaded.provider,
|
|
616
|
+
source: loaded.source,
|
|
617
|
+
stage,
|
|
618
|
+
window,
|
|
619
|
+
volume: { total, perDay: window.days === 0 ? 0 : total / window.days, busiest, quietest },
|
|
620
|
+
senderDomains,
|
|
621
|
+
longTail,
|
|
622
|
+
mix,
|
|
623
|
+
lanes,
|
|
624
|
+
reviewLaneRate: reviewRate,
|
|
625
|
+
actionLaneLoadPerDay,
|
|
626
|
+
taxonomy,
|
|
627
|
+
openQuestions,
|
|
628
|
+
gateA,
|
|
629
|
+
markdown,
|
|
630
|
+
};
|
|
631
|
+
if (options.write !== false) {
|
|
632
|
+
const dir = await evidenceDir(options.workspaceDir ?? ".", slug);
|
|
633
|
+
const path = join(dir, `${today}-email-triage-soak-report.md`);
|
|
634
|
+
await writeEvidence(path, markdown, options.force === true);
|
|
635
|
+
result.evidencePath = path;
|
|
636
|
+
}
|
|
637
|
+
return result;
|
|
638
|
+
}
|
|
639
|
+
function renderSoakReport(r) {
|
|
640
|
+
const check = (ok) => (ok ? "✅" : "❌");
|
|
641
|
+
const parts = [];
|
|
642
|
+
parts.push(`# Email triage — soak report — ${r.slug} — ${r.today}`);
|
|
643
|
+
parts.push("");
|
|
644
|
+
parts.push(`> Generated by \`ia triage soak-report\` from ${r.source} (${r.provider} template, stage \`${r.stage}\` rows only). ` +
|
|
645
|
+
"Sender domains and message IDs only — no subjects, no bodies, no addresses. " +
|
|
646
|
+
"Every table below is the fixed set from the `email-triage-rollout` skill; do not add tables, fill the blanks.");
|
|
647
|
+
parts.push("");
|
|
648
|
+
parts.push(`## Gate A — soak → label ${check(r.gateA.ready)}`);
|
|
649
|
+
parts.push("");
|
|
650
|
+
parts.push(`- ${check(r.gateA.rowsOk)} ${r.volume.total} recorded classifications (need ≥ ${TRIAGE_GATES.soakMinRows})`);
|
|
651
|
+
parts.push(`- ${check(r.gateA.reviewLaneOk)} review lane ${pct(r.reviewLaneRate)} (must be ≤ ${pct(TRIAGE_GATES.soakMaxReviewLaneRate)})`);
|
|
652
|
+
parts.push("- [ ] client approved the lane names and the taxonomy below, in writing, in their channel");
|
|
653
|
+
parts.push(r.provider === "gmail"
|
|
654
|
+
? "- [ ] Gmail labels created, every `REPLACE_ME_LABEL_ID_*` filled, prompt names match `LABEL_IDS` exactly"
|
|
655
|
+
: "- [ ] destination folders created, every `REPLACE_ME_OUTLOOK_FOLDER_ID_*` filled, `HARD_BLOCK_CATEGORIES` read out to the client");
|
|
656
|
+
if (r.gateA.blockers.length > 0) {
|
|
657
|
+
parts.push("");
|
|
658
|
+
parts.push("Blockers:");
|
|
659
|
+
for (const b of r.gateA.blockers)
|
|
660
|
+
parts.push(`- ${b}`);
|
|
661
|
+
}
|
|
662
|
+
parts.push("");
|
|
663
|
+
parts.push("## 1. Volume");
|
|
664
|
+
parts.push("");
|
|
665
|
+
parts.push(mdTable(["Measure", "Value"], [
|
|
666
|
+
["Messages recorded", r.volume.total],
|
|
667
|
+
[
|
|
668
|
+
"Window",
|
|
669
|
+
r.window.from && r.window.to
|
|
670
|
+
? `${r.window.from.slice(0, 10)} → ${r.window.to.slice(0, 10)} (${r.window.days} day${r.window.days === 1 ? "" : "s"})`
|
|
671
|
+
: "(no rows)",
|
|
672
|
+
],
|
|
673
|
+
["Messages / day", r.volume.perDay.toFixed(1)],
|
|
674
|
+
[
|
|
675
|
+
"Busiest day",
|
|
676
|
+
r.volume.busiest ? `${r.volume.busiest.day} (${r.volume.busiest.count})` : "—",
|
|
677
|
+
],
|
|
678
|
+
[
|
|
679
|
+
"Quietest day",
|
|
680
|
+
r.volume.quietest ? `${r.volume.quietest.day} (${r.volume.quietest.count})` : "—",
|
|
681
|
+
],
|
|
682
|
+
]));
|
|
683
|
+
parts.push("");
|
|
684
|
+
parts.push("## 2. Sender domains (top 20)");
|
|
685
|
+
parts.push("");
|
|
686
|
+
parts.push(mdTable(["#", "Domain", "Messages", "Share"], r.senderDomains.map((d, i) => [i + 1, d.domain, d.count, pct(d.share)])));
|
|
687
|
+
parts.push("");
|
|
688
|
+
parts.push(`Long tail: ${r.longTail.domains} more domain(s), ${r.longTail.messages} message(s).`);
|
|
689
|
+
parts.push("");
|
|
690
|
+
parts.push(`## 3. Proposed ${r.provider === "gmail" ? "disposition" : "category"} mix (the classifier's hypothesis)`);
|
|
691
|
+
parts.push("");
|
|
692
|
+
parts.push(mdTable([
|
|
693
|
+
r.provider === "gmail" ? "Disposition" : "Category",
|
|
694
|
+
"Messages",
|
|
695
|
+
"Share",
|
|
696
|
+
"Client-facing lane",
|
|
697
|
+
], r.mix.map((m) => [m.internal, m.count, pct(m.share), m.lane])));
|
|
698
|
+
parts.push("");
|
|
699
|
+
parts.push("### 3b. Client-facing lanes");
|
|
700
|
+
parts.push("");
|
|
701
|
+
parts.push(mdTable(["Lane", "Messages", "Share"], r.lanes.map((l) => [l.lane, l.count, pct(l.share)])));
|
|
702
|
+
parts.push("");
|
|
703
|
+
parts.push("## 4. Review-lane rate");
|
|
704
|
+
parts.push("");
|
|
705
|
+
parts.push(`${pct(r.reviewLaneRate)} of recorded mail landed in the review lane. Above ${pct(TRIAGE_GATES.soakMaxReviewLaneRate)} the taxonomy does not fit the mail — fix the categories, never the confidence floor.`);
|
|
706
|
+
parts.push("");
|
|
707
|
+
parts.push("## 5. Action-lane load");
|
|
708
|
+
parts.push("");
|
|
709
|
+
parts.push(`${r.actionLaneLoadPerDay.toFixed(1)} Critical + Today messages per day would reach the owner. If that is most of the inbox, the automation gives them nothing yet.`);
|
|
710
|
+
parts.push("");
|
|
711
|
+
parts.push(`## 6. Proposed taxonomy (${r.provider === "gmail" ? "topic labels" : "categories"}) — the client says yes or no to this`);
|
|
712
|
+
parts.push("");
|
|
713
|
+
parts.push(mdTable(["Name", "Messages", "Share", "Lane", "One-line definition (fill in)"], r.taxonomy.map((t) => [t.name, t.count, pct(t.share), t.lane, ""])));
|
|
714
|
+
parts.push("");
|
|
715
|
+
parts.push("## 7. Open questions");
|
|
716
|
+
parts.push("");
|
|
717
|
+
for (const q of r.openQuestions)
|
|
718
|
+
parts.push(`- [ ] ${q}`);
|
|
719
|
+
parts.push("");
|
|
720
|
+
parts.push("## Verdict");
|
|
721
|
+
parts.push("");
|
|
722
|
+
parts.push(r.gateA.ready
|
|
723
|
+
? "Data sufficiency met. Send the lane names + table 6 to the client (house-voice, Slack register) and WAIT for their written yes before promoting to `label`."
|
|
724
|
+
: "Gate A not met yet — see Blockers. Let the record sheet refill and re-run; never promote on a hunch.");
|
|
725
|
+
parts.push("");
|
|
726
|
+
return parts.join("\n");
|
|
727
|
+
}
|
|
728
|
+
/** mulberry32 — small, seedable, good enough for drawing a sample. Exported for tests. */
|
|
729
|
+
export function seededRandom(seed) {
|
|
730
|
+
let a = seed >>> 0;
|
|
731
|
+
return () => {
|
|
732
|
+
a = (a + 0x6d2b79f5) >>> 0;
|
|
733
|
+
let t = a;
|
|
734
|
+
t = Math.imul(t ^ (t >>> 15), t | 1);
|
|
735
|
+
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
|
|
736
|
+
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
|
737
|
+
};
|
|
738
|
+
}
|
|
739
|
+
function drawSample(items, size, random) {
|
|
740
|
+
const pool = [...items];
|
|
741
|
+
const picked = [];
|
|
742
|
+
while (picked.length < size && pool.length > 0) {
|
|
743
|
+
const i = Math.floor(random() * pool.length);
|
|
744
|
+
picked.push(pool.splice(i, 1)[0]);
|
|
745
|
+
}
|
|
746
|
+
return picked;
|
|
747
|
+
}
|
|
748
|
+
function toSampleRow(r, n) {
|
|
749
|
+
return {
|
|
750
|
+
n,
|
|
751
|
+
messageId: r.messageId,
|
|
752
|
+
recordedAt: r.recordedAt.toISOString(),
|
|
753
|
+
senderDomain: r.senderDomain,
|
|
754
|
+
internal: r.internal,
|
|
755
|
+
labels: r.labels,
|
|
756
|
+
lane: r.lane,
|
|
757
|
+
confidence: r.confidence,
|
|
758
|
+
reviewLane: r.reviewLane,
|
|
759
|
+
};
|
|
760
|
+
}
|
|
761
|
+
export async function triageGateSample(slug, options) {
|
|
762
|
+
if (options.stage !== "label" && options.stage !== "organize") {
|
|
763
|
+
throw new Error(`--stage must be "label" (gate B) or "organize" (gate C) — got "${String(options.stage)}". ` +
|
|
764
|
+
"Gate A is the soak report; stage 4 has no exit gate.");
|
|
765
|
+
}
|
|
766
|
+
const size = options.size ?? TRIAGE_GATES.sampleSize;
|
|
767
|
+
if (!Number.isInteger(size) || size < 1)
|
|
768
|
+
throw new Error("--size must be a positive integer");
|
|
769
|
+
const loaded = await loadRecords(slug, options);
|
|
770
|
+
const stageRows = loaded.rows.filter((r) => r.stage === options.stage);
|
|
771
|
+
if (stageRows.length === 0) {
|
|
772
|
+
const seen = [...new Set(loaded.rows.map((r) => r.stage))].sort().join(", ") || "(none)";
|
|
773
|
+
throw new Error(`no rows recorded at stage "${options.stage}" — stages present: ${seen}. A gate samples only rows ` +
|
|
774
|
+
"written at the current stage (earlier rows are a different experiment).");
|
|
775
|
+
}
|
|
776
|
+
const now = options.now ?? Date.now;
|
|
777
|
+
const seed = options.seed ?? now() % 2_147_483_647;
|
|
778
|
+
const random = seededRandom(seed);
|
|
779
|
+
const sample = drawSample(stageRows, size, random).map(toSampleRow);
|
|
780
|
+
const gate = options.stage === "label" ? "B" : "C";
|
|
781
|
+
const reviewRate = reviewLaneRate(stageRows);
|
|
782
|
+
const spamRows = loaded.provider === "outlook" && gate === "C"
|
|
783
|
+
? stageRows.filter((r) => normaliseKey(r.internal) === "spam").map(toSampleRow)
|
|
784
|
+
: [];
|
|
785
|
+
const zeroTolerance = [];
|
|
786
|
+
if (loaded.provider === "gmail") {
|
|
787
|
+
zeroTolerance.push("No message the owner needed to act on was classified `archive`. One instance fails the gate.");
|
|
788
|
+
}
|
|
789
|
+
else {
|
|
790
|
+
zeroTolerance.push("Nothing the owner needed to act on was categorised `Spam`, `Newsletter` or `Notifications`. One instance fails the gate.");
|
|
791
|
+
}
|
|
792
|
+
if (gate === "C") {
|
|
793
|
+
zeroTolerance.push("The owner pulled NOTHING back out of a label/folder into the inbox during the window — ask them directly.");
|
|
794
|
+
zeroTolerance.push("The owner has read at least five sample reply drafts (generated in a test run, pasted in the channel — never already in their Drafts) and approved the voice.");
|
|
795
|
+
if (loaded.provider === "outlook") {
|
|
796
|
+
zeroTolerance.push(`Every Spam row in the window is listed below and judged — ${spamRows.length} row(s). One wrong Spam call blocks the gate; if the list is too long to judge, the classifier is over-calling Spam.`);
|
|
797
|
+
zeroTolerance.push("Decided with the client whether `needs_human_review` mail may still get a draft; recorded in the tech spec.");
|
|
798
|
+
}
|
|
799
|
+
}
|
|
800
|
+
const today = new Date(now()).toISOString().slice(0, 10);
|
|
801
|
+
const base = {
|
|
802
|
+
slug,
|
|
803
|
+
provider: loaded.provider,
|
|
804
|
+
source: loaded.source,
|
|
805
|
+
stage: options.stage,
|
|
806
|
+
gate,
|
|
807
|
+
window: windowOf(stageRows),
|
|
808
|
+
population: stageRows.length,
|
|
809
|
+
seed,
|
|
810
|
+
sample,
|
|
811
|
+
reviewLaneRate: reviewRate,
|
|
812
|
+
reviewLaneOk: reviewRate <= TRIAGE_GATES.maxReviewLaneRate,
|
|
813
|
+
spamRows,
|
|
814
|
+
zeroTolerance,
|
|
815
|
+
thresholds: {
|
|
816
|
+
minPrecision: TRIAGE_GATES.minPrecision,
|
|
817
|
+
maxReviewLaneRate: TRIAGE_GATES.maxReviewLaneRate,
|
|
818
|
+
sampleSize: size,
|
|
819
|
+
},
|
|
820
|
+
};
|
|
821
|
+
const markdown = renderGateSample(base, today);
|
|
822
|
+
const result = { ...base, markdown };
|
|
823
|
+
if (options.write !== false) {
|
|
824
|
+
const dir = await evidenceDir(options.workspaceDir ?? ".", slug);
|
|
825
|
+
const stageNumber = gate === "B" ? 2 : 3;
|
|
826
|
+
const path = join(dir, `${today}-email-triage-stage${stageNumber}-gate.md`);
|
|
827
|
+
await writeEvidence(path, markdown, options.force === true);
|
|
828
|
+
result.evidencePath = path;
|
|
829
|
+
}
|
|
830
|
+
return result;
|
|
831
|
+
}
|
|
832
|
+
function sampleTable(rows, provider) {
|
|
833
|
+
return mdTable([
|
|
834
|
+
"#",
|
|
835
|
+
"message_id",
|
|
836
|
+
"Recorded",
|
|
837
|
+
"Sender domain",
|
|
838
|
+
provider === "gmail" ? "Disposition · labels" : "Category",
|
|
839
|
+
"Lane",
|
|
840
|
+
"Conf.",
|
|
841
|
+
"Review",
|
|
842
|
+
"Correct? (y/n)",
|
|
843
|
+
"If wrong: what it should have been",
|
|
844
|
+
], rows.map((r) => [
|
|
845
|
+
r.n,
|
|
846
|
+
`\`${r.messageId}\``,
|
|
847
|
+
r.recordedAt.slice(0, 16).replace("T", " "),
|
|
848
|
+
r.senderDomain,
|
|
849
|
+
provider === "gmail"
|
|
850
|
+
? `${r.internal}${r.labels.length ? ` · ${r.labels.join(", ")}` : ""}`
|
|
851
|
+
: r.internal,
|
|
852
|
+
r.lane,
|
|
853
|
+
r.confidence,
|
|
854
|
+
r.reviewLane ? "yes" : "",
|
|
855
|
+
"",
|
|
856
|
+
"",
|
|
857
|
+
]));
|
|
858
|
+
}
|
|
859
|
+
function renderGateSample(r, today) {
|
|
860
|
+
const check = (ok) => (ok ? "✅" : "❌");
|
|
861
|
+
const needCorrect = Math.ceil(r.thresholds.minPrecision * r.sample.length);
|
|
862
|
+
const parts = [];
|
|
863
|
+
parts.push(`# Email triage — gate ${r.gate} (${r.stage} → ${r.gate === "B" ? "organize" : "full"}) — ${r.slug} — ${today}`);
|
|
864
|
+
parts.push("");
|
|
865
|
+
parts.push(`> Generated by \`ia triage sample\` from ${r.source} (${r.provider} template). Population: ${r.population} rows recorded at stage \`${r.stage}\`, ` +
|
|
866
|
+
`${r.window.from.slice(0, 10)} → ${r.window.to.slice(0, 10)}. Sample of ${r.sample.length} drawn at random across the whole window (seed ${r.seed} — re-run with \`--seed ${r.seed}\` to reproduce). ` +
|
|
867
|
+
"Open each message_id in the client's own mailbox; judge against what the OWNER would have wanted, not what the prompt says.");
|
|
868
|
+
parts.push("");
|
|
869
|
+
parts.push("## Thresholds");
|
|
870
|
+
parts.push("");
|
|
871
|
+
parts.push(`- [ ] ≥ ${pct(r.thresholds.minPrecision)} correct: **___ / ${r.sample.length}** (need ≥ ${needCorrect})`);
|
|
872
|
+
parts.push(`- ${check(r.reviewLaneOk)} review lane ${pct(r.reviewLaneRate)} across the window (must be < ${pct(r.thresholds.maxReviewLaneRate)}) — higher means the taxonomy does not fit, not that the floor is wrong`);
|
|
873
|
+
parts.push("");
|
|
874
|
+
parts.push("## Zero tolerance — one instance is a fail");
|
|
875
|
+
parts.push("");
|
|
876
|
+
for (const z of r.zeroTolerance)
|
|
877
|
+
parts.push(`- [ ] ${z}`);
|
|
878
|
+
parts.push("");
|
|
879
|
+
parts.push(`## Sample (${r.sample.length})`);
|
|
880
|
+
parts.push("");
|
|
881
|
+
parts.push(sampleTable(r.sample, r.provider));
|
|
882
|
+
parts.push("");
|
|
883
|
+
if (r.spamRows.length > 0) {
|
|
884
|
+
parts.push(`## Every Spam row in the window (${r.spamRows.length}) — gate C, Outlook only`);
|
|
885
|
+
parts.push("");
|
|
886
|
+
parts.push(sampleTable(r.spamRows, r.provider));
|
|
887
|
+
parts.push("");
|
|
888
|
+
}
|
|
889
|
+
parts.push("## Misses");
|
|
890
|
+
parts.push("");
|
|
891
|
+
parts.push("List every wrong row: `#`, what it was, what it should have been, and whether it hits a zero-tolerance line.");
|
|
892
|
+
parts.push("");
|
|
893
|
+
parts.push("- ");
|
|
894
|
+
parts.push("");
|
|
895
|
+
parts.push("## Verdict");
|
|
896
|
+
parts.push("");
|
|
897
|
+
parts.push("- [ ] PASS — promote (`TRIAGE_STAGE` one step, publish, re-export, commit; tell the client what changes today and how they undo it)");
|
|
898
|
+
parts.push("- [ ] FAIL — say the number to the client, name what you are changing, let the sheet refill, re-sample");
|
|
899
|
+
parts.push("");
|
|
900
|
+
return parts.join("\n");
|
|
901
|
+
}
|
|
902
|
+
export async function triageHealth(slug, options = {}) {
|
|
903
|
+
const days = options.days ?? 1;
|
|
904
|
+
if (!Number.isInteger(days) || days < 1)
|
|
905
|
+
throw new Error("--days must be a positive integer");
|
|
906
|
+
const loaded = await loadRecords(slug, options);
|
|
907
|
+
const now = options.now ?? Date.now;
|
|
908
|
+
const cutoff = now() - days * 86_400_000;
|
|
909
|
+
const recent = loaded.rows.filter((r) => r.recordedAt.getTime() >= cutoff);
|
|
910
|
+
const last = loaded.rows.at(-1)?.recordedAt ?? null;
|
|
911
|
+
const stagesInWindow = {};
|
|
912
|
+
for (const [stage, n] of countBy(recent, (r) => r.stage))
|
|
913
|
+
stagesInWindow[stage] = n;
|
|
914
|
+
const spamShare = loaded.provider === "outlook"
|
|
915
|
+
? share(recent.filter((r) => normaliseKey(r.internal) === "spam").length, recent.length)
|
|
916
|
+
: null;
|
|
917
|
+
const ok = recent.length > 0;
|
|
918
|
+
const hoursSinceLast = last ? Math.round((now() - last.getTime()) / 3_600_000) : null;
|
|
919
|
+
const message = ok
|
|
920
|
+
? `${recent.length} row(s) in the last ${days} day(s) — the workflow is recording.`
|
|
921
|
+
: `NO rows in the last ${days} day(s)${last ? ` (last row ${last.toISOString()}, ${hoursSinceLast}h ago)` : " (the record has no rows at all)"} — ` +
|
|
922
|
+
"the workflow is off, the trigger broke, or a credential expired. Nothing in the mailbox will tell you.";
|
|
923
|
+
return {
|
|
924
|
+
slug,
|
|
925
|
+
provider: loaded.provider,
|
|
926
|
+
source: loaded.source,
|
|
927
|
+
days,
|
|
928
|
+
rowsInWindow: recent.length,
|
|
929
|
+
lastRecordedAt: last ? last.toISOString() : null,
|
|
930
|
+
hoursSinceLast,
|
|
931
|
+
stagesInWindow,
|
|
932
|
+
reviewLaneRate: reviewLaneRate(recent),
|
|
933
|
+
spamShare,
|
|
934
|
+
ok,
|
|
935
|
+
message,
|
|
936
|
+
};
|
|
937
|
+
}
|
|
938
|
+
/** Parse `--lane "New Lead=Today,Vendor=Noise"` into a laneOverrides map. Exported for the CLI. */
|
|
939
|
+
export function parseLaneOverrides(spec) {
|
|
940
|
+
if (!spec)
|
|
941
|
+
return undefined;
|
|
942
|
+
const out = {};
|
|
943
|
+
for (const pair of spec.split(",")) {
|
|
944
|
+
const [name, lane] = pair.split("=").map((s) => s.trim());
|
|
945
|
+
if (!name || !lane || !TRIAGE_LANES.includes(lane)) {
|
|
946
|
+
throw new Error(`bad --lane entry "${pair}" — use "<category>=<${TRIAGE_LANES.join("|")}>", comma-separated`);
|
|
947
|
+
}
|
|
948
|
+
out[name] = lane;
|
|
949
|
+
}
|
|
950
|
+
return out;
|
|
951
|
+
}
|