@flue/sdk 0.1.2 → 0.1.3

package/README.md

@@ -94,9 +94,8 @@ A triage agent that runs in CI whenever an issue is opened on GitHub. The `"loca
 
 ```ts
 // .flue/agents/triage.ts
-import { defineCommand, type FlueContext } from '@flue/sdk/client';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { type FlueContext } from '@flue/sdk/client';
+import { defineCommand } from '@flue/sdk/node';
 import * as v from 'valibot';
 
 // Because we are running this in CI, we don't need to expose this as an HTTP endpoint.
@@ -106,12 +105,8 @@ export const triggers = {};
 // Connect privileged CLIs to your agent without leaking sensitive keys and secrets.
 // Secrets are hooked up inside the command definition here, so your agent never sees them.
 // Commands are controlled per-prompt, so you can be as granular with access as you need.
-const npm = defineCommand('npm', async (args) => promisify(execFile)('npm', args));
-const gh = defineCommand('gh', async (args) =>
-  promisify(execFile)('gh', args, {
-    env: { GH_TOKEN: process.env.GH_TOKEN },
-  }),
-);
+const npm = defineCommand('npm');
+const gh = defineCommand('gh', { env: { GH_TOKEN: process.env.GH_TOKEN } });
 
 export default async function ({ init, payload }: FlueContext) {
   // 'local' mounts the host filesystem at /workspace — ideal for CI

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C8tsaK1j.mjs";
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-BZPltYah.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts
@@ -21,10 +21,5 @@ interface FlueContextInternal extends FlueContext {
   setEventCallback(callback: FlueEventCallback | undefined): void;
 }
 declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
-declare function defineCommand(name: string, execute: (args: string[]) => Promise<{
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}>): Command;
 //#endregion
-export { type BashLike, type Command, type CommandSupport, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, Type, createFlueContext, defineCommand };
+export { type BashLike, type Command, type CommandSupport, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, Type, createFlueContext };

package/dist/client.mjs

@@ -1,5 +1,5 @@
 import { r as discoverSessionContext } from "./agent-BYG0nVbQ.mjs";
-import { n as Session } from "./session-BRLCNVG1.mjs";
+import { n as Session } from "./session-CiAMTsLZ.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
@@ -32,7 +32,7 @@ function createFlueContext(config) {
 				skills: localContext.skills,
 				model: sessionModel
 			};
-			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback);
+			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback, options?.commands);
 		},
 		setEventCallback(callback) {
 			currentEventCallback = callback;
@@ -54,12 +54,6 @@ async function resolveSessionEnv(sessionId, sandbox, config) {
 	}
 	return sandbox.createSessionEnv({ sessionId });
 }
-function defineCommand(name, execute) {
-	return {
-		name,
-		execute
-	};
-}
 
 //#endregion
-export { Type, createFlueContext, defineCommand };
+export { Type, createFlueContext };

package/dist/cloudflare/index.d.mts

@@ -1,4 +1,5 @@
-import { S as SessionStore, b as SessionEnv } from "../types-C8tsaK1j.mjs";
+import { S as SessionStore, b as SessionEnv, s as Command } from "../types-BZPltYah.mjs";
+import { t as CommandExecutor } from "../command-helpers-BPcSV93o.mjs";
 
 //#region src/cloudflare/virtual-sandbox.d.ts
 interface VirtualSandboxOptions {
@@ -8,6 +9,9 @@ interface VirtualSandboxOptions {
 declare function getVirtualSandbox(): Promise<any>;
 declare function getVirtualSandbox(bucket: unknown, options?: VirtualSandboxOptions): Promise<any>;
 //#endregion
+//#region src/cloudflare/define-command.d.ts
+declare function defineCommand(name: string, execute: CommandExecutor): Command;
+//#endregion
 //#region src/cloudflare/cf-sandbox.d.ts
 declare function cfSandboxToSessionEnv(sandbox: any, cwd?: string): Promise<SessionEnv>;
 //#endregion
@@ -33,4 +37,4 @@ declare function setCloudflareContext(ctx: CloudflareContext): void;
 declare function getCloudflareContext(): CloudflareContext;
 declare function clearCloudflareContext(): void;
 //#endregion
-export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, clearCloudflareContext, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };
+export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, clearCloudflareContext, defineCommand, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };

package/dist/cloudflare/index.mjs

@@ -1,6 +1,7 @@
 import "../agent-BYG0nVbQ.mjs";
-import "../session-BRLCNVG1.mjs";
+import "../session-CiAMTsLZ.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
+import { t as normalizeExecutor } from "../command-helpers-CxRhK1my.mjs";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
 
 //#region src/cloudflare/context.ts
@@ -105,6 +106,28 @@ 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. */
@@ -204,4 +227,4 @@ function store() {
 }
 
 //#endregion
-export { cfSandboxToSessionEnv, clearCloudflareContext, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };
+export { cfSandboxToSessionEnv, clearCloudflareContext, defineCommand, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };

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

@@ -0,0 +1,21 @@
+import { w as ShellResult } from "./types-BZPltYah.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-CxRhK1my.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

