roboz 0.1.2.dev2__tar.gz → 0.1.2.dev3__tar.gz

{roboz-0.1.2.dev2 → roboz-0.1.2.dev3}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.1.2.dev3 - 2026-09-11
+
+- Breaking: remove the redundant `roboz[shed]` installation extra. Install
+  `roboshed` directly; it installs its compatible core Roboz dependency.
+
+- Add `DeployableAgent.build_graph()` to return the root agent and all background
+  handles for host lifecycle control. `build()` still returns the root alone.
+
+- Breaking: replace `AgentDefinition` and `SubAgentSpec` with recursive
+  `DeployableAgent` definitions. Put child definitions directly in `subagents`
+  or `background_agents`; delegation tools use the child's name and description,
+  and background agents start through default tools. Construct generic
+  definitions directly with `DeployableAgent(...)`.
+  Sandbox-aware `Deployment` lives in `roboshed.deployments`, not core.
+  See `docs/agent-factories.md` for migration.
+
 ## 0.1.2.dev2 - 2026-09-09
 
 - Breaking: remove the `roboz[openai]` extra. Install
@@ -20,7 +36,7 @@
   references retain identity and deferred resolution. See
   `docs/agent-factories.md` for builder migration.
 
-- Breaking: move the Librarian and its memory/summarization tools out of core into `roboshed.agents` and `roboshed.tools`. Use `librarian(capabilities=..., agent_endpoint=...)` instead of `LibrarianConstructor` and its path record; see `docs/agent-factories.md`. Core retains control, interaction, and generic construction primitives.
+- Breaking: move the Librarian and its memory/summarization tools out of core into `roboshed.agents` and `roboshed.tools`. Use `librarian(sandbox, agent_names, agent_endpoint=...)` instead of `LibrarianConstructor` and its path record; see `docs/agent-factories.md`. Core retains control, interaction, and generic construction primitives.
 
 - Add generic `AgentDefinition`, `AgentCapability`, `Capability`, and `SubAgentSpec` in `roboz.deployment`. Configure all tools and skills through capabilities, with fresh agent pipes and explicit sink configuration; definitions select no project, memory, or persistence conventions. See `docs/agent-factories.md`.
 

