aisolate-agent 0.3.1__tar.gz → 0.3.2__tar.gz

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aisolate-agent
-Version: 0.3.1
+Version: 0.3.2
 Summary: AI Agent with intelligent planning and reasoning
 License: Apache-2.0
 Requires-Python: >=3.10
@@ -30,7 +30,7 @@ AI Agent with intelligent planning and reasoning
 ## Local Installation
 
 ```bash
-pip install path/to/aisolate_agent-0.3.1-py3-none-any.whl
+pip install path/to/aisolate_agent-0.3.2-py3-none-any.whl
 ```
 
 ## Usage

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/README.md

@@ -5,7 +5,7 @@ AI Agent with intelligent planning and reasoning
 ## Local Installation
 
 ```bash
-pip install path/to/aisolate_agent-0.3.1-py3-none-any.whl
+pip install path/to/aisolate_agent-0.3.2-py3-none-any.whl
 ```
 
 ## Usage

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aisolate-agent"
-version = "0.3.1"
+version = "0.3.2"
 description = "AI Agent with intelligent planning and reasoning"
 readme = "README.md"
 requires-python = ">=3.10"

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/agent.py

@@ -16,6 +16,7 @@ from .core.graph import AgentGraph
 from .core.protocols import LLMStrategy, MemoryStrategy
 from .core.snapshot import AgentSnapshot
 from .core.budget import RunBudget
