xerxes-agent 0.2.0__py3-none-any.whl

xerxes/__init__.py

@@ -0,0 +1,210 @@
+# Copyright 2026 The Xerxes-Agents Author @erfanzar (Erfan Zare Chavoshi).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Public surface of the Xerxes-Agents package.
+
+Re-exports the core API used by external code and integrators: the
+``Xerxes`` facade, agent orchestration (``Cortex`` and friends), LLM
+provider classes and helpers, MCP integration, memory store types,
+streaming primitives, runtime configuration, and the message/agent
+type system. The ``__all__`` tuple is the authoritative list of names
+considered part of the stable public API.
+"""
+
+from .core import PromptTemplate
+from .core.streamer_buffer import StreamerBuffer
+from .cortex import (
+    ChainLink,
+    ChainType,
+    Cortex,
+    CortexAgent,
+    CortexMemory,
+    CortexOutput,
+    CortexTask,
+    CortexTaskOutput,
+    CortexTool,
+    ProcessType,
+)
+from .executors import AgentOrchestrator
+from .llms import (
+    COSTS,
+    PROVIDERS,
+    AnthropicLLM,
+    BaseLLM,
+    CustomLLM,
+    DeepSeekLLM,
+    GeminiLLM,
+    KimiLLM,
+    LLMConfig,
+    LMStudioLLM,
+    LocalLLM,
+    OllamaLLM,
+    OpenAICompatLLM,
+    OpenAILLM,
+    ProviderConfig,
+    QwenLLM,
+    ZhipuLLM,
+    calc_cost,
+    create_llm,
+    detect_provider,
+    get_context_limit,
+    list_all_models,
+)
+from .mcp import MCPClient, MCPManager, MCPResource, MCPServerConfig, MCPTool
+from .memory import MemoryEntry, MemoryStore, MemoryType
+from .operators.config import OperatorRuntimeConfig
+from .runtime.features import AgentRuntimeOverrides, RuntimeFeaturesConfig
+from .runtime.profiles import PromptProfile, PromptProfileConfig
+from .streaming import (
+    AgentState,
+    NeutralMessage,
+    PermissionMode,
+    PermissionRequest,
+    StreamEvent,
+    TextChunk,
+    ThinkingChunk,
+    ToolEnd,
+    ToolStart,
+    TurnDone,
+    check_permission,
+    messages_to_anthropic,
+    messages_to_openai,
+    run_agent_loop,
+)
+from .types import (
+    Agent,
+    AgentCapability,
+    AgentFunction,
+    AgentSwitch,
+    AgentSwitchTrigger,
+    AssistantMessage,
+    AssistantMessageType,
+    ChatMessageType,
+    Completion,
+    ExecutionResult,
+    ExecutionStatus,
+    FunctionCallInfo,
+    FunctionCallsExtracted,
+    FunctionCallStrategy,
+    FunctionDetection,
+    FunctionExecutionComplete,
+    FunctionExecutionStart,
+    MessagesHistory,
+    RequestFunctionCall,
+    Roles,
+    StreamChunk,
+    SwitchContext,
+    SystemMessage,
+    SystemMessageType,
+    ToolMessage,
+    ToolMessageType,
+    UserMessage,
+    UserMessageType,
+)
+from .xerxes import Xerxes
+
+__all__ = (
+    "COSTS",
+    "PROVIDERS",
+    "Agent",
+    "AgentCapability",
+    "AgentFunction",
+    "AgentOrchestrator",
+    "AgentRuntimeOverrides",
+    "AgentState",
+    "AgentSwitch",
+    "AgentSwitchTrigger",
+    "AnthropicLLM",
+    "AssistantMessage",
+    "AssistantMessageType",
+    "BaseLLM",
+    "ChainLink",
+    "ChainType",
+    "ChatMessageType",
+    "Completion",
+    "Cortex",
+    "CortexAgent",
+    "CortexMemory",
+    "CortexOutput",
+    "CortexTask",
+    "CortexTaskOutput",
+    "CortexTool",
+    "CustomLLM",
+    "DeepSeekLLM",
+    "ExecutionResult",
+    "ExecutionStatus",
+    "FunctionCallInfo",
+    "FunctionCallStrategy",
+    "FunctionCallsExtracted",
+    "FunctionDetection",
+    "FunctionExecutionComplete",
+    "FunctionExecutionStart",
+    "GeminiLLM",
+    "KimiLLM",
+    "LLMConfig",
+    "LMStudioLLM",
+    "LocalLLM",
+    "MCPClient",
+    "MCPManager",
+    "MCPResource",
+    "MCPServerConfig",
+    "MCPTool",
+    "MemoryEntry",
+    "MemoryStore",
+    "MemoryType",
+    "MessagesHistory",
+    "NeutralMessage",
+    "OllamaLLM",
+    "OpenAICompatLLM",
+    "OpenAILLM",
+    "OperatorRuntimeConfig",
+    "PermissionMode",
+    "PermissionRequest",
+    "ProcessType",
+    "PromptProfile",
+    "PromptProfileConfig",
+    "PromptTemplate",
+    "ProviderConfig",
+    "QwenLLM",
+    "RequestFunctionCall",
+    "Roles",
+    "RuntimeFeaturesConfig",
+    "StreamChunk",
+    "StreamEvent",
+    "StreamerBuffer",
+    "SwitchContext",
+    "SystemMessage",
+    "SystemMessageType",
+    "TextChunk",
+    "ThinkingChunk",
+    "ToolEnd",
+    "ToolMessage",
+    "ToolMessageType",
+    "ToolStart",
+    "TurnDone",
+    "UserMessage",
+    "UserMessageType",
+    "Xerxes",
+    "ZhipuLLM",
+    "calc_cost",
+    "check_permission",
+    "create_llm",
+    "detect_provider",
+    "get_context_limit",
+    "list_all_models",
+    "messages_to_anthropic",
+    "messages_to_openai",
+    "run_agent_loop",
+)
+
+__version__ = "0.2.0"

xerxes/__main__.py

@@ -0,0 +1,188 @@
+# Copyright 2026 The Xerxes-Agents Author @erfanzar (Erfan Zare Chavoshi).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""CLI entry point for the ``xerxes`` command.
+
+Dispatches between three modes:
+
+* ``xerxes telegram ...`` — start the daemon with the Telegram gateway
+  enabled (token via flag or ``TELEGRAM_BOT_TOKEN`` env var).
+* One-shot — a prompt provided as positional args or piped on stdin;
+  streams assistant text to stdout and exits.
+* Interactive — no prompt and stdin is a tty; launches ``XerxesTUI``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+
+def _resolve_one_shot_prompt(
+    prompt_parts: list[str],
+    *,
+    stdin_is_tty: bool,
+    stdin_text: str | None = None,
+) -> tuple[str, bool]:
+    """Decide whether to run one-shot and produce the prompt text.
+
+    Positional CLI args take precedence; if absent, non-tty stdin is
+    consumed. Returns ``(prompt, True)`` when the CLI should run
+    non-interactively, ``("", False)`` to open the TUI.
+    """
+    parts = list(prompt_parts)
+    if parts and parts[0] == "--":
+        parts = parts[1:]
+    if parts:
+        return " ".join(parts).strip(), True
+    if not stdin_is_tty:
+        text = sys.stdin.read() if stdin_text is None else stdin_text
+        return text.strip(), True
+    return "", False
+
+
+async def _run_one_shot(prompt: str, *, resume_session_id: str = "", mode: str = "code") -> None:
+    """Run one prompt against a spawned daemon and stream text to stdout.
+
+    Auto-rejects approval requests (no interactive UI) and surfaces
+    error notifications on stderr. Returns when ``TurnEnd`` is seen.
+    """
+    from .streaming.wire_events import ApprovalRequest, Notification, TextPart, TurnEnd
+    from .tui.engine import BridgeClient
+
+    client = BridgeClient()
+    wrote_text = False
+    try:
+        client.spawn()
+        await client.initialize(
+            permission_mode="accept-all",
+            resume_session_id=resume_session_id,
+        )
+        await client.query(prompt, plan_mode=mode == "plan", mode=mode)
+        async for event in client.events():
+            if isinstance(event, TextPart):
+                sys.stdout.write(event.text)
+                sys.stdout.flush()
+                wrote_text = True
+            elif isinstance(event, ApprovalRequest):
+                await client.permission_response(event.id, "reject")
+                print(
+                    f"Rejected permission request for {event.action}: non-interactive CLI has no approval UI.",
+                    file=sys.stderr,
+                )
+            elif isinstance(event, Notification) and event.severity == "error":
+                body = event.body or event.title
+                if body:
+                    print(body, file=sys.stderr)
+            elif isinstance(event, TurnEnd):
+                break
+        if wrote_text:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+    finally:
+        client.close()
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse ``argv`` and dispatch to telegram, one-shot, or TUI mode.
+
+    Imports the TUI lazily so that ``xerxes telegram`` and one-shot
+    paths avoid the heavy ``prompt_toolkit`` startup. Honours
+    ``KeyboardInterrupt`` quietly.
+    """
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "telegram":
+        telegram_parser = argparse.ArgumentParser(
+            prog="xerxes telegram", description="Start the daemon with Telegram enabled."
+        )
+        telegram_parser.add_argument("--token", default=os.environ.get("TELEGRAM_BOT_TOKEN", ""))
+        telegram_parser.add_argument("--project-dir", default="")
+        telegram_parser.add_argument("--host", default="")
+        telegram_parser.add_argument("--port", type=int, default=0)
+        telegram_args = telegram_parser.parse_args(argv[1:])
+        if telegram_args.token:
+            os.environ["TELEGRAM_BOT_TOKEN"] = telegram_args.token
+        os.environ["XERXES_DAEMON_ENABLE_TELEGRAM"] = "1"
+
+        from .daemon.config import load_config
+        from .daemon.server import DaemonServer
+
+        config = load_config(project_dir=telegram_args.project_dir)
+        if telegram_args.host:
+            config.ws_host = telegram_args.host
+        if telegram_args.port:
+            config.ws_port = telegram_args.port
+        asyncio.run(DaemonServer(config).run())
+        return
+
+    from .tui import XerxesTUI
+
+    parser = argparse.ArgumentParser(
+        prog="xerxes",
+        description="Xerxes — interactive AI agent in your terminal.",
+    )
+    parser.add_argument(
+        "-r",
+        "--resume",
+        metavar="SESSION_ID",
+        default="",
+        help="Resume a previous session by id (saved under ~/.xerxes/sessions).",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=("code", "researcher", "research", "plan"),
+        default="code",
+        help="Mode for one-shot prompts.",
+    )
+    parser.add_argument(
+        "--yolo",
+        action="store_true",
+        help="Ignored for one-shot prompts; they always use accept-all permissions.",
+    )
+    parser.add_argument(
+        "prompt",
+        nargs=argparse.REMAINDER,
+        help="Run a one-shot prompt instead of opening the TUI.",
+    )
+    args = parser.parse_args(argv)
+    prompt, one_shot = _resolve_one_shot_prompt(
+        args.prompt,
+        stdin_is_tty=sys.stdin.isatty(),
+    )
+
+    if one_shot:
+        if not prompt:
+            parser.error("empty prompt")
+        mode = "researcher" if args.mode == "research" else args.mode
+        try:
+            asyncio.run(_run_one_shot(prompt, resume_session_id=args.resume, mode=mode))
+        except KeyboardInterrupt:
+            pass
+        return
+
+    async def _run() -> None:
+        """Open the interactive TUI and await its lifecycle."""
+        tui = XerxesTUI(resume_session_id=args.resume)
+        async with tui:
+            await tui.wait_until_done()
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

