forge-ai-runtime 0.7.0__py3-none-any.whl

ai_runtime/__init__.py

@@ -0,0 +1,100 @@
+from .runtime import AgentRuntime
+from .version import __version__
+
+from .context import ContextWindow
+from .memory import (
+    MemoryStore,
+    InMemoryStore,
+    ConversationMemory,
+    SemanticMemory,
+)
+from .rag import Document, VectorStore, InMemoryVectorStore, Retriever
+from .skills import Skill, SkillRegistry, ComposedSkills
+from .agents import Agent, AgentRunner
+from .tools import Tool, ToolResult, ToolRegistry, ToolExecutor, FunctionTool
+from .execution.plan import Plan
+from .execution.hooks import HookRegistry, HookEvent, HookContext, HookResult
+from .mcp import MCPClient, StdioTransport, MCPTool, register_mcp_tools
+from .execution.background import BackgroundTaskRegistry, BackgroundTask
+from .agents.subagent import SubAgentSpec, SubAgentResult
+from .tools.permissions import (
+    PermissionPolicy,
+    PermissionRule,
+    PermissionDecision,
+    PermissionError,
+)
+from .tools.guarded_executor import GuardedToolExecutor
+from .tools.builtin import (
+    ReadFileTool,
+    WriteFileTool,
+    EditFileTool,
+    GlobTool,
+    GrepTool,
+    BashTool,
+    register_builtin_tools,
+)
+from .tools.checkpoints import CheckpointManager, Checkpoint
+from .agents.config_files import load_project_instructions, discover_instructions
+from .server import AgentServer, AgentRequest, AgentResponse
+from .workspace import Project
+from .commands import CommandRegistry, Command, default_commands
+
+__all__ = [
+    "AgentRuntime",
+    "__version__",
+    "ContextWindow",
+    "MemoryStore",
+    "InMemoryStore",
+    "ConversationMemory",
+    "SemanticMemory",
+    "Document",
+    "VectorStore",
+    "InMemoryVectorStore",
+    "Retriever",
+    "Skill",
+    "SkillRegistry",
+    "ComposedSkills",
+    "Agent",
+    "AgentRunner",
+    "SubAgentSpec",
+    "SubAgentResult",
+    "Tool",
+    "ToolResult",
+    "ToolRegistry",
+    "ToolExecutor",
+    "FunctionTool",
+    "ReadFileTool",
+    "WriteFileTool",
+    "EditFileTool",
+    "GlobTool",
+    "GrepTool",
+    "BashTool",
+    "register_builtin_tools",
+    "CheckpointManager",
+    "Checkpoint",
+    "PermissionPolicy",
+    "PermissionRule",
+    "PermissionDecision",
+    "PermissionError",
+    "GuardedToolExecutor",
+    "load_project_instructions",
+    "discover_instructions",
+    "Plan",
+    "HookRegistry",
+    "HookEvent",
+    "HookContext",
+    "HookResult",
+    "MCPClient",
+    "StdioTransport",
+    "MCPTool",
+    "register_mcp_tools",
+    "BackgroundTaskRegistry",
+    "BackgroundTask",
+    "AgentServer",
+    "AgentRequest",
+    "AgentResponse",
+    "Project",
+    "CommandRegistry",
+    "Command",
+    "default_commands",
+]

ai_runtime/adapters/litellm/response_adapter.py

@@ -0,0 +1,58 @@
+from typing import Any
+
+from ai_runtime.conversation import (
+    ChatResponse,
+    ChatMessage,
+    ToolCall,
+    Usage,
+)
+
+
+class LiteLLMResponseAdapter:
+
+    @staticmethod
+    def from_response(response: Any) -> ChatResponse:
+        choice = response.choices[0]
+        message = choice.message
+
+        tool_calls = LiteLLMResponseAdapter.to_tool_calls(
+            getattr(message, "tool_calls", None)
+        )
+
+        return ChatResponse.assistant(
+            getattr(message, "content", None) or "",
+            usage=LiteLLMResponseAdapter.to_usage(
+                getattr(response, "usage", None)
+            ),
+            finish_reason=getattr(choice, "finish_reason", None),
+            tool_calls=tool_calls or None,
+            raw=response,
+        )
+
+    @staticmethod
+    def to_tool_calls(raw_calls: Any) -> list[ToolCall]:
+        if not raw_calls:
+            return []
+
+        calls: list[ToolCall] = []
+        for rc in raw_calls:
+            function = getattr(rc, "function", None)
+            calls.append(
+                ToolCall(
+                    id=getattr(rc, "id", ""),
+                    name=getattr(function, "name", ""),
+                    arguments=getattr(function, "arguments", ""),
+                )
+            )
+        return calls
+
+    @staticmethod
+    def to_usage(usage: Any) -> Usage:
+        if usage is None:
+            return Usage()
+
+        return Usage(
+            prompt_tokens=getattr(usage, "prompt_tokens", 0) or 0,
+            completion_tokens=getattr(usage, "completion_tokens", 0) or 0,
+            total_tokens=getattr(usage, "total_tokens", 0) or 0,
+        )