+from .core.initial_state import InitialState
 from .core.events import (
     AgentStartedEvent,
     TurnStartedEvent,
@@ -316,6 +317,7 @@ class Agent:
         self, task: str, conversation_id: str,
         *, cancel_event: "Optional[asyncio.Event]" = None,
         budget: Optional[RunBudget] = None,
+        initial_state: "Optional[InitialState]" = None,
     ):
         """Run the agent with streaming updates.
 
@@ -336,6 +338,10 @@ class Agent:
                 ``cancel_event``, with reason ``time_budget`` /
                 ``token_budget``. Both signals live on the root context;
                 sub loops observe them through ``suspension_due()``.
+            initial_state: Log events and workspace files to seed beside the
+                task. Applied at CYCLE start only — a fresh run or a follow-up
+                on a finished conversation — and ignored on a mid-run resume,
+                which already holds its state.
 
         Yields:
             Dict updates about agent state, tool calls, and progress
@@ -398,6 +404,7 @@ class Agent:
                 # through suspension_due() → root_context().
                 context.cancel_event = cancel_event
                 context.budget = budget
+                context.initial_state = initial_state
 
                 # RESTORATION LOGIC - Load and apply snapshot if it exists
                 snapshot = await context.memory.load_latest_snapshot(conversation_id)
@@ -1392,6 +1399,13 @@ class Agent:
             "turn": context.turn,
             "suspended_at": datetime.now(timezone.utc).isoformat(),
         }
+        if reason == "turn_budget":
+            # The cap that bound the run, so a caller can raise it without
+            # knowing how this agent was configured. Resuming a turn-budget
+            # suspension with an unchanged cap re-suspends without executing a
+            # turn (see the check in the run loop), which is indistinguishable
+            # from a run that tried and got nowhere.
+            context.suspension["max_turns"] = self.settings.max_turns
         if reason == "hitl" and context.pending_hitl_signal is not None:
             context.suspension["signal"] = dict(
                 context.pending_hitl_signal.__dict__
@@ -1596,11 +1610,17 @@ class Agent:
             # Each state projects its own prompt envelope from the log.
             if not context.conversation.events():
                 context.seed_task()
+                context.apply_initial_state()
 
             # Enter the graph's entry node (only if not restored from snapshot)
             if context.execution.current_state is None:
                 context.enter_node(self.graph.entry)
 
+            # Where this run picked up the counter. A resumed run that suspends
+            # again having executed nothing did not try and fail — its budget
+            # was never raised.
+            turn_at_entry = context.turn
+
             yield AgentStartedEvent(
                 task=context.task,
                 turn=context.turn,
@@ -1641,9 +1661,12 @@ class Agent:
                 ):
                     suspend_reason = "turn_budget"
                     bound_logger.warning(
-                        "Turn budget exhausted — suspending (resumable)",
+                        "Turn budget exhausted — suspending (resumable). "
+                        "A resume must RAISE max_turns; an unchanged cap "
+                        "re-suspends here without executing a turn.",
                         turn=context.turn,
                         max_turns=self.settings.max_turns,
+                        executed_this_run=context.turn - turn_at_entry,
                     )
                     break
 

aisolate_agent-0.3.2/src/aisolate/agent/core/__init__.py

@@ -0,0 +1,41 @@
+"""Core agent module containing foundational components.
+
+Alongside the strategy protocols and the run context, this exports the workflow
+composition surface — ``AgentGraph``, its routing/validation types, and the
+``policy`` routers — so a consumer can compose its own control flow from the
+same parts ``aisolate.agent.graphs`` uses.
+"""
+
+from . import policy
+from .protocols import LLMStrategy, MemoryStrategy, Tool
+from .exceptions import AgentError, StateTransitionError, ToolExecutionError
+from .context import AgentContext
+from .graph import (
+    AgentGraph,
+    GraphValidationError,
+    Router,
+    RoutingDecision,
+    RoutingError,
+)
+from .initial_state import InitialState, WorkspaceSeed
+from .llm_response import TokenUsage, LLMResponse
+
+__all__ = [
+    "LLMStrategy",
+    "MemoryStrategy",
+    "Tool",
+    "AgentError",
+    "StateTransitionError",
+    "ToolExecutionError",
+    "AgentContext",
+    "AgentGraph",
+    "InitialState",
+    "WorkspaceSeed",
+    "GraphValidationError",
+    "Router",
+    "RoutingDecision",
+    "RoutingError",
+    "policy",
+    "TokenUsage",
+    "LLMResponse",
+]

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/core/context.py

@@ -42,6 +42,7 @@ if TYPE_CHECKING:  # pragma: no cover
     from ..tools.models import FinalAnswerResult
     from .budget import RunBudget
     from .graph import AgentGraph, RoutingDecision
+    from .initial_state import InitialState
 
 logger = get_logger("aisolate.agent.core.context")
 
@@ -304,6 +305,10 @@ class AgentContext:
         self.current_node: Optional[str] = None
         self._node_instances: Dict[str, "State"] = {}
 
+        # Caller-supplied opening state, applied at cycle start only (see
+        # apply_initial_state).
+        self.initial_state: Optional["InitialState"] = None
+
         # Review posture. ``review_count`` is derived from the log (see the
         # property); only the budget is a plain field.
         self.max_reviews: int = 2
@@ -533,6 +538,24 @@ class AgentContext:
             )
         )
 
+    def apply_initial_state(self) -> None:
+        """Apply the caller's supplied opening state, if any.
+
+        Called beside ``seed_task`` — the two cycle starts, a fresh run and a
+        follow-up — and nowhere else: a mid-run resume already holds this state
+        and re-applying it would overwrite live work. Files OVERLAY the
+        manifest, so a follow-up's restored artifacts survive.
+        """
+        state = self.initial_state
+        if not state:
+            return
+        for event in state.events:
+            self.conversation.append(event)
+        for seed in state.files:
+            self.artifacts.put_text(
+                seed.path, seed.text, kind=seed.kind, mime=seed.mime,
+            )
+
     def active_view(self) -> List[Message]:
         """The current state's projected LLM input (its curated view of the log).
 
@@ -719,9 +742,10 @@ class AgentContext:
           message is appended to the log as a ``steering`` event — binding
           user input for the remaining work, NOT a new task;
         * a finished cycle → a follow-up: the new user message becomes a new
-          ``task`` event and the run starts at planning on a FRESH turn
-          budget — planning's view seeds it with the latest compaction (or
-          the unsuperseded prior final);
+          ``task`` event and the run starts at the graph's ``cycle_entry``
+          (``planning`` for both shipped shapes) on a FRESH turn budget —
+          planning's view seeds it with the latest compaction (or the
+          unsuperseded prior final);
         * unfinished with NO posture → crash-degraded: the same mid-run
           resume at ``current_node``, plus a synthetic note that the run was
           interrupted uncleanly (kernel state may be lost).
@@ -877,7 +901,8 @@ class AgentContext:
                         ),
                     ))
             self.seed_task(self._initial_task)
