@flue/sdk 0.3.11 → 0.4.1

package/dist/cloudflare/index.mjs

@@ -1,9 +1,12 @@
-import "../agent-Cahthgu3.mjs";
-import "../session-DlwIt7wq.mjs";
+import "../result-K1IRhWKM.mjs";
+import { c as CLOUDFLARE_AI_BINDING_API, n as getModelBinding } from "../providers-DeFRIwp0.mjs";
+import { t as abortErrorFor } from "../abort-Bg3qsAkU.mjs";
+import "../session-CFOByKnM.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
-import { t as normalizeExecutor } from "../command-helpers-hTZKWK13.mjs";
+import { createAssistantMessageEventStream, parseStreamingJson } from "@mariozechner/pi-ai";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { convertMessages } from "@mariozechner/pi-ai/openai-completions";
 
 //#region src/cloudflare/context.ts
 /**
@@ -113,28 +116,6 @@ async function getVirtualSandbox(bucket, options) {
 	});
 }
 
-//#endregion
-//#region src/cloudflare/define-command.ts
-/**
-* Cloudflare-specific `defineCommand`. Function form only — Workers cannot
-* spawn host processes, so there is no pass-through sugar. The user supplies
-* an executor (typically `fetch`-based or SDK-based) and benefits from
-* return-shape normalization plus automatic throw-catching.
-*
-* ```ts
-* const issues = defineCommand('issues', async (args) => {
-*   const res = await fetch(`https://api.github.com/...`);
-*   return { stdout: await res.text() };
-* });
-* ```
-*/
-function defineCommand(name, execute) {
-	return {
-		name,
-		execute: normalizeExecutor(execute)
-	};
-}
-
 //#endregion
 //#region src/cloudflare/cf-sandbox.ts
 /** Wraps a @cloudflare/sandbox instance (from getSandbox()) into SessionEnv. */
