@flue/sdk 0.3.0 → 0.3.1

package/dist/cloudflare/index.mjs

@@ -0,0 +1,241 @@
+import "../agent-BB4lwAd5.mjs";
+import "../session-DukL3zwF.mjs";
+import { createSandboxSessionEnv } from "../sandbox.mjs";
+import { t as normalizeExecutor } from "../command-helpers-hTZKWK13.mjs";
+import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/cloudflare/context.ts
+/**
+* Cloudflare environment context injection.
+*
+* Durable Objects are single-threaded, but async executions can still interleave
+* at await points. AsyncLocalStorage keeps Cloudflare runtime primitives scoped
+* to the request/fiber that invoked them instead of sharing a module global.
+*/
+const contextStorage = new AsyncLocalStorage();
+function runWithCloudflareContext(ctx, fn) {
+	return contextStorage.run(ctx, fn);
+}
+function getCloudflareContext() {
+	const ctx = contextStorage.getStore();
+	if (!ctx) throw new Error("[flue:cloudflare] Not running in a Cloudflare context. This function can only be called inside a Cloudflare Worker or Durable Object.");
+	return ctx;
+}
+
+//#endregion
+//#region src/cloudflare/virtual-sandbox.ts
+/**
+* In-process just-bash sandbox for Cloudflare Workers (no container).
+* Without args: empty in-memory. With R2 bucket: persistent files via DO SQLite + R2.
+*/
+function adaptStat(cfStat) {
+	return {
+		isFile: cfStat.type === "file",
+		isDirectory: cfStat.type === "directory",
+		isSymbolicLink: cfStat.type === "symlink",
+		mode: cfStat.mode ?? (cfStat.type === "directory" ? 493 : 420),
+		size: cfStat.size,
+		mtime: cfStat.mtime
+	};
+}
+function adaptToJustBash(cfFs) {
+	return {
+		readFile: (path, _opts) => cfFs.readFile(path),
+		readFileBuffer: (path) => cfFs.readFileBytes(path),
+		async writeFile(path, content, _opts) {
+			if (typeof content === "string") await cfFs.writeFile(path, content);
+			else await cfFs.writeFileBytes(path, content);
+		},
+		appendFile: (path, content, _opts) => cfFs.appendFile(path, content),
+		exists: (path) => cfFs.exists(path),
+		async stat(path) {
+			return adaptStat(await cfFs.stat(path));
+		},
+		async lstat(path) {
+			return adaptStat(await cfFs.lstat(path));
+		},
+		mkdir: (path, opts) => cfFs.mkdir(path, opts),
+		readdir: (path) => cfFs.readdir(path),
+		async readdirWithFileTypes(path) {
+			return (await cfFs.readdirWithFileTypes(path)).map((e) => ({
+				name: e.name,
+				isFile: e.type === "file",
+				isDirectory: e.type === "directory",
+				isSymbolicLink: e.type === "symlink"
+			}));
+		},
+		rm: (path, opts) => cfFs.rm(path, opts),
+		cp: (src, dest, opts) => cfFs.cp(src, dest, opts),
+		mv: (src, dest) => cfFs.mv(src, dest),
+		resolvePath: (base, path) => cfFs.resolvePath(base, path),
+		getAllPaths: () => [],
+		async chmod(_path, _mode) {},
+		symlink: (target, linkPath) => cfFs.symlink(target, linkPath),
+		async link(existingPath, newPath) {
+			const content = await cfFs.readFileBytes(existingPath);
+			await cfFs.writeFileBytes(newPath, content);
+		},
+		readlink: (path) => cfFs.readlink(path),
+		realpath: (path) => cfFs.realpath(path),
+		async utimes(_path, _atime, _mtime) {}
+	};
+}
+async function getVirtualSandbox(bucket, options) {
+	if (bucket === void 0) {
+		const { Bash, InMemoryFs } = await import(
+			/* @vite-ignore */
+			"just-bash"
+);
+		const fs = new InMemoryFs();
+		return () => new Bash({
+			fs,
+			network: { dangerouslyAllowFullInternetAccess: true }
+		});
+	}
+	const { storage } = getCloudflareContext();
+	const prefix = options?.prefix ?? "default";
+	const r2Adapter = adaptToJustBash(new WorkspaceFileSystem(new Workspace({
+		sql: storage.sql,
+		r2: bucket,
+		name: () => prefix
+	})));
+	const { Bash, MountableFs, InMemoryFs } = await import(
+		/* @vite-ignore */
+		"just-bash"
+);
+	const fs = new MountableFs({ base: new InMemoryFs() });
+	fs.mount("/workspace", r2Adapter);
+	return () => new Bash({
+		fs,
+		cwd: "/workspace",
+		network: { dangerouslyAllowFullInternetAccess: true }
+	});
+}
+
+//#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. */
+async function cfSandboxToSessionEnv(sandbox, cwd = "/workspace") {
+	return createSandboxSessionEnv({
+		async readFile(path) {
+			return (await sandbox.readFile(path)).content;
+		},
+		async readFileBuffer(path) {
+			const file = await sandbox.readFile(path, { encoding: "base64" });
+			const binary = atob(file.content);
+			const bytes = new Uint8Array(binary.length);
+			for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+			return bytes;
+		},
+		async writeFile(path, content) {
+			if (typeof content === "string") await sandbox.writeFile(path, content);
+			else {
+				let binary = "";
+				for (let i = 0; i < content.length; i++) binary += String.fromCharCode(content[i]);
+				const b64 = btoa(binary);
+				await sandbox.writeFile(path, b64, { encoding: "base64" });
+			}
+		},
+		async stat(path) {
+			const result = await sandbox.exec(`stat -c '{"size":%s,"isDir":%F}' '${path.replace(/'/g, "'\\''")}'`);
+			if (!result.success) throw new Error(`stat failed for ${path}: ${result.stderr}`);
+			try {
+				const raw = result.stdout.trim();
+				const sizeMatch = raw.match(/"size":(\d+)/);
+				const isDir = raw.includes("directory");
+				return {
+					isFile: !isDir,
+					isDirectory: isDir,
+					isSymbolicLink: false,
+					size: sizeMatch ? parseInt(sizeMatch[1], 10) : 0,
+					mtime: /* @__PURE__ */ new Date()
+				};
+			} catch {
+				throw new Error(`Failed to parse stat output for ${path}: ${result.stdout}`);
+			}
+		},
+		async readdir(path) {
+			const result = await sandbox.exec(`ls -1 '${path.replace(/'/g, "'\\''")}'`);
+			if (!result.success) throw new Error(`readdir failed for ${path}: ${result.stderr}`);
+			return result.stdout.trim().split("\n").filter((s) => s.length > 0);
+		},
+		async exists(path) {
+			return (await sandbox.exists(path)).exists;
+		},
+		async mkdir(path, opts) {
+			await sandbox.mkdir(path, opts);
+		},
+		async rm(path, opts) {
+			if (opts?.recursive || opts?.force) {
+				const flags = [opts.recursive ? "-r" : "", opts.force ? "-f" : ""].filter(Boolean).join("");
+				await sandbox.exec(`rm ${flags} '${path.replace(/'/g, "'\\''")}'`);
+			} else await sandbox.deleteFile(path);
+		},
+		async exec(command, execOpts) {
+			const result = await sandbox.exec(command, {
+				cwd: execOpts?.cwd,
+				env: execOpts?.env
+			});
+			return {
+				stdout: result.stdout ?? "",
+				stderr: result.stderr ?? "",
+				exitCode: result.exitCode ?? (result.success ? 0 : 1)
+			};
+		}
+	}, cwd);
+}
+
+//#endregion
+//#region src/cloudflare/session-store.ts
+function store() {
+	return {
+		async save(id, data) {
+			const { agentInstance } = getCloudflareContext();
+			const sessions = { ...agentInstance.state?.sessions ?? {} };
+			sessions[id] = data;
+			agentInstance.setState({
+				...agentInstance.state,
+				sessions
+			});
+		},
+		async load(id) {
+			const { agentInstance } = getCloudflareContext();
+			return agentInstance.state?.sessions?.[id] ?? null;
+		},
+		async delete(id) {
+			const { agentInstance } = getCloudflareContext();
+			const sessions = { ...agentInstance.state?.sessions ?? {} };
+			delete sessions[id];
+			agentInstance.setState({
+				...agentInstance.state,
+				sessions
+			});
+		}
+	};
+}
+
+//#endregion
+export { cfSandboxToSessionEnv, defineCommand, getCloudflareContext, getVirtualSandbox, runWithCloudflareContext, store };

