roboz 0.1.2.dev2__py3-none-any.whl

roboz/__init__.py

@@ -0,0 +1,91 @@
+"""Golden-path authoring API for Roboz."""
+
+from roboz.agent import (
+    Agent,
+    BackgroundAgentStatus,
+    prompt_agent,
+    run_background_agent,
+    run_subagent,
+)
+from roboz.dependencies import (
+    DependencyRoute,
+    ExecutableDependency,
+    ExternalDependency,
+    ExternalDependencyKind,
+    ExternalDependencyReference,
+    ExternalDependencySource,
+    LazyExternalDependency,
+    ModelEndpointDependency,
+    NetworkServiceDependency,
+)
+from roboz.models import (
+    AgentBaseModel,
+    All,
+    Empty,
+    HashMaps,
+    Int,
+    Invoke,
+    Location,
+    LocationStr,
+    Message,
+    Role,
+    Stop,
+    StopLocation,
+    Str,
+    Strs,
+)
+from roboz.skill import Skill
+from roboz.tooling import Factory, Tool
+from roboz.tooling.context import Ctx
+from roboz.tooling.decorators import factory, tool
+from roboz.tools import (
+    PromptUser,
+    message_user,
+    prompt_user,
+    prompt_user_at_start,
+    stop,
+    stop_after,
+)
+
+__all__ = [
+    "Ctx",
+    "Agent",
+    "AgentBaseModel",
+    "All",
+    "BackgroundAgentStatus",
+    "Empty",
+    "DependencyRoute",
+    "ExecutableDependency",
+    "ExternalDependency",
+    "ExternalDependencyKind",
+    "ExternalDependencyReference",
+    "ExternalDependencySource",
+    "Factory",
+    "HashMaps",
+    "Int",
+    "Invoke",
+    "LazyExternalDependency",
+    "Location",
+    "LocationStr",
+    "Message",
+    "ModelEndpointDependency",
+    "NetworkServiceDependency",
+    "PromptUser",
+    "Role",
+    "Skill",
+    "Stop",
+    "StopLocation",
+    "Str",
+    "Strs",
+    "Tool",
+    "factory",
+    "message_user",
+    "prompt_agent",
+    "prompt_user",
+    "prompt_user_at_start",
+    "run_background_agent",
+    "run_subagent",
+    "stop",
+    "stop_after",
+    "tool",
+]

roboz/_naming.py

@@ -0,0 +1,19 @@
+"""Validation for identifiers exposed to language models."""
+
+from __future__ import annotations
+
+import re
+
+_PUBLIC_NAME = re.compile(r"[a-z][a-z0-9]*(?:_[a-z0-9]+)*", flags=re.ASCII)
+
+
+def validate_public_name(name: str, *, kind: str) -> str:
+    """Return ``name`` when it is a lowercase ASCII snake-case identifier."""
+    if not isinstance(name, str):
+        raise TypeError(f"{kind} name must be a string")
+    if _PUBLIC_NAME.fullmatch(name) is None:
+        raise ValueError(
+            f"{kind} name must be lowercase ASCII snake_case and match "
+            "'[a-z][a-z0-9]*(?:_[a-z0-9]+)*'"
+        )
+    return name

roboz/agent/__init__.py

@@ -0,0 +1,21 @@
+"""Agent construction, execution, and delegation interfaces."""
+
+from roboz.agent._execution_context import get_active_agent_stack
+from roboz.agent.background_agent import (
+    BackgroundAgentPhase,
+    BackgroundAgentStatus,
+    run_background_agent,
+)
+from roboz.agent.core import Agent
+from roboz.agent.prompt_agent_tool import prompt_agent
+from roboz.agent.subagent import run_subagent
+
+__all__ = [
+    "Agent",
+    "BackgroundAgentPhase",
+    "BackgroundAgentStatus",
+    "get_active_agent_stack",
+    "prompt_agent",
+    "run_background_agent",
+    "run_subagent",
+]

roboz/agent/_execution_context.py

