@better-agent/client 0.1.0-canary.0

package/dist/index.mjs

@@ -0,0 +1,643 @@
+import { a as toModelMessages, i as fromModelMessages, n as createAgentChatController, o as getEventErrorMessage, r as fromConversationItems, s as toAgentClientError } from "./controller-Cf_JhTdJ.mjs";
+import { Events } from "@better-agent/core/events";
+import { BetterAgentError } from "@better-agent/shared/errors";
+import { pruneInputByCapabilities } from "@better-agent/core";
+
+//#region src/core/sse.ts
+const isEventType = (value) => Object.values(Events).includes(value);
+const resetFrame = () => ({ data: "" });
+const getSseErrorMessage = (data) => {
+	try {
+		const parsed = JSON.parse(data);
+		if (typeof parsed.message === "string" && parsed.message.trim().length > 0) return parsed.message;
+	} catch {}
+	return data.trim().length > 0 ? data.trim() : "Stream failed";
+};
+const parseFrame = (frame, options) => {
+	if (!frame.data) return null;
+	const data = frame.data.replace(/\n$/, "");
+	if (frame.eventName === "error") throw new Error(getSseErrorMessage(data));
+	try {
+		const parsed = JSON.parse(data);
+		if (!(parsed && typeof parsed === "object" && typeof parsed.type === "string")) return null;
+		if (!isEventType(parsed.type)) return null;
+		if (typeof frame.id === "number") {
+			parsed.seq = frame.id;
+			options.onId?.(frame.id);
+		}
+		return parsed;
+	} catch {
+		return null;
+	}
+};
+async function* parseSse(body, options = {}) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let frame = resetFrame();
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		for (;;) {
+			const nl = buffer.indexOf("\n");
+			if (nl < 0) break;
+			const line = buffer.slice(0, nl).replace(/\r$/, "");
+			buffer = buffer.slice(nl + 1);
+			if (line === "") {
+				const event = parseFrame(frame, options);
+				frame = resetFrame();
+				if (event) yield event;
+				continue;
+			}
+			if (line.startsWith("event:")) {
+				frame.eventName = line.slice(6).trim();
+				continue;
+			}
+			if (line.startsWith("id:")) {
+				const idValue = Number(line.slice(3).trim());
+				frame.id = Number.isFinite(idValue) ? idValue : void 0;
+				continue;
+			}
+			if (line.startsWith("data:")) frame.data += `${line.slice(5).trim()}\n`;
+		}
+	}
+	const finalEvent = parseFrame(frame, options);
+	if (finalEvent) yield finalEvent;
+}
+
+//#endregion
+//#region src/core/client/errors.ts
+const tryParseJson = (bodyText) => {
+	try {
+		return JSON.parse(bodyText);
+	} catch {
+		return null;
+	}
+};
+const parseErrorBody = (bodyText) => {
+	let errorCodeFromBody;
+	let errorMessageFromBody;
+	let errorTitleFromBody;
+	let errorStatusFromBody;
+	let retryableFromBody;
+	let traceIdFromBody;
+	let issuesFromBody;
+	let contextFromBody;
+	let traceFromBody;
+	if (bodyText.length > 0) {
+		const parsed = tryParseJson(bodyText);
+		if (parsed) {
+			if (typeof parsed.code === "string") errorCodeFromBody = parsed.code;
+			else if (typeof parsed.error === "string") errorCodeFromBody = parsed.error;
+			if (typeof parsed.message === "string") errorMessageFromBody = parsed.message;
+			else if (typeof parsed.detail === "string") errorMessageFromBody = parsed.detail;
+			if (typeof parsed.title === "string") errorTitleFromBody = parsed.title;
+			if (typeof parsed.status === "number") errorStatusFromBody = parsed.status;
+			if (typeof parsed.retryable === "boolean") retryableFromBody = parsed.retryable;
+			if (typeof parsed.traceId === "string") traceIdFromBody = parsed.traceId;
+			if (Array.isArray(parsed.issues)) issuesFromBody = parsed.issues;
+			if (typeof parsed.context === "object" && parsed.context !== null) contextFromBody = parsed.context;
+			if (Array.isArray(parsed.trace)) traceFromBody = parsed.trace;
+		}
+	}
+	return {
+		errorCodeFromBody,
+		errorMessageFromBody,
+		errorTitleFromBody,
+		errorStatusFromBody,
+		retryableFromBody,
+		traceIdFromBody,
+		issuesFromBody,
+		contextFromBody,
+		traceFromBody
+	};
+};
+const getContentType = (response) => response.headers.get("content-type")?.toLowerCase() ?? "";
+const isHtmlResponse = (response) => getContentType(response).includes("text/html");
+const truncateForContext = (value, maxLength = 300) => value.length <= maxLength ? value : `${value.slice(0, maxLength)}...`;
+const throwRequestError = async (params) => {
+	const bodyText = (await params.response.text().catch(() => "")).trim();
+	const { errorCodeFromBody, errorMessageFromBody, errorTitleFromBody, errorStatusFromBody, retryableFromBody, traceIdFromBody, issuesFromBody, contextFromBody, traceFromBody } = parseErrorBody(bodyText);
+	const fallbackDetail = isHtmlResponse(params.response) ? "Server returned an HTML error page. This usually means a framework or dev-server failure before the API handler ran." : params.response.statusText || "Unknown error";
+	const detail = errorMessageFromBody ?? (bodyText.length > 0 && !isHtmlResponse(params.response) ? bodyText : void 0) ?? fallbackDetail;
+	throw Object.assign(BetterAgentError.fromCode(errorCodeFromBody ?? (params.response.status >= 500 || params.response.status === 429 ? "UPSTREAM_FAILED" : "BAD_REQUEST"), detail, {
+		title: errorTitleFromBody,
+		status: errorStatusFromBody ?? params.response.status,
+		retryable: retryableFromBody,
+		traceId: traceIdFromBody,
+		context: {
+			...params.context,
+			operation: params.operation,
+			status: params.response.status,
+			...contextFromBody ?? {},
+			error: errorCodeFromBody,
+			issues: issuesFromBody,
+			...isHtmlResponse(params.response) && bodyText.length > 0 ? {
+				responseContentType: getContentType(params.response),
+				responseBodySnippet: truncateForContext(bodyText)
+			} : {}
+		},
+		trace: [...traceFromBody ?? [], { at: params.at }]
+	}), issuesFromBody ? { issues: issuesFromBody } : {});
+};
+
+//#endregion
+//#region src/core/client/request.ts
+const mergeHeaders = (...parts) => {
+	const merged = new Headers();
+	for (const part of parts) {
+		if (!part) continue;
+		new Headers(part).forEach((value, key) => merged.set(key, value));
+	}
+	return merged;
+};
+const prepareRequest = async (advanced, context) => {
+	if (!advanced?.prepareRequest) return {
+		url: context.url,
+		method: context.method,
+		headers: context.headers,
+		body: context.body
+	};
+	const prepared = await advanced.prepareRequest(context);
+	if (!prepared) return {
+		url: context.url,
+		method: context.method,
+		headers: context.headers,
+		body: context.body
+	};
+	return {
+		url: prepared.url ?? context.url,
+		method: prepared.method ?? context.method,
+		headers: prepared.headers ?? context.headers,
+		...prepared.body !== void 0 ? { body: prepared.body } : context.body !== void 0 ? { body: context.body } : {}
+	};
+};
+
+//#endregion
+//#region src/core/client/tool-submission.ts
+const sleep = async (ms) => {
+	await new Promise((resolve) => setTimeout(resolve, ms));
+};
+const createToolSubmissionHandlers = (deps) => {
+	const doFetch = deps.doFetch;
+	const authHeaders = deps.secret ? { authorization: `Bearer ${deps.secret}` } : void 0;
+	const submitToolResult = async (params) => {
+		const payload = JSON.stringify({
+			runId: params.runId,
+			toolCallId: params.toolCallId,
+			...params.error !== void 0 ? {
+				status: "error",
+				error: params.error
+			} : {
+				status: "success",
+				result: params.result
+			}
+		});
+		for (let attempt = 1; attempt <= deps.toolSubmissionMaxAttempts; attempt++) try {
+			const prepared = await prepareRequest(deps.advanced, {
+				operation: "tool-result",
+				url: `${deps.baseURL}/${encodeURIComponent(params.agent)}/run/tool-result`,
+				method: "POST",
+				headers: mergeHeaders(authHeaders, { "content-type": "application/json" }, deps.defaultHeaders),
+				body: payload
+			});
+			const res = await doFetch(prepared.url, {
+				method: prepared.method,
+				headers: prepared.headers,
+				body: prepared.body
+			});
+			if (res.ok) return;
+			if (!(res.status >= 500 || res.status === 429) || attempt === deps.toolSubmissionMaxAttempts) await throwRequestError({
+				response: res,
+				operation: "tool-result",
+				at: "client.core.submitToolResult",
+				context: {
+					agentName: params.agent,
+					runId: params.runId,
+					toolCallId: params.toolCallId
+				}
+			});
+			await sleep(deps.toolSubmissionRetryDelayMs * attempt);
+		} catch (error) {
+			const wrapped = error instanceof Error ? error : new Error("Tool result submission failed.", { cause: error });
+			if (attempt === deps.toolSubmissionMaxAttempts) throw wrapped;
+			await sleep(deps.toolSubmissionRetryDelayMs * attempt);
+		}
+	};
+	const submitToolApproval = async (params) => {
+		const payload = JSON.stringify({
+			runId: params.runId,
+			toolCallId: params.toolCallId,
+			decision: params.decision,
+			...params.note !== void 0 ? { note: params.note } : {},
+			...params.actorId !== void 0 ? { actorId: params.actorId } : {}
+		});
+		for (let attempt = 1; attempt <= deps.toolSubmissionMaxAttempts; attempt++) try {
+			const prepared = await prepareRequest(deps.advanced, {
+				operation: "tool-approval",
+				url: `${deps.baseURL}/${encodeURIComponent(params.agent)}/run/tool-approval`,
+				method: "POST",
+				headers: mergeHeaders(authHeaders, { "content-type": "application/json" }, deps.defaultHeaders),
+				body: payload
+			});
+			const res = await doFetch(prepared.url, {
+				method: prepared.method,
+				headers: prepared.headers,
+				body: prepared.body
+			});
+			if (res.ok) return;
+			if (!(res.status >= 500 || res.status === 429) || attempt === deps.toolSubmissionMaxAttempts) await throwRequestError({
+				response: res,
+				operation: "tool-approval",
+				at: "client.core.submitToolApproval",
+				context: {
+					agentName: params.agent,
+					runId: params.runId,
+					toolCallId: params.toolCallId,
+					decision: params.decision
+				}
+			});
+			await sleep(deps.toolSubmissionRetryDelayMs * attempt);
+		} catch (error) {
+			const wrapped = error instanceof Error ? error : new Error("Tool approval submission failed.", { cause: error });
+			if (attempt === deps.toolSubmissionMaxAttempts) throw wrapped;
+			await sleep(deps.toolSubmissionRetryDelayMs * attempt);
+		}
+	};
+	return {
+		submitToolApproval,
+		submitToolResult
+	};
+};
+
+//#endregion
+//#region src/core/client/index.ts
+/**
+* Creates a Better Agent client.
+*
+* @param config Client configuration.
+* @returns A typed client.
+*
+* @example
+* ```ts
+* import { createClient } from "@better-agent/client";
+*
+* const client = createClient({
+*   baseURL: "http://localhost:3000/api",
+*   secret: "dev_secret",
+* });
+*
+* const result = await client.run("helloAgent", {
+*   input: "Write one short sentence about TypeScript.",
+* });
+* ```
+*
+* @example
+* ```ts
+* import type ba from "./better-agent/server";
+* import { createClient } from "@better-agent/client";
+*
+* const client = createClient<typeof ba>({
+*   baseURL: "http://localhost:3000/api",
+*   secret: "dev_secret",
+*   toolHandlers: {
+*     getClientTime: () => ({ now: new Date().toISOString() }),
+*   },
+* });
+*
+* for await (const event of client.stream("helloAgent", {
+*   input: "Use tools if needed.",
+* })) {
+*   console.log(event.type);
+* }
+* ```
+*/
+const createClient = (config) => {
+	const baseURL = config.baseURL.replace(/\/$/, "");
+	const doFetch = config.fetch ?? fetch;
+	const advanced = config.advanced;
+	const authHeaders = config.secret ? { authorization: `Bearer ${config.secret}` } : void 0;
+	const toolSubmissionMaxAttempts = Math.max(1, Math.floor(advanced?.toolSubmissionMaxAttempts ?? 3));
+	const toolSubmissionRetryDelayMs = Math.max(0, advanced?.toolSubmissionRetryDelayMs ?? 150);
+	const { submitToolResult, submitToolApproval } = createToolSubmissionHandlers({
+		advanced,
+		baseURL,
+		defaultHeaders: config.headers,
+		doFetch,
+		secret: config.secret,
+		toolSubmissionMaxAttempts,
+		toolSubmissionRetryDelayMs
+	});
+	return {
+		async run(agent, input, options) {
+			const request = {
+				agent,
+				...input
+			};
+			const prepared = await prepareRequest(advanced, {
+				operation: "run",
+				url: `${baseURL}/${encodeURIComponent(String(agent))}/run`,
+				method: "POST",
+				headers: mergeHeaders(authHeaders, { "content-type": "application/json" }, config.headers, options?.headers),
+				body: JSON.stringify(request)
+			});
+			const res = await doFetch(prepared.url, {
+				method: prepared.method,
+				headers: prepared.headers,
+				...prepared.body !== void 0 ? { body: prepared.body } : {},
+				signal: options?.signal ?? null
+			});
+			options?.onResponse?.(res);
+			if (!res.ok) await throwRequestError({
+				response: res,
+				operation: "run",
+				at: "client.core.run",
+				context: { agentName: agent }
+			});
+			return await res.json();
+		},
+		stream(agent, input, options) {
+			const request = {
+				agent,
+				...input
+			};
+			return (async function* () {
+				const pendingToolCalls = /* @__PURE__ */ new Map();
+				const toolCallController = new AbortController();
+				const abortToolCalls = () => {
+					if (!toolCallController.signal.aborted) toolCallController.abort();
+				};
+				const externalSignal = options?.signal;
+				const onExternalAbort = () => abortToolCalls();
+				if (externalSignal) if (externalSignal.aborted) abortToolCalls();
+				else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+				const processClientToolCall = async (toolCallKey, runId, toolCallId) => {
+					const pending = pendingToolCalls.get(toolCallKey);
+					if (!pending || pending.submitted || !pending.ended || pending.approvalState !== "waiting" && pending.approvalState !== "approved") return;
+					pending.submitted = true;
+					let parsedArgs = {};
+					try {
+						parsedArgs = pending.argsJson ? JSON.parse(pending.argsJson) : {};
+					} catch {
+						await submitToolResult({
+							agent: String(agent),
+							runId,
+							toolCallId,
+							error: `Invalid client tool arguments for '${pending.toolName}'.`
+						});
+						return;
+					}
+					const context = {
+						agent,
+						runId,
+						toolCallId,
+						signal: toolCallController.signal
+					};
+					const handler = resolveToolHandler(pending.toolName, options, config.toolHandlers);
+					if (!handler) {
+						await submitToolResult({
+							agent: String(agent),
+							runId,
+							toolCallId,
+							error: `Missing client tool handler for '${pending.toolName}'.`
+						});
+						return;
+					}
+					try {
+						const result = await Promise.resolve(handler({
+							toolName: pending.toolName,
+							input: parsedArgs,
+							context
+						}));
+						await submitToolResult({
+							agent: String(agent),
+							runId,
+							toolCallId,
+							result
+						});
+					} catch (error) {
+						await submitToolResult({
+							agent: String(agent),
+							runId,
+							toolCallId,
+							error: error instanceof Error ? error.message : "Client tool handler failed."
+						});
+					}
+				};
+				try {
+					const prepared = await prepareRequest(advanced, {
+						operation: "stream",
+						url: `${baseURL}/${encodeURIComponent(String(agent))}/run`,
+						method: "POST",
+						headers: mergeHeaders(authHeaders, {
+							"content-type": "application/json",
+							accept: "text/event-stream"
+						}, config.headers, options?.headers),
+						body: JSON.stringify({
+							...request,
+							stream: true
+						})
+					});
+					const res = await doFetch(prepared.url, {
+						method: prepared.method,
+						headers: prepared.headers,
+						body: prepared.body,
+						signal: options?.signal ?? null
+					});
+					options?.onResponse?.(res);
+					if (!res.ok) await throwRequestError({
+						response: res,
+						operation: "stream",
+						at: "client.core.stream",
+						context: { agentName: agent }
+					});
+					if (!res.body) return;
+					for await (const ev of parseSse(res.body)) {
+						if (ev.type === "TOOL_CALL_START") {
+							if (ev.toolTarget !== "client") {
+								yield ev;
+								continue;
+							}
+							if (typeof ev.runId === "string") pendingToolCalls.set(getToolCallKey(ev.runId, ev.toolCallId), {
+								toolName: ev.toolCallName,
+								argsJson: "",
+								ended: false,
+								submitted: false,
+								approvalState: "waiting"
+							});
+						} else if (ev.type === "TOOL_CALL_ARGS") {
+							if (typeof ev.runId !== "string") {
+								yield ev;
+								continue;
+							}
+							const pending = pendingToolCalls.get(getToolCallKey(ev.runId, ev.toolCallId));
+							if (pending) pending.argsJson += ev.delta;
+						} else if (ev.type === "TOOL_CALL_END" && typeof ev.runId === "string") {
+							const toolCallKey = getToolCallKey(ev.runId, ev.toolCallId);
+							const pending = pendingToolCalls.get(toolCallKey);
+							if (pending) {
+								pending.ended = true;
+								await processClientToolCall(toolCallKey, ev.runId, ev.toolCallId);
+							}
+						} else if ((ev.type === "TOOL_APPROVAL_REQUIRED" || ev.type === "TOOL_APPROVAL_UPDATED") && ev.toolTarget === "client" && typeof ev.runId === "string") {
+							const toolCallKey = getToolCallKey(ev.runId, ev.toolCallId);
+							const pending = pendingToolCalls.get(toolCallKey);
+							if (pending) {
+								pending.approvalState = ev.state === "approved" ? "approved" : ev.state === "requested" ? "requested" : ev.state === "denied" ? "denied" : "expired";
+								if (pending.approvalState === "denied" || pending.approvalState === "expired") {
+									pending.submitted = true;
+									pendingToolCalls.delete(toolCallKey);
+								} else if (pending.approvalState === "approved") await processClientToolCall(toolCallKey, ev.runId, ev.toolCallId);
+							}
+						}
+						if (ev.type === "RUN_ABORTED" || ev.type === "RUN_ERROR" || ev.type === "RUN_FINISHED") {
+							for (const [toolCallKey, pending] of pendingToolCalls) if (pending.submitted) pendingToolCalls.delete(toolCallKey);
+							abortToolCalls();
+						}
+						yield ev;
+					}
+				} finally {
+					abortToolCalls();
+					if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
+					pendingToolCalls.clear();
+				}
+			})();
+		},
+		resumeStream(agent, input, options) {
+			return (async function* () {
+				const searchParams = new URLSearchParams();
+				searchParams.set("streamId", input.streamId);
+				const headers = mergeHeaders(authHeaders, { accept: "text/event-stream" }, config.headers, options?.headers);
+				if (typeof input.afterSeq === "number") headers.set("last-event-id", String(input.afterSeq));
+				const prepared = await prepareRequest(advanced, {
+					operation: "resume-stream",
+					url: `${baseURL}/${encodeURIComponent(String(agent))}/stream-events/resume?${searchParams.toString()}`,
+					method: "GET",
+					headers
+				});
+				const res = await doFetch(prepared.url, {
+					method: prepared.method,
+					headers: prepared.headers,
+					...prepared.body !== void 0 ? { body: prepared.body } : {},
+					signal: options?.signal ?? null
+				});
+				options?.onResponse?.(res);
+				if (res.status === 204) return;
+				if (!res.ok) await throwRequestError({
+					response: res,
+					operation: "resume-stream",
+					at: "client.core.resumeStream",
+					context: { agentName: agent }
+				});
+				if (!res.body) return;
+				for await (const ev of parseSse(res.body)) yield ev;
+			})();
+		},
+		resumeConversation(agent, input, options) {
+			return (async function* () {
+				const headers = mergeHeaders(authHeaders, { accept: "text/event-stream" }, config.headers, options?.headers);
+				if (typeof input.afterSeq === "number") headers.set("last-event-id", String(input.afterSeq));
+				const prepared = await prepareRequest(advanced, {
+					operation: "resume-conversation",
+					url: `${baseURL}/${encodeURIComponent(String(agent))}/conversations/${encodeURIComponent(input.conversationId)}/resume`,
+					method: "GET",
+					headers
+				});
+				const res = await doFetch(prepared.url, {
+					method: prepared.method,
+					headers: prepared.headers,
+					...prepared.body !== void 0 ? { body: prepared.body } : {},
+					signal: options?.signal ?? null
+				});
+				options?.onResponse?.(res);
+				if (res.status === 204) return;
+				if (!res.ok) await throwRequestError({
+					response: res,
+					operation: "resume-conversation",
+					at: "client.core.resumeConversation",
+					context: {
+						agentName: agent,
+						conversationId: input.conversationId
+					}
+				});
+				if (!res.body) return;
+				for await (const ev of parseSse(res.body)) yield ev;
+			})();
+		},
+		async loadConversation(agent, conversationId, options) {
+			const prepared = await prepareRequest(advanced, {
+				operation: "load-conversation",
+				url: `${baseURL}/${encodeURIComponent(String(agent))}/conversations/${encodeURIComponent(conversationId)}`,
+				method: "GET",
+				headers: mergeHeaders(authHeaders, config.headers, options?.headers)
+			});
+			const res = await doFetch(prepared.url, {
+				method: prepared.method,
+				headers: prepared.headers,
+				...prepared.body !== void 0 ? { body: prepared.body } : {},
+				signal: options?.signal ?? null
+			});
+			options?.onResponse?.(res);
+			if (res.status === 204) return null;
+			if (!res.ok) await throwRequestError({
+				response: res,
+				operation: "load-conversation",
+				at: "client.core.loadConversation",
+				context: {
+					agentName: agent,
+					conversationId
+				}
+			});
+			return await res.json();
+		},
+		async abortRun(req, options) {
+			const prepared = await prepareRequest(advanced, {
+				operation: "abort-run",
+				url: `${baseURL}/${encodeURIComponent(String(req.agent))}/runs/${encodeURIComponent(req.runId)}/abort`,
+				method: "POST",
+				headers: mergeHeaders(authHeaders, config.headers, options?.headers)
+			});
+			const res = await doFetch(prepared.url, {
+				method: prepared.method,
+				headers: prepared.headers,
+				...prepared.body !== void 0 ? { body: prepared.body } : {},
+				signal: options?.signal ?? null
+			});
+			options?.onResponse?.(res);
+			if (res.status === 204) return;
+			if (!res.ok) await throwRequestError({
+				response: res,
+				operation: "abort-run",
+				at: "client.core.abortRun",
+				context: {
+					agentName: req.agent,
+					runId: req.runId
+				}
+			});
+		},
+		async submitToolResult(req) {
+			await submitToolResult({
+				...req,
+				agent: String(req.agent)
+			});
+		},
+		async submitToolApproval(req) {
+			await submitToolApproval({
+				...req,
+				agent: String(req.agent)
+			});
+		}
+	};
+};
+const getToolCallKey = (runId, toolCallId) => `${runId}:${toolCallId}`;
+const resolveToolHandler = (toolName, options, staticToolHandlers) => {
+	const requestHandler = options?.onToolCall;
+	const requestToolHandler = (options?.toolHandlers)?.[toolName];
+	const staticHandler = staticToolHandlers?.[toolName];
+	return requestHandler ?? (requestToolHandler ? (params) => requestToolHandler(params.input, params.context) : void 0) ?? (staticHandler ? (params) => staticHandler(params.input, params.context) : void 0);
+};
+
+//#endregion
+export { createAgentChatController, createClient, fromConversationItems, fromModelMessages, getEventErrorMessage, pruneInputByCapabilities, toAgentClientError, toModelMessages };
+//# sourceMappingURL=index.mjs.map