@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
package/dist/index.d.ts CHANGED
@@ -1,4 +1,6 @@
1
+ export { type AgentMirrorOptions, type AgentMirrorResult, checkAgentMirror, type MirrorRow, type MirrorState, type MirrorSummary, } from "./agent-mirror.js";
1
2
  export { type AgentBankOptions, type AgentTemplateInfo, type AgentTemplateMatch, type CreateFromTemplateInput, type CreateFromTemplateResult, createFromAgentTemplate, type ListAgentTemplatesResult, listAgentTemplates, N8N_API_KEY_ENV, N8N_API_URL_ENV, N8nAuthError, type SanitizedWorkflow, type SaveAgentTemplateInput, type SaveAgentTemplateOptions, type SaveAgentTemplateResult, type SearchAgentTemplatesOptions, type SearchAgentTemplatesResult, type SopState, type StrippedCredential, sanitizeN8nWorkflow, saveAgentTemplate, searchAgentTemplates, } from "./agent-templates.js";
3
+ export { CLAUDE_CONFIG_DIR_ENV, type ClaudeHoursExportOptions, type ClaudeHoursExportResult, type ClaudeHoursSummaryRow, compactClaudeHoursExport, type DeliverClaudeHoursExportOptions, type DeliverClaudeHoursExportResult, deliverClaudeHoursExport, exportClaudeHours, HOURS_EXPORT_DIR, HOURS_EXPORT_SCHEMA, HOURS_EXPORT_SECRET_ENV, HOURS_EXPORT_SECRET_HEADER, HOURS_EXPORT_WEBHOOK_URL, PROMPT_WINDOW_MINUTES, parseLedgerDate, parseMinuteIso, type SaveClaudeHoursExportOptions, type SendClaudeHoursExportOptions, saveClaudeHoursExport, sendClaudeHoursExport, TOOL_INPUT_PATH_KEYS, UNATTRIBUTED_SLUG, } from "./claude-hours.js";
2
4
  export { ClientBuildAuthError, type ClientBuildDoc, type ClientBuildOptions, type ClientBuildResult, clientBuild, GITHUB_API_TOKEN_ENV, } from "./client-build.js";
3
5
  export { type ClientCall, type ClientContextOptions, type ClientContextResult, clientContext, } from "./client-context.js";
4
6
  export { AIRTABLE_API_TOKEN_ENV, buildAssertionClaims, ClientDriveAuthError, type ClientDriveDoc, type ClientDriveSearchOptions, type ClientDriveSearchResult, clientDriveSearch, GOOGLE_SERVICE_ACCOUNT_KEY_ENV, parseServiceAccountKey, } from "./client-drive.js";