@@ -0,0 +1,53 @@
+"""Context-local tracking of nested agent execution."""
+
+from __future__ import annotations
+
+import keyword
+from contextvars import ContextVar, Token
+
+
+_active_agent_stack: ContextVar[tuple[str, ...]] = ContextVar(
+    "_active_agent_stack", default=()
+)
+
+
+def get_active_agent_stack() -> tuple[str, ...]:
+    return _active_agent_stack.get()
+
+
+def push_active_agent(agent_name: str) -> Token[tuple[str, ...]]:
+    stack = _active_agent_stack.get()
+    return _active_agent_stack.set(stack + (agent_name,))
+
+
+def pop_active_agent(token: Token[tuple[str, ...]]) -> None:
+    _active_agent_stack.reset(token)
+
+
+_WINDOWS_RESERVED_NAMES: frozenset[str] = frozenset(
+    {
+        "con",
+        "prn",
+        "aux",
+        "nul",
+        *(f"com{i}" for i in range(1, 10)),
+        *(f"lpt{i}" for i in range(1, 10)),
+    }
+)
+
+
+def validate_agent_name(name: str) -> str:
+    if not isinstance(name, str):
+        raise TypeError(f"agent name must be str, got {type(name).__name__}")
+    stripped = name.strip()
+    if not stripped:
+        raise ValueError("agent name cannot be blank")
+    if not stripped.isidentifier():
+        raise ValueError(f"agent name must be a valid Python identifier, got {name!r}")
+    if keyword.iskeyword(stripped):
+        raise ValueError(f"agent name cannot be a Python keyword, got {name!r}")
+    if stripped.lower() in _WINDOWS_RESERVED_NAMES:
+        raise ValueError(
+            f"agent name is reserved as a device name on Windows, got {name!r}"
+        )
+    return stripped

roboz/agent/_identifiers.py

@@ -0,0 +1,15 @@
+"""Stable identifiers for the built-in agent tools.
+
+Single source of truth for the built-in tool names that downstream packages
+compare against (e.g. ``caller == PROMPT_USER_TOOL_NAME``). Change values here when
+renaming the corresponding tool; never duplicate these strings as literals elsewhere.
+Each value must match the actual ``tool.name`` (guarded by a test).
+"""
+
+from typing import Final
+
+# --- Tools (``tool.name``) — imperative expressions `do` ---
+
+PROMPT_AGENT_TOOL_NAME: Final[str] = "prompt_agent"
+RUN_BACKGROUND_AGENT_TOOL_NAME: Final[str] = "run_background_agent"
+RUN_SUBAGENT_TOOL_NAME: Final[str] = "run_subagent"

roboz/agent/_notifications.py

@@ -0,0 +1,25 @@
+"""Notification text produced while agents load skills and tools."""
+
+from __future__ import annotations
+
+from typing import Final
+
+AUTO_LOAD_SKILLS_BANNER: Final[str] = (
+    "Here are skills that *I* have chosen to invoke automatically "
+    "and the respective instructions on how to use "
+    "them. They are from this point onwards freely at your disposal."
+)
+INTERRUPT_PROMPT_TO_USER: Final[str] = "Action interrupted!"
+INTERRUPTED_GENERATION_CONTEXT: Final[str] = (
+    "The previous assistant generation was interrupted by the user before it "
+    "completed. Treat the user's next message as a change of direction."
+)
+LLM_PROVIDER_REQUEST_RETRY_PROMPT: Final[str] = (
+    "The selected model could not complete the request. Choose another model, "
+    "then enter retry and Send."
+)
+SUBAGENT_NO_OUTCOME_PLACEHOLDER: Final[str] = "The agent finished without a message."
+
+
+def auto_load_skill_rationale(skill_name: str) -> str:
+    return f"Loading the {skill_name} skill"

roboz/agent/_prompts.py

