@installagent/sdk 0.4.1 → 0.5.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 (37) hide show
  1. package/dist/agent-mirror.js +22 -10
  2. package/dist/agent-templates.d.ts +10 -12
  3. package/dist/agent-templates.js +34 -6
  4. package/dist/doctor.d.ts +11 -1
  5. package/dist/doctor.js +24 -22
  6. package/dist/index.d.ts +4 -1
  7. package/dist/index.js +4 -1
  8. package/dist/lefthook-hooks.d.ts +36 -0
  9. package/dist/lefthook-hooks.js +64 -0
  10. package/dist/n8n-defaults.d.ts +90 -0
  11. package/dist/n8n-defaults.js +153 -0
  12. package/dist/portal-admin.d.ts +104 -13
  13. package/dist/portal-admin.js +113 -28
  14. package/dist/pr-open.d.ts +45 -0
  15. package/dist/pr-open.js +98 -0
  16. package/dist/sync-repos.d.ts +8 -1
  17. package/dist/sync-repos.js +10 -9
  18. package/dist/triage-enable.js +20 -7
  19. package/package.json +1 -1
  20. package/templates/workspace-root/ONBOARDING.md +9 -7
  21. package/templates/workspace-root/skills/CLAUDE.md +4 -4
  22. package/templates/workspace-root/skills/README.md +2 -2
  23. package/templates/workspace-root/skills/ad-machine/SKILL.md +14 -18
  24. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +14 -16
  25. package/templates/workspace-root/skills/client-latest/SKILL.md +14 -18
  26. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +22 -16
  27. package/templates/workspace-root/skills/engagement-spec/SKILL.md +11 -14
  28. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +9 -0
  29. package/templates/workspace-root/skills/house-voice/SKILL.md +67 -19
  30. package/templates/workspace-root/skills/ia-cli/SKILL.md +14 -17
  31. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +14 -20
  32. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +2 -2
  33. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +13 -15
  34. package/templates/workspace-root/skills/slack-voice/SKILL.md +50 -31
  35. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +14 -15
  36. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +13 -19
  37. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +13 -15