@@ -16,18 +18,27 @@ export { type ExecFileFn, MINT_HANDOFF_WARNING, type MintGcpServiceAccountKeyOpt
16
18
  export { DEFAULT_GEMINI_KEY_DISPLAY_NAME, GEMINI_API_TARGET, type MintGeminiApiKeyOptions, type MintGeminiApiKeyResult, mintGeminiApiKey, } from "./gemini-api-key.js";
17
19
  export { type CloneFn, type CloneOptions, gitClone, gitPullFfOnly, type PullFn } from "./git.js";
18
20
  export { GITHUB_TOKEN_FIX, type ResolvedGithubToken, type ResolveGithubTokenOptions, resolveGithubToken, } from "./github-token.js";
21
+ export { buildServiceAccountClaims, GOOGLE_TOKEN_URL, GoogleServiceAccountAuthError, getServiceAccountAccessToken, } from "./google-service-account.js";
22
+ export { type ActivityEvent, type EstimateHoursOptions, estimateHours, HOURS_SOURCES, type HoursByPersonSlugMonth, type HoursEstimate, type HoursSource, LEAD_HEAVY_MINUTES, LEAD_LIGHT_MINUTES, LEDGER_TIME_ZONE, ledgerDay, ledgerMonth, roundMonths, SESSION_GAP_MINUTES, } from "./hours-estimate.js";
23
+ export { type HoursExportScheduleOptions, type HoursExportScheduleResult, installHoursExportSchedule, type UninstallHoursExportScheduleOptions, uninstallHoursExportSchedule, } from "./hours-export-schedule.js";
24
+ export { buildHoursLedger, CLIENT_FIELDS, DEFAULT_HOURS_LEDGER_DIR, type HoursLedgerConfig, type HoursLedgerData, type HoursLedgerIngest, type HoursLedgerOptions, type HoursLedgerPersonTotal, type HoursLedgerResult, type HoursLedgerRow, identityMatches, LEDGER_WINDOW_START, OTHER_LEAD_SLUG, TEAM_FIELDS, } from "./hours-ledger.js";
19
25
  export { CLIENT_TEMPLATE_URL, type InitStep, type InitWorkspaceOptions, type InitWorkspaceResult, initWorkspace, MCP_RECOMMENDATIONS, type McpRecommendation, TEAM_CLIENTS_URL, } from "./init.js";
20
- export { findProjectBySlugId, LINEAR_API_TOKEN_ENV, LinearAuthError, type LinearIssue, LinearProjectNotFoundError, type LinearProjectOptions, type LinearProjectResult, linearProject, linearProjectIssues, type ProjectNode, } from "./linear-project.js";
26
+ export { findProjectBySlugId, LINEAR_API_TOKEN_ENV, LinearAuthError, type LinearIssue, LinearProjectNotFoundError, type LinearProjectOptions, type LinearProjectResult, linearProject, linearProjectIssues, linearRequest, type ProjectNode, } from "./linear-project.js";
21
27
  export { type CreateLoggerOptions, createLogger, type LogFields, type Logger, type LogLevel, redactFields, } from "./log.js";
22
28
  export { type ExtractNodeOutputsOptions, extractNodeOutputs, listN8nExecutions, listNodesRun, type N8nExecutionDetail, type N8nExecutionStatus, type N8nExecutionSummary, type N8nExecutionsInput, type N8nExecutionsOptions, type N8nExecutionsResult, type N8nNodeOutput, unflattenExecutionData, } from "./n8n-executions.js";
23
29
  export { type NewClientOptions, type NewClientResult, newClient, SLUG_PATTERN, } from "./new-client.js";
24
30
  export { opInstallCommand, opInstallFix, opIntegrationFix } from "./op-cli.js";
25
31
  export { type PingResult, ping } from "./ping.js";
26
32
  export { detectPlatform, detectPlatformInfo, detectShell, opNeedsAnotherShell, type Platform, type PlatformInfo, type Shell, } from "./platform.js";
27
- export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, type PortalAddUserInput, type PortalAddUserResult, PortalAdminAuthError, type PortalAdminOptions, type PortalAgent, type PortalAgentSyncRow, type PortalCreateAgentInput, type PortalCreateOrgInput, type PortalCreateOrgResult, type PortalListAgentsResult, type PortalListOrgsResult, type PortalOrg, type PortalOrgUser, type PortalSetAgentNameInput, type PortalSetAgentNameResult, type PortalSetAgentStatusInput, type PortalSetAgentStatusResult, type PortalSetAgentWorkflowInput, type PortalSetAgentWorkflowResult, type PortalSetDriveFolderResult, type PortalSetPasswordResult, type PortalSyncRunsResult, portalAddUser, portalCreateAgent, portalCreateOrg, portalListAgents, portalListOrgs, portalSetAgentName, portalSetAgentStatus, portalSetAgentWorkflow, portalSetDriveFolder, portalSetPassword, portalSyncRuns, } from "./portal-admin.js";
33
+ export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, type PortalAddUserInput, type PortalAddUserResult, PortalAdminAuthError, type PortalAdminOptions, type PortalAgent, type PortalAgentSyncRow, type PortalCreateAgentInput, type PortalCreateOrgInput, type PortalCreateOrgResult, type PortalListAgentsResult, type PortalListOrgsResult, type PortalOrg, type PortalOrgUser, PortalRequestError, type PortalSetAgentNameInput, type PortalSetAgentNameResult, type PortalSetAgentStatusInput, type PortalSetAgentStatusResult, type PortalSetAgentTriageResult, type PortalSetAgentWorkflowInput, type PortalSetAgentWorkflowResult, type PortalSetDriveFolderResult, type PortalSetPasswordResult, type PortalSyncRunsResult, type PortalTriageBackfillResult, type PortalTriageProvider, type PortalTriageRecordsPage, portalAddUser, portalBackfillTriageRecords, portalCreateAgent, portalCreateOrg, portalListAgents, portalListOrgs, portalReadTriageRecords, portalSetAgentName, portalSetAgentStatus, portalSetAgentTriage, portalSetAgentWorkflow, portalSetDriveFolder, portalSetOrgSlackChannel, portalSetPassword, portalSyncRuns, } from "./portal-admin.js";
28
34
  export { type StandupCallPrep, type StandupCallPrepStatus, type StandupGitState, type StandupIssueRef, type StandupLinear, type StandupOptions, type StandupRepo, type StandupRepoLint, type StandupResult, type StandupStaleTodo, standup, } from "./standup.js";