{roboz-0.1.2.dev2 → roboz-0.1.2.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev2
+Version: 0.1.2.dev3
 Import-Name: roboz
 Summary: Typed primitives for composable agentic workflows
 Project-URL: Homepage, https://github.com/Tachion-Oy/roboz
@@ -25,8 +25,6 @@ Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: rich>=14.2.0
 Provides-Extra: proton-bridge-beta
 Requires-Dist: roboz-proton-bridge<0.2.0,>=0.1.0b1; extra == 'proton-bridge-beta'
-Provides-Extra: shed
-Requires-Dist: roboshed<0.2.0,>=0.1.0a2; extra == 'shed'
 Description-Content-Type: text/markdown
 
 # Roboz
@@ -170,12 +168,16 @@ Install `roboz-endpoints[openai]` for the initial OpenRouter, Cerebras, and Groq
 catalogues; it installs core automatically. See the
 [endpoint guide](packages/endpoints/README.md) for model selection and SDK adapters.
 
-`roboz.deployment` supplies generic agent definitions, capability contracts,
-and specialist composition. Capabilities accept tool-specific endpoints and pass
-them directly to their tools, using the owning agent's endpoint as the default. `roboshed` supplies orchestrator/Librarian
-factories, concrete capabilities, memory tools, and workspace structure. These are described in [agent factories](docs/agent-factories.md). Configured file and compaction capabilities live in `roboshed.capabilities`,
-alongside `roboshed.tools` and `roboshed.skills`. The project deployment lives in
-`roboshed.deployments.robosprawl`; agent presets live in `roboshed.agents`.
+`roboz.deployment` supplies recursive `DeployableAgent` definitions and
+capability contracts. Put definitions directly in `subagents` or
+`background_agents`. Capabilities accept tool-specific endpoints and use the
+owning agent's endpoint as their default. `roboshed` supplies reusable
+orchestrator and Librarian constructors, concrete capabilities, memory tools,
+and sandbox structure. Import the constructors from `roboshed.agents`; concrete
+RoboSprawl configuration belongs to the external application. Sandbox-aware
+assembly lives in `roboshed.deployments.Deployment`: configure
+`deployment.sandbox.configure_scope(folder)` and `deployment.event_sinks`, then
+unpack `agent, background_agents = deployment.build()`.
 
 ## Documentation
 

{roboz-0.1.2.dev2 → roboz-0.1.2.dev3}/README.md

@@ -139,12 +139,16 @@ Install `roboz-endpoints[openai]` for the initial OpenRouter, Cerebras, and Groq
 catalogues; it installs core automatically. See the
 [endpoint guide](packages/endpoints/README.md) for model selection and SDK adapters.
 
-`roboz.deployment` supplies generic agent definitions, capability contracts,
-and specialist composition. Capabilities accept tool-specific endpoints and pass
-them directly to their tools, using the owning agent's endpoint as the default. `roboshed` supplies orchestrator/Librarian
-factories, concrete capabilities, memory tools, and workspace structure. These are described in [agent factories](docs/agent-factories.md). Configured file and compaction capabilities live in `roboshed.capabilities`,
-alongside `roboshed.tools` and `roboshed.skills`. The project deployment lives in
-`roboshed.deployments.robosprawl`; agent presets live in `roboshed.agents`.
+`roboz.deployment` supplies recursive `DeployableAgent` definitions and
+capability contracts. Put definitions directly in `subagents` or
+`background_agents`. Capabilities accept tool-specific endpoints and use the
+owning agent's endpoint as their default. `roboshed` supplies reusable
+orchestrator and Librarian constructors, concrete capabilities, memory tools,
+and sandbox structure. Import the constructors from `roboshed.agents`; concrete
+RoboSprawl configuration belongs to the external application. Sandbox-aware
+assembly lives in `roboshed.deployments.Deployment`: configure
+`deployment.sandbox.configure_scope(folder)` and `deployment.event_sinks`, then
+unpack `agent, background_agents = deployment.build()`.
 
 ## Documentation
 

{roboz-0.1.2.dev2 → roboz-0.1.2.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboz"
-version = "0.1.2.dev2"
+version = "0.1.2.dev3"
 description = "Typed primitives for composable agentic workflows"
 readme = "README.md"
 authors = [{ name = "Tachion Oy" }]
@@ -30,7 +30,6 @@ requires = ["hatchling>=1.32"]
 build-backend = "hatchling.build"
 
 [project.optional-dependencies]
-shed = ["roboshed>=0.1.0a2,<0.2.0"]
 proton-bridge-beta = ["roboz-proton-bridge>=0.1.0b1,<0.2.0"]
 
 [tool.uv.workspace]

{roboz-0.1.2.dev2 → roboz-0.1.2.dev3}/src/roboz/deployment.py

@@ -1,11 +1,13 @@
 """Data-driven agent definitions and runtime-bound capabilities."""
 
+from __future__ import annotations
+
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Protocol
 
-from roboz.agent import Agent, run_subagent
+from roboz.agent import Agent, run_background_agent, run_subagent
 from roboz.llm import EndpointLike
 from roboz.runtime import EventPipe, EventSink, Output
 from roboz.skill import Skill
@@ -48,24 +50,19 @@ class Capability(AgentCapability):
         return self
 
 
-@dataclass(frozen=True)
-class SubAgentSpec:
-    """A specialist definition and its parent-facing tool identity."""
-
-    definition: "AgentDefinition"
-    tool_name: str
-    tool_description: str
-
-
 @dataclass(frozen=True, kw_only=True)
-class AgentDefinition:
-    """Configured inputs for independently constructing an agent runtime.
+class DeployableAgent:
+    """One agent's configuration, including its sub-agents and background agents.
 
     All tools and skills enter through capabilities. Already-bound inputs and
     endpoint dependencies are supplied objects; callers own their reuse. Scripted
     mock endpoints that consume responses must be recreated for each run.
-    Each capability selects its tool endpoints, using the agent endpoint as
-    the default. Endpoint objects remain independent of runtime controls.
+    Configure definitions before building; do not mutate them concurrently with
+    construction. Each capability selects its tool endpoints, using the agent
+    endpoint as the default. Endpoint objects remain independent of runtime controls.
+    Sub-agents become named delegation tools. Background agents are started
+    through default tools when their parent runs. Both slots contain the same
+    recursive definition type.
     """
 
     name: str
@@ -76,14 +73,24 @@ class AgentDefinition:
     is_agentic: bool = True
     automatic_tool_prompt: bool = True
     capabilities: tuple[AgentCapability, ...] = ()
-    subagents: tuple[SubAgentSpec, ...] = ()
+    subagents: tuple["DeployableAgent", ...] = ()
+    background_agents: tuple["DeployableAgent", ...] = ()
     initial_messages: tuple[Path | str, ...] = ()
 
-    def agent_names(self) -> frozenset[str]:
-        """Return recursive agent identities, rejecting ambiguous names."""
+    def agent_names(self, *, include_background: bool = True) -> frozenset[str]:
+        """Validate all names and return identities in the selected branches.
+
+        Excluding background agents also excludes their descendants, for
+        foreground-only consumers such as conversation maintenance.
+        """
+        if not include_background:
+            self.agent_names()
         names = {self.name}
-        for spec in self.subagents:
-            children = spec.definition.agent_names()
+        definitions = self.subagents
+        if include_background:
+            definitions += self.background_agents
+        for definition in definitions:
+            children = definition.agent_names(include_background=include_background)
             if names & children:
                 raise ValueError("agent names must be unique")
             names.update(children)
@@ -97,9 +104,28 @@ class AgentDefinition:
     ) -> Agent:
         """Create fresh pipes, resolve capabilities, and construct the agent once.
 
-        Caller sinks follow specialists. The optional factory supplies fresh
+        Caller sinks follow synchronous children. The optional factory supplies fresh
         agent-specific sinks by name; these are never inherited by children.
         Without supplied sinks, construction selects no output or persistence.
+        Use build_graph() to retain background agents for host control.
+        """
+        return self.build_graph(
+            event_sinks=event_sinks, event_sink_factory=event_sink_factory
+        )[0]
+
+    def build_graph(
+        self,
+        *,
+        event_sinks: Sequence[EventSink] = (),
+        event_sink_factory: Callable[[str], Sequence[EventSink]] | None = None,
+    ) -> tuple[Agent, tuple[Agent, ...]]:
+        """Build fresh agents and return the root and all background handles.
+
+        Validate names before constructing capabilities or sinks. Sink routing
+        follows build(): caller sinks reach foreground branches only, and the
+        factory supplies each agent's own sinks. Background handles include
+        descendants of both child slots. No agents are started by construction;
+        callers own their invocation and shutdown.
         """
         self.agent_names()
         pipe = EventPipe(
@@ -115,16 +141,32 @@ class AgentDefinition:
             )
 
         tools = [tool for contribution in contributions for tool in contribution.tools]
-        for spec in self.subagents:
-            child = spec.definition.build(
+        default_tools = [tool for c in contributions for tool in c.default_tools]
+        background_agents: list[Agent] = []
+        for definition in self.subagents:
+            child, descendants = definition.build_graph(
                 event_sinks=event_sinks, event_sink_factory=event_sink_factory
             )
-            delegation = run_subagent(Ctx(agent=child)).copy(
-                name=spec.tool_name, description=spec.tool_description
+            tools.append(
+                run_subagent(Ctx(agent=child)).copy(
+                    name=child.name,
+                    description=child.description,
+                )
+            )
+            background_agents.extend(descendants)
+        for definition in self.background_agents:
+            child, descendants = definition.build_graph(
+                event_sink_factory=event_sink_factory
+            )
+            default_tools.append(
+                run_background_agent(Ctx(agent=child)).copy(
+                    name=f"start_background_agent_{child.name}",
+                )
             )
-            tools.append(delegation)
+            background_agents.append(child)
+            background_agents.extend(descendants)
 
-        return Agent(
+        agent = Agent(
             name=self.name,
             description=self.description,
             agent_endpoint=self.agent_endpoint,
@@ -134,18 +176,18 @@ class AgentDefinition:
             automatic_tool_prompt=self.automatic_tool_prompt,
             system_prompt=self.system_prompt,
             tools=tools,
-            default_tools=[tool for c in contributions for tool in c.default_tools],
+            default_tools=default_tools,
             skills=[skill for c in contributions for skill in c.skills],
             auto_loaded_skills=[
                 skill for c in contributions for skill in c.auto_loaded_skills
             ],
             initial_messages=self.initial_messages,
         )
+        return agent, tuple(background_agents)
 
 
 __all__ = [
     "AgentCapability",
-    "AgentDefinition",
     "Capability",
-    "SubAgentSpec",
+    "DeployableAgent",
 ]