-            self.enter_node("planning")
+            self.apply_initial_state()
+            self.enter_node(self.graph.cycle_entry)
             return
 
         # Suspended (stop / time_budget / token_budget) or crash-degraded

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/core/conversation_log.py

@@ -134,6 +134,11 @@ META_KEYS = frozenset(
         "omitted_count",
         "artifact_key",
         "tool_call_id",
+        # Who authored the event, when that is not the state whose phase it
+        # carries: "supplied" marks one the caller seeded at cycle start
+        # (see core.initial_state), which reads and renders exactly like a
+        # generated one and must stay distinguishable in a trace.
+        "origin",
     }
 )
 

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/core/graph.py

@@ -5,10 +5,17 @@ An ``AgentGraph`` is the whole control-flow story of an agent: named nodes
 ``(node, Output type)``, and — where a transition is a decision rather than a
 constant — a pure policy router that returns a ``RoutingDecision``.
 
+Everything the framework needs to know about a workflow is DECLARED here, not
+inferred elsewhere from node names: where a run starts (``entry``), where a new
+cycle starts (``cycle_entry``), and whether the run maintains the workspace
+checklist (``workspace_ops``). A consumer composing its own graph therefore gets
+the same behaviour the shipped shapes get, without the framework having to
+recognise it.
+
 The graph is validated at construction, so an incoherent workflow fails when
 it is composed, not turns later mid-run:
 
-* the entry node exists; every edge references known nodes;
+* the entry and cycle-entry nodes exist; every edge references known nodes;
 * every output a node declares in ``produces`` has a route;
 * at least one node is terminal (the run can end);
 * the view lint: every kind a node declares in ``emits`` is viewed by some
@@ -80,6 +87,17 @@ class AgentGraph:
     entry: str
     nodes: Mapping[str, Callable[[], "State"]]
     edges: Mapping[Tuple[str, Type["Output"]], Union[str, Router]]