@@ -1,4 +1,4 @@
-import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, T as Skill, _ as Role, a as BuildOptions, b as SessionEnv, c as CommandDef, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, i as BuildContext, l as CommandSupport, m as FlueSession, n as AgentInfo, o as BuildPlugin, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C8tsaK1j.mjs";
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, T as Skill, _ as Role, a as BuildOptions, b as SessionEnv, c as CommandDef, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, i as BuildContext, l as CommandSupport, m as FlueSession, n as AgentInfo, o as BuildPlugin, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-BZPltYah.mjs";
 import { AgentTool } from "@mariozechner/pi-agent-core";
 
 //#region src/build.d.ts

package/dist/internal.d.mts

@@ -1,4 +1,4 @@
-import { S as SessionStore, y as SessionData } from "./types-C8tsaK1j.mjs";
+import { S as SessionStore, y as SessionData } from "./types-BZPltYah.mjs";
 import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import "valibot";

package/dist/internal.mjs

@@ -1,5 +1,5 @@
 import "./agent-BYG0nVbQ.mjs";
-import { t as InMemorySessionStore } from "./session-BRLCNVG1.mjs";
+import { t as InMemorySessionStore } from "./session-CiAMTsLZ.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import { createFlueContext } from "./client.mjs";
 

package/dist/node/index.d.mts

@@ -0,0 +1,14 @@
+import { s as Command } from "../types-BZPltYah.mjs";
+import { t as CommandExecutor } from "../command-helpers-BPcSV93o.mjs";
+import { execFile } from "node:child_process";
+
+//#region src/node/define-command.d.ts
+/**
+ * Options forwarded directly to Node's `child_process.execFile`. Full pass-through.
+ */
+type CommandOptions = NonNullable<Parameters<typeof execFile>[2]>;
+declare function defineCommand(name: string): Command;
+declare function defineCommand(name: string, options: CommandOptions): Command;
+declare function defineCommand(name: string, execute: CommandExecutor): Command;
+//#endregion
+export { type CommandOptions, defineCommand };

package/dist/node/index.mjs

@@ -0,0 +1,75 @@
+import { t as normalizeExecutor } from "../command-helpers-CxRhK1my.mjs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+//#region src/node/define-command.ts
+/**
+* Node-specific `defineCommand`. Supports three forms:
+*
+* ```ts
+* defineCommand('agent-browser');
+* defineCommand('gh', { env: { GH_TOKEN: process.env.GH_TOKEN } });
+* defineCommand('gh', async (args) => ({ stdout: '...' }));
+* ```
+*
+* Forms A and B shell out via `child_process.execFile`. Form C lets the user
+* implement the command however they like. All three forms benefit from
+* return-shape normalization and throw-catching — no `try`/`catch` or
+* `return { stdout, stderr, exitCode: 0 }` boilerplate required.
+*/
+const execFileAsync = promisify(execFile);
+/**
+* Essential, non-sensitive environment variables automatically forwarded to
+* pass-through commands (forms A and B). Users can override any of these —
+* or add their own (e.g. `GH_TOKEN`) — via `options.env`. Anything not listed
+* here (API keys, tokens, secrets, etc.) stays on the host and is NEVER
+* exposed to the spawned process unless the caller opts in explicitly.
+*
+* If you need full control over the env, use the function form:
+* `defineCommand('gh', async (args) => { ... })`.
+*/
+const DEFAULT_ENV = {
+	PATH: process.env.PATH,
+	HOME: process.env.HOME,
+	USER: process.env.USER,
+	LOGNAME: process.env.LOGNAME,
+	HOSTNAME: process.env.HOSTNAME,
+	SHELL: process.env.SHELL,
+	LANG: process.env.LANG,
+	LC_ALL: process.env.LC_ALL,
+	LC_CTYPE: process.env.LC_CTYPE,
+	TZ: process.env.TZ,
+	TERM: process.env.TERM,
+	TMPDIR: process.env.TMPDIR,
+	TMP: process.env.TMP,
+	TEMP: process.env.TEMP
+};
+function defineCommand(name, arg) {
+	if (typeof arg === "function") return {
+		name,
+		execute: normalizeExecutor(arg)
+	};
+	const userOpts = arg ?? {};
+	const mergedOpts = {
+		maxBuffer: 50 * 1024 * 1024,
+		...userOpts,
+		env: {
+			...DEFAULT_ENV,
+			...userOpts.env ?? {}
+		}
+	};
+	const executor = async (args) => {
+		const { stdout, stderr } = await execFileAsync(name, args, mergedOpts);
+		return {
+			stdout: String(stdout ?? ""),
+			stderr: String(stderr ?? "")
+		};
+	};
+	return {
+		name,
+		execute: normalizeExecutor(executor)
+	};
+}
+
+//#endregion
+export { defineCommand };

package/dist/sandbox.d.mts

@@ -1,4 +1,4 @@
-import { b as SessionEnv, c as CommandDef, r as BashLike, u as FileStat, v as SandboxFactory, w as ShellResult } from "./types-C8tsaK1j.mjs";
+import { b as SessionEnv, c as CommandDef, r as BashLike, u as FileStat, v as SandboxFactory, w as ShellResult } from "./types-BZPltYah.mjs";
 
 //#region src/sandbox.d.ts
 declare function bashToSessionEnv(bash: BashLike): SessionEnv;