ai_runtime/agents/__init__.py

@@ -0,0 +1,12 @@
+"""Agent subsystem: declarative agents and orchestration runner."""
+
+from .agent import Agent
+from .runner import AgentRunner
+from .subagent import SubAgentSpec, SubAgentResult
+
+__all__ = [
+    "Agent",
+    "AgentRunner",
+    "SubAgentSpec",
+    "SubAgentResult",
+]

ai_runtime/agents/agent.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ai_runtime.conversation import ChatMessage
+from ai_runtime.memory import MemoryStore, InMemoryStore, ConversationMemory
+from ai_runtime.skills import SkillRegistry, ComposedSkills
+from ai_runtime.tools import ToolRegistry, ToolExecutor
+from .subagent import SubAgentSpec
+
+
+class Agent:
+    """A configured agent: provider + system prompt + tools + memory + skills.
+
+    An `Agent` is a declarative specification. Execution is performed by
+    `AgentRunner`, which wires the agent's pieces into the runtime's
+    execution pipeline (including the tool-call loop).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        provider,
+        system_prompt: str | None = None,
+        tool_registry: ToolRegistry | None = None,
+        memory_store: MemoryStore | None = None,
+        skill_registry: SkillRegistry | None = None,
+        skills: list[str] | None = None,
+        memory: ConversationMemory | None = None,
+        sub_agents: list[SubAgentSpec] | None = None,
+    ):
+        self.name = name
+        self.provider = provider
+        self.system_prompt = system_prompt
+        self.tool_registry = tool_registry or ToolRegistry()
+        self.tool_executor = ToolExecutor(self.tool_registry)
+        self.memory_store = memory_store or InMemoryStore()
+        self.memory = memory or ConversationMemory(self.memory_store, name)
+        self.skill_registry = skill_registry
+        self.skills: ComposedSkills | None = None
+        if skill_registry is not None and skills:
+            self.skills = skill_registry.compose(skills)
+        self.sub_agents = sub_agents or []
+
+    def effective_system_prompt(self) -> str | None:
+        """Combine the agent prompt with any composed skill prompts."""
+        parts: list[str] = []
+        if self.system_prompt:
+            parts.append(self.system_prompt)
+        if self.skills is not None and self.skills.system_prompt:
+            parts.append(self.skills.system_prompt)
+        return "\n\n".join(parts) if parts else None
+
+    def effective_tool_names(self) -> list[str]:
+        if self.skills is None:
+            return list(self.tool_registry._tools.keys())
+        return self.skills.tool_names or list(
+            self.tool_registry._tools.keys()
+        )
+
+    async def ensure_memory_loaded(self) -> None:
+        await self.memory.load()

ai_runtime/agents/config_files.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+# Candidate instruction-file locations, checked in priority order.
+INSTRUCTION_CANDIDATES = [
+    ".github/copilot-instructions.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursor/rules",
+    "ai-runtime.md",
+]
+
+
+def discover_instructions(project_root: str) -> list[str]:
+    """Return the contents of discovered agent instruction files.
+
+    Mirrors the instruction-file discovery of Copilot (`copilot-instructions.md`),
+    Codex/Claude (`AGENTS.md` / `CLAUDE.md`), and Cursor (`.cursor/rules`).
+    Returns a list of markdown text blocks to prepend to the system prompt.
+    """
+    root = Path(project_root)
+    blocks: list[str] = []
+    for rel in INSTRUCTION_CANDIDATES:
+        path = root / rel
+        if path.is_file():
+            blocks.append(path.read_text(encoding="utf-8", errors="replace"))
+        elif path.is_dir():
+            for f in sorted(path.glob("*.mdc")) + sorted(path.glob("*.md")):
+                blocks.append(f.read_text(encoding="utf-8", errors="replace"))
+    return blocks
+
+
+def load_project_instructions(project_root: str) -> str | None:
+    """Concatenate discovered instruction files into a single system block."""
+    blocks = discover_instructions(project_root)
+    return "\n\n---\n\n".join(blocks) if blocks else None

ai_runtime/agents/runner.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ai_runtime.conversation import ChatMessage, ChatRequest
+from ai_runtime.execution.plan import Plan
+from ai_runtime.streaming import StreamEvent
+from collections.abc import AsyncIterator
+
+if TYPE_CHECKING:
+    from ai_runtime.execution import ExecutionEngine
+
+from ai_runtime.execution.context import ExecutionContext
+
+from .agent import Agent
+
+
+class AgentRunner:
+    """Orchestrates agent execution over the runtime pipeline.
+
+    For each `run`, the runner:
+      1. Loads persisted conversation memory.
+      2. Prepends the agent's (skill-composed) system prompt.
+      3. Executes via `ExecutionEngine` (which includes the tool-call loop).
+      4. Persists the updated conversation back to memory.
+    """
+
+    def __init__(self, agent: Agent, engine: ExecutionEngine | None = None):
+        if engine is None:
+            from ai_runtime.execution import ExecutionEngine
+
+            engine = ExecutionEngine()
+        self.agent = agent
+        self.engine = engine
+        self.last_plan: Plan | None = None
+        self.last_plan_text: str = ""
+
+    async def run(
+        self,
+        message: str | ChatMessage | ChatRequest,
+        system_prompt: str | None = None,
+    ):
+        await self.agent.ensure_memory_loaded()
+
+        context = ExecutionContext(
+            provider=self.agent.provider,
+            tool_executor=self.agent.tool_executor,
+        )
+        context.agent = self.agent
+        context._engine = self.engine
+
+        # Seed conversation with system prompt + persisted history.
+        prompt = system_prompt or self.agent.effective_system_prompt()
+        if prompt:
+            context.conversation.add(ChatMessage.system(prompt))
+        for msg in self.agent.memory.conversation.messages:
+            context.conversation.add(msg)
+
+        if isinstance(message, str):
+            user_msg = ChatMessage.user(message)
+        elif isinstance(message, ChatMessage):
+            user_msg = message
+        else:
+            user_msg = ChatMessage.user(message.messages[-1].content)
+
+        response = await self.engine.chat(context, user_msg)
+
+        # Persist the new turns (exclude the prepended system prompt).
+        if prompt:
+            persisted = context.conversation.copy()
+            persisted.messages = persisted.messages[1:]
+            self.agent.memory._conversation = persisted
+        else:
+            self.agent.memory._conversation = context.conversation.copy()
+        await self.agent.memory.save()
+
+        return response
+
+    async def stream(
+        self,
+        message: str | ChatMessage | ChatRequest,
+        system_prompt: str | None = None,
+    ):
+        await self.agent.ensure_memory_loaded()
+
+        context = ExecutionContext(
+            provider=self.agent.provider,
+            tool_executor=self.agent.tool_executor,
+        )
+        context.agent = self.agent
+        context._engine = self.engine
+
+        prompt = system_prompt or self.agent.effective_system_prompt()
+        if prompt:
+            context.conversation.add(ChatMessage.system(prompt))
+        for msg in self.agent.memory.conversation.messages:
+            context.conversation.add(msg)
+
+        if isinstance(message, str):
+            user_msg = ChatMessage.user(message)
+        elif isinstance(message, ChatMessage):
+            user_msg = message
+        else:
+            user_msg = ChatMessage.user(message.messages[-1].content)
+
+        async for event in self.engine.stream(context, user_msg):
+            yield event
+
+        await self.agent.memory.save()
+
+    async def plan(
+        self,
+        message: str | ChatMessage | ChatRequest,
+        system_prompt: str | None = None,
+    ) -> Plan:
+        """Produce a reviewable plan for the agent without executing tools."""
+        await self.agent.ensure_memory_loaded()
+
+        context = ExecutionContext(
+            provider=self.agent.provider,
+            tool_executor=self.agent.tool_executor,
+        )
+
+        prompt = system_prompt or self.agent.effective_system_prompt()
+        if prompt:
+            context.conversation.add(ChatMessage.system(prompt))
+        for msg in self.agent.memory.conversation.messages:
+            context.conversation.add(msg)
+
+        if isinstance(message, str):
+            user_msg = ChatMessage.user(message)
+        elif isinstance(message, ChatMessage):
+            user_msg = message
+        else:
+            user_msg = ChatMessage.user(message.messages[-1].content)
+
+        return await self.engine.plan(context, user_msg)
+
+    async def stream_plan(
+        self,
+        message: str | ChatMessage | ChatRequest,
+        system_prompt: str | None = None,
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream a plan (live thinking + placeholder, then the parsed plan).
+
+        The planner parses the model's JSON into a `Plan` during streaming, so
+        no second LLM call is needed — the parsed plan is available on
+        `self.last_plan` afterwards.
+        """
+        await self.agent.ensure_memory_loaded()
+
+        context = ExecutionContext(
+            provider=self.agent.provider,
+            tool_executor=self.agent.tool_executor,
+        )
+        context.agent = self.agent
+        context._engine = self.engine
+
+        prompt = system_prompt or self.agent.effective_system_prompt()
+        if prompt:
+            context.conversation.add(ChatMessage.system(prompt))
+        for msg in self.agent.memory.conversation.messages:
+            context.conversation.add(msg)
+
+        if isinstance(message, str):
+            user_msg = ChatMessage.user(message)
+        elif isinstance(message, ChatMessage):
+            user_msg = message
+        else:
+            user_msg = ChatMessage.user(message.messages[-1].content)
+
+        async for event in self.engine.stream_plan(context, user_msg):
+            yield event
+        # Capture the parsed plan and the raw streamed text produced during
+        # streaming, so the transport can echo back exactly what was shown.
+        self.last_plan = context.plan
+        self.last_plan_text = context.assistant_text