29
- export { type SyncRepoResult, type SyncRepoStatus, type SyncReposOptions, type SyncReposResult, syncRepos, } from "./sync-repos.js";
35
+ export { type SyncRepoResult, type SyncRepoStatus, type SyncReposOptions, type SyncReposResult, syncRepos, workspaceRepoNames, } from "./sync-repos.js";
30
36
  export { type SyncTemplatesFileResult, type SyncTemplatesFileStatus, type SyncTemplatesOptions, type SyncTemplatesResult, syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
31
37
  export { TEMPLATE_SYNCED_FILES, type TemplateSyncFileResult, type TemplateSyncFileStatus, type TemplateSyncOptions, type TemplateSyncRepoResult, type TemplateSyncResult, templateSync, } from "./template-sync.js";
38
+ export { TRIAGE_BACKFILL_CHUNK, type TriageBackfillOptions, type TriageBackfillResult, triageBackfill, } from "./triage-backfill.js";
39
+ export { checkTriageRecordWiring, detectWorkflowProvider, PORTAL_INGEST_CREDENTIAL_NAME, TRIAGE_RECORDS_PATH, type TriageEnableOptions, type TriageEnableResult, type TriageWiringCheck, type TriageWiringCheckId, type TriageWiringReport, triageEnable, } from "./triage-enable.js";
40
+ export { CRITICAL_PRIORITIES, CRITICAL_URGENCIES, detectProvider, GMAIL_HEADERS, GMAIL_LANE_BY_DISPOSITION, laneFor, OUTLOOK_HEADERS, OUTLOOK_LANE_BY_CATEGORY, parseCsv, parseLaneOverrides, type RecordTable, readRecordSheetTable, resolveRecordSheetId, SHEETS_SCOPE, seededRandom, TRIAGE_GATES, TRIAGE_LANES, TRIAGE_STAGES, type TriageGateSampleOptions, type TriageGateSampleResult, type TriageHealthOptions, type TriageHealthResult, type TriageLane, type TriageProvider, type TriageRecordRow, type TriageSampleRow, type TriageSoakReportOptions, type TriageSoakReportResult, type TriageSourceOptions, type TriageStage, type TriageWindow, triageGateSample, triageHealth, triageSoakReport, } from "./triage-gates.js";
32
41
  export { type CloneProtocol, repoUrl, WIZARD_REPO_NAMES, type WizardStep, type WizardWorkspaceOptions, type WizardWorkspaceResult, wizardWorkspace, } from "./wizard.js";
33
42
  export { type EnvExampleStatus, refreshEnvExample, refreshWorkspaceDocs, resolveTemplateDir, type WorkspaceDocsResult, } from "./workspace-docs.js";
43
+ export { pushWorkspaceRepos, type WorkspacePushOptions, type WorkspacePushRepoResult, type WorkspacePushRepoStatus, type WorkspacePushResult, } from "./workspace-push.js";
44
+ export { type WorkspaceRepoState, type WorkspaceRepoStatus, type WorkspaceStatusOptions, type WorkspaceStatusResult, workspaceStatus, } from "./workspace-status.js";
package/dist/index.js CHANGED
@@ -1,7 +1,9 @@
1
1
  // @installagent/sdk — the only place with real logic. apps/cli and
2
2
  // apps/mcp are thin adapters over these exports; every operation here must be
3
3
  // reachable from both. See ../../docs/spec.md.
4
+ export { checkAgentMirror, } from "./agent-mirror.js";
4
5
  export { createFromAgentTemplate, listAgentTemplates, N8N_API_KEY_ENV, N8N_API_URL_ENV, N8nAuthError, sanitizeN8nWorkflow, saveAgentTemplate, searchAgentTemplates, } from "./agent-templates.js";
6
+ export { CLAUDE_CONFIG_DIR_ENV, compactClaudeHoursExport, deliverClaudeHoursExport, exportClaudeHours, HOURS_EXPORT_DIR, HOURS_EXPORT_SCHEMA, HOURS_EXPORT_SECRET_ENV, HOURS_EXPORT_SECRET_HEADER, HOURS_EXPORT_WEBHOOK_URL, PROMPT_WINDOW_MINUTES, parseLedgerDate, parseMinuteIso, saveClaudeHoursExport, sendClaudeHoursExport, TOOL_INPUT_PATH_KEYS, UNATTRIBUTED_SLUG, } from "./claude-hours.js";
5
7
  export { ClientBuildAuthError, clientBuild, GITHUB_API_TOKEN_ENV, } from "./client-build.js";
6
8
  export { clientContext, } from "./client-context.js";
7
9
  export { AIRTABLE_API_TOKEN_ENV, buildAssertionClaims, ClientDriveAuthError, clientDriveSearch, GOOGLE_SERVICE_ACCOUNT_KEY_ENV, parseServiceAccountKey, } from "./client-drive.js";
@@ -19,18 +21,27 @@ export { MINT_HANDOFF_WARNING, mintGcpServiceAccountKey, } from "./gcp-service-a
19
21
  export { DEFAULT_GEMINI_KEY_DISPLAY_NAME, GEMINI_API_TARGET, mintGeminiApiKey, } from "./gemini-api-key.js";
20
22
  export { gitClone, gitPullFfOnly } from "./git.js";
21
23
  export { GITHUB_TOKEN_FIX, resolveGithubToken, } from "./github-token.js";
24
+ export { buildServiceAccountClaims, GOOGLE_TOKEN_URL, GoogleServiceAccountAuthError, getServiceAccountAccessToken, } from "./google-service-account.js";
25
+ export { estimateHours, HOURS_SOURCES, LEAD_HEAVY_MINUTES, LEAD_LIGHT_MINUTES, LEDGER_TIME_ZONE, ledgerDay, ledgerMonth, roundMonths, SESSION_GAP_MINUTES, } from "./hours-estimate.js";
26
+ export { installHoursExportSchedule, uninstallHoursExportSchedule, } from "./hours-export-schedule.js";
27
+ export { buildHoursLedger, CLIENT_FIELDS, DEFAULT_HOURS_LEDGER_DIR, identityMatches, LEDGER_WINDOW_START, OTHER_LEAD_SLUG, TEAM_FIELDS, } from "./hours-ledger.js";
22
28
  export { CLIENT_TEMPLATE_URL, initWorkspace, MCP_RECOMMENDATIONS, TEAM_CLIENTS_URL, } from "./init.js";
23
- export { findProjectBySlugId, LINEAR_API_TOKEN_ENV, LinearAuthError, LinearProjectNotFoundError, linearProject, linearProjectIssues, } from "./linear-project.js";
29
+ export { findProjectBySlugId, LINEAR_API_TOKEN_ENV, LinearAuthError, LinearProjectNotFoundError, linearProject, linearProjectIssues, linearRequest, } from "./linear-project.js";
24
30
  export { createLogger, redactFields, } from "./log.js";
25
31
  export { extractNodeOutputs, listN8nExecutions, listNodesRun, unflattenExecutionData, } from "./n8n-executions.js";
26
32
  export { newClient, SLUG_PATTERN, } from "./new-client.js";
27
33
  export { opInstallCommand, opInstallFix, opIntegrationFix } from "./op-cli.js";
28
34
  export { ping } from "./ping.js";
29
35
  export { detectPlatform, detectPlatformInfo, detectShell, opNeedsAnotherShell, } from "./platform.js";
30
- export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, PortalAdminAuthError, portalAddUser, portalCreateAgent, portalCreateOrg, portalListAgents, portalListOrgs, portalSetAgentName, portalSetAgentStatus, portalSetAgentWorkflow, portalSetDriveFolder, portalSetPassword, portalSyncRuns, } from "./portal-admin.js";
36
+ export { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_PASSWORD_WARNING, PORTAL_SYNC_MAX_DAYS, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, portalAddUser, portalBackfillTriageRecords, portalCreateAgent, portalCreateOrg, portalListAgents, portalListOrgs, portalReadTriageRecords, portalSetAgentName, portalSetAgentStatus, portalSetAgentTriage, portalSetAgentWorkflow, portalSetDriveFolder, portalSetOrgSlackChannel, portalSetPassword, portalSyncRuns, } from "./portal-admin.js";
31
37
  export { standup, } from "./standup.js";