@@ -0,0 +1,154 @@
+"""System-prompt assembly for agentic and non-agentic runs."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Sequence
+
+from roboz.skill._prompts import AGENT_SKILL_USE_INSTRUCTIONS
+from roboz.tooling._prompts import AGENT_TOOL_USE_INSTRUCTIONS, _get_single_instruction
+
+if TYPE_CHECKING:
+    from roboz.skill.core import Skill
+    from roboz.tooling.core import Tool
+
+logger = logging.getLogger(__name__)
+
+
+def _get_available_tools_and_skills_section(
+    tools: Sequence[Tool] | None,
+    skills: Sequence[Skill] | None,
+) -> str:
+    tools = tools if tools is not None else []
+    skills = skills if skills is not None else []
+    skill_names = {s.name for s in skills if s is not None}
+    section = "## Available tools and skills\n\n"
+    for t in tools:
+        if t is None or t.chained_to or t.name in skill_names:
+            continue
+        section += f"{_get_single_instruction(t)}\n\n"
+    for s in skills:
+        if s is None:
+            continue
+        section += f"{_get_single_instruction(s.get_skill_as_tool())}\n\n"
+    return section.rstrip()
+
+
+def get_example_agent_discussion() -> str:
+    """Return a multi-turn example showing how turns appear in the agent (roles and JSON shapes)."""
+    section = "## Example discussion\n\n<example>\n\n"
+    section += (
+        "The following is a **full multi-turn discussion**: many separate "
+        "Assistant/User rounds over time—not one assistant message. Each "
+        "`Assistant:` line is exactly **one** assistant reply containing **one** "
+        "JSON object; never paste several JSON objects into a single assistant "
+        "reply.\n\n"
+    )
+    section += (
+        "System: This is an example system message for illustrative purposes.\n\n"
+    )
+    section += "Assistant: "
+    section += (
+        json.dumps(
+            {
+                "action": "prompt_user",
+                "rationale": "Getting the user's request.",
+                "value": "Hi there! How should we start the example?",
+            }
+        )
+        + "\n\n"
+    )
+    section += "User: "
+    section += (
+        json.dumps(
+            {
+                "caller": "prompt_user",
+                "value": "Please demonstrate the example tool by calling it with value 42.",
+            }
+        )
+        + "\n\n"
+    )
+    section += "Assistant: "
+    section += (
+        json.dumps(
+            {
+                "action": "example_tool",
+                "rationale": "Calling the example_tool to demonstrate its structure as requested.",
+                "value": 42,
+            }
+        )
+        + "\n\n"
+    )
+    section += "User: "
+    section += (
+        json.dumps(
+            {
+                "caller": "example_tool",
+                "value": "Example: 42",
+            }
+        )
+        + "\n\n"
+    )
+    section += "Assistant: "
+    section += (
+        json.dumps(
+            {
+                "action": "prompt_user",
+                "rationale": "Getting the user's next request.",
+                "value": "Anything else I can help you with?",
+            }
+        )
+        + "\n\n"
+    )
+    section += "User: "
+    section += (
+        json.dumps(
+            {
+                "caller": "prompt_user",
+                "value": "Please load the example skill.",
+            }
+        )
+        + "\n\n"
+    )
+    section += "Assistant: "
+    section += (
+        json.dumps(
+            {
+                "action": "example_skill",
+                "rationale": "Loading the example_skill as requested.",
+            }
+        )
+        + "\n\n"
+    )
+    section += "User: "
+    section += json.dumps(
+        {
+            "caller": "example_skill",
+            "value": "# Instructions\n\nYou are now using the Example Skill... "
+            "<redacted the rest as this is an example>",
+        }
+    )
+    section += "\n\n</example>"
+    return section
+
+
+def get_agentic_system_prompt(
+    *,
+    system_prompt: str = "",
+    tools: Sequence[Tool] | None = None,
+    skills: Sequence[Skill] | None = None,
+) -> str:
+    """Build the complete technical prompt for an agentic run.
+
+    Keep detailed tool and skill calling instructions out of the supplied
+    system prompt because this builder generates them consistently.
+    """
+    parts = [
+        system_prompt.strip(),
+        AGENT_TOOL_USE_INSTRUCTIONS,
+        AGENT_SKILL_USE_INSTRUCTIONS,
+        _get_available_tools_and_skills_section(tools, skills),
+        get_example_agent_discussion(),
+    ]
+    return "\n\n".join(p for p in parts if p)

roboz/agent/_tool_observer.py

@@ -0,0 +1,159 @@
+"""Lifecycle observation around individual tool calls."""
+
+from __future__ import annotations
+
+import time
+from logging import getLogger
+from typing import Any, Final
+
+from roboz.exceptions import (
+    ExternalCallCancelledError,
+    ExternalCallInterruptedError,
+    LLMProviderRequestError,
+)
+from roboz.models import Empty, Invoke, Message, Stop
+from roboz.runtime._logging import LogScalar, log_with_data
+from roboz.runtime.observability import (
+    LifecycleKind,
+    ObservedFailure,
+    RuntimeEventCategory,
+    RuntimeEventKind,
+    RuntimeEventLevel,
+)
+from roboz.runtime.pipe import EventPipe
+from roboz.tooling.core import Tool
+
+logger = getLogger(__name__)
+
+_AGENT_KEY: Final[str] = "agent"
+_TOOL_KEY: Final[str] = "tool"
+_DURATION_MS_KEY: Final[str] = "duration_ms"
+_OUTPUT_TYPE_KEY: Final[str] = "output_type"
+_OUTPUT_CHARS_KEY: Final[str] = "output_chars"
+_ERROR_TYPE_KEY: Final[str] = "error_type"
+_MILLISECONDS_PER_SECOND: Final[int] = 1_000
+
+
+class ToolInvocationObserver:
+    """Invoke tools while emitting their agent-scoped runtime lifecycle.
+
+    This wrapper is observability-only. It does not recover from, translate, or
+    otherwise handle failures; after recording one, it re-raises the original
+    exception unchanged so the agent retains ownership of control-flow policy.
+    """
+
+    def __init__(self, *, agent_name: str, pipe: EventPipe) -> None:
+        self._agent_name = agent_name
+        self._pipe = pipe
+
+    def invoke(
+        self,
+        tool: Tool[Any, Any],
+        input: Invoke | Empty,
+        messages: list[Message],
+    ) -> Invoke | Empty | Stop:
+        started = time.monotonic()
+        self._emit(
+            tool=tool,
+            kind=LifecycleKind.STARTED,
+            level=RuntimeEventLevel.INFO,
+            message="Tool call started",
+        )
+        try:
+            output = tool(input, messages)
+        except (Exception, KeyboardInterrupt) as error:
+            self._emit_failure(tool=tool, error=error, started=started)
+            raise
+
+        output_chars = len(output.model_dump_json())
+        self._emit(
+            tool=tool,
+            kind=LifecycleKind.SUCCEEDED,
+            level=RuntimeEventLevel.INFO,
+            message="Tool call succeeded",
+            data={
+                _DURATION_MS_KEY: round(
+                    (time.monotonic() - started) * _MILLISECONDS_PER_SECOND
+                ),
+                _OUTPUT_TYPE_KEY: type(output).__name__,
+                _OUTPUT_CHARS_KEY: output_chars,
+            },
+        )
+        return output
+
+    def _emit_failure(
+        self,
+        *,
+        tool: Tool[Any, Any],
+        error: BaseException,
+        started: float,
+    ) -> None:
+        failure = _failure_for(error)
+        self._emit(
+            tool=tool,
+            kind=failure.kind,
+            level=failure.level,
+            message=f"Tool call {failure.kind}",
+            data={
+                _DURATION_MS_KEY: round(
+                    (time.monotonic() - started) * _MILLISECONDS_PER_SECOND
+                ),
+                _ERROR_TYPE_KEY: type(error).__name__,
+            },
+        )
+
+    def _emit(
+        self,
+        *,
+        tool: Tool[Any, Any],
+        kind: RuntimeEventKind,
+        level: RuntimeEventLevel,
+        message: str,
+        data: dict[str, object] | None = None,
+    ) -> None:
+        observation = {_TOOL_KEY: tool.name, **(data or {})}
+        log_data: dict[str, LogScalar] = {_AGENT_KEY: self._agent_name}
+        log_data.update(
+            (key, value)
+            for key, value in observation.items()
+            if value is None or isinstance(value, (str, int, float, bool))
+        )
+        details: list[str] = []
+        duration_ms = observation.get(_DURATION_MS_KEY)
+        if isinstance(duration_ms, int):
+            details.append(f"duration_ms={duration_ms}")
+        output_type = observation.get(_OUTPUT_TYPE_KEY)
+        if isinstance(output_type, str):
+            details.append(f"result={output_type}")
+        error_type = observation.get(_ERROR_TYPE_KEY)
+        if isinstance(error_type, str):
+            details.append(f"error_type={error_type}")
+        suffix = f", {', '.join(details)}" if details else ""
+        log_with_data(
+            logger,
+            level.logging_level,
+            f"Tool call {kind}: {tool.name} (agent={self._agent_name}{suffix})",
+            log_data,
+        )
+        self._pipe.emit_runtime_event(
+            category=RuntimeEventCategory.TOOL,
+            kind=kind,
+            level=level,
+            message=f"{message}: {tool.name}",
+            data=observation,
+        )
+
+
+def _failure_for(error: BaseException) -> ObservedFailure:
+    match error:
+        case LLMProviderRequestError():
+            return ObservedFailure.failed(level=RuntimeEventLevel.WARNING)
+        case ExternalCallInterruptedError() | KeyboardInterrupt():
+            return ObservedFailure.interrupted(level=RuntimeEventLevel.WARNING)
+        case ExternalCallCancelledError():
+            return ObservedFailure.cancelled(level=RuntimeEventLevel.WARNING)
+        case _:
+            return ObservedFailure.failed()
+
+
+__all__ = ["ToolInvocationObserver"]

roboz/agent/background_agent.py

@@ -0,0 +1,157 @@
+"""Run agents in background threads."""
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from functools import partial
+from threading import Event
+from typing import Final, Literal
+
+from roboz.models import Empty, Message
+from roboz.models.truncation import NO_MESSAGE
+from roboz.runtime.events import PipeEvent, RunLifecycleEvent
+from roboz.tooling.context import Ctx, _prepare_context
+from roboz.tooling.decorators import factory
+
+logger = logging.getLogger(__name__)
+
+type BackgroundAgentPhase = Literal["started", "alive", "restarted"]
+
+BACKGROUND_START_TIMEOUT_S: Final[float] = 5.0
+_STARTED_PHASE: Final[BackgroundAgentPhase] = "started"
+_ALIVE_PHASE: Final[BackgroundAgentPhase] = "alive"
+_RESTARTED_PHASE: Final[BackgroundAgentPhase] = "restarted"
+_RUN_STARTED_KIND: Final[Literal["started"]] = "started"
+
+
+@dataclass
+class BackgroundAgentState:
+    thread: threading.Thread | None = None
+    checks: int = 0
+    started_monotonic: float | None = None
+
+
+class BackgroundAgentStatus(Empty):
+    """Evolving heartbeat for a background daemon's trigger tool."""
+
+    status: BackgroundAgentPhase
+    agent: str
+    checks: int
+    uptime: str
+
+
+def _fmt_uptime(seconds: float) -> str:
+    total = int(seconds)
+    if total < 60:
+        return f"{total}s"
+    minutes, secs = divmod(total, 60)
+    if minutes < 60:
+        return f"{minutes}m{secs:02d}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{hours}h{minutes:02d}m"
+
+
+def _invoke_agent(ctx: Ctx) -> None:
+    agent = ctx.agent
+    logger.debug(
+        "Background agent invoke starting (name=%s, thread=%s)",
+        agent.name,
+        threading.current_thread().name,
+    )
+    try:
+        agent.invoke()
+    except Exception as error:  # noqa: BLE001 - background agents must not crash callers
+        logger.error(
+            "Background agent failed (name=%s, error_type=%s)",
+            agent.name,
+            type(error).__name__,
+        )
+    finally:
+        logger.debug("Background agent invoke returned (name=%s)", agent.name)
+
+
+def _status(
+    ctx: Ctx,
+    *,
+    status: BackgroundAgentPhase,
+    checks: int,
+    started_monotonic: float,
+) -> BackgroundAgentStatus:
+    return BackgroundAgentStatus(
+        status=status,
+        agent=ctx.agent.name,
+        checks=checks,
+        uptime=_fmt_uptime(time.monotonic() - started_monotonic),
+        truncation=NO_MESSAGE,
+    )
+
+
+@factory
+def run_background_agent(
+    input: Empty, messages: list[Message], ctx: Ctx
+) -> BackgroundAgentStatus:
+    """Start a background agent in a daemon thread and return a heartbeat."""
+    ctx.state.checks += 1
+    checks = ctx.state.checks
+    thread = ctx.state.thread
+    if thread is not None and thread.is_alive():
+        started_monotonic = ctx.state.started_monotonic or time.monotonic()
+        return _status(
+            ctx,
+            status=_ALIVE_PHASE,
+            checks=checks,
+            started_monotonic=started_monotonic,
+        )
+
+    # First start, or the previous daemon thread has died and we respawn it.
+    status = _RESTARTED_PHASE if thread is not None else _STARTED_PHASE
+    started_monotonic = time.monotonic()
+    ctx.state.started_monotonic = started_monotonic
+    thread = threading.Thread(
+        target=_invoke_agent,
+        args=(ctx,),
+        daemon=True,
+        name=f"background-agent-{ctx.agent.name}",
+    )
+    ctx.state.thread = thread
+    logger.debug(
+        "Spawning background agent thread (name=%s, status=%s, thread=%s)",
+        ctx.agent.name,
+        status,
+        thread.name,
+    )
+    started = Event()
+
+    def signal_started(event: PipeEvent) -> None:
+        if isinstance(event, RunLifecycleEvent) and event.kind == _RUN_STARTED_KIND:
+            started.set()
+
+    unsubscribe = ctx.agent.pipe.add_sink(signal_started)
+    try:
+        thread.start()
+        if not started.wait(BACKGROUND_START_TIMEOUT_S):
+            state = "alive" if thread.is_alive() else "stopped"
+            raise RuntimeError(
+                "background agent did not persist its lifecycle event "
+                f"within {BACKGROUND_START_TIMEOUT_S:g}s (thread={state})"
+            )
+    finally:
+        unsubscribe()
+    return _status(
+        ctx, status=status, checks=checks, started_monotonic=started_monotonic
+    )
+
+
+__all__ = [
+    "BackgroundAgentPhase",
+    "BackgroundAgentStatus",
+    "run_background_agent",
+]
+
+
+run_background_agent._prepare_ctx = partial(
+    _prepare_context,
+    required=("agent",),
+    default_factories={"state": BackgroundAgentState},
+)