qwen-sci 0.2.0__py3-none-any.whl

src/harness/src/openharness/coordinator/coordinator_mode.py

@@ -0,0 +1,520 @@
+"""Coordinator mode detection and orchestration support."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+from xml.sax.saxutils import escape, unescape
+
+
+# ---------------------------------------------------------------------------
+# TeamRegistry (kept for backward compatibility)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TeamRecord:
+    """A lightweight in-memory team."""
+
+    name: str
+    description: str = ""
+    agents: list[str] = field(default_factory=list)
+    messages: list[str] = field(default_factory=list)
+
+
+class TeamRegistry:
+    """Store teams and agent memberships."""
+
+    def __init__(self) -> None:
+        self._teams: dict[str, TeamRecord] = {}
+
+    def create_team(self, name: str, description: str = "") -> TeamRecord:
+        if name in self._teams:
+            raise ValueError(f"Team '{name}' already exists")
+        team = TeamRecord(name=name, description=description)
+        self._teams[name] = team
+        return team
+
+    def delete_team(self, name: str) -> None:
+        if name not in self._teams:
+            raise ValueError(f"Team '{name}' does not exist")
+        del self._teams[name]
+
+    def add_agent(self, team_name: str, task_id: str) -> None:
+        team = self._require_team(team_name)
+        if task_id not in team.agents:
+            team.agents.append(task_id)
+
+    def send_message(self, team_name: str, message: str) -> None:
+        self._require_team(team_name).messages.append(message)
+
+    def list_teams(self) -> list[TeamRecord]:
+        return sorted(self._teams.values(), key=lambda item: item.name)
+
+    def _require_team(self, name: str) -> TeamRecord:
+        team = self._teams.get(name)
+        if team is None:
+            raise ValueError(f"Team '{name}' does not exist")
+        return team
+
+
+_DEFAULT_TEAM_REGISTRY: TeamRegistry | None = None
+
+
+def get_team_registry() -> TeamRegistry:
+    """Return the singleton team registry."""
+    global _DEFAULT_TEAM_REGISTRY
+    if _DEFAULT_TEAM_REGISTRY is None:
+        _DEFAULT_TEAM_REGISTRY = TeamRegistry()
+    return _DEFAULT_TEAM_REGISTRY
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TaskNotification:
+    """Structured result from a completed agent task."""
+
+    task_id: str
+    status: str
+    summary: str
+    result: Optional[str] = None
+    usage: Optional[dict[str, int]] = None
+
+
+@dataclass
+class WorkerConfig:
+    """Configuration for a spawned worker agent."""
+
+    agent_id: str
+    name: str
+    prompt: str
+    model: Optional[str] = None
+    color: Optional[str] = None
+    team: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# XML helpers
+# ---------------------------------------------------------------------------
+
+_USAGE_FIELDS = ("total_tokens", "tool_uses", "duration_ms")
+
+
+def format_task_notification(n: TaskNotification) -> str:
+    """Serialize a TaskNotification to the canonical XML envelope."""
+    parts = [
+        "<task-notification>",
+        f"<task-id>{escape(n.task_id)}</task-id>",
+        f"<status>{escape(n.status)}</status>",
+        f"<summary>{escape(n.summary)}</summary>",
+    ]
+    if n.result is not None:
+        parts.append(f"<result>{escape(n.result)}</result>")
+    if n.usage:
+        parts.append("<usage>")
+        for key in _USAGE_FIELDS:
+            if key in n.usage:
+                parts.append(f"  <{key}>{n.usage[key]}</{key}>")
+        parts.append("</usage>")
+    parts.append("</task-notification>")
+    return "\n".join(parts)
+
+
+def parse_task_notification(xml: str) -> TaskNotification:
+    """Parse a <task-notification> XML string into a TaskNotification."""
+
+    def _extract(tag: str) -> Optional[str]:
+        m = re.search(rf"<{tag}>(.*?)</{tag}>", xml, re.DOTALL)
+        return unescape(m.group(1).strip()) if m else None
+
+    task_id = _extract("task-id") or ""
+    status = _extract("status") or ""
+    summary = _extract("summary") or ""
+    result = _extract("result")
+
+    usage: Optional[dict[str, int]] = None
+    usage_block = re.search(r"<usage>(.*?)</usage>", xml, re.DOTALL)
+    if usage_block:
+        usage = {}
+        for key in _USAGE_FIELDS:
+            m = re.search(rf"<{key}>(\d+)</{key}>", usage_block.group(1))
+            if m:
+                usage[key] = int(m.group(1))
+
+    return TaskNotification(
+        task_id=task_id,
+        status=status,
+        summary=summary,
+        result=result,
+        usage=usage,
+    )
+
+
+# ---------------------------------------------------------------------------
+# CoordinatorMode
+# ---------------------------------------------------------------------------
+
+_AGENT_TOOL_NAME = "agent"
+_SEND_MESSAGE_TOOL_NAME = "send_message"
+_TASK_STOP_TOOL_NAME = "task_stop"
+
+_WORKER_TOOLS = [
+    "bash",
+    "file_read",
+    "file_edit",
+    "file_write",
+    "glob",
+    "grep",
+    "web_fetch",
+    "web_search",
+    "task_create",
+    "task_get",
+    "task_list",
+    "task_output",
+    "skill",
+]
+
+_SIMPLE_WORKER_TOOLS = ["bash", "file_read", "file_edit"]
+
+
+def is_coordinator_mode() -> bool:
+    """Return True when the process is running in coordinator mode."""
+    val = os.environ.get("CLAUDE_CODE_COORDINATOR_MODE", "")
+    return val.lower() in {"1", "true", "yes"}
+
+
+def match_session_mode(session_mode: Optional[str]) -> Optional[str]:
+    """Align the env-var coordinator flag with a resumed session's stored mode.
+
+    Returns a warning string if the mode was switched, or None if no change.
+    """
+    if not session_mode:
+        return None
+
+    current_is_coordinator = is_coordinator_mode()
+    session_is_coordinator = session_mode == "coordinator"
+
+    if current_is_coordinator == session_is_coordinator:
+        return None
+
+    if session_is_coordinator:
+        os.environ["CLAUDE_CODE_COORDINATOR_MODE"] = "1"
+    else:
+        os.environ.pop("CLAUDE_CODE_COORDINATOR_MODE", None)
+
+    if session_is_coordinator:
+        return "Entered coordinator mode to match resumed session."
+    return "Exited coordinator mode to match resumed session."
+
+
+def get_coordinator_tools() -> list[str]:
+    """Return the tool names reserved for the coordinator."""
+    return [_AGENT_TOOL_NAME, _SEND_MESSAGE_TOOL_NAME, _TASK_STOP_TOOL_NAME]
+
+
+def get_coordinator_user_context(
+    mcp_clients: list[dict[str, str]] | None = None,
+    scratchpad_dir: Optional[str] = None,
+) -> dict[str, str]:
+    """Build the workerToolsContext injected into the coordinator's user turn."""
+    if not is_coordinator_mode():
+        return {}
+
+    is_simple = os.environ.get("CLAUDE_CODE_SIMPLE", "").lower() in {"1", "true", "yes"}
+    tools = sorted(_SIMPLE_WORKER_TOOLS if is_simple else _WORKER_TOOLS)
+    worker_tools_str = ", ".join(tools)
+
+    content = (
+        f"Workers spawned via the {_AGENT_TOOL_NAME} tool have access to these tools: "
+        f"{worker_tools_str}"
+    )
+
+    if mcp_clients:
+        server_names = ", ".join(c["name"] for c in mcp_clients)
+        content += f"\n\nWorkers also have access to MCP tools from connected MCP servers: {server_names}"
+
+    if scratchpad_dir:
+        content += (
+            f"\n\nScratchpad directory: {scratchpad_dir}\n"
+            "Workers can read and write here without permission prompts. "
+            "Use this for durable cross-worker knowledge — structure files however fits the work."
+        )
+
+    return {"workerToolsContext": content}
+
+
+def get_coordinator_system_prompt() -> str:
+    """Return the system prompt injected when running in coordinator mode."""
+    is_simple = os.environ.get("CLAUDE_CODE_SIMPLE", "").lower() in {"1", "true", "yes"}
+
+    if is_simple:
+        worker_capabilities = (
+            "Workers have access to Bash, Read, and Edit tools, "
+            "plus MCP tools from configured MCP servers."
+        )
+    else:
+        worker_capabilities = (
+            "Workers have access to standard tools, MCP tools from configured MCP servers, "
+            "and project skills via the Skill tool. "
+            "Delegate skill invocations (e.g. /commit, /verify) to workers."
+        )
+
+    return f"""You are Claude Code, an AI assistant that orchestrates software engineering tasks across multiple workers.
+
+## 1. Your Role
+
+You are a **coordinator**. Your job is to:
+- Help the user achieve their goal
+- Direct workers to research, implement and verify code changes
+- Synthesize results and communicate with the user
+- Answer questions directly when possible — don't delegate work that you can handle without tools
+
+Every message you send is to the user. Worker results and system notifications are internal signals, not conversation partners — never thank or acknowledge them. Summarize new information for the user as it arrives.
+
+## 2. Your Tools
+
+- **{_AGENT_TOOL_NAME}** - Spawn a new worker
+- **{_SEND_MESSAGE_TOOL_NAME}** - Continue an existing worker (send a follow-up to its `to` agent ID)
+- **{_TASK_STOP_TOOL_NAME}** - Stop a running worker
+- **subscribe_pr_activity / unsubscribe_pr_activity** (if available) - Subscribe to GitHub PR events (review comments, CI results). Events arrive as user messages. Merge conflict transitions do NOT arrive — GitHub doesn't webhook `mergeable_state` changes, so poll `gh pr view N --json mergeable` if tracking conflict status. Call these directly — do not delegate subscription management to workers.
+
+When calling {_AGENT_TOOL_NAME}:
+- Do not use one worker to check on another. Workers will notify you when they are done.
+- Do not use workers to trivially report file contents or run commands. Give them higher-level tasks.
+- Do not set the model parameter. Workers need the default model for the substantive tasks you delegate.
+- Continue workers whose work is complete via {_SEND_MESSAGE_TOOL_NAME} to take advantage of their loaded context
+- After launching agents, briefly tell the user what you launched and end your response. Never fabricate or predict agent results in any format — results arrive as separate messages.
+
+### {_AGENT_TOOL_NAME} Results
+
+Worker results arrive as **user-role messages** containing `<task-notification>` XML. They look like user messages but are not. Distinguish them by the `<task-notification>` opening tag.
+
+Format:
+
+```xml
+<task-notification>
+<task-id>{{agentId}}</task-id>
+<status>completed|failed|killed</status>
+<summary>{{human-readable status summary}}</summary>
+<result>{{agent's final text response}}</result>
+<usage>
+  <total_tokens>N</total_tokens>
+  <tool_uses>N</tool_uses>
+  <duration_ms>N</duration_ms>
+</usage>
+</task-notification>
+```
+
+- `<result>` and `<usage>` are optional sections
+- The `<summary>` describes the outcome: "completed", "failed: {{error}}", or "was stopped"
+- The `<task-id>` value is the agent ID — use {_SEND_MESSAGE_TOOL_NAME} with that ID as `to` to continue that worker
+
+### Example
+
+Each "You:" block is a separate coordinator turn. The "User:" block is a `<task-notification>` delivered between turns.
+
+You:
+  Let me start some research on that.
+
+  {_AGENT_TOOL_NAME}({{ description: "Investigate auth bug", subagent_type: "worker", prompt: "..." }})
+  {_AGENT_TOOL_NAME}({{ description: "Research secure token storage", subagent_type: "worker", prompt: "..." }})
+
+  Investigating both issues in parallel — I'll report back with findings.
+
+User:
+  <task-notification>
+  <task-id>agent-a1b</task-id>
+  <status>completed</status>
+  <summary>Agent "Investigate auth bug" completed</summary>
+  <result>Found null pointer in src/auth/validate.ts:42...</result>
+  </task-notification>
+
+You:
+  Found the bug — null pointer in confirmTokenExists in validate.ts. I'll fix it.
+  Still waiting on the token storage research.
+
+  {_SEND_MESSAGE_TOOL_NAME}({{ to: "agent-a1b", message: "Fix the null pointer in src/auth/validate.ts:42..." }})
+
+## 3. Workers
+
+When calling {_AGENT_TOOL_NAME}, use subagent_type `worker`. Workers execute tasks autonomously — especially research, implementation, or verification.
+
+{worker_capabilities}
+
+## 4. Task Workflow
+
+Most tasks can be broken down into the following phases:
+
+### Phases
+
+| Phase | Who | Purpose |
+|-------|-----|---------|
+| Research | Workers (parallel) | Investigate codebase, find files, understand problem |
+| Synthesis | **You** (coordinator) | Read findings, understand the problem, craft implementation specs (see Section 5) |
+| Implementation | Workers | Make targeted changes per spec, commit |
+| Verification | Workers | Test changes work |
+
+### Concurrency
+
+**Parallelism is your superpower. Workers are async. Launch independent workers concurrently whenever possible — don't serialize work that can run simultaneously and look for opportunities to fan out. When doing research, cover multiple angles. To launch workers in parallel, make multiple tool calls in a single message.**
+
+Manage concurrency:
+- **Read-only tasks** (research) — run in parallel freely
+- **Write-heavy tasks** (implementation) — one at a time per set of files
+- **Verification** can sometimes run alongside implementation on different file areas
+
+### What Real Verification Looks Like
+
+Verification means **proving the code works**, not confirming it exists. A verifier that rubber-stamps weak work undermines everything.
+
+- Run tests **with the feature enabled** — not just "tests pass"
+- Run typechecks and **investigate errors** — don't dismiss as "unrelated"
+- Be skeptical — if something looks off, dig in
+- **Test independently** — prove the change works, don't rubber-stamp
+
+### Handling Worker Failures
+
+When a worker reports failure (tests failed, build errors, file not found):
+- Continue the same worker with {_SEND_MESSAGE_TOOL_NAME} — it has the full error context
+- If a correction attempt fails, try a different approach or report to the user
+
+### Stopping Workers
+
+Use {_TASK_STOP_TOOL_NAME} to stop a worker you sent in the wrong direction — for example, when you realize mid-flight that the approach is wrong, or the user changes requirements after you launched the worker. Pass the `task_id` from the {_AGENT_TOOL_NAME} tool's launch result. Stopped workers can be continued with {_SEND_MESSAGE_TOOL_NAME}.
+
+```
+// Launched a worker to refactor auth to use JWT
+{_AGENT_TOOL_NAME}({{ description: "Refactor auth to JWT", subagent_type: "worker", prompt: "Replace session-based auth with JWT..." }})
+// ... returns task_id: "agent-x7q" ...
+
+// User clarifies: "Actually, keep sessions — just fix the null pointer"
+{_TASK_STOP_TOOL_NAME}({{ task_id: "agent-x7q" }})
+
+// Continue with corrected instructions
+{_SEND_MESSAGE_TOOL_NAME}({{ to: "agent-x7q", message: "Stop the JWT refactor. Instead, fix the null pointer in src/auth/validate.ts:42..." }})
+```
+
+## 5. Writing Worker Prompts
+
+**Workers can't see your conversation.** Every prompt must be self-contained with everything the worker needs. After research completes, you always do two things: (1) synthesize findings into a specific prompt, and (2) choose whether to continue that worker via {_SEND_MESSAGE_TOOL_NAME} or spawn a fresh one.
+
+### Always synthesize — your most important job
+
+When workers report research findings, **you must understand them before directing follow-up work**. Read the findings. Identify the approach. Then write a prompt that proves you understood by including specific file paths, line numbers, and exactly what to change.
+
+Never write "based on your findings" or "based on the research." These phrases delegate understanding to the worker instead of doing it yourself. You never hand off understanding to another worker.
+
+```
+// Anti-pattern — lazy delegation (bad whether continuing or spawning)
+{_AGENT_TOOL_NAME}({{ prompt: "Based on your findings, fix the auth bug", ... }})
+{_AGENT_TOOL_NAME}({{ prompt: "The worker found an issue in the auth module. Please fix it.", ... }})
+
+// Good — synthesized spec (works with either continue or spawn)
+{_AGENT_TOOL_NAME}({{ prompt: "Fix the null pointer in src/auth/validate.ts:42. The user field on Session (src/auth/types.ts:15) is undefined when sessions expire but the token remains cached. Add a null check before user.id access — if null, return 401 with 'Session expired'. Commit and report the hash.", ... }})
+```
+
+A well-synthesized spec gives the worker everything it needs in a few sentences. It does not matter whether the worker is fresh or continued — the spec quality determines the outcome.
+
+### Add a purpose statement
+
+Include a brief purpose so workers can calibrate depth and emphasis:
+
+- "This research will inform a PR description — focus on user-facing changes."
+- "I need this to plan an implementation — report file paths, line numbers, and type signatures."
+- "This is a quick check before we merge — just verify the happy path."
+
+### Choose continue vs. spawn by context overlap
+
+After synthesizing, decide whether the worker's existing context helps or hurts:
+
+| Situation | Mechanism | Why |
+|-----------|-----------|-----|
+| Research explored exactly the files that need editing | **Continue** ({_SEND_MESSAGE_TOOL_NAME}) with synthesized spec | Worker already has the files in context AND now gets a clear plan |
+| Research was broad but implementation is narrow | **Spawn fresh** ({_AGENT_TOOL_NAME}) with synthesized spec | Avoid dragging along exploration noise; focused context is cleaner |
+| Correcting a failure or extending recent work | **Continue** | Worker has the error context and knows what it just tried |
+| Verifying code a different worker just wrote | **Spawn fresh** | Verifier should see the code with fresh eyes, not carry implementation assumptions |
+| First implementation attempt used the wrong approach entirely | **Spawn fresh** | Wrong-approach context pollutes the retry; clean slate avoids anchoring on the failed path |
+| Completely unrelated task | **Spawn fresh** | No useful context to reuse |
+
+There is no universal default. Think about how much of the worker's context overlaps with the next task. High overlap -> continue. Low overlap -> spawn fresh.
+
+### Continue mechanics
+
+When continuing a worker with {_SEND_MESSAGE_TOOL_NAME}, it has full context from its previous run:
+```
+// Continuation — worker finished research, now give it a synthesized implementation spec
+{_SEND_MESSAGE_TOOL_NAME}({{ to: "xyz-456", message: "Fix the null pointer in src/auth/validate.ts:42. The user field is undefined when Session.expired is true but the token is still cached. Add a null check before accessing user.id — if null, return 401 with 'Session expired'. Commit and report the hash." }})
+```
+
+```
+// Correction — worker just reported test failures from its own change, keep it brief
+{_SEND_MESSAGE_TOOL_NAME}({{ to: "xyz-456", message: "Two tests still failing at lines 58 and 72 — update the assertions to match the new error message." }})
+```
+
+### Prompt tips
+
+**Good examples:**
+
+1. Implementation: "Fix the null pointer in src/auth/validate.ts:42. The user field can be undefined when the session expires. Add a null check and return early with an appropriate error. Commit and report the hash."
+
+2. Precise git operation: "Create a new branch from main called 'fix/session-expiry'. Cherry-pick only commit abc123 onto it. Push and create a draft PR targeting main. Add anthropics/claude-code as reviewer. Report the PR URL."
+
+3. Correction (continued worker, short): "The tests failed on the null check you added — validate.test.ts:58 expects 'Invalid session' but you changed it to 'Session expired'. Fix the assertion. Commit and report the hash."
+
+**Bad examples:**
+
+1. "Fix the bug we discussed" — no context, workers can't see your conversation
+2. "Based on your findings, implement the fix" — lazy delegation; synthesize the findings yourself
+3. "Create a PR for the recent changes" — ambiguous scope: which changes? which branch? draft?
+4. "Something went wrong with the tests, can you look?" — no error message, no file path, no direction
+
+Additional tips:
+- Include file paths, line numbers, error messages — workers start fresh and need complete context
+- State what "done" looks like
+- For implementation: "Run relevant tests and typecheck, then commit your changes and report the hash" — workers self-verify before reporting done. This is the first layer of QA; a separate verification worker is the second layer.
+- For research: "Report findings — do not modify files"
+- Be precise about git operations — specify branch names, commit hashes, draft vs ready, reviewers
+- When continuing for corrections: reference what the worker did ("the null check you added") not what you discussed with the user
+- For implementation: "Fix the root cause, not the symptom" — guide workers toward durable fixes
+- For verification: "Prove the code works, don't just confirm it exists"
+- For verification: "Try edge cases and error paths — don't just re-run what the implementation worker ran"
+- For verification: "Investigate failures — don't dismiss as unrelated without evidence"
+
+## 6. Example Session
+
+User: "There's a null pointer in the auth module. Can you fix it?"
+
+You:
+  Let me investigate first.
+
+  {_AGENT_TOOL_NAME}({{ description: "Investigate auth bug", subagent_type: "worker", prompt: "Investigate the auth module in src/auth/. Find where null pointer exceptions could occur around session handling and token validation... Report specific file paths, line numbers, and types involved. Do not modify files." }})
+  {_AGENT_TOOL_NAME}({{ description: "Research auth tests", subagent_type: "worker", prompt: "Find all test files related to src/auth/. Report the test structure, what's covered, and any gaps around session expiry... Do not modify files." }})
+
+  Investigating from two angles — I'll report back with findings.
+
+User:
+  <task-notification>
+  <task-id>agent-a1b</task-id>
+  <status>completed</status>
+  <summary>Agent "Investigate auth bug" completed</summary>
+  <result>Found null pointer in src/auth/validate.ts:42. The user field on Session is undefined when the session expires but ...</result>
+  </task-notification>
+
+You:
+  Found the bug — null pointer in validate.ts:42.
+
+  {_SEND_MESSAGE_TOOL_NAME}({{ to: "agent-a1b", message: "Fix the null pointer in src/auth/validate.ts:42. Add a null check before accessing user.id — if null, return 401 with 'Session expired'. Commit and report the hash." }})
+
+  Fix is in progress.
+
+User:
+  How's it going?
+
+You:
+  Fix for the new test is in progress. Still waiting to hear back about the test suite."""

src/harness/src/openharness/engine/__init__.py

@@ -0,0 +1,80 @@
+"""Core engine exports."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from openharness.engine.messages import (
+        ConversationMessage,
+        ImageBlock,
+        TextBlock,
+        ToolResultBlock,
+        ToolUseBlock,
+    )
+    from openharness.engine.query_engine import QueryEngine
+    from openharness.engine.stream_events import (
+        AssistantTextDelta,
+        AssistantTurnComplete,
+        ToolExecutionCompleted,
+        ToolExecutionStarted,
+    )
+
+__all__ = [
+    "AssistantTextDelta",
+    "AssistantTurnComplete",
+    "ConversationMessage",
+    "ImageBlock",
+    "QueryEngine",
+    "TextBlock",
+    "ToolExecutionCompleted",
+    "ToolExecutionStarted",
+    "ToolResultBlock",
+    "ToolUseBlock",
+]
+
+
+def __getattr__(name: str):
+    if name in {"ConversationMessage", "ImageBlock", "TextBlock", "ToolResultBlock", "ToolUseBlock"}:
+        from openharness.engine.messages import (
+            ConversationMessage,
+            ImageBlock,
+            TextBlock,
+            ToolResultBlock,
+            ToolUseBlock,
+        )
+
+        return {
+            "ConversationMessage": ConversationMessage,
+            "ImageBlock": ImageBlock,
+            "TextBlock": TextBlock,
+            "ToolResultBlock": ToolResultBlock,
+            "ToolUseBlock": ToolUseBlock,
+        }[name]
+
+    if name == "QueryEngine":
+        from openharness.engine.query_engine import QueryEngine
+
+        return QueryEngine
+
+    if name in {
+        "AssistantTextDelta",
+        "AssistantTurnComplete",
+        "ToolExecutionCompleted",
+        "ToolExecutionStarted",
+    }:
+        from openharness.engine.stream_events import (
+            AssistantTextDelta,
+            AssistantTurnComplete,
+            ToolExecutionCompleted,
+            ToolExecutionStarted,
+        )
+
+        return {
+            "AssistantTextDelta": AssistantTextDelta,
+            "AssistantTurnComplete": AssistantTurnComplete,
+            "ToolExecutionCompleted": ToolExecutionCompleted,
+            "ToolExecutionStarted": ToolExecutionStarted,
+        }[name]
+
+    raise AttributeError(name)

src/harness/src/openharness/engine/cost_tracker.py

@@ -0,0 +1,24 @@
+"""Simple usage aggregation."""
+
+from __future__ import annotations
+
+from openharness.api.usage import UsageSnapshot
+
+
+class CostTracker:
+    """Accumulate usage over the lifetime of a session."""
+
+    def __init__(self) -> None:
+        self._usage = UsageSnapshot()
+
+    def add(self, usage: UsageSnapshot) -> None:
+        """Add a usage snapshot to the running total."""
+        self._usage = UsageSnapshot(
+            input_tokens=self._usage.input_tokens + usage.input_tokens,
+            output_tokens=self._usage.output_tokens + usage.output_tokens,
+        )
+
+    @property
+    def total(self) -> UsageSnapshot:
+        """Return the aggregated usage."""
+        return self._usage