+    #: Where a NEW CYCLE starts — a follow-up request on a finished
+    #: conversation. Distinct from ``entry`` because intake nodes run once per
+    #: conversation, not once per cycle: the standard graph enters at
+    #: ``clarification`` and re-enters at ``planning``. Defaults to ``entry``.
+    cycle_entry: Optional[str] = None
+    #: Whether this workflow maintains the workspace checklist and working
+    #: memory (``task.md`` / ``memory.md``, via the ``mark_tasks`` /
+    #: ``write_memory`` ops). Defaults to ``"task" in nodes`` — the node that
+    #: generates a checklist implies one — so a graph that obtains its
+    #: checklist another way declares it instead.
+    workspace_ops: Optional[bool] = None
     # One prototype instance per node, built during validation. Used for
     # declaration lookups (produces/emits/view/terminal) — never for runs.
     _prototypes: Dict[str, "State"] = field(
@@ -89,6 +107,10 @@ class AgentGraph:
     def __post_init__(self) -> None:
         object.__setattr__(self, "nodes", dict(self.nodes))
         object.__setattr__(self, "edges", dict(self.edges))
+        if self.cycle_entry is None:
+            object.__setattr__(self, "cycle_entry", self.entry)
+        if self.workspace_ops is None:
+            object.__setattr__(self, "workspace_ops", "task" in self.nodes)
         self._validate()
 
     # ---- routing -------------------------------------------------------------
@@ -130,6 +152,11 @@ class AgentGraph:
             raise GraphValidationError(
                 f"entry node {self.entry!r} is not in nodes {sorted(self.nodes)}"
             )
+        if self.cycle_entry not in self.nodes:
+            raise GraphValidationError(
+                f"cycle_entry node {self.cycle_entry!r} is not in nodes "
+                f"{sorted(self.nodes)}"
+            )
 
         for name, factory in self.nodes.items():
             try:

aisolate_agent-0.3.2/src/aisolate/agent/core/initial_state.py

@@ -0,0 +1,48 @@
+"""State a caller supplies at cycle start, beside the task.
+
+A run's opening state had exactly one producer: the memory strategy's latest
+snapshot for the conversation. The task, which is also opening state, was
+already an argument — this makes the rest one too, so a caller that knows the
+plan (a pipeline whose stage prompt IS the plan), or that wants to fork a
+conversation, replay from a known state, or construct a mid-cycle posture in a
+test, can say so instead of writing a snapshot first.
+
+Applied where a CYCLE starts — a fresh run, or a follow-up on a finished
+conversation — and ignored on a mid-run resume, whose state is already live and
+must not be overwritten. ``events`` append to the log in order; ``files``
+overlay the workspace manifest, so a follow-up's restored artifacts survive and
+named slots are replaced.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional, Tuple
+
+if TYPE_CHECKING:
+    from .conversation_log import Event
+
+
+@dataclass(frozen=True)
+class WorkspaceSeed:
+    """One workspace file to place before the first turn.
+
+    ``kind`` is the framework's internal role for its reserved slots (see
+    ``core.workspace.named_kind``); ``None`` for an ordinary file.
+    """
+
+    path: str
+    text: str
+    kind: Optional[str] = None
+    mime: str = "text/markdown"
+
+
+@dataclass(frozen=True)
+class InitialState:
+    """Log events and workspace files to seed at cycle start."""
+
+    events: Tuple["Event", ...] = field(default_factory=tuple)
+    files: Tuple[WorkspaceSeed, ...] = field(default_factory=tuple)
+
+    def __bool__(self) -> bool:
+        return bool(self.events or self.files)

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/graphs.py

@@ -13,7 +13,8 @@ judges the handover), no compaction (the bounded output IS the handover), and
 therefore no HITL at all.
 
 Composition facts, not flags: an agent reviews iff the graph has a ``critic``
-node; a graph without clarification starts at planning. The workflow is
+node; a graph without clarification starts at planning. Both shapes declare
+``cycle_entry="planning"`` — a follow-up skips intake. The workflow is
 substrate-independent — the same shapes run on the jupyter and shell bindings
 (see ``aisolate.agent.substrate``).
 
@@ -108,7 +109,9 @@ def build_workflow(
     if role == "sub":
         # The bounded output IS the handover — no review, no compaction.
         edges[("executing", FinalDrafted)] = "finished"
-        return AgentGraph(entry=entry, nodes=nodes, edges=edges)
+        return AgentGraph(
+            entry=entry, nodes=nodes, edges=edges, cycle_entry="planning",
+        )
 
     nodes["compaction"] = CompactionState
     edges[("executing", FinalDrafted)] = policy.route_after_final
@@ -129,7 +132,11 @@ def build_workflow(
         edges[("critic", VerdictProduced)] = policy.route_after_verdict
         edges[("critic", ReviewFailed)] = policy.route_after_review_failure
 
-    return AgentGraph(entry=entry, nodes=nodes, edges=edges)
+    # A follow-up re-enters at planning, never at clarification: intake happens
+    # once per conversation, and the human is not asked to restate the brief.
+    return AgentGraph(
+        entry=entry, nodes=nodes, edges=edges, cycle_entry="planning",
+    )
 
 
 STANDARD_GRAPH = build_workflow()

aisolate_agent-0.3.2/src/aisolate/agent/states/__init__.py

@@ -0,0 +1,64 @@
+"""States module for agent lifecycle management.
+
+This is the supported surface for composing a workflow: the node classes, plus
+the ``Output`` types that key an ``AgentGraph``'s edges. Compose them with
+``aisolate.agent.core.AgentGraph`` and the routers in
+``aisolate.agent.core.policy``; ``aisolate.agent.graphs.build_workflow`` is one
+convenience constructor over the same parts, not the only way in.
+"""
+
+from .base import AbstractState, State, StateResult
+from .clarification import ClarificationState
+from .compaction import CompactionState
+from .critic import CriticState
+from .executing import ExecutingState
+from .expert_synthesis import ExpertSynthesisState
+from .finished import FinishedState
+from .hitl_pause import HITLPauseState
+from .planning import PlanningState
+from .task import TaskState
+from .outputs import (
+    BriefProduced,
+    CompactionFailed,
+    CompactionWritten,
+    FinalDrafted,
+    IntakeComplete,
+    NoAction,
+    Output,
+    PlanProduced,
+    QuestionAsked,
+    ReviewFailed,
+    Stalled,
+    TasksProduced,
+    ToolExecuted,
+    VerdictProduced,
+)
+
+__all__ = [
+    "AbstractState",
+    "State",
+    "StateResult",
+    "ClarificationState",
+    "CompactionState",
+    "CriticState",
+    "ExecutingState",
+    "ExpertSynthesisState",
+    "FinishedState",
+    "HITLPauseState",
+    "PlanningState",
+    "TaskState",
+    "Output",
+    "BriefProduced",
+    "CompactionFailed",
+    "CompactionWritten",
+    "FinalDrafted",
+    "IntakeComplete",
+    "NoAction",
+    "PlanProduced",
+    "QuestionAsked",
+    "ReviewFailed",
+    "Stalled",
+    "TasksProduced",
+    "ToolExecuted",
+    "VerdictProduced",
+]

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/substrate.py

@@ -148,7 +148,7 @@ class ExecutionSubstrate:
 
         A sub-agent runs the forced lean workflow, not the graph its Agent
         was constructed against — so ops gated on the graph (the workspace
-        ops) are re-derived here against the sub graph. Returns
+        ops it declares) are re-derived here against the sub graph. Returns
         ``(extra_actions, extra_tools)``: kernel CodeActions on jupyter,
         host-side tools on shell.
         """
