steerable-agent-harness 0.6.0__py3-none-any.whl

steerable_agent_harness/__init__.py

@@ -0,0 +1,37 @@
+from .budget import BudgetLimit, BudgetState, consume_budget
+from .completion import is_terminal_result
+from .policy import PolicyDecision, ToolMode, decide_tool_mode
+from .retry import RetryPolicy, next_retry_delay_ms
+from .safety import (
+    BUILTIN_PATTERNS,
+    SAFETY_CATEGORIES,
+    CommandSafetyConfig,
+    SafetyPatternDef,
+    ShellCommandClassification,
+    classify_shell_command,
+    get_patterns_by_category,
+)
+from .tracing import TraceSpan
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BUILTIN_PATTERNS",
+    "SAFETY_CATEGORIES",
+    "BudgetLimit",
+    "BudgetState",
+    "CommandSafetyConfig",
+    "PolicyDecision",
+    "RetryPolicy",
+    "SafetyPatternDef",
+    "ShellCommandClassification",
+    "ToolMode",
+    "TraceSpan",
+    "__version__",
+    "classify_shell_command",
+    "consume_budget",
+    "decide_tool_mode",
+    "get_patterns_by_category",
+    "is_terminal_result",
+    "next_retry_delay_ms",
+]

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/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/generated.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from typing import Any
+from pydantic import BaseModel
+
+class ActionSegmentPayload(BaseModel):
+    segments: list[Any]
+
+class AnalysisDocumentPayload(BaseModel):
+    title: Any | None = None
+    body: str
+    createdAt: Any | None = None
+    modelId: Any | None = None
+
+class AskUserQuestionsPayload(BaseModel):
+    intro: str
+    outro: Any | None = None
+    answers: Any | None = None
+    questions: list[Any]
+
+class CoverageReportPayload(BaseModel):
+    reportId: str
+    title: str
+    overallCoverage: float
+    overallMastery: float
+    summary: Any | None = None
+    sections: list[Any]
+    weakPoints: list[Any]
+    actions: dict[str, Any]
+
+class OrchestrationPlanPayload(BaseModel):
+    rationale: str | None = None
+    mode: str | None = None
+    tasks: list[Any]
+    coordinator: dict[str, Any] | None = None
+
+class PlanSelectorPayload(BaseModel):
+    comparison: str
+    selectedPlan: Any | None = None
+    goalAttribution: dict[str, Any]
+    plans: list[Any]
+
+class PlanStepsPayload(BaseModel):
+    steps: list[Any]
+
+class QuizPayload(BaseModel):
+    quizId: str
+    title: str
+    description: Any | None = None
+    submitActionLabel: str
+    submittedAnswers: Any | None = None
+    questions: list[Any]
+
+class ResearchPlanPayload(BaseModel):
+    topic: str
+    round: int
+    final: bool
+    subQuestions: list[Any]
+    decision: dict[str, Any]
+
+class SearchSourcesPayload(BaseModel):
+    sources: list[Any]
+
+class SuggestedRepliesPayload(BaseModel):
+    suggestions: list[Any]
+
+class SummaryMessagePayload(BaseModel):
+    body: str
+    summarizedCount: Any | None = None
+    status: Any | None = None
+    type: Any | None = None
+
+class ThinkingProcessPayload(BaseModel):
+    body: str
+    defaultExpanded: bool | None = None
+
+class ToolExecutionPayload(BaseModel):
+    id: str
+    name: str
+    status: str
+    summary: Any | None = None
+    args: Any | None = None
+    output: Any | None = None
+    error: Any | None = None
+    durationMs: Any | None = None
+    icon: Any | None = None
+    expandable: bool | None = None
+
+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
+    parts: list[Any] | None = None
+    agentId: str | None = None
+    toolCalls: list[Any] | None = None
+    toolResult: Any | None = None
+    createdAt: str
+    updatedAt: str | None = None
+
+class ContentPart(BaseModel):
+    type: str
+    text: str | None = None
+    url: str | None = None
+    data: str | None = None
+    mediaType: 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/policy.py

