steerable-agent-harness 0.2.0__tar.gz

steerable_agent_harness-0.2.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: steerable-agent-harness
+Version: 0.2.0
+Summary: Steerable harness helpers for Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
+
+# steerable-agent-harness
+
+Python harness primitives and policy helpers for Steerable.

steerable_agent_harness-0.2.0/README.md

@@ -0,0 +1,3 @@
+# steerable-agent-harness
+
+Python harness primitives and policy helpers for Steerable.

steerable_agent_harness-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "steerable-agent-harness"
+version = "0.2.0"
+description = "Steerable harness helpers for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+# Pre-1.0 inter-package pin uses a `>=X,<1.0.0` range so release-please can
+# bump any single Steerable package without breaking installs of the others.
+# Lockstep across protocol↔harness is enforced separately by
+# scripts/check_lockstep_versions.py (CI gate). Tighten to `~=1.0` post-GA.
+dependencies = [
+  "pydantic>=2.10.0",
+  "steerable-agent-protocol>=0.1.0,<1.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+steerable-agent-protocol = { workspace = true }

steerable_agent_harness-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steerable_agent_harness-0.2.0/src/steerable_agent_harness/__init__.py

@@ -0,0 +1,21 @@
+from .policy import ToolMode, PolicyDecision, decide_tool_mode
+from .budget import BudgetState, BudgetLimit, consume_budget
+from .retry import RetryPolicy, next_retry_delay_ms
+from .completion import is_terminal_result
+from .tracing import TraceSpan
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "ToolMode",
+    "PolicyDecision",
+    "decide_tool_mode",
+    "BudgetState",
+    "BudgetLimit",
+    "consume_budget",
+    "RetryPolicy",
+    "next_retry_delay_ms",
+    "is_terminal_result",
+    "TraceSpan",
+]

steerable_agent_harness-0.2.0/src/steerable_agent_harness/budget.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class BudgetLimit:
+    max_tokens: int
+    max_steps: int
+    max_tool_calls: int
+
+
+@dataclass(slots=True)
+class BudgetState:
+    tokens_used: int = 0
+    steps_used: int = 0
+    tool_calls_used: int = 0
+
+
+def consume_budget(
+    state: BudgetState,
+    limits: BudgetLimit,
+    *,
+    tokens: int = 0,
+    step: bool = False,
+    tool_call: bool = False,
+) -> tuple[BudgetState, bool]:
+    next_state = BudgetState(
+        tokens_used=state.tokens_used + max(tokens, 0),
+        steps_used=state.steps_used + (1 if step else 0),
+        tool_calls_used=state.tool_calls_used + (1 if tool_call else 0),
+    )
+    exhausted = (
+        next_state.tokens_used > limits.max_tokens
+        or next_state.steps_used > limits.max_steps
+        or next_state.tool_calls_used > limits.max_tool_calls
+    )
+    return next_state, exhausted

steerable_agent_harness-0.2.0/src/steerable_agent_harness/completion.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_terminal_result(result: dict[str, Any] | None) -> bool:
+    if not result:
+        return False
+    if result.get("terminal") is True:
+        return True
+    if result.get("success") is False and result.get("needsFollowup") is not True:
+        return True
+    return False

