@softr/sdk 0.0.87-alpha.3 → 0.0.87

package/dist/agent/agent-fns.js

@@ -1,164 +0,0 @@
-import { assert } from "../assertions.js";
-import { fetch } from "../fetch.js";
-import { sessionConfig } from "../auth/config.js";
-import { readSessionToken } from "../auth/session.js";
-import { softrApiUrl } from "../softr-api.js";
-import { describeFailure, refererHeader } from "../datasource/record.js";
-import { z } from "zod";
-import { createServerFn } from "@tanstack/react-start";
-import { getRequest } from "@tanstack/react-start/server";
-
-//#region src/agent/agent-fns.ts
-const AGENTS_PRODUCTION = "https://agents-api.softr.io";
-/**
-* Where the agents service is. It sits next to the platform API, so unless
-* `SOFTR_AGENTS_API_URL` says otherwise, it's the platform's host with
-* `agents-api` in place of `platform-api`.
-*/
-function agentsApiUrl() {
-	const explicit = process.env.SOFTR_AGENTS_API_URL;
-	if (explicit) return explicit.replace(/\/+$/, "");
-	if (!process.env.SOFTR_PLATFORM_API_URL) return AGENTS_PRODUCTION;
-	const platform = new URL(softrApiUrl("SOFTR_PLATFORM_API_URL"));
-	assert(platform.hostname.startsWith("platform-api"), () => `can't tell the agents API from ${platform.origin}, set SOFTR_AGENTS_API_URL`);
-	platform.hostname = platform.hostname.replace(/^platform-api/, "agents-api");
-	return platform.origin;
-}
-function agentsFetch(path, init = {}) {
-	const token = readSessionToken();
-	return fetch(`${agentsApiUrl()}/v1/agents/${path}`, {
-		method: init.method ?? "GET",
-		signal: init.signal,
-		headers: {
-			"Content-Type": "application/json",
-			...token ? { Authorization: `Bearer ${token}` } : {},
-			"Softr-Application-ID": sessionConfig().applicationId,
-			...refererHeader(),
-			...init.headers
-		},
-		body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
-	});
-}
-const chatSchema = z.object({
-	agentId: z.string().min(1),
-	message: z.string(),
-	sessionId: z.string().nullable(),
-	timezone: z.string(),
-	pageName: z.string(),
-	record: z.object({
-		id: z.string(),
-		fields: z.record(z.string(), z.unknown())
-	}).nullable()
-});
-/**
-* Sends one message and streams the reply back as it comes, one JSON event per line.
-*
-* Takes FormData so the browser can call it with plain `fetch` and read the
-* stream itself. A failed call passes the agents service's status and message on.
-*/
-const agentChatFn = createServerFn({ method: "POST" }).validator((data) => {
-	const payload = data.get("payload");
-	assert(typeof payload === "string", "agent chat: payload is required");
-	return chatSchema.parse(JSON.parse(payload));
-}).handler(async ({ data }) => {
-	const upstream = await agentsFetch(`${encodeURIComponent(data.agentId)}/chat`, {
-		method: "POST",
-		signal: getRequest().signal,
-		headers: {
-			Accept: "application/x-ndjson",
-			"X-User-Timezone": data.timezone
-		},
-		body: {
-			message: data.message,
-			...data.sessionId ? { sessionId: data.sessionId } : {},
-			context: {
-				pageName: data.pageName,
-				...data.record ? { currentRecord: { data: data.record } } : {}
-			}
-		}
-	});
-	return new Response(upstream.body, {
-		status: upstream.status,
-		headers: { "Content-Type": upstream.headers.get("Content-Type") ?? "application/x-ndjson" }
-	});
-});
-const agentSchema = z.object({
-	id: z.string(),
-	title: z.string(),
-	avatar: z.string().nullish(),
-	thumbnail: z.string().nullish()
-});
-/**
-* The agents the visitor may chat with in this app. The builder attaches them
-* in Studio, and each one's visibility settings decide who sees it.
-*/
-const listAgents = createServerFn({ method: "GET" }).handler(async () => {
-	const token = readSessionToken();
-	const res = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${sessionConfig().applicationId}/agents`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
-	if (!res.ok) throw new Error(`Loading agents failed: ${await describeFailure(res)}`);
-	return z.array(agentSchema).parse(await res.json());
-});
-const listAgentChatsFn = createServerFn({ method: "POST" }).validator(z.object({ agentId: z.string().min(1) })).handler(async ({ data }) => {
-	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions`);
-	if (!res.ok) throw new Error(`Loading chats failed: ${await describeFailure(res)}`);
-	return z.array(z.object({
-		id: z.string(),
-		title: z.string()
-	})).parse(await res.json());
-});
-const historySchema = z.object({
-	messages: z.array(z.object({
-		id: z.string(),
-		role: z.enum(["USER", "ASSISTANT"]),
-		content: z.string(),
-		createdAt: z.number()
-	})),
-	toolCalls: z.array(z.object({
-		id: z.string(),
-		messageId: z.string(),
-		toolName: z.string(),
-		input: z.string(),
-		createdAt: z.number(),
-		metadata: z.object({
-			innerThought: z.string().nullish(),
-			durationMs: z.number().nullish(),
-			failed: z.boolean().nullish()
-		})
-	}))
-});
-/** What a past chat holds, or `null` when it's gone or belongs to someone else. */
-const loadAgentChatFn = createServerFn({ method: "POST" }).validator(z.object({
-	agentId: z.string().min(1),
-	sessionId: z.string().min(1)
-})).handler(async ({ data }) => {
-	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions/${encodeURIComponent(data.sessionId)}`);
-	if ([
-		401,
-		403,
-		404,
-		410
-	].includes(res.status)) return null;
-	if (!res.ok) throw new Error(`Loading the chat failed: ${await describeFailure(res)}`);
-	return historySchema.parse(await res.json());
-});
-const decideAgentToolFn = createServerFn({ method: "POST" }).validator(z.object({
-	agentId: z.string().min(1),
-	sessionId: z.string().min(1),
-	toolCallId: z.string().min(1),
-	toolName: z.string().min(1),
-	decision: z.enum(["APPROVE", "REJECT"]),
-	scope: z.enum([
-		"ONCE",
-		"SESSION",
-		"USER"
-	])
-})).handler(async ({ data: { agentId,...decision } }) => {
-	const res = await agentsFetch(`${encodeURIComponent(agentId)}/tool-permission-decisions`, {
-		method: "POST",
-		body: decision
-	});
-	if (!res.ok) throw new Error(`Saving the answer failed: ${await describeFailure(res)}`);
-});
-
-//#endregion
-export { agentChatFn, decideAgentToolFn, listAgentChatsFn, listAgents, loadAgentChatFn };

package/dist/agent/use-agent-chat.d.ts

@@ -1,94 +0,0 @@
-import { AgentChatSummary } from "./agent-fns.js";
-
-//#region src/agent/use-agent-chat.d.ts
-/** A step of the agent's work: a tool it calls, and where that call stands. */
-type AgentToolCall = {
-  type: "tool";
-  id: string;
-  name: string;
-  /** The tool's input as the agent sent it, usually JSON. */
-  input?: string;
-  /**
-   * `awaiting-approval` waits for `approve` or `reject`. `awaiting-connection`
-   * needs the visitor to connect `integration` first, which code apps can't do yet.
-   */
-  status: "running" | "done" | "failed" | "awaiting-approval" | "approved" | "rejected" | "awaiting-connection";
-  error?: string;
-  integration?: string;
-};
-type AgentTodo = {
-  content: string;
-  status: "pending" | "in_progress" | "completed";
-};
-type AgentQuestion = {
-  question: string;
-  header: string;
-  options: Array<{
-    label: string;
-    description: string;
-  }>;
-  multiSelect: boolean;
-};
-/** One piece of a message, in the order the agent produced it. */
-type AgentBlock = {
-  type: "text";
-  text: string;
-} | AgentToolCall
-/** The agent's plan. It replaces itself as the agent works through it. */ | {
-  type: "todo";
-  todos: AgentTodo[];
-}
-/** The agent asks the visitor to pick. They answer by sending a message. */ | {
-  type: "question";
-  questions: AgentQuestion[];
-} | {
-  type: "error";
-  message: string;
-};
-type AgentMessage = {
-  id: string;
-  role: "user" | "assistant";
-  blocks: AgentBlock[];
-};
-type AgentChat = {
-  /** The whole chat, oldest first. While the agent replies, its reply is the last one and grows. */
-  messages: AgentMessage[];
-  /** `thinking` until the first part of the reply arrives, `replying` until it ends. */
-  status: "idle" | "thinking" | "replying";
-  /** Why the last request failed. Cleared by the next one. */
-  error: Error | null;
-  /** The chat the next message goes to, `null` for a new one. */
-  chatId: string | null;
-  send: (text: string) => void;
-  /** Stops the reply. What arrived so far stays. */
-  stop: () => void;
-  newChat: () => void;
-  /** Opens a past chat from `listChats`. */
-  openChat: (chatId: string) => void;
-  /** The visitor's past chats with this agent. */
-  listChats: () => Promise<AgentChatSummary[]>;
-  /** Lets a tool waiting for approval run, once, for this chat, or always for this visitor. */
-  approve: (toolCallId: string, scope?: "ONCE" | "SESSION" | "USER") => void;
-  reject: (toolCallId: string) => void;
-};
-type AgentChatOptions = {
-  /**
-   * The record the visitor is looking at, so they can say "this one". Sent
-   * with each message. Keys are what the agent reads, so use field names.
-   */
-  record?: {
-    id: string;
-    fields: Record<string, unknown>;
-  } | null;
-};
-/**
- * A chat with one of the app's Softr agents, as the signed-in visitor. No UI:
- * render `messages` with the app's own components.
- *
- * @example
- * const chat = useAgentChat(AGENT_ID, { record: ticket && { id: ticket.id, fields: ticket.fields } })
- * <form onSubmit={(e) => { e.preventDefault(); chat.send(draft) }}>
- */
-declare function useAgentChat(agentId: string, options?: AgentChatOptions): AgentChat;
-//#endregion
-export { AgentBlock, AgentChat, AgentChatOptions, AgentMessage, AgentQuestion, AgentTodo, AgentToolCall, useAgentChat };

package/dist/agent/use-agent-chat.js

@@ -1,367 +0,0 @@
-import { assert } from "../assertions.js";
-import { agentChatFn, decideAgentToolFn, listAgentChatsFn, loadAgentChatFn } from "./agent-fns.js";
-import { useCallback, useEffect, useRef, useState } from "react";
-
-//#region src/agent/use-agent-chat.ts
-/**
-* A chat with one of the app's Softr agents, as the signed-in visitor. No UI:
-* render `messages` with the app's own components.
-*
-* @example
-* const chat = useAgentChat(AGENT_ID, { record: ticket && { id: ticket.id, fields: ticket.fields } })
-* <form onSubmit={(e) => { e.preventDefault(); chat.send(draft) }}>
-*/
-function useAgentChat(agentId, options = {}) {
-	const [messages, setMessages] = useState([]);
-	const [live, setLive] = useState(null);
-	const [status, setStatus] = useState("idle");
-	const [error, setError] = useState(null);
-	const [chatId, setChatId] = useState(null);
-	const chatIdRef = useRef(chatId);
-	chatIdRef.current = chatId;
-	const recordRef = useRef(options.record ?? null);
-	recordRef.current = options.record ?? null;
-	const liveRef = useRef(live);
-	liveRef.current = live;
-	const abortRef = useRef(null);
-	useEffect(() => () => abortRef.current?.abort(), []);
-	const commitLive = useCallback((blocks) => {
-		setLive(null);
-		if (!blocks?.some((b) => b.type !== "text" || b.text.trim())) return;
-		setMessages((prev) => [...prev, {
-			id: crypto.randomUUID(),
-			role: "assistant",
-			blocks: endRunningTools(blocks)
-		}]);
-	}, []);
-	const stream = useCallback(async (message) => {
-		abortRef.current?.abort();
-		const controller = new AbortController();
-		abortRef.current = controller;
-		setError(null);
-		setStatus("thinking");
-		let blocks = [];
-		try {
-			const request = {
-				agentId,
-				message,
-				sessionId: chatIdRef.current,
-				timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-				pageName: document.title,
-				record: recordRef.current
-			};
-			const form = new FormData();
-			form.append("payload", JSON.stringify(request));
-			const res = await fetch(agentChatFn.url, {
-				method: "POST",
-				body: form,
-				signal: controller.signal
-			});
-			if (!res.ok) throw new Error(await failureMessage(res));
-			assert(res.body, "agent chat: the reply has no body");
-			const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
-			let buffer = "";
-			const onLine = (line) => {
-				const event = parseEvent(line);
-				if (event === null) return;
-				if (event.sessionId && event.sessionId !== chatIdRef.current) {
-					chatIdRef.current = event.sessionId;
-					setChatId(event.sessionId);
-				}
-				blocks = reduceEvent(blocks, event);
-				setLive(blocks);
-				setStatus("replying");
-			};
-			for (;;) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				buffer += value;
-				const lines = buffer.split("\n");
-				buffer = lines.pop() ?? "";
-				lines.forEach(onLine);
-			}
-			onLine(buffer);
-		} catch (err) {
-			if (controller.signal.aborted) return;
-			setError(err instanceof Error ? err : new Error(String(err)));
-		}
-		if (abortRef.current !== controller) return;
-		abortRef.current = null;
-		commitLive(blocks);
-		setStatus("idle");
-	}, [agentId, commitLive]);
-	const send = useCallback((text) => {
-		const trimmed = text.trim();
-		if (!trimmed) return;
-		abortRef.current?.abort();
-		commitLive(liveRef.current);
-		setMessages((prev) => [...prev, {
-			id: crypto.randomUUID(),
-			role: "user",
-			blocks: [{
-				type: "text",
-				text: trimmed
-			}]
-		}]);
-		stream(trimmed);
-	}, [stream, commitLive]);
-	const stop = useCallback(() => {
-		if (abortRef.current === null) return;
-		abortRef.current.abort();
-		abortRef.current = null;
-		commitLive(liveRef.current);
-		setStatus("idle");
-	}, [commitLive]);
-	const reset = useCallback((id) => {
-		abortRef.current?.abort();
-		abortRef.current = null;
-		chatIdRef.current = id;
-		setChatId(id);
-		setMessages([]);
-		setLive(null);
-		setStatus("idle");
-		setError(null);
-	}, []);
-	const newChat = useCallback(() => reset(null), [reset]);
-	const openChat = useCallback((id) => {
-		reset(id);
-		loadAgentChatFn({ data: {
-			agentId,
-			sessionId: id
-		} }).then((history) => {
-			if (chatIdRef.current !== id) return;
-			if (history === null) {
-				reset(null);
-				setError(/* @__PURE__ */ new Error("This chat is no longer available. Start a new one."));
-				return;
-			}
-			setMessages(fromHistory(history));
-		}).catch((err) => {
-			if (chatIdRef.current === id) setError(err instanceof Error ? err : new Error(String(err)));
-		});
-	}, [agentId, reset]);
-	const listChats = useCallback(() => listAgentChatsFn({ data: { agentId } }), [agentId]);
-	const setToolStatus = useCallback((toolCallId, next) => {
-		const update = (blocks) => blocks.map((b) => b.type === "tool" && b.id === toolCallId ? {
-			...b,
-			status: next
-		} : b);
-		setLive((prev) => prev && update(prev));
-		setMessages((prev) => prev.map((m) => ({
-			...m,
-			blocks: update(m.blocks)
-		})));
-	}, []);
-	const decide = useCallback((toolCallId, decision, scope) => {
-		const sessionId = chatIdRef.current;
-		const tool = [...messages.flatMap((m) => m.blocks), ...liveRef.current ?? []].find((b) => b.type === "tool" && b.id === toolCallId);
-		if (sessionId === null || tool?.status !== "awaiting-approval") return;
-		setToolStatus(toolCallId, decision === "APPROVE" ? "approved" : "rejected");
-		decideAgentToolFn({ data: {
-			agentId,
-			sessionId,
-			toolCallId,
-			toolName: tool.name,
-			decision,
-			scope
-		} }).then(() => {
-			if (decision !== "APPROVE") return;
-			abortRef.current?.abort();
-			commitLive(liveRef.current);
-			stream("");
-		}).catch((err) => {
-			setToolStatus(toolCallId, "awaiting-approval");
-			setError(err instanceof Error ? err : new Error(String(err)));
-		});
-	}, [
-		agentId,
-		messages,
-		setToolStatus,
-		commitLive,
-		stream
-	]);
-	const approve = useCallback((toolCallId, scope = "ONCE") => decide(toolCallId, "APPROVE", scope), [decide]);
-	const reject = useCallback((toolCallId) => decide(toolCallId, "REJECT", "ONCE"), [decide]);
-	return {
-		messages: live === null ? messages : [...messages, {
-			id: "live",
-			role: "assistant",
-			blocks: live
-		}],
-		status,
-		error,
-		chatId,
-		send,
-		stop,
-		newChat,
-		openChat,
-		listChats,
-		approve,
-		reject
-	};
-}
-const TODO_TOOL = "TodoWrite";
-/** Its question shows as a question block, so the call itself is noise. */
-const QUESTION_TOOL = "AskUserQuestion";
-function parseEvent(line) {
-	if (!line.trim()) return null;
-	try {
-		return JSON.parse(line);
-	} catch {
-		return null;
-	}
-}
-function reduceEvent(blocks, event) {
-	switch (event.type) {
-		case "TEXT": {
-			const last = blocks.at(-1);
-			return last?.type === "text" ? [...blocks.slice(0, -1), {
-				type: "text",
-				text: last.text + event.response
-			}] : [...blocks, {
-				type: "text",
-				text: event.response
-			}];
-		}
-		case "TOOL_CALL_START":
-			if (event.toolName === TODO_TOOL) {
-				const todos = parseTodos(event.input);
-				if (todos) return upsertTodos(blocks, todos);
-			}
-			if (event.toolName === QUESTION_TOOL) return blocks;
-			if (blocks.some((b) => b.type === "tool" && b.id === event.toolCallId)) return updateTool(blocks, event.toolCallId, (b) => b.status === "running" ? {
-				...b,
-				input: event.input ?? b.input
-			} : b);
-			return [...blocks, {
-				type: "tool",
-				id: event.toolCallId,
-				name: event.toolName,
-				input: event.input,
-				integration: event.integrationType,
-				status: "running"
-			}];
-		case "TOOL_CALL_END": return updateTool(blocks, event.toolCallId, (b) => b.status === "running" || b.status === "approved" ? {
-			...b,
-			status: event.failed ? "failed" : "done",
-			error: event.errorMessage
-		} : b);
-		case "TOOL_PERMISSION_REQUEST":
-		case "INTEGRATION_AUTH_REQUEST": {
-			const status = event.type === "TOOL_PERMISSION_REQUEST" ? "awaiting-approval" : "awaiting-connection";
-			const integration = event.type === "INTEGRATION_AUTH_REQUEST" ? event.integrationType : void 0;
-			if (blocks.some((b) => b.type === "tool" && b.id === event.toolCallId)) return updateTool(blocks, event.toolCallId, (b) => ({
-				...b,
-				status,
-				integration: integration ?? b.integration,
-				input: ("input" in event ? event.input : void 0) ?? b.input
-			}));
-			return [...blocks, {
-				type: "tool",
-				id: event.toolCallId,
-				name: event.toolName,
-				input: "input" in event ? event.input : void 0,
-				integration,
-				status
-			}];
-		}
-		case "QUESTION": return [...blocks, {
-			type: "question",
-			questions: event.questions
-		}];
-		case "ERROR": return [...blocks, {
-			type: "error",
-			message: event.message
-		}];
-		default: return blocks;
-	}
-}
-function updateTool(blocks, id, update) {
-	return blocks.map((b) => b.type === "tool" && b.id === id ? update(b) : b);
-}
-/** A reply that ended without finishing a tool call, stopped or cut off, never will. */
-function endRunningTools(blocks) {
-	return blocks.map((b) => b.type === "tool" && b.status === "running" ? {
-		...b,
-		status: "failed",
-		error: "The agent stopped before this step finished."
-	} : b);
-}
-/** Each plan update re-sends the whole list, so only the latest one is kept, where the first one was. */
-function upsertTodos(blocks, todos) {
-	const index = blocks.findIndex((b) => b.type === "todo");
-	if (index === -1) return [...blocks, {
-		type: "todo",
-		todos
-	}];
-	return blocks.map((b, i) => i === index ? {
-		type: "todo",
-		todos
-	} : b);
-}
-function parseTodos(input) {
-	if (!input) return null;
-	try {
-		const parsed = JSON.parse(input);
-		if (typeof parsed !== "object" || parsed === null || !("todos" in parsed)) return null;
-		const outer = parsed.todos;
-		const raw = typeof outer === "object" && outer !== null && "todos" in outer ? outer.todos : outer;
-		if (!Array.isArray(raw)) return null;
-		const todos = raw.flatMap((item) => {
-			if (typeof item !== "object" || item === null) return [];
-			const { content, status } = item;
-			if (typeof content !== "string" || !content.trim()) return [];
-			if (status !== "pending" && status !== "in_progress" && status !== "completed") return [];
-			return [{
-				content,
-				status
-			}];
-		});
-		return todos.length > 0 ? todos : null;
-	} catch {
-		return null;
-	}
-}
-function fromHistory(history) {
-	const toolsByMessage = Map.groupBy(history.toolCalls, (call) => call.messageId);
-	return history.messages.filter((m) => m.role !== "USER" || m.content.trim()).map((m) => {
-		if (m.role === "USER") return {
-			id: m.id,
-			role: "user",
-			blocks: [{
-				type: "text",
-				text: m.content
-			}]
-		};
-		let blocks = [];
-		const calls = (toolsByMessage.get(m.id) ?? []).toSorted((a, b) => a.createdAt - b.createdAt);
-		for (const call of calls) {
-			const todos = call.toolName === TODO_TOOL ? parseTodos(call.input) : null;
-			if (todos) blocks = upsertTodos(blocks, todos);
-			else if (call.toolName !== QUESTION_TOOL) blocks.push({
-				type: "tool",
-				id: call.id,
-				name: call.toolName,
-				input: call.input,
-				status: call.metadata.failed ? "failed" : "done"
-			});
-		}
-		if (m.content) blocks.push({
-			type: "text",
-			text: m.content
-		});
-		return {
-			id: m.id,
-			role: "assistant",
-			blocks
-		};
-	});
-}
-async function failureMessage(res) {
-	const body = await res.json().catch(() => null);
-	if (typeof body === "object" && body !== null && "message" in body && typeof body.message === "string") return body.message;
-	return `The agent could not answer (${res.status}).`;
-}
-
-//#endregion
-export { useAgentChat };