@lobehub/chat 1.128.7 → 1.128.8

package/packages/agent-runtime/src/types/event.ts

@@ -0,0 +1,121 @@
+/* eslint-disable sort-keys-fix/sort-keys-fix, typescript-sort-keys/interface */
+import type { AgentState, ToolsCalling } from './state';
+
+export interface AgentEventInit {
+  type: 'init';
+}
+
+export interface AgentEventLlmStart {
+  type: 'llm_start';
+  payload: unknown;
+}
+
+export interface AgentEventLlmStream {
+  type: 'llm_stream';
+  chunk: unknown;
+}
+
+export interface AgentEventLlmResult {
+  type: 'llm_result';
+  result: unknown;
+}
+
+export interface AgentEventToolPending {
+  type: 'tool_pending';
+  toolCalls: ToolsCalling[];
+}
+
+export interface AgentEventToolResult {
+  type: 'tool_result';
+  id: string;
+  result: any;
+}
+
+export interface AgentEventHumanApproveRequired {
+  type: 'human_approve_required';
+  pendingToolsCalling: ToolsCalling[];
+  sessionId: string;
+}
+
+export interface AgentEventHumanPromptRequired {
+  type: 'human_prompt_required';
+  metadata?: Record<string, unknown>;
+  prompt: string;
+  sessionId: string;
+}
+
+export interface AgentEventHumanSelectRequired {
+  type: 'human_select_required';
+  metadata?: Record<string, unknown>;
+  multi?: boolean;
+  options: { label: string; value: string }[];
+  prompt?: string;
+  sessionId: string;
+}
+
+/**
+ * Standardized finish reasons
+ */
+export type FinishReason =
+  | 'completed' // Normal completion
+  | 'user_requested' // User requested to end
+  | 'max_steps_exceeded' // Reached maximum steps limit
+  | 'cost_limit_exceeded' // Reached cost limit
+  | 'timeout' // Execution timeout
+  | 'agent_decision' // Agent decided to finish
+  | 'error_recovery' // Finished due to unrecoverable error
+  | 'system_shutdown'; // System is shutting down
+
+export interface AgentEventDone {
+  type: 'done';
+  finalState: AgentState;
+  reason: FinishReason;
+  reasonDetail?: string;
+}
+
+export interface AgentEventError {
+  type: 'error';
+  error: any;
+}
+
+export interface AgentEventInterrupted {
+  type: 'interrupted';
+  reason: string;
+  interruptedAt: string;
+  interruptedInstruction?: any;
+  canResume: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentEventResumed {
+  type: 'resumed';
+  reason: string;
+  resumedAt: string;
+  resumedFromStep: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Events emitted by the AgentRuntime during execution
+ */
+export type AgentEvent =
+  // Initialization
+  | AgentEventInit
+  // LLM streaming output
+  | AgentEventLlmStart
+  | AgentEventLlmStream
+  | AgentEventLlmResult
+  // Tool invocation
+  | AgentEventToolPending
+  | AgentEventToolResult
+  // Normal completion
+  | AgentEventDone
+  // Error thrown
+  | AgentEventError
+  // Human-in-the-loop (HIL)
+  | AgentEventHumanApproveRequired
+  | AgentEventHumanPromptRequired
+  | AgentEventHumanSelectRequired
+  // Interruption and resumption
+  | AgentEventInterrupted
+  | AgentEventResumed;

package/packages/agent-runtime/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from './event';
+export * from './instruction';
+export * from './runtime';
+export * from './state';
+export * from './usage';

package/packages/agent-runtime/src/types/instruction.ts

@@ -0,0 +1,125 @@
+import type { FinishReason } from './event';
+import { AgentState, ToolRegistry, ToolsCalling } from './state';
+import type { Cost, CostCalculationContext, Usage } from './usage';
+
+/**
+ * Runtime execution context passed to Agent runner
+ */
+export interface RuntimeContext {
+  /** Phase-specific payload/context */
+  payload?: unknown;
+  /** Current execution phase */
+  phase:
+    | 'init'
+    | 'user_input'
+    | 'llm_result'
+    | 'tool_result'
+    | 'human_response'
+    | 'human_approved_tool'
+    | 'error';
+  /** Session metadata */
+  session: {
+    eventCount: number;
+    messageCount: number;
+    sessionId: string;
+    status: AgentState['status'];
+    stepCount: number;
+  };
+}
+
+/**
+ * Represents the "Brain" of an agent.
+ * It contains all the decision-making logic and is completely stateless.
+ */
+export interface Agent {
+  /**
+   * Calculate cost from usage statistics
+   * @param context - Cost calculation context with usage and limits
+   * @returns Updated cost information
+   */
+  calculateCost?(context: CostCalculationContext): Cost;
+
+  /**
+   * Calculate usage statistics from operation results
+   * @param operationType - Type of operation that was performed
+   * @param operationResult - Result data from the operation
+   * @param previousUsage - Previous usage statistics
+   * @returns Updated usage statistics
+   */
+  calculateUsage?(
+    operationType: 'llm' | 'tool' | 'human_interaction',
+    operationResult: any,
+    previousUsage: Usage,
+  ): Usage;
+
+  /** Optional custom executors mapping to extend runtime behaviors */
+  executors?: Partial<Record<AgentInstruction['type'], any>>;
+
+  /**
+   * Model runtime function for LLM calls - Agent owns its model integration
+   * @param payload - LLM call payload (messages, tools, etc.)
+   * @returns Async iterable of streaming response chunks
+   */
+  modelRuntime?: (payload: unknown) => AsyncIterable<any>;
+
+  /**
+   * The core runner method. Based on the current execution context and state,
+   * it decides what the next action should be.
+   * @param context - Current runtime context with phase and payload
+   * @param state - Complete agent state for reference
+   */
+  runner(context: RuntimeContext, state: AgentState): Promise<AgentInstruction>;
+
+  /** Optional tools registry held by the agent */
+  tools?: ToolRegistry;
+}
+
+export interface AgentInstructionCallLlm {
+  payload: unknown;
+  type: 'call_llm';
+}
+
+export interface AgentInstructionCallTool {
+  toolCall: ToolsCalling;
+  type: 'call_tool';
+}
+
+export interface AgentInstructionRequestHumanPrompt {
+  metadata?: Record<string, unknown>;
+  prompt: string;
+  reason?: string;
+  type: 'request_human_prompt';
+}
+
+export interface AgentInstructionRequestHumanSelect {
+  metadata?: Record<string, unknown>;
+  multi?: boolean;
+  options: Array<{ label: string; value: string }>;
+  prompt?: string;
+  reason?: string;
+  type: 'request_human_select';
+}
+
+export interface AgentInstructionRequestHumanApprove {
+  pendingToolsCalling: ToolsCalling[];
+  reason?: string;
+  type: 'request_human_approve';
+}
+
+export interface AgentInstructionFinish {
+  reason: FinishReason;
+  reasonDetail?: string;
+  type: 'finish';
+}
+
+/**
+ * A serializable instruction object that the "Agent" (Brain) returns
+ * to the "AgentRuntime" (Engine) to execute.
+ */
+export type AgentInstruction =
+  | AgentInstructionCallLlm
+  | AgentInstructionCallTool
+  | AgentInstructionRequestHumanPrompt
+  | AgentInstructionRequestHumanSelect
+  | AgentInstructionRequestHumanApprove
+  | AgentInstructionFinish;

package/packages/agent-runtime/src/types/runtime.ts

@@ -0,0 +1,18 @@
+import type { AgentEvent } from './event';
+import { AgentInstruction, RuntimeContext } from './instruction';
+import { AgentState } from './state';
+
+export type InstructionExecutor = (
+  instruction: AgentInstruction,
+  state: AgentState,
+) => Promise<{
+  events: AgentEvent[];
+  newState: AgentState;
+  /** Next context to pass to Agent runner (if execution should continue) */
+  nextContext?: RuntimeContext;
+}>;
+
+export interface RuntimeConfig {
+  /** Custom executors for specific instruction types */
+  executors?: Partial<Record<AgentInstruction['type'], InstructionExecutor>>;
+}

package/packages/agent-runtime/src/types/state.ts

@@ -0,0 +1,108 @@
+/* eslint-disable sort-keys-fix/sort-keys-fix, typescript-sort-keys/interface */
+import type { AgentEvent } from './event';
+import type { Cost, CostLimit, Usage } from './usage';
+
+/**
+ * Agent's serializable state.
+ * This is the "passport" that can be persisted and transferred.
+ */
+export interface AgentState {
+  sessionId: string;
+  // --- State Machine ---
+  status: 'idle' | 'running' | 'waiting_for_human_input' | 'done' | 'error' | 'interrupted';
+
+  // --- Core Context ---
+  messages: any[];
+  systemRole?: string;
+
+  // --- Event History ---
+  /**
+   * Complete event trace for this agent session.
+   * Useful for debugging, auditing, and state replay.
+   */
+  events: AgentEvent[];
+
+  // --- Execution Tracking ---
+  /**
+   * Number of execution steps in this session.
+   * Incremented on each runtime.step() call.
+   */
+  stepCount: number;
+  /**
+   * Optional maximum number of steps allowed.
+   * If set, execution will stop with error when exceeded.
+   */
+  maxSteps?: number;
+
+  // --- Usage and Cost Tracking ---
+  /**
+   * Accumulated usage statistics for this session.
+   * Tracks tokens, API calls, tool usage, etc.
+   */
+  usage: Usage;
+  /**
+   * Current calculated cost for this session.
+   * Updated after each billable operation.
+   */
+  cost: Cost;
+  /**
+   * Optional cost limits configuration.
+   * If set, execution will stop when limits are exceeded.
+   */
+  costLimit?: CostLimit;
+
+  // --- HIL ---
+  /**
+   * When status is 'waiting_for_human_input', this stores pending requests
+   * for human-in-the-loop operations.
+   */
+  pendingToolsCalling?: ToolsCalling[];
+  pendingHumanPrompt?: { metadata?: Record<string, unknown>; prompt: string };
+  pendingHumanSelect?: {
+    metadata?: Record<string, unknown>;
+    multi?: boolean;
+    options: Array<{ label: string; value: string }>;
+    prompt?: string;
+  };
+
+  // --- Interruption Handling ---
+  /**
+   * When status is 'interrupted', this stores the interruption context
+   * for potential resumption or cleanup.
+   */
+  interruption?: {
+    /** Reason for interruption */
+    reason: string;
+    /** Timestamp when interruption occurred */
+    interruptedAt: string;
+    /** The instruction that was being executed when interrupted */
+    interruptedInstruction?: any;
+    /** Whether the interruption can be resumed */
+    canResume: boolean;
+  };
+
+  // --- Metadata ---
+  createdAt: string;
+  error?: any;
+  lastModified: string;
+
+  // --- Extensible metadata ---
+  metadata?: Record<string, any>;
+}
+
+/**
+ * OpenAI Tool Call
+ */
+export interface ToolsCalling {
+  function: {
+    arguments: string;
+    name: string; // A JSON string of arguments
+  };
+  id: string;
+  type: 'function';
+}
+
+/**
+ * A registry for tools, mapping tool names to their implementation.
+ */
+export type ToolRegistry = Record<string, (args: any) => Promise<any>>;

package/packages/agent-runtime/src/types/usage.ts

@@ -0,0 +1,128 @@
+/**
+ * Token usage tracking for different types of operations
+ */
+export interface TokenUsage {
+  /** Input tokens consumed */
+  input: number;
+  /** Output tokens generated */
+  output: number;
+  /** Total tokens (input + output) */
+  total: number;
+}
+
+/**
+ * Usage statistics for different operation types
+ */
+export interface Usage {
+  /** Human interaction statistics */
+  humanInteraction: {
+    /** Number of approval requests */
+    approvalRequests: number;
+    /** Number of prompt requests */
+    promptRequests: number;
+    /** Number of selection requests */
+    selectRequests: number;
+    /** Total waiting time for human input */
+    totalWaitingTimeMs: number;
+  };
+
+  /** LLM model usage */
+  llm: {
+    /** Number of LLM API calls made */
+    apiCalls: number;
+    /** Total processing time in milliseconds */
+    processingTimeMs: number;
+    /** Total token usage across all LLM calls */
+    tokens: TokenUsage;
+  };
+
+  /** Tool usage statistics */
+  tools: {
+    /** Usage breakdown by tool name */
+    byTool: Record<
+      string,
+      {
+        calls: number;
+        errors: number;
+        totalTimeMs: number;
+      }
+    >;
+    /** Number of tool calls executed */
+    totalCalls: number;
+    /** Total tool execution time */
+    totalTimeMs: number;
+  };
+}
+
+/**
+ * Cost calculation result
+ */
+export interface Cost {
+  /** Cost calculation timestamp */
+  calculatedAt: string;
+
+  currency: string;
+
+  /** LLM API costs */
+  llm: {
+    /** Cost per model used */
+    byModel: Record<
+      string,
+      {
+        currency: string;
+        inputTokens: number;
+        outputTokens: number;
+        totalCost: number;
+      }
+    >;
+    currency: string;
+    /** Total LLM cost */
+    total: number;
+  };
+  /** Tool execution costs */
+  tools: {
+    /** Cost per tool (if tool has associated costs) */
+    byTool: Record<
+      string,
+      {
+        calls: number;
+        currency: string;
+        totalCost: number;
+      }
+    >;
+    currency: string;
+    /** Total tool cost */
+    total: number;
+  };
+
+  /** Total session cost */
+  total: number;
+}
+
+/**
+ * Cost limit configuration
+ */
+export interface CostLimit {
+  /** Currency for cost limits */
+  currency: string;
+  /** Maximum LLM cost allowed */
+  maxLlmCost?: number;
+  /** Maximum tool cost allowed */
+  maxToolCost?: number;
+  /** Maximum total cost allowed */
+  maxTotalCost: number;
+  /** Action to take when limit is exceeded */
+  onExceeded: 'stop' | 'warn' | 'interrupt';
+}
+
+/**
+ * Cost calculation context passed to Agent
+ */
+export interface CostCalculationContext {
+  /** Cost limits configuration */
+  costLimit?: CostLimit;
+  /** Previous cost calculation (if any) */
+  previousCost?: Cost;
+  /** Current usage statistics */
+  usage: Usage;
+}

package/packages/agent-runtime/vitest.config.mts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      reporter: ['text', 'json', 'lcov', 'text-summary'],
+    },
+    environment: 'happy-dom',
+  },
+});
+
+

package/packages/database/migrations/0031_add_agent_index.sql

@@ -0,0 +1,2 @@
+CREATE INDEX "agents_title_idx" ON "agents" USING btree ("title");--> statement-breakpoint
+CREATE INDEX "agents_description_idx" ON "agents" USING btree ("description");