@opengroundplan/core 0.1.1

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/loop.py

@@ -0,0 +1,112 @@
+"""The loop: repeat while the model asks for a tool, and stop unconditionally at the caps.
+
+Both ceilings are checked BEFORE the request that would breach them — a cap tested after
+the call has already been paid for.
+"""
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from .model import next_turn
+from .settings import get_settings
+from .tools.registry import invoke, tool_schemas
+from .tools.spec import ToolError
+from .trace import trace
+
+StopReason = Literal["end_turn", "max_turns", "max_total_tokens", "refusal"]
+
+
+@dataclass
+class RunResult:
+    text: str
+    stop_reason: StopReason
+    turns: int
+    total_tokens: int
+    messages: list[dict[str, Any]] = field(default_factory=list)
+
+
+async def run(prompt: str, system: str) -> RunResult:
+    settings = get_settings()
+    messages: list[dict[str, Any]] = [{"role": "user", "content": prompt}]
+    tools = tool_schemas()
+    turns = 0
+    total_tokens = 0
+
+    trace(
+        "run.start",
+        max_turns=settings.max_turns,
+        max_total_tokens=settings.max_total_tokens,
+        max_output_tokens=settings.max_output_tokens,
+    )
+
+    while True:
+        if turns >= settings.max_turns:
+            return _stop("max_turns", messages, turns, total_tokens)
+        if total_tokens >= settings.max_total_tokens:
+            return _stop("max_total_tokens", messages, turns, total_tokens)
+
+        turn = await next_turn(
+            system=system,
+            messages=messages,
+            tools=tools,
+            max_output_tokens=settings.max_output_tokens,
+        )
+
+        turns += 1
+        total_tokens += turn.usage.input_tokens + turn.usage.output_tokens
+        trace("turn.end", turn=turns, stop_reason=turn.stop_reason, total_tokens=total_tokens)
+
+        # Thinking blocks are echoed back unchanged; editing them breaks the next turn.
+        messages.append({"role": "assistant", "content": turn.content})
+
+        # Safety classifiers can decline with HTTP 200 — check before reading content.
+        if turn.stop_reason == "refusal":
+            return _stop("refusal", messages, turns, total_tokens)
+        if turn.stop_reason != "tool_use":
+            return _stop("end_turn", messages, turns, total_tokens, turn)
+
+        messages.append({"role": "user", "content": await _run_tool_calls(turn)})
+
+
+async def _run_tool_calls(turn: Any) -> list[dict[str, Any]]:
+    """All results go back in ONE user message; splitting them stops parallel tool calls."""
+    calls = [block for block in turn.content if block.type == "tool_use"]
+    return list(await asyncio.gather(*(_run_one(call) for call in calls)))
+
+
+async def _run_one(call: Any) -> dict[str, Any]:
+    timeout = get_settings().tool_timeout_seconds
+    try:
+        content = await asyncio.wait_for(invoke(call.name, call.input), timeout=timeout)
+        trace("tool.ok", tool=call.name)
+        return {"type": "tool_result", "tool_use_id": call.id, "content": content}
+    except Exception as error:
+        # A failed tool is reported back, never dropped: the model needs it to change course.
+        message = str(error) if isinstance(error, ToolError) else f"Tool failed: {error!r}"
+        trace("tool.error", tool=call.name, message=message)
+        return {
+            "type": "tool_result",
+            "tool_use_id": call.id,
+            "content": message,
+            "is_error": True,
+        }
+
+
+def _stop(
+    stop_reason: StopReason,
+    messages: list[dict[str, Any]],
+    turns: int,
+    total_tokens: int,
+    turn: Any = None,
+) -> RunResult:
+    trace("run.stop", stop_reason=stop_reason, turns=turns, total_tokens=total_tokens)
+    blocks = getattr(turn, "content", []) or []
+    text = "".join(block.text for block in blocks if block.type == "text")
+    return RunResult(
+        text=text,
+        stop_reason=stop_reason,
+        turns=turns,
+        total_tokens=total_tokens,
+        messages=messages,
+    )

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/model.py