@@ -195,12 +176,15 @@ async function cfSandboxToSessionEnv(sandbox, cwd = "/workspace") {
 			} else await sandbox.deleteFile(path);
 		},
 		async exec(command, execOpts) {
+			const externalSignal = execOpts?.signal;
+			if (externalSignal?.aborted) throw abortErrorFor(externalSignal);
 			const timeoutMs = typeof execOpts?.timeout === "number" ? execOpts.timeout * 1e3 : void 0;
 			const result = await sandbox.exec(command, {
 				cwd: execOpts?.cwd,
 				env: execOpts?.env,
 				timeout: timeoutMs
 			});
+			if (externalSignal?.aborted) throw abortErrorFor(externalSignal);
 			return {
 				stdout: result.stdout ?? "",
 				stderr: result.stderr ?? "",
@@ -240,4 +224,382 @@ function store() {
 }
 
 //#endregion
-export { cfSandboxToSessionEnv, defineCommand, getCloudflareContext, getVirtualSandbox, runWithCloudflareContext, store };
+//#region src/cloudflare/workers-ai-provider.ts
+/**
+* Mirrors pi-ai's `detectCompat('cloudflare-workers-ai')`. Hardcoded here
+* because `convertMessages` requires a fully-resolved compat object and the
+* binding's wire format matches `cloudflare-workers-ai` exactly. Re-mirror
+* if pi-ai's detection logic changes upstream.
+*/
+const WORKERS_AI_COMPAT = {
+	supportsStore: false,
+	supportsDeveloperRole: false,
+	supportsReasoningEffort: true,
+	supportsUsageInStreaming: true,
+	maxTokensField: "max_completion_tokens",
+	requiresToolResultName: false,
+	requiresAssistantAfterToolResult: false,
+	requiresThinkingAsText: false,
+	requiresReasoningContentOnAssistantMessages: false,
+	thinkingFormat: "openai",
+	openRouterRouting: {},
+	vercelGatewayRouting: {},
+	zaiToolStream: false,
+	supportsStrictMode: true,
+	cacheControlFormat: void 0,
+	sendSessionAffinityHeaders: true,
+	supportsLongCacheRetention: false
+};
+function convertTools(tools) {
+	return tools.map((tool) => ({
+		type: "function",
+		function: {
+			name: tool.name,
+			description: tool.description,
+			parameters: tool.parameters,
+			...WORKERS_AI_COMPAT.supportsStrictMode !== false && { strict: false }
+		}
+	}));
+}
+function emptyUsage() {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			total: 0
+		}
+	};
+}
+function parseChunkUsage(raw) {
+	const cacheRead = raw.prompt_tokens_details?.cached_tokens ?? 0;
+	const promptTokens = raw.prompt_tokens ?? 0;
+	const completionTokens = raw.completion_tokens ?? 0;
+	return {
+		input: Math.max(0, promptTokens - cacheRead),
+		output: completionTokens,
+		cacheRead,
+		cacheWrite: 0,
+		totalTokens: raw.total_tokens ?? promptTokens + completionTokens,
+		cost: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			total: 0
+		}
+	};
+}
+function mapStopReason(reason) {
+	switch (reason) {
+		case "stop":
+		case "eos": return { stopReason: "stop" };
+		case "length": return { stopReason: "length" };
+		case "tool_calls":
+		case "function_call": return { stopReason: "toolUse" };
+		case "content_filter": return {
+			stopReason: "error",
+			errorMessage: "Provider stopped generation: content filter"
+		};
+		default: return {
+			stopReason: "error",
+			errorMessage: `Provider finish_reason: ${reason}`
+		};
+	}
+}
+async function* iterateSseChunks(body) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) {
+				if (buffer.trim().length > 0) yield* parseSseEvents(buffer);
+				return;
+			}
+			buffer += decoder.decode(value, { stream: true });
+			let separatorIndex = buffer.indexOf("\n\n");
+			while (separatorIndex !== -1) {
+				const block = buffer.slice(0, separatorIndex);
+				buffer = buffer.slice(separatorIndex + 2);
+				yield* parseSseEvents(block);
+				separatorIndex = buffer.indexOf("\n\n");
+			}
+		}
+	} finally {
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+}
+function* parseSseEvents(block) {
+	for (const rawLine of block.split("\n")) {
+		const line = rawLine.replace(/\r$/, "");
+		if (!line.startsWith("data:")) continue;
+		const data = line.slice(5).trimStart();
+		if (data === "" || data === "[DONE]") continue;
+		try {
+			yield JSON.parse(data);
+		} catch {}
+	}
+}
+function isAbortError(error) {
+	return error instanceof Error && (error.name === "AbortError" || /aborted/i.test(error.message));
+}
+const streamCloudflareWorkersAi = (model, context, options) => {
+	const stream = createAssistantMessageEventStream();
+	(async () => {
+		const output = {
+			role: "assistant",
+			content: [],
+			api: model.api,
+			provider: model.provider,
+			model: model.id,
+			usage: emptyUsage(),
+			stopReason: "stop",
+			timestamp: Date.now()
+		};
+		try {
+			const ai = resolveBinding(model);
+			const payload = {
+				messages: convertMessages(model, context, WORKERS_AI_COMPAT),
+				stream: true,
+				stream_options: { include_usage: true }
+			};
+			if (context.tools && context.tools.length > 0) payload.tools = convertTools(context.tools);
+			if (options?.maxTokens) payload.max_completion_tokens = options.maxTokens;
+			if (options?.temperature !== void 0) payload.temperature = options.temperature;
+			const overridden = await options?.onPayload?.(payload, model);
+			const finalPayload = overridden === void 0 ? payload : overridden;
+			const extraHeaders = {};
+			if (options?.sessionId) extraHeaders["x-session-affinity"] = options.sessionId;
+			if (options?.headers) Object.assign(extraHeaders, options.headers);
+			const response = await ai.run(model.id, finalPayload, {
+				returnRawResponse: true,
+				...options?.signal ? { signal: options.signal } : {},
+				...Object.keys(extraHeaders).length > 0 ? { extraHeaders } : {}
+			});
+			await options?.onResponse?.({
+				status: response.status,
+				headers: headersToRecord(response.headers)
+			}, model);
+			if (!response.ok) {
+				const errorBody = await safeReadText(response);
+				throw new Error(`Cloudflare AI binding returned ${response.status} ${response.statusText}` + (errorBody ? `: ${errorBody}` : ""));
+			}
+			if (!response.body) throw new Error("Cloudflare AI binding returned empty response body.");
+			stream.push({
+				type: "start",
+				partial: output
+			});
+			let currentBlock = null;
+			const blocks = output.content;
+			const indexOf = (block) => block ? blocks.indexOf(block) : -1;
+			const finishCurrentBlock = (block) => {
+				if (!block) return;
+				const contentIndex = indexOf(block);
+				if (contentIndex === -1) return;
+				if (block.type === "text") stream.push({
+					type: "text_end",
+					contentIndex,
+					content: block.text,
+					partial: output
+				});
+				else if (block.type === "thinking") stream.push({
+					type: "thinking_end",
+					contentIndex,
+					content: block.thinking,
+					partial: output
+				});
+				else if (block.type === "toolCall") {
+					block.arguments = parseStreamingJson(block.partialArgs ?? "");
+					delete block.partialArgs;
+					delete block.streamIndex;
+					stream.push({
+						type: "toolcall_end",
+						contentIndex,
+						toolCall: block,
+						partial: output
+					});
+				}
+			};
+			for await (const rawChunk of iterateSseChunks(response.body)) {
+				const chunk = rawChunk;
+				if (!chunk || typeof chunk !== "object") continue;
+				output.responseId ||= chunk.id;
+				if (typeof chunk.model === "string" && chunk.model.length > 0 && chunk.model !== model.id) output.responseModel ||= chunk.model;
+				if (chunk.usage) output.usage = parseChunkUsage(chunk.usage);
+				const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : void 0;
+				if (!choice) continue;
+				if (!chunk.usage && choice.usage) output.usage = parseChunkUsage(choice.usage);
+				if (choice.finish_reason) {
+					const mapped = mapStopReason(choice.finish_reason);
+					output.stopReason = mapped.stopReason;
+					if (mapped.errorMessage) output.errorMessage = mapped.errorMessage;
+				}
+				const delta = choice.delta;
+				if (!delta) continue;
+				if (delta.content !== null && delta.content !== void 0 && delta.content.length > 0) {
+					if (!currentBlock || currentBlock.type !== "text") {
+						finishCurrentBlock(currentBlock);
+						currentBlock = {
+							type: "text",
+							text: ""
+						};
+						blocks.push(currentBlock);
+						stream.push({
+							type: "text_start",
+							contentIndex: indexOf(currentBlock),
+							partial: output
+						});
+					}
+					currentBlock.text += delta.content;
+					stream.push({
+						type: "text_delta",
+						contentIndex: indexOf(currentBlock),
+						delta: delta.content,
+						partial: output
+					});
+				}
+				const reasoningDelta = pickReasoning(delta);
+				if (reasoningDelta) {
+					if (!currentBlock || currentBlock.type !== "thinking") {
+						finishCurrentBlock(currentBlock);
+						currentBlock = {
+							type: "thinking",
+							thinking: "",
+							thinkingSignature: reasoningDelta.field
+						};
+						blocks.push(currentBlock);
+						stream.push({
+							type: "thinking_start",
+							contentIndex: indexOf(currentBlock),
+							partial: output
+						});
+					}
+					currentBlock.thinking += reasoningDelta.text;
+					stream.push({
+						type: "thinking_delta",
+						contentIndex: indexOf(currentBlock),
+						delta: reasoningDelta.text,
+						partial: output
+					});
+				}
+				if (delta.tool_calls) for (const toolCall of delta.tool_calls) {
+					const streamIndex = typeof toolCall.index === "number" ? toolCall.index : void 0;
+					if (!(currentBlock?.type === "toolCall" && (streamIndex !== void 0 && currentBlock.streamIndex === streamIndex || streamIndex === void 0 && !!toolCall.id && currentBlock.id === toolCall.id))) {
+						finishCurrentBlock(currentBlock);
+						currentBlock = {
+							type: "toolCall",
+							id: toolCall.id ?? "",
+							name: toolCall.function?.name ?? "",
+							arguments: {},
+							partialArgs: "",
+							streamIndex
+						};
+						blocks.push(currentBlock);
+						stream.push({
+							type: "toolcall_start",
+							contentIndex: indexOf(currentBlock),
+							partial: output
+						});
+					}
+					const block = currentBlock?.type === "toolCall" ? currentBlock : null;
+					if (block) {
+						if (!block.id && toolCall.id) block.id = toolCall.id;
+						if (!block.name && toolCall.function?.name) block.name = toolCall.function.name;
+						if (block.streamIndex === void 0 && streamIndex !== void 0) block.streamIndex = streamIndex;
+						let toolDelta = "";
+						if (toolCall.function?.arguments) {
+							toolDelta = toolCall.function.arguments;
+							block.partialArgs = (block.partialArgs ?? "") + toolDelta;
+							block.arguments = parseStreamingJson(block.partialArgs);
+						}
+						stream.push({
+							type: "toolcall_delta",
+							contentIndex: indexOf(block),
+							delta: toolDelta,
+							partial: output
+						});
+					}
+				}
+			}
+			finishCurrentBlock(currentBlock);
+			if (options?.signal?.aborted) throw new Error("Request was aborted");
+			if (output.stopReason === "aborted") throw new Error("Request was aborted");
+			if (output.stopReason === "error") throw new Error(output.errorMessage ?? "Provider returned an error stop reason");
+			stream.push({
+				type: "done",
+				reason: output.stopReason,
+				message: output
+			});
+			stream.end();
+		} catch (error) {
+			for (const block of output.content) if (block.type === "toolCall") {
+				delete block.partialArgs;
+				delete block.streamIndex;
+			}
+			output.stopReason = options?.signal?.aborted || isAbortError(error) ? "aborted" : "error";
+			output.errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
+			stream.push({
+				type: "error",
+				reason: output.stopReason,
+				error: output
+			});
+			stream.end();
+		}
+	})();
+	return stream;
+};
+/**
+* Read the binding extension carried on the resolved Model.
+*/
+function resolveBinding(model) {
+	const ai = getModelBinding(model);
+	if (!ai) throw new Error("[flue] Cloudflare AI binding not available. Models prefixed with \"cloudflare/\" require running on the Cloudflare target with `\"ai\": { \"binding\": \"AI\" }` declared in wrangler.jsonc. For URL-based access without the binding, use pi-ai's `cloudflare-workers-ai/...` or `cloudflare-ai-gateway/...` providers (both require Cloudflare API credentials in env vars).");
+	return ai;
+}
+function pickReasoning(delta) {
+	for (const field of ["reasoning_content", "reasoning"]) {
+		const value = delta[field];
+		if (typeof value === "string" && value.length > 0) return {
+			field,
+			text: value
+		};
+	}
+	return null;
+}
+function headersToRecord(headers) {
+	const out = {};
+	headers.forEach((value, key) => {
+		out[key] = value;
+	});
+	return out;
+}
+async function safeReadText(response) {
+	try {
+		return await response.text();
+	} catch {
+		return;
+	}
+}
+/**
+* Return the pi-ai `ApiProvider` definition for the Cloudflare AI binding.
+*/
+function getCloudflareAIBindingApiProvider() {
+	return {
+		api: CLOUDFLARE_AI_BINDING_API,
+		stream: streamCloudflareWorkersAi,
+		streamSimple: streamCloudflareWorkersAi
+	};
+}
+
+//#endregion
+export { cfSandboxToSessionEnv, getCloudflareAIBindingApiProvider, getCloudflareContext, getVirtualSandbox, runWithCloudflareContext, store };

