@flue/sdk 0.3.4 → 0.3.6

package/dist/internal.mjs

@@ -1,10 +1,426 @@
-import "./agent-BB4lwAd5.mjs";
-import { t as InMemorySessionStore } from "./session-DukL3zwF.mjs";
+import "./agent-BTB0809P.mjs";
+import { t as InMemorySessionStore } from "./session-BaaSQTWS.mjs";
 import { bashFactoryToSessionEnv } from "./sandbox.mjs";
-import "./mcp-DOgMtp8y.mjs";
+import "./mcp-DTFRe9vh.mjs";
 import { createFlueContext } from "./client.mjs";
 import { getModel } from "@mariozechner/pi-ai";
 
+//#region src/errors.ts
+/**
+* Concrete error classes thrown by Flue.
+*
+* This file is the *vocabulary* of errors in Flue. Every error the framework
+* throws has a class here. The framework scaffolding (base class, renderers,
+* type guards, request-parsing helpers) lives in `error-utils.ts`.
+*
+* ──── Why this file exists ────────────────────────────────────────────────
+*
+* Concentrating every error in one file is deliberate. When all errors are
+* visible together, it's easy to:
+*
+*   - Keep message tone and detail level consistent across the codebase.
+*   - Notice duplicates ("oh, we already have an error for this case").
+*   - Establish norms by example — when adding a new error, look at the
+*     neighbors above and copy the pattern.
+*
+* Application code throughout the codebase should reach for one of these
+* classes rather than constructing a `FlueError` ad hoc. If no existing class
+* fits, add one here. That's the entire convention.
+*
+* ──── Two audiences: caller vs. developer ─────────────────────────────────
+*
+* The reader of an error message is one of two distinct audiences:
+*
+*   - The *caller*: an HTTP client. Possibly third-party, possibly hostile,
+*     possibly an end user who shouldn't even know we're built on Flue.
+*     Sees `message` and `details` always.
+*
+*   - The *developer*: the human running the service (`flue dev`, `flue run`,
+*     local debugging). Sees `dev` in addition, but only when the server is
+*     running in local/dev mode (gated by `FLUE_MODE=local`).
+*
+* Every error class must classify its prose by audience. The required-but-
+* possibly-empty shape of both `details` and `dev` is the discipline:
+* forgetting either field is a TypeScript error, and writing `''` is a
+* deliberate "I have nothing for that audience" decision.
+*
+* Concretely:
+*
+*   - `message`     One sentence. Caller-safe. Always rendered.
+*   - `details`     Longer caller-safe prose. About the request itself, the
+*                   contract, what the caller can do to fix it. Always
+*                   rendered. NEVER includes:
+*                     - sibling/neighbor enumeration (leaks namespace)
+*                     - filesystem paths or "agents/" / "skills/" / etc.
+*                       (leaks framework internals)
+*                     - source-code-level fix instructions ("add ... to your
+*                       agent definition") (caller can't act on these)
+*                     - build-time or runtime mechanics
+*   - `dev`         Longer dev-audience prose. Available alternatives,
+*                   filesystem layout, framework guidance, source-code-level
+*                   fix instructions. Rendered ONLY when FLUE_MODE=local.
+*
+* When in doubt, put information in `dev`. The default is conservative.
+*
+* ──── Conventions for new error classes ───────────────────────────────────
+*
+*   - Class name: PascalCase, suffixed with `Error`. E.g. `AgentNotFoundError`.
+*   - The class owns its `type` constant (snake_case). Set once in the
+*     subclass constructor, never passed by callers. Renaming the wire type
+*     is then a one-line change.
+*   - Constructor takes ONLY structured input data (the values used to build
+*     the message). The constructor assembles `message`, `details`, and
+*     `dev` from that data, so call sites never reinvent phrasing.
+*   - `details` and `dev` are both required strings. Pass `''` only when
+*     there's genuinely nothing more to say for that audience.
+*   - For HTTP errors, the class sets its own `status` (and `headers` where
+*     relevant). Callers do not pick HTTP status codes ad-hoc.
+*
+* Worked example (matches `AgentNotFoundError` below):
+*
+*     new AgentNotFoundError({ name, available });
+*     // builds:
+*     //   message: `Agent "foo" is not registered.`
+*     //   details: `Verify the agent name is correct.`
+*     //   dev:     `Available agents: "echo", "greeter". Agents are
+*     //            loaded from the workspace's "agents/" directory at
+*     //            build time. ...`
+*
+* The wire response in production omits `dev`; in `flue dev` / `flue run`
+* it includes `dev`. That separation is what lets the dev field be richly
+* helpful without leaking namespace state to public callers.
+*
+* Counter-example to avoid:
+*
+*     class AgentNotFoundError extends FlueHttpError {
+*       constructor(message: string) {                       // ✗ free-form
+*         super({                                            // ✗ wrong type
+*           type: 'agent_error',
+*           message,
+*           details: 'Available: "x", "y", "z"',             // ✗ leaks names
+*           dev: '',                                         // ✗ wasted channel
+*           status: 500,                                     // ✗ wrong status
+*         });
+*       }
+*     }
+*
+* The structured-constructor pattern below is what prevents that drift.
+*/
+/**
+* Format a list of items for inclusion in error details. Empty lists render
+* as the supplied fallback (default `(none)`), so messages read naturally
+* regardless of whether anything is registered.
+*
+* Module-private: only used by the concrete error subclasses below. Promote
+* to `export` if/when a real cross-file caller appears.
+*/
+function formatList(items, fallback = "(none)") {
+	if (items.length === 0) return fallback;
+	return items.map((item) => `"${String(item)}"`).join(", ");
+}
+/**
+* Base class for every error Flue throws. Do not instantiate directly in
+* application code — extend it via a subclass below. If a use case isn't
+* covered, add a new subclass here rather than throwing a raw `FlueError`.
+*/
+var FlueError = class extends Error {
+	type;
+	details;
+	dev;
+	meta;
+	cause;
+	constructor(options) {
+		super(options.message);
+		this.name = "FlueError";
+		this.type = options.type;
+		this.details = options.details;
+		this.dev = options.dev;
+		this.meta = options.meta;
+		this.cause = options.cause;
+	}
+};
+/**
+* Base class for HTTP-layer errors. Adds `status` and optional `headers`.
+* Subclasses set these in the `super({...})` call so the call site doesn't
+* have to think about HTTP semantics.
+*/
+var FlueHttpError = class extends FlueError {
+	status;
+	headers;
+	constructor(options) {
+		super(options);
+		this.name = "FlueHttpError";
+		this.status = options.status;
+		this.headers = options.headers;
+	}
+};
+var MethodNotAllowedError = class extends FlueHttpError {
+	constructor({ method, allowed }) {
+		super({
+			type: "method_not_allowed",
+			message: `HTTP method ${method} is not allowed on this endpoint.`,
+			details: `This endpoint accepts ${formatList(allowed)} only.`,
+			dev: "",
+			status: 405,
+			headers: { Allow: allowed.join(", ") }
+		});
+	}
+};
+var UnsupportedMediaTypeError = class extends FlueHttpError {
+	constructor({ received }) {
+		const detailLines = [];
+		if (received) detailLines.push(`Received Content-Type: "${received}".`);
+		else detailLines.push(`No Content-Type header was sent.`);
+		detailLines.push("Send the request body as JSON with the header \"Content-Type: application/json\", or omit the body entirely (and the Content-Type header) if the request doesn't have a payload.");
+		super({
+			type: "unsupported_media_type",
+			message: `Request body must be sent as application/json.`,
+			details: detailLines.join("\n"),
+			dev: "",
+			status: 415
+		});
+	}
+};
+var InvalidJsonError = class extends FlueHttpError {
+	constructor({ parseError }) {
+		super({
+			type: "invalid_json",
+			message: `Request body is not valid JSON.`,
+			details: `The JSON parser reported: ${parseError}\nVerify the body is well-formed JSON, or omit the body entirely if the request doesn't have a payload.`,
+			dev: "",
+			status: 400
+		});
+	}
+};
+var AgentNotFoundError = class extends FlueHttpError {
+	constructor({ name, available }) {
+		super({
+			type: "agent_not_found",
+			message: `Agent "${name}" is not registered.`,
+			details: `Verify the agent name is correct.`,
+			dev: `Available agents: ${formatList(available)}.\nAgents are loaded from the workspace's "agents/" directory at build time. Verify the agent file is present in the workspace being served.`,
+			status: 404
+		});
+	}
+};
+var AgentNotWebhookError = class extends FlueHttpError {
+	constructor({ name }) {
+		super({
+			type: "agent_not_webhook",
+			message: `Agent "${name}" is not web-accessible.`,
+			details: `This endpoint is not exposed over HTTP.`,
+			dev: "This agent has no webhook trigger configured. To expose it, add a webhook trigger to its definition (`triggers: { webhook: true }`). Trigger-less agents remain invokable via \"flue run\" in local mode.",
+			status: 404
+		});
+	}
+};
+var RouteNotFoundError = class extends FlueHttpError {
+	constructor({ method, path }) {
+		super({
+			type: "route_not_found",
+			message: `No route matches ${method} ${path}.`,
+			details: `Webhook agents are served at POST /agents/<name>/<id>.`,
+			dev: "",
+			status: 404
+		});
+	}
+};
+var InvalidRequestError = class extends FlueHttpError {
+	constructor({ reason }) {
+		super({
+			type: "invalid_request",
+			message: `Request is malformed.`,
+			details: reason,
+			dev: "",
+			status: 400
+		});
+	}
+};
+
+//#endregion
+//#region src/error-utils.ts
+/**
+* Error framework for Flue.
+*
+* This file holds the abstract scaffolding (renderers, helpers, request-
+* parsing utilities, type guard, logger) that supports the concrete error
+* subclasses defined in `errors.ts`. The two-file split is deliberate:
+*
+*   - `errors.ts` is the *vocabulary*: the `FlueError` base class plus every
+*     concrete subclass Flue can throw. That's the file new contributors
+*     touch when they need to add a new error.
+*
+*   - `error-utils.ts` (this file) is the *framework*: the renderers that
+*     turn errors into HTTP responses and SSE event data, the type guard,
+*     the logger, and the request-parsing utilities. This file rarely
+*     changes.
+*
+* Application code should NOT instantiate `FlueError` directly. Always reach
+* for a subclass from `errors.ts`. If no existing subclass fits, add one
+* there. This is what keeps message tone, detail level, and field naming
+* consistent across the codebase.
+*
+* Wire envelope (HTTP body + SSE `data:` payload for error events):
+*
+*     {
+*       "error": {
+*         "type":    "...",
+*         "message": "...",
+*         "details": "...",
+*         "dev":     "..."   // present only in local/dev mode AND when non-empty
+*       }
+*     }
+*
+* Field rules:
+*   - `type`, `message`, `details` are always present on the wire.
+*   - `dev` is gated by `FLUE_MODE === 'local'` (set by `flue run` and
+*     `flue dev --target node`). Even in dev mode, `dev` is omitted when
+*     the error class set it to `''` — so its presence is not a reliable
+*     signal of mode by itself; clients should not depend on it that way.
+*     See `errors.ts` for the two-audience rationale.
+*   - `meta` is included on the wire only when an error subclass sets it
+*     (rare).
+*   - `cause` is never included on the wire (it's logged server-side only).
+*/
+function isFlueError(value) {
+	return value instanceof FlueError;
+}
+/**
+* Structured error logger. Used by the HTTP and SSE renderers below to log
+* unknown/wrapped errors before rendering a generic envelope.
+*
+* Module-private for now: when an external call site appears we can promote
+* to `export` and decide the right shape for `warn`/`info` (FlueError
+* subclasses with severity? plain strings? structured data?) — rather than
+* committing to a shape now without any usage to validate it.
+*/
+function formatForLog(prefix, err) {
+	if (isFlueError(err)) {
+		const lines = [`${prefix} [${err.type}] ${err.message}`];
+		if (err.details) for (const line of err.details.split("\n")) lines.push(`  ${line}`);
+		if (err.dev) for (const line of err.dev.split("\n")) lines.push(`  ${line}`);
+		if (err.cause !== void 0) lines.push(`  cause: ${err.cause instanceof Error ? err.cause.stack ?? err.cause.message : String(err.cause)}`);
+		return lines.join("\n");
+	}
+	if (err instanceof Error) return `${prefix} ${err.stack ?? err.message}`;
+	return `${prefix} ${String(err)}`;
+}
+const flueLog = { error(err) {
+	console.error(formatForLog("[flue]", err));
+} };
+/**
+* Detect whether the server is running in local/dev mode. Gates whether the
+* `dev` field is included on the wire — see the convention doc in `errors.ts`.
+*
+* Currently keyed off the `FLUE_MODE=local` env var, which is set by
+* `flue run` and `flue dev --target node`. On Cloudflare workers there is
+* no global `process` and no current "local mode" plumbing for the worker —
+* so deployed CF and `flue dev --target cloudflare` both currently render
+* the prod envelope. Threading a dev-mode signal through to the worker
+* fetch handler is left as a follow-up.
+*/
+function isDevMode() {
+	return typeof process !== "undefined" && process.env?.FLUE_MODE === "local";
+}
+function envelope(err) {
+	const out = { error: {
+		type: err.type,
+		message: err.message,
+		details: err.details
+	} };
+	if (isDevMode() && err.dev) out.error.dev = err.dev;
+	if (err.meta) out.error.meta = err.meta;
+	return out;
+}
+const GENERIC_INTERNAL = { error: {
+	type: "internal_error",
+	message: "An internal error occurred.",
+	details: "The server encountered an unexpected error while handling this request."
+} };
+/**
+* Render any thrown value into a `Response` with the canonical Flue error
+* envelope. Unknown / non-Flue errors are logged in full and rendered as a
+* generic 500 with no message leaked.
+*/
+function toHttpResponse(err) {
+	if (isFlueError(err)) {
+		const isHttp = err instanceof FlueHttpError;
+		const status = isHttp ? err.status : 500;
+		const headers = { "content-type": "application/json" };
+		if (isHttp && err.headers) Object.assign(headers, err.headers);
+		if (!isHttp) flueLog.error(err);
+		return new Response(JSON.stringify(envelope(err)), {
+			status,
+			headers
+		});
+	}
+	flueLog.error(err);
+	return new Response(JSON.stringify(GENERIC_INTERNAL), {
+		status: 500,
+		headers: { "content-type": "application/json" }
+	});
+}
+/**
+* Render any thrown value into a JSON string suitable for the `data:` line of
+* an SSE `error` event. Same envelope as `toHttpResponse`. Unknown / non-Flue
+* errors are logged and replaced with a generic envelope.
+*/
+function toSseData(err) {
+	if (isFlueError(err)) {
+		if (!(err instanceof FlueHttpError)) flueLog.error(err);
+		return JSON.stringify({
+			type: "error",
+			...envelope(err)
+		});
+	}
+	flueLog.error(err);
+	return JSON.stringify({
+		type: "error",
+		...GENERIC_INTERNAL
+	});
+}
+/**
+* Parse a request body as JSON. Returns `{}` for genuinely empty bodies
+* (Content-Length: 0 or missing) so that webhook agents which don't accept
+* a payload can be invoked without one.
+*
+* Throws `UnsupportedMediaTypeError` if a body is present without
+* `application/json` content-type, and `InvalidJsonError` if the body is
+* present but unparseable.
+*/
+async function parseJsonBody(request) {
+	const contentLengthHeader = request.headers.get("content-length");
+	const contentLength = contentLengthHeader === null ? null : Number(contentLengthHeader);
+	const contentType = request.headers.get("content-type");
+	if (contentLength === 0 || contentLengthHeader === null && contentType === null) return {};
+	if (!contentType || !contentType.toLowerCase().includes("application/json")) throw new UnsupportedMediaTypeError({ received: contentType });
+	let text;
+	try {
+		text = await request.text();
+	} catch (err) {
+		throw new InvalidJsonError({ parseError: err instanceof Error ? err.message : String(err) });
+	}
+	if (text.trim() === "") return {};
+	try {
+		return JSON.parse(text);
+	} catch (err) {
+		throw new InvalidJsonError({ parseError: err instanceof Error ? err.message : String(err) });
+	}
+}
+function validateAgentRequest(opts) {
+	if (opts.method !== "POST") throw new MethodNotAllowedError({
+		method: opts.method,
+		allowed: ["POST"]
+	});
+	if (opts.name.trim() === "" || opts.id.trim() === "") throw new InvalidRequestError({ reason: "Webhook URLs must have the shape /agents/<name>/<id> with non-empty segments." });
+	if (!opts.registeredAgents.includes(opts.name)) throw new AgentNotFoundError({
+		name: opts.name,
+		available: opts.registeredAgents
+	});
+	if (!opts.allowNonWebhook && !opts.webhookAgents.includes(opts.name)) throw new AgentNotWebhookError({ name: opts.name });
+}
+
+//#endregion
 //#region src/internal.ts
 /**
 * Internal runtime helpers consumed by the generated server entry point.
@@ -36,4 +452,4 @@ function resolveModel(modelString) {
 }
 
 //#endregion
-export { InMemorySessionStore, bashFactoryToSessionEnv, createFlueContext, resolveModel };
+export { AgentNotFoundError, InMemorySessionStore, InvalidRequestError, MethodNotAllowedError, RouteNotFoundError, bashFactoryToSessionEnv, createFlueContext, parseJsonBody, resolveModel, toHttpResponse, toSseData, validateAgentRequest };

package/dist/{mcp-DOgMtp8y.mjs → mcp-DTFRe9vh.mjs}

@@ -1,5 +1,5 @@
-import { r as discoverSessionContext } from "./agent-BB4lwAd5.mjs";
-import { a as assertRoleExists, n as Session, o as createScopedEnv, r as deleteSessionTree, s as mergeCommands } from "./session-DukL3zwF.mjs";
+import { r as discoverSessionContext } from "./agent-BTB0809P.mjs";
+import { a as assertRoleExists, n as Session, o as createScopedEnv, r as deleteSessionTree, s as mergeCommands } from "./session-BaaSQTWS.mjs";
 import { createCwdSessionEnv } from "./sandbox.mjs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -31,7 +31,8 @@ var AgentClient = class {
 		const effectiveCommands = mergeCommands(this.agentCommands, options?.commands);
 		const result = await (await createScopedEnv(this.env, effectiveCommands)).exec(command, {
 			env: options?.env,
-			cwd: options?.cwd
+			cwd: options?.cwd,
+			timeout: options?.timeout
 		});
 		return {
 			stdout: result.stdout,

package/dist/{mcp-BVF-sOBZ.d.mts → mcp-EZy-Vb5M.d.mts}

@@ -1,4 +1,4 @@
-import { j as ToolDef } from "./types-T8pE1xIS.mjs";
+import { j as ToolDef } from "./types-CItTrBsU.mjs";
 
 //#region src/mcp.d.ts
 type McpTransport = 'streamable-http' | 'sse';

package/dist/node/index.d.mts

@@ -1,5 +1,5 @@
-import { l as Command } from "../types-T8pE1xIS.mjs";
-import { t as CommandExecutor } from "../command-helpers-DdAfbnom.mjs";
+import { l as Command } from "../types-CItTrBsU.mjs";
+import { t as CommandExecutor } from "../command-helpers-CXzopT_-.mjs";
 import { execFile } from "node:child_process";
 
 //#region src/node/define-command.d.ts

package/dist/sandbox.d.mts

@@ -1,4 +1,4 @@
-import { C as SessionEnv, D as ShellResult, d as FileStat, i as BashFactory, u as CommandDef, x as SandboxFactory } from "./types-T8pE1xIS.mjs";
+import { C as SessionEnv, D as ShellResult, d as FileStat, i as BashFactory, u as CommandDef, x as SandboxFactory } from "./types-CItTrBsU.mjs";
 
 //#region src/sandbox.d.ts
 declare function createCwdSessionEnv(parentEnv: SessionEnv, cwd: string): SessionEnv;
@@ -21,6 +21,7 @@ interface SandboxApi {
   exec(command: string, options?: {
     cwd?: string;
     env?: Record<string, string>;
+    timeout?: number;
   }): Promise<ShellResult>;
 }
 /** Wrap a SandboxApi into SessionEnv. No just-bash, no intermediate filesystem layer. */

