roboshed 0.1.1.dev1__tar.gz → 0.1.1.dev2__tar.gz

{roboshed-0.1.1.dev1 → roboshed-0.1.1.dev2}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.1.1.dev2 - 2026-09-12
+
+- Breaking: move permission, sandbox, watched-agent, and default model inputs
+  from Shed capability objects to their owning `DeployableAgent` configuration.
+  Capability-specific thresholds, limits, timeouts, and endpoint overrides stay
+  on the capability objects.
+- Breaking: remove `Deployment` and replace the callable `RoboSprawl` dataclass
+  with a standalone configuration class. Construct `RoboSprawl()` without
+  inputs, supply runtime inputs through its setters, then call argument-free
+  `build()` to obtain fresh root/background agents. `robosprawl` aliases the
+  class, not the former function signature. The existing orchestrator defaults,
+  Librarian pipeline, project context, and persistence remain in the recipe.
+  Use one configuration instance per new run; see `docs/agent-factories.md`.
+
 ## 0.1.1.dev1 - 2026-09-12
 
 - Add `roboshed.deployments.robosprawl.RoboSprawl`, a callable configuration

{roboshed-0.1.1.dev1 → roboshed-0.1.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roboshed
-Version: 0.1.1.dev1
+Version: 0.1.1.dev2
 Import-Name: roboshed
 Summary: roboshed: optional building blocks for Roboz
 Project-URL: Repository, https://github.com/Tachion-Oy/roboz
@@ -11,7 +11,7 @@ Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: pydantic>=2.12.4
-Requires-Dist: roboz<0.2.0,>=0.1.2.dev3
+Requires-Dist: roboz<0.2.0,>=0.1.2.dev4
 Description-Content-Type: text/markdown
 
 # roboshed
@@ -35,48 +35,59 @@ permissions = PermissionPolicy.local(Path("./sandbox"))
 agent = DeployableAgent(
     name="file_worker",
     system_prompt="Complete the user's task, then call stop.",
-    agent_endpoint=MockLLMEndpoint([
-        {"action": "stop", "rationale": "done", "value": "Ready."}
-    ]),
-    capabilities=(
+    default_capabilities=(
         Capability(tools=(stop,)),
-        FileCommands(permissions),
-        FileEditing(permissions),
+        FileCommands(),
+        FileEditing(),
     ),
-).build()
+)
+agent.set_agent_endpoint(MockLLMEndpoint([
+    {"action": "stop", "rationale": "done", "value": "Ready."}
+]))
+agent.set_attributes(permissions=permissions)
+agent, background_agents = agent.build()
 result, messages = agent.invoke()
 ```
 
 `roboshed.capabilities` provides `FileCommands`, `FileEditing`, `Compactification`,
 `ConversationSnapshots`, `MemoryConsolidation`, `ArtifactRetention`, and
 `MaintenanceCadence`, alongside the `tools` and `skills` modules. Applications
-choose capabilities through each agent definition's `capabilities` tuple.
+choose fixed capabilities through `default_capabilities` and append application
+extensions with `add_capabilities()`.
 A capability owns its tools and skills. Generic `DeployableAgent` definitions
 live in `roboz.deployment`.
 Reusable `orchestrator` and `librarian` constructors live in `roboshed.agents`.
 The orchestrator owns stop and guarded file work, and the Librarian owns
 snapshots, consolidation, retention, and cadence. Root-only application
-capabilities go in `Deployment.additional_capabilities`, after the agent's
-built-in capability loop, without unpacking the role defaults.
+capabilities append after the agent's protected defaults, without unpacking the
+role definitions.
 
-Each capability uses an explicit endpoint override or its agent's default.
-Runtime controls remain separate. Direct standalone builds accept explicit
-`PermissionPolicy` and sandbox inputs.
+Each capability declares the typed attributes it reads from its owning
+`DeployableAgent`. Runtime controls remain separate. Use `set_attributes()` to
+supply standalone permission policies and sandbox inputs before building.
 
 See the [factory and migration guide](../../docs/agent-factories.md).
 
 ## RoboSprawl deployment recipe
 
-`roboshed.deployments.robosprawl.RoboSprawl` configures the concrete persistent
-orchestrator and Librarian recipe. Construct it with `memory_endpoint`,
-`additional_capabilities`, `subagents`, and `interaction_mode`. Call the object
-with an already-scoped sandbox, matching project slug, `endpoint_getter`, and
-optional `event_sinks` to receive a fresh unbuilt `Deployment`.
+`roboshed.deployments.robosprawl.RoboSprawl` is the concrete lazy persistent
+orchestrator and Librarian recipe. Construct `RoboSprawl()` without inputs;
+supply the required scoped sandbox, endpoint getter, and memory endpoint with
+`set_sandbox()`, `set_endpoint_getter()`, and `set_memory_endpoint()`.
+`set_additional_capabilities()`, `set_specialists()`, `set_interaction_mode()`,
+and `set_event_sinks()` supply optional inputs (empty sequences and
+`interaction_mode=None` by default). A `None` mode inherits core's current output
+setting, falling back to CLI when none is bound. Argument-free `build()` returns
+a fresh root/background-agent tuple
+or reports missing required inputs. `robosprawl` is an alias for this class.
 
 The recipe loads project memory and supplies project locations through initial
 messages. Its root follows the selected model getter; the Librarian uses its
-separate memory endpoint. Construction starts no agents and creates no
-directories. The application owns scope selection and runtime lifecycle.
+separate memory endpoint. Configuration and building start no agents or provider
+clients and create no project directories. Use a fresh recipe per new run;
+setters snapshot the sandbox and sequence containers, while supplied endpoints
+and capability/child objects remain caller-owned. The application owns scope
+selection and runtime lifecycle. See the [migration example](../../docs/agent-factories.md#fixed-robosprawl-recipe).
 
 ## Conversation compaction
 
@@ -129,17 +140,16 @@ See the [migration guide](https://github.com/Tachion-Oy/roboz/blob/main/docs/con
 for low-level context fields and state ownership.
 
 
-## Deployment instances
+## Deployable agent graphs
 
-Declare a `Deployment(agent=..., sandbox=...)` from `roboshed.deployments`.
-The root definition owns all recursive `subagents` and `background_agents`;
-both slots contain the same definition type. Configure the attached objects in
-place before building:
+The root `DeployableAgent` owns recursive `subagents` and `background_agents`;
+both slots contain the same definition type. Configure each object explicitly
+before building:
 
 ```python
-deployment.sandbox.configure_scope(folder)
-deployment.event_sinks.append(dispatch)
-agent, background_agents = deployment.build()
+sandbox.configure_scope(folder)
+definition.set_attributes(permissions=sandbox.permissions())
+agent, background_agents = definition.build(event_sinks=(dispatch,))
 ```
 
 Construct each application sandbox directly:
@@ -151,10 +161,9 @@ sandbox.configure_scope(folder)
 
 The host supplies `folder` at runtime. For now it is a direct child of the
 sandbox's existing `projects_dir`, with unchanged tiered permission behavior.
-Default persistence paths follow that scope, and CLI sinks are disabled unless
-requested. Startup memory is agent configuration, not deployment configuration.
-Each build captures its scope and sink registrations, so later reconfiguration
-cannot redirect an existing agent.
+Default persistence paths follow that scope. Startup memory and endpoints are
+agent configuration. Each build creates fresh runtime state; applications can
+supply an agent-specific sink factory for persistence.
 
 The Librarian constructor declares its standard maintenance sequence:
 snapshots, consolidation, retention, then cadence. Pass its sandbox and the
@@ -163,9 +172,10 @@ a background agent. The orchestrator also takes the configured sandbox and
 captures its permission policy when constructed.
 
 Invoke the returned agent directly and retain the background agents for control.
-Do not reconfigure the same deployment concurrently. Repeated builds create fresh
-runtimes and built-in persistence sinks, but supplied endpoint/sink objects remain
-caller-owned. The old factories, host protocols, and result bundles are removed.
+Repeated builds create fresh runtimes and bindings, but supplied endpoints,
+capabilities, and sinks remain caller-owned. No execution state is retained on
+the definition. The old deployment wrapper, factories, host protocols, and
+result bundles are removed.
 Use core's `roboz.llm.ModelSelector` for lazy model selection.
 `roboz.dependencies` supplies exact dependency registration and binding;
 `roboshed.dependency_health` supplies isolated `inspect_dependencies`, probes,
@@ -179,4 +189,4 @@ The `robosprawl` skill from `roboshed.skills` covers sandbox orientation and the
 HUD file-link/markdown contract. The external RoboSprawl application may select
 it through `Capability(auto_loaded_skills=(robosprawl,))`. Concrete paths,
 endpoints, extra capabilities, and specialist definitions remain application
-choices. The `RoboSprawl` recipe assembles them into a fresh `Deployment`.
+choices. The `robosprawl` recipe assembles and builds a fresh agent graph.

{roboshed-0.1.1.dev1 → roboshed-0.1.1.dev2}/README.md

@@ -19,48 +19,59 @@ permissions = PermissionPolicy.local(Path("./sandbox"))
 agent = DeployableAgent(
     name="file_worker",
     system_prompt="Complete the user's task, then call stop.",
-    agent_endpoint=MockLLMEndpoint([
-        {"action": "stop", "rationale": "done", "value": "Ready."}
-    ]),
-    capabilities=(
+    default_capabilities=(
         Capability(tools=(stop,)),
-        FileCommands(permissions),
-        FileEditing(permissions),
+        FileCommands(),
+        FileEditing(),
     ),
-).build()
+)
+agent.set_agent_endpoint(MockLLMEndpoint([
+    {"action": "stop", "rationale": "done", "value": "Ready."}
+]))
+agent.set_attributes(permissions=permissions)
+agent, background_agents = agent.build()
 result, messages = agent.invoke()
 ```
 
 `roboshed.capabilities` provides `FileCommands`, `FileEditing`, `Compactification`,
 `ConversationSnapshots`, `MemoryConsolidation`, `ArtifactRetention`, and
 `MaintenanceCadence`, alongside the `tools` and `skills` modules. Applications
-choose capabilities through each agent definition's `capabilities` tuple.
+choose fixed capabilities through `default_capabilities` and append application
+extensions with `add_capabilities()`.
 A capability owns its tools and skills. Generic `DeployableAgent` definitions
 live in `roboz.deployment`.
 Reusable `orchestrator` and `librarian` constructors live in `roboshed.agents`.
 The orchestrator owns stop and guarded file work, and the Librarian owns
 snapshots, consolidation, retention, and cadence. Root-only application
-capabilities go in `Deployment.additional_capabilities`, after the agent's
-built-in capability loop, without unpacking the role defaults.
+capabilities append after the agent's protected defaults, without unpacking the
+role definitions.
 
-Each capability uses an explicit endpoint override or its agent's default.
-Runtime controls remain separate. Direct standalone builds accept explicit
-`PermissionPolicy` and sandbox inputs.
+Each capability declares the typed attributes it reads from its owning
+`DeployableAgent`. Runtime controls remain separate. Use `set_attributes()` to
+supply standalone permission policies and sandbox inputs before building.
 
 See the [factory and migration guide](../../docs/agent-factories.md).
 
 ## RoboSprawl deployment recipe
 
-`roboshed.deployments.robosprawl.RoboSprawl` configures the concrete persistent
-orchestrator and Librarian recipe. Construct it with `memory_endpoint`,
-`additional_capabilities`, `subagents`, and `interaction_mode`. Call the object
-with an already-scoped sandbox, matching project slug, `endpoint_getter`, and
-optional `event_sinks` to receive a fresh unbuilt `Deployment`.
+`roboshed.deployments.robosprawl.RoboSprawl` is the concrete lazy persistent
+orchestrator and Librarian recipe. Construct `RoboSprawl()` without inputs;
+supply the required scoped sandbox, endpoint getter, and memory endpoint with
+`set_sandbox()`, `set_endpoint_getter()`, and `set_memory_endpoint()`.
+`set_additional_capabilities()`, `set_specialists()`, `set_interaction_mode()`,
+and `set_event_sinks()` supply optional inputs (empty sequences and
+`interaction_mode=None` by default). A `None` mode inherits core's current output
+setting, falling back to CLI when none is bound. Argument-free `build()` returns
+a fresh root/background-agent tuple
+or reports missing required inputs. `robosprawl` is an alias for this class.
 
 The recipe loads project memory and supplies project locations through initial
 messages. Its root follows the selected model getter; the Librarian uses its
-separate memory endpoint. Construction starts no agents and creates no
-directories. The application owns scope selection and runtime lifecycle.
+separate memory endpoint. Configuration and building start no agents or provider
+clients and create no project directories. Use a fresh recipe per new run;
+setters snapshot the sandbox and sequence containers, while supplied endpoints
+and capability/child objects remain caller-owned. The application owns scope
+selection and runtime lifecycle. See the [migration example](../../docs/agent-factories.md#fixed-robosprawl-recipe).
 
 ## Conversation compaction
 
@@ -113,17 +124,16 @@ See the [migration guide](https://github.com/Tachion-Oy/roboz/blob/main/docs/con
 for low-level context fields and state ownership.
 
 
-## Deployment instances
+## Deployable agent graphs
 
-Declare a `Deployment(agent=..., sandbox=...)` from `roboshed.deployments`.
-The root definition owns all recursive `subagents` and `background_agents`;
-both slots contain the same definition type. Configure the attached objects in
-place before building:
+The root `DeployableAgent` owns recursive `subagents` and `background_agents`;
+both slots contain the same definition type. Configure each object explicitly
+before building:
 
 ```python
-deployment.sandbox.configure_scope(folder)
-deployment.event_sinks.append(dispatch)
-agent, background_agents = deployment.build()
+sandbox.configure_scope(folder)
+definition.set_attributes(permissions=sandbox.permissions())
+agent, background_agents = definition.build(event_sinks=(dispatch,))
 ```
 
 Construct each application sandbox directly:
@@ -135,10 +145,9 @@ sandbox.configure_scope(folder)
 
 The host supplies `folder` at runtime. For now it is a direct child of the
 sandbox's existing `projects_dir`, with unchanged tiered permission behavior.
-Default persistence paths follow that scope, and CLI sinks are disabled unless
-requested. Startup memory is agent configuration, not deployment configuration.
-Each build captures its scope and sink registrations, so later reconfiguration
-cannot redirect an existing agent.
+Default persistence paths follow that scope. Startup memory and endpoints are
+agent configuration. Each build creates fresh runtime state; applications can
+supply an agent-specific sink factory for persistence.
 
 The Librarian constructor declares its standard maintenance sequence:
 snapshots, consolidation, retention, then cadence. Pass its sandbox and the
@@ -147,9 +156,10 @@ a background agent. The orchestrator also takes the configured sandbox and
 captures its permission policy when constructed.
 
 Invoke the returned agent directly and retain the background agents for control.
-Do not reconfigure the same deployment concurrently. Repeated builds create fresh
-runtimes and built-in persistence sinks, but supplied endpoint/sink objects remain
-caller-owned. The old factories, host protocols, and result bundles are removed.
+Repeated builds create fresh runtimes and bindings, but supplied endpoints,
+capabilities, and sinks remain caller-owned. No execution state is retained on
+the definition. The old deployment wrapper, factories, host protocols, and
+result bundles are removed.
 Use core's `roboz.llm.ModelSelector` for lazy model selection.
 `roboz.dependencies` supplies exact dependency registration and binding;
 `roboshed.dependency_health` supplies isolated `inspect_dependencies`, probes,
@@ -163,4 +173,4 @@ The `robosprawl` skill from `roboshed.skills` covers sandbox orientation and the
 HUD file-link/markdown contract. The external RoboSprawl application may select
 it through `Capability(auto_loaded_skills=(robosprawl,))`. Concrete paths,
 endpoints, extra capabilities, and specialist definitions remain application
-choices. The `RoboSprawl` recipe assembles them into a fresh `Deployment`.
+choices. The `robosprawl` recipe assembles and builds a fresh agent graph.

{roboshed-0.1.1.dev1 → roboshed-0.1.1.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboshed"
-version = "0.1.1.dev1"
+version = "0.1.1.dev2"
 description = "roboshed: optional building blocks for Roboz"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -9,7 +9,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE"]
 import-names = ["roboshed"]
 classifiers = ["Development Status :: 2 - Pre-Alpha", "Typing :: Typed"]
-dependencies = ["roboz>=0.1.2.dev3,<0.2.0","pydantic>=2.12.4"]
+dependencies = ["roboz>=0.1.2.dev4,<0.2.0","pydantic>=2.12.4"]
 
 [build-system]
 requires = ["hatchling>=1.32"]

{roboshed-0.1.1.dev1 → roboshed-0.1.1.dev2}/src/roboshed/agents/librarian.py

@@ -21,25 +21,30 @@ LIBRARIAN_AGENT_DESCRIPTION: Final[str] = (
 
 def librarian(
     sandbox: Sandbox,
-    agent_names: Collection[str],
+    watched_agent_names: Collection[str],
     *,
     agent_endpoint: EndpointLike | None,
 ) -> DeployableAgent:
     """Configure maintenance for the sandbox and foreground agent names."""
-    return DeployableAgent(
+    agent = DeployableAgent(
         name=LIBRARIAN_AGENT_NAME,
         description=LIBRARIAN_AGENT_DESCRIPTION,
-        interaction_mode=None,
         is_agentic=False,
         automatic_tool_prompt=False,
-        agent_endpoint=agent_endpoint,
-        capabilities=(
-            ConversationSnapshots(sandbox=sandbox, agent_names=agent_names),
-            MemoryConsolidation(sandbox=sandbox, agent_names=agent_names),
-            ArtifactRetention(sandbox=sandbox),
-            MaintenanceCadence(sandbox=sandbox, agent_names=agent_names),
+        default_capabilities=(
+            ConversationSnapshots(),
+            MemoryConsolidation(),
+            ArtifactRetention(),
+            MaintenanceCadence(),
         ),
     )
+    agent.set_agent_endpoint(agent_endpoint)
+    agent.set_interaction_mode(None)
+    agent.set_attributes(
+        sandbox=sandbox,
+        watched_agent_names=frozenset(watched_agent_names),
+    )
+    return agent
 
 
 __all__ = ["LIBRARIAN_AGENT_DESCRIPTION", "librarian"]

{roboshed-0.1.1.dev1 → roboshed-0.1.1.dev2}/src/roboshed/agents/orchestrator.py

@@ -30,21 +30,23 @@ def orchestrator(
     initial_messages: Sequence[Path | str] = (),
 ) -> DeployableAgent:
     """Configure the orchestrator for an already-configured sandbox."""
-    return DeployableAgent(
+    agent = DeployableAgent(
         name="orchestrator",
         description="Coordinates ongoing user goals and specialist agents.",
         system_prompt=ORCHESTRATOR_PROMPT,
-        agent_endpoint=agent_endpoint,
-        capabilities=(
+        default_capabilities=(
             Capability(tools=(stop,)),
-            FileCommands(sandbox.permissions()),
-            FileEditing(sandbox.permissions()),
+            FileCommands(),
+            FileEditing(),
         ),
         subagents=tuple(subagents),
         background_agents=tuple(background_agents),
-        interaction_mode=interaction_mode,
-        initial_messages=tuple(initial_messages),
     )
+    agent.set_agent_endpoint(agent_endpoint)
+    agent.set_interaction_mode(interaction_mode)
+    agent.set_initial_messages(initial_messages)
+    agent.set_attributes(permissions=sandbox.permissions())
+    return agent
 
 
 __all__ = ["ORCHESTRATOR_PROMPT", "orchestrator"]