terrarium-python 0.1.1__py3-none-any.whl

terrarium/errors.py

@@ -0,0 +1,66 @@
+"""Typed exceptions so callers can branch on failure class instead of
+string-matching HTTP status codes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class TerrariumError(Exception):
+    """Base for all SDK errors. Carries the HTTP status + response body when known."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class AuthError(TerrariumError):
+    """401/403 — missing, invalid, or insufficiently-scoped token."""
+
+
+class NotFoundError(TerrariumError):
+    """404 — session/agent/etc. does not exist."""
+
+
+class ConflictError(TerrariumError):
+    """409 — conflicting state."""
+
+
+class RateLimitError(TerrariumError):
+    """429 — slow down."""
+
+
+class ServerError(TerrariumError):
+    """5xx — orchestrator-side failure (transient: retried)."""
+
+
+class TransportError(TerrariumError):
+    """Connection/timeout failure reaching the orchestrator (transient: retried)."""
+
+
+def from_status(e: httpx.HTTPStatusError) -> TerrariumError:
+    status = e.response.status_code
+    try:
+        body = e.response.json()
+        detail = body.get("detail") if isinstance(body, dict) else body
+    except Exception:
+        body = e.response.text
+        detail = body
+    msg = f"{status} {e.request.method} {e.request.url.path}: {detail}"
+    cls = {
+        401: AuthError, 403: AuthError, 404: NotFoundError,
+        409: ConflictError, 429: RateLimitError,
+    }.get(status, ServerError if status >= 500 else TerrariumError)
+    return cls(msg, status=status, body=body)
+
+
+def is_transient(e: BaseException) -> bool:
+    """Worth retrying: connection/timeout, 429, or 5xx."""
+    if isinstance(e, httpx.TransportError):
+        return True
+    if isinstance(e, httpx.HTTPStatusError):
+        return e.response.status_code == 429 or e.response.status_code >= 500
+    return False

terrarium/memory.py