@@ -0,0 +1,153 @@
1
+ /**
2
+ * House defaults for n8n workflows, and the lint that checks them.
3
+ *
4
+ * Measured 2026-10-15 on our shared instance: 0 of 48 workflows set a
5
+ * timeout, 33 of 48 had no retry anywhere, and 3 of 14 newer workflows had no
6
+ * error workflow — including a client-facing poller with 2,861 runs. A
7
+ * workflow without an error workflow fails in silence. These defaults live in
8
+ * every bank template; `ia agent create` fills the error workflow id and
9
+ * `ia agent lint` refuses a workflow without them.
10
+ */
11
+ /** The shared instance's global error handler (`IA - global-error-handler`). */
12
+ export const IA_ERROR_WORKFLOW_ID = "vJt4USrJnUQG0EWo";
13
+ /** What a bank template carries instead of a real error workflow id. */
14
+ export const ERROR_WORKFLOW_PLACEHOLDER = "REPLACE_ME_ERROR_WORKFLOW_ID";
15
+ /**
16
+ * 30 minutes. A ceiling for a stuck run, not a budget for a normal one: the
17
+ * longest agent runs on the instance finish in a few minutes. n8n kills the
18
+ * execution at this point and the error workflow reports it.
19
+ */
20
+ export const DEFAULT_EXECUTION_TIMEOUT_S = 1800;
21
+ /** The workflow-level `settings` every bank template carries. */
22
+ export const DEFAULT_WORKFLOW_SETTINGS = {
23
+ executionOrder: "v1",
24
+ errorWorkflow: ERROR_WORKFLOW_PLACEHOLDER,
25
+ executionTimeout: DEFAULT_EXECUTION_TIMEOUT_S,
26
+ saveDataErrorExecution: "all",
27
+ };
28
+ /** Node-level retry for read-only HTTP calls. Writes never retry: a retried POST can double-send. */
29
+ export const DEFAULT_GET_RETRY = {
30
+ retryOnFail: true,
31
+ maxTries: 3,
32
+ waitBetweenTries: 5000,
33
+ };
34
+ /**
35
+ * `<client-slug or IA> - <slug> - <purpose>` (team-web hub, Infra → n8n).
36
+ * Slugs are lowercase kebab-case; the purpose is free text.
37
+ */
38
+ export const WORKFLOW_NAME_PATTERN = /^(IA|[a-z0-9]+(?:-[a-z0-9]+)*) - [a-z0-9]+(?:-[a-z0-9]+)* - \S.*$/;
39
+ /** An HTTP Request node whose method is GET (n8n's default when unset). */
40
+ export function isGetHttpNode(node) {
41
+ if (node.type !== "n8n-nodes-base.httpRequest")
42
+ return false;
43
+ const method = node.parameters?.method;
44
+ return method === undefined || method === "GET";
45
+ }
46
+ /** True for an error handler itself: it must not point at an error workflow. */
47
+ function isErrorHandler(wf) {
48
+ return (wf.nodes ?? []).some((n) => n.type === "n8n-nodes-base.errorTrigger");
49
+ }
50
+ export function lintN8nWorkflow(wf, options = {}) {
51
+ const findings = [];
52
+ const settings = wf.settings ?? {};
53
+ const name = typeof wf.name === "string" ? wf.name : "";
54
+ if (!options.template && !WORKFLOW_NAME_PATTERN.test(name)) {
55
+ findings.push({
56
+ level: "error",
57
+ rule: "name-pattern",
58
+ message: `name "${name}" is not \`<client-slug or IA> - <slug> - <purpose>\` (use \`ia agent create --client <slug>\`)`,
59
+ });
60
+ }
61
+ if (!isErrorHandler(wf)) {
62
+ const errorWorkflow = settings.errorWorkflow;
63
+ if (options.template) {
64
+ if (errorWorkflow !== ERROR_WORKFLOW_PLACEHOLDER) {
65
+ findings.push({
66
+ level: "error",
67
+ rule: "error-workflow",
68
+ message: `settings.errorWorkflow must be "${ERROR_WORKFLOW_PLACEHOLDER}" in a bank template (found ${JSON.stringify(errorWorkflow ?? null)})`,
69
+ });
70
+ }
71
+ }
72
+ else if (typeof errorWorkflow !== "string" ||
73
+ errorWorkflow === "" ||
74
+ errorWorkflow.startsWith("REPLACE_ME")) {
75
+ findings.push({
76
+ level: "error",
77
+ rule: "error-workflow",
78
+ message: `settings.errorWorkflow is not set, so a failure reports nowhere (shared instance: ${IA_ERROR_WORKFLOW_ID})`,
79
+ });
80
+ }
81
+ }
82
+ const timeout = settings.executionTimeout;
83
+ if (typeof timeout !== "number" || timeout <= 0) {
84
+ findings.push({
85
+ level: "error",
86
+ rule: "timeout",
87
+ message: `settings.executionTimeout is not set, so a stuck run never ends (house default ${DEFAULT_EXECUTION_TIMEOUT_S} s)`,
88
+ });
89
+ }
90
+ for (const node of wf.nodes ?? []) {
91
+ if (isGetHttpNode(node) && node.retryOnFail !== true) {
92
+ findings.push({
93
+ level: "warn",
94
+ rule: "get-retry",
95
+ message: `node "${String(node.name)}" is a GET with no retry (Settings → Retry On Fail, 3 tries, 5000 ms)`,
96
+ });
97
+ }
98
+ }
99
+ return findings;
100
+ }
101
+ /**
102
+ * Turn a bank template into a client workflow: house settings filled in, the
103
+ * placeholder replaced by a real error workflow id, and (with a client slug)
104
+ * the house name. Keys the template already sets win over the defaults.
105
+ */
106
+ export function applyClientDefaults(wf, opts) {
107
+ const settings = {
108
+ ...DEFAULT_WORKFLOW_SETTINGS,
109
+ ...(wf.settings ?? {}),
110
+ };
111
+ const isHandler = (wf.nodes ?? []).some((n) => n.type === "n8n-nodes-base.errorTrigger");
112
+ if (isHandler)
113
+ delete settings.errorWorkflow;
114
+ else if (typeof settings.errorWorkflow !== "string" ||
115
+ settings.errorWorkflow === "" ||
116
+ settings.errorWorkflow.startsWith("REPLACE_ME")) {
117
+ settings.errorWorkflow = opts.errorWorkflowId ?? IA_ERROR_WORKFLOW_ID;
118
+ }
119
+ const out = { ...wf, settings };
120
+ if (opts.client)
121
+ out.name = clientWorkflowName(opts.client, opts.template, String(wf.name ?? ""));
122
+ return out;
123
+ }
124
+ /** `<client> - <template slug> - <purpose>`; the purpose is the template title without bank markers. */
125
+ export function clientWorkflowName(client, template, templateTitle) {
126
+ const purpose = templateTitle
127
+ .replace(/\s*\(template\)\s*$/i, "")
128
+ .replace(/^(Team|IA)\s+-\s+/, "")
129
+ .trim() || template;
130
+ return `${client} - ${template} - ${purpose}`;
131
+ }
132
+ /** `ia agent lint`: read each workflow JSON and lint it. A file that is not JSON fails. */
133
+ export async function lintWorkflowFiles(files, options = {}) {
134
+ const { readFile } = await import("node:fs/promises");
135
+ const results = [];
136
+ for (const file of files) {
137
+ let findings;
138
+ try {
139
+ findings = lintN8nWorkflow(JSON.parse(await readFile(file, "utf8")), options);
140
+ }
141
+ catch (error) {
142
+ findings = [
143
+ {
144
+ level: "error",
145
+ rule: "unreadable",
146
+ message: `cannot read as workflow JSON: ${error instanceof Error ? error.message : String(error)}`,
147
+ },
148
+ ];
149
+ }
150
+ results.push({ file, findings, failed: findings.some((f) => f.level === "error") });
151
+ }
152
+ return { ok: results.every((r) => !r.failed), results };
153
+ }
@@ -38,18 +38,43 @@ export interface PortalOrg {
38
38
  slackChannelId?: string | null;
39
39
  users: PortalOrgUser[];
40
40
  }