steerable_agent_harness-0.2.0/src/steerable_agent_harness/generated.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from typing import Any
+from pydantic import BaseModel
+
+class ChatAgent(BaseModel):
+    id: str
+    slug: str | None = None
+    name: str
+    icon: str | None = None
+    color: str | None = None
+    description: str | None = None
+    rolePrompt: str | None = None
+    forbiddenPrompt: str | None = None
+    skillIds: list[Any] | None = None
+    allowExternalSkills: bool | None = None
+    isBuiltin: bool | None = None
+    isArchived: bool | None = None
+    sortOrder: int | None = None
+    createdAt: str
+    updatedAt: str
+
+class ChatMessage(BaseModel):
+    id: str
+    chatId: str | None = None
+    role: str
+    content: str
+    agentId: str | None = None
+    toolCalls: list[Any] | None = None
+    toolResult: Any | None = None
+    createdAt: str
+    updatedAt: str | None = None
+
+class SSEEvent(BaseModel):
+    type: str
+    event: str | None = None
+    content: str | None = None
+    hint: str | None = None
+    message: str | None = None
+    code: str | None = None
+    orchestrationGroupId: str | None = None
+    taskId: str | None = None
+    messageId: str | None = None
+    payload: dict[str, Any] | None = None
+
+class AgentSession(BaseModel):
+    id: str | None = None
+    sessionId: str
+    userId: str
+    projectId: Any | None = None
+    chatId: str
+    currentStage: str
+    nextStage: Any | None = None
+    scenario: str | None = None
+    stageData: Any | None = None
+    isActive: bool
+    createdAt: str
+    updatedAt: str
+
+class HarnessTrace(BaseModel):
+    traceId: str
+    userId: Any | None = None
+    chatId: Any | None = None
+    sessionId: Any | None = None
+    assistantMessageId: Any | None = None
+    status: str
+    durationMs: Any | None = None
+    hadError: bool
+    errorMessage: Any | None = None
+    eventCount: int
+    spanCount: int
+    totalTokens: Any | None = None
+    modelId: Any | None = None
+    startedAtMs: Any | None = None
+    createdAt: str
+    updatedAt: str
+
+class TraceEvent(BaseModel):
+    id: str | None = None
+    traceId: str
+    kind: str
+    name: str
+    sequence: int
+    timestampMs: int
+    durationMs: Any | None = None
+    status: Any | None = None
+    payload: Any | None = None
+    createdAt: str | None = None
+
+class TraceSpan(BaseModel):
+    spanId: str
+    traceId: Any | None = None
+    parentSpanId: Any | None = None
+    name: str
+    kind: str | None = None
+    startMs: int
+    endMs: Any | None = None
+    durationMs: Any | None = None
+    status: str
+    attrs: dict[str, Any] | None = None
+
+class CommandSafetyPattern(BaseModel):
+    id: str
+    label: str
+    description: str
+    pattern: str
+    category: str
+    severity: str
+    platform: str
+
+class SidecarError(BaseModel):
+    code: int
+    message: str
+    data: Any | None = None
+    kind: str | None = None
+
+class SidecarHealth(BaseModel):
+    status: str
+    version: str
+    protocolVersion: str | None = None
+    uptimeMs: int
+    pid: int | None = None
+    pythonVersion: str | None = None
+    platform: str | None = None
+    loadedProviders: list[Any] | None = None
+    loadedTools: int | None = None
+    activeTraces: int | None = None
+    checks: dict[str, Any] | None = None
+
+class SidecarNotification(BaseModel):
+    jsonrpc: str
+    method: str
+    params: Any | None = None
+
+class SidecarRequest(BaseModel):
+    jsonrpc: str
+    id: Any
+    method: str
+    params: Any | None = None
+
+class SidecarResponse(BaseModel):
+    jsonrpc: str
+    id: Any
+    result: Any | None = None
+    error: Any | None = None
+
+class ToolCall(BaseModel):
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+class ToolResult(BaseModel):
+    success: bool
+    terminal: bool | None = None
+    needsFollowup: bool | None = None
+    nextAction: str | None = None
+    message: str | None = None
+    error: str | None = None
+    data: dict[str, Any] | None = None

steerable_agent_harness-0.2.0/src/steerable_agent_harness/policy.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+ToolMode = Literal["read", "safe_write", "destructive", "other"]
+
+
+@dataclass(slots=True)
+class PolicyDecision:
+    allowed: bool
+    tool_mode: ToolMode
+    reason: str
+
+
+def decide_tool_mode(tool_name: str) -> ToolMode:
+    normalized = tool_name.lower()
+    if normalized.startswith(("get_", "list_", "read_")):
+        return "read"
+    if normalized.startswith(("create_", "update_", "set_", "write_", "apply_")):
+        return "safe_write"
+    if normalized.startswith(("delete_", "drop_", "remove_", "destroy_")):
+        return "destructive"
+    return "other"