@@ -0,0 +1,50 @@
+"""The one place the vendor SDK is imported and the one place the model is called.
+
+``.importlinter`` forbids every other module under ``agent/`` from importing ``anthropic`` —
+a second call site is a second set of caps nobody is enforcing.
+"""
+
+from functools import lru_cache
+from typing import Any
+
+import anthropic
+
+from .settings import api_key_for, get_settings, model_for
+
+
+class ModelError(Exception):
+    """One failure type for callers, whatever the SDK raised underneath."""
+
+
+# Cached: a client per turn leaks a connection pool for every round trip in the loop.
+@lru_cache(maxsize=1)
+def _client() -> anthropic.AsyncAnthropic:
+    options: dict[str, Any] = {"timeout": get_settings().request_timeout_seconds}
+    key = api_key_for()
+    if key:
+        options["api_key"] = key
+    return anthropic.AsyncAnthropic(**options)
+
+
+async def next_turn(
+    *,
+    system: str,
+    messages: list[dict[str, Any]],
+    tools: list[dict[str, Any]],
+    max_output_tokens: int,
+) -> anthropic.types.Message:
+    """One round trip. The caller owns the output ceiling; this module never invents one."""
+    try:
+        return await _client().messages.create(
+            model=model_for(),
+            max_tokens=max_output_tokens,
+            # Adaptive is the only on-mode on current models; omitting it disables thinking.
+            thinking={"type": "adaptive"},
+            system=system,
+            tools=tools,
+            messages=messages,
+        )
+    except Exception as error:
+        # Deliberately broad: the SDK signals missing credentials with TypeError and
+        # transport failures with its own hierarchy. Callers only need one type.
+        raise ModelError(f"model call failed: {error}") from error

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/sandbox.py

@@ -0,0 +1,62 @@
+"""The seam for effects that cannot be undone.
+
+Replace ``decide`` with your real policy — a human approval queue, an allowlist, a
+per-tenant permission check. The default is ``deny`` because an autonomous loop that can
+act irreversibly on day one is the failure mode this seam exists to prevent.
+"""
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+from .settings import get_settings
+from .tools.spec import ToolSpec
+from .trace import trace
+
+
+@dataclass(frozen=True)
+class SandboxDecision:
+    allowed: bool
+    # Returned to the model in place of the tool result when ``allowed`` is False.
+    reason: str = ""
+
+
+def decide(tool: ToolSpec, tool_input: Any) -> SandboxDecision:
+    if tool.effect == "read":
+        return SandboxDecision(allowed=True)
+
+    mode = get_settings().sandbox_mode
+    if mode == "allow":
+        trace("sandbox.allow", tool=tool.name)
+        return SandboxDecision(allowed=True)
+    if mode == "dry-run":
+        trace("sandbox.dry_run", tool=tool.name)
+        return SandboxDecision(
+            allowed=False,
+            reason=f'Dry run: "{tool.name}" was not executed. Report what you would have done.',
+        )
+
+    trace("sandbox.deny", tool=tool.name)
+    return SandboxDecision(
+        allowed=False,
+        reason=(
+            f'"{tool.name}" has an irreversible effect and the sandbox policy is "deny". '
+            "Do not retry it; explain what you would need permission for."
+        ),
+    )
+
+
+def guard(tool: ToolSpec) -> ToolSpec:
+    """Wrap a handler so the policy runs before the effect, never after."""
+    if tool.effect == "read":
+        return tool
+
+    inner = tool.handler
+
+    async def gated(tool_input: Any) -> str:
+        decision = decide(tool, tool_input)
+        if not decision.allowed:
+            return decision.reason
+        result = inner(tool_input)
+        return await result if hasattr(result, "__await__") else result
+
+    return replace(tool, handler=gated)

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/settings.py

