open-agents-ai 0.62.0 → 0.63.0

package/README.md

@@ -40,6 +40,7 @@ An autonomous multi-turn tool-calling agent that reads your code, makes changes,
 - **Autoresearch Swarm** — 5-agent GPU experiment loop during REM sleep: Researcher, Monitor, Evaluator, Critic, Flow Maintainer autonomously run ML training experiments, keep improvements, discard regressions
 - **Live Listen** — bidirectional voice communication with real-time Whisper transcription
 - **Live Voice Session** — `/listen` with `/voice` enabled spawns a cloudflared tunnel with a real-time WebSocket audio endpoint. A floating presence UI shows live transcription, connected users, and audio visualization. Echo cancellation prevents TTS feedback loops
+- **Call Sub-Agent** — each WebSocket caller gets a dedicated AgenticRunner for low-latency voice-to-voice loops, with admin/public access tiers and bidirectional activity sharing with the main agent
 - **Telegram Voice** — `/voice` enabled via Telegram forwards TTS audio as voice messages alongside text responses. Incoming voice messages are auto-transcribed and handled as text
 - **Neural TTS** — hear what the agent is doing via GLaDOS or Overwatch ONNX voices, with personality-driven expressiveness
 - **Personality Core** — SAC framework-based style control (concise/balanced/verbose/pedagogical) that shapes agent response depth, voice expressiveness, and system prompt behavior
@@ -518,7 +519,7 @@ The agent stack includes a real-time emotion system that modulates behavior base
 - **Valence** (-1 to +1): displeasure ↔ pleasure
 - **Arousal** (0 to 1): calm ↔ energized
 
-Every agent event (tool success/failure, task completion, errors, context pressure) is appraised and shifts the emotional state, which decays back toward a baseline over ~60 seconds. The emotional state modulates agent behavior:
+Every agent event (tool success/failure, task completion, errors, context pressure) is appraised and shifts the emotional state, which decays back toward a baseline over ~5 minutes. The emotional state modulates agent behavior across all layers: system prompt behavioral hints, voice narration tone, and decision-making style:
 
 | Quadrant | Valence | Arousal | Behavioral Effect |
 |----------|---------|---------|-------------------|
@@ -853,19 +854,31 @@ The TUI features an animated multilingual phrase carousel, live metrics bar with
 
 All settings commands accept `--local` to save to project `.oa/settings.json` instead of global config.
 
-### Mid-Task Steering
+### Mid-Task Steering (Sub-Agent Architecture)
 
-While the agent is working (shown by the `+` prompt), type to add context:
+While the agent is working (shown by the `+` prompt), type to add context. A **dedicated steering sub-agent** spins up in the background to process your input:
+
+1. **Immediate acknowledgment** — the steering agent speaks a brief response via TTS (e.g., "Got it, I'll adjust the approach")
+2. **Context expansion** — your terse input is expanded into a structured steering instruction grounded in the current task goal and recent agent activity
+3. **Non-blocking injection** — the expanded instruction is injected into the main agent's context at the next turn boundary, without interrupting the current tool call
 
 ```
 > fix the auth bug
   ⎿  Read: src/auth.ts
 + also check the session handling        ← typed while agent works
-  ↪ Context added: also check the session handling
+  🔊 "Got it, adjusting to include session handling"
+  ↪ USER STEERING: Check session handling in addition to auth...
   ⎿  Search: session
   ⎿  Edit: src/auth.ts
 ```
 
+The steering sub-agent uses the same model and backend as the main agent with `maxTurns: 3` and `maxTokens: 512` for fast response. If the steering agent fails, the raw input is injected as a fallback.
+
+**Research foundations:**
+- **ReAct** (Yao et al., 2023) — interleaved reasoning + acting benefits from external course corrections grounded in current state
+- **LATS** (Zhou et al., 2024) — mid-execution replanning with user-provided value signals improves task completion on complex multi-step problems
+- **AutoGen** (Wu et al., 2023) — human-in-the-loop patterns work best when user messages are expanded into structured instructions, reducing ambiguity for the primary agent
+
 ## Tools (47)
 
 | Tool | Description |
@@ -1051,6 +1064,34 @@ When `/voice` is enabled and the Telegram bridge is active:
 
 Cloudflared is automatically installed at startup alongside other dependencies (moondream, tesseract, transcribe-cli). The install is non-blocking and runs in the background.
 