steerable_agent_harness-0.2.0/src/steerable_agent_harness/retry.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import random
+
+
+@dataclass(slots=True)
+class RetryPolicy:
+    max_attempts: int = 3
+    base_delay_ms: int = 200
+    max_delay_ms: int = 5000
+    jitter: bool = True
+
+
+def next_retry_delay_ms(policy: RetryPolicy, attempt: int) -> int:
+    if attempt < 1:
+        attempt = 1
+    delay = min(policy.base_delay_ms * (2 ** (attempt - 1)), policy.max_delay_ms)
+    if policy.jitter:
+        delay = int(delay * random.uniform(0.8, 1.2))
+    return max(delay, 0)

steerable_agent_harness-0.2.0/src/steerable_agent_harness/tracing.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(slots=True)
+class TraceSpan:
+    span_id: str
+    name: str
+    start_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    end_at: str | None = None
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+    def finish(self) -> None:
+        if self.end_at is None:
+            self.end_at = datetime.now(timezone.utc).isoformat()

steerable_agent_harness-0.2.0/src/steerable_agent_harness.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: steerable-agent-harness
+Version: 0.2.0
+Summary: Steerable harness helpers for Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
+
+# steerable-agent-harness
+
+Python harness primitives and policy helpers for Steerable.

steerable_agent_harness-0.2.0/src/steerable_agent_harness.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+src/steerable_agent_harness/__init__.py
+src/steerable_agent_harness/budget.py
+src/steerable_agent_harness/completion.py
+src/steerable_agent_harness/generated.py
+src/steerable_agent_harness/policy.py
+src/steerable_agent_harness/retry.py
+src/steerable_agent_harness/tracing.py
+src/steerable_agent_harness.egg-info/PKG-INFO
+src/steerable_agent_harness.egg-info/SOURCES.txt
+src/steerable_agent_harness.egg-info/dependency_links.txt
+src/steerable_agent_harness.egg-info/requires.txt
+src/steerable_agent_harness.egg-info/top_level.txt
+tests/test_budget.py
+tests/test_completion.py
+tests/test_policy.py
+tests/test_retry.py
+tests/test_tracing.py

steerable_agent_harness-0.2.0/src/steerable_agent_harness.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

steerable_agent_harness-0.2.0/src/steerable_agent_harness.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pydantic>=2.10.0
+steerable-agent-protocol<1.0.0,>=0.1.0

steerable_agent_harness-0.2.0/src/steerable_agent_harness.egg-info/top_level.txt

@@ -0,0 +1 @@
+steerable_agent_harness

steerable_agent_harness-0.2.0/tests/test_budget.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from steerable_agent_harness import budget
+
+
+def _limits(**overrides) -> budget.BudgetLimit:
+    base = {"max_tokens": 1000, "max_steps": 10, "max_tool_calls": 5}
+    base.update(overrides)
+    return budget.BudgetLimit(**base)
+
+
+def test_budget_consume_returns_new_state() -> None:
+    state = budget.BudgetState()
+    next_state, exhausted = budget.consume_budget(
+        state,
+        _limits(),
+        tokens=200,
+        step=True,
+        tool_call=True,
+    )
+    assert next_state.tokens_used == 200
+    assert next_state.steps_used == 1
+    assert next_state.tool_calls_used == 1
+    assert exhausted is False
+    assert state.tokens_used == 0  # original state untouched
+
+
+def test_budget_token_overflow_exhausted() -> None:
+    state = budget.BudgetState(tokens_used=900)
+    _, exhausted = budget.consume_budget(state, _limits(), tokens=200)
+    assert exhausted is True
+
+
+def test_budget_step_overflow_exhausted() -> None:
+    state = budget.BudgetState(steps_used=10)
+    _, exhausted = budget.consume_budget(state, _limits(), step=True)
+    assert exhausted is True
+
+
+def test_budget_tool_call_overflow_exhausted() -> None:
+    state = budget.BudgetState(tool_calls_used=5)
+    _, exhausted = budget.consume_budget(state, _limits(), tool_call=True)
+    assert exhausted is True
+
+
+def test_negative_tokens_clamp_to_zero() -> None:
+    state = budget.BudgetState(tokens_used=10)
+    next_state, exhausted = budget.consume_budget(state, _limits(), tokens=-50)
+    assert next_state.tokens_used == 10
+    assert exhausted is False
+
+
+def test_idle_call_does_not_increment() -> None:
+    state = budget.BudgetState(tokens_used=5, steps_used=1, tool_calls_used=1)
+    next_state, exhausted = budget.consume_budget(state, _limits())
+    assert next_state == state
+    assert exhausted is False
+
+
+def test_budget_golden(assert_golden) -> None:
+    state = budget.BudgetState()
+    timeline = []
+    for i in range(3):
+        state, exhausted = budget.consume_budget(
+            state,
+            _limits(max_tokens=400),
+            tokens=150,
+            step=True,
+            tool_call=(i % 2 == 0),
+        )
+        timeline.append(
+            {
+                "step": i + 1,
+                "tokens_used": state.tokens_used,
+                "steps_used": state.steps_used,
+                "tool_calls_used": state.tool_calls_used,
+                "exhausted": exhausted,
+            }
+        )
+    assert_golden("budget_timeline", timeline)

