boundflow 0.2.0__tar.gz → 0.3.0__tar.gz

{boundflow-0.2.0 → boundflow-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boundflow
-Version: 0.2.0
+Version: 0.3.0
 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,6 +18,8 @@ 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: opentelemetry-sdk; extra == "dev"
+Requires-Dist: opentelemetry-exporter-otlp; extra == "dev"
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.3; extra == "langchain"
 Provides-Extra: otel

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/__init__.py

@@ -5,10 +5,15 @@ from .control_plane import (
     ControlPlaneClient,
     ApprovalAuditRecord,
     ApprovalDecision,
+    InputAuditRecord,
+    InputDecision,
     PolicyActionRecord,
     WorkflowPolicyAction,
     AgentPolicyActionRecord,
+    InvokeMode,
     LifecycleState,
+    PendingApproval,
+    PendingInput,
     RequestInfo,
     Run,
     RunOutcome,
@@ -32,7 +37,7 @@ from .errors import (
     UnauthenticatedError,
     UnavailableError,
 )
-from .llm import MockLlmClient, MockContext, Turn, turn, submit
+from .llm import AgentCallTimeout, MockLlmClient, MockContext, Turn, turn, submit
 from .trace import (
     AgentRunTrace,
     JsonlFileTraceSink,
@@ -62,8 +67,10 @@ from .worker import (
     AgentDefinition,
     ApprovalRequest,
     AwaitApproval,
+    AwaitInput,
     BoundFlowWorker,
     Complete,
+    InputRequest,
     Next,
     OperationContext,
     OperationResult,
@@ -75,11 +82,11 @@ __all__ = [
     "AnthropicLlmClient",
     "ControlPlaneClient", "LifecycleState", "RunStatus", "RunOutcome", "Run", "RequestInfo",
     "Tenant", "TenantGroup", "Workflow",
-    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "ApprovalAuditRecord", "ApprovalDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "MockLlmClient", "MockContext", "Turn",
+    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "PendingApproval", "PendingInput", "InvokeMode", "ApprovalAuditRecord", "ApprovalDecision", "InputAuditRecord", "InputDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "AgentCallTimeout", "MockLlmClient", "MockContext", "Turn",
     "turn", "submit", "AgentMetric", "AgentRule", "Cooldown", "Op", "Pause",
     "RuntimePolicy", "SetMaxCostUsd", "SetMaxLlmCalls", "SetMaxTokensPerCall",
     "SetModel", "SetVersion", "ToolCallLimit", "WorkflowMetric", "WorkflowRule",
-    "AgentDefinition", "ApprovalRequest", "AwaitApproval", "BoundFlowWorker",
+    "AgentDefinition", "ApprovalRequest", "AwaitApproval", "AwaitInput", "InputRequest", "BoundFlowWorker",
     "Complete", "Next", "OperationContext", "OperationResult", "Tool", "tool",
     "AgentRunTrace", "OperationTrace", "Span", "TraceSink", "LoggingTraceSink",
     "JsonlFileTraceSink", "OTelTraceSink",

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/_transport.py

@@ -50,11 +50,16 @@ def new_approval_id() -> str:
     return str(uuid.uuid4())
 
 
+def new_input_id() -> str:
+    return str(uuid.uuid4())
+
+
 def metrics_to_proto(snapshot: dict) -> op_pb.AgentInvocationMetrics:
     m = op_pb.AgentInvocationMetrics(
         cost_usd=snapshot.get("cost_usd", 0.0),
         llm_calls=snapshot.get("llm_calls", 0),
         tokens_used=snapshot.get("tokens_used", 0),
+        latency_seconds=snapshot.get("latency_seconds", 0.0),
         ran_at=snapshot.get("ran_at", 0),
     )
     for tool, count in (snapshot.get("calls_per_tool") or {}).items():
@@ -89,6 +94,7 @@ def _runtime_policy_to_proto(p) -> ap_pb.AgentRuntimePolicy:
         max_llm_calls=p.max_llm_calls,
         max_cost_usd=p.max_cost_usd,
         max_tokens_per_call=p.max_tokens_per_call,
+        max_call_seconds=p.max_call_seconds,
         tool_call_limits=[ap_pb.ToolCallLimit(tool=l.tool, max_calls=l.max_calls) for l in p.tool_call_limits],
     )
 

{boundflow-0.2.0 → boundflow-0.3.0}/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 success
+from boundflow.cli._output import output, success
 from boundflow.policies import AgentRule, RuntimePolicy, ToolCallLimit, WorkflowRule
 
 app = typer.Typer(help="Manage agent and workflow policies.")
@@ -65,6 +65,16 @@ def runtime_set(
     success(f"Runtime policy set on {workflow_id} / {agent_name}.")
 
 
+@app.command("get-runtime")
+def runtime_get(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    agent_name: str = typer.Argument(..., help="Agent name"),
+):
+    """Show the armed runtime (hard cap) policy for an agent (empty if none is set)."""
+    policy = cp_call(lambda cp: cp.get_agent_runtime_policy(workflow_id, agent_name))
+    output(policy or {})
+
+
 @lifecycle_app.command("set-agent")
 def lifecycle_set_agent(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),
@@ -98,3 +108,22 @@ def lifecycle_set_workflow(
     wf_rules = [WorkflowRule.model_validate(r) for r in raw]
     cp_call(lambda cp: cp.set_workflow_lifecycle_policy(workflow_id, wf_rules))
     success(f"Workflow lifecycle policy set on {workflow_id}.")
+
+
+@lifecycle_app.command("get-agent")
+def lifecycle_get_agent(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    agent_name: str = typer.Argument(..., help="Agent name"),
+):
+    """Show the armed lifecycle rules for an agent (empty if none is set)."""
+    policy = cp_call(lambda cp: cp.get_agent_lifecycle_policy(workflow_id, agent_name))
+    output(policy or {})
+
+
+@lifecycle_app.command("get-workflow")
+def lifecycle_get_workflow(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """Show the armed lifecycle rules for a workflow (empty if none is set)."""
+    rules = cp_call(lambda cp: cp.get_workflow_lifecycle_policy(workflow_id))
+    output([r.model_dump(mode="json") for r in rules])

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/cli/commands/workflows.py

@@ -1,12 +1,13 @@
 """boundflow workflow — workflow lifecycle commands."""
 
+import json
 from typing import Optional
 
 import typer
 
 from boundflow.cli._client import cp_call
 from boundflow.cli._output import output, success
-from boundflow.control_plane import WorkflowConfig
+from boundflow.control_plane import InvokeMode, WorkflowConfig
 
 app = typer.Typer(help="Manage workflows.")
 
@@ -19,6 +20,12 @@ def create(
     timeout: int = typer.Option(60, "--timeout", help="Invoke timeout in seconds"),
     repeat: int = typer.Option(0, "--repeat", help="Repeat every N seconds (0 = no repeat)"),
     no_triggerable: bool = typer.Option(False, "--no-triggerable", help="Disable manual triggering"),
+    invoke_mode: InvokeMode = typer.Option(
+        InvokeMode.COALESCE, "--invoke-mode",
+        help="How piled-up invokes are handled: coalesce (latest-wins) or queue (run each, FIFO)"),
+    max_queue_depth: int = typer.Option(
+        0, "--max-queue-depth",
+        help="Queue-mode backlog cap; invokes past it are rejected (0 = server default)"),
 ):
     """Create a new workflow."""
     config = WorkflowConfig(
@@ -26,6 +33,8 @@ def create(
         invoke_timeout_seconds=timeout,
         repeat_every_seconds=repeat,
         triggerable=not no_triggerable,
+        invoke_mode=invoke_mode,
+        max_queue_depth=max_queue_depth,
     )
     result = cp_call(lambda cp: cp.create_workflow(workflow_type, tenant_id, config=config))
     output(result)
@@ -116,6 +125,23 @@ def reject(
     success(f"Approval {approval_id} rejected.")
 
 
+@app.command("submit-input")
+def submit_input(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    input_id: str = typer.Argument(..., help="Input ID (from the input request)"),
+    answer: str = typer.Option(..., "--answer", help="Answer as a JSON object, e.g. '{\"choice\": \"refund\"}'"),
+    actor: str = typer.Option("", "--actor", help="Who supplied the answer (e.g. email or user ID)"),
+):
+    """Answer a pending workflow input gate."""
+    try:
+        parsed = json.loads(answer)
+    except json.JSONDecodeError as e:
+        typer.echo(f"Error: --answer must be valid JSON: {e}", err=True)
+        raise typer.Exit(1)
+    cp_call(lambda cp: cp.submit_input(workflow_id, input_id, parsed, actor=actor))
+    success(f"Input {input_id} submitted.")
+
+
 @app.command("delete")
 def delete(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/control_plane.py

@@ -12,6 +12,7 @@ from datetime import datetime
 from enum import Enum
 
 import grpc
+from google.protobuf.json_format import MessageToDict
 from google.protobuf.struct_pb2 import Struct
 
 from boundflow.v1 import agent_policy_pb2 as ap
@@ -43,12 +44,22 @@ class Tenant:
     tenant_group_id: str
 
 
+class InvokeMode(str, Enum):
+    """How piled-up invokes are handled for a workflow (WorkflowConfig.invoke_mode)."""
+    COALESCE = "coalesce"  # latest-wins: a newer invoke supersedes older pending ones
+    QUEUE = "queue"        # fan-in: every invoke runs, drained oldest-first (FIFO)
+
+
 @dataclass
 class WorkflowConfig:
     version: int = 0
     invoke_timeout_seconds: int = 60
     repeat_every_seconds: int = 0
     triggerable: bool = True
+    # max_queue_depth (0 = server default) bounds the queue-mode backlog; ignored in
+    # coalesce mode.
+    invoke_mode: InvokeMode = InvokeMode.COALESCE
+    max_queue_depth: int = 0
 
 
 @dataclass
@@ -66,6 +77,7 @@ class LifecycleState(str, Enum):
     BLOCKED = "blocked"
     INVOKING = "invoking"
     AWAITING_APPROVAL = "awaiting_approval"
+    AWAITING_INPUT = "awaiting_input"
     DELETING = "deleting"
     DELETED = "deleted"
     INTERRUPTED = "interrupted"
@@ -109,6 +121,13 @@ class ApprovalDecision(str, Enum):
     TIMED_OUT = "timed_out"
 
 
+class InputDecision(str, Enum):
+    """How an input gate was resolved (InputAuditRecord.decision)."""
+    UNSPECIFIED = "unspecified"
+    ANSWERED = "answered"
+    TIMED_OUT = "timed_out"
+
+
 class WorkflowPolicyAction(str, Enum):
     """The action a workflow-lifecycle rule took (PolicyActionRecord.action)."""
     UNSPECIFIED = "unspecified"
@@ -117,10 +136,39 @@ class WorkflowPolicyAction(str, Enum):
     PAUSE = "pause"
 
 
+@dataclass
+class PendingApproval:
+    """The currently open approval gate for a workflow (WorkflowInfo.pending_approval,
+    populated only while lifecycle_state is AWAITING_APPROVAL). approval_id is what
+    approve_workflow/reject_workflow expect — this is how an external caller (e.g. a
+    page reload with no in-process on_approval_requested state) discovers it."""
+    approval_id: str
+    justification: str
+    metadata: dict
+    opened_at: datetime | None
+    timeout_at: datetime | None
+
+
+@dataclass
+class PendingInput:
+    """The currently open input gate for a workflow (WorkflowInfo.pending_input,
+    populated only while lifecycle_state is AWAITING_INPUT). input_id is what
+    submit_input expects — this is how an external caller (e.g. a page reload with
+    no in-process on_input_requested state) discovers it."""
+    input_id: str
+    prompt: str
+    metadata: dict
+    opened_at: datetime | None
+    timeout_at: datetime | None
+
+
 @dataclass
 class WorkflowInfo:
     """A read-only view of a workflow — its current version, lifecycle state, and
-    workflow state. Returned by `get_workflow` (one) and `list_workflows` (all)."""
+    workflow state. Returned by `get_workflow` (one) and `list_workflows` (all).
+    pending_approval/pending_input are only populated by `get_workflow` (None from
+    `list_workflows`, which returns a lighter view) and only while lifecycle_state
+    is AWAITING_APPROVAL / AWAITING_INPUT respectively."""
     id: str
     workflow_type: str
     tenant_id: str
@@ -128,6 +176,8 @@ class WorkflowInfo:
     workflow_state: WorkflowState
     version: int
     last_interrupted_request_id: str
+    pending_approval: PendingApproval | None = None
+    pending_input: PendingInput | None = None
 
 
 def _workflow_info(w) -> WorkflowInfo:
@@ -139,6 +189,30 @@ def _workflow_info(w) -> WorkflowInfo:
         workflow_state=_WF_STATE.get(w.workflow_state, WorkflowState.UNSPECIFIED),
         version=w.workflow_config.version,
         last_interrupted_request_id=w.last_interrupted_request_id,
+        pending_approval=_pending_approval(w) if w.HasField("pending_approval") else None,
+        pending_input=_pending_input(w) if w.HasField("pending_input") else None,
+    )
+
+
+def _pending_approval(w) -> PendingApproval:
+    p = w.pending_approval
+    return PendingApproval(
+        approval_id=p.approval_id,
+        justification=p.justification,
+        metadata=MessageToDict(p.metadata) if p.HasField("metadata") else {},
+        opened_at=_ts(p, "opened_at"),
+        timeout_at=_ts(p, "timeout_at"),
+    )
+
+
+def _pending_input(w) -> PendingInput:
+    p = w.pending_input
+    return PendingInput(
+        input_id=p.input_id,
+        prompt=p.prompt,
+        metadata=MessageToDict(p.metadata) if p.HasField("metadata") else {},
+        opened_at=_ts(p, "opened_at"),
+        timeout_at=_ts(p, "timeout_at"),
     )
 
 
@@ -162,7 +236,11 @@ class RequestInfo:
     """Full state of one run, from get_request_info(request_id). `status` is the run's
     lifecycle (`RunStatus`); `run_outcome` is the terminal `RunOutcome`, or None until
     the run is terminal. sequence_number orders a workflow's runs (monotonic per
-    workflow)."""
+    workflow). `result` is the run's published output (Complete(result=...)), or None
+    if the run hasn't completed or didn't publish one. invoke_context, timeout_seconds,
+    and agent_runtime_policies are what was actually resolved for this specific run —
+    useful when workflow/agent config has since changed and you want to know what was
+    true at the time this run happened."""
     request_id: str
     workflow_id: str
     request_type: str
@@ -172,6 +250,10 @@ class RequestInfo:
     sequence_number: int
     created_at: datetime | None
     completed_at: datetime | None
+    result: dict | None
+    invoke_context: dict | None
+    timeout_seconds: int
+    agent_runtime_policies: dict | None
 
 
 @dataclass
@@ -189,6 +271,23 @@ class ApprovalAuditRecord:
     occurred_at: datetime | None   # when the decision was recorded
 
 
+@dataclass
+class InputAuditRecord:
+    """One input decision from the audit log. Correlate with a run trace via
+    input_id (the trace's boundflow.input_id). answer is the submitted content
+    (unset on a timeout decision) — recorded here because it's the governance-
+    relevant content, same reasoning as auditing an approval decision."""
+    workflow_id: str
+    request_id: str
+    input_id: str
+    decision: InputDecision
+    opened_at: datetime | None
+    decided_at: datetime | None
+    actor: str                     # customer-supplied; empty for timeouts
+    occurred_at: datetime | None   # when the decision was recorded
+    answer: dict | None            # unset on a timeout decision
+
+
 @dataclass
 class PolicyActionRecord:
     """One workflow-lifecycle policy firing. Self-describing: the rule that fired
@@ -229,6 +328,10 @@ _APPROVAL_DECISION = {
     lc.APPROVAL_DECISION_REJECTED: ApprovalDecision.REJECTED,
     lc.APPROVAL_DECISION_TIMED_OUT: ApprovalDecision.TIMED_OUT,
 }
+_INPUT_DECISION = {
+    lc.INPUT_DECISION_ANSWERED: InputDecision.ANSWERED,
+    lc.INPUT_DECISION_TIMED_OUT: InputDecision.TIMED_OUT,
+}
 _WORKFLOW_METRIC = {
     lc.WORKFLOW_METRIC_NUM_FAILURES: "num_failures",
     lc.WORKFLOW_METRIC_COST: "cost",
@@ -275,6 +378,15 @@ def _approval_record(r) -> ApprovalAuditRecord:
         actor=r.actor, occurred_at=_ts(r, "occurred_at"))
 
 
+def _input_record(r) -> InputAuditRecord:
+    return InputAuditRecord(
+        workflow_id=r.workflow_id, request_id=r.request_id, input_id=r.input_id,
+        decision=_INPUT_DECISION.get(r.decision, InputDecision.UNSPECIFIED),
+        opened_at=_ts(r, "opened_at"), decided_at=_ts(r, "decided_at"),
+        actor=r.actor, occurred_at=_ts(r, "occurred_at"),
+        answer=MessageToDict(r.answer) if r.HasField("answer") else None)
+
+
 def _workflow_policy_record(r) -> PolicyActionRecord:
     act = r.rule.action
     return PolicyActionRecord(
@@ -324,6 +436,7 @@ _LIFECYCLE = {
     "blocked": LifecycleState.BLOCKED,
     "invoking": LifecycleState.INVOKING,
     "awaiting_approval": LifecycleState.AWAITING_APPROVAL,
+    "awaiting_input": LifecycleState.AWAITING_INPUT,
     "deleting": LifecycleState.DELETING,
     "deleted": LifecycleState.DELETED,
     "interrupted": LifecycleState.INTERRUPTED,
@@ -344,6 +457,7 @@ _WF_METRIC = {
     WorkflowMetric.APPROVAL_REJECTIONS: lc.WORKFLOW_METRIC_APPROVAL_REJECTIONS,
     WorkflowMetric.TOOL_FAILURE_RATE: lc.WORKFLOW_METRIC_TOOL_FAILURE_RATE,
 }
+_WF_METRIC_REV = {v: k for k, v in _WF_METRIC.items()}
 
 
 def _struct(d: dict) -> Struct:
@@ -479,12 +593,17 @@ class ControlPlaneClient:
                 invoke_timeout_seconds=cfg.invoke_timeout_seconds,
                 repeat_every_seconds=cfg.repeat_every_seconds,
                 triggerable=cfg.triggerable,
+                invoke_mode=(ri.INVOKE_MODE_QUEUE if cfg.invoke_mode == InvokeMode.QUEUE
+                             else ri.INVOKE_MODE_COALESCE),
+                max_queue_depth=cfg.max_queue_depth,
             ),
         ), metadata=self._metadata)
         inst = resp.workflow
         wc = inst.workflow_config
         return Workflow(inst.id, inst.tenant_id, WorkflowConfig(
-            wc.version, wc.invoke_timeout_seconds, wc.repeat_every_seconds, wc.triggerable))
+            wc.version, wc.invoke_timeout_seconds, wc.repeat_every_seconds, wc.triggerable,
+            InvokeMode.QUEUE if wc.invoke_mode == ri.INVOKE_MODE_QUEUE else InvokeMode.COALESCE,
+            wc.max_queue_depth))
 
     async def activate_workflow(self, workflow_id: str) -> None:
         await self._lc.ActivateWorkflow(
@@ -499,12 +618,18 @@ class ControlPlaneClient:
             lc.ResolveInterruptedWorkflowRequest(workflow_id=workflow_id, request_id=request_id),
             metadata=self._metadata)
 
-    async def invoke_workflow(self, workflow_id: str, *, operation_timeout_seconds: int = 0) -> str:
+    async def invoke_workflow(self, workflow_id: str, *, operation_timeout_seconds: int = 0,
+                              context: dict | None = None) -> str:
         """Trigger a run; returns the request_id — the run/trace id you can use to
-        find this invocation's trace later."""
+        find this invocation's trace later.
+
+        `context` is optional per-run input; operations read and write it via
+        `ctx.context` (the caller's own data, kept apart from the runtime's keys in the
+        raw job context). Keep it small (input/coordination data, not a datastore)."""
         resp = await self._lc.InvokeWorkflow(lc.InvokeWorkflowRequest(
             workflow_id=workflow_id,
             runtime_overrides=lc.RuntimeOverrides(operation_timeout_seconds=operation_timeout_seconds),
+            initial_context=_struct(context) if context else None,
         ), metadata=self._metadata)
         return resp.request_id
 
@@ -554,6 +679,10 @@ class ControlPlaneClient:
             sequence_number=r.version,
             created_at=_ts(r, "created_at"),
             completed_at=_ts(r, "completed_at"),
+            result=MessageToDict(r.result) if r.HasField("result") else None,
+            invoke_context=MessageToDict(r.invoke_context) if r.HasField("invoke_context") else None,
+            timeout_seconds=r.operation_timeout_seconds,
+            agent_runtime_policies=MessageToDict(r.agent_runtime_policies) if r.HasField("agent_runtime_policies") else None,
         )
 
     async def approve_workflow(self, workflow_id: str, approval_id: str, actor: str = "") -> None:
@@ -582,6 +711,21 @@ class ControlPlaneClient:
             lc.GetApprovalAuditByIdRequest(approval_id=approval_id), metadata=self._metadata)
         return _approval_record(resp.record) if resp.HasField("record") else None
 
+    async def submit_input(self, workflow_id: str, input_id: str, answer: dict, actor: str = "") -> None:
+        """Answer a parked input gate. `actor` identifies who supplied the answer
+        (e.g. an email or user id); it's recorded in the input audit log (auth is
+        tenant-scoped, so the customer's gate is the source of actor identity)."""
+        await self._lc.SubmitInput(
+            lc.SubmitInputRequest(workflow_id=workflow_id, input_id=input_id,
+                                  answer=_struct(answer), actor=actor),
+            metadata=self._metadata)
+
+    async def get_input_audit(self, workflow_id: str) -> list[InputAuditRecord]:
+        """A workflow's input decisions (newest first)."""
+        resp = await self._lc.GetInputAudit(
+            lc.GetInputAuditRequest(workflow_id=workflow_id), metadata=self._metadata)
+        return [_input_record(r) for r in resp.records]
+
     async def get_workflow_policy_audit(self, workflow_id: str) -> list[PolicyActionRecord]:
         """A workflow's workflow-lifecycle policy firings (newest first)."""
         resp = await self._lc.GetWorkflowPolicyAudit(
@@ -599,7 +743,7 @@ class ControlPlaneClient:
     async def get_audit_log(self, workflow_id: str = ""):
         """The unified, time-ordered audit log (newest first). workflow_id is optional
         — omit for the whole tenant group. Each item is an ApprovalAuditRecord,
-        PolicyActionRecord, or AgentPolicyActionRecord."""
+        InputAuditRecord, PolicyActionRecord, or AgentPolicyActionRecord."""
         resp = await self._lc.GetAuditLog(
             lc.GetAuditLogRequest(workflow_id=workflow_id), metadata=self._metadata)
         out = []
@@ -611,6 +755,8 @@ class ControlPlaneClient:
                 out.append(_workflow_policy_record(e.workflow_policy))
             elif which == "agent_policy":
                 out.append(_agent_policy_record(e.agent_policy))
+            elif which == "input":
+                out.append(_input_record(e.input))
         return out
 
     async def delete_workflow(self, workflow_id: str) -> None:
@@ -648,6 +794,31 @@ class ControlPlaneClient:
                 rules=[_workflow_rule_proto(r) for r in rules]),
         ), metadata=self._metadata)
 
+    async def get_workflow_lifecycle_policy(self, workflow_id: str) -> list[WorkflowRule]:
+        """The armed workflow-lifecycle policy — the rules currently configured (the
+        inverse of set_workflow_lifecycle_policy). Empty list if none is set. Reflects the
+        current config, not a per-run snapshot; capture at run time for an audit receipt."""
+        resp = await self._lc.GetWorkflowLifecyclePolicy(
+            lc.GetWorkflowLifecyclePolicyRequest(workflow_id=workflow_id),
+            metadata=self._metadata)
+        return [_workflow_rule_from_proto(r) for r in resp.lifecycle_policy.rules]
+
+    async def get_agent_runtime_policy(self, workflow_id: str, agent_name: str) -> dict:
+        """The armed runtime policy (hard caps + model override) for one agent, as a dict.
+        Empty dict if none is set."""
+        resp = await self._lc.GetAgentRuntimePolicy(
+            lc.GetAgentRuntimePolicyRequest(workflow_id=workflow_id, agent_name=agent_name),
+            metadata=self._metadata)
+        return MessageToDict(resp.runtime_policy)
+
+    async def get_agent_lifecycle_policy(self, workflow_id: str, agent_name: str) -> dict:
+        """The armed lifecycle policy (adaptive rules) for one agent, as a dict. Empty dict
+        if none is set."""
+        resp = await self._lc.GetAgentLifecyclePolicy(
+            lc.GetAgentLifecyclePolicyRequest(workflow_id=workflow_id, agent_name=agent_name),
+            metadata=self._metadata)
+        return MessageToDict(resp.lifecycle_policy)
+
 
 def _workflow_rule_proto(rule: WorkflowRule) -> lc.WorkflowLifecyclePolicyRule:
     action = rule.action
@@ -671,3 +842,21 @@ def _workflow_rule_proto(rule: WorkflowRule) -> lc.WorkflowLifecyclePolicyRule:
         tool_name=rule.tool or "",
         action=act,
     )
+
+
+def _workflow_rule_from_proto(r: lc.WorkflowLifecyclePolicyRule) -> WorkflowRule:
+    """Inverse of _workflow_rule_proto: proto rule → WorkflowRule. The rule's window
+    lives on the action in the SDK model (Pause/Cooldown), so it's folded back in."""
+    t = r.action.type
+    if t == lc.WORKFLOW_POLICY_ACTION_COOLDOWN:
+        action = Cooldown(window=r.window, seconds=r.action.cooldown_seconds)
+    elif t == lc.WORKFLOW_POLICY_ACTION_SET_VERSION:
+        action = SetVersion(target=r.action.target_version)
+    else:
+        action = Pause(window=r.window)
+    return WorkflowRule(
+        metric=_WF_METRIC_REV[r.metric],
+        threshold=r.threshold,
+        action=action,
+        tool=r.tool_name or None,
+    )

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/lifecycle.py

@@ -47,6 +47,7 @@ def load_runtime_policy(node: dict | None) -> RuntimePolicy:
         max_llm_calls=node.get("max_llm_calls", 0),
         max_cost_usd=node.get("max_cost_usd", 0),
         max_tokens_per_call=node.get("max_tokens_per_call", 0),
+        max_call_seconds=node.get("max_call_seconds", 0),
         tool_call_limits=limits,
         model=node.get("model"),
     )

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/llm.py

@@ -7,6 +7,7 @@ port of BoundFlow.SDK Orchestrator.RunAsync.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from dataclasses import dataclass, field
 from typing import Any, Callable, Protocol
@@ -130,6 +131,12 @@ class LlmClient(Protocol):
     async def complete(self, request: LlmRequest) -> LlmResponse: ...
 
 
+class AgentCallTimeout(Exception):
+    """Raised when an LLM call exceeds RuntimePolicy.max_call_seconds. A customer-
+    domain failure like any other callback exception — the operation completes
+    (marked failed) and the workflow stays active."""
+
+
 # ── Scripted mock ─────────────────────────────────────────────────────────────
 
 
@@ -318,7 +325,14 @@ class Orchestrator:
             )
             log.debug("llm_call #%d forced_tool=%s", llm_calls + 1, req.forced_tool)
             _llm_start = now_ms()
-            resp = await self._client.complete(req)
+            try:
+                if cfg.policy.max_call_seconds > 0:
+                    resp = await asyncio.wait_for(self._client.complete(req), timeout=cfg.policy.max_call_seconds)
+                else:
+                    resp = await self._client.complete(req)
+            except asyncio.TimeoutError:
+                raise AgentCallTimeout(
+                    f"LLM call exceeded max_call_seconds={cfg.policy.max_call_seconds}") from None
             _llm_end = now_ms()
             _input_messages = _gen_ai_input_messages(req)  # snapshot as-sent, before appending the reply
 

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/policies.py

@@ -21,11 +21,14 @@ class ToolCallLimit(BaseModel):
 
 
 class RuntimePolicy(BaseModel):
-    """Hard caps enforced SDK-side during the agent loop."""
+    """Hard caps enforced SDK-side during the agent loop. Unlike the other caps —
+    which force a graceful submit_result on the next turn — max_call_seconds cancels
+    an in-flight LLM call outright, since a hung call never reaches a next turn."""
 
     max_llm_calls: int = 0
     max_cost_usd: float = 0
     max_tokens_per_call: int = 0
+    max_call_seconds: float = 0  # 0 = unset (no per-call timeout)
     tool_call_limits: list[ToolCallLimit] = Field(default_factory=list)
     model: str | None = None
 

{boundflow-0.2.0 → boundflow-0.3.0}/boundflow/trace.py

@@ -59,6 +59,7 @@ BF_OPERATION = "boundflow.operation"
 BF_OUTCOME = "boundflow.outcome"
 BF_FAILED = "boundflow.failed"
 BF_APPROVAL_ID = "boundflow.approval_id"
+BF_INPUT_ID = "boundflow.input_id"
 
 # ── Vocabulary values (not attribute keys) ────────────────────────────────────
 # GenAI operation-name values (the value of gen_ai.operation.name):
@@ -81,6 +82,7 @@ SPAN_KIND_TOOL = "tool"
 OUTCOME_COMPLETED = "completed"
 OUTCOME_NEXT = "next"
 OUTCOME_AWAIT_APPROVAL = "await_approval"
+OUTCOME_AWAIT_INPUT = "await_input"
 # Generic error attribute keys:
 ERROR = "error"
 ERROR_MESSAGE = "error.message"
@@ -141,6 +143,9 @@ class OperationTrace:
     # actor, and timing server-side via GetApprovalAudit. The decision itself is
     # NOT in the trace by design — it lives in the BoundFlow audit log.
     approval_id: str | None = None
+    # Set only when outcome == "await_input": the key to look up the answer, actor,
+    # and timing server-side via GetInputAudit. Same reasoning as approval_id.
+    input_id: str | None = None
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -239,6 +244,8 @@ class OTelTraceSink:
         op.set_attribute(BF_FAILED, trace.failed)
         if trace.approval_id:
             op.set_attribute(BF_APPROVAL_ID, trace.approval_id)
+        if trace.input_id:
+            op.set_attribute(BF_INPUT_ID, trace.input_id)
         op_ctx = self._ot.set_span_in_context(op)
         for run in trace.agent_runs:
             agent = self._tracer.start_span(f"agent {run.agent}", context=op_ctx,