package/dist/command-helpers-DdAfbnom.d.mts

@@ -0,0 +1,21 @@
+import { D as ShellResult } from "./types-T8pE1xIS.mjs";
+
+//#region src/command-helpers.d.ts
+/**
+ * Loose return shape accepted from user-supplied command executors. All forms
+ * are normalized to a full `ShellResult` by `normalizeExecutor()`.
+ */
+type CommandExecutorResult = ShellResult | {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+} | string | void;
+/**
+ * User-supplied command executor. Can return a full `ShellResult`, a partial
+ * `{ stdout?, stderr?, exitCode? }` object, a bare string (treated as stdout),
+ * or void (empty success). Thrown errors are caught and converted to an
+ * `exitCode`-bearing `ShellResult` — no `try`/`catch` needed at the call site.
+ */
+type CommandExecutor = (args: string[]) => Promise<CommandExecutorResult>;
+//#endregion
+export { CommandExecutor as t };

package/dist/command-helpers-hTZKWK13.mjs

@@ -0,0 +1,37 @@
+//#region src/command-helpers.ts
+/**
+* Wrap a user-supplied `CommandExecutor` to always resolve with a full
+* `ShellResult`. Applies loose-return normalization and catches throws.
+*/
+function normalizeExecutor(executor) {
+	return async (args) => {
+		try {
+			const raw = await executor(args);
+			if (raw === void 0 || raw === null) return {
+				stdout: "",
+				stderr: "",
+				exitCode: 0
+			};
+			if (typeof raw === "string") return {
+				stdout: raw,
+				stderr: "",
+				exitCode: 0
+			};
+			return {
+				stdout: raw.stdout ?? "",
+				stderr: raw.stderr ?? "",
+				exitCode: raw.exitCode ?? 0
+			};
+		} catch (err) {
+			const e = err ?? {};
+			return {
+				stdout: typeof e.stdout === "string" ? e.stdout : "",
+				stderr: typeof e.stderr === "string" ? e.stderr : String(err),
+				exitCode: typeof e.code === "number" ? e.code : 1
+			};
+		}
+	};
+}
+
+//#endregion
+export { normalizeExecutor as t };

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, O as Skill, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, b as Role, c as BuildPlugin, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, n as AgentInfo, o as BuildContext, p as FlueContext, r as AgentInit, s as BuildOptions, t as AgentConfig, u as CommandDef, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-T8pE1xIS.mjs";
+import { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
+
+//#region src/build.d.ts
+/**
+ * Result returned by {@link build}. `changed` indicates whether any file in
+ * `dist/` was actually modified. Callers (notably the dev server) use this to
+ * skip restarting downstream processes for no-op rebuilds on agent body edits.
+ */
+interface BuildResult {
+  changed: boolean;
+}
+/**
+ * Build a workspace into a deployable artifact.
+ *
+ * `options.workspaceDir` is treated as an explicit workspace root — the directory
+ * directly containing agents/ and roles/. No .flue/ waterfall is performed here;
+ * callers that want waterfall behavior (e.g. the CLI when --workspace is omitted)
+ * should use `resolveWorkspaceFromCwd` first.
+ *
+ * AGENTS.md and .agents/skills/ are NOT bundled — discovered at runtime from session cwd.
+ */
+declare function build(options: BuildOptions): Promise<BuildResult>;
+/**
+ * Resolve a Flue workspace directory from the current working directory,
+ * using the two-layout convention. Intended for the CLI when `--workspace` is
+ * not provided — callers that pass an explicit workspace path should skip this
+ * and pass the path straight to `build()`.
+ *
+ * Two supported layouts, checked in order:
+ *   1. `<cwd>/.flue/` — use this when Flue is embedded in an existing project.
+ *   2. `<cwd>/` — use this when the project itself is the Flue workspace.
+ *
+ * If `.flue/` exists, it wins unconditionally — no mixing with the bare layout.
+ * Returns null if neither is present so the caller can produce a helpful error.
+ */
+declare function resolveWorkspaceFromCwd(cwd: string): string | null;
+//#endregion
+//#region src/dev.d.ts
+interface DevOptions {
+  workspaceDir: string;
+  outputDir: string;
+  target: 'node' | 'cloudflare';
+  /** Defaults to 3583 ("FLUE" on a phone keypad). */
+  port?: number;
+}
+/** Default port for `flue dev`. F=3, L=5, U=8, E=3 on a phone keypad. */
+declare const DEFAULT_DEV_PORT = 3583;
+/**
+ * Start a Flue dev server. Resolves only when the server is shut down (e.g.
+ * via SIGINT). Errors during the initial build/start are thrown synchronously;
+ * errors during subsequent rebuilds are logged but do NOT exit the dev server
+ * — the user is editing code, after all, and we want to recover when they fix it.
+ */
+declare function dev(options: DevOptions): Promise<void>;
+//#endregion
+//#region src/agent.d.ts
+declare const BUILTIN_TOOL_NAMES: Set<string>;
+interface TaskToolParams {
+  prompt: string;
+  description?: string;
+  role?: string;
+  cwd?: string;
+}
+interface TaskToolResultDetails {
+  taskId: string;
+  sessionId: string;
+  messageId?: string;
+  role?: string;
+  cwd?: string;
+}
+interface CreateToolsOptions {
+  task?: (params: TaskToolParams, signal?: AbortSignal) => Promise<AgentToolResult<TaskToolResultDetails>>;
+  roles?: Record<string, Role>;
+}
+declare function createTools(env: SessionEnv, options?: CreateToolsOptions): AgentTool<any>[];
+//#endregion
+export { type AgentConfig, type AgentInfo, type AgentInit, BUILTIN_TOOL_NAMES, type BashFactory, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, DEFAULT_DEV_PORT, type DevOptions, type FileStat, type FlueAgent, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, build, createTools, dev, resolveWorkspaceFromCwd };