Terminals AI Agent Orchestrator (OpenRouter Backend)

[LATEST INFO – 2025-08-26] Operation is configurable via the MODE environment variable: - AGENT: Utilizes a singular control function (agent) for abstracting research, follow-up, data retrieval, and querying tasks. - MANUAL: Exposes discrete, atomic functions for every possible operation. - ALL (Default): Combines AGENT mode functionality with all individual MANUAL tools, plus persistent operational utilities.

Architectural Flow Summary

[Core Utilities] status_check • query_server_health • monitor_job • halt_job

AGENT PATH Client Invocation → agent → (investigate | refine | fetch_context | ask_question)

MANUAL PATH Client Invocation → (initiate_investigation | execute_investigation | fetch_context | ask_question | iterative_refinement | extract_final_document | enumerate_history)

Core Capabilities: - Workflow Blueprinting → Concurrent Decomposition → Synthesis Engine utilizing bounded parallelism. - Fluid Model Selection Registry; natively supports Anthropic Sonnet‑4 and next-gen OpenAI GPT‑5 series. - Integrated Semantic Repository (PostgreSQL/pgvector) featuring persistence, migration utilities, integrity checks, and vector reconstruction. - Lightweight Web Interface tools: rapid data fetching and web context acquisition. - Resilient event streaming (SSE), per-session authentication enforcement, and verbose logging control.

Deployment & Startup

• Local Project Dependency Installation bash npm install @terminals-tech/openrouter-agents

• Global Installation (Optional) bash npm install -g @terminals-tech/openrouter-agents

• Execution via npx (No persistent install required) bash npx @terminals-tech/openrouter-agents --stdio

Or run as persistent service (daemon)

SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents

Recent Changes (v1.5.0)

• Uniform versioning across npm registry, binary releases, and GitHub artifacts.
• Activation of dual publication pipeline.

Full History Log →

Getting Started Guide

1) Prerequisites - Node.js version 18 or newer (20 LTS advised), npm client, Git utility, Valid OpenRouter API credential

2) Installation bash npm install

3) Configuration (via .env file) dotenv OPENROUTER_API_KEY=your_openrouter_key SERVER_API_KEY=your_http_transport_key SERVER_PORT=3002

Operational Modes (select one; ALL is default)

AGENT = primary interface + system utilities (health/job monitoring)

MANUAL = atomic toolset + system utilities

ALL = AGENT + atomic tools + system utilities

MODE=ALL

Orchestration Parameters

ENSEMBLE_SIZE=2 PARALLELISM=4

Model Configuration (Fine-tune cost/capability tiers)

PLANNING_MODEL=openai/gpt-5-chat PLANNING_CANDIDATES=openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4 HIGH_COST_MODELS=x-ai/grok-4,openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4,morph/morph-v3-large LOW_COST_MODELS=deepseek/deepseek-chat-v3.1,z-ai/glm-4.5v,qwen/qwen3-coder,openai/gpt-5-mini,google/gemini-2.5-flash VERY_LOW_COST_MODELS=openai/gpt-5-nano,deepseek/deepseek-chat-v3.1

Local Database Settings

PGLITE_DATA_DIR=./researchAgentDB PGLITE_RELAXED_DURABILITY=true REPORT_OUTPUT_PATH=./research_outputs/

Indexing Service

INDEXER_ENABLED=true INDEXER_AUTO_INDEX_REPORTS=true INDEXER_AUTO_INDEX_FETCHED=true

MCP Integration Flags

MCP_ENABLE_PROMPTS=true MCP_ENABLE_RESOURCES=true

Prompt Generation Style

PROMPTS_COMPACT=true PROMPTS_REQUIRE_URLS=true PROMPTS_CONFIDENCE=true

4) Execution - Standard I/O Transport (Optimal for IDE/Cursor integration): bash node src/server/mcpServer.js --stdio

• HTTP/SSE Transport (For standalone service): bash SERVER_API_KEY=$SERVER_API_KEY node src/server/mcpServer.js

Windows PowerShell Examples

• STDIO Mode powershell $env:OPENROUTER_API_KEY='your_key' $env:INDEXER_ENABLED='true' node src/server/mcpServer.js --stdio

• HTTP/SSE Mode powershell $env:OPENROUTER_API_KEY='your_key' $env:SERVER_API_KEY='devkey' $env:SERVER_PORT='3002' node src/server/mcpServer.js

Concise Runtime Scripts (One-liners)

Dev (HTTP/SSE): bash SERVER_API_KEY=devkey INDEXER_ENABLED=true node src/server/mcpServer.js

STDIO (IDE Integration): bash OPENROUTER_API_KEY=your_key INDEXER_ENABLED=true node src/server/mcpServer.js --stdio

MCP Manifest JSON Registration (Zero Manual Startup)

You can embed this configuration directly into MCP-compliant client settings files.

1) STDIO Communication (Recommended for IDEs)