package/dist/sandbox.mjs

@@ -1,5 +1,5 @@
-import "./agent-BB4lwAd5.mjs";
-import { i as normalizePath, o as createScopedEnv } from "./session-DukL3zwF.mjs";
+import "./agent-BTB0809P.mjs";
+import { i as normalizePath, o as createScopedEnv } from "./session-BaaSQTWS.mjs";
 
 //#region src/sandbox.ts
 function createCwdSessionEnv(parentEnv, cwd) {
@@ -12,7 +12,8 @@ function createCwdSessionEnv(parentEnv, cwd) {
 	return {
 		exec: (cmd, opts) => parentEnv.exec(cmd, {
 			cwd: opts?.cwd ?? scopedCwd,
-			env: opts?.env
+			env: opts?.env,
+			timeout: opts?.timeout
 		}),
 		scope: async (options) => createCwdSessionEnv(await createScopedEnv(parentEnv, options?.commands ?? []), scopedCwd),
 		readFile: (p) => parentEnv.readFile(resolvePath(p)),
@@ -49,7 +50,31 @@ function createBashSessionEnv(bash, createScope) {
 	const cwd = bash.getCwd();
 	const resolve = (p) => p.startsWith("/") ? p : fs.resolvePath(cwd, p);
 	return {
-		exec: (cmd, opts) => bash.exec(cmd, opts),
+		exec: async (cmd, opts) => {
+			const exec = bash.exec;
+			const timeout = opts?.timeout;
+			let timeoutSignal;
+			let timer;
+			if (typeof timeout === "number") {
+				const controller = new AbortController();
+				timeoutSignal = controller.signal;
+				timer = setTimeout(() => controller.abort(), timeout * 1e3);
+			}
+			try {
+				const result = await exec.call(bash, cmd, opts ? {
+					cwd: opts.cwd,
+					env: opts.env,
+					signal: timeoutSignal
+				} : void 0);
+				if (timeoutSignal?.aborted) return {
+					...result,
+					stderr: result.stderr || `[flue] Command timed out after ${timeout} seconds.`
+				};
+				return result;
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+		},
 		scope: (options) => createScope(options?.commands ?? []),
 		readFile: (p) => fs.readFile(resolve(p)),
 		readFileBuffer: (p) => fs.readFileBuffer(resolve(p)),
@@ -93,7 +118,8 @@ function createSandboxSessionEnv(api, cwd, cleanup) {
 		async exec(command, options) {
 			return api.exec(command, {
 				cwd: options?.cwd ?? cwd,
-				env: options?.env
+				env: options?.env,
+				timeout: options?.timeout
 			});
 		},
 		async readFile(path) {

package/dist/{session-DukL3zwF.mjs → session-BaaSQTWS.mjs}

@@ -1,4 +1,4 @@
-import { i as loadSkillByPath, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-BB4lwAd5.mjs";
+import { i as loadSkillByPath, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-BTB0809P.mjs";
 import { completeSimple, isContextOverflow } from "@mariozechner/pi-ai";
 import { Agent } from "@mariozechner/pi-agent-core";
 import { toJsonSchema } from "@valibot/to-json-schema";
@@ -491,7 +491,7 @@ function assertRoleExists(roles, roleName) {
 	if (roles[roleName]) return;
 	const available = Object.keys(roles);
 	const list = available.length > 0 ? available.join(", ") : "(none defined)";
-	throw new Error(`[flue] Role "${roleName}" not registered. Available roles: ${list}. Define roles as markdown files under \`.flue/roles/\`.`);
+	throw new Error(`[flue] Role "${roleName}" not registered. Available roles: ${list}. Define roles as markdown files in \`roles/\` (or \`.flue/roles/\`).`);
 }
 function resolveEffectiveRole(options) {
 	const role = options.callRole ?? options.sessionRole ?? options.agentRole;
@@ -814,7 +814,8 @@ var Session = class {
 			}
 			if (!registeredSkill) {
 				const available = Object.keys(this.config.skills).join(", ") || "(none)";
-				throw new Error(`Skill "${name}" not registered. Available: ${available}. Skills can also be referenced by relative path under .agents/skills/ (e.g. "triage/reproduce.md").`);
+				const cwd = this.env.cwd;
+				throw new Error(`Skill "${name}" not registered. Available: ${available}.\n\nSkills are loaded at init() time from ${cwd}/.agents/skills/<name>/SKILL.md inside the session's sandbox. If you expected "${name}" to be there, make sure the file exists in your sandbox at that path before calling init() — the default empty sandbox starts with no files, so it has no skills unless you put them there.\n\nSkills can also be referenced by relative path under .agents/skills/ (e.g. "triage/reproduce.md").`);
 			}
 			const schema = options?.result;
 			const skillPrompt = buildSkillPrompt(registeredSkill.instructions, options?.args, schema);
@@ -845,7 +846,8 @@ var Session = class {
 			const effectiveCommands = mergeCommands(this.agentCommands, options?.commands);
 			const result = await (await createScopedEnv(this.env, effectiveCommands)).exec(command, {
 				env: options?.env,
-				cwd: options?.cwd
+				cwd: options?.cwd,
+				timeout: options?.timeout
 			});
 			const shellResult = {
 				stdout: result.stdout,

package/dist/{types-T8pE1xIS.d.mts → types-CItTrBsU.d.mts}

@@ -67,6 +67,7 @@ interface SessionEnv {
   exec(command: string, options?: {
     cwd?: string;
     env?: Record<string, string>;
+    timeout?: number;
   }): Promise<ShellResult>;
   /** Create an operation-scoped environment, usually backed by a fresh Bash runtime. */
   scope?(options?: {
@@ -119,12 +120,16 @@ interface AgentConfig {
   resolveModel?: (modelString: string) => Model<any>;
   compaction?: CompactionConfig;
 }
-/** Request context passed to agent handler functions. */
-interface FlueContext {
+/**
+ * Request context passed to agent handler functions. Pass type parameters
+ * to type `payload` and `env` (e.g. the `Env` interface generated by
+ * `wrangler types`). Compile-time only — no runtime validation of `payload`.
+ */
+interface FlueContext<TPayload = any, TEnv = Record<string, any>> {
   readonly id: string;
-  readonly payload: any;
+  readonly payload: TPayload;
   /** Platform env bindings (process.env on Node, Worker env on Cloudflare). */
-  readonly env: Record<string, any>;
+  readonly env: TEnv;
   /** Initialize an agent runtime with sandbox + persistence. */
   init(options?: AgentInit): Promise<FlueAgent>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {