@perstack/runtime 0.0.38 → 0.0.40

package/README.md

@@ -0,0 +1,201 @@
+# @perstack/runtime
+
+The **Execution Engine** for Perstack agents.
+
+This package serves as the engine of Perstack. It orchestrates the lifecycle of an agent's execution, manages state, bridges the gap between LLMs and tools, and handles multi-agent coordination.
+
+## Installation
+
+```bash
+npm install @perstack/runtime
+```
+
+## Usage
+
+The primary entry point is the `run` function. It takes a `RunSetting` object and an optional `RunOptions` object.
+
+```typescript
+import { run } from "@perstack/runtime"
+import { type RunSetting } from "@perstack/core"
+
+// Configure the run
+const setting: RunSetting = {
+  runId: "run-123",
+  expertKey: "researcher",
+  input: { text: "Research quantum computing" },
+  // ... configuration for model, experts, etc.
+}
+
+// Execute the run
+const finalCheckpoint = await run({ setting }, {
+  eventListener: (event) => {
+    console.log(`[${event.type}]`, event)
+  }
+})
+```
+
+### Event Object
+
+The `eventListener` callback receives a `RunEvent` object, which provides granular details about the execution.
+
+```typescript
+type RunEvent = {
+  type: EventType       // e.g., "startRun", "callTool"
+  id: string            // Unique event ID
+  timestamp: number     // Unix timestamp
+  runId: string         // ID of the current run
+  stepNumber: number    // Current step number
+  // ... plus payload specific to the event type
+}
+```
+
+You can narrow down the event type to access specific properties:
+
+```typescript
+eventListener: (event) => {
+  if (event.type === "callTool") {
+    // event is now narrowed to the callTool event type
+    console.log(`Executing tool: ${event.toolCall.name}`)
+  }
+}
+```
+
+## Package Responsibilities
+
+1. **Expert Realization**: The engine that brings declaratively defined Experts to life, realizing the desired state described by the developer.
+2. **Lifecycle**: Drives the main execution loop of the agent (Reasoning -> Act -> Observe, repeat).
+3. **State Management**: Maintains the canonical state of an execution in the form of **Checkpoints**, enabling pause/resume and time-travel.
+4. **Skill Provider**: Provides the client side of the **Model Context Protocol (MCP)** to securely execute tools.
+5. **Expert Delegation**: Implements the protocol for **Expert-to-Expert delegation**, allowing agents to call each other.
+
+## Architecture
+
+The runtime orchestrates the interaction between the user's definition of an Expert and the actual execution environment.
+
+```mermaid
+graph TD
+    Author((Author)) -->|Defines| Def[Expert Definition]
+    User((User)) -->|Provides| Input[Input / Query]
+    
+    subgraph Runtime [Runtime Engine]
+        subgraph Instance [Expert Instance]
+            State[State Machine]
+            Context[Execution Context]
+            
+            subgraph Skills [Skill Layer]
+                SM[Skill Manager]
+                MCP[MCP Client]
+                MCPServer[MCP Server]
+            end
+        end
+    end
+
+    subgraph External [External World]
+        LLM[LLM Provider]
+        Workspace[Workspace / FS]
+    end
+
+    Def -->|Instantiates| Instance
+    Input -->|Starts| Instance
+
+    State -->|Reasoning| LLM
+    State -->|Act| SM
+    SM -->|Execute| MCP
+    MCP -->|Connect| MCPServer
+    MCPServer -->|Access| Workspace
+    
+    SM -.->|Delegate| Instance2["Expert Instance (Delegate)"]
+
+    State ~~~ Context
+```
+
+## Core Concepts
+
+The runtime's execution model can be visualized as a timeline where **Events** are points, **Steps** are the lines connecting them, and **Checkpoints** are the anchors.
+
+```mermaid
+graph LR
+    subgraph Step1 [Step 1: The Process]
+        direction LR
+        E1(Event: Start) --> E2(Event: Reasoning) --> E3(Event: Act) --> CP1((Checkpoint 1))
+    end
+    
+    subgraph Step2 [Step 2: The Process]
+        direction LR
+        CP1 --> E4(Event: Start) --> E5(Event: Reasoning) --> CP2((Checkpoint 2))
+    end
+
+    style CP1 fill:#f96,stroke:#333,stroke-width:4px
+    style CP2 fill:#f96,stroke:#333,stroke-width:4px
+```
+
+### 1. Events
+**Events** are granular moments in time that occur *during* execution. They represent specific actions or observations, such as "started reasoning", "called tool", or "finished tool".
+
+### 2. Step
+A **Step** is the continuous process that connects these events. It represents one atomic cycle of the agent's loop (Reasoning -> Act -> Observe, repeat).
+
+### 3. Checkpoint
+A **Checkpoint** is the immutable result at the end of a Step. It serves as the anchor point that:
+- Finalizes the previous Step.
+- Becomes the starting point for the next Step.
+- Allows the execution to be paused, resumed, or forked from that exact moment.
+
+## Internal State Machine
+
+The runtime ensures deterministic execution through a strictly defined state machine.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Init
+    Init --> PreparingForStep: startRun
+    PreparingForStep --> GeneratingToolCall: startGeneration
+    
+    GeneratingToolCall --> CallingTool: callTool
+    GeneratingToolCall --> CallingInteractiveTool: callInteractiveTool
+    GeneratingToolCall --> CallingDelegate: callDelegate
+    GeneratingToolCall --> FinishingStep: retry
+
+    CallingTool --> ResolvingToolResult: resolveToolResult
+    CallingTool --> ResolvingThought: resolveThought
+    CallingTool --> ResolvingPdfFile: resolvePdfFile
+    CallingTool --> ResolvingImageFile: resolveImageFile
+    CallingTool --> GeneratingRunResult: attemptCompletion
+
+    ResolvingToolResult --> FinishingStep: finishToolCall
+    ResolvingThought --> FinishingStep: finishToolCall
+    ResolvingPdfFile --> FinishingStep: finishToolCall
+    ResolvingImageFile --> FinishingStep: finishToolCall
+
+    GeneratingRunResult --> Stopped: completeRun
+    GeneratingRunResult --> FinishingStep: retry
+
+    CallingInteractiveTool --> Stopped: stopRunByInteractiveTool
+    CallingDelegate --> Stopped: stopRunByDelegate
+    
+    FinishingStep --> PreparingForStep: continueToNextStep
+    FinishingStep --> Stopped: stopRunByExceededMaxSteps
+```
+
+### Events
+Events trigger state transitions. They are emitted by the runtime logic or external inputs.
+
+- **Lifecycle**: `startRun`, `startGeneration`, `continueToNextStep`, `completeRun`
+- **Tool Execution**: `callTool`, `resolveToolResult`, `finishToolCall`
+- **Special Types**: `resolveThought`, `resolvePdfFile`, `resolveImageFile`
+- **Interruption**: `stopRunByInteractiveTool`, `stopRunByDelegate`, `stopRunByExceededMaxSteps`
+- **Error Handling**: `retry`
+
+## Checkpoint Status
+
+The `status` field in a Checkpoint indicates the current state of the execution.
+
+- **init**: The run has been created but not yet started.
+- **proceeding**: The run is currently active and executing steps.
+- **completed**: The run has finished successfully.
+- **stoppedByInteractiveTool**: The run is paused, waiting for user input (e.g., confirmation or parameter entry).
+- **stoppedByDelegate**: The run is paused, waiting for a delegated sub-agent to complete.
+- **stoppedByExceededMaxSteps**: The run stopped because it reached the maximum allowed steps.
+- **stoppedByError**: The run stopped due to an unrecoverable error.
+
+

package/dist/src/index.d.ts

@@ -1,8 +1,20 @@
-import * as xstate from 'xstate';
-import { SnapshotFrom, ActorRefFrom } from 'xstate';
 import * as _perstack_core from '@perstack/core';
-import { ToolDefinition, SkillType, McpStdioSkill, McpSseSkill, InteractiveSkill, Expert, SkillManagerParams, TextPart, ImageInlinePart, FileInlinePart, RunSetting, Step, Checkpoint, RunEvent, RunParamsInput, ProviderConfig, ProviderName, Usage } from '@perstack/core';
+import { ProviderConfig, ProviderName, Usage, RunParamsInput, RunSetting, Checkpoint, Step, RunEvent, RuntimeEvent, ToolDefinition, SkillType, McpStdioSkill, McpSseSkill, InteractiveSkill, Expert, SkillManagerParams, TextPart, ImageInlinePart, FileInlinePart } from '@perstack/core';
 import { LanguageModel } from 'ai';
+import * as xstate from 'xstate';
+import { SnapshotFrom, ActorRefFrom } from 'xstate';
+
+declare function getModel(modelId: string, providerConfig: ProviderConfig): LanguageModel;
+declare function getContextWindow(providerName: ProviderName, modelId: string): number | undefined;
+declare function calculateContextWindowUsage(usage: Usage, contextWindow: number): number;
+
+declare function run(runInput: RunParamsInput, options?: {
+    shouldContinueRun?: (setting: RunSetting, checkpoint: Checkpoint, step: Step) => Promise<boolean>;
+    retrieveCheckpoint?: (checkpointId: string) => Promise<Checkpoint>;
+    storeCheckpoint?: (checkpoint: Checkpoint, timestamp: number) => Promise<void>;
+    eventListener?: (event: RunEvent | RuntimeEvent) => void;
+}): Promise<Checkpoint>;
+declare function getRunDir(runId: string): string;
 
 declare class SkillManager {
     protected _toolDefinitions: ToolDefinition[];
@@ -17,7 +29,9 @@ declare class SkillManager {
     private _mcpClient?;
     private _params;
     private _env;
-    constructor(params: SkillManagerParams);
+    private _runId;
+    private _eventListener?;
+    constructor(params: SkillManagerParams, runId: string, eventListener?: (event: RunEvent | RuntimeEvent) => void);
     init(): Promise<void>;
     isInitialized(): boolean;
     private _performInit;
@@ -5351,18 +5365,6 @@ declare const StateMachineLogics: Record<Exclude<RunSnapshot["value"], "Stopped"
 type RunActor = ActorRefFrom<typeof runtimeStateMachine>;
 type RunSnapshot = SnapshotFrom<typeof runtimeStateMachine>;
 
-declare function run(runInput: RunParamsInput, options?: {
-    shouldContinueRun?: (setting: RunSetting, checkpoint: Checkpoint, step: Step) => Promise<boolean>;
-    retrieveCheckpoint?: (checkpointId: string) => Promise<Checkpoint>;
-    storeCheckpoint?: (checkpoint: Checkpoint, timestamp: number) => Promise<void>;
-    eventListener?: (event: RunEvent) => Promise<void>;
-}): Promise<Checkpoint>;
-declare function getRunDir(runId: string): string;
-
-declare function getModel(modelId: string, providerConfig: ProviderConfig): LanguageModel;
-declare function getContextWindow(providerName: ProviderName, modelId: string): number | undefined;
-declare function calculateContextWindowUsage(usage: Usage, contextWindow: number): number;
-
-declare function defaultEventListener(e: RunEvent): Promise<void>;
+declare const RUNTIME_VERSION: string;
 
-export { type RunActor, type RunSnapshot, StateMachineLogics, calculateContextWindowUsage, defaultEventListener, getContextWindow, getModel, getRunDir, run, runtimeStateMachine };
+export { RUNTIME_VERSION, type RunActor, type RunSnapshot, StateMachineLogics, calculateContextWindowUsage, getContextWindow, getModel, getRunDir, run, runtimeStateMachine };