{ "servers": { "openrouter-agents": { "command": "npx", "args": ["@terminals-tech/openrouter-agents", "--stdio"], "env": { "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}", "SERVER_API_KEY": "${SERVER_API_KEY}", "PGLITE_DATA_DIR": "./researchAgentDB", "INDEXER_ENABLED": "true" } } } }

2) HTTP/SSE Link (Daemon Mode)

{ "servers": { "openrouter-agents": { "url": "http://127.0.0.1:3002", "sse": "/sse", "messages": "/messages", "headers": { "Authorization": "Bearer ${SERVER_API_KEY}" } } } }

Once the package is globally available or referenced via npx, clients can auto-spawn the service based on this JSON manifest (Consult your client documentation for the precise location of the configuration file, e.g., ~/.config/client/mcp.json).

Available Toolset (Key Utilities)

• Persistent Utilities (All Modes): ping, query_server_health, monitor_job, get_job_status, halt_job
• AGENT Gateway: agent (Unified access for investigation, refinement, context retrieval, and direct query execution)
• Atomic Toolset (MANUAL/ALL): initiate_investigation (Asynchronous), execute_investigation (Synchronous/Streaming), iterative_refinement, search (Hybrid search mode), fetch_context (Index/SQL wrapper), ask_question (Read-only SQL execution), extract_final_document, enumerate_history
• Job Control: get_job_status, halt_job
• Context Retrieval: search (Integrated BM25 + vector search with optional LLM refinement pass), fetch_context (DB/SQL accessor)
• Database Operations: query (SELECT statements only; optional explain plan), export_db_backup (tar.gz format), export_artifacts, import_artifacts, db_integrity_check, rebuild_vector_index
• Metadata: list_models
• Web Access: search_web, fetch_url_content
• Indexing Engine: index_text_data, index_remote_url, search_local_index, indexer_health_report

LLM Interaction Blueprints (Tool Usage)

Consult the tool_patterns resource for structured JSON recipes demonstrating effective operational sequences, such as: - Web Crawl → Contextual Extraction → Core Investigation - Asynchronous research: Initiate job, monitor progress via SSE /jobs/:id/events, then retrieve final output.

Notes on Persistence: - Data storage defaults to PGLITE_DATA_DIR (./researchAgentDB). Backups reside in ./backups. - Use list_models to dynamically catalog available provider capabilities and IDs.

System Blueprint Overview

Refer to docs/diagram-architecture.mmd (Mermaid format). To visualize, use Mermaid CLI: bash npx @mermaid-js/mermaid-cli -i docs/diagram-architecture.mmd -o docs/diagram-architecture.svg

Or use the integrated script: bash npm run gen:diagram

If rendering fails in your local tool, open docs/diagram-architecture-branded.svg directly.

Final Output Crystallization View

Distinction from Standard Agent Architectures: - Beyond simple function chaining; incorporates dynamic plan generation, parallel execution across specialized agents, and a synthesis step that resolves conflicts, identifies consensus, and flags knowledge gaps. - Persistent Indexing: Data encountered during research is indexed immediately, accelerating future context lookups. - Failsafe Mechanism: Strict guardrails mandate verifiable source citations, use of the [Unverified] tag when necessary, and explicit confidence scoring.

Minimal Token Prompting Strategy

• Compact mode strips boilerplate text, retaining only core directives; supplementary context is inferred.
• Mandatory Directives: Requires precise URL citations, prohibits assumptions regarding resource IDs/URLs, and mandates confidence labeling.
• Tool Specification Efficiency: Employs minimal parameter names, leveraging server defaults where possible.

Typical Operational Scenarios

• “Deliver a summary briefing on the status of MCP infrastructure as of mid-2025.”
• System generates sub-tasks, retrieves data from authoritative endpoints, and synthesizes the report with verifiable citations.

• Previously indexed findings expedite subsequent follow-up inquiries.

• “Identify models supporting visual inputs and route image processing requests appropriately.”

• Utilizes /models to filter capabilities, constructs a specific routing template, with graceful fallback mechanisms to text-only models if vision support is absent.

• “Contrast orchestration paradigms supporting bounded concurrency.”

• Gathers documentation from OTel/Airflow/Temporal sources, generating a Mutually Exclusive Collectively Exhaustive (MECE) synthesis including relevant code snippets.

Cursor IDE Integration

• Configure this server in Cursor's MCP settings, pointing the executable path to node src/server/mcpServer.js --stdio.
• Leverage new prompt templates (planning_prompt, synthesis_prompt) within Cursor to rapidly scaffold complex investigative procedures.

Frequently Asked Questions (Quick Reference)

• Hallucination Mitigation: Achieved via rigorous citation mandates, use of [Unverified] tags, reuse of past indexed knowledge, and real-time indexing.
• Feature Toggling: All functionalities are controllable via the environment variables listed previously.
• Streaming Support: Fully supported via Server-Sent Events (SSE) for HTTP connections and directly over stdio for MCP clients.