32
- export { syncRepos, } from "./sync-repos.js";
38
+ export { syncRepos, workspaceRepoNames, } from "./sync-repos.js";
33
39
  export { syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
34
40
  export { TEMPLATE_SYNCED_FILES, templateSync, } from "./template-sync.js";
41
+ export { TRIAGE_BACKFILL_CHUNK, triageBackfill, } from "./triage-backfill.js";
42
+ export { checkTriageRecordWiring, detectWorkflowProvider, PORTAL_INGEST_CREDENTIAL_NAME, TRIAGE_RECORDS_PATH, triageEnable, } from "./triage-enable.js";
43
+ export { CRITICAL_PRIORITIES, CRITICAL_URGENCIES, detectProvider, GMAIL_HEADERS, GMAIL_LANE_BY_DISPOSITION, laneFor, OUTLOOK_HEADERS, OUTLOOK_LANE_BY_CATEGORY, parseCsv, parseLaneOverrides, readRecordSheetTable, resolveRecordSheetId, SHEETS_SCOPE, seededRandom, TRIAGE_GATES, TRIAGE_LANES, TRIAGE_STAGES, triageGateSample, triageHealth, triageSoakReport, } from "./triage-gates.js";
35
44
  export { repoUrl, WIZARD_REPO_NAMES, wizardWorkspace, } from "./wizard.js";
36
45
  export { refreshEnvExample, refreshWorkspaceDocs, resolveTemplateDir, } from "./workspace-docs.js";
46
+ export { pushWorkspaceRepos, } from "./workspace-push.js";
47
+ export { workspaceStatus, } from "./workspace-status.js";
@@ -6,6 +6,13 @@ export declare const PORTAL_SYNC_MAX_DAYS = 90;
6
6
  /** Thrown when the portal admin secret is missing or rejected. */
7
7
  export declare class PortalAdminAuthError extends Error {
8
8
  }
9
+ /** Any other non-2xx answer: the status and the server's own message, for callers that branch on them. */
10
+ export declare class PortalRequestError extends Error {
11
+ readonly status: number;
12
+ readonly serverError: string | null;
13
+ constructor(message: string, status: number, serverError: string | null);
14
+ }
15
+ export type PortalTriageProvider = "gmail" | "outlook";
9
16
  export interface PortalAdminOptions {
10
17
  /** Bearer secret; defaults to $IA_PORTAL_ADMIN_SECRET. */
11
18
  secret?: string;
@@ -27,6 +34,8 @@ export interface PortalOrg {
27
34
  status: string;
28
35
  driveFolderId: string | null;
29
36
  airtableRecordId: string | null;
37
+ /** The client channel the weekly triage digest posts to; null = no digest. */
38
+ slackChannelId?: string | null;
30
39
  users: PortalOrgUser[];
31
40
  }
32
41
  export interface PortalAgent {
@@ -38,6 +47,8 @@ export interface PortalAgent {
38
47
  status: "active" | "paused" | "retired";
39
48
  n8nActive: boolean | null;
40
49
  lastSyncedAt: string | null;
50
+ /** Set = an email-triage agent of that provider. Absent on portals older than 2026-09-29. */
51
+ triageProvider?: PortalTriageProvider | null;
41
52
  }
42
53
  export interface PortalCreateOrgInput {
43
54
  slug: string;
@@ -171,3 +182,60 @@ export declare function portalListAgents(input?: {
171
182
  export declare function portalSyncRuns(input?: {
172
183
  days?: number;
173
184
  }, options?: PortalAdminOptions): Promise<PortalSyncRunsResult>;
185
+ export interface PortalSetAgentTriageResult {
186
+ org: string;
187
+ agent: string;
188
+ triageProvider: PortalTriageProvider | null;
189
+ }
190
+ /**
191
+ * Mark an agent as an email-triage agent of one provider, or clear it with
192
+ * null. Only a triage agent may write classification rows, and the provider
193
+ * decides the row shape the portal accepts.
194
+ */
195
+ export declare function portalSetAgentTriage(input: {
196
+ slug: string;
197
+ agent: string;
198
+ provider: PortalTriageProvider | null;
199
+ }, options?: PortalAdminOptions): Promise<PortalSetAgentTriageResult>;
200
+ /** Where the weekly triage digest posts for this client; null = no digest. */
201
+ export declare function portalSetOrgSlackChannel(input: {
202
+ slug: string;
203
+ channelId: string | null;
204
+ }, options?: PortalAdminOptions): Promise<{
205
+ slug: string;
206
+ slackChannelId: string | null;
207
+ }>;
208
+ export interface PortalTriageRecordsPage {
209
+ org: string;
210
+ agent: string;
211
+ provider: PortalTriageProvider;
212
+ /** Record-sheet-shaped rows: the provider's own header names, every cell a string. */
213
+ rows: Record<string, string>[];
214
+ /** Cursor for the next page, or null on the last one. */
215
+ next: string | null;
216
+ }
217
+ /** One page of a triage agent's classification rows, oldest first. */
218
+ export declare function portalReadTriageRecords(input: {
219
+ org: string;
220
+ agent?: string;
221
+ since?: Date;
222
+ until?: Date;
223
+ after?: string;
224
+ limit?: number;
225
+ }, options?: PortalAdminOptions): Promise<PortalTriageRecordsPage>;
226
+ export interface PortalTriageBackfillResult {
227
+ org: string;
228
+ agent: string;
229
+ received: number;
230
+ inserted: number;
231
+ duplicates: number;
232
+ }
233
+ /**
234
+ * One backfill batch of record-sheet rows (the portal accepts 1–500). The
235
+ * insert is idempotent on (agent, message_id), so a re-run inserts nothing.
236
+ */
237
+ export declare function portalBackfillTriageRecords(input: {
238
+ org: string;
239
+ agent?: string;
240
+ rows: Record<string, string>[];
241
+ }, options?: PortalAdminOptions): Promise<PortalTriageBackfillResult>;
@@ -18,6 +18,16 @@ export const PORTAL_SYNC_MAX_DAYS = 90;
18
18
  /** Thrown when the portal admin secret is missing or rejected. */
19
19
  export class PortalAdminAuthError extends Error {
20
20
  }
21
+ /** Any other non-2xx answer: the status and the server's own message, for callers that branch on them. */
22
+ export class PortalRequestError extends Error {
23
+ status;
24
+ serverError;
25
+ constructor(message, status, serverError) {
26
+ super(message);
27
+ this.status = status;
28
+ this.serverError = serverError;
29
+ }
30
+ }
21
31
  /** Lowercase then validate, matching the server (and the old script). */
22
32
  function normalizeSlug(value, field) {
23
33
  const slug = value.toLowerCase();
@@ -53,7 +63,7 @@ async function portalRequest(method, path, options, body) {
53
63
  ? String(data.error)
54
64
  : null)
55
65
  .catch(() => null);
56
- throw new Error(`${method} ${path} failed: HTTP ${res.status}${serverError ? ` — ${serverError}` : ""}`);
66
+ throw new PortalRequestError(`${method} ${path} failed: HTTP ${res.status}${serverError ? ` — ${serverError}` : ""}`, res.status, serverError);
57
67
  }
58
68
  return (await res.json());
59
69
  }
@@ -172,3 +182,56 @@ export async function portalSyncRuns(input = {}, options = {}) {
172
182
  throw new Error(`${message} (the sync is idempotent — safe to re-run, or use a smaller --days)`);
173
183
  }
174
184
  }
185
+ // ─── Email-triage record (the portal's triage_classifications) ─────────────
186
+ function assertProvider(provider) {
187
+ if (provider !== null && provider !== "gmail" && provider !== "outlook") {
188
+ throw new Error("provider must be gmail|outlook, or null to clear it");
189
+ }
190
+ }
191
+ /**
192
+ * Mark an agent as an email-triage agent of one provider, or clear it with
193
+ * null. Only a triage agent may write classification rows, and the provider
194
+ * decides the row shape the portal accepts.
195
+ */
196
+ export async function portalSetAgentTriage(input, options = {}) {
197
+ const slug = normalizeSlug(input.slug, "org");
198
+ const agent = normalizeSlug(input.agent, "agent");
199
+ assertProvider(input.provider);
200
+ return portalRequest("POST", "/api/admin/agents/triage", options, {
201
+ slug,
202
+ agent,
203
+ provider: input.provider,
204
+ });
205
+ }
206
+ /** Where the weekly triage digest posts for this client; null = no digest. */
207
+ export async function portalSetOrgSlackChannel(input, options = {}) {
208
+ const slug = normalizeSlug(input.slug, "org");
209
+ const channelId = input.channelId === null ? null : input.channelId.trim();
210
+ return portalRequest("POST", "/api/admin/orgs/slack-channel", options, { slug, channelId });
211
+ }
212
+ /** One page of a triage agent's classification rows, oldest first. */
213
+ export async function portalReadTriageRecords(input, options = {}) {
214
+ const query = new URLSearchParams({ org: normalizeSlug(input.org, "org") });
215
+ if (input.agent)
216
+ query.set("agent", normalizeSlug(input.agent, "agent"));
217
+ if (input.since)
218
+ query.set("since", input.since.toISOString());
219
+ if (input.until)
220
+ query.set("until", input.until.toISOString());
221
+ if (input.after)
222
+ query.set("after", input.after);
223
+ if (input.limit !== undefined)
224
+ query.set("limit", String(input.limit));
225
+ return portalRequest("GET", `/api/admin/triage-records?${query.toString()}`, options);
226
+ }
227
+ /**
228
+ * One backfill batch of record-sheet rows (the portal accepts 1–500). The
229
+ * insert is idempotent on (agent, message_id), so a re-run inserts nothing.
230
+ */
231
+ export async function portalBackfillTriageRecords(input, options = {}) {
232
+ return portalRequest("POST", "/api/admin/triage-records", options, {
233
+ org: normalizeSlug(input.org, "org"),
234
+ ...(input.agent ? { agent: normalizeSlug(input.agent, "agent") } : {}),
235
+ rows: input.rows,
236
+ });
237
+ }
@@ -44,4 +44,11 @@ export interface SyncReposResult {
44
44
  envExample?: EnvExampleStatus;
45
45
  nextSteps: string[];
46
46
  }
47
+ /**
48
+ * Every repo `ia sync`/`ia status`/`ia push` operate on: the team repos plus
49
+ * every `clients/client-*` clone actually present on this machine. POSIX-
50
+ * separated relative paths (see `clientRepoPaths`) — split with `/` before
51
+ * joining onto a filesystem path.
52
+ */
53
+ export declare function workspaceRepoNames(workspaceDir: string): string[];
47
54
  export declare function syncRepos(options?: SyncReposOptions): Promise<SyncReposResult>;
@@ -21,6 +21,15 @@ function clientRepoPaths(workspaceDir) {
21
21
  .filter((rel) => existsSync(join(workspaceDir, ...rel.split("/"), ".git")))
22
22
  .sort();
23
23
  }
24
+ /**
25
+ * Every repo `ia sync`/`ia status`/`ia push` operate on: the team repos plus
26
+ * every `clients/client-*` clone actually present on this machine. POSIX-
27
+ * separated relative paths (see `clientRepoPaths`) — split with `/` before
28
+ * joining onto a filesystem path.
29
+ */
30
+ export function workspaceRepoNames(workspaceDir) {
31
+ return [...WIZARD_REPO_NAMES.map(String), ...clientRepoPaths(workspaceDir)];
32
+ }
24
33
  export async function syncRepos(options = {}) {
25
34
  const dir = resolve(options.dir ?? ".");
26
35
  const pull = options.pull ?? gitPullFfOnly;
@@ -28,7 +37,7 @@ export async function syncRepos(options = {}) {
28
37
  // Team repos first (team-tools carries the templates a --docs refresh
29
38
  // reads, so it must be current before the docs step runs), then every
30
39
  // client clone the technician actually has.
31
- const targets = [...WIZARD_REPO_NAMES.map(String), ...clientRepoPaths(dir)];
40
+ const targets = workspaceRepoNames(dir);
32
41
  const repos = [];
33
42
  for (const rel of targets) {
34
43
  // rel is always POSIX (see clientRepoPaths); split it back out so the
@@ -19,15 +19,16 @@
19
19
  * design, so byte-drift is expected, and repo-lint already enforces their
20
20
  * presence.
21
21
  *
22
- * pr-to-slack.yml (added 2026-08-22) is the review notification every repo
23
- * posts to Slack's #notify-prs. It carries no client-specific content — the
24
- * repo name comes from the GitHub event and the webhook URL from an org-level
25
- * secret — so it syncs verbatim. Keeping it here matters more than for the
26
- * lint chain: a per-repo edit to the Block Kit payload silently changes what
27
- * the reviewer sees, and the n8n receiver ("GitHub PR Actions (Slack)")
28
- * derives owner/repo/PR number by regex over the PR URL in the message
29
- * blocks, so a repo that drops or reshapes that block breaks its own buttons
30
- * with no error anywhere.
22
+ * pr-to-slack.yml (added 2026-08-22, switched from the fantomă webhook to
23
+ * @Agent Zero 2026-08-26) is the review notification every repo posts to
24
+ * Slack's #notify-prs. It carries no client-specific content — the repo name
25
+ * comes from the GitHub event and the posting token from an org-level secret
26
+ * — so it syncs verbatim. Keeping it here matters more than for the lint
27
+ * chain: a per-repo edit to the Block Kit payload silently changes what the
28
+ * reviewer sees, and the pr_merge/pr_close button `value` carries the
29
+ * owner/repo/PR number as JSON for Agent Zero to act on, so a repo that
30
+ * drops or reshapes that block breaks its own buttons with no error
31
+ * anywhere.
31
32
  */
32
33
  export declare const TEMPLATE_SYNCED_FILES: string[];
33
34
  export interface TemplateSyncOptions {
@@ -22,15 +22,16 @@ import { dirname, join, resolve } from "node:path";
22
22
  * design, so byte-drift is expected, and repo-lint already enforces their
23
23
  * presence.
24
24
  *
25
- * pr-to-slack.yml (added 2026-08-22) is the review notification every repo
26
- * posts to Slack's #notify-prs. It carries no client-specific content — the
27
- * repo name comes from the GitHub event and the webhook URL from an org-level
28
- * secret — so it syncs verbatim. Keeping it here matters more than for the
29
- * lint chain: a per-repo edit to the Block Kit payload silently changes what
30
- * the reviewer sees, and the n8n receiver ("GitHub PR Actions (Slack)")
31
- * derives owner/repo/PR number by regex over the PR URL in the message
32
- * blocks, so a repo that drops or reshapes that block breaks its own buttons
33
- * with no error anywhere.
25
+ * pr-to-slack.yml (added 2026-08-22, switched from the fantomă webhook to
26
+ * @Agent Zero 2026-08-26) is the review notification every repo posts to
27
+ * Slack's #notify-prs. It carries no client-specific content — the repo name
28
+ * comes from the GitHub event and the posting token from an org-level secret
29
+ * — so it syncs verbatim. Keeping it here matters more than for the lint
30
+ * chain: a per-repo edit to the Block Kit payload silently changes what the
31
+ * reviewer sees, and the pr_merge/pr_close button `value` carries the
32
+ * owner/repo/PR number as JSON for Agent Zero to act on, so a repo that
33
+ * drops or reshapes that block breaks its own buttons with no error
34
+ * anywhere.
34
35
  */
35
36
  export const TEMPLATE_SYNCED_FILES = [
36
37
  "CADENCE.md",
@@ -39,6 +40,10 @@ export const TEMPLATE_SYNCED_FILES = [
39
40
  "lefthook.yml",
40
41
  ".github/workflows/repo-lint.yml",
41
42
  ".github/workflows/pr-to-slack.yml",
43
+ // The generic kickoff deck the technician presents on the first call. Same
44
+ // file in every client repo, never edited per client — client specifics go
45
+ // in that repo's onboarding.html.
46
+ "docs/kickoff-presentation.html",
42
47
  ];
43
48
  /**
44
49
  * Compare (and optionally fix) the shared infra files every client-<slug>
@@ -0,0 +1,37 @@
1
+ import { type PortalAdminOptions } from "./portal-admin.js";
2
+ import { type TriageProvider, type TriageSourceOptions } from "./triage-gates.js";
3
+ /** The portal accepts 1–500 rows a request; 200 keeps each body far below its cap. */
4
+ export declare const TRIAGE_BACKFILL_CHUNK = 200;
5
+ export interface TriageBackfillOptions extends Pick<TriageSourceOptions, "csv" | "sheetId" | "workspaceDir" | "serviceAccountKey" | "fetchImpl" | "now"> {
6
+ /** Portal agent slug — needed only when the org has more than one triage agent. */
7
+ agent?: string;
8
+ /** Portal admin API access; the secret defaults to $IA_PORTAL_ADMIN_SECRET. */
9
+ portal?: Omit<PortalAdminOptions, "fetchImpl">;
10
+ /** Read and count only; send nothing. */
11
+ dryRun?: boolean;
12
+ /**
13
+ * A JSON file with the 🧺 Batch Record Rows output of an n8n execution —
14
+ * `{ rows: […] }`, the batch object, n8n's copied item list, or a bare array
15
+ * of rows — instead of a sheet.
16
+ */
17
+ rowsFile?: string;
18
+ }
19
+ export interface TriageBackfillResult {
20
+ slug: string;
21
+ provider: TriageProvider;
22
+ source: string;
23
+ /** The portal agent the rows landed under (null on a dry run). */
24
+ agent: string | null;
25
+ /** Record rows found in the sheet. */
26
+ rowsInSource: number;
27
+ sent: number;
28
+ inserted: number;
29
+ duplicates: number;
30
+ /** Sheet rows with no valid recorded_at or message_id — not records, never sent. */
31
+ skipped: number;
32
+ /** Sheet columns the template does not write — dropped, because the portal refuses unknown keys. */
33
+ droppedHeaders: string[];
34
+ chunks: number;
35
+ dryRun: boolean;
36
+ }
37
+ export declare function triageBackfill(slug: string, options?: TriageBackfillOptions): Promise<TriageBackfillResult>;
@@ -0,0 +1,211 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import { PORTAL_ADMIN_SECRET_ENV, PortalAdminAuthError, PortalRequestError, portalBackfillTriageRecords, portalListAgents, } from "./portal-admin.js";
3
+ import { detectProvider, GMAIL_HEADERS, OUTLOOK_HEADERS, readRecordSheetTable, } from "./triage-gates.js";
4
+ // `ia triage backfill <slug>`: copy a client's classification record SHEET
5
+ // into the portal (`triage_classifications`) — the first step of moving a
6
+ // client off the sheet. The rows go over as they are (the portal's wire row
7
+ // IS the sheet row), through the portal's admin backfill door, which shares
8
+ // the ingest's validation and its idempotent insert. So a re-run inserts
9
+ // nothing, and "new: 0" on a re-run is the proof that every sheet row is in
10
+ // the portal. Reads the sheet only — never the portal as its source.
11
+ //
12
+ // `--rows <file>` is the recovery path for a client with no sheet: when a
13
+ // record POST fails, the technician copies the 🧺 Batch Record Rows output of
14
+ // that execution into a file, and this sends the same rows through the same
15
+ // door. The batch names its workflow, so rows of another client's workflow
16
+ // are refused before anything is sent.
17
+ /** The portal accepts 1–500 rows a request; 200 keeps each body far below its cap. */
18
+ export const TRIAGE_BACKFILL_CHUNK = 200;
19
+ /** A value from the n8n output as the sheet would hold it. */
20
+ function asCell(value) {
21
+ if (value === null || value === undefined)
22
+ return "";
23
+ if (Array.isArray(value))
24
+ return value.map(asCell).join("|");
25
+ if (typeof value === "object")
26
+ return JSON.stringify(value);
27
+ return String(value);
28
+ }
29
+ function isRecord(value) {
30
+ return typeof value === "object" && value !== null && !Array.isArray(value);
31
+ }
32
+ /**
33
+ * The rows and the workflow ids in a copied 🧺 Batch Record Rows output. n8n
34
+ * copies an item list (`[{…batch}]`, sometimes `[{ json: {…batch} }]`); a
35
+ * technician may also paste only the batch, only `{ rows }`, or the rows.
36
+ */
37
+ function rowsOfBatchOutput(value) {
38
+ const rows = [];
39
+ const workflowIds = new Set();
40
+ const visit = (item) => {
41
+ if (Array.isArray(item)) {
42
+ for (const entry of item)
43
+ visit(entry);
44
+ return;
45
+ }
46
+ if (!isRecord(item))
47
+ return;
48
+ if (isRecord(item.json) && Object.keys(item).every((k) => k === "json" || k === "pairedItem")) {
49
+ visit(item.json);
50
+ return;
51
+ }
52
+ if (Array.isArray(item.rows)) {
53
+ if (typeof item.workflowId === "string" && item.workflowId.trim()) {
54
+ workflowIds.add(item.workflowId.trim());
55
+ }
56
+ for (const row of item.rows)
57
+ if (isRecord(row))
58
+ rows.push(row);
59
+ return;
60
+ }
61
+ if ("message_id" in item)
62
+ rows.push(item);
63
+ };
64
+ visit(value);
65
+ return { rows, workflowIds };
66
+ }
67
+ /** The rows file as a header + body table — the shape the sheet path already sends. */
68
+ async function readRowsFileTable(path) {
69
+ let parsed;
70
+ try {
71
+ parsed = JSON.parse(await readFile(path, "utf8"));
72
+ }
73
+ catch (error) {
74
+ const reason = error instanceof Error ? error.message : String(error);
75
+ throw new Error(`cannot read the rows file ${path}: ${reason}`);
76
+ }
77
+ const { rows, workflowIds } = rowsOfBatchOutput(parsed);
78
+ if (rows.length === 0) {
79
+ throw new Error(`${path} holds no record rows — copy the OUTPUT of 🧺 Batch Record Rows (its rows[] carry ` +
80
+ "recorded_at, message_id, …) from the failed execution");
81
+ }
82
+ if (workflowIds.size > 1) {
83
+ throw new Error(`${path} mixes rows from two or more workflows (${[...workflowIds].join(", ")}) — one file per workflow`);
84
+ }
85
+ const header = [];
86
+ for (const row of rows)
87
+ for (const key of Object.keys(row))
88
+ if (!header.includes(key))
89
+ header.push(key);
90
+ return {
91
+ table: [header, ...rows.map((row) => header.map((key) => asCell(row[key])))],
92
+ workflowId: [...workflowIds][0] ?? null,
93
+ };
94
+ }
95
+ function toWireRows(provider, header, body, firstLine) {
96
+ const keys = header.map((h) => h.trim());
97
+ const allowed = provider === "gmail" ? GMAIL_HEADERS : OUTLOOK_HEADERS;
98
+ const droppedHeaders = keys.filter((k) => k && !allowed.includes(k));
99
+ const rows = [];
100
+ let skipped = 0;
101
+ body.forEach((line, index) => {
102
+ const cells = {};
103
+ for (const key of allowed) {
104
+ const column = keys.indexOf(key);
105
+ cells[key] = column === -1 ? "" : (line[column] ?? "").trim();
106
+ }
107
+ const recordedAt = new Date(cells.recorded_at ?? "");
108
+ if (Number.isNaN(recordedAt.getTime()) || !cells.message_id) {
109
+ skipped += 1;
110
+ return;
111
+ }
112
+ // Sheet row numbers count the header as row 1; a rows file counts from 1.
113
+ rows.push({ line: index + firstLine, cells });
114
+ });
115
+ return { rows, skipped, droppedHeaders };
116
+ }
117
+ /** "rows[3]: …" from the portal → the sheet row it came from. */
118
+ function refusedSheetRow(error, chunk) {
119
+ const match = /rows\[(\d+)\]/.exec(error.serverError ?? "");
120
+ const row = match ? chunk[Number(match[1])] : undefined;
121
+ return row ? row.line : null;
122
+ }
123
+ /**
124
+ * The agent of this client that reports as `workflowId`. Refuses rows from a
125
+ * workflow no agent of the client runs — the wrong file, or the wrong client.
126
+ */
127
+ async function agentOfWorkflow(slug, workflowId, wanted, portalOptions) {
128
+ const { agents } = await portalListAgents({ slug }, portalOptions);
129
+ const owner = agents.find((a) => a.workflowId === workflowId);
130
+ if (!owner) {
131
+ throw new Error(`the rows come from n8n workflow ${workflowId}, but no agent under ${slug} reports as that ` +
132
+ "workflow — the wrong file, or the wrong client. Nothing was sent.");
133
+ }
134
+ if (wanted && wanted !== owner.slug) {
135
+ throw new Error(`the rows come from ${slug}/${owner.slug} (workflow ${workflowId}), not --agent ${wanted}`);
136
+ }
137
+ return owner.slug;
138
+ }
139
+ export async function triageBackfill(slug, options = {}) {
140
+ const portalOptions = {
141
+ ...options.portal,
142
+ ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
143
+ };
144
+ if (!options.dryRun && !(portalOptions.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV])) {
145
+ throw new PortalAdminAuthError(`the backfill writes to the portal — set ${PORTAL_ADMIN_SECRET_ENV} (ia env fill), or add --dry-run to only count`);
146
+ }
147
+ let record;
148
+ let agent = options.agent;
149
+ if (options.rowsFile) {
150
+ if (options.csv || options.sheetId) {
151
+ throw new Error(`pass --rows or a sheet source (--csv / --sheet), not both`);
152
+ }
153
+ const file = await readRowsFileTable(options.rowsFile);
154
+ if (file.workflowId && (portalOptions.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV])) {
155
+ agent = await agentOfWorkflow(slug, file.workflowId, agent, portalOptions);
156
+ }
157
+ record = {
158
+ table: file.table,
159
+ source: `rows file ${options.rowsFile}${file.workflowId ? ` (workflow ${file.workflowId})` : ""}`,
160
+ };
161
+ }
162
+ else {
163
+ record = await readRecordSheetTable(slug, options);
164
+ }
165
+ const [header, ...body] = record.table;
166
+ if (!header)
167
+ throw new Error(`${record.source} is empty — the header row must be row 1`);
168
+ const provider = detectProvider(header);
169
+ const fromFile = options.rowsFile !== undefined;
170
+ const { rows, skipped, droppedHeaders } = toWireRows(provider, header, body, fromFile ? 1 : 2);
171
+ const rowName = (line) => fromFile ? `row ${line} of the rows file` : `sheet row ${line}`;
172
+ const rangeName = (first, last) => fromFile ? `rows ${first}–${last} of the rows file` : `sheet rows ${first}–${last}`;
173
+ const result = {
174
+ slug,
175
+ provider,
176
+ source: record.source,
177
+ agent: null,
178
+ rowsInSource: rows.length,
179
+ sent: 0,
180
+ inserted: 0,
181
+ duplicates: 0,
182
+ skipped,
183
+ droppedHeaders,
184
+ chunks: 0,
185
+ dryRun: options.dryRun === true,
186
+ };
187
+ if (options.dryRun)
188
+ return result;
189
+ for (let start = 0; start < rows.length; start += TRIAGE_BACKFILL_CHUNK) {
190
+ const chunk = rows.slice(start, start + TRIAGE_BACKFILL_CHUNK);
191
+ try {
192
+ const report = await portalBackfillTriageRecords({ org: slug, agent, rows: chunk.map((row) => row.cells) }, portalOptions);
193
+ result.agent = report.agent;
194
+ result.sent += report.received;
195
+ result.inserted += report.inserted;
196
+ result.duplicates += report.duplicates;
197
+ result.chunks += 1;
198
+ }
199
+ catch (error) {
200
+ if (!(error instanceof PortalRequestError))
201
+ throw error;
202
+ const line = refusedSheetRow(error, chunk);
203
+ const first = chunk[0]?.line ?? 0;
204
+ const last = chunk.at(-1)?.line ?? 0;
205
+ throw new Error(`the portal refused ${line ? rowName(line) : `the batch of ${rangeName(first, last)}`}: ` +
206
+ `${error.serverError ?? error.message}. ${result.sent} row(s) already sent ` +
207
+ `(${result.inserted} new) — the backfill is idempotent, so it is safe to re-run once the row is fixed.`);
208
+ }
209
+ }
210
+ return result;
211
+ }