ai_runtime/agents/subagent.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+@dataclass
+class SubAgentSpec:
+    """Declarative spec for a child agent spawned by a supervisor.
+
+    Mirrors the sub-agent model of agentic coding tools: a child has its
+    own tools, model, and isolation scope, and runs in a separate context
+    so its transcript does not pollute the parent's context window.
+    """
+
+    name: str
+    agent: Agent
+    task_template: str = "{task}"  # receives `task` kwarg
+    max_depth: int = 1  # how many levels of nesting allowed
+    isolated: bool = True  # run in a fresh conversation context
+
+
+@dataclass
+class SubAgentResult:
+    name: str
+    output: str
+    success: bool = True
+    error: str | None = None

ai_runtime/cli.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+from ai_runtime.agents import Agent
+from ai_runtime.providers.enums import ProviderType
+from ai_runtime.providers import ProviderConfig
+from ai_runtime.server.agent_server import AgentServer
+from ai_runtime.server.protocol import AgentRequest
+from ai_runtime.tools.builtin import register_builtin_tools
+from ai_runtime.tools import ToolRegistry, GuardedToolExecutor, PermissionPolicy
+from ai_runtime.agents.config_files import load_project_instructions
+
+
+def _build_agent(args) -> Agent:
+    config = ProviderConfig(
+        provider=ProviderType(args.provider),
+        model=args.model,
+        api_key=os.getenv(args.api_key_env),
+        reasoning_effort=args.reasoning_effort,
+    )
+    registry = ToolRegistry()
+    register_builtin_tools(registry, base_dir=args.cwd)
+    executor = GuardedToolExecutor(
+        registry.executor if hasattr(registry, "executor") else __import__(
+            "ai_runtime.tools.executor", fromlist=["ToolExecutor"]
+        ).ToolExecutor(registry),
+        PermissionPolicy.permissive() if args.yolo else PermissionPolicy.default(),
+    )
+    return Agent(
+        name="cli-agent",
+        provider=config,
+        system_prompt=load_project_instructions(args.cwd),
+        tool_registry=registry,
+    )
+
+
+async def _run(args) -> None:
+    agent = _build_agent(args)
+    server = AgentServer(agent)
+    req = AgentRequest(session_id="cli", message=args.prompt, mode=args.mode)
+    if args.mode == "stream":
+        async for line in server.stream(req):
+            sys.stdout.write(line)
+    else:
+        resp = await server.handle(req)
+        print(resp.content)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="ai-runtime", description="ai_runtime agent CLI")
+    parser.add_argument("prompt", nargs="?", help="Prompt to send to the agent")
+    parser.add_argument("--provider", default="openai", help="Provider type")
+    parser.add_argument("--model", required=True, help="Model id")
+    parser.add_argument("--api-key-env", default="OPENAI_API_KEY", help="Env var with API key")
+    parser.add_argument("--mode", default="chat", choices=["chat", "stream", "plan"])
+    parser.add_argument("--cwd", default=os.getcwd(), help="Project root / sandbox dir")
+    parser.add_argument("--reasoning-effort", default=None, help="low|medium|high")
+    parser.add_argument("--yolo", action="store_true", help="Allow all tools without prompting")
+    parser.add_argument("--serve", action="store_true", help="Start stdio server")
+    parser.add_argument("--http", action="store_true", help="Start HTTP server")
+    parser.add_argument("--port", type=int, default=8787)
+    args = parser.parse_args()
+
+    if args.serve:
+        agent = _build_agent(args)
+        asyncio.run(AgentServer(agent).serve_stdio())
+    elif args.http:
+        agent = _build_agent(args)
+        asyncio.run(AgentServer(agent).serve_http(port=args.port))
+    elif args.prompt:
+        asyncio.run(_run(args))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