@@ -0,0 +1,35 @@
+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
+
+
+#: Side-effect-free network reads the prefix rules cannot reach. Exact
+#: names, not a ``web_`` prefix: a future ``web_deploy``-style tool must not
+#: inherit the read posture. The approval algebra reads this table
+#: (``ApprovalRequest.mode``), so the classification decides both the
+#: prompt's risk label and the headless AutoApprover's default verdict.
+_READ_EXACT = frozenset({"web_search", "web_fetch"})
+
+
+def decide_tool_mode(tool_name: str) -> ToolMode:
+    normalized = tool_name.lower()
+    if normalized in _READ_EXACT:
+        return "read"
+    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/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/safety.py

@@ -0,0 +1,170 @@
+"""Shell command safety patterns — classify a command before it runs.
+
+Ported from deeppath-agent's `src/harness/safety-patterns.ts` (61 built-in
+rules) and kept in lockstep with the TS twin
+``packages/agent-harness/ts/src/safety-patterns.ts`` via the conformance case
+``tests/conformance/cases/safety/classify_shell_command.yaml``.
+
+The classifier is a pure function: it never executes anything. Products decide
+what to do with a ``critical`` / ``warning`` verdict (block, require consent,
+or just annotate). Rule order matters: ``matched_rules`` follows
+``BUILTIN_PATTERNS`` order so both languages return identical lists.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+PatternSeverity = Literal["critical", "warning"]
+PatternPlatform = Literal["all", "unix", "windows"]
+
+
+@dataclass(frozen=True, slots=True)
+class SafetyPatternDef:
+    id: str
+    label: str
+    description: str
+    pattern: str
+    category: str
+    severity: PatternSeverity
+    platform: PatternPlatform
+
+
+SAFETY_CATEGORIES: dict[str, str] = {
+    "file_ops": "文件操作",
+    "system": "系统管理",
+    "process": "进程管理",
+    "network": "网络安全",
+    "package": "包管理",
+    "vcs": "版本控制",
+    "container": "容器管理",
+    "file_write": "文件写入",
+    "windows": "Windows / PowerShell",
+}
+
+# Merged from deeppath-agent local-actions.ts (web, severity=warning) and
+# local-executor.ts (desktop, severity=critical). Keep aligned with the TS twin.
+BUILTIN_PATTERNS: list[SafetyPatternDef] = [
+    # ── file_ops ──
+    SafetyPatternDef("rm", "rm 删除", "匹配 rm 命令", r"\brm\s", "file_ops", "warning", "unix"),
+    SafetyPatternDef("rm_end", "rm（行尾）", "匹配行尾的 rm", r"\brm$", "file_ops", "warning", "unix"),
+    SafetyPatternDef("rm_rf_root", "rm -rf /", "递归删除根目录", r"rm\s+-rf\s+\/(?:\s|$)", "file_ops", "critical", "unix"),
+    SafetyPatternDef("rmdir", "rmdir 删除目录", "匹配 rmdir 命令", r"\brmdir\s", "file_ops", "warning", "unix"),
+    SafetyPatternDef("mv", "mv 移动/重命名", "匹配 mv 命令", r"\bmv\s.*\/", "file_ops", "warning", "unix"),
+    SafetyPatternDef("shred", "shred 安全擦除", "不可恢复地擦除文件", r"\bshred\b", "file_ops", "warning", "unix"),
+    SafetyPatternDef("truncate", "truncate 截断文件", "截断文件内容", r"\btruncate\b", "file_ops", "warning", "unix"),
+    # ── system ──
+    SafetyPatternDef("sudo", "sudo 提权", "以超级用户权限执行", r"\bsudo\s", "system", "critical", "unix"),
+    SafetyPatternDef("mkfs", "mkfs 格式化磁盘", "创建文件系统（格式化）", r"\bmkfs\b", "system", "critical", "unix"),
+    SafetyPatternDef("dd", "dd 磁盘写入", "底层磁盘数据复制", r"\bdd\s", "system", "warning", "unix"),
+    SafetyPatternDef("dd_if", "dd if= 磁盘镜像", "使用 dd if= 读写磁盘", r"\bdd\s+if=", "system", "critical", "unix"),
+    SafetyPatternDef("format", "format 格式化", "格式化磁盘", r"\bformat\b", "system", "warning", "all"),
+    SafetyPatternDef("shutdown", "shutdown 关机", "关闭系统", r"\bshutdown\b", "system", "warning", "all"),
+    SafetyPatternDef("reboot", "reboot 重启", "重启系统", r"\breboot\b", "system", "warning", "all"),
+    SafetyPatternDef("chmod", "chmod 修改权限", "修改文件权限", r"\bchmod\s", "system", "warning", "unix"),
+    SafetyPatternDef("chmod_777_root", "chmod -R 777 /", "递归赋予根目录所有权限", r"chmod\s+-R\s+777\s+\/(?:\s|$)", "system", "critical", "unix"),
+    SafetyPatternDef("chown", "chown 修改所有者", "修改文件所有者", r"\bchown\s", "system", "warning", "unix"),
+    SafetyPatternDef("fork_bomb", "Fork Bomb", ":(){ :|:& };: fork 炸弹", r":\(\)\s*\{\s*:\|:&\s*\};:", "system", "critical", "unix"),
+    # ── process ──
+    SafetyPatternDef("kill", "kill 终止进程", "向进程发送信号", r"\bkill\s", "process", "warning", "unix"),
+    SafetyPatternDef("killall", "killall 终止所有", "按名称终止进程", r"\bkillall\s", "process", "warning", "unix"),
+    # ── network ──
+    SafetyPatternDef("curl_pipe_sh", "curl | sh", "从网络下载并直接执行脚本", r"\bcurl\s.*\|\s*(sh|bash|zsh)", "network", "warning", "unix"),
+    SafetyPatternDef("wget_pipe_sh", "wget | sh", "从网络下载并直接执行脚本", r"\bwget\s.*\|\s*(sh|bash|zsh)", "network", "warning", "unix"),
+    SafetyPatternDef("redirect_dev", "重定向到 /dev/", "向设备文件写入数据", r">\s*\/dev\/", "network", "warning", "unix"),
+    # ── package ──
+    SafetyPatternDef("npm_publish", "npm publish", "发布/取消发布 npm 包", r"\bnpm\s+(publish|unpublish)", "package", "warning", "all"),
+    SafetyPatternDef("pip_install", "pip install", "安装 Python 包", r"\bpip\s+install\b", "package", "warning", "all"),
+    SafetyPatternDef("npm_install", "npm install", "安装 npm 包", r"\bnpm\s+install\b", "package", "warning", "all"),
+    SafetyPatternDef("yarn_add", "yarn add", "添加 yarn 依赖", r"\byarn\s+add\b", "package", "warning", "all"),
+    SafetyPatternDef("pnpm_add", "pnpm add", "添加 pnpm 依赖", r"\bpnpm\s+add\b", "package", "warning", "all"),
+    SafetyPatternDef("uv_add", "uv add", "添加 uv 依赖", r"\buv\s+add\b", "package", "warning", "all"),
+    SafetyPatternDef("apt_install", "apt install/remove", "系统包管理器操作", r"\bapt(-get)?\s+(install|remove|purge)", "package", "warning", "unix"),
+    SafetyPatternDef("brew_install", "brew install/uninstall", "Homebrew 包管理器操作", r"\bbrew\s+(install|uninstall|remove)", "package", "warning", "unix"),
+    # ── vcs ──
+    SafetyPatternDef("git_push", "git push / reset --hard", "Git 远程推送或硬重置", r"\bgit\s+(push|reset\s+--hard|clean\s+-fd)", "vcs", "warning", "all"),
+    # ── container ──
+    SafetyPatternDef("docker_rm", "docker rm/rmi/prune", "删除容器/镜像或清理系统", r"\bdocker\s+(rm|rmi|system\s+prune)", "container", "warning", "all"),
+    # ── file_write ──
+    SafetyPatternDef("redirect_overwrite", "> / >> 重定向写入", "文件重定向覆盖或追加", r"\b(>\s|>>)\s*[^|]", "file_write", "warning", "all"),
+    SafetyPatternDef("tee", "tee 写入文件", "将输出写入文件", r"\btee\s", "file_write", "warning", "unix"),
+    SafetyPatternDef("sed_inplace", "sed -i 原地修改", "直接修改文件内容", r"\bsed\s+-i", "file_write", "warning", "unix"),
+    # ── windows ──
+    SafetyPatternDef("win_del", "del 删除", "Windows 删除命令", r"\bdel\s", "windows", "warning", "windows"),
+    SafetyPatternDef("win_rd", "rd 删除目录", "Windows 删除目录", r"\brd\s", "windows", "warning", "windows"),
+    SafetyPatternDef("win_rd_end", "rd（行尾）", "匹配行尾的 rd", r"\brd$", "windows", "warning", "windows"),
+    SafetyPatternDef("win_rdel", "rdel", "Windows rdel 命令", r"\brdel\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_del_force", "del /f /s /q 强制删除", "强制递归删除整个驱动器", r"\bdel\s+\/f\s+\/s\s+\/q\s+[a-z]:\\", "windows", "critical", "windows"),
+    SafetyPatternDef("win_rd_force", "rd /s /q 强制删除目录", "强制递归删除整个驱动器目录", r"\brd\s+\/s\s+\/q\s+[a-z]:\\", "windows", "critical", "windows"),
+    SafetyPatternDef("win_remove_item", "Remove-Item", "PowerShell 删除项", r"\bRemove-Item\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_stop_process", "Stop-Process", "PowerShell 终止进程", r"\bStop-Process\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_stop_computer", "Stop-Computer", "PowerShell 关机", r"\bStop-Computer\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_restart_computer", "Restart-Computer", "PowerShell 重启", r"\bRestart-Computer\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_set_execution_policy", "Set-ExecutionPolicy", "修改脚本执行策略", r"\bSet-ExecutionPolicy\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_format_volume", "Format-Volume", "PowerShell 格式化卷", r"\bFormat-Volume\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_clear_disk", "Clear-Disk", "PowerShell 清除磁盘", r"\bClear-Disk\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_wsl", "wsl 子系统", "调用 WSL 子系统", r"\bwsl\s", "windows", "warning", "windows"),
+    SafetyPatternDef("win_powershell_cmd", "powershell -Command", "通过 PowerShell 执行命令", r"\bpowershell\s.*-[Cc]ommand", "windows", "warning", "windows"),
+    SafetyPatternDef("win_pwsh", "pwsh", "PowerShell Core", r"\bpwsh\s", "windows", "warning", "windows"),
+    SafetyPatternDef("win_cmd_c", "cmd /c", "CMD 执行命令", r"\bcmd\s*\/c\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_reg", "reg delete/add", "注册表操作", r"\breg\s+(delete|add)\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_net", "net user/stop/start", "网络和用户管理", r"\bnet\s+(user|stop|start)\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_sc", "sc delete/stop/config", "服务管理", r"\bsc\s+(delete|stop|config)\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_diskpart", "diskpart", "磁盘分区工具", r"\bdiskpart\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_bcdedit", "bcdedit", "启动配置编辑", r"\bbcdedit\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_sfc", "sfc", "系统文件检查器", r"\bsfc\b", "windows", "warning", "windows"),
+    SafetyPatternDef("win_dism", "dism", "部署映像服务和管理", r"\bdism\b", "windows", "warning", "windows"),
+    # Only matches "format <drive>:" style disk formatting (incl. format.com),
+    # not PowerShell's Format-List / Format-Table output cmdlets (Format-Volume
+    # is covered separately above).
+    SafetyPatternDef("win_format_cmd", "format（Windows）", "Windows 格式化磁盘命令", r"\bformat(\.com)?\s+[a-z]:", "windows", "critical", "windows"),
+]
+
+
+@dataclass(slots=True)
+class CommandSafetyConfig:
+    disabled_pattern_ids: list[str] = field(default_factory=list)
+    custom_patterns: list[dict] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ShellCommandClassification:
+    severity: Literal["safe", "critical", "warning"]
+    matched_rules: list[str]
+
+
+def _compile(rule: SafetyPatternDef) -> re.Pattern[str]:
+    flags = re.IGNORECASE if rule.platform == "windows" else 0
+    return re.compile(rule.pattern, flags)
+
+
+def classify_shell_command(
+    command: str, config: CommandSafetyConfig | None = None
+) -> ShellCommandClassification:
+    normalized = command.strip()
+    if not normalized:
+        return ShellCommandClassification(severity="safe", matched_rules=[])
+
+    disabled = set(config.disabled_pattern_ids if config else [])
+    matched = [
+        rule
+        for rule in BUILTIN_PATTERNS
+        if rule.id not in disabled and _compile(rule).search(normalized)
+    ]
+    if not matched:
+        return ShellCommandClassification(severity="safe", matched_rules=[])
+    severity: Literal["critical", "warning"] = (
+        "critical" if any(r.severity == "critical" for r in matched) else "warning"
+    )
+    return ShellCommandClassification(
+        severity=severity, matched_rules=[r.id for r in matched]
+    )
+
+
+def get_patterns_by_category() -> dict[str, list[SafetyPatternDef]]:
+    grouped: dict[str, list[SafetyPatternDef]] = {}
+    for p in BUILTIN_PATTERNS:
+        grouped.setdefault(p.category, []).append(p)
+    return grouped

steerable_agent_harness/tracing.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import re
+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()
+
+
+# ---------------------------------------------------------------------------
+# Secret redaction (spec/runtime/README.md "Secret redaction").
+#
+# Every `payload` / `attrs` / `stageData` field persisted to a trace must be
+# secret-redacted first. `sanitize_for_trace` is the canonical scrubber: it
+# walks a JSON-ish value and redacts (a) any dict value whose key names a
+# credential, and (b) any string that *looks* like a live credential even
+# under a benign key (defense in depth — a tool result echoing an
+# `Authorization: Bearer …` header or an `sk-…` key must not land in a trace).
+# ---------------------------------------------------------------------------
+
+#: Replacement text for anything redacted.
+REDACTED = "***"
+
+#: Secret key names, compared after normalizing to lowercase alphanumerics
+#: (so `api_key`, `apiKey`, `api-key`, `ApiKey` all match `apikey`). Exact
+#: match only — substring matching would false-positive on `tokenize`,
+#: `monkey`, `authority`, etc.
+_SECRET_KEY_NAMES = frozenset(
+    {
+        "password",
+        "passwd",
+        "pwd",
+        "secret",
+        "token",
+        "accesstoken",
+        "refreshtoken",
+        "idtoken",
+        "apikey",
+        "authorization",
+        "auth",
+        "credential",
+        "credentials",
+        "clientsecret",
+        "privatekey",
+        "sessionkey",
+        "sessionid",
+        "cookie",
+        "setcookie",
+        "xapikey",
+    }
+)
+
+_KEY_NORMALIZE = re.compile(r"[^a-z0-9]")
+
+#: High-confidence live-credential value patterns. Kept narrow on purpose —
+#: each is a well-known secret prefix/format, so matches are almost never
+#: benign. Long opaque strings under a non-secret key are left alone (a hash
+#: or id is not a credential).
+_SECRET_VALUE_PATTERNS = (
+    # PEM private keys (any algorithm).
+    re.compile(
+        r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?-----END [A-Z0-9 ]*PRIVATE KEY-----",
+        re.DOTALL,
+    ),
+    # Authorization: Bearer <token>.
+    re.compile(r"Bearer\s+[A-Za-z0-9._~+/=-]{8,}", re.IGNORECASE),
+    # Common API-key prefixes: OpenAI/DeepSeek `sk-…`, GitHub
+    # (`ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_`/`github_pat_…`), GitLab `glpat-…`,
+    # Slack `xox…-…`, AWS `AKIA`/`ASIA…`.
+    re.compile(
+        r"\b(?:sk-[A-Za-z0-9_-]{8,}|gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,}"
+        r"|glpat-[A-Za-z0-9_-]{12,}|xox[baprs]-[A-Za-z0-9-]{8,}|(?:AKIA|ASIA)[A-Z0-9]{16})\b"
+    ),
+)
+
+
+def _is_secret_key(key: Any) -> bool:
+    if not isinstance(key, str):
+        return False
+    return _KEY_NORMALIZE.sub("", key.lower()) in _SECRET_KEY_NAMES
+
+
+def _scrub_string(text: str) -> str:
+    for pattern in _SECRET_VALUE_PATTERNS:
+        text = pattern.sub(REDACTED, text)
+    return text
+
+
+def sanitize_for_trace(value: Any, *, extra_keys: frozenset[str] | None = None) -> Any:
+    """Return ``value`` with credentials redacted, safe to persist in a trace.
+
+    Recursively walks dicts / lists / tuples / strings:
+
+    - a dict value whose key names a credential (see ``_SECRET_KEY_NAMES``,
+      plus ``extra_keys``) is replaced with ``REDACTED`` regardless of content;
+    - a string is scanned for live-credential patterns (Bearer tokens, ``sk-…``
+      keys, PEM private keys, …) and each match replaced with ``REDACTED``;
+    - all other values pass through unchanged.
+
+    The input is never mutated; a new structure is returned. Non-JSON scalar
+    types (numbers, booleans, ``None``) are returned as-is.
+    """
+    secret_names = (
+        _SECRET_KEY_NAMES | {_KEY_NORMALIZE.sub("", k.lower()) for k in extra_keys}
+        if extra_keys
+        else _SECRET_KEY_NAMES
+    )
+
+    def walk(node: Any) -> Any:
+        if isinstance(node, dict):
+            out: dict[Any, Any] = {}
+            for k, v in node.items():
+                if isinstance(k, str) and _KEY_NORMALIZE.sub("", k.lower()) in secret_names:
+                    out[k] = REDACTED
+                else:
+                    out[k] = walk(v)
+            return out
+        if isinstance(node, (list, tuple)):
+            return [walk(item) for item in node]
+        if isinstance(node, str):
+            return _scrub_string(node)
+        return node
+
+    return walk(value)

steerable_agent_harness-0.6.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: steerable-agent-harness
+Version: 0.6.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.6.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+steerable_agent_harness/__init__.py,sha256=NPyjrYCQQBvS7aJUu-UknVI6RHa-H-1wa3UCaxXGYl4,920
+steerable_agent_harness/budget.py,sha256=Cx38m3ifbbjVtG-FJPKpY4TrBsgS5AOTOaVGybkbUvk,927
+steerable_agent_harness/completion.py,sha256=FMqUyfyUssFmZXwA7ohwWMqj93gsXYsyd1VdfkZxCl0,343
+steerable_agent_harness/generated.py,sha256=jeynKncOP0HWEpXcFs7A7y3z4zloR0njCar2gMcBfbo,6005
+steerable_agent_harness/policy.py,sha256=nCv8F1U6Mmke0q1i6ZnGC6WaIK6BIWbXzj8XwxHYcIE,1137
+steerable_agent_harness/retry.py,sha256=UKDAfpKCc92oWABQb2rPepeCg3RYt45X3lHL18OGMQo,528
+steerable_agent_harness/safety.py,sha256=WwnI5LRNw9UuGb_a5t5u97_YgmmYVD7sYsQKPVlbD8c,11637
+steerable_agent_harness/tracing.py,sha256=PpcqRCrC4NIiESRSaUAPZi0FeZQn4gRxCUlqVSngKXg,4762
+steerable_agent_harness-0.6.0.dist-info/METADATA,sha256=Pd79fzji_JDunEtpCvjYJ_wXbgdfb69dyUgY1aE3egA,351
+steerable_agent_harness-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+steerable_agent_harness-0.6.0.dist-info/top_level.txt,sha256=L99GRcOHaeL_gakhZZnmpEbK5yV4fOeIxXzWKW_2lDA,24
+steerable_agent_harness-0.6.0.dist-info/RECORD,,

steerable_agent_harness-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

steerable_agent_harness-0.6.0.dist-info/top_level.txt

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