boundflow 0.5.0__tar.gz → 0.7.0.dev7__tar.gz

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boundflow
-Version: 0.5.0
+Version: 0.7.0.dev7
 Summary: BoundFlow Python SDK — build governed fleets of agents against a self-hostable control plane.
 License-Expression: MIT
 Keywords: agents,llm,orchestration,control-plane,governance
@@ -18,10 +18,20 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: langchain-core>=0.3; extra == "dev"
 Requires-Dist: langchain-anthropic>=0.3; extra == "dev"
+Requires-Dist: langgraph>=0.2; extra == "dev"
+Requires-Dist: deepagents>=0.7; extra == "dev"
+Requires-Dist: starlette>=0.37; extra == "dev"
+Requires-Dist: uvicorn>=0.30; extra == "dev"
+Requires-Dist: python-multipart>=0.0.9; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
 Requires-Dist: opentelemetry-sdk; extra == "dev"
 Requires-Dist: opentelemetry-exporter-otlp; extra == "dev"
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: ui
+Requires-Dist: starlette>=0.37; extra == "ui"
+Requires-Dist: uvicorn>=0.30; extra == "ui"
+Requires-Dist: python-multipart>=0.0.9; extra == "ui"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-sdk; extra == "otel"
 Requires-Dist: opentelemetry-exporter-otlp; extra == "otel"

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/__init__.py