@@ -208,11 +208,11 @@ class JupyterSubstrate(ExecutionSubstrate):
 
             actions["load_handover_data"] = LoadHandoverAction()
 
-        # The task workflow (planning → task → executing) exposes the
-        # workspace actions that maintain task.md / memory.md in the worker
-        # directory.
+        # A workflow that maintains task.md / memory.md gets the ops that
+        # maintain them (the graph declares this; it is not read off the node
+        # set, so a supplied checklist keeps its tools).
         graph = self.agent.graph
-        if graph is not None and "task" in getattr(graph, "nodes", {}):
+        if graph is not None and getattr(graph, "workspace_ops", False):
             from .tools.actions.workspace import MarkTasksAction, WriteMemoryAction
 
             actions["mark_tasks"] = MarkTasksAction()
@@ -221,7 +221,7 @@ class JupyterSubstrate(ExecutionSubstrate):
         return actions
 
     def delegation_ops(self, sub_graph) -> "tuple[Dict[str, Any], List[Any]]":
-        if sub_graph is None or "task" not in getattr(sub_graph, "nodes", {}):
+        if sub_graph is None or not getattr(sub_graph, "workspace_ops", False):
             return {}, []
         from .tools.actions.workspace import MarkTasksAction, WriteMemoryAction
 
@@ -352,7 +352,7 @@ class ShellSubstrate(ExecutionSubstrate):
             ShellFinalAnswerTool(),
         ]
         graph = self.agent.graph
-        if graph is not None and "task" in getattr(graph, "nodes", {}):
+        if graph is not None and getattr(graph, "workspace_ops", False):
             tools.append(MarkTasksTool())
             tools.append(WriteMemoryTool())
         for tool in tools:
@@ -365,7 +365,7 @@ class ShellSubstrate(ExecutionSubstrate):
         return {}
 
     def delegation_ops(self, sub_graph) -> "tuple[Dict[str, Any], List[Any]]":
-        if sub_graph is None or "task" not in getattr(sub_graph, "nodes", {}):
+        if sub_graph is None or not getattr(sub_graph, "workspace_ops", False):
             return {}, []
         from .tools.platform.workspace_tools import MarkTasksTool, WriteMemoryTool
 

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/tests/test_core/test_architecture_assumptions.py

@@ -20,6 +20,43 @@ def test_canonical_message_is_harmony_primitive():
     assert Message is openai_harmony.Message
 
 