+### Call Sub-Agent Architecture
+
+Each WebSocket caller in a live voice session gets a **dedicated AgenticRunner** — a fully independent agent instance that handles the voice-to-text-to-LLM-to-TTS-to-reply pipeline with minimal latency.
+
+**Access tiers** — callers connect at one of two privilege levels:
+
+| Tier | URL | Tool Access | Max Turns |
+|------|-----|-------------|-----------|
+| **Admin** | `wss://…?key=<session-key>` | Full tool set (12 tools: file read/write/edit, shell, grep, glob, list directory, web search/fetch, memory read/write/search) | 15 |
+| **Public** | `wss://…` (no key) | Read-only tools (6 tools: file read, grep, glob, list directory, memory read/search) | 5 |
+
+The **session key** is a `crypto.randomBytes(16)` hex string generated per TUI session and displayed in the terminal when the voice session starts. Passing it as the `?key=` URL parameter on the WebSocket connection upgrades the caller to admin access.
+
+**ActivityFeed** — the main TUI agent and all call sub-agents share a bidirectional ring buffer (max 100 entries). Tool calls and results from call sub-agents surface in the main terminal waterfall, and the main agent's activity is visible to connected callers. Each entry carries timestamp, source (main/call), sourceId, tool name, success status, and a summary. Admin callers see verbose timestamped activity; public callers see surface-level summaries.
+
+**Per-client lifecycle** — on WebSocket connect, a `CallSubAgent` is instantiated with its own `AgenticRunner`, `OllamaAgenticBackend`, and conversation history. Transcripts are queued FIFO if the agent is mid-response, ensuring nothing is dropped. On disconnect, the sub-agent is disposed and removed from the active client map.
+
+### Content-Aware Voice Narration
+
+The stochastic narration engine generates spoken descriptions of what the agent is doing for TTS output. Instead of preset phrases, it uses:
+
+- **Variant pools** — 6-10 phrasings per tool per personality tier (terse/conversational/chatty), selected randomly with no back-to-back repeats
+- **Context modifiers** — tracks session state (consecutive errors, file revisits, progress beats) to add natural transitions like "Third time's the charm" or "Coming back to"
+- **Content digests** — extracts key details from actual tool result content (ETH balances, test results, error messages, wallet addresses, status tags, version numbers) and weaves them into the spoken narration. Instead of "Got it", the agent says "Got it — 2.5 ETH, address 0x9fe7F838..." or "That worked, 42 tests passed"
+- **Cross-tool context** — the digest from a tool result optionally carries forward into the next tool call description, so the agent can say "Checking that file, following up on 2.5 ETH" instead of repeating a generic opener
+- **Personality scaling** — terse mode (level 1-2) uses short functional descriptions; conversational (3) adds natural phrasing; chatty (4-5) adds theatrical commentary and content references
+- **Natural silence** — on bland successes without notable content, ~40% of the time the narration is skipped entirely for a more natural rhythm
+
 ## Personality Core — SAC Framework Style Control
 
 The personality system controls how the agent communicates — from silent operator to teacher mode. It's based on the **SAC framework** (arXiv:2506.20993) which models personality along five behavioral intensity dimensions rather than binary trait toggles.

package/dist/index.d.ts

@@ -1,59 +1,6 @@
-#!/usr/bin/env node
-/**
- * index.ts — Main CLI entry point for @open-agents/cli
- *
- * Routes CLI arguments to the appropriate command handler.
- *
- * Commands:
- *   open-agents "task"                    implicit run
- *   open-agents run "task"                explicit run
- *   open-agents index /path/to/repo       index a repository
- *   open-agents status                    show system status
- *   open-agents config                    show config
- *   open-agents config set KEY VALUE      set config key
- *   open-agents serve                     start vLLM server
- *   open-agents eval                      run eval suite
- *   open-agents --help                    help
- *   open-agents --version                 version
- */
-import type { BackendType } from "./config.js";
-export type CommandName = "run" | "index" | "status" | "config" | "serve" | "eval" | "unknown";
-export interface ParsedCliArgs {
-    command: CommandName;
-    /** Task text for the run command */
-    task?: string;
-    /** Repository path (for run and index commands) */
-    repoPath?: string;
-    /** Config sub-command (e.g. "set", "keys") */
-    configSubCommand?: string;
-    /** Config key (for config set) */
-    configKey?: string;
-    /** Config value (for config set) */
-    configValue?: string;
-    /** Eval suite name */
-    evalSuite?: string;
-    /** vLLM server port for serve command */
-    servePort?: number;
-    model?: string;
-    backendUrl?: string;
-    backendType?: BackendType;
-    dryRun?: boolean;
-    verbose?: boolean;
-    maxRetries?: number;
-    timeoutMs?: number;
-    offline?: boolean;
-    /** When true, config set writes to .oa/settings.json (project-local) */
-    local?: boolean;
-    help?: boolean;
-    version?: boolean;
-}
-export declare function routeCommand(command: string): CommandName;
-export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
-export { createCli } from "./cli.js";
-export { parseArgs } from "./args.js";
-export type { CliOptions } from "./types.js";
-export { loadConfig, mergeConfig, setConfigValue, DEFAULT_CONFIG } from "./config.js";
-export type { AgentConfig, BackendType } from "./config.js";
-export { Spinner } from "./ui/spinner.js";
-export { printHeader, printSuccess, printError, printWarning, printInfo, printSection, printKeyValue, printBlank, printReport, formatDuration, } from "./ui/output.js";
-//# sourceMappingURL=index.d.ts.map
+export { parseCliArgs, routeCommand } from "./types.js";
+export type { ParsedCliArgs, CommandName } from "./types.js";
+export { loadConfig, mergeConfig, setConfigValue, DEFAULT_CONFIG } from "./types.js";
+export type { AgentConfig, BackendType } from "./types.js";
+export { Spinner } from "./types.js";
+export { printHeader, printSuccess, printError, printWarning, printInfo, printSection, printKeyValue, printBlank, printReport, formatDuration } from "./types.js";