@@ -0,0 +1,171 @@
+"""Structured, retrieval-backed memory for long-running agents.
+
+The sandbox's ``/memory`` is an FS volume — no retrieval, and on k8s its RWO PVC can't
+multi-attach, so concurrent sessions of one agent silently fork. This module offers memory as
+**client tools** instead: the agent calls ``memory_search`` / ``memory_write`` / ``memory_get``,
+and the handlers run in YOUR process against a real store. That gives keyword/vector retrieval
+at scale AND sidesteps multi-attach entirely (no shared volume) — concurrent sessions and
+scheduled jobs share one store.
+
+    from terrarium import TerrariumClient, TerrariumOptions
+    from terrarium.memory import SqliteMemory, memory_tools
+
+    store = SqliteMemory("assistant.db")            # durable across sessions/processes
+    opts = TerrariumOptions(agent_id=agent_id, tools=memory_tools(store))
+
+Bring your own backend (pgvector, Redis, an API) by implementing ``MemoryStore``; the reference
+``SqliteMemory`` needs only the stdlib (SQLite FTS5, with a LIKE fallback).
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import sqlite3
+import threading
+import time
+from typing import Any, Protocol, runtime_checkable
+
+from .options import ClientTool, tool
+
+__all__ = ["MemoryStore", "SqliteMemory", "memory_tools"]
+
+
+def _coerce_tags(tags: Any) -> list[str]:
+    """Models routinely pass `tags` as a comma-joined STRING despite the array schema. Coerce
+    to a clean list (split a string on commas/whitespace); ignore non-iterables. Without this,
+    `" ".join(a_string)` silently stores it character-by-character."""
+    if tags is None:
+        return []
+    if isinstance(tags, str):
+        return [t for t in re.split(r"[,\s]+", tags.strip()) if t]
+    if isinstance(tags, (list, tuple)):
+        return [str(t) for t in tags if t is not None and str(t)]
+    return []
+
+
+@runtime_checkable
+class MemoryStore(Protocol):
+    """A pluggable memory backend. Implement these three async methods over your own store
+    (pgvector, Redis, an internal API) and pass it to :func:`memory_tools`."""
+
+    async def write(self, content: str, tags: list[str] | None = None) -> str:
+        """Persist a memory; return its id."""
+        ...
+
+    async def search(self, query: str, limit: int = 5) -> list[dict[str, Any]]:
+        """Return up to ``limit`` memories matching ``query`` (most relevant first)."""
+        ...
+
+    async def get(self, memory_id: str) -> dict[str, Any] | None:
+        """Fetch one memory by id, or ``None``."""
+        ...
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _fts_match(query: str) -> str:
+    # Build an FTS5 query that RECALLS well. Three things matter:
+    #  - quote each term so user text can't inject FTS5 operators;
+    #  - prefix `*` (terms ≥3 chars) + the porter tokenizer so inflection doesn't lose a hit
+    #    ("language" finds "languages", "cat" finds "cats");
+    #  - join with OR, not the default implicit AND. An LLM's recall query is a bag of terms
+    #    spread across MANY memories ("timezone language preference" where each fact lives in a
+    #    different row); AND requires all terms in ONE row, so a broad query recalls nothing.
+    #    OR surfaces every partial match and `ORDER BY rank` (in _search) floats the best up.
+    terms = [t for t in query.replace('"', " ").split() if t]
+    return " OR ".join((f'"{t}"*' if len(t) >= 3 else f'"{t}"') for t in terms)
+
+
+class SqliteMemory:
+    """Reference :class:`MemoryStore` over SQLite. Uses FTS5 for ranked full-text search when
+    available, falling back to ``LIKE``. Thread-safe (one connection + lock); pass a file path
+    for durability across processes, or the default ``:memory:`` for ephemeral use."""
+
+    def __init__(self, path: str = ":memory:") -> None:
+        self._c = sqlite3.connect(path, check_same_thread=False)
+        self._c.row_factory = sqlite3.Row
+        self._lock = threading.Lock()
+        self._fts = True
+        try:
+            # porter stemming so "languages"/"language", "preferences"/"preference", etc. recall
+            # each other (an LLM rarely recalls with the inflection it wrote). New tables only —
+            # an existing table keeps its tokenizer, but prefix matching (see _fts_match) still helps.
+            self._c.execute(
+                "CREATE VIRTUAL TABLE IF NOT EXISTS memories "
+                "USING fts5(content, tags, created_at UNINDEXED, tokenize='porter unicode61')")
+        except sqlite3.OperationalError:  # SQLite built without FTS5 — degrade to LIKE
+            self._fts = False
+            self._c.execute(
+                "CREATE TABLE IF NOT EXISTS memories "
+                "(id INTEGER PRIMARY KEY, content TEXT, tags TEXT, created_at TEXT)")
+        self._c.commit()
+
+    # --- sync core (run off-loop via asyncio.to_thread) ---
+    def _write(self, content: str, tags: list[str] | None) -> str:
+        with self._lock:
+            cur = self._c.execute(
+                "INSERT INTO memories(content, tags, created_at) VALUES(?,?,?)",
+                (content, " ".join(_coerce_tags(tags)), _now()))  # coerce: a stray str must not char-join
+            self._c.commit()
+            return str(cur.lastrowid)
+
+    def _search(self, query: str, limit: int) -> list[dict[str, Any]]:
+        with self._lock:
+            if self._fts and (m := _fts_match(query)):
+                rows = self._c.execute(
+                    "SELECT rowid AS id, content, tags, created_at FROM memories "
+                    "WHERE memories MATCH ? ORDER BY rank LIMIT ?", (m, limit)).fetchall()
+            else:
+                rows = self._c.execute(
+                    "SELECT rowid AS id, content, tags, created_at FROM memories "
+                    "WHERE content LIKE ? ORDER BY rowid DESC LIMIT ?",
+                    (f"%{query}%", limit)).fetchall()
+            return [dict(r) for r in rows]
+
+    def _get(self, memory_id: str) -> dict[str, Any] | None:
+        with self._lock:
+            row = self._c.execute(
+                "SELECT rowid AS id, content, tags, created_at FROM memories WHERE rowid=?",
+                (memory_id,)).fetchone()
+            return dict(row) if row else None
+
+    async def write(self, content: str, tags: list[str] | None = None) -> str:
+        return await asyncio.to_thread(self._write, content, tags)
+
+    async def search(self, query: str, limit: int = 5) -> list[dict[str, Any]]:
+        return await asyncio.to_thread(self._search, query, limit)
+
+    async def get(self, memory_id: str) -> dict[str, Any] | None:
+        return await asyncio.to_thread(self._get, memory_id)
+
+
+def memory_tools(store: MemoryStore) -> list[ClientTool]:
+    """Ready-made client tools (``memory_write`` / ``memory_search`` / ``memory_get``) backed by
+    ``store``. Pass the result to ``TerrariumOptions(tools=...)``; the handlers run in your
+    process, so the store and its credentials never enter the sandbox."""
+
+    @tool("memory_write", "Save a durable memory — a fact, preference, or decision — for later recall.",
+          {"content": {"type": "string", "description": "The thing to remember"},
+           "tags": {"type": "array", "items": {"type": "string"}, "description": "Optional labels"}})
+    async def memory_write(args: dict[str, Any]) -> str:
+        # Coerce at the protocol boundary so EVERY MemoryStore backend gets a clean list, even
+        # when the model passes tags as a comma-joined string (it routinely does).
+        mid = await store.write(str(args["content"]), _coerce_tags(args.get("tags")))
+        return f"saved memory {mid}"
+
+    @tool("memory_search", "Search durable memory by keyword or topic. Call this BEFORE answering "
+          "to recall relevant past context.",
+          {"query": {"type": "string"}, "limit": {"type": "integer", "description": "max results (default 5)"}})
+    async def memory_search(args: dict[str, Any]) -> str:
+        hits = await store.search(str(args["query"]), int(args.get("limit") or 5))
+        return json.dumps(hits) if hits else "no memories matched"
+
+    @tool("memory_get", "Fetch one memory by its id.", {"id": {"type": "string"}})
+    async def memory_get(args: dict[str, Any]) -> str:
+        m = await store.get(str(args["id"]))
+        return json.dumps(m) if m else "not found"
+
+    return [memory_write, memory_search, memory_get]

terrarium/messages.py

@@ -0,0 +1,137 @@
+"""Typed messages + content blocks — modelled on the Claude Agent SDK's message types
+(``AssistantMessage``, ``TextBlock``, ``ToolUseBlock``, ``ResultMessage`` …) so iterating a
+Terrarium turn feels like iterating a Claude Agent SDK response.
+
+Terrarium streams a flat event log; ``parse_message`` lifts each event into the closest
+Claude-SDK message. Every message keeps the original event under ``.raw`` as an escape hatch.
+Terrarium-only events (human-in-the-loop) become ``QuestionMessage`` / ``PermissionMessage``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+
+# --- content blocks (mirror claude_agent_sdk) ---
+@dataclass
+class TextBlock:
+    text: str
+
+
+@dataclass
+class ThinkingBlock:
+    thinking: str
+    signature: str = ""
+
+
+@dataclass
+class ToolUseBlock:
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass
+class ToolResultBlock:
+    tool_use_id: str
+    content: Any
+    is_error: bool = False
+
+
+ContentBlock = Union[TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock]
+
+
+# --- messages (mirror claude_agent_sdk) ---
+@dataclass
+class AssistantMessage:
+    content: list[ContentBlock]
+    model: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def text(self) -> str:
+        """Concatenated text of any TextBlocks (convenience)."""
+        return "".join(b.text for b in self.content if isinstance(b, TextBlock))
+
+
+@dataclass
+class UserMessage:
+    content: list[ContentBlock]
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SystemMessage:
+    subtype: str
+    data: dict[str, Any]
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ResultMessage:
+    subtype: str
+    total_cost_usd: float | None
+    usage: dict[str, Any]
+    duration_ms: int | None
+    num_turns: int | None
+    is_error: bool
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+# --- Terrarium extensions (human-in-the-loop) ---
+@dataclass
+class QuestionMessage:
+    """An AskUserQuestion prompt. Answer with ``session.answer(question_id, {...})`` or via a
+    ``can_use_tool`` callback returning ``PermissionResultAllow(updated_input={"answers": ...})``."""
+
+    question_id: str
+    questions: list[dict[str, Any]]
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PermissionMessage:
+    """A gated tool-permission request (when the harness sets ``approval``). Resolve with
+    ``session.decide(request_id, "allow"|"always"|"deny")`` or a ``can_use_tool`` callback."""
+
+    request_id: str
+    tool_name: str
+    input: dict[str, Any]
+    title: str | None = None
+    description: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+Message = Union[AssistantMessage, UserMessage, SystemMessage, ResultMessage, QuestionMessage, PermissionMessage]
+
+
+def parse_message(ev: dict[str, Any]) -> Message | None:
+    """Convert a raw Terrarium event into a typed message, or ``None`` for events with no
+    message equivalent (status, rewind_point, answered, decided, …)."""
+    t = ev.get("type")
+    # The worker stamps the responding model on assistant events (emit(EV_ASSISTANT_TEXT,
+    # …, model=msg.model)); carry it through so AssistantMessage.model matches the real SDK.
+    model = ev.get("model")
+    if t == "assistant_text":
+        return AssistantMessage(content=[TextBlock(str(ev.get("text", "")))], model=model, raw=ev)
+    if t == "thinking":
+        return AssistantMessage(content=[ThinkingBlock(str(ev.get("text", "")))], model=model, raw=ev)
+    if t == "tool_use":
+        return AssistantMessage(content=[ToolUseBlock(str(ev.get("id", "")), str(ev.get("name", "")), ev.get("input") or {})], model=model, raw=ev)
+    if t == "tool_result":
+        return UserMessage(content=[ToolResultBlock(str(ev.get("tool_use_id", "")), ev.get("content"), bool(ev.get("is_error")))], raw=ev)
+    if t == "result":
+        return ResultMessage(
+            subtype=str(ev.get("subtype", "")), total_cost_usd=ev.get("total_cost_usd"),
+            usage=ev.get("usage") or {}, duration_ms=ev.get("duration_ms"),
+            num_turns=ev.get("num_turns"), is_error=bool(ev.get("is_error")), raw=ev)
+    if t in ("system", "ready", "session_start", "error", "session_end", "worker_lost"):
+        data = ev.get("data") if isinstance(ev.get("data"), dict) else {k: v for k, v in ev.items() if k not in ("type", "seq", "ts")}
+        return SystemMessage(subtype=str(ev.get("subtype", t)), data=data, raw=ev)
+    if t == "question":
+        return QuestionMessage(str(ev.get("question_id", "")), ev.get("questions") or [], raw=ev)
+    if t == "permission":
+        return PermissionMessage(str(ev.get("request_id", "")), str(ev.get("tool_name", "")),
+                                 ev.get("input") or {}, ev.get("title"), ev.get("description"), raw=ev)
+    return None