41
- export interface PortalAgent {
41
+ /**
42
+ * What kind of thing a portal build is (2026-10-13). `agent` = an automation
43
+ * that runs as an n8n workflow (workflow id required). `app` = something we
44
+ * built that has no runs — a web app or website — with an optional https
45
+ * `url` and NO workflow id.
46
+ */
47
+ export type PortalBuildType = "agent" | "app";
48
+ export declare const PORTAL_BUILD_TYPES: readonly PortalBuildType[];
49
+ /**
50
+ * One row of the portal's builds registry (named `agents` before 2026-10-13).
51
+ * The wire field is `workflowId` (the portal's `n8n_workflow_id` column).
52
+ */
53
+ export interface PortalBuild {
42
54
  org: string;
43
55
  slug: string;
44
56
  name: string;
45
57
  description: string;
46
- workflowId: string;
58
+ /** The n8n workflow id the build reports as; null for an app build. */
59
+ workflowId: string | null;
47
60
  status: "active" | "paused" | "retired";
48
61
  n8nActive: boolean | null;
49
62
  lastSyncedAt: string | null;
50
63
  /** Set = an email-triage agent of that provider. Absent on portals older than 2026-09-29. */
51
64
  triageProvider?: PortalTriageProvider | null;
65
+ /** Absent on portals older than 2026-10-13 — read it through `portalBuildType()`. */
66
+ buildType?: PortalBuildType;
67
+ /** An app build's https address; null/absent when there is none. */
68
+ url?: string | null;
69
+ /** ISO time the build was registered (its go-live date). Absent on portals older than 2026-10-16. */
70
+ createdAt?: string;
52
71
  }
72
+ /** Old name of `PortalBuild`, kept as an alias until the full rename. */
73
+ export type PortalAgent = PortalBuild;
74
+ /** The build's type; a portal older than 2026-10-13 sends none, and then every build is an agent. */
75
+ export declare function portalBuildType(build: PortalBuild): PortalBuildType;
76
+ /** The build's workflow id when it is an agent with one; null for an app (nothing to run). */
77
+ export declare function portalBuildWorkflowId(build: PortalBuild): string | null;
53
78
  export interface PortalCreateOrgInput {
54
79
  slug: string;
55
80
  name: string;
@@ -86,12 +111,27 @@ export interface PortalAddUserResult {
86
111
  export interface PortalListOrgsResult {
87
112
  orgs: PortalOrg[];
88
113
  }
89
- export interface PortalCreateAgentInput {
114
+ export interface PortalCreateBuildInput {
90
115
  slug: string;
91
- agent: string;
116
+ /** The build slug, e.g. "follow-up". */
117
+ build: string;
92
118
  name: string;
93
119
  description: string;
94
- workflowId: string;
120
+ /** Default "agent". */
121
+ buildType?: PortalBuildType;
122
+ /** Required for an agent; refused for an app. */
123
+ workflowId?: string;
124
+ /** Optional https address (an app's web app or website). */
125
+ url?: string;
126
+ }
127
+ /** Old input shape of `portalCreateAgent`: the build slug is `agent`. */
128
+ export type PortalCreateAgentInput = Omit<PortalCreateBuildInput, "build"> & {
129
+ agent: string;
130
+ };
131
+ export interface PortalSetBuildStatusInput {
132
+ slug: string;
133
+ build: string;
134
+ status: "active" | "paused" | "retired";
95
135
  }
96
136
  export interface PortalSetAgentStatusInput {
97
137
  slug: string;
@@ -131,9 +171,14 @@ export interface PortalSetAgentWorkflowResult {
131
171
  /** False when the agent already pointed there — the call is idempotent. */
132
172
  changed: boolean;
133
173
  }
174
+ /**
175
+ * The portal's list answer. The key stays `agents` on the wire (the
176
+ * `/api/admin/agents` route); every item is a build of either type.
177
+ */
134
178
  export interface PortalListAgentsResult {
135
- agents: PortalAgent[];
179
+ agents: PortalBuild[];
136
180
  }
181
+ export type PortalListBuildsResult = PortalListAgentsResult;
137
182
  export interface PortalAgentSyncRow {
138
183
  org: string;
139
184
  agent: string;
@@ -160,22 +205,61 @@ export declare function portalSetDriveFolder(input: {
160
205
  }, options?: PortalAdminOptions): Promise<PortalSetDriveFolderResult>;
161
206
  export declare function portalAddUser(input: PortalAddUserInput, options?: PortalAdminOptions): Promise<PortalAddUserResult>;
162
207
  export declare function portalListOrgs(options?: PortalAdminOptions): Promise<PortalListOrgsResult>;
208
+ /**
209
+ * The client-side check of a create: an agent needs its n8n workflow id, an
210
+ * app must not carry one, and a url (either type) must be https. The portal
211
+ * re-validates; this only stops an obvious mistake before the request.
212
+ */
213
+ export declare function validatePortalBuildFields(input: {
214
+ buildType?: string;
215
+ workflowId?: string;
216
+ url?: string;
217
+ }): {
218
+ buildType: PortalBuildType;
219
+ workflowId: string | null;
220
+ url: string | null;
221
+ };
222
+ /** Register a build (an agent or an app) for an org. */
223
+ export declare function portalCreateBuild(input: PortalCreateBuildInput, options?: PortalAdminOptions): Promise<{
224
+ agent: PortalBuild;
225
+ }>;
226
+ /** Old name of `portalCreateBuild` (the build slug is `agent`). */
163
227
  export declare function portalCreateAgent(input: PortalCreateAgentInput, options?: PortalAdminOptions): Promise<{
164
- agent: PortalAgent;
228
+ agent: PortalBuild;
165
229
  }>;
230
+ export declare function portalSetBuildStatus(input: PortalSetBuildStatusInput, options?: PortalAdminOptions): Promise<PortalSetAgentStatusResult>;
231
+ /** Old name of `portalSetBuildStatus`. */
166
232
  export declare function portalSetAgentStatus(input: PortalSetAgentStatusInput, options?: PortalAdminOptions): Promise<PortalSetAgentStatusResult>;
167
233
  /**
168
- * Rename an agent — the client-facing label on its card. The agent slug is the
234
+ * Rename a build — the client-facing label on its card. The build slug is the
169
235
  * stable identifier, so a rename breaks no reference.
170
236
  */
237
+ export declare function portalSetBuildName(input: {
238
+ slug: string;
239
+ build: string;
240
+ name: string;
241
+ }, options?: PortalAdminOptions): Promise<PortalSetAgentNameResult>;
242
+ /** Old name of `portalSetBuildName`. */
171
243
  export declare function portalSetAgentName(input: PortalSetAgentNameInput, options?: PortalAdminOptions): Promise<PortalSetAgentNameResult>;
172
244
  /**
173
- * Repoint an agent at a different n8n workflow — for a version bump (v2
245
+ * Repoint an agent build at a different n8n workflow — for a version bump (v2
174
246
  * replacing a retired v1), which is the same agent from the client's side.
175
247
  * The row keeps its slug, name, and run history; the portal re-observes the
176
- * new workflow's live state on the next sync.
248
+ * new workflow's live state on the next sync. An app build has no workflow;
249
+ * the portal refuses this call for one.
177
250
  */
251
+ export declare function portalSetBuildWorkflow(input: {
252
+ slug: string;
253
+ build: string;
254
+ workflowId: string;
255
+ }, options?: PortalAdminOptions): Promise<PortalSetAgentWorkflowResult>;
256
+ /** Old name of `portalSetBuildWorkflow`. */
178
257
  export declare function portalSetAgentWorkflow(input: PortalSetAgentWorkflowInput, options?: PortalAdminOptions): Promise<PortalSetAgentWorkflowResult>;
258
+ /** Every registered build (agents and apps), for all orgs or one. */
259
+ export declare function portalListBuilds(input?: {
260
+ slug?: string;
261
+ }, options?: PortalAdminOptions): Promise<PortalListBuildsResult>;
262
+ /** Old name of `portalListBuilds`. */
179
263
  export declare function portalListAgents(input?: {
180
264
  slug?: string;
181
265
  }, options?: PortalAdminOptions): Promise<PortalListAgentsResult>;
@@ -188,10 +272,17 @@ export interface PortalSetAgentTriageResult {
188
272
  triageProvider: PortalTriageProvider | null;
189
273
  }
190
274
  /**
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.
275
+ * Mark an agent build as an email-triage agent of one provider, or clear it
276
+ * with null. Only a triage agent may write classification rows, and the
277
+ * provider decides the row shape the portal accepts. An app build never runs,
278
+ * so it is never a triage agent.
194
279
  */
280
+ export declare function portalSetBuildTriage(input: {
281
+ slug: string;
282
+ build: string;
283
+ provider: PortalTriageProvider | null;
284
+ }, options?: PortalAdminOptions): Promise<PortalSetAgentTriageResult>;
285
+ /** Old name of `portalSetBuildTriage`. */
195
286
  export declare function portalSetAgentTriage(input: {
196
287
  slug: string;
197
288
  agent: string;
@@ -28,6 +28,18 @@ export class PortalRequestError extends Error {
28
28
  this.serverError = serverError;
29
29
  }
30
30
  }
31
+ export const PORTAL_BUILD_TYPES = ["agent", "app"];
32
+ /** The build's type; a portal older than 2026-10-13 sends none, and then every build is an agent. */
33
+ export function portalBuildType(build) {
34
+ return build.buildType ?? "agent";
35
+ }
36
+ /** The build's workflow id when it is an agent with one; null for an app (nothing to run). */
37
+ export function portalBuildWorkflowId(build) {
38
+ if (portalBuildType(build) !== "agent")
39
+ return null;
40
+ const id = build.workflowId?.trim();
41
+ return id ? id : null;
42
+ }
31
43
  /** Lowercase then validate, matching the server (and the old script). */
32
44
  function normalizeSlug(value, field) {
33
45
  const slug = value.toLowerCase();
@@ -105,62 +117,130 @@ export async function portalAddUser(input, options = {}) {
105
117
  export async function portalListOrgs(options = {}) {
106
118
  return portalRequest("GET", "/api/admin/orgs", options);
107
119
  }
108
- export async function portalCreateAgent(input, options = {}) {
120
+ // ─── Builds registry (named `agents` before 2026-10-13) ─────────────────────
121
+ //
122
+ // The portal renamed its `agents` registry to `builds` and added a build type
123
+ // (agent | app). The SDK still calls the `/api/admin/agents*` routes: they
124
+ // stay as aliases on the portal, so these calls work both before and after
125
+ // the portal deploy. When the full rename happens, switch every path below
126
+ // to `/api/admin/builds*` (same bodies) and drop the `*Agent*` aliases — see
127
+ // docs/spec.md § "Portal builds rename (2026-10-13)". The request body keeps
128
+ // the `agent` key: it is the portal's wire name for the build slug.
129
+ const BUILDS_PATH = "/api/admin/agents";
130
+ function isHttpsUrl(value) {
131
+ try {
132
+ return new URL(value).protocol === "https:";
133
+ }
134
+ catch {
135
+ return false;
136
+ }
137
+ }
138
+ /**
139
+ * The client-side check of a create: an agent needs its n8n workflow id, an
140
+ * app must not carry one, and a url (either type) must be https. The portal
141
+ * re-validates; this only stops an obvious mistake before the request.
142
+ */
143
+ export function validatePortalBuildFields(input) {
144
+ const buildType = input.buildType ?? "agent";
145
+ if (!PORTAL_BUILD_TYPES.includes(buildType)) {
146
+ throw new Error(`build type must be ${PORTAL_BUILD_TYPES.join("|")} (got "${buildType}")`);
147
+ }
148
+ const workflowId = input.workflowId?.trim() || null;
149
+ const url = input.url?.trim() || null;
150
+ if (buildType === "agent" && !workflowId) {
151
+ throw new Error("an agent build needs its n8n workflow id (--workflow)");
152
+ }
153
+ if (buildType === "app" && workflowId) {
154
+ throw new Error("an app build has no n8n workflow — drop --workflow, or use --type agent");
155
+ }
156
+ if (url && !isHttpsUrl(url)) {
157
+ throw new Error(`url must be an https:// address (got "${url}")`);
158
+ }
159
+ return { buildType: buildType, workflowId, url };
160
+ }
161
+ /** Register a build (an agent or an app) for an org. */
162
+ export async function portalCreateBuild(input, options = {}) {
109
163
  const slug = normalizeSlug(input.slug, "org");
110
- const agent = normalizeSlug(input.agent, "agent");
111
- return portalRequest("POST", "/api/admin/agents", options, {
164
+ const build = normalizeSlug(input.build, "build");
165
+ const fields = validatePortalBuildFields(input);
166
+ return portalRequest("POST", BUILDS_PATH, options, {
112
167
  slug,
113
- agent,
168
+ agent: build,
114
169
  name: input.name,
115
170
  description: input.description,
116
- workflowId: input.workflowId,
171
+ buildType: fields.buildType,
172
+ ...(fields.workflowId ? { workflowId: fields.workflowId } : {}),
173
+ ...(fields.url ? { url: fields.url } : {}),
117
174
  });
118
175
  }
119
- export async function portalSetAgentStatus(input, options = {}) {
176
+ /** Old name of `portalCreateBuild` (the build slug is `agent`). */
177
+ export async function portalCreateAgent(input, options = {}) {
178
+ const { agent, ...rest } = input;
179
+ return portalCreateBuild({ ...rest, build: agent }, options);
180
+ }
181
+ export async function portalSetBuildStatus(input, options = {}) {
120
182
  const slug = normalizeSlug(input.slug, "org");
121
- const agent = normalizeSlug(input.agent, "agent");
183
+ const build = normalizeSlug(input.build, "build");
122
184
  if (input.status !== "active" && input.status !== "paused" && input.status !== "retired") {
123
185
  throw new Error("status must be active|paused|retired");
124
186
  }
125
- return portalRequest("POST", "/api/admin/agents/status", options, {
187
+ return portalRequest("POST", `${BUILDS_PATH}/status`, options, {
126
188
  slug,
127
- agent,
189
+ agent: build,
128
190
  status: input.status,
129
191
  });
130
192
  }
193
+ /** Old name of `portalSetBuildStatus`. */
194
+ export async function portalSetAgentStatus(input, options = {}) {
195
+ return portalSetBuildStatus({ slug: input.slug, build: input.agent, status: input.status }, options);
196
+ }
131
197
  /**
132
- * Rename an agent — the client-facing label on its card. The agent slug is the
198
+ * Rename a build — the client-facing label on its card. The build slug is the
133
199
  * stable identifier, so a rename breaks no reference.
134
200
  */
135
- export async function portalSetAgentName(input, options = {}) {
201
+ export async function portalSetBuildName(input, options = {}) {
136
202
  const slug = normalizeSlug(input.slug, "org");
137
- const agent = normalizeSlug(input.agent, "agent");
203
+ const build = normalizeSlug(input.build, "build");
138
204
  const name = input.name.trim();
139
205
  if (!name)
140
206
  throw new Error("name required");
141
- return portalRequest("POST", "/api/admin/agents/name", options, { slug, agent, name });
207
+ return portalRequest("POST", `${BUILDS_PATH}/name`, options, { slug, agent: build, name });
208
+ }
209
+ /** Old name of `portalSetBuildName`. */
210
+ export async function portalSetAgentName(input, options = {}) {
211
+ return portalSetBuildName({ slug: input.slug, build: input.agent, name: input.name }, options);
142
212
  }
143
213
  /**
144
- * Repoint an agent at a different n8n workflow — for a version bump (v2
214
+ * Repoint an agent build at a different n8n workflow — for a version bump (v2
145
215
  * replacing a retired v1), which is the same agent from the client's side.
146
216
  * The row keeps its slug, name, and run history; the portal re-observes the
147
- * new workflow's live state on the next sync.
217
+ * new workflow's live state on the next sync. An app build has no workflow;
218
+ * the portal refuses this call for one.
148
219
  */
149
- export async function portalSetAgentWorkflow(input, options = {}) {
220
+ export async function portalSetBuildWorkflow(input, options = {}) {
150
221
  const slug = normalizeSlug(input.slug, "org");
151
- const agent = normalizeSlug(input.agent, "agent");
222
+ const build = normalizeSlug(input.build, "build");
152
223
  const workflowId = input.workflowId.trim();
153
224
  if (!workflowId)
154
225
  throw new Error("workflowId required");
155
- return portalRequest("POST", "/api/admin/agents/workflow-id", options, {
226
+ return portalRequest("POST", `${BUILDS_PATH}/workflow-id`, options, {
156
227
  slug,
157
- agent,
228
+ agent: build,
158
229
  workflowId,
159
230
  });
160
231
  }
161
- export async function portalListAgents(input = {}, options = {}) {
232
+ /** Old name of `portalSetBuildWorkflow`. */
233
+ export async function portalSetAgentWorkflow(input, options = {}) {
234
+ return portalSetBuildWorkflow({ slug: input.slug, build: input.agent, workflowId: input.workflowId }, options);
235
+ }
236
+ /** Every registered build (agents and apps), for all orgs or one. */
237
+ export async function portalListBuilds(input = {}, options = {}) {
162
238
  const query = input.slug ? `?slug=${encodeURIComponent(normalizeSlug(input.slug, "org"))}` : "";
163
- return portalRequest("GET", `/api/admin/agents${query}`, options);
239
+ return portalRequest("GET", `${BUILDS_PATH}${query}`, options);
240
+ }
241
+ /** Old name of `portalListBuilds`. */
242
+ export async function portalListAgents(input = {}, options = {}) {
243
+ return portalListBuilds(input, options);
164
244
  }
165
245
  export async function portalSyncRuns(input = {}, options = {}) {
166
246
  if (input.days !== undefined) {
@@ -189,20 +269,25 @@ function assertProvider(provider) {
189
269
  }
190
270
  }
191
271
  /**
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.
272
+ * Mark an agent build as an email-triage agent of one provider, or clear it
273
+ * with null. Only a triage agent may write classification rows, and the
274
+ * provider decides the row shape the portal accepts. An app build never runs,
275
+ * so it is never a triage agent.
195
276
  */
196
- export async function portalSetAgentTriage(input, options = {}) {
277
+ export async function portalSetBuildTriage(input, options = {}) {
197
278
  const slug = normalizeSlug(input.slug, "org");
198
- const agent = normalizeSlug(input.agent, "agent");
279
+ const build = normalizeSlug(input.build, "build");
199
280
  assertProvider(input.provider);
200
- return portalRequest("POST", "/api/admin/agents/triage", options, {
281
+ return portalRequest("POST", `${BUILDS_PATH}/triage`, options, {
201
282
  slug,
202
- agent,
283
+ agent: build,
203
284
  provider: input.provider,
204
285
  });
205
286
  }
287
+ /** Old name of `portalSetBuildTriage`. */
288
+ export async function portalSetAgentTriage(input, options = {}) {
289
+ return portalSetBuildTriage({ slug: input.slug, build: input.agent, provider: input.provider }, options);
290
+ }
206
291
  /** Where the weekly triage digest posts for this client; null = no digest. */
207
292
  export async function portalSetOrgSlackChannel(input, options = {}) {
208
293
  const slug = normalizeSlug(input.slug, "org");
@@ -0,0 +1,45 @@
1
+ import { type ExecFileFn } from "./exec.js";
2
+ /**
3
+ * `ia pr open` — push the current branch and open a DRAFT pull request, with
4
+ * the three checks that the Slack Merge button made necessary:
5
+ *
6
+ * 1. The gh account is the workspace's work account (`.github-account` at the
7
+ * workspace root). A PR under a personal account lands on the wrong identity
8
+ * and lacks org access.
9
+ * 2. The branch has no MERGED pull request. The Merge button squash-merges and
10
+ * deletes the branch about a minute after a PR opens; a later push to the
11
+ * same branch was silently lost (6 incidents in 20 days, Oct 2026).
12
+ * 3. The branch has no OPEN pull request. More commits on an open PR is the
13
+ * same trap one click later: open a new PR per slice.
14
+ *
15
+ * The PR opens as a draft, so no Slack card (and no Merge button) exists until
16
+ * someone marks it ready on purpose.
17
+ */
18
+ export interface PrOpenOptions {
19
+ /** The git checkout to open the PR from. Defaults to the current dir. */
20
+ repoDir?: string;
21
+ /** installagent/ workspace root, for `.github-account`. Found from repoDir when unset. */
22
+ workspaceDir?: string;
23
+ title?: string;
24
+ body?: string;
25
+ base?: string;
26
+ /** Open it ready for review (posts the Slack card at once). Default false. */
27
+ ready?: boolean;
28
+ /** Run the checks only; push nothing and open nothing. */
29
+ dryRun?: boolean;
30
+ execFileImpl?: ExecFileFn;
31
+ }
32
+ export interface PrOpenResult {
33
+ repo: string;
34
+ branch: string;
35
+ base: string;
36
+ account: string;
37
+ draft: boolean;
38
+ /** Undefined on a dry run. */
39
+ url?: string;
40
+ dryRun: boolean;
41
+ }
42
+ /** `owner/repo` from a GitHub remote URL (ssh or https). */
43
+ export declare function parseGithubRemote(url: string): string | undefined;
44
+ export declare function expectedGithubAccount(workspaceDir: string | null): string | undefined;
45
+ export declare function prOpen(options?: PrOpenOptions): Promise<PrOpenResult>;