xerxes/_compat_shims.py

@@ -0,0 +1,38 @@
+# Copyright 2026 The Xerxes-Agents Author @erfanzar (Erfan Zare Chavoshi).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Lightweight path helpers that avoid importing ``xerxes.core.paths``.
+
+Used by modules that participate in circular imports with the core
+paths module, or by plugin entry points where pulling the full path
+machinery would be too heavy. Mirrors the subset of behaviour needed
+by callers without the full configuration surface.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def xerxes_subdir_safe(*parts: str) -> Path:
+    """Resolve a path under ``$XERXES_HOME`` (default ``~/.xerxes``).
+
+    Does not create the directory or read any other configuration; the
+    caller is responsible for ``mkdir`` if persistence is required.
+    """
+    base = os.environ.get("XERXES_HOME") or str(Path.home() / ".xerxes")
+    return Path(base, *parts)
+
+
+__all__ = ["xerxes_subdir_safe"]

xerxes/acp/__init__.py

@@ -0,0 +1,39 @@
+# Copyright 2026 The Xerxes-Agents Author @erfanzar (Erfan Zare Chavoshi).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Agent Client Protocol (ACP) adapter package.
+
+Maps Xerxes's streaming/loop surface to the ACP interface that IDE
+clients (Claude Code, Cursor, Cline) speak. ACP is a young
+standard; the registry metadata + session adapter live here so the
+``xerxes-acp`` entry point can register Xerxes as an ACP server."""
+
+from .events import AcpEvent, AcpEventKind, to_acp_event
+from .permissions import AcpPermissionRequest, route_permission
+from .registry import REGISTRY_METADATA, write_registry_file
+from .server import AcpServer, ServerCapabilities
+from .session import AcpSession, AcpSessionStore
+
+__all__ = [
+    "REGISTRY_METADATA",
+    "AcpEvent",
+    "AcpEventKind",
+    "AcpPermissionRequest",
+    "AcpServer",
+    "AcpSession",
+    "AcpSessionStore",
+    "ServerCapabilities",
+    "route_permission",
+    "to_acp_event",
+    "write_registry_file",
+]

xerxes/acp/events.py

@@ -0,0 +1,123 @@
+# Copyright 2026 The Xerxes-Agents Author @erfanzar (Erfan Zare Chavoshi).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""ACP wire-event shape and conversion from internal ``StreamEvent``.
+
+Internal types live in ``xerxes.streaming.events`` and are sync
+Python dataclasses. ACP clients expect a tagged-union with ``kind``
+discriminator. Use ``to_acp_event(stream_event)`` to convert."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from ..streaming.events import (
+    PermissionRequest,
+    SkillSuggestion,
+    StreamEvent,
+    TextChunk,
+    ThinkingChunk,
+    ToolEnd,
+    ToolStart,
+    TurnDone,
+)
+
+
+class AcpEventKind(StrEnum):
+    """ACP wire event kinds Xerxes can emit."""
+
+    TEXT_DELTA = "text_delta"
+    THINKING_DELTA = "thinking_delta"
+    TOOL_CALL_START = "tool_call_start"
+    TOOL_CALL_END = "tool_call_end"
+    PERMISSION_REQUEST = "permission_request"
+    TURN_END = "turn_end"
+    SKILL_SUGGESTION = "skill_suggestion"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class AcpEvent:
+    """Single event delivered over ACP.
+
+    Attributes:
+        kind: discriminator tagging the payload shape.
+        payload: kind-specific JSON-shaped fields (text, tool info, etc.).
+    """
+
+    kind: AcpEventKind
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    def to_wire(self) -> dict[str, Any]:
+        """Render as the flat JSON-RPC dict expected on the wire."""
+        return {"kind": self.kind.value, **self.payload}
+
+
+def to_acp_event(event: StreamEvent) -> AcpEvent:
+    """Convert an internal stream event to an ACP event.
+
+    Unknown event types degrade to ``AcpEventKind.UNKNOWN`` with the
+    raw repr so the client can at least log them."""
+
+    if isinstance(event, TextChunk):
+        return AcpEvent(AcpEventKind.TEXT_DELTA, {"text": event.text})
+    if isinstance(event, ThinkingChunk):
+        return AcpEvent(AcpEventKind.THINKING_DELTA, {"text": event.text})
+    if isinstance(event, ToolStart):
+        return AcpEvent(
+            AcpEventKind.TOOL_CALL_START,
+            {"name": event.name, "inputs": event.inputs, "tool_call_id": event.tool_call_id},
+        )
+    if isinstance(event, ToolEnd):
+        return AcpEvent(
+            AcpEventKind.TOOL_CALL_END,
+            {
+                "name": event.name,
+                "result": event.result,
+                "permitted": event.permitted,
+                "tool_call_id": event.tool_call_id,
+                "duration_ms": event.duration_ms,
+            },
+        )
+    if isinstance(event, PermissionRequest):
+        return AcpEvent(
+            AcpEventKind.PERMISSION_REQUEST,
+            {
+                "tool_name": event.tool_name,
+                "description": event.description,
+                "inputs": event.inputs,
+            },
+        )
+    if isinstance(event, TurnDone):
+        return AcpEvent(
+            AcpEventKind.TURN_END,
+            {
+                "input_tokens": event.input_tokens,
+                "output_tokens": event.output_tokens,
+                "tool_calls_count": event.tool_calls_count,
+                "model": event.model,
+                "cache_read_tokens": getattr(event, "cache_read_tokens", 0),
+                "cache_creation_tokens": getattr(event, "cache_creation_tokens", 0),
+            },
+        )
+    if isinstance(event, SkillSuggestion):
+        return AcpEvent(
+            AcpEventKind.SKILL_SUGGESTION,
+            {"skill_name": event.skill_name, "description": event.description},
+        )
+    return AcpEvent(AcpEventKind.UNKNOWN, {"repr": repr(event)})
+
+
+__all__ = ["AcpEvent", "AcpEventKind", "to_acp_event"]