@flue/sdk 0.2.0 → 0.3.1

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

@@ -33,19 +33,22 @@ interface CommandDef {
   name: string;
   env?: Record<string, string>;
 }
+type ToolParameters = TSchema | Record<string, unknown>;
 /**
- * Custom tool passed to prompt() or skill(). Scoped to the duration of the call.
- * Parameters use TypeBox schemas — import `Type` from `@flue/sdk/client`.
+ * Custom tool passed to init(), prompt(), skill(), or task(). init() tools are
+ * available to every session call; prompt/skill/task tools are scoped to that call.
+ * Parameters are JSON Schema-compatible. Use `Type` from `@flue/sdk/client` for
+ * hand-written tools, or pass schemas discovered from adapters such as MCP.
  */
-interface ToolDef<TParams extends TSchema = TSchema> {
+interface ToolDef<TParams extends ToolParameters = ToolParameters> {
   /** Must be unique across built-in and custom tools. */
   name: string;
   /** Tells the LLM when and how to use this tool. */
   description: string;
-  /** TypeBox parameter schema. */
+  /** JSON Schema-compatible parameter schema. */
   parameters: TParams;
   /** Returns a string result sent back to the LLM. Thrown errors become tool errors. */
-  execute: (args: Record<string, any>) => Promise<string>;
+  execute: (args: Record<string, any>, signal?: AbortSignal) => Promise<string>;
 }
 interface FileStat {
   isFile: boolean;
@@ -54,11 +57,6 @@ interface FileStat {
   size: number;
   mtime: Date;
 }
-/** Registers commands into the isolate's bash. Only present when the sandbox supports it. */
-interface CommandSupport {
-  register(cmd: Command): void;
-  unregister(name: string): void;
-}
 /**
  * Universal session environment interface. All sandbox modes (isolate, local, remote)
  * implement this — no mode-specific branching needed in core logic.
@@ -70,6 +68,10 @@ interface SessionEnv {
     cwd?: string;
     env?: Record<string, string>;
   }): Promise<ShellResult>;
+  /** Create an operation-scoped environment, usually backed by a fresh Bash runtime. */
+  scope?(options?: {
+    commands?: Command[];
+  }): Promise<SessionEnv>;
   readFile(path: string): Promise<string>;
   readFileBuffer(path: string): Promise<Uint8Array>;
   writeFile(path: string, content: string | Uint8Array): Promise<void>;
@@ -90,8 +92,6 @@ interface SessionEnv {
    * for your own logic (e.g., extracting the parent directory).
    */
   resolvePath(p: string): string;
-  /** Only present with isolate/local sandboxes. Undefined for remote sandboxes. */
-  commandSupport?: CommandSupport;
   cleanup(): Promise<void>;
 }
 interface CompactionConfig {
@@ -108,53 +108,90 @@ interface AgentConfig {
   skills: Record<string, Skill>;
   roles: Record<string, Role>;
   /**
-   * Session-wide default model. Undefined by default — the user must set it via
+   * 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.
    */
   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>;
   compaction?: CompactionConfig;
 }
 /** Request context passed to agent handler functions. */
 interface FlueContext {
-  readonly sessionId: string;
+  readonly id: string;
   readonly payload: any;
   /** Platform env bindings (process.env on Node, Worker env on Cloudflare). */
   readonly env: Record<string, any>;
-  /** Create a session with sandbox + persistence. Can only be called once per request. */
-  init(options?: SessionInit): Promise<FlueSession>;
+  /** Initialize an agent runtime with sandbox + persistence. */
+  init(options?: AgentInit): Promise<FlueAgent>;
 }
 /** All fields are optional — omitting gives platform defaults (empty sandbox, platform store, build-time model). */
-interface SessionInit {
+interface AgentInit {
+  /** Agent/sandbox scope id. Defaults to the route/context id. */
+  id?: string;
+  /** Working directory for context discovery, tools, and shell calls. Defaults to the sandbox cwd. */
+  cwd?: string;
   /**
    * - `'empty'` (default): In-memory sandbox, no files, no host access.
    * - `'local'`: Mounts process.cwd() at /workspace. Node only.
-   * - `BashLike`: User-configured just-bash instance.
+   * - `BashFactory`: User-configured just-bash factory. Must return a fresh Bash-like instance.
    * - `SandboxFactory`: Connector-wrapped external sandbox (Daytona, CF Containers, etc.).
    */
-  sandbox?: 'empty' | 'local' | SandboxFactory | BashLike;
+  sandbox?: 'empty' | 'local' | SandboxFactory | BashFactory;
   /** Defaults to platform store (in-memory on Node, DO SQLite on Cloudflare). */
   persist?: SessionStore;
   /**
-   * Override the default model for this session. Applies to all prompt(), skill(),
-   * and task() calls unless overridden at the call site.
+   * Override the default model for this agent. Applies to all prompt() and skill()
+   * calls unless overridden at the call site.
    *
    * Format: `'provider/modelId'` (e.g. `'anthropic/claude-opus-4-20250514'`).
    *
-   * Precedence (highest wins): per-call `model` > role `model` > session `model` > build-time default.
+   * Precedence (highest wins): per-call `model` > role `model` > agent `model` > build-time default.
    */
   model?: string;
+  /** Agent-wide default role. Overridden by session-level or per-call roles. */
+  role?: string;
   /**
-   * Session-wide commands. Every prompt(), skill(), and shell() call inherits
+   * 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.
+   */
+  tools?: ToolDef[];
+  /**
+   * Agent-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
+   * shares a name with an agent command, the per-call version wins for that
    * call.
    */
   commands?: Command[];
 }
+interface FlueAgent {
+  readonly id: string;
+  /** Get or create a session in this agent. Defaults to the "default" session. */
+  session(id?: string, options?: SessionOptions): Promise<FlueSession>;
+  /** Explicit session management helpers. */
+  readonly sessions: FlueSessions;
+  /** Run a shell command in the agent sandbox without recording it in a conversation. */
+  shell(command: string, options?: ShellOptions): Promise<ShellResult>;
+  /** Destroy the agent runtime and clean up the sandbox resources it owns. */
+  destroy(): Promise<void>;
+}
+interface FlueSessions {
+  /** Load an existing session. Throws if it does not exist. */
+  get(id?: string, options?: SessionOptions): Promise<FlueSession>;
+  /** Create a new session. Throws if it already exists. */
+  create(id?: string, options?: SessionOptions): Promise<FlueSession>;
+  /** Delete a session's stored conversation state. No-op when missing. */
+  delete(id?: string): Promise<void>;
+}
+interface SessionOptions {
+  /** Session-wide default role. Per-call roles override this. */
+  role?: string;
+}
 interface FlueSession {
+  readonly id: string;
   prompt<S extends v.GenericSchema>(text: string, options: PromptOptions<S> & {
     result: S;
   }): Promise<v.InferOutput<S>>;
@@ -164,30 +201,51 @@ interface FlueSession {
     result: S;
   }): Promise<v.InferOutput<S>>;
   skill(name: string, options?: SkillOptions): Promise<PromptResponse>;
-  /** Sub-agent task with its own conversation history, context discovery, and compaction. */
-  task<S extends v.GenericSchema>(prompt: string, options: TaskOptions<S> & {
+  task<S extends v.GenericSchema>(text: string, options: TaskOptions<S> & {
     result: S;
   }): Promise<v.InferOutput<S>>;
-  task(prompt: string, options?: TaskOptions): Promise<PromptResponse>;
-  destroy(): Promise<void>;
+  task(text: string, options?: TaskOptions): Promise<PromptResponse>;
+  delete(): Promise<void>;
 }
 interface PromptResponse {
   text: string;
 }
 interface SessionData {
-  messages: AgentMessage[];
+  version: 2;
+  entries: SessionEntry[];
+  leafId: string | null;
   metadata: Record<string, any>;
   createdAt: string;
   updatedAt: string;
-  lastCompaction?: {
-    summary: string;
-    firstKeptIndex: number;
-    details?: {
-      readFiles: string[];
-      modifiedFiles: string[];
-    };
+}
+type SessionEntry = MessageEntry | CompactionEntry | BranchSummaryEntry;
+interface SessionEntryBase {
+  type: string;
+  id: string;
+  parentId: string | null;
+  timestamp: string;
+}
+interface MessageEntry extends SessionEntryBase {
+  type: 'message';
+  message: AgentMessage;
+  source?: 'prompt' | 'skill' | 'shell' | 'task' | 'retry';
+}
+interface CompactionEntry extends SessionEntryBase {
+  type: 'compaction';
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  details?: {
+    readFiles: string[];
+    modifiedFiles: string[];
   };
 }
+interface BranchSummaryEntry extends SessionEntryBase {
+  type: 'branch_summary';
+  fromId: string;
+  summary: string;
+  details?: unknown;
+}
 interface SessionStore {
   save(id: string, data: SessionData): Promise<void>;
   load(id: string): Promise<SessionData | null>;
@@ -213,11 +271,13 @@ interface SkillOptions<S extends v.GenericSchema | undefined = undefined> {
   model?: string;
 }
 interface TaskOptions<S extends v.GenericSchema | undefined = undefined> {
-  /** Workspace directory — AGENTS.md and skills are discovered from here. */
-  workspace?: string;
   result?: S;
+  commands?: Command[];
+  tools?: ToolDef[];
   role?: string;
   model?: string;
+  /** Working directory for the detached task session. Defaults to the parent session cwd. */
+  cwd?: string;
 }
 interface ShellOptions {
   env?: Record<string, string>;
@@ -233,8 +293,8 @@ interface ShellResult {
 /** Wraps external sandboxes (Daytona, CF Containers, etc.) into Flue's SessionEnv. */
 interface SandboxFactory {
   createSessionEnv(options: {
-    sessionId: string;
-    workspace?: string;
+    id: string;
+    cwd?: string;
   }): Promise<SessionEnv>;
 }
 /**
@@ -265,7 +325,9 @@ interface BashLike {
   };
   registerCommand?(cmd: any): void;
 }
-type FlueEvent = {
+/** Factory for a fresh Bash-like runtime. Share `fs` inside the closure to persist files. */
+type BashFactory = () => BashLike | Promise<BashLike>;
+type FlueEvent = ({
   type: 'agent_start';
 } | {
   type: 'text_delta';
@@ -291,6 +353,17 @@ type FlueEvent = {
   type: 'command_end';
   command: string;
   exitCode: number;
+} | {
+  type: 'task_start';
+  taskId: string;
+  prompt: string;
+  role?: string;
+  cwd?: string;
+} | {
+  type: 'task_end';
+  taskId: string;
+  isError: boolean;
+  result?: any;
 } | {
   type: 'compaction_start';
   reason: 'threshold' | 'overflow';
@@ -300,15 +373,14 @@ type FlueEvent = {
   messagesBefore: number;
   messagesAfter: number;
 } | {
-  type: 'task_start';
-  workspace: string;
-} | {
-  type: 'task_end';
-} | {
-  type: 'done';
+  type: 'idle';
 } | {
   type: 'error';
   error: string;
+}) & {
+  sessionId?: string;
+  parentSessionId?: string;
+  taskId?: string;
 };
 type FlueEventCallback = (event: FlueEvent) => void;
 interface AgentInfo {
@@ -328,13 +400,44 @@ interface BuildContext {
   outputDir: string;
   options: BuildOptions;
 }
-/** Controls the build output format for a target platform. */
+/**
+ * Controls the build output format for a target platform.
+ *
+ * A plugin can either ship a fully-bundled JavaScript artifact (Node target)
+ * or hand over a TypeScript/ESM entry source that some downstream tool will
+ * bundle (Cloudflare target — wrangler does the bundling). Pre-bundling on
+ * top of a tool that bundles for itself causes subtle resolution conflicts
+ * (we hit this with `tar`/`fs`/etc. via `nodejs_compat`), so the Cloudflare
+ * path explicitly opts out.
+ */
 interface BuildPlugin {
   name: string;
-  generateEntryPoint(ctx: BuildContext): string;
-  esbuildOptions(ctx: BuildContext): Record<string, any>;
-  /** Additional files to write to dist/ (e.g., wrangler.jsonc, Dockerfile). */
-  additionalOutputs?(ctx: BuildContext): Record<string, string>;
+  /**
+   * The source of the entry point (TS or JS). May be async — the Cloudflare
+   * plugin reads the user's wrangler config (via wrangler's reader) which is
+   * a sync call but lives behind a lazy `await import('wrangler')`.
+   */
+  generateEntryPoint(ctx: BuildContext): string | Promise<string>;
+  /**
+   * Bundling strategy:
+   *   - `'esbuild'` (default): run the SDK's esbuild pass to produce a
+   *     bundled `dist/server.mjs`. Use when the deploy target is "just run
+   *     this file" with no further bundling step.
+   *   - `'none'`: skip esbuild. The entry is written as-is to `dist/` and
+   *     becomes the input for whatever tool will deploy it (e.g. wrangler).
+   *     The plugin must also implement `entryFilename` to set the file name.
+   */
+  bundle?: 'esbuild' | 'none';
+  /**
+   * The filename to use for the entry, written under `dist/`. Required when
+   * `bundle === 'none'`. For `bundle === 'esbuild'` the output is always
+   * `server.mjs` and this field is ignored.
+   */
+  entryFilename?: string;
+  /** esbuild options. Only consulted when `bundle === 'esbuild'`. */
+  esbuildOptions?(ctx: BuildContext): Record<string, any>;
+  /** Additional files to write to dist/ (e.g., wrangler.jsonc, Dockerfile). May be async. */
+  additionalOutputs?(ctx: BuildContext): Record<string, string> | Promise<Record<string, string>>;
 }
 interface BuildOptions {
   /**
@@ -355,4 +458,4 @@ interface BuildOptions {
   plugin?: BuildPlugin;
 }
 //#endregion
-export { ShellOptions as C, TaskOptions as D, SkillOptions as E, ToolDef as O, SessionStore as S, Skill as T, Role as _, BuildOptions as a, SessionEnv as b, CommandDef as c, FlueContext as d, FlueEvent as f, PromptResponse as g, PromptOptions as h, BuildContext as i, CommandSupport as l, FlueSession as m, AgentInfo as n, BuildPlugin as o, FlueEventCallback as p, BashLike as r, Command as s, AgentConfig as t, FileStat as u, SandboxFactory as v, ShellResult as w, SessionInit as x, SessionData as y };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -39,18 +39,26 @@
     "@hono/node-server": "^1.14.0",
     "@mariozechner/pi-agent-core": "*",
     "@mariozechner/pi-ai": "*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@valibot/to-json-schema": "^1.0.0",
-    "agentfs-sdk": "^0.6.4",
     "esbuild": "^0.25.0",
     "hono": "^4.7.0",
-    "jsonc-parser": "^3.3.1",
     "just-bash": "^2.14.2",
     "package-up": "^5.0.0",
     "valibot": "^1.0.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250410.0",
-    "tsdown": "^0.20.3"
+    "tsdown": "^0.20.3",
+    "wrangler": "^4.83.0"
+  },
+  "peerDependencies": {
+    "wrangler": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "wrangler": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsdown",