@flue/sdk 0.3.11 → 0.4.0

package/dist/types-DGpyKMFm.d.mts

@@ -1,508 +0,0 @@
-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>;
-    timeout?: number;
-  }): 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 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;
-  /** Discovered at runtime from .agents/skills/ in the session's cwd. */
-  skills: Record<string, Skill>;
-  roles: Record<string, Role>;
-  /**
-   * 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;
-  /** 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;
-}
-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: TPayload;
-  /** Platform env bindings (process.env on Node, Worker env on Cloudflare). */
-  readonly env: TEnv;
-  /** Initialize an agent runtime with sandbox + persistence. */
-  init(options: AgentInit): Promise<FlueAgent>;
-}
-/** 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;
-  /** 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;
-  /**
-   * 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`.
-   */
-  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.
-   */
-  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;
-  };
-}
-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 { 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 };