ai_runtime/commands/__init__.py

@@ -0,0 +1,5 @@
+"""Slash-command / prompt-file registry (à la Copilot's `/` menu)."""
+
+from .registry import Command, CommandRegistry, default_commands
+
+__all__ = ["Command", "CommandRegistry", "default_commands"]

ai_runtime/commands/registry.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class Command:
+    """A slash command / prompt file (à la Copilot's `/` menu).
+
+    A command is a named, reusable prompt (or hook) the user can invoke.
+    `render` produces the prompt text sent to the model; `run` optionally
+    executes side effects (e.g. `/compact`, `/context`).
+    """
+
+    name: str
+    description: str
+    prompt_template: str | None = None
+    run: Callable[[Any], Any] | None = None
+
+    def render(self, **kwargs: Any) -> str:
+        if self.prompt_template:
+            try:
+                return self.prompt_template.format(**kwargs)
+            except (KeyError, IndexError):
+                return self.prompt_template
+        return self.description
+
+
+class CommandRegistry:
+    """Registry of slash commands / prompt files."""
+
+    def __init__(self):
+        self._commands: dict[str, Command] = {}
+
+    def register(self, command: Command) -> None:
+        self._commands[command.name] = command
+
+    def get(self, name: str) -> Command | None:
+        return self._commands.get(name)
+
+    def list(self) -> list[Command]:
+        return list(self._commands.values())
+
+    def render(self, name: str, **kwargs: Any) -> str | None:
+        cmd = self._commands.get(name)
+        return cmd.render(**kwargs) if cmd else None
+
+
+# Built-in commands mirroring Copilot/Claude/Cursor slash commands.
+def default_commands() -> CommandRegistry:
+    reg = CommandRegistry()
+    reg.register(
+        Command("compact", "Summarize the conversation to free context", "Please summarize the conversation so far concisely.")
+    )
+    reg.register(
+        Command("context", "Show a token/context breakdown", "List the current context window usage.")
+    )
+    reg.register(
+        Command("clear", "Clear the conversation history", "Clear all messages from the current session.")
+    )
+    return reg

ai_runtime/compat.py

@@ -0,0 +1,32 @@
+"""Backwards-compatibility shims.
+
+This module preserves names that were renamed or moved in previous releases
+so that existing imports keep working. Deprecated aliases emit a warning and
+will be removed in a future major version.
+
+Renames:
+- ``ChatSession`` -> :class:`ai_runtime.session.Session`
+"""
+from __future__ import annotations
+
+import warnings
+
+from .session import Session
+
+_DEPRECATION_MSG = (
+    "{old} is deprecated and will be removed in a future major version. "
+    "Use {new} instead."
+)
+
+
+def __getattr__(name: str):
+    """Lazy deprecation shim for renamed symbols."""
+    if name == "ChatSession":
+        warnings.warn(
+            _DEPRECATION_MSG.format(old="ChatSession", new="Session"),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return Session
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ai_runtime/context/__init__.py

@@ -0,0 +1,15 @@
+"""Context management: token budgeting, truncation, and summarization."""
+
+from .window import (
+    ContextWindow,
+    DropOldestStrategy,
+    TruncationStrategy,
+    estimate_tokens,
+)
+
+__all__ = [
+    "ContextWindow",
+    "TruncationStrategy",
+    "DropOldestStrategy",
+    "estimate_tokens",
+]