Function Map (Quick Reference)

• Bootstrap (stdio): npm run stdio
• Bootstrap (HTTP/SSE): npm start
• Execute via npx (Scoped): npx @terminals-tech/openrouter-agents --stdio
• Generate Demos: npm run gen:examples
• Catalog Models: MCP call list_models { refresh:false }
• Initiate Research (Async): initiate_investigation { objective:"<query>", cost_preference:"low", audience:"intermediate", format:"report", include_sources:true }
• Monitor Job: get_job_status { job_id:"..." }, Cancel: halt_job { job_id:"..." }
• Unified Search: search { q:"<query>", limit:10, scope:"all" }
• Read-Only SQL: query { sql:"SELECT ... WHERE id = $1", params:[1], analyze:true }
• Retrieve Prior Work: get_past_research { criteria:"<query>", max_results:5 }
• Index URL (if active): index_remote_url { url:"https://..." }
• Management UI (Localhost): Navigate to http://localhost:3002/ui to view real-time job event streams (SSE).

Package Deployment Details

• Package Identifier: @terminals-tech/openrouter-agents
• Current Version: 1.3.2
• Executable Entry: openrouter-agents
• Maintainer: Tej Desai admin@terminals.tech
• Project Site: https://terminals.tech

Execute without local cloning: bash npx @terminals-tech/openrouter-agents --stdio

Or daemon mode

SERVER_API_KEY=your_key npx @terminals-tech/openrouter-agents

Scoped Publishing Sequence

bash npm login npm version 1.3.2 -m "chore(release): %s" git push --follow-tags npm publish --access public --provenance

Validation Protocol – MSeeP (Multi-Source Evidence & Evaluation Protocol)

• Citation Mandate: Requires verifiable URLs and confidence classifications; ambiguous data is flagged as [Unverified].
• Model Triangulation: The planning phase disseminates tasks across disparate models; synthesis assesses agreement versus conflicting data points.
• Knowledge Base Grounding: Utilizes a local hybrid index (BM25 + vector similarity) to retrieve historical context for verification.
• User Feedback Integration: Results are logged via rate_research_report { rating, comment }, which is stored to refine subsequent iterative tasks.
• Auditability: Functions like export_artifacts and export_db_backup ensure all research components are captured for inspection.

Quality Enhancement Feedback Cycle

• Execute Demos: npm run gen:examples
• Review Context: enumerate_history, extract_final_document {reportId}
• Provide Rating: rate_research_report { reportId, rating:1..5, comment }
• Optimize Retrieval: rebuild_vector_index, indexer_health_report, search_local_index { query }

Branded Architectural Visualization

• The official diagram is located at docs/diagram-architecture-branded.svg (The logo links back to https://terminals.tech).

Repository Popularity

OVERVIEW: XMLHttpRequest (XHR) is a JavaScript object API designed to facilitate HTTP requests between a client web browser and a remote server. This capability allows browser-based applications to initiate server communications and receive data asynchronously, post-page load, forming the foundation of Ajax techniques. Before Ajax, interaction relied mainly on traditional page refreshes triggered by form submissions or hyperlink clicks.

== Genesis == The conceptual basis for XMLHttpRequest originated in 2000 with Microsoft Outlook developers. It was first integrated into Internet Explorer 5 (1999), though initially utilizing non-standard identifiers like ActiveXObject("Msxml2.XMLHTTP"). By Internet Explorer 7 (2006), full support for the standard XMLHttpRequest identifier was achieved. This identifier has since become the universal standard across all major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) released the initial Working Draft for the XMLHttpRequest object specification on April 5, 2006. A subsequent Level 2 draft, introducing features for cross-site requests, event progress monitoring, and byte stream handling, was published on February 25, 2008. Level 2 features were eventually merged back into the primary specification by late 2011. Development stewardship transitioned to WHATWG in late 2012, which now maintains the living document using Web IDL definitions.

== Operational Flow == Executing a transmission via XMLHttpRequest typically requires several sequential programming actions.

1. Instantiate the XHR object via its constructor.
2. Invoke the "open" method to define the request method (GET/POST, etc.), specify the target resource URI, and select either synchronous or asynchronous execution mode.
3. For asynchronous modes, attach an event listener to monitor state changes.
4. Begin the transmission by calling the "send" method, optionally including payload data.
5. Process state transitions within the event listener. Upon successful server response, data is typically held in the "responseText" property. Completion is signaled when the object reaches state 4 ("done"). Beyond these core steps, XHR allows for fine-grained control: custom headers can be injected, data can be uploaded in the "send" call, responses can be immediately parsed from JSON into native JavaScript objects, or processed incrementally as they arrive. Requests can also be prematurely halted or subjected to a timeout.

== Cross-Origin Transactions == In the early stages of the World Wide Web's evolution, restrictions were imposed that severely limited interactions betw