HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
"""One Qoder Cloud Agents turn, as a runner subprocess.
Spawned per turn by server.py under the same contract as every other backend: `__hr_init` first,
one `{"m": ..., "p": ...}` JSON line per event on stdout, `__hr_result` last, and server.py's
normaliser (_qoder_to_claude) unaware of the wire. What differs is that the agent loop runs in
Qoder's cloud, not in this sandbox: this process is a client of a REST + SSE API (Managed mode,
`/api/v1/cloud`), so what a CLI driver spends on a subprocess this one spends on a session.
The wire is Qoder's own Python SDK (`qca-sdk`, pinned in docker/entrypoint.sh into its own venv,
imported in Client so the module loads without it): typed calls, the SDK's retry classification
(a POST is retried only under an `Idempotency-Key`, which every user.message here carries), and
its SSE decoder. The reconnect loop stays here rather than in the SDK's ResumableStream, because
a stream that ends without a terminal event is decided by the SESSION's status (idle twice with no
idle event seen = the event was lost; running = reconnect), which the stream alone cannot know.
The credential never enters this process. The job carries the runner's loopback relay as the
base and a placeholder bearer; the relay holds the PAT and forwards this route verbatim (no body
rewrites, no served-model or usage taps, see _qoder_relay_route in server.py). The one network
call that bypasses the relay is the presigned artifact download, which carries no credential and
which the SDK follows itself (`files.download`), refusing a link that is not a web address.
Everything the turn creates at Qoder — the Environment, the Agent, the Session, uploaded input
files, delivered artifact files, a Vault for MCP bearers, Skill resources — is recorded in
<cwd>/.harness/qoder/state.json, which travels in the checkpoint. A follow-up turn finds the
session to continue there; `DELETE /workspace` runs this file in purge mode so a delete reaches
Qoder (nothing the session created outlives it).
Cancellation: the runner sends SIGTERM and waits a bounded grace before its SIGKILL (a remote
backend, BACKENDS[...]["remote"]). The handler raises out of whatever read is in flight, the
turn posts `POST /sessions/{id}/cancel`, says on stdout whether that was accepted, and exits.
Without that call the remote turn would keep running and billing after the local process died.
"""
from __future__ import annotations
import hashlib
import json
import mimetypes
import os
import pathlib
import re
import shutil
import signal
import sys
import time
import uuid
STATE_REL = os.path.join(".harness", "qoder", "state.json")
# The built-in tools of agent_toolset_20260401 (agents/schemas.md, "内置工具名"), the names
# `tools_disabled` matches exactly. The gateway's catalog is pinned equal to this tuple.
TOOLS = ("Bash", "DeliverArtifacts", "Edit", "Glob", "Grep", "ImageGen", "ImageSearch", "Read",
"WebFetch", "WebSearch", "Write")
TOOLSET = "agent_toolset_20260401"
EFFORTS = ("none", "low", "medium", "high", "xhigh", "max")
# Files the upload endpoint accepts (files/schemas.md): text MIME types, and this extension list.
# Anything else is refused by Qoder with a 400, so it is refused here first, naming the file.
UPLOAD_MIME_PREFIX = "text/"
UPLOAD_MIME = {"application/json", "application/xml", "application/javascript", "application/x-yaml",
"application/x-toml"}
UPLOAD_EXT = {".txt", ".md", ".csv", ".json", ".xml", ".yaml", ".yml", ".toml", ".ini", ".conf", ".cfg",
".env", ".log", ".html", ".htm", ".css", ".scss", ".less", ".js", ".jsx", ".ts", ".tsx",
".vue", ".svelte", ".py", ".go", ".rs", ".java", ".kt", ".scala", ".c", ".cpp", ".cc", ".h",
".hpp", ".rb", ".php", ".swift", ".r", ".lua", ".pl", ".sh", ".bash", ".zsh", ".fish",
".ps1", ".sql", ".graphql", ".gql", ".proto", ".dockerfile", ".makefile", ".gitignore",
".editorconfig", ".eslintrc", ".prettierrc", ".tex", ".rst", ".adoc", ".org", ".svg"}
UPLOAD_BARE = {"dockerfile", "makefile", "gemfile", "rakefile", "procfile", "vagrantfile", "justfile",
"brewfile"}
UPLOAD_MAX_BYTES = 5 * 1024 * 1024
MOUNT_ROOT = "/mnt/session/uploads"
# The largest delivered artifact landed in the workspace. A download goes to disk as it arrives (never
# held whole in memory) and is cut off past this.
ARTIFACT_MAX_BYTES = int(os.environ.get("HR_QODER_ARTIFACT_MAX_BYTES") or 2 * 1024 ** 3)
# How long one call may take, and how long a stream read may go without a byte. The stream
# carries a heartbeat about every 15 s, so a read that waits this long is a dead connection, and
# the turn reconnects from the last event id rather than hanging on it.
CALL_TIMEOUT_S = 120.0
STREAM_READ_TIMEOUT_S = 90.0
STREAM_RECONNECTS = 20
_SKILL_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
def _emit(method: str, payload) -> None:
sys.stdout.write(json.dumps({"m": method, "p": payload}, default=str) + "\n")
sys.stdout.flush()
class Cancelled(BaseException):
"""The runner asked the turn to stop (SIGTERM). A BaseException so no `except Exception`
on the way out swallows it."""
class ApiError(Exception):
"""Qoder answered with an error: the status and the envelope's type and message. Status 0 is
the driver's own verdict on an answer it could not use (no id where one was due)."""
def __init__(self, status: int, kind: str, message: str, path: str = ""):
super().__init__(f"{status} {kind}: {message}")
self.status, self.kind, self.message, self.path = status, kind, message, path
class NetError(Exception):
"""Nothing answered: the connection was refused, dropped, or timed out."""
class LinkRefused(Exception):
"""The storage host refused a presigned download link; a lapsed one is refused there (403 on
most stores), and the rule is that a fresh link is asked for, never that the file is gone."""
# ── the SDK ─────────────────────────────────────────────────────────────────────────────────────
def _plain(obj):
"""A pydantic model (or a list of them) as JSON-compatible dicts, extras included; anything
else as it is. The handlers below read dicts, as they did off the wire."""
if isinstance(obj, list):
return [_plain(x) for x in obj]
dump = getattr(obj, "model_dump", None)
return dump(mode="json", exclude_none=True) if callable(dump) else obj
class Client:
"""The Managed API through the relay, on Qoder's SDK: `base` is the relay's address, `token`
a placeholder. Every method answers plain dicts and raises ApiError / NetError, so the turn's
logic reads one shape whatever the SDK's models and exceptions are called."""
def __init__(self, base: str, token: str):
import httpx # noqa: PLC0415 — the SDK's own dependency, present wherever the SDK is
from qca.managed import Managed # noqa: PLC0415 — installed in the backend's venv, not the runner's
import qca # noqa: PLC0415
self._x = qca
self._httpx = httpx
self.base = base.rstrip("/") + "/"
self.m = Managed(pat=token, base_url=self.base, timeout=httpx.Timeout(CALL_TIMEOUT_S), max_retries=2)
# one place turns the SDK's exceptions into the driver's two
def _call(self, path: str, fn, *a, **kw):
x = self._x
try:
return _plain(fn(*a, **kw))
except x.APIStatusError as e:
body = e.body if isinstance(e.body, dict) else {}
err = body.get("error") if isinstance(body.get("error"), dict) else {}
kind = str(err.get("type") or body.get("code") or "")
msg = str(err.get("message") or body.get("message") or str(e))[:300]
raise ApiError(int(e.status_code), kind, msg, path) from None
except x.APIConnectionError as e: # APITimeoutError is one of these
raise NetError(f"{type(e).__name__}: {e}"[:300]) from None
except x.APIResponseValidationError as e:
raise ApiError(0, "api_error", f"an answer the SDK could not read: {e}"[:300], path) from None
# environments
def environment_create(self, body: dict) -> dict:
return self._call("/environments", self.m.environments.create, **body)
def environment_delete(self, eid: str) -> dict:
return self._call(f"/environments/{eid}", self.m.environments.delete, eid)
def environment_archive(self, eid: str) -> dict:
return self._call(f"/environments/{eid}/archive", self.m.environments.archive, eid)
# vaults
def vault_create(self, display_name: str, metadata: dict) -> dict:
return self._call("/vaults", self.m.vaults.create, display_name=display_name, metadata=metadata)
def vault_delete(self, vid: str) -> dict:
return self._call(f"/vaults/{vid}", self.m.vaults.delete, vid)
def credential_create(self, vid: str, auth: dict) -> dict:
return self._call(f"/vaults/{vid}/credentials", self.m.vaults.credentials.create, vid, auth=auth)
def credentials_list(self, vid: str) -> list[dict]:
page = self._call(f"/vaults/{vid}/credentials", self.m.vaults.credentials.list, vid)
return list((page or {}).get("data") or [])
def credential_archive(self, vid: str, cid: str) -> dict:
return self._call(f"/vaults/{vid}/credentials/{cid}/archive", self.m.vaults.credentials.archive, cid, vault_id=vid)
# agents
def agent_create(self, body: dict) -> dict:
return self._call("/agents", self.m.agents.create, **body)
def agent_retrieve(self, aid: str) -> dict:
return self._call(f"/agents/{aid}", self.m.agents.retrieve, aid)
def agent_update(self, aid: str, body: dict, version: int) -> dict:
return self._call(f"/agents/{aid}", self.m.agents.update, aid, version=version, **body)
def agent_archive(self, aid: str) -> dict:
return self._call(f"/agents/{aid}/archive", self.m.agents.archive, aid)
# sessions
def session_create(self, body: dict) -> dict:
return self._call("/sessions", self.m.sessions.create, **body)
def session_retrieve(self, sid: str) -> dict:
return self._call(f"/sessions/{sid}", self.m.sessions.retrieve, sid)
def session_update(self, sid: str, body: dict) -> dict:
return self._call(f"/sessions/{sid}", self.m.sessions.update, sid, **body)
def session_cancel(self, sid: str) -> dict:
return self._call(f"/sessions/{sid}/cancel", self.m.sessions.cancel, sid,
timeout=self._httpx.Timeout(20.0))
def session_delete(self, sid: str) -> dict:
return self._call(f"/sessions/{sid}", self.m.sessions.delete, sid)
def resource_add(self, sid: str, file_id: str, mount_path: str) -> dict:
return self._call(f"/sessions/{sid}/resources", self.m.sessions.resources.add, sid,
type="file", file_id=file_id, mount_path=mount_path)
def events_send(self, sid: str, events: list[dict], idempotency_key: str = "") -> list[dict]:
hdrs = {"Idempotency-Key": idempotency_key} if idempotency_key else None
doc = self._call(f"/sessions/{sid}/events", self.m.sessions.events.send, sid, events=events,
extra_headers=hdrs)
return list((doc or {}).get("data") or [])
def events_list(self, sid: str, **query) -> dict:
return self._call(f"/sessions/{sid}/events", self.m.sessions.events.list, sid, **query) or {}
def events_stream(self, sid: str, last_event_id: str = ""):
"""An open SDK Stream of SessionStreamEvent, deltas of agent.message requested; the caller
iterates it and reads `.last_event_id` after each event for the cursor."""
x = self._x
try:
return self.m.sessions.events.stream(
sid, event_deltas=["agent.message"], last_event_id=last_event_id or None,
timeout=self._httpx.Timeout(CALL_TIMEOUT_S, read=STREAM_READ_TIMEOUT_S))
except x.APIStatusError as e:
body = e.body if isinstance(e.body, dict) else {}
err = body.get("error") if isinstance(body.get("error"), dict) else {}
raise ApiError(int(e.status_code), str(err.get("type") or ""), str(err.get("message") or e)[:300],
f"/sessions/{sid}/events/stream") from None
except x.APIConnectionError as e:
raise NetError(f"{type(e).__name__}: {e}"[:300]) from None
def stream_errors(self) -> tuple:
"""What a read off an open stream raises when the connection goes (the caller reconnects)."""
x = self._x
return (x.APIConnectionError, x.APITimeoutError)
def stream_error_frame(self) -> type:
"""What a read raises when the stream carries an `error` frame of its own."""
return self._x.APIError
# files
def file_upload(self, name: str, data: bytes, ctype: str) -> dict:
return self._call("/files", self.m.files.upload, file=(name, data, ctype), name=name)
def file_download(self, fid: str):
"""An open binary download of the file's bytes (the SDK fetched the presigned link and
refused one that is not http(s)); iterate `.iter_bytes()`, then `.close()`."""
x = self._x
try:
return self.m.files.download(fid)
except x.APIStatusError as e:
if "authorization" not in e.request.headers:
# The SDK makes two requests here and raises the same class for both. The storage
# request is the one that carries no credential (the presigned link is the
# authority), so a refusal there is the link's, not the file's.
raise LinkRefused(f"the storage host refused the download link ({e.status_code})") from None
body = e.body if isinstance(e.body, dict) else {}
err = body.get("error") if isinstance(body.get("error"), dict) else {}
raise ApiError(int(e.status_code), str(err.get("type") or ""), str(err.get("message") or e)[:300],
f"/files/{fid}/content") from None
except x.APIConnectionError as e:
raise NetError(f"{type(e).__name__}: {e}"[:300]) from None
except x.APIResponseValidationError as e:
raise ApiError(0, "api_error", "the download link is not a web address", f"/files/{fid}/content") from e
def file_delete(self, fid: str) -> dict:
return self._call(f"/files/{fid}", self.m.files.delete, fid)
# skills
def skill_create(self, files: list[tuple[str, bytes, str]]) -> dict:
return self._call("/skills", self.m.skills.create, files=files)
def skill_version_create(self, skill_id: str, files: list[tuple[str, bytes, str]]) -> dict:
return self._call(f"/skills/{skill_id}/versions", self.m.skills.versions.create, skill_id, files=files)
def skill_delete(self, skill_id: str) -> dict:
return self._call(f"/skills/{skill_id}", self.m.skills.delete, skill_id)
# ── state ────────────────────────────────────────────────────────────────────────────────────────
def state_path(cwd: str) -> pathlib.Path:
return pathlib.Path(cwd) / STATE_REL
def load_state(cwd: str) -> dict:
try:
doc = json.loads(state_path(cwd).read_text())
return doc if isinstance(doc, dict) else {}
except (OSError, ValueError):
return {}
def save_state(cwd: str, st: dict) -> None:
p = state_path(cwd)
p.parent.mkdir(parents=True, exist_ok=True)
tmp = p.with_suffix(".json.tmp")
tmp.write_text(json.dumps(st, indent=1, sort_keys=True))
os.replace(tmp, p)
def _sha(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
# ── artifacts ────────────────────────────────────────────────────────────────────────────────────
def artifact_name(original: str) -> tuple[str, str]:
"""(the plain name to write under the workspace root, "") or ("", why it was refused).
`original_filename` comes from the remote run, and in the end from the model: a name is
input. Only a plain file name lands: no path separator of either kind, no `..`, nothing that
opens a dot directory the runner owns, no control characters, and nothing that is only dots
or whitespace."""
name = (original or "").strip()
if not name:
return "", "empty artifact name"
if "/" in name or "\\" in name or "\0" in name:
return "", f"artifact name carries a path: {original!r}"
if name in (".", "..") or name.startswith(".."):
return "", f"artifact name is a traversal: {original!r}"
if any(ord(c) < 32 for c in name):
return "", f"artifact name carries control characters: {original!r}"
if name.startswith("."):
# .harness, .git and the CLI homes live here, and a hidden file is never a deliverable
return "", f"artifact name opens a dot directory or hidden file: {original!r}"
if len(name.encode("utf-8")) > 240:
# a file name is at most 255 BYTES; cut by bytes, keeping the extension and room for " (n)"
stem, ext = os.path.splitext(name)
ext = ext if len(ext.encode("utf-8")) <= 16 else ""
name = stem.encode("utf-8")[:240 - len(ext.encode("utf-8"))].decode("utf-8", "ignore").rstrip() + ext
return name, ""
def land_artifact(cwd: str, name: str, data: bytes | pathlib.Path,
replaceable: frozenset[str] | set[str] = frozenset()) -> tuple[str, str]:
"""Write `data` as `name` under the workspace root; (the relative path written, a note).
A path in `replaceable` (a file THIS session's deliveries wrote: the deliverable's earlier
version) is replaced, atomically, the way a revised file is on every other base: on 0.33.0-rc.19
a conversation revising one PDF over five turns left hi.pdf, "hi (2).pdf", "hi (3).pdf"…, the
newest under a name the person never chose. Any OTHER existing path is never overwritten (a file
the person attached, or one this session did not deliver) and a symlink is never followed: it
lands beside it as `name (2).ext`, and the note says so."""
root = pathlib.Path(cwd)
stem, ext = os.path.splitext(name)
if name in replaceable and (root / name).is_file() and not (root / name).is_symlink():
tmp = root / f".{name}.{uuid.uuid4().hex}.landing"
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
with os.fdopen(fd, "wb") as f:
if isinstance(data, (bytes, bytearray)):
f.write(data)
else:
with open(data, "rb") as src:
shutil.copyfileobj(src, f, 1 << 20)
os.replace(tmp, root / name)
return name, ""
candidate, n, note = name, 1, ""
while True:
target = root / candidate
if target.is_symlink():
n += 1
candidate = f"{stem} ({n}){ext}"
note = f"{name!r} was a symlink; written as {candidate!r}"
continue
try:
fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
except FileExistsError:
n += 1
candidate = f"{stem} ({n}){ext}"
note = f"{name!r} already existed; written as {candidate!r}"
continue
with os.fdopen(fd, "wb") as f:
if isinstance(data, (bytes, bytearray)):
f.write(data)
else: # a download already on disk (see Turn.artifact)
with open(data, "rb") as src:
shutil.copyfileobj(src, f, 1 << 20)
return candidate, note
# ── the Agent definition ────────────────────────────────────────────────────────────────────────
def tools_config(disabled: list[str]) -> list[dict]:
"""The toolset entry: the enabled built-ins as a strict whitelist, each `always_allow` so no
call ever pauses for a confirmation nobody is here to give, and the disabled ones named in
`disallowed_tools` as well. Both lists, because an EMPTY `enabled_tools` means "the default
set" to Qoder, not "nothing"."""
off = {t for t in (disabled or []) if t in TOOLS}
on = [t for t in TOOLS if t not in off]
entry: dict = {"type": TOOLSET,
"configs": [{"name": t, "enabled": True, "permission_policy": {"type": "always_allow"}}
for t in on]}
if on:
entry["enabled_tools"] = on
if off:
entry["disallowed_tools"] = sorted(off)
entry["configs"] += [{"name": t, "enabled": False} for t in sorted(off)]
return [entry]
def mcp_config(servers: list[dict]) -> tuple[list[dict], list[dict], list[dict]]:
"""(mcp_servers for the Agent, the servers whose bearer needs a Vault credential, the ones this
backend cannot offer). Only a Streamable HTTP URL reaches Qoder; a plugin's stdio server is a
process on this box, which Qoder's cloud cannot dial. A header other than a bearer has no
home in a Vault credential either."""
out, creds, dropped = [], [], []
seen: set[str] = set()
for i, s in enumerate(servers or []):
if not isinstance(s, dict):
continue
raw_name = str(s.get("name") or s.get("id") or f"mcp{i}")
name = re.sub(r"[^A-Za-z0-9_-]+", "-", raw_name).strip("-") or f"mcp{i}"
url = str(s.get("url") or "").strip()
if not url:
dropped.append({"name": raw_name, "reason": "stdio server: a process on the runner's box"})
continue
if name in seen:
name = f"{name}-{i}"
seen.add(name)
out.append({"name": name, "type": "url", "url": url})
auth = s.get("auth")
hdrs = s.get("headers") if isinstance(s.get("headers"), dict) else {}
bearer = ""
if auth:
bearer = str(auth)
for k, v in hdrs.items():
if str(k).lower() == "authorization" and v:
bearer = str(v)
elif v:
dropped.append({"name": raw_name, "reason": f"header {k} cannot travel: Qoder takes a bearer in a Vault only"})
if bearer:
if bearer.lower().startswith("bearer "):
bearer = bearer[7:].strip()
creds.append({"url": url, "token": bearer})
return out, creds, dropped
def agent_body(job: dict, skills: list[dict], mcp_servers: list[dict]) -> dict:
model: str | dict = str(job.get("model") or "ultimate")
effort = str(job.get("effort") or "").strip().lower()
if effort and effort in EFFORTS:
model = {"id": model, "effort": effort}
# The model reads the agent's name as its own: named "harnessrouter <session dir>", qfmodel
# opened a turn with "Hi! I'm harnessrouter hsess2b3b804c…" (0.33.0-rc.19). It is the base's
# name; the session is identified by the metadata, and the environment and vault keep theirs.
return {"name": "Qoder", "model": model,
"description": "Created by HarnessRouter for one session; deleted with it.",
"system": system_prompt(job),
"tools": tools_config(job.get("tools_disabled") or []),
"mcp_servers": mcp_servers,
"skills": [{"type": "custom", "skill_id": s["id"], "version": s["version"]} for s in skills],
"metadata": {"harnessrouter": "1"}}
def system_prompt(job: dict) -> str:
"""The harness's instructions, then the contract this runtime has instead of a workspace: a
file reaches the person only when it is delivered. A file written in Qoder's sandbox and never
passed to DeliverArtifacts does not exist to the user, and the artifact scenario measures it."""
base = str(job.get("agent_doc") or "").strip()
lines = ["## Delivering files", "",
"You run in a remote sandbox. The user sees NO file you write unless you deliver it: when "
"a task produces a deliverable (a document, a deck, code, an export), save it and then call "
"DeliverArtifacts with its path. Deliver each file once, by a plain file name; an "
"undelivered file is lost to the user.",
"", f"Files the user attaches are mounted read-only under `{MOUNT_ROOT}/`; each message "
"names the ones it brought."]
block = "\n".join(lines)
return (base + "\n\n" + block) if base else block
def config_hash(body: dict) -> str:
return _sha(json.dumps(body, sort_keys=True).encode())
# ── skills ───────────────────────────────────────────────────────────────────────────────────────
def skill_tree(folder: str) -> tuple[str, list[tuple[str, bytes]], str]:
"""(the frontmatter name, [(relative path, bytes)], "") for a skill folder, or ("", [], why).
Qoder requires the package's single top-level directory to equal SKILL.md's `name`, which
must match ^[a-z0-9][a-z0-9_-]*$ — a bundle whose name does not cannot be published."""
root = pathlib.Path(folder)
manifest = root / "SKILL.md"
if not manifest.is_file():
return "", [], f"{root.name}: no SKILL.md"
name = ""
try:
head = manifest.read_text(encoding="utf-8", errors="replace")
except OSError as e:
return "", [], f"{root.name}: {e}"
if head.startswith("---"):
for ln in head.split("\n")[1:60]:
if ln.strip() == "---":
break
if ln.startswith("name:"):
name = ln.split(":", 1)[1].strip().strip("'\"")
if not name or not _SKILL_NAME_RE.match(name) or len(name) > 64:
return "", [], f"{root.name}: SKILL.md name {name!r} is not a Qoder skill name"
files: list[tuple[str, bytes]] = []
total = 0
for p in sorted(root.rglob("*")):
if p.is_file() and not p.is_symlink():
data = p.read_bytes()
total += len(data)
files.append((f"{name}/{p.relative_to(root).as_posix()}", data))
if total > 50 * 1024 * 1024:
return "", [], f"{root.name}: {total} bytes, over the 50 MB package limit"
return name, files, ""
def publish_skills(api: Client, st: dict, skills: list[dict], notes: list[str]) -> list[dict]:
"""Each harness skill bundle as a Qoder custom Skill (a new version when its bytes changed),
reused across the session's turns by content hash; → the bindings for the Agent. The package
goes as a bare file tree, each part's filename its path under the skill's directory."""
known: dict = st.setdefault("skills", {})
out: list[dict] = []
for s in skills or []:
folder = str((s or {}).get("dir") or "")
name, files, why = skill_tree(folder)
if why:
notes.append(f"skill not published: {why}")
continue
digest = _sha(b"".join(_sha(d).encode() + p.encode() for p, d in files))
rec = known.get(name) or {}
if rec.get("id") and rec.get("sha") == digest and rec.get("version"):
out.append({"id": rec["id"], "version": rec["version"]})
continue
parts = [(path, data, mimetypes.guess_type(path)[0] or "application/octet-stream") for path, data in files]
if rec.get("id"):
ver = api.skill_version_create(rec["id"], parts)
version = str((ver or {}).get("version") or "")
else:
created = api.skill_create(parts)
rec = {"id": str((created or {}).get("id") or "")}
version = str((created or {}).get("latest_version") or "")
if not rec.get("id") or not version:
notes.append(f"skill {name}: Qoder returned no id/version")
continue
rec.update(sha=digest, version=version)
known[name] = rec
out.append({"id": rec["id"], "version": version})
return out
# ── input files ──────────────────────────────────────────────────────────────────────────────────
def upload_ok(rel: str, size: int) -> str:
""""" when the upload endpoint takes this file, else why not."""
base = os.path.basename(rel)
ext = os.path.splitext(base)[1].lower()
mime = (mimetypes.guess_type(base)[0] or "").lower()
if size > UPLOAD_MAX_BYTES:
return f"{rel}: {size} bytes, over Qoder's 5 MB upload limit"
if ext in UPLOAD_EXT or base.lower() in UPLOAD_BARE or mime.startswith(UPLOAD_MIME_PREFIX) or mime in UPLOAD_MIME:
return ""
return f"{rel}: Qoder accepts text-type input files only (binary, image and archive files are refused)"
def upload_inputs(api: Client, st: dict, cwd: str, rels: list[str]) -> list[dict]:
"""Upload the runner's staged input files once each (by content hash); → the file resources
to mount, with the mount path the model is told."""
known: dict = st.setdefault("files", {})
out: list[dict] = []
for rel in rels or []:
p = pathlib.Path(cwd) / rel
try:
data = p.read_bytes()
except OSError:
continue
digest = _sha(data)
rec = known.get(rel) or {}
if not (rec.get("id") and rec.get("sha") == digest):
created = api.file_upload(os.path.basename(rel), data, mimetypes.guess_type(rel)[0] or "text/plain")
rec = {"id": str((created or {}).get("id") or ""), "sha": digest, "mounted": []}
known[rel] = rec
mount = f"{MOUNT_ROOT}/{rel.lstrip('/')}"
out.append({"type": "file", "file_id": rec["id"], "mount_path": mount, "_rel": rel})
return out
# ── the turn ─────────────────────────────────────────────────────────────────────────────────────
class Turn:
def __init__(self, job: dict):
self.job = job
self.cwd = str(job.get("cwd") or os.getcwd())
self.api = Client(str(job.get("base_url") or ""), str(job.get("api_key") or ""))
self.st = load_state(self.cwd)
self.notes: list[str] = []
self.session_id = ""
self.final = ""
self.streamed: dict[str, str] = {} # delta text already emitted, by event id
self.declared: list[dict] = [] # artifacts the stream announced
self.landed: list[dict] = []
self.artifact_failures: list[str] = []
self.usage: dict | None = None
self.error: dict | None = None
self.stop_reason: dict | None = None
self.terminated = False
self.last_event_id = ""
self.pending_confirm: list[str] = []
self.deny_ids: set[str] = set() # pending confirmations of tools the harness disabled
self.replaying: dict[str, int] = {} # a reconnect is replaying deltas of this message: bytes seen
self.disabled = {str(t) for t in (job.get("tools_disabled") or [])}
self.mounts: list[str] = [] # where this turn's attached files are mounted
self.written: list[str] = [] # paths the agent wrote or edited this turn
self.delivered_paths: set[str] = set() # paths it passed to DeliverArtifacts
self.nudging = False # the delivery round (deliver_written) is running
# ── remote objects ──
def ensure_environment(self) -> str:
env_id = str(self.st.get("environment_id") or "")
if env_id:
return env_id
created = self.api.environment_create({
"name": f"harnessrouter {pathlib.Path(self.cwd).name}"[:256],
"description": "Created by HarnessRouter for one session; deleted with it.",
"config": {"type": "cloud"}, "metadata": {"harnessrouter": "1"}})
env_id = str((created or {}).get("id") or "")
if not env_id:
raise ApiError(0, "api_error", "environment create returned no id", "/environments")
self.st["environment_id"] = env_id
save_state(self.cwd, self.st)
return env_id
def ensure_vault(self, creds: list[dict]) -> list[str]:
"""The session's Vault, holding one active static_bearer credential per MCP server URL with
THIS turn's token. A server URL is unique among a vault's active credentials, so a token that
changed since the last turn (a rotated key, or the per-turn credential the gateway mints for
a server it hosts itself, which expires) archives the old credential and creates the new one:
a vault that kept the first turn's token fails that server on every later turn. Only a hash
of each token is kept in the state, never the token."""
if not creds:
return [self.st["vault_id"]] if self.st.get("vault_id") else []
vid = str(self.st.get("vault_id") or "")
if not vid:
created = self.api.vault_create(f"harnessrouter {pathlib.Path(self.cwd).name}"[:255], {"harnessrouter": "1"})
vid = str((created or {}).get("id") or "")
if not vid:
raise ApiError(0, "api_error", "vault create returned no id", "/vaults")
self.st["vault_id"] = vid
save_state(self.cwd, self.st)
have: dict = self.st.setdefault("vault_creds", {}) # url -> {"id", "sha"}
for c in creds:
sha = _sha(c["token"].encode())
cur = have.get(c["url"]) or {}
if cur.get("id") and cur.get("sha") == sha:
continue
if cur.get("id"):
self._archive_credential(vid, cur["id"])
have[c["url"]] = {"id": self._create_credential(vid, c), "sha": sha}
save_state(self.cwd, self.st)
return [vid]
def _create_credential(self, vid: str, c: dict) -> str:
auth = {"type": "static_bearer", "mcp_server_url": c["url"], "token": c["token"]}
try:
doc = self.api.credential_create(vid, auth)
except ApiError as e:
if e.status != 409:
raise
# an active credential for this URL that the state does not know: archived, then made anew
for old in self._active_credentials(vid, c["url"]):
self._archive_credential(vid, old)
doc = self.api.credential_create(vid, auth)
cid = str((doc or {}).get("id") or "")
if not cid:
raise ApiError(0, "api_error", "credential create returned no id", f"/vaults/{vid}/credentials")
return cid
def _active_credentials(self, vid: str, url: str) -> list[str]:
out = []
for x in self.api.credentials_list(vid):
if not isinstance(x, dict) or not x.get("id") or x.get("archived_at"):
continue
if url in (x.get("mcp_server_url"), (x.get("auth") or {}).get("mcp_server_url")):
out.append(str(x["id"]))
return out
def _archive_credential(self, vid: str, cid: str) -> None:
try:
self.api.credential_archive(vid, cid)
except ApiError as e:
if e.status not in (404, 409): # gone, or archived already
raise
def ensure_agent(self, body: dict) -> tuple[str, int, bool]:
"""(agent id, version, whether the configuration changed this turn)."""
digest = config_hash(body)
aid = str(self.st.get("agent_id") or "")
if aid and self.st.get("agent_hash") == digest and self.st.get("agent_version"):
return aid, int(self.st["agent_version"]), False
if aid:
current = self.api.agent_retrieve(aid)
version = int((current or {}).get("version") or 1)
updated = self.api.agent_update(aid, body, version)
else:
updated = self.api.agent_create(body)
aid = str((updated or {}).get("id") or "")
version = int((updated or {}).get("version") or 1)
if not aid:
raise ApiError(0, "api_error", "agent create returned no id", "/agents")
self.st.update(agent_id=aid, agent_version=version, agent_hash=digest)
save_state(self.cwd, self.st)
return aid, version, True
def find_session(self, resume: str) -> tuple[str, bool]:
"""(the session to continue, False) or ("", lost): the id the caller named, when the state
knows it and Qoder still has it in a state that takes a message."""
if not resume:
return "", False
if resume != str(self.st.get("session_id") or ""):
return "", True
try:
doc = self.api.session_retrieve(resume)
except ApiError as e:
if e.status == 404:
return "", True
raise
if not isinstance(doc, dict) or doc.get("archived_at") or doc.get("status") == "terminated":
return "", True
if doc.get("status") in ("running", "rescheduling"):
raise ApiError(409, "invalid_request_error",
"the Qoder session is still processing an earlier turn; cancel it or wait",
f"/sessions/{resume}")
return resume, False
def create_session(self, aid: str, version: int, env_id: str, vault_ids: list[str],
resources: list[dict]) -> str:
body: dict = {"agent": {"id": aid, "type": "agent", "version": version},
"environment_id": env_id,
"title": f"HarnessRouter {pathlib.Path(self.cwd).name}"[:200],
"metadata": {"harnessrouter": "1"}}
if vault_ids:
body["vault_ids"] = vault_ids
if resources:
body["resources"] = [{k: v for k, v in r.items() if not k.startswith("_")} for r in resources]
doc = self.api.session_create(body)
sid = str((doc or {}).get("id") or "")
if not sid:
raise ApiError(0, "api_error", "session create returned no id", "/sessions")
self.st["session_id"] = sid
self.st.setdefault("sessions", [])
if sid not in self.st["sessions"]:
self.st["sessions"].append(sid)
for r in resources:
self.st["files"][r["_rel"]].setdefault("mounted", []).append(sid)
save_state(self.cwd, self.st)
return sid
def mount_resources(self, sid: str, resources: list[dict]) -> None:
for r in resources:
rec = self.st["files"][r["_rel"]]
if sid in (rec.get("mounted") or []):
continue
try:
self.api.resource_add(sid, r["file_id"], r["mount_path"])
except ApiError as e:
if e.status != 409:
raise
rec.setdefault("mounted", []).append(sid)
save_state(self.cwd, self.st)
# ── the stream ──
def handle(self, eid: str, doc: dict, posted_id: str, started: list[bool]) -> bool:
"""One stream event, as the SDK decoded it; True when the turn is over."""
if not isinstance(doc, dict):
return False
t = str(doc.get("type") or "")
if t == "heartbeat":
return False
if eid and t not in ("event_start", "event_delta"):
self.last_event_id = eid
if not started[0]:
# events before this turn's message are history, not this turn
if (t == "user.message" and doc.get("id") == posted_id) or t == "session.status_running":
started[0] = True
return False
if t == "event_start":
e = doc.get("event") or {}
if e.get("type") == "agent.message" and e.get("id"):
mid = str(e["id"])
if mid in self.streamed:
# a reconnect replays the message's start and its retained deltas: what was
# already written is not written twice
self.replaying[mid] = 0
else:
self.streamed[mid] = ""
return False
if t == "event_delta":
if self.nudging:
return False # the delivery round's own words are not the turn's answer
d = doc.get("delta") or {}
c = d.get("content") or {}
txt = str(c.get("text") or "") if c.get("type") == "text" else ""
mid = str(doc.get("event_id") or "")
if not txt or not mid:
return False
if mid in self.replaying:
pos, have = self.replaying[mid], len(self.streamed.get(mid, ""))
if pos + len(txt) <= have:
self.replaying[mid] = pos + len(txt)
return False
txt = txt[max(0, have - pos):]
del self.replaying[mid]
self.streamed[mid] = self.streamed.get(mid, "") + txt
_emit("text", {"text": txt})
return False
if t == "agent.message":
full = "".join(str(c.get("text") or "") for c in (doc.get("content") or [])
if isinstance(c, dict) and c.get("type") == "text")
seen = self.streamed.pop(str(doc.get("id") or ""), "")
if self.nudging:
return False
if full:
self.final = full
if full and full != seen:
if not seen:
_emit("text", {"text": full})
elif full.startswith(seen):
_emit("text", {"text": full[len(seen):]})
return False
if t == "agent.thinking":
return False # the content is not public; the event is only a marker
if t in ("agent.tool_use", "agent.mcp_tool_use", "agent.custom_tool_use"):
name = str(doc.get("name") or "tool")
if t == "agent.mcp_tool_use" and doc.get("mcp_server_name"):
name = f"mcp__{doc['mcp_server_name']}__{name}"
inp = doc.get("input") if isinstance(doc.get("input"), dict) else {}
_emit("tool_use", {"id": str(doc.get("id") or ""), "name": name, "input": inp,
"permission": doc.get("evaluated_permission")})
if t == "agent.tool_use" and name in ("Write", "Edit") and inp.get("file_path"):
if str(inp["file_path"]) not in self.written:
self.written.append(str(inp["file_path"]))
if t == "agent.tool_use" and name == "DeliverArtifacts":
for f in inp.get("files") or []:
if isinstance(f, dict) and f.get("path"):
self.delivered_paths.add(str(f["path"]))
if doc.get("evaluated_permission") == "ask" and doc.get("id"):
self.pending_confirm.append(str(doc["id"]))
bare = str(doc.get("name") or "")
if name in self.disabled or bare in self.disabled:
self.deny_ids.add(str(doc["id"]))
return False
if t in ("agent.tool_result", "agent.mcp_tool_result"):
text = "\n".join(str(c.get("text") or "") for c in (doc.get("content") or [])
if isinstance(c, dict) and c.get("type") == "text")
_emit("tool_result", {"tool_use_id": str(doc.get("tool_use_id") or doc.get("mcp_tool_use_id") or ""),
"text": text, "is_error": bool(doc.get("is_error"))})
return False
if t == "agent.artifact_delivered":
self.artifact(doc)
return False
if t == "session.usage":
self.usage = {k: doc.get(k) for k in ("model_credits", "sandbox_runtime_credits", "total_credits")}
return False
if t == "session.error":
err = doc.get("error") if isinstance(doc.get("error"), dict) else {}
retry = str(((err.get("retry_status") or {}).get("type")) or "")
self.error = {"message": str(err.get("message") or "Qoder reported an error"),
"type": str(err.get("type") or ""), "retry": retry}
_emit("error", self.error)
return False
if t == "session.status_rescheduled":
_emit("notice", {"text": "Qoder is retrying the model request (rescheduling)"})
return False
if t == "session.status_idle":
self.stop_reason = doc.get("stop_reason") if isinstance(doc.get("stop_reason"), dict) else {"type": ""}
if self.stop_reason.get("type") == "requires_action":
self.confirm(list(self.stop_reason.get("event_ids") or []) or self.pending_confirm)
self.pending_confirm = []
self.stop_reason = None # the turn goes on; its real stop is still to come
return False
return True
if t in ("session.status_terminated", "session.deleted"):
self.terminated = True
return True
return False
def confirm(self, event_ids: list[str]) -> None:
"""Answer every pending tool confirmation: deny a tool the harness disabled, allow the rest.
The Agent's permission policy makes this path rare (always_allow on every built-in); an MCP
tool whose server-side default asks still gets its answer here instead of parking the
session, which never times out on its own."""
events = []
for eid in event_ids:
deny = eid in self.deny_ids
ev: dict = {"type": "user.tool_confirmation", "tool_use_id": eid, "result": "deny" if deny else "allow"}
if deny:
ev["deny_message"] = "This tool is disabled for this harness."
events.append(ev)
if events:
self.api.events_send(self.session_id, events, idempotency_key=uuid.uuid4().hex)
def artifact(self, doc: dict) -> None:
fid = str(doc.get("file_id") or "")
original = str(doc.get("original_filename") or "")
size = doc.get("size")
rec = {"file_id": fid, "name": original, "size": size}
self.declared.append(rec)
self.st.setdefault("artifacts", [])
if fid and fid not in self.st["artifacts"]:
self.st["artifacts"].append(fid)
save_state(self.cwd, self.st)
name, why = artifact_name(original)
if not why and isinstance(size, int) and size > ARTIFACT_MAX_BYTES:
why = f"{original}: {size} bytes declared, over the {ARTIFACT_MAX_BYTES}-byte artifact limit"
if why:
self.artifact_failures.append(why)
_emit("artifact", {**rec, "status": "refused", "reason": why})
return
# The download goes to disk as it arrives, under .harness/ (never a produced file), and is
# landed from there; nothing about one artifact (a full disk, a name the filesystem will not
# take) is let out of here, where it would read as a dropped stream and lose its reason.
part = pathlib.Path(self.cwd) / ".harness" / "qoder" / f"download-{uuid.uuid4().hex}.part"
try:
got, why = self._download(fid, original, part)
if got is not None and isinstance(size, int) and size >= 0 and got != size:
why, got = f"{original}: {got} bytes landed, {size} declared", None
if got is None:
self.artifact_failures.append(why or f"{original}: download failed")
_emit("artifact", {**rec, "status": "failed", "reason": why})
return
try:
written, note = land_artifact(self.cwd, name, part, frozenset(self.st.get("delivered") or []))
except OSError as e:
why = f"{original}: could not be written: {type(e).__name__}: {e}"[:300]
self.artifact_failures.append(why)
_emit("artifact", {**rec, "status": "failed", "reason": why})
return
finally:
try:
part.unlink()
except OSError:
pass
if note:
self.notes.append(note)
if written not in (self.st.get("delivered") or []):
self.st.setdefault("delivered", []).append(written)
save_state(self.cwd, self.st)
self.landed.append({**rec, "path": written})
_emit("artifact", {**rec, "status": "landed", "path": written})
def _download(self, fid: str, original: str, part: pathlib.Path) -> tuple[int | None, str]:
"""(bytes written to `part`, "") or (None, why). The SDK asks for the presigned link and
follows it (refusing one that is not http(s)); the link is asked for again once if the
first fails (its lifetime is not documented); a refused file is not retried."""
why = ""
for _attempt in (0, 1):
try:
part.parent.mkdir(parents=True, exist_ok=True)
n = 0
resp = self.api.file_download(fid)
try:
with open(part, "wb") as out:
for chunk in resp.iter_bytes(1 << 20):
n += len(chunk)
if n > ARTIFACT_MAX_BYTES:
return None, f"{original}: over the {ARTIFACT_MAX_BYTES}-byte artifact limit"
out.write(chunk)
finally:
resp.close()
return n, ""
except ApiError as e:
why = f"{original}: {e}"
if e.status in (0, 404, 410, 403):
break
except (NetError, LinkRefused, OSError) as e:
why = f"{original}: download failed: {type(e).__name__}: {e}"[:300]
except Exception as e: # noqa: BLE001 — the storage host dropped mid-body (httpx's own errors)
why = f"{original}: download failed: {type(e).__name__}: {e}"[:300]
return None, why
def run_stream(self, posted_id: str) -> None:
"""Read the session's stream until this turn ends, reconnecting from the last event id on
a drop; the message is never sent again.
The stream is opened AFTER the message is posted, with the message's own event id as the
cursor: the server replays from there, so nothing of this turn is missed however long the
open took, and nothing of an earlier turn is read as this one's."""
started = [bool(posted_id)]
self.last_event_id = posted_id
attempts = 0
idle_eofs = 0
dropped = self.api.stream_errors()
error_frame = self.api.stream_error_frame()
while True:
try:
stream = self.api.events_stream(self.session_id, self.last_event_id)
except ApiError as e:
if e.status in (400, 404) and self.last_event_id:
self.last_event_id = "" # the cursor is gone; start from now
attempts += 1
if attempts <= STREAM_RECONNECTS:
continue
raise
except NetError as e:
attempts += 1
if attempts > STREAM_RECONNECTS:
raise ApiError(0, "stream", f"the event stream could not be opened: {e}"[:300])
time.sleep(min(2.0 * attempts, 15.0))
continue
try:
for ev in stream:
eid = str(stream.last_event_id or "")
if self.handle(eid, _plain(ev), posted_id, started):
return
except dropped as e:
attempts += 1
_emit("notice", {"text": f"event stream dropped ({type(e).__name__}); resuming from {self.last_event_id or 'now'}"})
if attempts > STREAM_RECONNECTS:
raise ApiError(0, "stream", f"the event stream kept dropping: {e}"[:300])
time.sleep(min(2.0 * attempts, 15.0))
continue
except error_frame as e:
# the stream itself said `error`: Qoder's own word, and the turn's reason
raise ApiError(0, "stream", str(e)[:300], f"/sessions/{self.session_id}/events/stream") from None
finally:
try:
stream.close()
except Exception: # noqa: BLE001
pass
# EOF without a terminal event: the server closed the stream. Where the session stands
# decides: terminated ends the turn; running (or a turn resumed after a confirmation)
# means reconnect from the cursor; idle twice in a row with no idle event seen means
# the event was lost on the wire and the turn is over.
doc = self.api.session_retrieve(self.session_id)
status = str((doc or {}).get("status") or "")
if status == "terminated":
self.terminated = True
return
if status == "idle" and started[0]:
idle_eofs += 1
if idle_eofs >= 2:
if (self.stop_reason or {}).get("type") != "requires_action":
self.stop_reason = self.stop_reason or {"type": "end_turn"}
return
attempts += 1
if attempts > STREAM_RECONNECTS:
raise ApiError(0, "stream", "the event stream ended without a terminal event")
time.sleep(min(0.5 * attempts, 5.0))
def post_message(self, text: str | None = None) -> str:
"""Send the turn's message once (or `text`, the delivery round's); → the user.message event
id. The message carries an Idempotency-Key, the API's own guard against a retried POST
running twice (the SDK retries a POST only under one). If the call still fails after it may
have been delivered, the session's history says whether it was, and the message is never
sent a second time."""
before = self.last_history_id()
if text is None:
text = str(self.job.get("prompt") or "")
if self.mounts:
text = ("[Attached files, mounted read-only: " + ", ".join(f"`{m}`" for m in self.mounts) + "]\n\n" + text)
events = [{"type": "user.message", "content": [{"type": "text", "text": text}]}]
try:
for e in self.api.events_send(self.session_id, events, idempotency_key=uuid.uuid4().hex):
if isinstance(e, dict) and e.get("type") == "user.message":
return str(e.get("id") or "")
return ""
except NetError:
query: dict = {"limit": 20, "order": "asc", "types": ["user.message"]}
if before:
query["after_id"] = before
try:
doc = self.api.events_list(self.session_id, **query)
except ApiError:
doc = {}
for e in (doc or {}).get("data") or []:
if isinstance(e, dict) and e.get("type") == "user.message":
_emit("notice", {"text": "the message's acknowledgement was lost; the session history shows it arrived"})
return str(e.get("id") or "")
raise ApiError(0, "api_error", "the message could not be delivered", f"/sessions/{self.session_id}/events")
def undelivered(self) -> list[str]:
"""Files the agent wrote or edited this turn that never reached the person: not passed to
DeliverArtifacts and not among the delivered names. Scratch space, the read-only uploads and
dot paths are not deliverables."""
names = {str(d.get("name") or "") for d in self.declared}
out: list[str] = []
for p in self.written:
if p in out or p in self.delivered_paths or os.path.basename(p) in names:
continue
if p.startswith(("/tmp/", MOUNT_ROOT + "/")) or any(s.startswith(".") for s in p.split("/") if s):
continue
out.append(p)
return out
def deliver_written(self) -> None:
"""A file the agent wrote and did not deliver is lost to the person: Qoder's sandbox is
not this workspace, and DeliverArtifacts is the only way a file comes back. Every local
base gets what its turn wrote (the runner collects the workspace), so here a turn that ended
normally with such files asks the session, once, to deliver them. Measured 2026-10-10 on
0.33.0-rc.3: `auto` wrote the file the matrix's artifact scenario asked for and answered DONE
without delivering it, though the system prompt says to twice. The round's own words are
not shown or kept as the answer; what it delivers lands like any artifact."""
if self.terminated or (self.stop_reason or {}).get("type") != "end_turn":
return
missing = self.undelivered()
if not missing:
return
line = f"asked Qoder to deliver {len(missing)} file(s) the agent wrote but did not deliver: {', '.join(missing)}"
self.notes.append(line)
_emit("notice", {"text": line})
self.nudging, self.stop_reason = True, None
try:
posted = self.post_message("Deliver these files you wrote to the user now with DeliverArtifacts, in one "
"call, without changing them: " + ", ".join(missing) +
". Then reply with only: DELIVERED")
self.run_stream(posted)
finally:
self.nudging = False
def last_history_id(self) -> str:
try:
doc = self.api.events_list(self.session_id, limit=1, order="desc")
return str((doc or {}).get("first_id") or "")
except (ApiError, NetError):
return ""
def snapshot_usage(self) -> None:
try:
doc = self.api.session_retrieve(self.session_id)
u = (doc or {}).get("usage")
if isinstance(u, dict) and u:
self.usage = {k: u.get(k) for k in ("model_credits", "sandbox_runtime_credits", "total_credits")}
except (ApiError, NetError):
pass
def charge(self) -> dict | None:
"""This turn's charge: the session's usage now, less what the session had used when the
turn began. Qoder's usage is the SESSION's running total (the recorded live session read
0.35 credits after its first turn and 0.61 after its second), so the snapshot as it stands
would bill every earlier turn again on each new one. Sandbox credits settle after idle, so
what settles late is counted on the next turn rather than lost or counted twice."""
if not self.usage or self.usage.get("total_credits") is None:
return None
before = (self.st.get("usage_seen") or {}).get(self.session_id) or {}
def spent(k: str):
now = self.usage.get(k)
if not isinstance(now, (int, float)):
return now
was = before.get(k)
return round(max(now - (was if isinstance(was, (int, float)) else 0), 0), 6)
return {"amount": spent("total_credits"), "unit": "qoder_credits", "basis": "snapshot",
"model_credits": spent("model_credits"),
"sandbox_runtime_credits": spent("sandbox_runtime_credits"),
"session_total": self.usage.get("total_credits")}
def cancel_remote(self) -> str:
"""Stop the remote turn; → the line the record keeps about it."""
if not self.session_id:
return "cancelled before a Qoder session existed"
try:
self.api.session_cancel(self.session_id)
return f"cancel accepted by Qoder for session {self.session_id}"
except Exception as e: # noqa: BLE001
return f"cancel failed ({str(e)[:200]}); Qoder session {self.session_id} may still be running"
# ── main ──
def run(self) -> int:
job = self.job
resume = str(job.get("resume_session_id") or "")
sid, lost = self.find_session(resume)
if lost:
_emit("resume_lost", {"requested_session_id": resume})
_emit("__hr_init", {"session_id": sid, "agent_id": self.st.get("agent_id") or ""})
# input files first: a file Qoder cannot take fails the turn before anything is created
rels = [str(r) for r in (job.get("input_files") or [])]
for rel in rels:
try:
size = os.path.getsize(os.path.join(self.cwd, rel))
except OSError:
continue
why = upload_ok(rel, size)
if why:
self.result("failed", why)
return 0
env_id = self.ensure_environment()
servers, creds, dropped = mcp_config(job.get("mcp_servers") or [])
if dropped:
_emit("mcp_unavailable", {"servers": dropped})
vault_ids = self.ensure_vault(creds)
bindings = publish_skills(self.api, self.st, job.get("skills") or [], self.notes)
save_state(self.cwd, self.st)
resources = upload_inputs(self.api, self.st, self.cwd, rels)
save_state(self.cwd, self.st)
# The files this message brought are named IN the message. The Agent's system prompt cannot
# carry them: a session keeps the Agent version it was created with, so a file attached on a
# later turn was mounted and never mentioned, and the model did not know it was there.
self.mounts = [r["mount_path"] for r in resources]
body = agent_body(job, bindings, servers)
aid, version, changed = self.ensure_agent(body)
if sid:
if changed:
# a session pins its Agent version; its tools and servers are what it lets a
# later turn replace, so a tool disabled between turns is withheld on this one
self.api.session_update(sid, {"agent": {"tools": body["tools"], "mcp_servers": body["mcp_servers"]}})
self.mount_resources(sid, resources)
else:
sid = self.create_session(aid, version, env_id, vault_ids, resources)
self.session_id = sid
_emit("session", {"session_id": sid, "agent_id": aid, "agent_version": version,
"environment_id": env_id})
posted = self.post_message()
self.run_stream(posted)
self.deliver_written()
self.snapshot_usage()
save_state(self.cwd, self.st)
missing = [d for d in self.declared if not any(l["file_id"] == d["file_id"] for l in self.landed)]
lost = self.undelivered()
if self.terminated:
self.result("failed", (self.error or {}).get("message") or "the Qoder session was terminated")
elif self.error and self.error.get("retry") in ("terminal", "exhausted") and not self.final:
self.result("failed", self.error["message"])
elif str((self.stop_reason or {}).get("type") or "") != "end_turn":
self.result("incomplete", f"stop_reason {json.dumps(self.stop_reason or {})}")
elif missing or self.artifact_failures or lost:
self.result("incomplete", "artifact not delivered: " + "; ".join(
self.artifact_failures + [m["name"] for m in missing] + [f"{p} (written, never delivered)" for p in lost]))
else:
self.result("completed", "")
return 0
def result(self, status: str, reason: str) -> None:
charge = self.charge()
if charge and self.session_id:
# what the session had used by the end of this turn: the next turn's charge starts here
self.st.setdefault("usage_seen", {})[self.session_id] = dict(self.usage or {})
try:
save_state(self.cwd, self.st)
except OSError:
pass
_emit("__hr_result", {"status": status, "reason": reason, "final": self.final,
"session_id": self.session_id or self.st.get("session_id") or "",
"charge": charge, "notes": self.notes,
"artifacts": self.landed})
# ── purge ────────────────────────────────────────────────────────────────────────────────────────
def purge(job: dict) -> int:
"""Delete at Qoder everything the session's turns created there, in dependency order; every
failure is reported with its id, never swallowed. Exit 0 when nothing failed."""
cwd = str(job.get("cwd") or os.getcwd())
st = load_state(cwd)
try:
api = Client(str(job.get("base_url") or ""), str(job.get("api_key") or ""))
except ImportError as e:
# Without the SDK nothing can be deleted, and the runner removes the folder (and this
# state with it) whatever the answer is: the report names every recorded id, so what is
# left at Qoder is in the runner's log rather than in a traceback.
_emit("purge", {"done": [], "failed": [{
"what": "everything recorded: " + json.dumps(st)[:1200],
"error": f"the Qoder SDK (qca-sdk) is not installed in this interpreter: {e}"[:300]}],
"state": STATE_REL})
return 1
done: list[str] = []
failed: list[dict] = []
def attempt(label: str, fn, *a, ok_status=(404,)) -> bool:
try:
fn(*a)
done.append(label)
return True
except ApiError as e:
if e.status in ok_status:
done.append(label + " (already gone)")
return True
failed.append({"what": label, "error": str(e)})
except Exception as e: # noqa: BLE001
failed.append({"what": label, "error": f"{type(e).__name__}: {e}"[:300]})
return False
sessions = list(st.get("sessions") or ([st["session_id"]] if st.get("session_id") else []))
for sid in sessions:
attempt(f"cancel session {sid}", api.session_cancel, sid, ok_status=(404, 409))
attempt(f"delete session {sid}", api.session_delete, sid)
for fid in list(st.get("artifacts") or []):
attempt(f"delete artifact file {fid}", api.file_delete, fid)
for rel, rec in (st.get("files") or {}).items():
if isinstance(rec, dict) and rec.get("id"):
attempt(f"delete input file {rec['id']} ({rel})", api.file_delete, rec["id"])
if st.get("agent_id"):
attempt(f"archive agent {st['agent_id']}", api.agent_archive, st["agent_id"])
if st.get("vault_id"):
attempt(f"delete vault {st['vault_id']}", api.vault_delete, st["vault_id"])
for name, rec in (st.get("skills") or {}).items():
if isinstance(rec, dict) and rec.get("id"):
attempt(f"delete skill {rec['id']} ({name})", api.skill_delete, rec["id"])
if st.get("environment_id"):
eid = st["environment_id"]
try:
api.environment_delete(eid)
done.append(f"delete environment {eid}")
except ApiError as e:
if e.status == 404:
done.append(f"delete environment {eid} (already gone)")
elif e.status == 409: # still referenced: the API says to archive it instead
attempt(f"archive environment {eid}", api.environment_archive, eid)
else:
failed.append({"what": f"delete environment {eid}", "error": str(e)})
except Exception as e: # noqa: BLE001
failed.append({"what": f"delete environment {eid}", "error": f"{type(e).__name__}: {e}"[:300]})
_emit("purge", {"done": done, "failed": failed, "state": STATE_REL})
return 0 if not failed else 1
# ── entry ────────────────────────────────────────────────────────────────────────────────────────
def main() -> int:
job = json.loads(sys.argv[1])
if job.get("purge"):
return purge(job)
try:
turn = Turn(job)
except ImportError as e:
_emit("__hr_result", {"status": "failed", "final": "", "charge": None,
"reason": f"the Qoder SDK (qca-sdk) is not installed in this interpreter: {e}"[:500]})
return 0
def on_term(signum, frame): # noqa: ARG001
raise Cancelled()
signal.signal(signal.SIGTERM, on_term)
try:
return turn.run()
except Cancelled:
signal.signal(signal.SIGTERM, signal.SIG_IGN) # the cancel call itself is not interrupted
line = turn.cancel_remote()
_emit("notice", {"text": line})
turn.result("cancelled", line)
return 0
except ApiError as e:
turn.result("failed", f"Qoder API {e.path}: {e}"[:1000])
return 0
except NetError as e:
turn.result("failed", f"Qoder did not answer: {e}"[:1000])
return 0
except OSError as e:
# this box, not Qoder: a workspace file that could not be read or written. The SDK raises
# its own classes for the network, so what is left here is local, and said so.
turn.result("failed", f"the workspace: {type(e).__name__}: {e}"[:1000])
return 0
if __name__ == "__main__":
sys.exit(main())