+# ── The composition surface is complete ──────────────────────────────────────────
+def test_every_state_class_is_exported():
+    """A node a consumer cannot import from ``aisolate.agent.states`` is a node
+    it cannot compose a graph with. ``TaskState`` was missing for exactly as
+    long as nothing checked."""
+    import importlib
+    import inspect
+    import pkgutil
+
+    import aisolate.agent.states as states_pkg
+
+    discovered = set()
+    for mod in pkgutil.iter_modules(states_pkg.__path__):
+        module = importlib.import_module(f"{states_pkg.__name__}.{mod.name}")
+        for name, obj in vars(module).items():
+            if (
+                inspect.isclass(obj)
+                and issubclass(obj, State)
+                and obj.__module__ == module.__name__
+                and not name.startswith("_")
+            ):
+                discovered.add(name)
+
+    missing = discovered - set(states_pkg.__all__)
+    assert not missing, f"states/__init__.py does not export: {sorted(missing)}"
+
+
+def test_graph_composition_parts_are_exported_from_core():
+    """``AgentGraph`` + the policy routers are the composition kit: a consumer
+    building its own workflow must not have to reach past the package."""
+    import aisolate.agent.core as core
+
+    for name in ("AgentGraph", "RoutingDecision", "policy"):
+        assert name in core.__all__
+        assert hasattr(core, name)
+
+
 # ── Memory is an append-only log ──────────────────────────────────────────────────
 def test_agent_context_has_no_destructive_history_replace():
     """``AgentContext`` exposes no whole-history replacement or direct

{aisolate_agent-0.3.1 → aisolate_agent-0.3.2}/src/aisolate/agent/tests/test_core/test_graph.py

@@ -104,6 +104,12 @@ class TestValidator:
         with pytest.raises(GraphValidationError, match="entry"):
             minimal_graph(entry="nowhere")
 
+    def test_unknown_cycle_entry_raises(self):
+        # Validated exactly like `entry`: a follow-up must not discover
+        # mid-run that its re-entry node does not exist.
+        with pytest.raises(GraphValidationError, match="cycle_entry"):
+            minimal_graph(cycle_entry="nowhere")
+
     def test_edge_targeting_unknown_node_raises(self):
         with pytest.raises(GraphValidationError, match="unknown"):
             minimal_graph(
@@ -344,6 +350,80 @@ class TestInstantiation:
         )
 
 
+# ── 4b. Declarations: cycle entry & workspace posture ────────────────────────
+
+
+class TaskNamedStub(State):
+    """A node registered under the reserved ``task`` name."""
+
+    phase = "task"
+
+
+class TestCycleEntry:
+    """Where a NEW cycle starts is declared, not inferred from a node name."""
+
+    def test_defaults_to_entry(self):
+        assert minimal_graph().cycle_entry == "start"
+
+    def test_explicit_value_is_kept(self):
+        assert minimal_graph(cycle_entry="end").cycle_entry == "end"
+
+    @pytest.mark.parametrize(
+        "kwargs",
+        [
+            {},
+            {"clarification": False, "review": False},
+            {"clarification": False, "review": False, "tasks": True},
+            {"role": "sub"},
+        ],
+    )
+    def test_shipped_shapes_re_enter_at_planning(self, kwargs):
+        # A follow-up skips intake: the standard graph enters at
+        # `clarification` but re-enters at `planning`. This was a literal in
+        # the restore path; every shipped shape must keep that behaviour.
+        graph = build_workflow(**kwargs)
+        assert graph.cycle_entry == "planning"
+
+
+class TestWorkspaceOps:
+    """Whether the run maintains task.md / memory.md is declared, and its
+    default reproduces the ``"task" in nodes`` proxy it replaces."""
+
+    def test_defaults_true_when_a_task_node_is_present(self):
+        graph = minimal_graph(
+            nodes={"start": SilentStub, "task": TaskNamedStub, "end": TerminalStub},
+        )
+        assert graph.workspace_ops is True
+
+    def test_defaults_false_without_a_task_node(self):
+        assert minimal_graph().workspace_ops is False
+
+    def test_can_be_declared_without_a_task_node(self):
+        # The case the proxy could not express: a graph that is handed its
+        # checklist instead of generating one still needs the ops that work it.
+        assert minimal_graph(workspace_ops=True).workspace_ops is True
+
+    def test_can_be_declined_with_a_task_node(self):
+        graph = minimal_graph(
+            nodes={"start": SilentStub, "task": TaskNamedStub, "end": TerminalStub},
+            workspace_ops=False,
+        )
+        assert graph.workspace_ops is False
+
+    @pytest.mark.parametrize(
+        "kwargs",
+        [
+            {},
+            {"clarification": False, "review": False},
+            {"clarification": False, "review": False, "tasks": True},
+            {"role": "sub"},
+        ],
+    )
+    def test_shipped_shapes_match_the_replaced_proxy(self, kwargs):
+        graph = build_workflow(**kwargs)
+        assert graph.workspace_ops == ("task" in graph.nodes)
+
+
 # ── 5. Extension: a custom graph runs end-to-end on the unmodified driver ────