terrarium/options.py

@@ -0,0 +1,212 @@
+"""Options + permission types — modelled on the Claude Agent SDK (``ClaudeAgentOptions``,
+``can_use_tool``, ``PermissionResultAllow/Deny``) so the two SDKs feel the same, with extra
+fields for Terrarium's own features (personas, approval gating, egress profiles, memory).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, is_dataclass
+from typing import Any, Awaitable, Callable, Union
+
+
+@dataclass
+class AgentDefinition:
+    """A programmatic subagent — field-for-field the Claude Agent SDK's ``AgentDefinition``
+    (same names, incl. its camelCase), so ported code drops in unchanged. Plain dicts (with
+    snake_case or camelCase keys) are accepted anywhere this is."""
+
+    description: str
+    prompt: str
+    tools: list[str] | None = None
+    disallowedTools: list[str] | None = None  # noqa: N815 — Claude-SDK name
+    model: str | None = None
+    skills: list[str] | None = None
+    memory: str | None = None                 # "user" | "project" | "local"
+    mcpServers: "list[str | dict[str, Any]] | None" = None  # noqa: N815
+    initialPrompt: str | None = None          # noqa: N815
+    maxTurns: int | None = None               # noqa: N815
+    background: bool | None = None
+    effort: "str | int | None" = None
+    permissionMode: str | None = None         # noqa: N815
+
+
+def _agent_spec(a: "AgentDefinition | dict[str, Any]") -> dict[str, Any]:
+    if is_dataclass(a) and not isinstance(a, type):
+        return {k: v for k, v in asdict(a).items() if v is not None}
+    return dict(a)
+
+
+@dataclass
+class ToolPermissionContext:
+    """Context passed to a ``can_use_tool`` callback (mirrors the Claude SDK's). For a
+    permission request it carries the request id + the agent's title/description; for an
+    AskUserQuestion it wraps the question event."""
+
+    request_id: str = ""
+    title: str | None = None
+    description: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PermissionResultAllow:
+    """Allow a tool call. ``always`` maps to Terrarium's "always allow (this session)".
+    For AskUserQuestion, put the answers under ``updated_input={"answers": {...}}`` —
+    exactly as the Claude Agent SDK expects."""
+
+    updated_input: dict[str, Any] | None = None
+    always: bool = False
+
+
+@dataclass
+class PermissionResultDeny:
+    """Deny a tool call (optionally with a message the agent sees)."""
+
+    message: str = ""
+
+
+@dataclass
+class ClientTool:
+    """A custom tool whose handler runs in YOUR process (with your application context) —
+    bridged to the sandboxed agent. The agent's tool input crosses out, your handler runs
+    here, and only the result you return crosses back in; your code/state/secrets never
+    enter the sandbox. Create via :func:`tool`."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: "Callable[[dict[str, Any]], Any]"  # (input) -> str | {"content","is_error"} | awaitable
+
+    def schema(self) -> dict[str, Any]:
+        return {"name": self.name, "description": self.description, "input_schema": self.input_schema}
+
+
+def tool(name: str, description: str, input_schema: dict[str, Any] | None = None):
+    """Decorator turning an (async or sync) ``handler(input) -> result`` into a :class:`ClientTool`.
+    Pass the resulting tools to ``TerrariumOptions(tools=[...])``. Mirrors the Claude Agent SDK's
+    ``@tool`` — except the handler executes client-side, never in the sandbox.
+
+        @tool("get_user", "Look up a user by id", {"id": {"type": "string"}})
+        async def get_user(args):
+            return await db.users.find(args["id"])   # your app context, your process
+    """
+    def deco(fn):
+        return ClientTool(name=name, description=description, input_schema=input_schema or {}, handler=fn)
+    return deco
+
+
+PermissionResult = Union[PermissionResultAllow, PermissionResultDeny]
+# A permission callback (like the Claude Agent SDK's). May be sync OR async — the client
+# awaits the result if it's awaitable.
+CanUseTool = Callable[[str, dict[str, Any], ToolPermissionContext], Union[PermissionResult, Awaitable[PermissionResult]]]
+
+# Harness keys the orchestrator understands (kept in sync with terrarium/harness.py).
+_HARNESS_FIELDS = (
+    "model", "system_mode", "custom_prompt", "permission_mode", "allowed_tools", "builtin_tools",
+    "thinking", "effort", "fallback_model", "max_thinking_tokens", "betas",
+    "max_turns", "max_budget_usd", "mcp_servers", "agents", "skills",
+    "interactive", "approval", "setting_sources", "env", "extra_options",
+    "environments", "memory_mode",
+)
+
+
+@dataclass
+class TerrariumOptions:
+    """Configuration for a Terrarium agent/session — a superset of the Claude Agent SDK's
+    ``ClaudeAgentOptions``.
+
+    The first block mirrors the Claude SDK field-for-field (so existing knowledge carries
+    over); the second block adds Terrarium-only capabilities. ``None`` means "leave to the
+    orchestrator default" — only set fields are sent.
+    """
+
+    # --- Claude Agent SDK-aligned ---
+    model: str | None = None                      # "sonnet" | "opus" | "haiku" | full id
+    system_prompt: "str | dict[str, Any] | None" = None  # custom prompt (→ custom persona), or the
+    #     Claude-SDK preset dict {"type":"preset","preset":"claude_code"} (→ claude_code persona)
+    allowed_tools: list[str] | None = None        # AUTO-APPROVE list (Claude-SDK: skips the prompt;
+    #                                                does NOT change which tools the agent has)
+    builtin_tools: "list[str] | dict[str, Any] | None" = None  # AVAILABILITY allowlist — the base set
+    #     of built-in tools the agent may use. None=all defaults; ["Read","Grep"]=only those; []=none;
+    #     {"type":"preset","preset":"claude_code"}=all defaults. This is the real "restrict tools" knob.
+    permission_mode: str | None = None            # default | acceptEdits | plan | bypassPermissions
+    max_turns: int | None = None
+    max_budget_usd: float | None = None
+    mcp_servers: dict[str, Any] | None = None
+    agents: "dict[str, AgentDefinition | dict[str, Any]] | None" = None  # programmatic subagents
+    #     (SDK `agents`): name -> AgentDefinition, or a plain dict ({"description", "prompt",
+    #     and optionally "tools", "disallowed_tools", "model", "skills", "max_turns", ...})
+    thinking: dict[str, Any] | None = None         # e.g. {"type": "adaptive"} / {"type": "enabled", "budget_tokens": N}
+    effort: str | None = None                      # low | medium | high | xhigh | max
+    fallback_model: str | None = None              # model to retry with on overload/refusal
+    max_thinking_tokens: int | None = None         # hard cap on thinking tokens per turn
+    betas: list[str] | None = None                 # API beta flags to opt into
+    setting_sources: list[str] | None = None       # ["user", "project", "local"]
+    env: dict[str, str] | None = None
+    skills: "bool | list[str] | str | None" = None  # True=mount+discover; "all"; [names]=only these;
+    #     []=NO skills at all (hides the CLI's built-in skills too — the "bare harness" setting)
+    memory_mode: str | None = None                  # "volume" (default, durable mount) | "synced"
+    #     (snapshot in/out — much faster k8s launch, loses writes since the last turn if the pod
+    #     dies abruptly) | "none" (container-local scratch, discarded on stop)
+    can_use_tool: CanUseTool | None = None          # (tool, input, ctx) -> Allow | Deny
+    tools: list[ClientTool] | None = None           # custom tools that run in YOUR process (see `tool`)
+
+    # --- Terrarium extensions ---
+    system_mode: str | None = None                  # minimal | claude_code | custom | assistant
+    custom_prompt: str | None = None                # alias for system_prompt (explicit persona text)
+    approval: "str | list[str] | None" = None       # off | edits | all | [tool names] — human-in-the-loop gating
+    interactive: bool | None = None                 # allow AskUserQuestion / approval prompts to block for an operator
+    environments: list[str] | None = None           # attach to {secrets, egress} bundles — the sole per-agent
+    #     egress + secret-scoping mechanism. None/[] = no operator secrets + global egress; a list =
+    #     ONLY those environments' secrets, and egress merged from their profiles (enforce wins; hosts union).
+    memory_scope: str | None = None                 # share memory with another agent id
+    extra_options: dict[str, Any] | None = None     # new SDK fields only; Terrarium-managed keys are rejected
+
+    # --- session attach / routing (not part of the harness) ---
+    agent_id: str | None = None                     # attach the session to an existing agent
+    title: str | None = None
+
+    def to_harness(self) -> dict[str, Any]:
+        """Serialize the harness-relevant fields for the create-agent/create-session API."""
+        h: dict[str, Any] = {}
+        # `system_prompt` is the Claude-SDK name for a bespoke prompt → Terrarium custom
+        # persona. Its preset dict form maps onto the matching system_mode.
+        sp = self.system_prompt
+        preset_mode: str | None = None
+        if isinstance(sp, dict):
+            if sp.get("type") == "preset" and sp.get("preset") == "claude_code" and "append" not in sp:
+                sp = None
+                preset_mode = "claude_code"
+            else:  # unknown preset / "append" — no Terrarium equivalent; refuse loudly
+                raise ValueError(
+                    f"unsupported system_prompt {sp!r}: only "
+                    '{"type": "preset", "preset": "claude_code"} (without "append") maps to a '
+                    "persona; for appended guidance use system_prompt=<full text> instead"
+                )
+        # A claude_code preset can't be combined with a custom prompt or an explicit
+        # system_mode — either would silently clobber the preset. Refuse loudly (matching the
+        # unknown-preset/unknown-kwarg behavior) rather than picking one.
+        if preset_mode and (self.custom_prompt is not None or self.system_mode is not None):
+            raise ValueError(
+                'conflicting persona: system_prompt={"preset": "claude_code"} cannot be '
+                "combined with custom_prompt or an explicit system_mode — set only one"
+            )
+        custom = self.custom_prompt or sp
+        if custom is not None:
+            h["custom_prompt"] = custom
+            h["system_mode"] = self.system_mode or "custom"
+        elif self.system_mode is not None:
+            h["system_mode"] = self.system_mode
+        elif preset_mode is not None:
+            h["system_mode"] = preset_mode
+        for k in _HARNESS_FIELDS:
+            if k in ("custom_prompt", "system_mode"):
+                continue
+            v = getattr(self, k, None)
+            if v is not None:
+                h[k] = v
+        if self.agents:  # AgentDefinition dataclasses → plain dicts for the wire
+            h["agents"] = {name: _agent_spec(a) for name, a in self.agents.items()}
+        if self.tools:  # send only the SCHEMAS; the handlers stay client-side
+            h["client_tools"] = [t.schema() for t in self.tools]
+        return h