@flue/sdk 0.4.0 → 0.5.0

package/dist/{types-BAmV4f3Q.d.mts → types-Cdcq_ET2.d.mts}

@@ -112,7 +112,7 @@ interface SessionEnv {
   resolvePath(p: string): string;
 }
 /**
- * Filesystem surface for the agent sandbox, exposed on `FlueAgent.fs` and
+ * Filesystem surface for the harness sandbox, exposed on `FlueHarness.fs` and
  * `FlueSession.fs`. Reads and writes happen inside whatever the sandbox
  * connector points at (a remote container, microVM, in-process FS, etc.).
  *
@@ -173,7 +173,7 @@ interface ProviderSettings {
   baseUrl?: string;
   /** Headers merged into the resolved model's provider-level headers. */
   headers?: Record<string, string>;
-  /** API key returned to the underlying agent runtime for this provider. */
+  /** API key returned to the underlying harness runtime for this provider. */
   apiKey?: string;
   /**
    * Sends `store: true` for OpenAI Responses API providers. Only enable when
@@ -212,7 +212,10 @@ type ModelConfig = string | false;
  * `wrangler types`). Compile-time only — no runtime validation of `payload`.
  */
 interface FlueContext<TPayload = any, TEnv = Record<string, any>> {
+  /** Agent instance id from the URL `<id>` segment. */
   readonly id: string;
+  /** Server-minted id for this HTTP invocation. */
+  readonly runId: string;
   readonly payload: TPayload;
   /** Platform env bindings (process.env on Node, Worker env on Cloudflare). */
   readonly env: TEnv;
@@ -238,13 +241,20 @@ interface FlueContext<TPayload = any, TEnv = Record<string, any>> {
    * trusted proxy on Node. Don't trust headers you don't control.
    */
   readonly req: Request | undefined;
-  /** Initialize an agent runtime with sandbox + persistence. */
-  init(options: AgentInit): Promise<FlueAgent>;
+  /** Emit structured log events visible in the run event stream. */
+  readonly log: FlueLogger;
+  /** Initialize a harness with sandbox + persistence. */
+  init(options: AgentInit): Promise<FlueHarness>;
 }
-/** Agent runtime options. A default model is required unless explicitly disabled with `model: false`. */
+interface FlueLogger {
+  info(message: string, attributes?: Record<string, unknown>): void;
+  warn(message: string, attributes?: Record<string, unknown>): void;
+  error(message: string, attributes?: Record<string, unknown>): void;
+}
+/** Harness 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;
+  /** Harness name. Defaults to `"default"`. */
+  name?: string;
   /** Working directory for context discovery, tools, and shell calls. Defaults to the sandbox cwd. */
   cwd?: string;
   /**
@@ -260,16 +270,16 @@ interface AgentInit {
   /** 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()
+   * Default model for this harness. 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`.
+   * Precedence (highest wins): per-call `model` > role `model` > harness `model`.
    */
   model: ModelConfig;
-  /** Agent-wide default role. Overridden by session-level or per-call roles. */
+  /** Harness-wide default role. Overridden by session-level or per-call roles. */
   role?: string;
   /**
    * Default reasoning effort for every prompt(), skill(), and task() call.
@@ -278,38 +288,38 @@ interface AgentInit {
    * models effectively run with reasoning off after clamping.
    *
    * Precedence (highest wins): per-call `thinkingLevel` > role
-   * `thinkingLevel` > agent `thinkingLevel`. When nothing is set, the harness
+   * `thinkingLevel` > harness `thinkingLevel`. When nothing is set, the harness
    * defaults to `"medium"`. Use `"off"` to explicitly disable reasoning on
    * models that support it.
    */
   thinkingLevel?: ThinkingLevel;
   /**
-   * Agent-wide tools. Every prompt(), skill(), and task() call can use these.
+   * Harness-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[];
 }
-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>;
+interface FlueHarness {
+  readonly name: string;
+  /** Get or create a session in this harness. Defaults to the "default" session. */
+  session(name?: 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. */
+  /** Run a shell command in the harness sandbox without recording it in a conversation. */
   shell(command: string, options?: ShellOptions): CallHandle<ShellResult>;
   /**
-   * Read and write files in the agent sandbox without recording in a
+   * Read and write files in the harness sandbox without recording in a
    * conversation. See {@link FlueFs}.
    */
   readonly fs: FlueFs;
 }
 interface FlueSessions {
   /** Load an existing session. Throws if it does not exist. */
-  get(id?: string, options?: SessionOptions): Promise<FlueSession>;
+  get(name?: string, options?: SessionOptions): Promise<FlueSession>;
   /** Create a new session. Throws if it already exists. */
-  create(id?: string, options?: SessionOptions): Promise<FlueSession>;
+  create(name?: string, options?: SessionOptions): Promise<FlueSession>;
   /** Delete a session's stored conversation state. No-op when missing. */
-  delete(id?: string): Promise<void>;
+  delete(name?: string): Promise<void>;
 }
 interface SessionOptions {
   /** Session-wide default role. Per-call roles override this. */
@@ -328,7 +338,7 @@ interface CallHandle<T> extends PromiseLike<T> {
   abort(reason?: unknown): void;
 }
 interface FlueSession {
-  readonly id: string;
+  readonly name: string;
   prompt<S extends v.GenericSchema>(text: string, options: PromptOptions<S> & {
     schema: S;
   }): CallHandle<PromptResultResponse<v.InferOutput<S>>>;
@@ -408,7 +418,7 @@ interface PromptResultResponse<T> {
   model: PromptModel;
 }
 interface SessionData {
-  version: 2;
+  version: 3;
   entries: SessionEntry[];
   leafId: string | null;
   metadata: Record<string, any>;
@@ -566,7 +576,12 @@ interface BashLike {
 /** Factory that constructs the agent's Bash-like runtime. Called once at init. */
 type BashFactory = () => BashLike | Promise<BashLike>;
 type FlueEvent = ({
-  type: 'agent_start';
+  type: 'run_start';
+  runId: string;
+  instanceId: string;
+  agentName: string;
+  startedAt: string;
+  payload: unknown;
 } | {
   type: 'text_delta';
   text: string;
@@ -584,13 +599,20 @@ type FlueEvent = ({
   toolCallId: string;
   args?: any;
 } | {
-  type: 'tool_end';
+  type: 'tool_call';
   toolName: string;
   toolCallId: string;
   isError: boolean;
   result?: any;
+  durationMs: number;
 } | {
-  type: 'turn_end';
+  type: 'turn';
+  durationMs: number;
+  model?: string;
+  usage?: PromptUsage;
+  stopReason?: string;
+  isError: boolean;
+  error?: unknown;
 } | {
   type: 'task_start';
   taskId: string;
@@ -598,26 +620,59 @@ type FlueEvent = ({
   role?: string;
   cwd?: string;
 } | {
-  type: 'task_end';
+  type: 'task';
   taskId: string;
   isError: boolean;
   result?: any;
+  durationMs: number;
 } | {
   type: 'compaction_start';
   reason: 'threshold' | 'overflow';
   estimatedTokens: number;
 } | {
-  type: 'compaction_end';
+  type: 'compaction';
   messagesBefore: number;
   messagesAfter: number;
+  durationMs: number;
+  usage?: PromptUsage;
+} | {
+  type: 'operation_start';
+  operationId: string;
+  operationKind: 'prompt' | 'skill' | 'task' | 'shell';
+} | {
+  type: 'operation';
+  operationId: string;
+  operationKind: 'prompt' | 'skill' | 'task' | 'shell';
+  durationMs: number;
+  isError: boolean;
+  error?: unknown;
+  result?: unknown;
+  usage?: PromptUsage;
+} | {
+  type: 'log';
+  level: 'info' | 'warn' | 'error';
+  message: string;
+  attributes?: Record<string, unknown>;
 } | {
   type: 'idle';
+} | {
+  type: 'run_end';
+  runId: string;
+  result?: unknown;
+  isError: boolean;
+  error?: unknown;
+  durationMs: number;
 }) & {
-  sessionId?: string;
-  parentSessionId?: string;
+  runId?: string;
+  eventIndex?: number;
+  timestamp?: string;
+  session?: string;
+  parentSession?: string;
   taskId?: string;
+  harness?: string;
+  operationId?: string;
 };
-type FlueEventCallback = (event: FlueEvent) => void;
+type FlueEventCallback = (event: FlueEvent) => void | Promise<void>;
 interface AgentInfo {
   name: string;
   filePath: string;
@@ -724,4 +779,4 @@ interface BuildOptions {
   plugin?: BuildPlugin;
 }
 //#endregion
-export { SessionStore as A, PromptUsage as C, SessionData as D, SandboxFactory as E, TaskOptions as F, ThinkingLevel as I, ToolDef as L, ShellResult as M, Skill as N, SessionEnv as O, SkillOptions as P, ToolParameters as R, PromptResultResponse as S, Role as T, FlueSessions as _, BashLike as a, PromptOptions as b, BuildPlugin as c, FlueAgent as d, FlueContext as f, FlueSession as g, FlueFs as h, BashFactory as i, ShellOptions as j, SessionOptions as k, CallHandle as l, FlueEventCallback as m, AgentInfo as n, BuildContext as o, FlueEvent as p, AgentInit as r, BuildOptions as s, AgentConfig as t, FileStat as u, ModelConfig as v, ProviderSettings as w, PromptResponse as x, PromptModel as y };
+export { SessionStore as A, PromptUsage as C, SessionData as D, SandboxFactory as E, TaskOptions as F, ThinkingLevel as I, ToolDef as L, ShellResult as M, Skill as N, SessionEnv as O, SkillOptions as P, ToolParameters as R, PromptResultResponse as S, Role as T, FlueSessions as _, BashLike as a, PromptOptions as b, BuildPlugin as c, FlueContext as d, FlueEvent as f, FlueSession as g, FlueHarness as h, BashFactory as i, ShellOptions as j, SessionOptions as k, CallHandle as l, FlueFs as m, AgentInfo as n, BuildContext as o, FlueEventCallback as p, AgentInit as r, BuildOptions as s, AgentConfig as t, FileStat as u, ModelConfig as v, ProviderSettings as w, PromptResponse as x, PromptModel as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -57,6 +57,7 @@
     "just-bash": "^2.14.2",
     "package-up": "^5.0.0",
     "typescript": "^5.9.2",
+    "ulidx": "^2.4.1",
     "valibot": "^1.0.0"
   },
   "devDependencies": {