package/dist/sandbox.mjs

@@ -1,5 +1,5 @@
 import "./agent-BYG0nVbQ.mjs";
-import { r as normalizePath } from "./session-BRLCNVG1.mjs";
+import { r as normalizePath } from "./session-CiAMTsLZ.mjs";
 
 //#region src/sandbox.ts
 function bashToSessionEnv(bash) {

package/dist/{session-BRLCNVG1.mjs → session-CiAMTsLZ.mjs}

@@ -508,11 +508,13 @@ var Session = class Session {
 	compactionAbortController;
 	eventCallback;
 	builtinTools;
-	constructor(id, config, env, store, existingData, onAgentEvent) {
+	sessionCommands;
+	constructor(id, config, env, store, existingData, onAgentEvent, sessionCommands) {
 		this.id = id;
 		this.config = config;
 		this.env = env;
 		this.store = store;
+		this.sessionCommands = sessionCommands ?? [];
 		this.metadata = existingData?.metadata ?? {};
 		this.createdAt = existingData?.createdAt;
 		this.lastCompaction = existingData?.lastCompaction;
@@ -586,8 +588,9 @@ var Session = class Session {
 		const promptWithRole = this.injectRoleInstructions(text, options?.role);
 		const schema = options?.result;
 		const fullPrompt = buildPromptText(promptWithRole, schema);
-		if (options?.commands) this.assertCommandSupport(options.commands);
-		const registeredCommandNames = options?.commands ? this.registerCommands(options.commands) : [];
+		const effectiveCommands = this.mergeCommands(options?.commands);
+		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
+		const registeredCommandNames = this.registerCommands(effectiveCommands);
 		const registeredToolNames = options?.tools ? this.registerCustomTools(options.tools) : [];
 		try {
 			await this.agent.prompt(fullPrompt);
@@ -616,8 +619,9 @@ var Session = class Session {
 		const schema = options?.result;
 		const skillPrompt = buildSkillPrompt(registeredSkill.instructions, options?.args, schema);
 		const promptWithRole = this.injectRoleInstructions(skillPrompt, options?.role);
-		if (options?.commands) this.assertCommandSupport(options.commands);
-		const registeredCommandNames = options?.commands ? this.registerCommands(options.commands) : [];
+		const effectiveCommands = this.mergeCommands(options?.commands);
+		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
+		const registeredCommandNames = this.registerCommands(effectiveCommands);
 		const registeredToolNames = options?.tools ? this.registerCustomTools(options.tools) : [];
 		try {
 			await this.agent.prompt(promptWithRole);
@@ -632,8 +636,9 @@ var Session = class Session {
 		}
 	}
 	async shell(command, options) {
-		if (options?.commands) this.assertCommandSupport(options.commands);
-		const registeredNames = options?.commands ? this.registerCommands(options.commands) : [];
+		const effectiveCommands = this.mergeCommands(options?.commands);
+		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
+		const registeredNames = this.registerCommands(effectiveCommands);
 		try {
 			const result = await this.env.exec(command, {
 				env: options?.env,
@@ -750,6 +755,19 @@ var Session = class Session {
 		if (commands.length === 0) return;
 		if (!this.env.commandSupport) throw new Error("[flue] Cannot use commands: this environment does not support command registration. Commands are only available in isolate sandbox mode. Remote sandboxes handle command execution at the platform level.");
 	}
+	/**
+	* Merge session-wide `commands` (from init()) with per-call commands. When
+	* both define a command with the same name, the per-call entry wins for
+	* that call.
+	*/
+	mergeCommands(perCall) {
+		if (!perCall || perCall.length === 0) return this.sessionCommands;
+		if (this.sessionCommands.length === 0) return perCall;
+		const byName = /* @__PURE__ */ new Map();
+		for (const cmd of this.sessionCommands) byName.set(cmd.name, cmd);
+		for (const cmd of perCall) byName.set(cmd.name, cmd);
+		return Array.from(byName.values());
+	}
 	registerCommands(commands) {
 		if (!this.env.commandSupport || commands.length === 0) return [];
 		const names = [];

package/dist/{types-C8tsaK1j.d.mts → types-BZPltYah.d.mts}

@@ -146,6 +146,13 @@ interface SessionInit {
    * Precedence (highest wins): per-call `model` > role `model` > session `model` > build-time default.
    */
   model?: string;
+  /**
+   * Session-wide commands. Every prompt(), skill(), and shell() call inherits
+   * this list. Per-call `commands` are merged on top — if a per-call command
+   * shares a name with a session command, the per-call version wins for that
+   * call.
+   */
+  commands?: Command[];
 }
 interface FlueSession {
   prompt<S extends v.GenericSchema>(text: string, options: PromptOptions<S> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -23,6 +23,10 @@
     "./cloudflare": {
       "types": "./dist/cloudflare/index.d.mts",
       "import": "./dist/cloudflare/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.mts",
+      "import": "./dist/node/index.mjs"
     }
   },
   "main": "./dist/index.mjs",