@@ -14,6 +14,7 @@ from .control_plane import (
     LifecycleState,
     PendingApproval,
     PendingInput,
+    Suspension,
     RequestInfo,
     Run,
     RunOutcome,
@@ -38,7 +39,11 @@ from .errors import (
     UnauthenticatedError,
     UnavailableError,
 )
-from .llm import AgentCallTimeout, MockLlmClient, MockContext, Turn, turn, submit
+from .governed import AgentFinalized, AgentGovernor, GovernedCall
+from .llm import (
+    AgentCallTimeout, AgentPolicyLimitExceeded, ToolFailureLimitExceeded,
+    MockLlmClient, MockContext, Turn, turn, submit,
+)
 from .trace import (
     AgentRunTrace,
     JsonlFileTraceSink,
@@ -61,6 +66,7 @@ from .policies import (
     SetModel,
     SetVersion,
     ToolCallLimit,
+    ToolFailureLimit,
     WorkflowMetric,
     WorkflowRule,
 )
@@ -70,7 +76,9 @@ from .worker import (
     AwaitApproval,
     AwaitInput,
     BoundFlowWorker,
+    Budget,
     Complete,
+    ENTRY_OPERATION,
     InputRequest,
     Next,
     OperationContext,
@@ -83,12 +91,16 @@ __all__ = [
     "AnthropicLlmClient",
     "ControlPlaneClient", "LifecycleState", "RunStatus", "RunOutcome", "Run", "RequestInfo",
     "Tenant", "TenantGroup", "Workflow",
-    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "WorkflowMetrics", "PendingApproval", "PendingInput", "InvokeMode", "ApprovalAuditRecord", "ApprovalDecision", "InputAuditRecord", "InputDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "AgentCallTimeout", "MockLlmClient", "MockContext", "Turn",
+    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "WorkflowMetrics", "PendingApproval", "PendingInput", "InvokeMode", "ApprovalAuditRecord", "ApprovalDecision", "InputAuditRecord", "InputDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "AgentCallTimeout", "AgentPolicyLimitExceeded", "AgentFinalized", "AgentGovernor", "GovernedCall",
+    "MockLlmClient", "MockContext", "Turn",
+    "turn", "submit", "AgentMetric", "AgentRule", "Cooldown",
+    "Op", "Pause",
+    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "WorkflowMetrics", "PendingApproval", "PendingInput", "Suspension", "InvokeMode", "ApprovalAuditRecord", "ApprovalDecision", "InputAuditRecord", "InputDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "AgentCallTimeout", "AgentPolicyLimitExceeded", "MockLlmClient", "MockContext", "Turn",
     "turn", "submit", "AgentMetric", "AgentRule", "Cooldown", "Op", "Pause",
     "RuntimePolicy", "SetMaxCostUsd", "SetMaxLlmCalls", "SetMaxTokensPerCall",
-    "SetModel", "SetVersion", "ToolCallLimit", "WorkflowMetric", "WorkflowRule",
+    "SetModel", "SetVersion", "ToolCallLimit", "ToolFailureLimit", "ToolFailureLimitExceeded", "WorkflowMetric", "WorkflowRule",
     "AgentDefinition", "ApprovalRequest", "AwaitApproval", "AwaitInput", "InputRequest", "BoundFlowWorker",
-    "Complete", "Next", "OperationContext", "OperationResult", "Tool", "tool",
+    "Budget", "Complete", "ENTRY_OPERATION", "Next", "OperationContext", "OperationResult", "Tool", "tool",
     "AgentRunTrace", "OperationTrace", "Span", "TraceSink", "LoggingTraceSink",
     "JsonlFileTraceSink", "OTelTraceSink",
     "BoundflowError", "NotFoundError", "AlreadyExistsError", "InvalidArgumentError",

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/_transport.py

@@ -25,7 +25,12 @@ from boundflow.v1 import worker_pb2 as wk_pb
 from boundflow.v1 import worker_pb2_grpc as wk_grpc
 
 # dispatch: given the launched operation proto, produce the result proto.
-Dispatch = Callable[[op_pb.AtomicOperation], Awaitable[op_pb.AtomicOperationResult]]
+# The second argument reports metrics mid-operation: an interim AtomicOperationResult
+# carrying nothing but agent_state_updates. See `_run_operation`.
+Dispatch = Callable[
+    [op_pb.AtomicOperation, Callable[[op_pb.AtomicOperationResult], Awaitable[None]]],
+    Awaitable[op_pb.AtomicOperationResult],
+]
 
 
 def _strip_scheme(addr: str) -> str:
@@ -175,17 +180,37 @@ class WorkerSession:
                     op_task = asyncio.create_task(self._run_operation(call, op, dispatch))
                 elif which == "cancel":
                     if op_task is not None and command.cancel.operation_id == op_id:
+                        reason = command.cancel.reason
                         op_task.cancel()
                         try:
                             await op_task
                         except asyncio.CancelledError:
-                            await self._write(call, self._update(op_id, op_pb.OPERATION_STATUS_CANCELLED))
+                            # Echo the reason back: the server records the run outcome from
+                            # what actually stopped it, not from what it asked for.
+                            await self._write(call, self._update(
+                                op_id, op_pb.OPERATION_STATUS_CANCELLED, cancel_reason=reason))
                     op_task, op_id = None, None
                     await self._write(call, self._ready())
 
     async def _run_operation(self, call, op: op_pb.AtomicOperation, dispatch: Dispatch) -> None:
+        async def report(interim: op_pb.AtomicOperationResult) -> None:
+            """Send metrics before the operation ends.
+
+            Without this an operation's spend only reaches the server when it finishes,
+            so a worker that dies mid-run takes its accounting with it. Sent on the same
+            stream, in order, so an interim report can't overtake the final result.
+
+            No ack, deliberately: a failed write kills the stream and the run is
+            interrupted, which bounds the damage to whatever landed after the last
+            successful report. Worth revisiting — see the note in `worker.py`.
+            """
+            await self._write(call, wk_pb.WorkerMessage(
+                session_id=self._session_id,
+                update=wk_pb.OperationUpdate(operation_id=op.id, result=interim),
+            ))
+
         try:
-            result = await dispatch(op)
+            result = await dispatch(op, report)
         except asyncio.CancelledError:
             raise  # surfaced to the main loop, which sends CANCELLED
         except Exception as ex:  # noqa: BLE001 — report a handler failure
@@ -209,11 +234,14 @@ class WorkerSession:
             ready=wk_pb.ReadyForWork(capabilities=self._capabilities),
         )
 
-    def _update(self, operation_id: str, status, message: str = "") -> wk_pb.WorkerMessage:
+    def _update(self, operation_id: str, status, message: str = "", cancel_reason=None) -> wk_pb.WorkerMessage:
+        result = op_pb.AtomicOperationResult(status=status, message=message)
+        if cancel_reason is not None:
+            result.cancel_reason = cancel_reason
         return wk_pb.WorkerMessage(
             session_id=self._session_id,
             update=wk_pb.OperationUpdate(
                 operation_id=operation_id,
-                result=op_pb.AtomicOperationResult(status=status, message=message),
+                result=result,
             ),
         )

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/__init__.py

@@ -2,8 +2,8 @@
 
 import typer
 
-from boundflow.cli._client import configure
-from boundflow.cli._output import set_json
+from boundflow.cli._client import configure, resolved
+from boundflow.cli.output import error, set_json
 from boundflow.cli.commands import audit, policies, pricing, tenants, workflows
 
 app = typer.Typer(
@@ -38,5 +38,20 @@ def root(
     configure(server, api_key)
 
 
+@app.command("ui")
+def ui(
+    port: int = typer.Option(8787, "--port", help="Port to serve on (localhost only)"),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Don't open a browser"),
+):
+    """Serve the local operator console: the fleet, its gates, and holds."""
+    from boundflow.ui import serve
+
+    server, api_key = resolved()
+    if not api_key:
+        error("no API key. Set BOUNDFLOW_API_KEY or pass --api-key.")
+        raise typer.Exit(1)
+    serve(server, api_key, port=port, open_browser=not no_browser)
+
+
 def main() -> None:
     app()

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/_client.py

@@ -5,7 +5,7 @@ import os
 
 import typer
 
-from boundflow.cli._output import error as report_error
+from boundflow.cli.output import error as report_error
 from boundflow.control_plane import ControlPlaneClient, DEFAULT_SERVER_ADDRESS
 
 _server: str = DEFAULT_SERVER_ADDRESS
@@ -41,3 +41,9 @@ def cp_call(fn):
     except Exception as exc:
         report_error(str(exc))
         raise typer.Exit(1)
+
+
+def resolved() -> tuple[str, str]:
+    """The server address and API key the root callback settled on, for commands that
+    manage their own connection rather than going through cp_call."""
+    return _server, _api_key

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/commands/audit.py

@@ -1,4 +1,4 @@
-"""boundflow audit — approval and policy audit log commands."""
+"""boundflow audit — approval, input and policy audit log commands."""
 
 from dataclasses import asdict
 from typing import Optional
@@ -6,9 +6,9 @@ from typing import Optional
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import output
+from boundflow.cli.output import output
 
-app = typer.Typer(help="View approval and policy audit records.")
+app = typer.Typer(help="View approval, input and policy audit records.")
 
 
 def _flatten(record) -> dict:
@@ -34,6 +34,15 @@ def approvals(
         output([_flatten(r) for r in results])
 
 
+@app.command("inputs")
+def inputs(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """List input-gate decisions for a workflow."""
+    results = cp_call(lambda cp: cp.get_input_audit(workflow_id))
+    output([_flatten(r) for r in results])
+
+
 @app.command("workflow")
 def workflow_policy(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/commands/policies.py

@@ -7,7 +7,7 @@ from typing import List, Optional
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import error, output, success
+from boundflow.cli.output import error, output, success
 from boundflow.policies import AgentRule, RuntimePolicy, ToolCallLimit, WorkflowRule
 
 app = typer.Typer(help="Manage agent and workflow policies.")
@@ -38,6 +38,22 @@ def _load_json(file: Optional[Path], inline: Optional[str]) -> list:
     raise typer.Exit(1)
 
 
+def _parse_custom(raw: Optional[str]) -> dict:
+    """--custom takes a JSON object. Anything else is a mistake worth stopping for: these
+    caps are never validated downstream, so a malformed one would just quietly not exist."""
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as e:
+        error(f"--custom must be valid JSON: {e}")
+        raise typer.Exit(1)
+    if not isinstance(parsed, dict):
+        error("--custom must be a JSON object.")
+        raise typer.Exit(1)
+    return parsed
+
+
 @app.command("runtime")
 def runtime_set(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),
@@ -47,6 +63,7 @@ def runtime_set(
     max_cost_usd: Optional[float] = typer.Option(None, "--max-cost-usd", help="Max cost in USD per run"),
     max_tokens_per_call: Optional[int] = typer.Option(None, "--max-tokens-per-call", help="Max tokens per LLM call"),
     tool_limit: List[str] = typer.Option([], "--tool-limit", help="Per-tool call limit as TOOL:MAX (repeatable)"),
+    custom: Optional[str] = typer.Option(None, "--custom", help="JSON object of caps BoundFlow stores but does not enforce"),
     file: Optional[Path] = typer.Option(None, "--file", help="JSON file with a RuntimePolicy object (overrides all flags)"),
 ):
     """Set the runtime (hard cap) policy for an agent."""
@@ -60,11 +77,32 @@ def runtime_set(
             max_cost_usd=max_cost_usd or 0.0,
             max_tokens_per_call=max_tokens_per_call or 0,
             tool_call_limits=limits,
+            custom=_parse_custom(custom),
         )
     cp_call(lambda cp: cp.set_agent_runtime_policy(workflow_id, agent_name, policy))
     success(f"Runtime policy set on {workflow_id} / {agent_name}.")
 
 
+@app.command("agents")
+def list_agents(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """List a workflow's agents and their armed policies.
+
+    Every other agent command needs a name; this is where the names come from.
+    """
+    agents = cp_call(lambda cp: cp.list_agents(workflow_id))
+    output([
+        {
+            "agent_name": a.agent_name,
+            "runtime_policy": a.runtime_policy or {},
+            "lifecycle_policy": a.lifecycle_policy or {},
+            "updated_at": a.updated_at,
+        }
+        for a in agents
+    ])
+
+
 @app.command("get-runtime")
 def runtime_get(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/commands/pricing.py

@@ -3,7 +3,7 @@
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import output, success
+from boundflow.cli.output import output, success
 
 app = typer.Typer(help="Manage model pricing rates.")
 

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/commands/tenants.py

@@ -3,7 +3,7 @@
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import output, success
+from boundflow.cli.output import output, success
 
 app = typer.Typer(help="Manage tenant groups and tenants.")
 

{boundflow-0.5.0 → boundflow-0.7.0.dev7}/boundflow/cli/commands/workflows.py

@@ -1,12 +1,12 @@
 """boundflow workflow — workflow lifecycle commands."""
 
 import json
-from typing import Optional
+from typing import List, Optional
 
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import error, output, success
+from boundflow.cli.output import error, output, success
 from boundflow.control_plane import InvokeMode, WorkflowConfig
 
 app = typer.Typer(help="Manage workflows.")
@@ -129,6 +129,45 @@ def request(
     output(result)
 
 
+@app.command("suspend")
+def suspend(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    reason: str = typer.Option("", "--reason", help="Why it was held; shown on the workflow"),
+    stop_current_run: bool = typer.Option(False, "--stop-current-run", help="Stop the run in flight instead of letting it finish"),
+    suspension_id: str = typer.Option("", "--suspension-id", help="Retarget this hold instead of starting a new one"),
+):
+    """Hold a workflow. Prints the suspension_id that 'resume' requires."""
+    sid = cp_call(lambda cp: cp.suspend_workflow(
+        workflow_id, reason=reason, stop_current_run=stop_current_run,
+        suspension_id=suspension_id))
+    output({"suspension_id": sid})
+
+
+@app.command("resume")
+def resume(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    suspension_id: str = typer.Argument(..., help="From 'suspend', or workflow.suspension.suspension_id"),
+):
+    """Release a hold. Only valid once the suspension has finished draining."""
+    cp_call(lambda cp: cp.resume_workflow(workflow_id, suspension_id))
+    success(f"Workflow {workflow_id} resumed.")
+
+
+@app.command("abandon-queued")
+def abandon_queued(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    request_id: List[str] = typer.Option([], "--request-id", help="A queued run to abandon (repeatable)"),
+    all: bool = typer.Option(False, "--all", help="Abandon every queued run"),
+):
+    """Drop queued runs. Irreversible; a run already in progress is left alone."""
+    if all == bool(request_id):
+        error("provide --request-id (repeatable) or --all, not both.")
+        raise typer.Exit(1)
+    abandoned = cp_call(lambda cp: cp.abandon_queued_requests(
+        workflow_id, request_ids=list(request_id), all=all))
+    output({"abandoned": abandoned})
+
+
 @app.command("resolve")
 def resolve(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),
@@ -144,9 +183,10 @@ def approve(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),
     approval_id: str = typer.Argument(..., help="Approval ID (from the approval request)"),
     actor: str = typer.Option("", "--actor", help="Approver identity (e.g. email or user ID)"),
+    reason: str = typer.Option("", "--reason", help="Why it was approved; recorded on the audit event"),
 ):
     """Approve a pending workflow approval gate."""
-    cp_call(lambda cp: cp.approve_workflow(workflow_id, approval_id, actor=actor))
+    cp_call(lambda cp: cp.approve_workflow(workflow_id, approval_id, actor=actor, reason=reason))
     success(f"Approval {approval_id} approved.")
 
 
@@ -155,9 +195,10 @@ def reject(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),
     approval_id: str = typer.Argument(..., help="Approval ID (from the approval request)"),
     actor: str = typer.Option("", "--actor", help="Rejecter identity (e.g. email or user ID)"),
+    reason: str = typer.Option("", "--reason", help="Why it was rejected; recorded on the audit event"),
 ):
     """Reject a pending workflow approval gate."""
-    cp_call(lambda cp: cp.reject_workflow(workflow_id, approval_id, actor=actor))
+    cp_call(lambda cp: cp.reject_workflow(workflow_id, approval_id, actor=actor, reason=reason))
     success(f"Approval {approval_id} rejected.")
 
 

boundflow-0.5.0/boundflow/cli/_output.py → boundflow-0.7.0.dev7/boundflow/cli/output.py

@@ -1,4 +1,12 @@
-"""Rich table rendering and --json output helpers."""
+"""Rendering for CLIs built on BoundFlow — tables, or JSON under --json.
+
+Public so tools wrapping the control plane render the same way. `output()` derives its
+columns from the data, so a field added to a BoundFlow object appears without anyone
+updating a list of things to print — which is the point: a renderer that picks fields by
+hand silently drops the ones nobody remembered.
+
+`set_json()` writes a module global, so a process running two CLIs shares the flag.
+"""
 
 import json
 from dataclasses import asdict, is_dataclass