steerable_agent_harness-0.2.0/tests/test_completion.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from steerable_agent_harness import completion
+
+
+def test_terminal_when_explicit_flag() -> None:
+    assert completion.is_terminal_result({"terminal": True}) is True
+
+
+def test_terminal_when_failure_without_followup() -> None:
+    assert completion.is_terminal_result({"success": False}) is True
+
+
+def test_not_terminal_when_failure_needs_followup() -> None:
+    assert (
+        completion.is_terminal_result({"success": False, "needsFollowup": True})
+        is False
+    )
+
+
+def test_not_terminal_for_pure_success() -> None:
+    assert completion.is_terminal_result({"success": True}) is False
+
+
+def test_empty_or_none_not_terminal() -> None:
+    assert completion.is_terminal_result(None) is False
+    assert completion.is_terminal_result({}) is False
+
+
+def test_completion_golden(assert_golden) -> None:
+    cases = [
+        {"success": True},
+        {"success": False},
+        {"success": False, "needsFollowup": True},
+        {"terminal": True},
+        {"success": False, "terminal": True},
+        {},
+        None,
+    ]
+    payload = [
+        {"input": case, "is_terminal": completion.is_terminal_result(case)}
+        for case in cases
+    ]
+    assert_golden("completion_decisions", payload)

steerable_agent_harness-0.2.0/tests/test_policy.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import pytest
+
+from steerable_agent_harness import policy
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected",
+    [
+        ("get_user", "read"),
+        ("list_files", "read"),
+        ("read_file", "read"),
+        ("create_event", "safe_write"),
+        ("update_chat", "safe_write"),
+        ("set_config", "safe_write"),
+        ("write_file", "safe_write"),
+        ("apply_patch", "safe_write"),
+        ("delete_event", "destructive"),
+        ("drop_table", "destructive"),
+        ("remove_user", "destructive"),
+        ("destroy_session", "destructive"),
+        ("compute_score", "other"),
+        ("orchestrate_steps", "other"),
+        ("", "other"),
+    ],
+)
+def test_decide_tool_mode(tool_name: str, expected: str) -> None:
+    assert policy.decide_tool_mode(tool_name) == expected
+
+
+def test_decide_tool_mode_is_case_insensitive() -> None:
+    assert policy.decide_tool_mode("DELETE_USER") == "destructive"
+    assert policy.decide_tool_mode("Get_User") == "read"
+
+
+def test_policy_decision_dataclass_round_trip() -> None:
+    decision = policy.PolicyDecision(allowed=True, tool_mode="read", reason="auto")
+    assert decision.allowed is True
+    assert decision.tool_mode == "read"
+    assert decision.reason == "auto"
+
+
+def test_policy_decision_golden(assert_golden) -> None:
+    samples = [
+        ("get_x", policy.decide_tool_mode("get_x")),
+        ("create_x", policy.decide_tool_mode("create_x")),
+        ("delete_x", policy.decide_tool_mode("delete_x")),
+        ("frobnicate", policy.decide_tool_mode("frobnicate")),
+    ]
+    payload = {name: mode for name, mode in samples}
+    assert_golden("policy_decisions", payload)