package/dist/cloudflare-model-BeiZ1pLz.d.mts

@@ -0,0 +1,6 @@
+//#region src/cloudflare-model.d.ts
+/** Pi-ai `Api` slug for the binding-backed Workers AI provider. */
+declare const CLOUDFLARE_AI_BINDING_API: "cloudflare-ai-binding";
+type CloudflareAIBindingApi = typeof CLOUDFLARE_AI_BINDING_API;
+//#endregion
+export { CloudflareAIBindingApi as n, CLOUDFLARE_AI_BINDING_API as t };

package/dist/config.d.mts

@@ -0,0 +1,133 @@
+//#region src/config.d.ts
+/**
+ * Flue config file support — `flue.config.{ts,mts,mjs,js,cjs,cts}`.
+ *
+ * Modeled on Vite/Astro:
+ *
+ *   - The config file lives at the project root. Its directory IS the root for
+ *     the purposes of resolving any relative paths it sets (`root`, `output`).
+ *   - Discovery: `--config <path>` (resolved vs. cwd) wins; otherwise we search
+ *     a starting directory (`--root` if given, else cwd) for any of the
+ *     supported extensions, in order.
+ *   - Loading: plain Node dynamic `import()`. We rely on Node's native
+ *     TypeScript type-stripping (Node ≥ 22.18 / ≥ 23.6 by default) to handle
+ *     `.ts` configs. We deliberately do NOT bundle the config — `flue.config`
+ *     is a flat declarative surface, and "what valid TS works" should match
+ *     the same rules the user already absorbed for the rest of the runtime.
+ *     The CLI bin pre-checks the Node version before we ever get here, so
+ *     `ERR_UNKNOWN_FILE_EXTENSION` shouldn't surface in practice.
+ *   - Validation: valibot schema on the user-facing shape.
+ *   - Resolution: CLI inline > config file > built-in defaults. CLI flags
+ *     always win on a per-field basis — only the fields the user actually
+ *     passed get to override the file.
+ *
+ * The two public types mirror Astro's `AstroUserConfig` / `AstroConfig`
+ * split: `UserFlueConfig` is what users author (everything optional);
+ * `FlueConfig` is the resolved shape with required defaults filled in.
+ *
+ * Provider/model configuration lives in `app.ts`, where runtime env is
+ * available.
+ */
+/**
+ * User-facing config shape — everything optional so `defineConfig({})` is
+ * valid. Defaults are filled in at resolution time. Modeled on Astro's
+ * `AstroUserConfig`.
+ */
+interface UserFlueConfig {
+  /**
+   * Build target. Required somewhere — either here or via `--target`.
+   */
+  target?: 'node' | 'cloudflare';
+  /**
+   * Project root. Source files (`agents/`, `roles/`) live here directly,
+   * or under `<root>/.flue/`. Relative paths are resolved vs. the
+   * directory containing the config file (Vite-style: the config file's
+   * dir IS the root by default). Defaults to that directory if unset.
+   */
+  root?: string;
+  /**
+   * Build output dir. Relative paths are resolved vs. the directory
+   * containing the config file. Defaults to `<root>/dist`.
+   */
+  output?: string;
+}
+/**
+ * Resolved config — what the rest of the SDK consumes. All paths are
+ * absolute; all required fields are present.
+ */
+interface FlueConfig {
+  target: 'node' | 'cloudflare';
+  /** Absolute path. */
+  root: string;
+  /** Absolute path. */
+  output: string;
+}
+/**
+ * Identity helper for type inference and editor intellisense, à la Vite's
+ * `defineConfig`. Returns its argument unchanged.
+ *
+ * ```ts
+ * import { defineConfig } from '@flue/sdk/config';
+ * export default defineConfig({ target: 'node' });
+ * ```
+ */
+declare function defineConfig(config: UserFlueConfig): UserFlueConfig;
+interface ResolveConfigPathOptions {
+  /** Where to start searching when `configFile` is not set. */
+  cwd: string;
+  /**
+   * Explicit config-file path (relative to `cwd`, or absolute), or `false`
+   * to disable config loading entirely. Mirrors Astro's
+   * `AstroInlineOnlyConfig.configFile`.
+   */
+  configFile?: string | false;
+}
+/**
+ * Resolve the absolute path of the user's `flue.config.*` file, or
+ * `undefined` if none is found and the user didn't ask for one.
+ *
+ * Throws if `configFile` is an explicit path that doesn't exist on disk —
+ * that's a typo, not a "config not configured" situation.
+ */
+declare function resolveConfigPath(opts: ResolveConfigPathOptions): string | undefined;
+interface ResolveConfigOptions {
+  /** Working directory of the CLI invocation; default search base. */
+  cwd: string;
+  /**
+   * Optional starting directory to search for the config. If unset, falls
+   * back to `cwd`. Used when the CLI received `--root` and we want to look
+   * for a config inside that directory rather than cwd. Vite has the same
+   * behavior with `--root`.
+   */
+  searchFrom?: string;
+  /** Explicit `--config` value, or `false` to skip loading. */
+  configFile?: string | false;
+  /**
+   * Inline overrides from the CLI. Only fields the user actually passed
+   * should be present — `undefined` means "fall through to the config file
+   * value or the default".
+   */
+  inline?: UserFlueConfig;
+}
+interface ResolvedConfigResult {
+  /** Absolute path of the loaded config file, or undefined if none. */
+  configPath: string | undefined;
+  /** The merged-but-unresolved user config (config file + inline). */
+  userConfig: UserFlueConfig;
+  /** The fully-resolved config consumed by the rest of the SDK. */
+  flueConfig: FlueConfig;
+}
+/**
+ * Discover, load, validate, merge, and resolve a Flue config. The single
+ * entry point CLIs and embedders call.
+ *
+ * Precedence (highest first):
+ *   1. CLI inline values (`opts.inline.*`)
+ *   2. `flue.config.ts`
+ *   3. Built-in defaults
+ *
+ * Throws if validation fails or if no `target` is supplied anywhere.
+ */
+declare function resolveConfig(opts: ResolveConfigOptions): Promise<ResolvedConfigResult>;
+//#endregion
+export { FlueConfig, ResolveConfigOptions, ResolveConfigPathOptions, ResolvedConfigResult, UserFlueConfig, defineConfig, resolveConfig, resolveConfigPath };