@installagent/sdk 0.4.0 → 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.
- package/dist/agent-mirror.js +22 -10
- package/dist/agent-templates.d.ts +10 -12
- package/dist/agent-templates.js +34 -6
- package/dist/doctor.d.ts +11 -1
- package/dist/doctor.js +24 -22
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/lefthook-hooks.d.ts +36 -0
- package/dist/lefthook-hooks.js +64 -0
- package/dist/n8n-defaults.d.ts +90 -0
- package/dist/n8n-defaults.js +153 -0
- package/dist/portal-admin.d.ts +104 -13
- package/dist/portal-admin.js +113 -28
- package/dist/pr-open.d.ts +45 -0
- package/dist/pr-open.js +98 -0
- package/dist/sync-repos.d.ts +8 -1
- package/dist/sync-repos.js +10 -9
- package/dist/triage-enable.js +20 -7
- package/package.json +1 -1
- package/templates/workspace-root/AGENT.md +2 -1
- package/templates/workspace-root/ONBOARDING.md +10 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +7 -2
- package/templates/workspace-root/skills/CLAUDE.md +4 -4
- package/templates/workspace-root/skills/README.md +2 -2
- package/templates/workspace-root/skills/ad-machine/SKILL.md +14 -18
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +14 -16
- package/templates/workspace-root/skills/client-latest/SKILL.md +14 -18
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +22 -16
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +11 -14
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +9 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +67 -19
- package/templates/workspace-root/skills/ia-cli/SKILL.md +14 -17
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +14 -20
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +2 -2
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +13 -15
- package/templates/workspace-root/skills/slack-voice/SKILL.md +50 -31
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +14 -15
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +13 -19
- 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
|
+
}
|
package/dist/portal-admin.d.ts
CHANGED
|
@@ -38,18 +38,43 @@ export interface PortalOrg {
|
|
|
38
38
|
slackChannelId?: string | null;
|
|
39
39
|
users: PortalOrgUser[];
|
|
40
40
|
}
|
|
41
|
-
|
|
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
|
-
|
|
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
|
|
114
|
+
export interface PortalCreateBuildInput {
|
|
90
115
|
slug: string;
|
|
91
|
-
|
|
116
|
+
/** The build slug, e.g. "follow-up". */
|
|
117
|
+
build: string;
|
|
92
118
|
name: string;
|
|
93
119
|
description: string;
|
|
94
|
-
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
192
|
-
* null. Only a triage agent may write classification rows, and the
|
|
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;
|
package/dist/portal-admin.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
111
|
-
|
|
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
|
-
|
|
171
|
+
buildType: fields.buildType,
|
|
172
|
+
...(fields.workflowId ? { workflowId: fields.workflowId } : {}),
|
|
173
|
+
...(fields.url ? { url: fields.url } : {}),
|
|
117
174
|
});
|
|
118
175
|
}
|
|
119
|
-
|
|
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
|
|
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",
|
|
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
|
|
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
|
|
201
|
+
export async function portalSetBuildName(input, options = {}) {
|
|
136
202
|
const slug = normalizeSlug(input.slug, "org");
|
|
137
|
-
const
|
|
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",
|
|
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
|
|
220
|
+
export async function portalSetBuildWorkflow(input, options = {}) {
|
|
150
221
|
const slug = normalizeSlug(input.slug, "org");
|
|
151
|
-
const
|
|
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",
|
|
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
|
-
|
|
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",
|
|
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
|
|
193
|
-
* null. Only a triage agent may write classification rows, and the
|
|
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
|
|
277
|
+
export async function portalSetBuildTriage(input, options = {}) {
|
|
197
278
|
const slug = normalizeSlug(input.slug, "org");
|
|
198
|
-
const
|
|
279
|
+
const build = normalizeSlug(input.build, "build");
|
|
199
280
|
assertProvider(input.provider);
|
|
200
|
-
return portalRequest("POST",
|
|
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>;
|