psadk 1.4.7 → 1.4.8

package/README.md

@@ -14,6 +14,7 @@ $ npm install psadk
 
 - **Multi-Provider LLM Support**: OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI, and more
 - **A2A Protocol Compatible**: Build agents that work with the Agent-to-Agent protocol
+- **Local Agent Mode**: Run agents fully in-process via `agent-core` — no PS API dependency required
 - **Prompt Caching**: Reduce costs and latency with built-in prompt caching support (90% cost reduction!)
 - **Custom Tools**: Create and integrate custom tools with your agents
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
@@ -25,6 +26,93 @@ The classes are documented here [Documentation](./globals.md)
 
 **New:** [Prompt Caching Guide](./docs/PROMPT_CACHING.md) - Learn how to reduce costs and latency by 90% with prompt caching
 
+**New:** [Local Agent Mode](#local-agent-mode) - Run agents in-process without the PS API
+
+## Local Agent Mode
+
+PSAgent now supports a **local execution mode** that runs the agent fully in-process using `agent-core`, bypassing the PS API entirely. 
+
+LLM calls are routed through the PS LLM API — only the agent orchestration loop runs locally.
+
+### Enabling Local Mode
+
+Set `local: true` in your `PSAgentConfig` and add an `llm` entry to `ServiceUrls` pointing at your PS API base URL:
+
+```typescript
+import { PSAgent, PSAgentLogger } from 'psadk';
+import type { LocalAgentEvent } from 'psadk';
+
+const agent = new PSAgent(
+  {
+    name: 'MyAgent',
+    description: 'A local agent',
+    instruction: 'You are a helpful assistant.',
+    model: 'gpt-4o-mini',
+    token: process.env.PS_API_TOKEN,
+    local: true,                    // ← enable local mode
+    onEvent: (event: LocalAgentEvent) => {
+      console.log(event.agentStatus, event.output?.response ?? event.message ?? '');
+    },
+  },
+  new PSAgentLogger({ prefix: 'MyAgent' }),
+  {
+    agents: 'https://dev.lionis.ai',
+    events: 'https://dev.lionis.ai',
+    llm: 'https://dev.lionis.ai',   // ← LLM API base URL for local mode
+  },
+);
+
+const result = await agent.start({ query: 'Hello!' });
+console.log(result);
+```
+
+### Local Agent Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `local` | `boolean` | `false` | Run the agent in-process via `agent-core` instead of the PS API |
+| `onEvent` | `(event: LocalAgentEvent) => void` | — | Callback invoked for each streamed event during local execution |
+| `ServiceUrls.llm` | `string` | agents URL | Base URL for the PS LLM API (e.g. `https://dev.lionis.ai`) |
+| `llm_config.reasoning_effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | — | Controls model reasoning: `medium`/`high` → `reasoning: true`; `low`/`minimal` → `reasoning: false` |
+| `llm_config.context_window` | `number` | `128000` | Context window size in tokens passed to the local agent runtime |
+| `llm_config.max_completion_tokens` | `number` | `4096` | Max output tokens for the model |
+
+### LocalAgentEvent Shape
+
+```typescript
+interface LocalAgentEvent {
+  agentStatus: 'pending' | 'in-progress' | 'waiting' | 'completed' | 'failed';
+  timestamp: number;        // Unix timestamp (ms)
+  tool?: string;            // Present when agentStatus === 'waiting'
+  toolInput?: { request_body: Record<string, any> }; // Tool input arguments
+  output?: { response: string; [key: string]: any }; // Present on 'completed'
+  message?: string;         // Present on 'failed' or 'in-progress'
+}
+```
+
+### Behaviour Differences in Local Mode
+
+| Operation | Remote mode | Local mode |
+|-----------|-------------|------------|
+| `start()` | Submits task to PS API | Runs agent-core loop in-process |
+| `resume()` | Sends tool output to PS API | No-op (tools execute in-process) |
+| `cancel()` | Calls PS API cancel endpoint | Calls `agent.abort()` on the in-process agent |
+| `getEvents()` | Polls PS events API | Returns in-memory event log snapshot |
+
+### Running the Local Agent Example
+
+```bash
+# Build first
+npm run build
+
+# Run the example
+PS_API_TOKEN=<token> PS_API_URL=https://dev.lionis.ai npm run local-agent-test
+```
+
+See [`examples/local-agent-test.ts`](./examples/local-agent-test.ts) for a full working example with tools and event streaming.
+
+---
+
 ## Agent Core Module
 
 The `agent-core` module provides a low-level, event-driven agent runtime built on `@earendil-works/pi-ai`. This module is designed for advanced use cases where you need fine-grained control over agent execution, tool calling, and message handling.
@@ -322,6 +410,71 @@ export const movie_search_tool = new PSAgentTool({
 });
 ```
 
+#### local agent - run agent in-process with event streaming
+
+```typescript
+import { PSAgent, PSAgentLogger } from 'psadk';
+import type { LocalAgentEvent } from 'psadk';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+  const token = process.env.PS_API_TOKEN!;
+  const baseUrl = process.env.PS_API_URL || 'https://dev.lionis.ai';
+
+  const agent = new PSAgent(
+    {
+      name: 'LocalHelloAgent',
+      description: 'A simple agent running in local mode',
+      instruction: 'You are a friendly assistant that greets users.',
+      model: 'gpt-4o-mini',
+      token,
+      local: true,                         // run agent-core in-process
+      llm_config: {
+        reasoning_effort: 'high',          // 'medium'|'high' → reasoning: true; 'low'|'minimal' → reasoning: false
+        context_window: 128000,            // token context window (default: 128000)
+        max_completion_tokens: 4096,       // max output tokens (default: 4096)
+      },
+      onEvent: (event: LocalAgentEvent) => {
+        switch (event.agentStatus) {
+          case 'pending':
+            console.log('⏳ Agent starting...');
+            break;
+          case 'in-progress':
+            console.log('🔄 Agent thinking...');
+            break;
+          case 'waiting':
+            console.log(`🔧 Calling tool: ${event.tool}`);
+            console.log('   Input:', JSON.stringify(event.toolInput?.request_body));
+            break;
+          case 'completed':
+            console.log('✅ Done:', event.output?.response);
+            break;
+          case 'failed':
+            console.error('❌ Failed:', event.message);
+            break;
+        }
+      },
+    },
+    new PSAgentLogger({ prefix: 'LocalHelloAgent' }),
+    {
+      agents: baseUrl,
+      events: baseUrl,
+      llm: baseUrl,                        // LLM calls route through PS LLM API
+    },
+  );
+
+  const result = await agent.start({ query: 'Say hello!' });
+  console.log('Result:', result);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
 ### Client: Sending a Message
 
 The A2AClient makes it easy to communicate with any A2A-compliant agent.

package/build/main/lib/PSAgent.d.ts

@@ -9,6 +9,10 @@ export interface ServiceUrls {
     agents?: string;
     events?: string;
     llmtrack?: string;
+    /** Base URL for the PS LLM API. Used in local mode to route LLM calls in-process.
+     *  e.g. 'https://dev.lionis.ai' — the /api/v1/llm path is appended automatically.
+     *  Defaults to the agents service base URL when not specified. */
+    llm?: string;
 }
 export declare function sleep(ms: number): Promise<void>;
 /**
@@ -63,6 +67,8 @@ export declare class PSAgent implements AgentExecutor {
     private readonly log?;
     private serviceUrls?;
     private cancelledTasks;
+    private localAgent?;
+    private localEventLog;
     cancelTask: (taskId: string) => Promise<void>;
     /**
      * create a new PSAgent with the given config
@@ -232,6 +238,35 @@ export declare class PSAgent implements AgentExecutor {
      * @returns
      */
     execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+    /**
+     * Translate an agent-core AgentEvent into a LocalAgentEvent.
+     * Returns undefined for events that don't need to be surfaced.
+     */
+    private translateAgentEvent;
+    /**
+     * Wrap a PSAgentTool as an agent-core AgentTool.
+     * The JSON Schema requestBody is passed as parameters directly—agent-core's
+     * validateToolArguments handles plain JSON Schema without TypeBox conversion.
+     */
+    private bridgePSToolToAgentTool;
+    /**
+     * Build a single-text user AgentMessage from a start() input object.
+     */
+    private buildUserMessage;
+    /**
+     * Convert history entries (remote format) to AgentMessage[] for agent-core.
+     */
+    private buildHistoryMessages;
+    /**
+     * Local start() path — runs agent-core in-process.
+     * Non-blocking: kicks off the loop and returns a synthetic correlation ID immediately.
+     */
+    private startLocal;
+    /**
+     * Local execute() path — A2A AgentExecutor using agent-core streaming.
+     * Publishes TaskStatusUpdateEvents to the eventBus as events arrive, without polling.
+     */
+    private executeLocal;
     private getHostIPAddress;
     /**
      * Port for A2A express server