@flue/sdk 0.3.0 → 0.3.2

package/dist/types-T8pE1xIS.d.mts

@@ -0,0 +1,461 @@
+import { Model, TSchema } from "@mariozechner/pi-ai";
+import { AgentMessage } from "@mariozechner/pi-agent-core";
+import * as v from "valibot";
+
+//#region src/types.d.ts
+interface Skill {
+  name: string;
+  description: string;
+  /** Markdown body of SKILL.md (below the frontmatter). */
+  instructions: string;
+}
+interface Role {
+  name: string;
+  description: string;
+  /** Markdown body of the role file (below the frontmatter). */
+  instructions: string;
+  model?: string;
+}
+/**
+ * An executable command that can be passed to prompt(), skill(), or shell().
+ * Registered into just-bash for the duration of the call.
+ */
+interface Command {
+  name: string;
+  execute(args: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  }>;
+}
+/** @deprecated Use `Command` with `defineCommand()` instead. */
+interface CommandDef {
+  name: string;
+  env?: Record<string, string>;
+}
+type ToolParameters = TSchema | Record<string, unknown>;
+/**
+ * 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 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;
+  /** 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>, signal?: AbortSignal) => Promise<string>;
+}
+interface FileStat {
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+  size: number;
+  mtime: Date;
+}
+/**
+ * Universal session environment interface. All sandbox modes (isolate, local, remote)
+ * implement this — no mode-specific branching needed in core logic.
+ *
+ * File methods accept both absolute and relative paths (resolved against `cwd`).
+ */
+interface SessionEnv {
+  exec(command: string, options?: {
+    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>;
+  stat(path: string): Promise<FileStat>;
+  readdir(path: string): Promise<string[]>;
+  exists(path: string): Promise<boolean>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  rm(path: string, options?: {
+    recursive?: boolean;
+    force?: boolean;
+  }): Promise<void>;
+  cwd: string;
+  /**
+   * Resolve a relative path against cwd. Absolute paths pass through.
+   * File methods resolve internally — only needed when you need the absolute path
+   * for your own logic (e.g., extracting the parent directory).
+   */
+  resolvePath(p: string): string;
+  cleanup(): Promise<void>;
+}
+interface CompactionConfig {
+  enabled?: boolean;
+  /** Token buffer to keep free in the context window. Default: 16384 */
+  reserveTokens?: number;
+  /** Recent tokens to preserve (not summarized). Default: 20000 */
+  keepRecentTokens?: number;
+}
+interface AgentConfig {
+  /** Discovered at runtime from AGENTS.md + .agents/skills/ in the session's cwd. */
+  systemPrompt: string;
+  /** Discovered at runtime from .agents/skills/ in the session's cwd. */
+  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.
+   */
+  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 id: string;
+  readonly payload: any;
+  /** Platform env bindings (process.env on Node, Worker env on Cloudflare). */
+  readonly env: Record<string, any>;
+  /** 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 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.
+   * - `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 | BashFactory;
+  /** 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.
+   *
+   * Format: `'provider/modelId'` (e.g. `'anthropic/claude-opus-4-20250514'`).
+   *
+   * 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;
+  /**
+   * 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 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>>;
+  prompt(text: string, options?: PromptOptions): Promise<PromptResponse>;
+  shell(command: string, options?: ShellOptions): Promise<ShellResult>;
+  skill<S extends v.GenericSchema>(name: string, options: SkillOptions<S> & {
+    result: S;
+  }): Promise<v.InferOutput<S>>;
+  skill(name: string, options?: SkillOptions): Promise<PromptResponse>;
+  task<S extends v.GenericSchema>(text: string, options: TaskOptions<S> & {
+    result: S;
+  }): Promise<v.InferOutput<S>>;
+  task(text: string, options?: TaskOptions): Promise<PromptResponse>;
+  delete(): Promise<void>;
+}
+interface PromptResponse {
+  text: string;
+}
+interface SessionData {
+  version: 2;
+  entries: SessionEntry[];
+  leafId: string | null;
+  metadata: Record<string, any>;
+  createdAt: string;
+  updatedAt: 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>;
+  delete(id: string): Promise<void>;
+}
+/** All option fields are scoped to the duration of the call. */
+interface PromptOptions<S extends v.GenericSchema | undefined = undefined> {
+  result?: S;
+  timeout?: number;
+  commands?: Command[];
+  tools?: ToolDef[];
+  role?: string;
+  /** e.g., 'anthropic/claude-sonnet-4-20250514' */
+  model?: string;
+}
+interface SkillOptions<S extends v.GenericSchema | undefined = undefined> {
+  args?: Record<string, unknown>;
+  result?: S;
+  timeout?: number;
+  commands?: Command[];
+  tools?: ToolDef[];
+  role?: string;
+  model?: string;
+}
+interface TaskOptions<S extends v.GenericSchema | undefined = undefined> {
+  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>;
+  cwd?: string;
+  timeout?: number;
+  commands?: Command[];
+}
+interface ShellResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+/** Wraps external sandboxes (Daytona, CF Containers, etc.) into Flue's SessionEnv. */
+interface SandboxFactory {
+  createSessionEnv(options: {
+    id: string;
+    cwd?: string;
+  }): Promise<SessionEnv>;
+}
+/**
+ * Structural type for duck-type detection of just-bash `Bash` instances in init().
+ * Purely structural — no just-bash import, so client.ts stays platform-agnostic.
+ */
+interface BashLike {
+  exec(command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+  }): Promise<ShellResult>;
+  getCwd(): string;
+  fs: {
+    readFile(path: string, options?: any): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array, options?: any): Promise<void>;
+    stat(path: string): Promise<any>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+      recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+      recursive?: boolean;
+      force?: boolean;
+    }): Promise<void>;
+    resolvePath(base: string, path: string): string;
+  };
+  registerCommand?(cmd: any): void;
+}
+/** 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';
+  text: string;
+} | {
+  type: 'tool_start';
+  toolName: string;
+  toolCallId: string;
+  args?: any;
+} | {
+  type: 'tool_end';
+  toolName: string;
+  toolCallId: string;
+  isError: boolean;
+  result?: any;
+} | {
+  type: 'turn_end';
+} | {
+  type: 'command_start';
+  command: string;
+  args: string[];
+} | {
+  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';
+  estimatedTokens: number;
+} | {
+  type: 'compaction_end';
+  messagesBefore: number;
+  messagesAfter: number;
+} | {
+  type: 'idle';
+} | {
+  type: 'error';
+  error: string;
+}) & {
+  sessionId?: string;
+  parentSessionId?: string;
+  taskId?: string;
+};
+type FlueEventCallback = (event: FlueEvent) => void;
+interface AgentInfo {
+  name: string;
+  filePath: string;
+  triggers: {
+    webhook?: boolean;
+    cron?: string;
+  };
+}
+interface BuildContext {
+  agents: AgentInfo[];
+  roles: Record<string, Role>;
+  /** The workspace root: the directory directly containing agents/ and roles/. */
+  workspaceDir: string;
+  /** Where dist/ is written. Typically the project root, independent of workspaceDir. */
+  outputDir: string;
+  options: BuildOptions;
+}
+/**
+ * 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;
+  /**
+   * 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 {
+  /**
+   * The workspace directory: the directory directly containing agents/ and
+   * roles/. Pass an explicit path — no .flue/ waterfall is performed here.
+   * Callers that want the waterfall behavior (e.g. the CLI when --workspace
+   * is omitted) should resolve it themselves with `resolveWorkspaceFromCwd`.
+   */
+  workspaceDir: string;
+  /**
+   * Where to write the dist/ directory. Independent of workspaceDir — typically
+   * the project root, so platform config like wrangler.jsonc ends up where the
+   * deploy tool expects it.
+   */
+  outputDir: string;
+  target?: 'node' | 'cloudflare';
+  /** Overrides `target` when provided. */
+  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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -43,14 +43,22 @@
     "@valibot/to-json-schema": "^1.0.0",
     "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",