@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.
Files changed (56) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/claude-hours.d.ts +134 -0
  4. package/dist/claude-hours.js +638 -0
  5. package/dist/client-drive.d.ts +3 -0
  6. package/dist/client-drive.js +2 -2
  7. package/dist/client-linear-create.d.ts +10 -0
  8. package/dist/client-linear-create.js +30 -3
  9. package/dist/env-fill.js +21 -4
  10. package/dist/env-registry.d.ts +4 -0
  11. package/dist/env-registry.js +54 -2
  12. package/dist/git.d.ts +31 -0
  13. package/dist/git.js +59 -0
  14. package/dist/google-service-account.d.ts +20 -0
  15. package/dist/google-service-account.js +49 -0
  16. package/dist/hours-estimate.d.ts +43 -0
  17. package/dist/hours-estimate.js +159 -0
  18. package/dist/hours-export-schedule.d.ts +35 -0
  19. package/dist/hours-export-schedule.js +188 -0
  20. package/dist/hours-ledger.d.ts +137 -0
  21. package/dist/hours-ledger.js +926 -0
  22. package/dist/index.d.ts +14 -3
  23. package/dist/index.js +14 -3
  24. package/dist/portal-admin.d.ts +68 -0
  25. package/dist/portal-admin.js +64 -1
  26. package/dist/sync-repos.d.ts +7 -0
  27. package/dist/sync-repos.js +10 -1
  28. package/dist/template-sync.d.ts +10 -9
  29. package/dist/template-sync.js +14 -9
  30. package/dist/triage-backfill.d.ts +37 -0
  31. package/dist/triage-backfill.js +211 -0
  32. package/dist/triage-enable.d.ts +90 -0
  33. package/dist/triage-enable.js +428 -0
  34. package/dist/triage-gates.d.ts +252 -0
  35. package/dist/triage-gates.js +951 -0
  36. package/dist/workspace-push.d.ts +39 -0
  37. package/dist/workspace-push.js +78 -0
  38. package/dist/workspace-status.d.ts +37 -0
  39. package/dist/workspace-status.js +114 -0
  40. package/package.json +1 -1
  41. package/templates/env.example +6 -2
  42. package/templates/workspace-root/.claude/settings.json +12 -1
  43. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
  44. package/templates/workspace-root/skills/CLAUDE.md +6 -1
  45. package/templates/workspace-root/skills/README.md +17 -2
  46. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  47. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  48. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  49. package/templates/workspace-root/skills/client-latest/SKILL.md +124 -82
  50. package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
  51. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
  52. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  53. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  54. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  55. package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
  56. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
@@ -0,0 +1,252 @@
1
+ import { type PortalAdminOptions } from "./portal-admin.js";
2
+ export declare const SHEETS_API_BASE_URL = "https://sheets.googleapis.com/v4/spreadsheets";
3
+ /** Read-only — this tool never writes to a client's sheet. */
4
+ export declare const SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets.readonly";
5
+ export type TriageProvider = "gmail" | "outlook";
6
+ export type TriageStage = "soak" | "label" | "organize" | "full";
7
+ export declare const TRIAGE_STAGES: readonly TriageStage[];
8
+ /**
9
+ * The client-facing lane vocabulary (decided 2026-09-16). The kickoff deck,
10
+ * the soak report and every client Slack message use these four words; the
11
+ * templates' internal dispositions/categories map onto them below.
12
+ */
13
+ export type TriageLane = "Critical" | "Today" | "Later" | "Noise";
14
+ export declare const TRIAGE_LANES: readonly TriageLane[];
15
+ /** Gmail template: `disposition` → lane. `action` splits on `priority` (see laneFor). */
16
+ export declare const GMAIL_LANE_BY_DISPOSITION: Readonly<Record<string, TriageLane>>;
17
+ /** `action` mail with one of these priorities is Critical rather than Today. */
18
+ export declare const CRITICAL_PRIORITIES: readonly string[];
19
+ /**
20
+ * Outlook template: `category` → lane, keyed on the normalised category name
21
+ * (lower-case, letters and digits only) so "New Lead" and "NewLead" agree.
22
+ * Categories a client adds at gate A are passed in via `laneOverrides`.
23
+ */
24
+ export declare const OUTLOOK_LANE_BY_CATEGORY: Readonly<Record<string, TriageLane>>;
25
+ /** Outlook `urgency` / `importance` values that lift a message to Critical. */
26
+ export declare const CRITICAL_URGENCIES: readonly string[];
27
+ /** Gate thresholds, exactly as sop.md states them. Change the SOP and this together. */
28
+ export declare const TRIAGE_GATES: {
29
+ /** Gate A: recorded classifications before a taxonomy can be proposed. */
30
+ readonly soakMinRows: 200;
31
+ /** Gate A: review-lane share above which the taxonomy does not fit the mail. */
32
+ readonly soakMaxReviewLaneRate: 0.2;
33
+ /** Gates B and C: sample size drawn from the current stage's rows. */
34
+ readonly sampleSize: 50;
35
+ /** Gates B and C: minimum share of sampled rows with the correct label/category. */
36
+ readonly minPrecision: 0.9;
37
+ /** Gates B and C: maximum review-lane share across the stage window. */
38
+ readonly maxReviewLaneRate: 0.15;
39
+ };
40
+ export declare const GMAIL_HEADERS: readonly ["recorded_at", "stage", "message_id", "thread_id", "sender_domain", "disposition", "priority", "confidence", "labels", "review_lane"];
41
+ export declare const OUTLOOK_HEADERS: readonly ["recorded_at", "stage", "message_id", "conversation_id", "sender_domain", "category", "importance", "urgency", "confidence", "needs_review", "reply_recommended", "flagged"];
42
+ export interface TriageRecordRow {
43
+ recordedAt: Date;
44
+ stage: string;
45
+ messageId: string;
46
+ senderDomain: string;
47
+ /** Gmail `disposition` / Outlook `category`, as written. */
48
+ internal: string;
49
+ /** Gmail `labels` split on `|`; empty for Outlook. */
50
+ labels: string[];
51
+ /** Raw confidence cell (Gmail 0–1, Outlook high/medium/low). */
52
+ confidence: string;
53
+ reviewLane: boolean;
54
+ lane: TriageLane;
55
+ }
56
+ export interface TriageSourceOptions {
57
+ /** Path to a CSV export of the record sheet (File → Download → CSV). */
58
+ csv?: string;
59
+ /** Spreadsheet ID of the record sheet; resolved from the client repo's workflows/ when omitted. */
60
+ sheetId?: string;
61
+ /** installagent/ workspace root; the client repo is `clients/client-<slug>/` under it. */
62
+ workspaceDir?: string;
63
+ /** Client-specific category → lane additions (Outlook clients add their own categories). */
64
+ laneOverrides?: Record<string, TriageLane>;
65
+ /** Portal agent slug — needed only when the org has more than one triage agent. */
66
+ agent?: string;
67
+ /** Keep only rows recorded at or after this instant (ISO string or Date). */
68
+ since?: Date | string;
69
+ /** Keep only rows recorded before this instant (ISO string or Date). */
70
+ until?: Date | string;
71
+ /**
72
+ * Portal admin API access (secret defaults to $IA_PORTAL_ADMIN_SECRET, URL
73
+ * to $IA_PORTAL_URL); `false` never asks the portal. `fetchImpl` below is
74
+ * used for the portal too.
75
+ */
76
+ portal?: Omit<PortalAdminOptions, "fetchImpl"> | false;
77
+ /** Google service-account key JSON (raw string); defaults to $GOOGLE_SERVICE_ACCOUNT_KEY. */
78
+ serviceAccountKey?: string;
79
+ /** Injectable for tests; defaults to global fetch. */
80
+ fetchImpl?: typeof fetch;
81
+ /** Injectable clock; defaults to Date.now. */
82
+ now?: () => number;
83
+ }
84
+ /** Minimal RFC 4180 reader: quoted fields, doubled quotes, CRLF or LF. Exported for tests. */
85
+ export declare function parseCsv(text: string): string[][];
86
+ /**
87
+ * Find the record sheet ID in the client repo's exported workflow JSON: the
88
+ * Google Sheets append node whose documentId is a real spreadsheet URL (not
89
+ * the `REPLACE_ME_RECORD_SHEET_ID` placeholder). Exported for tests.
90
+ */
91
+ export declare function resolveRecordSheetId(workspaceDir: string, slug: string): Promise<string | undefined>;
92
+ /** Which template wrote this header row. Exported for the backfill. */
93
+ export declare function detectProvider(header: string[]): TriageProvider;
94
+ /** Exported for tests and for the SOP's lane table. */
95
+ export declare function laneFor(provider: TriageProvider, cells: Record<string, string>, laneOverrides?: Record<string, TriageLane>): {
96
+ lane: TriageLane;
97
+ mapped: boolean;
98
+ };
99
+ export interface RecordTable {
100
+ /** Row 1 is the header; the rest are record rows, cell for cell. */
101
+ table: string[][];
102
+ /** Where it came from, for the evidence header. */
103
+ source: string;
104
+ }
105
+ /**
106
+ * The record SHEET as a table: a CSV export, `--sheet`, or the sheet the
107
+ * client repo's workflow export writes to. Never the portal — the backfill
108
+ * reads a sheet with this. `note` says why the portal was not the source.
109
+ */
110
+ export declare function readRecordSheetTable(slug: string, options: TriageSourceOptions, note?: string): Promise<RecordTable>;
111
+ export interface TriageWindow {
112
+ from: string;
113
+ to: string;
114
+ days: number;
115
+ }
116
+ export interface TriageSoakReportOptions extends TriageSourceOptions {
117
+ /** Only rows recorded at this stage (default `soak`). */
118
+ stage?: TriageStage;
119
+ /** Write the markdown into the client repo's evidence/ (default true). */
120
+ write?: boolean;
121
+ /** Replace today's file if it already exists (default false — refuses). */
122
+ force?: boolean;
123
+ }
124
+ export interface TriageSoakReportResult {
125
+ slug: string;
126
+ provider: TriageProvider;
127
+ source: string;
128
+ stage: TriageStage;
129
+ window: TriageWindow;
130
+ volume: {
131
+ total: number;
132
+ perDay: number;
133
+ busiest: {
134
+ day: string;
135
+ count: number;
136
+ } | null;
137
+ quietest: {
138
+ day: string;
139
+ count: number;
140
+ } | null;
141
+ };
142
+ senderDomains: Array<{
143
+ domain: string;
144
+ count: number;
145
+ share: number;
146
+ }>;
147
+ longTail: {
148
+ domains: number;
149
+ messages: number;
150
+ };
151
+ mix: Array<{
152
+ internal: string;
153
+ count: number;
154
+ share: number;
155
+ lane: TriageLane;
156
+ }>;
157
+ lanes: Array<{
158
+ lane: TriageLane;
159
+ count: number;
160
+ share: number;
161
+ }>;
162
+ reviewLaneRate: number;
163
+ /** Critical + Today messages per day — what the owner would actually be pinged about. */
164
+ actionLaneLoadPerDay: number;
165
+ taxonomy: Array<{
166
+ name: string;
167
+ count: number;
168
+ share: number;
169
+ lane: TriageLane;
170
+ }>;
171
+ openQuestions: string[];
172
+ gateA: {
173
+ rowsOk: boolean;
174
+ reviewLaneOk: boolean;
175
+ ready: boolean;
176
+ blockers: string[];
177
+ };
178
+ markdown: string;
179
+ /** Where the markdown was written, or undefined when write was false. */
180
+ evidencePath?: string;
181
+ }
182
+ export declare function triageSoakReport(slug: string, options?: TriageSoakReportOptions): Promise<TriageSoakReportResult>;
183
+ export interface TriageGateSampleOptions extends TriageSourceOptions {
184
+ /** Rows from this stage only — `label` proves gate B, `organize` proves gate C. */
185
+ stage: "label" | "organize";
186
+ /** Sample size (default 50, per sop.md). */
187
+ size?: number;
188
+ /** PRNG seed; the same seed on the same rows reproduces the sample. Default: derived from now(). */
189
+ seed?: number;
190
+ write?: boolean;
191
+ force?: boolean;
192
+ }
193
+ export interface TriageSampleRow {
194
+ n: number;
195
+ messageId: string;
196
+ recordedAt: string;
197
+ senderDomain: string;
198
+ internal: string;
199
+ labels: string[];
200
+ lane: TriageLane;
201
+ confidence: string;
202
+ reviewLane: boolean;
203
+ }
204
+ export interface TriageGateSampleResult {
205
+ slug: string;
206
+ provider: TriageProvider;
207
+ source: string;
208
+ stage: "label" | "organize";
209
+ gate: "B" | "C";
210
+ window: TriageWindow;
211
+ population: number;
212
+ seed: number;
213
+ sample: TriageSampleRow[];
214
+ reviewLaneRate: number;
215
+ reviewLaneOk: boolean;
216
+ /** Gate C on Outlook only: every Spam row in the window, not a sample. */
217
+ spamRows: TriageSampleRow[];
218
+ zeroTolerance: string[];
219
+ thresholds: {
220
+ minPrecision: number;
221
+ maxReviewLaneRate: number;
222
+ sampleSize: number;
223
+ };
224
+ markdown: string;
225
+ evidencePath?: string;
226
+ }
227
+ /** mulberry32 — small, seedable, good enough for drawing a sample. Exported for tests. */
228
+ export declare function seededRandom(seed: number): () => number;
229
+ export declare function triageGateSample(slug: string, options: TriageGateSampleOptions): Promise<TriageGateSampleResult>;
230
+ export interface TriageHealthOptions extends TriageSourceOptions {
231
+ /** Look-back window in days (default 1). */
232
+ days?: number;
233
+ }
234
+ export interface TriageHealthResult {
235
+ slug: string;
236
+ provider: TriageProvider;
237
+ source: string;
238
+ days: number;
239
+ rowsInWindow: number;
240
+ lastRecordedAt: string | null;
241
+ /** Hours since the last row, at now(). */
242
+ hoursSinceLast: number | null;
243
+ stagesInWindow: Record<string, number>;
244
+ reviewLaneRate: number;
245
+ /** Outlook only: share of the window categorised Spam (the one category with a recovery clock). */
246
+ spamShare: number | null;
247
+ ok: boolean;
248
+ message: string;
249
+ }
250
+ export declare function triageHealth(slug: string, options?: TriageHealthOptions): Promise<TriageHealthResult>;
251
+ /** Parse `--lane "New Lead=Today,Vendor=Noise"` into a laneOverrides map. Exported for the CLI. */
252
+ export declare function parseLaneOverrides(spec: string | undefined): Record<string, TriageLane> | undefined;