@@ -0,0 +1,69 @@
+"""The one typed default table for the loop.
+
+No other module under ``agent/`` may read the environment or write a cap as a numeric
+literal — ``tests/architecture/test_agent_loop.py`` fails on both.
+"""
+
+import os
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+ENV_PREFIX = "{{ solutionName | upperSnake }}_AGENT_"
+
+# The only provider with a safe default; anything else must set <PREFIX>MODEL_DEFAULT.
+DEFAULT_MODEL = "claude-opus-4-8"
+
+
+class AgentSettings(BaseSettings):
+    """Every field is overridable by ``{{ solutionName | upperSnake }}_AGENT_<FIELD>``."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX,
+        env_file=".env",
+        extra="ignore",
+        protected_namespaces=(),
+    )
+
+    # Role name, not a model id. ``model_for`` resolves the id from it.
+    role: str = "{{ agentRole }}"
+
+    # Hard caps. An unbounded loop is the top cause of runaway agent spend, so these are
+    # ceilings the loop enforces itself — not hints handed to the model.
+    max_turns: int = {{ maxTurns }}
+    max_total_tokens: int = {{ maxTotalTokens }}
+    max_output_tokens: int = {{ maxOutputTokens }}
+    tool_timeout_seconds: float = {{ toolTimeoutSeconds }}
+    request_timeout_seconds: float = 120.0
+
+    # Irreversible effects need a policy, never a default yes.
+    sandbox_mode: str = "{{ sandboxMode }}"
+    trace_enabled: bool = True
+
+    # Where the example write-effect tool appends. Tools keep no paths of their own.
+    note_path: str = "agent-notes.log"
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> AgentSettings:
+    return AgentSettings()
+
+
+def _role_env(kind: str, role: str) -> str:
+    normalized = "".join(c if c.isalnum() else "_" for c in role).upper()
+    return f"{ENV_PREFIX}{kind}_{normalized}"
+
+
+def _resolve(kind: str, role: str) -> str | None:
+    return os.getenv(_role_env(kind, role)) or os.getenv(f"{ENV_PREFIX}{kind}_DEFAULT") or None
+
+
+def model_for(role: str | None = None) -> str:
+    """Role -> model id. Raises rather than guessing, so a misconfigured role fails loudly."""
+    resolved = role or get_settings().role
+    return _resolve("MODEL", resolved) or DEFAULT_MODEL
+
+
+def api_key_for(role: str | None = None) -> str | None:
+    """Role -> API key. ``None`` lets the vendor SDK read its own environment variable."""
+    return _resolve("API_KEY", role or get_settings().role)

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/tools/__init__.py

@@ -0,0 +1,6 @@
+"""Tool surface. Import the registry, never an individual tool module."""
+
+from .registry import TOOLS, invoke, tool_schemas
+from .spec import ToolError, ToolSpec
+
+__all__ = ["TOOLS", "ToolError", "ToolSpec", "invoke", "tool_schemas"]

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/tools/current_time.py

@@ -0,0 +1,27 @@
+"""Read-effect example: no side effect, safe to retry, needs no sandbox decision."""
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+
+from .spec import ToolSpec
+
+
+class CurrentTimeInput(BaseModel):
+    pass
+
+
+def _handler(_: CurrentTimeInput) -> str:
+    return datetime.now(UTC).isoformat()
+
+
+current_time = ToolSpec(
+    name="current_time",
+    description=(
+        "Return the current UTC time as an ISO-8601 string. Call this when the answer "
+        "depends on what time it is now — the model cannot know this from training data."
+    ),
+    schema=CurrentTimeInput,
+    effect="read",
+    handler=_handler,
+)

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/tools/registry.py

@@ -0,0 +1,44 @@
+"""THE registry.
+
+Every tool the loop can call is listed here and nowhere else — ``tests/architecture/
+test_agent_loop.py`` fails on a tool module this file does not import. ``guard`` is applied
+on the way in, so a write-effect tool cannot skip the sandbox.
+"""
+
+from typing import Any
+
+from pydantic import ValidationError
+
+from ..sandbox import guard
+from .current_time import current_time
+from .spec import ToolError, ToolSpec
+from .write_note import write_note
+
+TOOLS: tuple[ToolSpec, ...] = tuple(guard(tool) for tool in (current_time, write_note))
+
+_BY_NAME = {tool.name: tool for tool in TOOLS}
+if len(_BY_NAME) != len(TOOLS):
+    raise RuntimeError("Duplicate tool name in the registry.")
+
+
+def tool_schemas() -> list[dict[str, Any]]:
+    """The wire schema the model sees, generated from the same model the handler validates."""
+    return [
+        {"name": tool.name, "description": tool.description, "input_schema": tool.json_schema()}
+        for tool in TOOLS
+    ]
+
+
+async def invoke(name: str, raw_input: Any) -> str:
+    """Validate then run. Input comes from the model, so a handler never sees a bad shape."""
+    tool = _BY_NAME.get(name)
+    if tool is None:
+        raise ToolError(f'Unknown tool "{name}".')
+
+    try:
+        payload = tool.schema.model_validate(raw_input or {})
+    except ValidationError as error:
+        raise ToolError(f'Invalid input for "{name}": {error}') from error
+
+    result = tool.handler(payload)
+    return str(await result if hasattr(result, "__await__") else result)

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/tools/spec.py

@@ -0,0 +1,29 @@
+"""What a tool is. The registry accepts nothing that does not satisfy this shape."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+# ``read`` is replayable and safe to retry; ``write`` changes something outside this process
+# and cannot be undone. The registry routes every ``write`` through the sandbox on that
+# basis, so this field is the security boundary — not documentation.
+ToolEffect = Literal["read", "write"]
+
+
+class ToolError(Exception):
+    """Reported back to the model as a tool result, never raised out of the loop."""
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    # Say when to call it, not just what it does — the model picks tools from this text.
+    description: str
+    schema: type[BaseModel]
+    effect: ToolEffect
+    handler: Callable[[Any], Awaitable[str] | str]
+
+    def json_schema(self) -> dict[str, Any]:
+        return self.schema.model_json_schema()

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/tools/write_note.py