steerable_agent_harness-0.2.0/tests/test_retry.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import random
+
+from steerable_agent_harness import retry
+
+
+def test_default_policy_attempts() -> None:
+    policy = retry.RetryPolicy()
+    assert policy.max_attempts == 3
+    assert policy.base_delay_ms == 200
+    assert policy.max_delay_ms == 5000
+    assert policy.jitter is True
+
+
+def test_retry_delay_doubling_without_jitter() -> None:
+    policy = retry.RetryPolicy(base_delay_ms=100, max_delay_ms=1_000_000, jitter=False)
+    delays = [retry.next_retry_delay_ms(policy, attempt) for attempt in range(1, 6)]
+    assert delays == [100, 200, 400, 800, 1600]
+
+
+def test_retry_delay_caps_at_max() -> None:
+    policy = retry.RetryPolicy(base_delay_ms=1000, max_delay_ms=2500, jitter=False)
+    delays = [retry.next_retry_delay_ms(policy, attempt) for attempt in range(1, 6)]
+    assert delays == [1000, 2000, 2500, 2500, 2500]
+
+
+def test_retry_delay_jitter_within_bounds() -> None:
+    policy = retry.RetryPolicy(base_delay_ms=200, max_delay_ms=5000, jitter=True)
+    rng = random.Random(42)
+    samples: list[int] = []
+    state = random.getstate()
+    try:
+        random.seed(42)
+        for attempt in range(1, 6):
+            samples.append(retry.next_retry_delay_ms(policy, attempt))
+    finally:
+        random.setstate(state)
+    for attempt, value in zip(range(1, 6), samples, strict=True):
+        base = min(200 * (2 ** (attempt - 1)), 5000)
+        assert int(base * 0.8) <= value <= int(base * 1.2) + 1
+    assert rng  # silence unused warning if helper kept
+
+
+def test_attempt_clamped_to_one() -> None:
+    policy = retry.RetryPolicy(base_delay_ms=100, max_delay_ms=10_000, jitter=False)
+    assert retry.next_retry_delay_ms(policy, 0) == 100
+    assert retry.next_retry_delay_ms(policy, -1) == 100
+
+
+def test_retry_golden_no_jitter(assert_golden) -> None:
+    policy = retry.RetryPolicy(base_delay_ms=100, max_delay_ms=2_000, jitter=False)
+    payload = {
+        "policy": {
+            "max_attempts": policy.max_attempts,
+            "base_delay_ms": policy.base_delay_ms,
+            "max_delay_ms": policy.max_delay_ms,
+            "jitter": policy.jitter,
+        },
+        "delays": [retry.next_retry_delay_ms(policy, a) for a in range(1, 6)],
+    }
+    assert_golden("retry_no_jitter", payload)

steerable_agent_harness-0.2.0/tests/test_tracing.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from steerable_agent_harness import tracing
+
+
+def test_trace_span_starts_open() -> None:
+    span = tracing.TraceSpan(span_id="step_1", name="llm.generate")
+    assert span.start_at  # ISO timestamp present
+    assert span.end_at is None
+
+
+def test_trace_span_finish_sets_end_at_once() -> None:
+    span = tracing.TraceSpan(span_id="step_2", name="tool.exec")
+    span.finish()
+    assert span.end_at is not None
+    first_end = span.end_at
+    span.finish()
+    assert span.end_at == first_end  # no double-overwrite
+
+
+def test_trace_span_attrs_default_to_empty_dict() -> None:
+    span = tracing.TraceSpan(span_id="step_3", name="planning")
+    assert span.attrs == {}
+    span.attrs["model"] = "gpt-4o"
+    assert span.attrs == {"model": "gpt-4o"}
+
+
+def test_trace_span_golden(assert_golden) -> None:
+    span = tracing.TraceSpan(
+        span_id="step_1",
+        name="llm.generate",
+        start_at="2026-01-01T00:00:00+00:00",
+        attrs={"model": "gpt-4o"},
+    )
+    span.end_at = "2026-01-01T00:00:01+00:00"
+    payload = {
+        "span_id": span.span_id,
+        "name": span.name,
+        "start_at": span.start_at,
+        "end_at": span.end_at,
+        "attrs": span.attrs,
+    }
+    assert_golden("trace_span_basic", payload)