@flue/sdk 0.3.5 → 0.3.7

package/dist/{types-T8pE1xIS.d.mts → types-CKcp6T-y.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?: {
@@ -101,6 +102,25 @@ interface CompactionConfig {
   /** Recent tokens to preserve (not summarized). Default: 20000 */
   keepRecentTokens?: number;
 }
+interface ProviderSettings {
+  /**
+   * Provider endpoint used by built-in models. Useful for API gateways,
+   * LiteLLM-style proxies, or enterprise-managed provider endpoints.
+   */
+  baseUrl?: string;
+  /**
+   * Headers merged into the resolved model's provider-level headers. Values
+   * here override headers already defined by the built-in model.
+   */
+  headers?: Record<string, string>;
+  /**
+   * API key returned to the underlying agent runtime for this provider.
+   * Useful when the gateway requires a dummy key or when credentials should
+   * come from the agent's runtime env instead of process-global env vars.
+   */
+  apiKey?: string;
+}
+type ProvidersConfig = Record<string, ProviderSettings>;
 interface AgentConfig {
   /** Discovered at runtime from AGENTS.md + .agents/skills/ in the session's cwd. */
   systemPrompt: string;
@@ -108,27 +128,34 @@ interface AgentConfig {
   skills: Record<string, Skill>;
   roles: Record<string, Role>;
   /**
-   * Agent-wide default model. Undefined by default — the user must set it via
-   * `init({ model: "provider/model-id" })` or pass `{ model }` at each prompt/
-   * skill/task call site. Calls with no model resolved throw clearly at runtime.
+   * Agent-wide default model. Undefined when the user explicitly passes
+   * `init({ model: false })`, so each model-using call must resolve one from a
+   * role or call-site override.
    */
   model: Model<any> | undefined;
   /** Agent-wide default role. Per-session and per-call roles override this. */
   role?: string;
-  /** Resolve a "provider/modelId" string to a Model instance. Throws on invalid input. */
-  resolveModel?: (modelString: string) => Model<any>;
+  /** Provider runtime settings applied when resolving models. */
+  providers?: ProvidersConfig;
+  /** Resolve model config to a Model instance. Throws on invalid model strings. */
+  resolveModel: (model: ModelConfig | undefined, providers?: ProvidersConfig) => Model<any> | undefined;
   compaction?: CompactionConfig;
 }
-/** Request context passed to agent handler functions. */
-interface FlueContext {
+type ModelConfig = string | false;
+/**
+ * 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>;
+  init(options: AgentInit): Promise<FlueAgent>;
 }
-/** All fields are optional — omitting gives platform defaults (empty sandbox, platform store, build-time model). */
+/** Agent runtime options. A default model is required unless explicitly disabled with `model: false`. */
 interface AgentInit {
   /** Agent/sandbox scope id. Defaults to the route/context id. */
   id?: string;
@@ -144,16 +171,37 @@ interface AgentInit {
   /** Defaults to platform store (in-memory on Node, DO SQLite on Cloudflare). */
   persist?: SessionStore;
   /**
-   * Override the default model for this agent. Applies to all prompt() and skill()
-   * calls unless overridden at the call site.
+   * Default model for this agent. Applies to all prompt(), skill(), and task()
+   * calls unless overridden by a role or at the call site. Pass `false` to require every
+   * model-using call to resolve a model from a role or call-site override.
    *
    * Format: `'provider/modelId'` (e.g. `'anthropic/claude-opus-4-20250514'`).
    *
-   * Precedence (highest wins): per-call `model` > role `model` > agent `model` > build-time default.
+   * Precedence (highest wins): per-call `model` > role `model` > agent `model`.
    */
-  model?: string;
+  model: ModelConfig;
   /** Agent-wide default role. Overridden by session-level or per-call roles. */
   role?: string;
+  /**
+   * Provider runtime settings for every model used by this agent, including
+   * role-level and per-call model selections.
+   *
+   * Example:
+   *
+   * ```ts
+   * await init({
+   *   model: 'anthropic/claude-sonnet-4-6',
+   *   providers: {
+   *     anthropic: {
+   *       baseUrl: env.ANTHROPIC_BASE_URL,
+   *       headers: { 'X-Custom-Auth': env.GATEWAY_KEY },
+   *       apiKey: 'dummy',
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  providers?: ProvidersConfig;
   /**
    * Agent-wide tools. Every prompt(), skill(), and task() call can use these.
    * Per-call tools are added on top and must not reuse the same names.
@@ -458,4 +506,4 @@ interface BuildOptions {
   plugin?: BuildPlugin;
 }
 //#endregion
-export { TaskOptions as A, SessionEnv as C, ShellResult as D, ShellOptions as E, ToolParameters as M, Skill as O, SessionData as S, SessionStore as T, FlueSessions as _, BashLike as a, Role as b, BuildPlugin as c, FileStat as d, FlueAgent as f, FlueSession as g, FlueEventCallback as h, BashFactory as i, ToolDef as j, SkillOptions as k, Command as l, FlueEvent as m, AgentInfo as n, BuildContext as o, FlueContext as p, AgentInit as r, BuildOptions as s, AgentConfig as t, CommandDef as u, PromptOptions as v, SessionOptions as w, SandboxFactory as x, PromptResponse as y };
+export { ShellResult as A, Role as C, SessionOptions as D, SessionEnv as E, ToolParameters as F, SkillOptions as M, TaskOptions as N, SessionStore as O, ToolDef as P, ProvidersConfig as S, SessionData as T, FlueSessions as _, BashLike as a, PromptResponse as b, BuildPlugin as c, FileStat as d, FlueAgent as f, FlueSession as g, FlueEventCallback as h, BashFactory as i, Skill as j, ShellOptions as k, Command as l, FlueEvent as m, AgentInfo as n, BuildContext as o, FlueContext as p, AgentInit as r, BuildOptions as s, AgentConfig as t, CommandDef as u, ModelConfig as v, SandboxFactory as w, ProviderSettings as x, PromptOptions as y };

package/package.json

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