@@ -0,0 +1,36 @@
+"""Write-effect example.
+
+It does NOT consult the sandbox itself — the registry wraps every write-effect tool, so a
+tool author cannot forget the gate.
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from ..settings import get_settings
+from .spec import ToolSpec
+
+
+class WriteNoteInput(BaseModel):
+    text: str = Field(min_length=1, max_length=2000, description="The line to append.")
+
+
+def _handler(payload: WriteNoteInput) -> str:
+    stamp = datetime.now(UTC).isoformat()
+    with Path(get_settings().note_path).open("a", encoding="utf-8") as handle:
+        handle.write(f"{stamp} {payload.text}\n")
+    return "noted"
+
+
+write_note = ToolSpec(
+    name="write_note",
+    description=(
+        "Append a line to the run note. Call this to record a decision the user should see "
+        "later. This changes state outside the process and cannot be undone."
+    ),
+    schema=WriteNoteInput,
+    effect="write",
+    handler=_handler,
+)

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/trace.py

@@ -0,0 +1,33 @@
+"""Structured trace of the loop.
+
+Every turn, tool call, cap breach, and sandbox decision goes through here. A loop you
+cannot replay after the fact is a loop you cannot debug or bill accurately.
+"""
+
+import json
+import sys
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from .settings import get_settings
+
+
+# One JSON object per line — greppable on a terminal, ingestable by any log pipeline.
+def _default_sink(event: dict[str, Any]) -> None:
+    print(json.dumps(event), file=sys.stderr)
+
+
+_sink: Callable[[dict[str, Any]], None] = _default_sink
+
+
+def set_trace_sink(sink: Callable[[dict[str, Any]], None]) -> None:
+    """Swap in an OTel span emitter, a database writer, or a test spy."""
+    global _sink
+    _sink = sink
+
+
+def trace(event: str, **fields: Any) -> None:
+    if not get_settings().trace_enabled:
+        return
+    _sink({"at": datetime.now(UTC).isoformat(), "event": event, **fields})

package/templates/architectures/agentic-tool-loop/files/src/agent/config.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * The one typed default table for the loop. No other module under `src/agent/` may read
+ * `process.env` or write a cap as a numeric literal — `scripts/check-agent-loop.mjs` fails on both.
+ */
+const EnvSchema = z.object({
+  /** Role name, not a model id. `modelFor`/`apiKeyFor` resolve the id and key from it. */
+  AGENT_ROLE: z.string().min(1).default('{{ agentRole }}'),
+
+  // Hard caps. An unbounded loop is the top cause of runaway agent spend, so these are
+  // ceilings the loop enforces itself — not hints handed to the model.
+  AGENT_MAX_TURNS: z.coerce.number().int().min(1).default({{ maxTurns }}),
+  AGENT_MAX_TOTAL_TOKENS: z.coerce.number().int().min(1).default({{ maxTotalTokens }}),
+  AGENT_MAX_OUTPUT_TOKENS: z.coerce.number().int().min(1).default({{ maxOutputTokens }}),
+  AGENT_TOOL_TIMEOUT_MS: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .default({{ toolTimeoutSeconds }} * 1000),
+  AGENT_REQUEST_TIMEOUT_MS: z.coerce.number().int().min(1).default(120_000),
+
+  /** Policy for tools whose effect cannot be undone. Never defaults to `allow`. */
+  AGENT_SANDBOX_MODE: z.enum(['deny', 'dry-run', 'allow']).default('{{ sandboxMode }}'),
+  // stringbool, not coerce.boolean — `Boolean("false")` is true, so the off switch never worked.
+  AGENT_TRACE_ENABLED: z.stringbool().default(true),
+
+  /** Where the example write-effect tool appends. Tools keep no paths of their own. */
+  AGENT_NOTE_PATH: z.string().min(1).default('agent-notes.log'),
+});
+
+export type AgentConfig = Readonly<z.infer<typeof EnvSchema>>;
+
+function load(): AgentConfig {
+  const parsed = EnvSchema.safeParse(process.env);
+  if (!parsed.success) {
+    // Fail at boot, not on the turn that happens to exceed a cap nobody validated.
+    const detail = parsed.error.issues
+      .map((issue) => `  ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('\n');
+    throw new Error(`Invalid agent environment:\n${detail}`);
+  }
+  return Object.freeze(parsed.data);
+}
+
+export const agentConfig = load();
+
+/** Only provider with a safe default; any other must set AGENT_MODEL_DEFAULT. */
+const DEFAULT_MODEL = 'claude-opus-4-8';
+
+const envName = (kind: string, role: string) =>
+  `AGENT_${kind}_${role.replace(/[^a-zA-Z0-9]/g, '_').toUpperCase()}`;
+
+/** Role -> model id. Throws rather than guessing, so a misconfigured role fails loudly. */
+export function modelFor(role: string = agentConfig.AGENT_ROLE): string {
+  const resolved =
+    process.env[envName('MODEL', role)] ?? process.env.AGENT_MODEL_DEFAULT ?? DEFAULT_MODEL;
+  if (!resolved) throw new Error(`No model configured for role "${role}".`);
+  return resolved;
+}
+
+/** Role -> API key. `undefined` lets the SDK read its own environment variable. */
+export function apiKeyFor(role: string = agentConfig.AGENT_ROLE): string | undefined {
+  return process.env[envName('API_KEY', role)] ?? process.env.AGENT_API_KEY_DEFAULT;
+}

package/templates/architectures/agentic-tool-loop/files/src/agent/index.ts

@@ -0,0 +1,8 @@
+/** Public surface of the agent. Callers import from here, never from `loop` or `model`. */
+
+export { agentConfig, modelFor } from './config.js';
+export { type RunResult, run, type StopReason } from './loop.js';
+export { decide, type SandboxDecision } from './sandbox.js';
+export { listTools, toolSchemas } from './tools/registry.js';
+export { defineTool, type ToolDefinition, type ToolEffect } from './tools/types.js';
+export { setTraceSink, type TraceEvent } from './trace.js';

package/templates/architectures/agentic-tool-loop/files/src/agent/loop.ts

@@ -0,0 +1,117 @@
+import { agentConfig } from './config.js';
+import { type Message, nextTurn, type Turn } from './model.js';
+import { invoke, toolSchemas } from './tools/registry.js';
+import { ToolError } from './tools/types.js';
+import { trace } from './trace.js';
+
+export type StopReason = 'end_turn' | 'max_turns' | 'max_total_tokens' | 'refusal';
+
+export interface RunResult {
+  text: string;
+  stopReason: StopReason;
+  turns: number;
+  totalTokens: number;
+  messages: Message[];
+}
+
+/**
+ * The loop: repeat while the model asks for a tool, and stop unconditionally at the caps.
+ * Both ceilings are checked BEFORE the request that would breach them — a cap tested after
+ * the call has already been paid for.
+ */
+export async function run(prompt: string, system: string): Promise<RunResult> {
+  const messages: Message[] = [{ role: 'user', content: prompt }];
+  const tools = toolSchemas();
+  let turns = 0;
+  let totalTokens = 0;
+
+  trace('run.start', { caps: capsSnapshot() });
+
+  while (true) {
+    if (turns >= agentConfig.AGENT_MAX_TURNS)
+      return stop('max_turns', messages, turns, totalTokens);
+    if (totalTokens >= agentConfig.AGENT_MAX_TOTAL_TOKENS) {
+      return stop('max_total_tokens', messages, turns, totalTokens);
+    }
+
+    const turn = await nextTurn({
+      system,
+      messages,
+      tools,
+      maxOutputTokens: agentConfig.AGENT_MAX_OUTPUT_TOKENS,
+    });
+
+    turns += 1;
+    totalTokens += turn.usage.input_tokens + turn.usage.output_tokens;
+    trace('turn.end', { turn: turns, stopReason: turn.stop_reason, totalTokens });
+
+    messages.push({ role: 'assistant', content: turn.content });
+
+    // Safety classifiers can decline with HTTP 200 — check before reading content.
+    if (turn.stop_reason === 'refusal') return stop('refusal', messages, turns, totalTokens);
+    if (turn.stop_reason !== 'tool_use')
+      return stop('end_turn', messages, turns, totalTokens, turn);
+
+    messages.push({ role: 'user', content: await runToolCalls(turn) });
+  }
+}
+
+/** All results go back in ONE user message; splitting them trains the model out of parallel calls. */
+async function runToolCalls(turn: Turn) {
+  const calls = turn.content.filter((block) => block.type === 'tool_use');
+  return Promise.all(
+    calls.map(async (call) => {
+      const started = Date.now();
+      try {
+        const content = await withTimeout(invoke(call.name, call.input), call.name);
+        trace('tool.ok', { tool: call.name, ms: Date.now() - started });
+        return { type: 'tool_result' as const, tool_use_id: call.id, content };
+      } catch (error) {
+        // A failed tool is reported back, never dropped: the model needs it to change course.
+        const message =
+          error instanceof ToolError ? error.message : `Tool failed: ${String(error)}`;
+        trace('tool.error', { tool: call.name, ms: Date.now() - started, message });
+        return {
+          type: 'tool_result' as const,
+          tool_use_id: call.id,
+          content: message,
+          is_error: true,
+        };
+      }
+    }),
+  );
+}
+
+function withTimeout<T>(work: Promise<T>, tool: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new ToolError(`"${tool}" exceeded its time budget.`)),
+      agentConfig.AGENT_TOOL_TIMEOUT_MS,
+    );
+    timer.unref?.();
+  });
+  // Cleared on settle: a long loop otherwise accumulates one live timer per tool call.
+  return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+
+const capsSnapshot = () => ({
+  maxTurns: agentConfig.AGENT_MAX_TURNS,
+  maxTotalTokens: agentConfig.AGENT_MAX_TOTAL_TOKENS,
+  maxOutputTokens: agentConfig.AGENT_MAX_OUTPUT_TOKENS,
+});
+
+function stop(
+  stopReason: StopReason,
+  messages: Message[],
+  turns: number,
+  totalTokens: number,
+  turn?: Turn,
+): RunResult {
+  trace('run.stop', { stopReason, turns, totalTokens });
+  const text = (turn?.content ?? [])
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+  return { text, stopReason, turns, totalTokens, messages };
+}