Open History to see the last commit
1"""E1 — Harbor adapter for the TanStack AI context-optimization agent.
2
3Modeled on Harbor's ``langgraph.py`` + ``langgraphjs_runner.mjs`` precedent: a
4Python adapter that installs Node and the pinned ``@tanstack/ai`` packages into
5the task container, uploads ``tanstack_ai_runner.mjs``, runs the agent, and
6reports usage (including cache tokens) back into the Harbor trajectory the same
7way ``strands_runner.py`` does.
8
9Harbor is Apache-2.0. Adopting its runner buys direct comparability with the
10Strands numbers.
11
12NOTE: the exact ``BaseInstalledAgent`` method names / return shapes depend on
13the Harbor version you pin. Points that must be checked against that version are
14marked ``TODO(harbor)``. The Node runner (``tanstack_ai_runner.mjs``) is the
15source of truth for the agent behavior and the per-trial record shape.
16"""
17
18from __future__ import annotations
19
20import json
21import os
22import re
23import shlex
24from dataclasses import dataclass
25from pathlib import Path
26
27try:
28 # TODO(harbor): import path for the installed-agent base class in your pin.
29 from harbor.agents import BaseInstalledAgent # type: ignore
30except Exception: # pragma: no cover - lets this file import without Harbor present
31 class BaseInstalledAgent: # minimal stand-in for type-checking / docs
32 pass
33
34
35RUNNER = "tanstack_ai_runner.mjs"
36# Everything the runner needs at container runtime. The static imports
37# (ai, ai-optimize, ai-code-mode, ai-isolate-quickjs) load at startup; the
38# adapters (anthropic / openai / gemini) load dynamically per arm. Omitting any
39# of these makes the runner fail before the first trial.
40RUNTIME_PACKAGES = [
41 "@tanstack/ai",
42 "@tanstack/ai-optimize",
43 "@tanstack/ai-code-mode",
44 "@tanstack/ai-isolate-quickjs",
45 "@tanstack/ai-anthropic",
46 "@tanstack/ai-openai",
47 "@tanstack/ai-gemini",
48]
49
50
51def _pinned_specs() -> list[str]:
52 """Pin every runtime package to the published version (brief §7: "every
53 number names its implementation — language, package, version"). The pin
54 comes from ``TANSTACK_AI_PIN``; we refuse to build the install command
55 without a valid one, so a placeholder never reaches the shell."""
56 pin = os.environ.get("TANSTACK_AI_PIN", "")
57 if not re.fullmatch(r"[0-9A-Za-z][0-9A-Za-z.\-]*", pin):
58 raise RuntimeError(
59 "Set TANSTACK_AI_PIN to the published version to install "
60 "(e.g. TANSTACK_AI_PIN=0.1.0)."
61 )
62 return [f"{pkg}@{pin}" for pkg in RUNTIME_PACKAGES]
63
64
65@dataclass
66class ArmConfig:
67 arm: str # baseline | global | adorned | universal
68 model: str
69 turn_limit: int = 30
70
71
72class TanStackAIAgent(BaseInstalledAgent):
73 """Runs the TanStack AI agent for one arm/model inside a Harbor task container."""
74
75 def __init__(self, arm: str, model: str, turn_limit: int = 30) -> None:
76 self.cfg = ArmConfig(arm=arm, model=model, turn_limit=turn_limit)
77
78 # --- container provisioning ------------------------------------------------
79 def install(self, container) -> None:
80 """Install Node + pinned packages and upload the runner."""
81 # TODO(harbor): use Harbor's container exec/upload API for your pin.
82 container.exec(["bash", "-lc", "node --version || (curl -fsSL https://deb.nodesource.com/setup_24.x | bash - && apt-get install -y nodejs)"])
83 container.exec(["bash", "-lc", "mkdir -p /agent"])
84 container.upload(str(Path(__file__).with_name(RUNNER)), f"/agent/{RUNNER}")
85 container.upload(str(Path(__file__).with_name("arms.mjs")), "/agent/arms.mjs")
86 container.upload(str(Path(__file__).with_name("tools.mjs")), "/agent/tools.mjs")
87 specs = " ".join(shlex.quote(s) for s in _pinned_specs())
88 container.exec(["bash", "-lc", f"cd /agent && npm init -y >/dev/null 2>&1 && npm install {specs}"])
89
90 # --- the run ---------------------------------------------------------------
91 def run(self, container, task) -> dict:
92 """Run one task and return a trajectory dict Harbor converts."""
93 task_json = json.dumps(self._task_payload(task))
94 env = {
95 "ARM": self.cfg.arm,
96 "MODEL": self.cfg.model,
97 "TURN_LIMIT": str(self.cfg.turn_limit),
98 # Provider keys are injected by Harbor's secret mechanism.
99 "ANTHROPIC_API_KEY": os.environ.get("ANTHROPIC_API_KEY", ""),
100 "OPENAI_API_KEY": os.environ.get("OPENAI_API_KEY", ""),
101 }
102 # Write the task file, run the runner, capture its single JSONL line.
103 container.exec(["bash", "-lc", f"cat > /agent/task.json <<'EOF'\n{task_json}\nEOF"])
104 result = container.exec(
105 ["bash", "-lc", f"cd /agent && node {RUNNER} --smoke task.json"],
106 env=env,
107 )
108 record = json.loads(result.stdout.strip().splitlines()[-1])
109 return self._to_trajectory(record)
110
111 # --- mapping helpers -------------------------------------------------------
112 def _task_payload(self, task) -> dict:
113 # TODO(harbor): map Harbor's task object to the runner's task shape
114 # ({ id, suite, prompt, cwd, answer }). For Terminal-Bench 2.1 the
115 # prompt + working dir come from the task; `answer` may be absent (Harbor
116 # grades via its own checker instead of the runner's `classify`).
117 return {
118 "id": getattr(task, "id", "task"),
119 "suite": getattr(task, "suite", "terminal-bench"),
120 "prompt": getattr(task, "instruction", getattr(task, "prompt", "")),
121 "cwd": getattr(task, "workdir", "/workspace"),
122 "answer": getattr(task, "answer", None),
123 }
124
125 def _to_trajectory(self, record: dict) -> dict:
126 # Report usage incl. cache tokens into the Harbor context, mirroring how
127 # strands_runner.py surfaces usage. Harbor reads these for its cost math;
128 # our report.mjs is the independent cross-check.
129 return {
130 "outcome": record["outcome"],
131 "usage": {
132 "input_tokens": record["tokens"]["input"],
133 "output_tokens": record["tokens"]["output"],
134 "cache_read_tokens": record["tokens"]["cache_read"],
135 "cache_write_tokens": record["tokens"]["cache_write"],
136 },
137 "steps": record["tokens"]["steps"],
138 "metadata": {
139 "arm": record["arm"],
140 "model": record["model"],
141 "implementation": record["implementation"],
142 "failure_class": record.get("failureClass"),
143 "truncation": record.get("truncation"),
144 },
145 }