@alfe.ai/agent-api-client 0.14.0 → 0.15.0

package/dist/index.js

@@ -19,7 +19,14 @@ function firstFrame(err) {
 	return frame ? ` (${frame.trim()})` : "";
 }
 function buildLine(plugin, tool, kind, message, frame = "") {
-	return `[ERROR] alfe-tool plugin=${plugin} tool=${tool} ${kind}: ${message.replace(/\s+/g, " ").trim()}${frame}`.slice(0, 480);
+	const safeToken = (value) => value.replace(/[^A-Za-z0-9_.@/-]+/g, "_").slice(0, 80);
+	const stripControls = (value) => Array.from(value, (character) => {
+		const code = character.charCodeAt(0);
+		return code < 32 || code >= 127 && code <= 159 ? " " : character;
+	}).join("");
+	const oneLine = stripControls(message).replace(/\s+/g, " ").trim();
+	const safeFrame = stripControls(frame).replace(/\s+/g, " ");
+	return `[ERROR] alfe-tool plugin=${safeToken(plugin)} tool=${safeToken(tool)} ${kind}: ${oneLine}${safeFrame}`.slice(0, 480);
 }
 function wrapExecute(tool, opts) {
 	const execute = tool.execute;
@@ -56,7 +63,6 @@ function installToolErrorCapture(api, options) {
 	try {
 		const markedApi = api;
 		if (markedApi[INSTALLED_MARKER]) return;
-		markedApi[INSTALLED_MARKER] = true;
 		const emit = options.emit ?? ((line) => {
 			process.stderr.write(`${line}\n`);
 		});
@@ -65,24 +71,29 @@ function installToolErrorCapture(api, options) {
 			emit
 		};
 		const original = api.registerTool.bind(api);
-		api.registerTool = (...args) => {
+		const wrappedRegisterTool = (...args) => {
+			let preparedArgs = args;
 			try {
 				const [first, ...rest] = args;
 				if (typeof first === "function") {
 					const factory = first;
 					const wrappedFactory = (...fa) => {
 						const tool = factory(...fa);
-						if (typeof tool === "object" && tool !== null) wrapExecute(tool, opts);
+						if (typeof tool === "object" && tool !== null) try {
+							wrapExecute(tool, opts);
+						} catch {}
 						return tool;
 					};
-					return original(wrappedFactory, ...rest);
+					preparedArgs = [wrappedFactory, ...rest];
 				}
 				if (typeof first === "object" && first !== null) wrapExecute(first, opts);
-				return original(first, ...rest);
 			} catch {
-				return original(...args);
+				preparedArgs = args;
 			}
+			return original(...preparedArgs);
 		};
+		api.registerTool = wrappedRegisterTool;
+		markedApi[INSTALLED_MARKER] = true;
 	} catch {}
 }
 //#endregion
@@ -121,6 +132,10 @@ const RETRYABLE_STATUS = new Set([
 	504
 ]);
 const RETRY_DELAY_MS = 500;
+function isSafeRetryMethod(method) {
+	const normalized = (method ?? "GET").toUpperCase();
+	return normalized === "GET" || normalized === "HEAD" || normalized === "OPTIONS";
+}
 function sleep(ms) {
 	return new Promise((resolve) => {
 		setTimeout(resolve, ms);
@@ -132,6 +147,12 @@ function isRetryableNetworkError(err) {
 	if (err.name === "TypeError") return true;
 	return false;
 }
+/** Whether a completed request may be retried/polled without masking a real client error. */
+function isTransientRequestError(err) {
+	if (isRetryableNetworkError(err)) return true;
+	const status = err?.status;
+	return typeof status === "number" && RETRYABLE_STATUS.has(status);
+}
 var AgentApiTransport = class {
 	apiKey;
 	apiUrl;
@@ -144,16 +165,17 @@ var AgentApiTransport = class {
 	* `Content-Type: application/json` and parses a `{ data: T }` envelope,
 	* neither of which fits a raw-audio flow (voice TTS/STT), so those go
 	* through this instead. Auth (Bearer), the request budget, and the single
-	* retry on transient 5xx / network errors are kept in sync with
-	* `request()`. Retries fire only on statuses produced BEFORE the route
-	* handler runs (authorizer-timeout 500 + LB 502/503/504), so re-issuing a
-	* POST does not risk a duplicate side effect.
+	* retry policy on transient 5xx / network errors is kept in sync with
+	* `request()`. Safe read methods retry once by default; mutation methods do
+	* not, because a response can be lost after a handler or provider call has
+	* already succeeded.
 	*/
-	async rawRequest(path, init) {
+	async rawRequest(path, init, extra) {
 		const url = `${this.apiUrl}${path}`;
 		init.headers.set("Authorization", `Bearer ${this.apiKey}`);
+		const maxAttempts = extra?.retry ?? isSafeRetryMethod(init.method) ? 2 : 1;
 		let lastError;
-		for (let attempt = 1; attempt <= 2; attempt++) try {
+		for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
 			const res = await fetch(url, {
 				method: init.method,
 				headers: init.headers,
@@ -164,7 +186,7 @@ var AgentApiTransport = class {
 				const errorBody = await res.text();
 				const error = new Error(formatErrorMessage(res.status, errorBody));
 				error.status = res.status;
-				if (attempt === 1 && RETRYABLE_STATUS.has(res.status)) {
+				if (attempt < maxAttempts && RETRYABLE_STATUS.has(res.status)) {
 					lastError = error;
 					await sleep(RETRY_DELAY_MS);
 					continue;
@@ -173,7 +195,7 @@ var AgentApiTransport = class {
 			}
 			return res;
 		} catch (err) {
-			if (attempt === 1 && isRetryableNetworkError(err)) {
+			if (attempt < maxAttempts && isRetryableNetworkError(err)) {
 				lastError = err;
 				await sleep(RETRY_DELAY_MS);
 				continue;
@@ -186,8 +208,11 @@ var AgentApiTransport = class {
 	* @param extra.timeoutMs Per-request abort timeout (default REQUEST_TIMEOUT_MS).
 	*   Long endpoints (image generation) pass a larger value so the gateway's
 	*   own timeout wins with a readable status instead of a client-side abort.
-	* @param extra.retry Whether to retry once on transient failures (default
-	*   true). Expensive/non-idempotent endpoints pass false.
+	* @param extra.retry Whether to retry once on transient failures. Safe reads
+	*   (GET/HEAD/OPTIONS) default to true; mutations default to false. Set true
+	*   only when the endpoint's server-side contract is explicitly idempotent.
+	* @param extra.signal Optional caller cancellation combined with the client's
+	*   own timeout budget. Aborting either signal cancels the request.
 	*/
 	async request(path, options, extra) {
 		const url = `${this.apiUrl}${path}`;
@@ -195,13 +220,13 @@ var AgentApiTransport = class {
 		headers.set("Authorization", `Bearer ${this.apiKey}`);
 		headers.set("Content-Type", "application/json");
 		const timeoutMs = extra?.timeoutMs ?? 2e4;
-		const maxAttempts = extra?.retry === false ? 1 : 2;
+		const maxAttempts = extra?.retry ?? isSafeRetryMethod(options?.method) ? 2 : 1;
 		let lastError;
 		for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
 			const res = await fetch(url, {
 				...options,
 				headers,
-				signal: AbortSignal.timeout(timeoutMs)
+				signal: extra?.signal ? AbortSignal.any([extra.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs)
 			});
 			if (!res.ok) {
 				const errorBody = await res.text();
@@ -370,8 +395,9 @@ var ConnectCredentialsApi = class extends ApiBase {
 	* selector arg (e.g. `xeroTenantId`) on every credential-touching tool
 	* and look up the matching account by that selector at dispatch time.
 	*
-	* Returned `accounts[i].accountIdentifier` is the Xero tenantId — the
-	* stable cross-session identifier the LLM should pass.
+	* `xeroTenantId` is the model-facing organisation selector. The separate
+	* `accountIdentifier` is the Connect persistence key used for refresh and
+	* may be an email; never substitute one for the other.
 	*/
 	async getXeroAccounts() {
 		return { accounts: (await this.transport.request("/agent/connect/xero/accounts")).accounts.map((a) => ({
@@ -381,21 +407,21 @@ var ConnectCredentialsApi = class extends ApiBase {
 			connectedAt: a.connectedAt,
 			accessToken: a.accessToken,
 			accessTokenExpiresAt: a.accessTokenExpiresAt ?? "",
-			xeroTenantId: a.xeroTenantId ?? a.accountIdentifier
+			xeroTenantId: a.xeroTenantId ?? ""
 		})) };
 	}
 	async refreshXeroToken() {
-		return this.transport.request("/agent/connect/xero/refresh", { method: "POST" });
+		return this.transport.request("/agent/connect/xero/refresh", { method: "POST" }, { retry: true });
 	}
 	/**
-	* Pattern A: refresh a specific Xero connection by its `accountIdentifier`
-	* (the Xero `tenantId`). The legacy `refreshXeroToken()` only refreshes
-	* the *primary* connection, which is wrong for multi-tenant Xero where
-	* each tenant has its own non-interchangeable access token.
+	* Refresh a specific Xero Connection by its exact `accountIdentifier` from
+	* `getXeroAccounts()`. Do not substitute `xeroTenantId`: current Xero OAuth
+	* rows may use the account email as their persistence key even when a sole
+	* organisation tenant ID is available in provider metadata.
 	*/
-	async refreshXeroAccountToken(xeroTenantId) {
-		const path = `/agent/connect/xero/accounts/${encodeURIComponent(xeroTenantId)}/refresh`;
-		const raw = await this.transport.request(path, { method: "POST" });
+	async refreshXeroAccountToken(accountIdentifier) {
+		const path = `/agent/connect/xero/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
+		const raw = await this.transport.request(path, { method: "POST" }, { retry: true });
 		return {
 			accessToken: raw.accessToken,
 			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
@@ -457,7 +483,7 @@ var ConnectCredentialsApi = class extends ApiBase {
 		};
 	}
 	async refreshAtlassianToken() {
-		return this.transport.request("/agent/connect/atlassian/refresh", { method: "POST" });
+		return this.transport.request("/agent/connect/atlassian/refresh", { method: "POST" }, { retry: true });
 	}
 	/**
 	* Pattern A: multi-account / multi-site credential fetch for Atlassian.
@@ -513,7 +539,7 @@ var ConnectCredentialsApi = class extends ApiBase {
 	*/
 	async refreshAtlassianAccountToken(accountIdentifier) {
 		const path = `/agent/connect/atlassian/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
-		const raw = await this.transport.request(path, { method: "POST" });
+		const raw = await this.transport.request(path, { method: "POST" }, { retry: true });
 		return {
 			accessToken: raw.accessToken,
 			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
@@ -555,7 +581,26 @@ var ConnectCredentialsApi = class extends ApiBase {
 		})) };
 	}
 	async refreshMYOBToken() {
-		return this.transport.request("/agent/connect/myob/refresh", { method: "POST" });
+		return this.transport.request("/agent/connect/myob/refresh", { method: "POST" }, { retry: true });
+	}
+	/**
+	* Pattern A: refresh one MYOB Connection by its stable
+	* `accountIdentifier` (the MYOB business id returned by
+	* `getMYOBAccounts()`).
+	*
+	* MYOB refresh tokens belong to individual Connection rows. A
+	* multi-business client must use this method instead of refreshing the
+	* primary Connection and copying that access token into every cached
+	* business client.
+	*/
+	async refreshMYOBAccountToken(accountIdentifier) {
+		const path = `/agent/connect/myob/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
+		const raw = await this.transport.request(path, { method: "POST" }, { retry: true });
+		return {
+			accessToken: raw.accessToken,
+			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
+			expiresAt: raw.expiresAt ?? ""
+		};
 	}
 	/**
 	* @deprecated Returns a single primary credential blob. Use
@@ -596,7 +641,7 @@ var ConnectCredentialsApi = class extends ApiBase {
 	*/
 	async refreshSalesforceAccountToken(orgId) {
 		const path = `/agent/connect/salesforce/accounts/${encodeURIComponent(orgId)}/refresh`;
-		const raw = await this.transport.request(path, { method: "POST" });
+		const raw = await this.transport.request(path, { method: "POST" }, { retry: true });
 		return {
 			accessToken: raw.accessToken,
 			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
@@ -626,9 +671,6 @@ var ConnectCredentialsApi = class extends ApiBase {
 			connectedAt: a.connectedAt,
 			accessToken: a.accessToken ?? "",
 			accessTokenExpiresAt: a.accessTokenExpiresAt ?? "",
-			refreshToken: a.refreshToken ?? "",
-			clientId: a.clientId ?? "",
-			clientSecret: a.clientSecret ?? "",
 			email: a.email ?? a.accountIdentifier,
 			microsoftTenantId: a.microsoftTenantId ?? "",
 			workspaceDomain: a.workspaceDomain ?? ""
@@ -650,7 +692,7 @@ var ConnectCredentialsApi = class extends ApiBase {
 	*/
 	async refreshMicrosoftAccountToken(accountIdentifier) {
 		const path = `/agent/connect/microsoft/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
-		const raw = await this.transport.request(path, { method: "POST" });
+		const raw = await this.transport.request(path, { method: "POST" }, { retry: true });
 		return {
 			accessToken: raw.accessToken,
 			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
@@ -874,7 +916,7 @@ var ConnectCredentialsApi = class extends ApiBase {
 	*/
 	async refreshSocialAccount(provider, accountIdentifier) {
 		const path = `/agent/connect/${encodeURIComponent(provider)}/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
-		const raw = await this.transport.request(path, { method: "POST" });
+		const raw = await this.transport.request(path, { method: "POST" }, { retry: true });
 		return {
 			accountIdentifier: raw.accountIdentifier,
 			accessToken: raw.accessToken,
@@ -940,11 +982,8 @@ var IdentityApi = class extends ApiBase {
 			body: JSON.stringify(args)
 		});
 	}
-	async unmergeIdentity(identityId, args) {
-		return this.transport.request(`/agent/identity/${encodeURIComponent(identityId)}/unmerge`, {
-			method: "POST",
-			body: JSON.stringify(args)
-		});
+	async unmergeIdentity(identityId) {
+		return this.transport.request(`/agent/identity/${encodeURIComponent(identityId)}/unmerge`, { method: "POST" });
 	}
 	async addIdentityNote(identityId, args) {
 		return this.transport.request(`/agent/identity/${encodeURIComponent(identityId)}/notes`, {
@@ -961,6 +1000,7 @@ var IdentityApi = class extends ApiBase {
 	async getIdentityChangelog(identityId, args) {
 		const qs = new URLSearchParams();
 		if (args?.limit) qs.set("limit", String(args.limit));
+		if (args?.cursor) qs.set("cursor", args.cursor);
 		const query = qs.toString();
 		return this.transport.request(`/agent/identity/${encodeURIComponent(identityId)}/changelog${query ? `?${query}` : ""}`);
 	}
@@ -1037,8 +1077,9 @@ var ImagesApi = class extends ApiBase {
 			let job;
 			try {
 				job = await this.transport.request(`/agent/images/${jobId}`);
-			} catch {
-				continue;
+			} catch (error) {
+				if (isTransientRequestError(error)) continue;
+				throw error;
 			}
 			if (job.status === "completed") {
 				if (!job.imageUrl) throw new Error("Image generation completed without a URL");
@@ -1111,6 +1152,8 @@ var IntegrationsApi = class extends ApiBase {
 * Knowledge resource methods (org/team/project scoped docs, profiles,
 * change requests + RAG search) for the Agent API client.
 */
+/** Matches services/knowledge's maximum indexed document size. */
+const MAX_KNOWLEDGE_DOCUMENT_BYTES = 2 * 1024 * 1024;
 var KnowledgeApi = class extends ApiBase {
 	/**
 	* Semantic search across the agent's member scopes. Fan-out is gated
@@ -1199,16 +1242,18 @@ var KnowledgeApi = class extends ApiBase {
 	* from `services/org`, then fetches the bytes directly from S3 (the one
 	* legitimate raw fetch in a plugin — same pattern as sync).
 	*/
-	async readScopeDoc(scopeType, scopeId, filePath) {
+	async readScopeDoc(scopeType, scopeId, filePath, opts) {
+		const maxBytes = opts?.maxBytes ?? 2097152;
+		if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 2097152) throw new RangeError(`maxBytes must be an integer from 1 to ${String(MAX_KNOWLEDGE_DOCUMENT_BYTES)}`);
 		const { downloadUrl } = await this.transport.request(`/agent/org/files/${encodeURIComponent(scopeType)}/${encodeURIComponent(scopeId)}/download/${encodeFilePath(filePath)}`);
 		const res = await fetch(downloadUrl, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
 		if (!res.ok) {
-			await res.text();
+			await res.body?.cancel().catch(() => void 0);
 			throw new Error(`Doc download failed (${String(res.status)})`);
 		}
 		return {
 			filePath,
-			text: await res.text()
+			text: await readBoundedUtf8(res, maxBytes)
 		};
 	}
 	/**
@@ -1242,6 +1287,52 @@ var KnowledgeApi = class extends ApiBase {
 		return { filePath: presign.filePath };
 	}
 };
+async function readBoundedUtf8(response, maxBytes) {
+	const declaredLength = response.headers.get("content-length");
+	if (declaredLength !== null && /^\d+$/u.test(declaredLength) && Number(declaredLength) > maxBytes) {
+		await response.body?.cancel().catch(() => void 0);
+		throw documentTooLargeError(maxBytes);
+	}
+	if (response.body === null) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	let complete = false;
+	try {
+		while (!complete) {
+			const { done, value } = await reader.read();
+			if (done) {
+				complete = true;
+				continue;
+			}
+			total += value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel().catch(() => void 0);
+				throw documentTooLargeError(maxBytes);
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new Error("Knowledge document is not valid UTF-8 text");
+	}
+}
+function documentTooLargeError(maxBytes) {
+	const error = /* @__PURE__ */ new Error(`Knowledge document exceeds the ${String(maxBytes)} byte read limit`);
+	error.name = "KnowledgeDocumentTooLargeError";
+	error.code = "KNOWLEDGE_DOCUMENT_TOO_LARGE";
+	return error;
+}
 //#endregion
 //#region src/domains/memory.ts
 /**
@@ -1416,23 +1507,23 @@ var RemoteApi = class extends ApiBase {
 * Web/image/news search methods (services/search) for the Agent API client.
 */
 var SearchApi = class extends ApiBase {
-	async searchWeb(params) {
+	async searchWeb(params, options) {
 		return this.transport.request("/agent/search/web", {
 			method: "POST",
 			body: JSON.stringify(params)
-		});
+		}, { signal: options?.signal });
 	}
-	async searchImages(params) {
+	async searchImages(params, options) {
 		return this.transport.request("/agent/search/images", {
 			method: "POST",
 			body: JSON.stringify(params)
-		});
+		}, { signal: options?.signal });
 	}
-	async searchNews(params) {
+	async searchNews(params, options) {
 		return this.transport.request("/agent/search/news", {
 			method: "POST",
 			body: JSON.stringify(params)
-		});
+		}, { signal: options?.signal });
 	}
 	/** Search news across the selected provider's corpus. → POST /agent/news/search */
 	async newsSearch(params) {
@@ -1583,8 +1674,9 @@ var SelfApi = class extends ApiBase {
 			let job;
 			try {
 				job = await this.transport.request(`/agent/avatar/${jobId}`);
-			} catch {
-				continue;
+			} catch (error) {
+				if (isTransientRequestError(error)) continue;
+				throw error;
 			}
 			if (job.status === "completed") {
 				if (!job.agent) throw new Error("Avatar generation completed without an agent");
@@ -1729,7 +1821,11 @@ var SyncApi = class extends ApiBase {
 		return this.transport.request(`/agent/sync/files/${encodeFilePath(filePath)}`, { method: "DELETE" });
 	}
 	async sharedListFiles(args) {
-		return this.transport.request(`/agent/org/files/${encodeURIComponent(args.scope)}/${encodeURIComponent(args.scopeId)}`);
+		const params = new URLSearchParams();
+		if (args.limit !== void 0) params.set("limit", String(args.limit));
+		if (args.cursor) params.set("cursor", args.cursor);
+		const query = params.toString();
+		return this.transport.request(`/agent/org/files/${encodeURIComponent(args.scope)}/${encodeURIComponent(args.scopeId)}${query ? `?${query}` : ""}`);
 	}
 	async sharedDownloadUrl(args) {
 		return this.transport.request(`/agent/org/files/${encodeURIComponent(args.scope)}/${encodeURIComponent(args.scopeId)}/download/${encodeFilePath(args.filePath)}`);
@@ -1762,11 +1858,11 @@ var TeamsApi = class extends ApiBase {
 */
 var WorkspaceApi = class extends ApiBase {
 	/**
-	* GET /agents/me/workspace — workspace config for the authenticated agent
+	* GET /agent/workspace — workspace config for the authenticated agent
 	* (template assignment, default model, org roster).
 	*/
 	async getWorkspace() {
-		return this.transport.request("/agents/me/workspace");
+		return this.transport.request("/agent/workspace");
 	}
 	/**
 	* GET /templates/{key}/files — persona/workspace file contents for a
@@ -1775,7 +1871,30 @@ var WorkspaceApi = class extends ApiBase {
 	*/
 	async getTemplateFiles(templateKey, opts) {
 		const query = opts?.version !== void 0 ? `?version=${String(opts.version)}` : "";
-		return this.transport.request(`/templates/${encodeURIComponent(templateKey)}/files${query}`);
+		return this.transport.request(`/agent/templates/${encodeURIComponent(templateKey)}/files${query}`);
+	}
+};
+//#endregion
+//#region src/domains/webhooks.ts
+/** Agent self-service webhook management methods. */
+var WebhooksApi = class extends ApiBase {
+	async createWebhook(args) {
+		return this.transport.request("/agent/webhooks", {
+			method: "POST",
+			body: JSON.stringify(args)
+		}, { retry: false });
+	}
+	async listWebhooks() {
+		return (await this.transport.request("/agent/webhooks")).webhooks;
+	}
+	async deleteWebhook(webhookId) {
+		return this.transport.request(`/agent/webhooks/${encodeURIComponent(webhookId)}`, { method: "DELETE" });
+	}
+	async rotateWebhookSecret(webhookId) {
+		return this.transport.request(`/agent/webhooks/${encodeURIComponent(webhookId)}/rotate`, { method: "POST" }, { retry: false });
+	}
+	async listWebhookDeliveries(webhookId) {
+		return (await this.transport.request(`/agent/webhooks/${encodeURIComponent(webhookId)}/deliveries`)).deliveries;
 	}
 };
 //#endregion
@@ -1810,7 +1929,8 @@ applyMixins(AgentApiClient, [
 	RemoteApi,
 	SelfApi,
 	VoiceApi,
-	ImagesApi
+	ImagesApi,
+	WebhooksApi
 ]);
 //#endregion
 export { AgentApiClient, installToolErrorCapture };