papers/hanzo-harness-hacking/sections/07-multi-component-architecture.tex

\section{Multi-Component Architecture}

\label{sec:architecture}

\subsection{Hackable Components and Their Interfaces}
\label{sec:components}

Table~\ref{tab:components} summarizes the components that an agent running HHP
can modify, organized by Tier eligibility.

\begin{table}[H]
\centering
\begin{tabularx}{\textwidth}{l l X X}
\toprule
Component & Path & Purpose & Min Tier \\
\midrule
Bot extensions & \texttt{bot/bot/extensions/} & Per-agent tools and services & 2 \\
MCP tools & \texttt{hanzo/mcp} & 260+ model context protocol tools & 4 \\
Agent SDK & \texttt{hanzo/agent} & Multi-agent orchestration & 4 \\
LLM Gateway & \texttt{hanzo/llm} & Unified provider proxy & 4 \\
Operative & \texttt{hanzo/operative} & Computer-use / screen control & 4 \\
GRPO pipeline & \texttt{zoo/gym} & Experience extraction training & 4 \\
Skill library & \texttt{bot/skills/} & Declarative knowledge base & 3 \\
Model configs & \texttt{zen/gateway/config.yaml} & Routing and model parameters & 4 \\
\bottomrule
\end{tabularx}
\caption{Hackable components in the Hanzo ecosystem. ``Min Tier'' indicates the
minimum trust tier required to modify that component.}
\label{tab:components}
\end{table}

\subsection{Extension Architecture}
\label{sec:ext-arch}

Bot extensions follow a plug-in pattern with three required files:

\begin{enumerate}[leftmargin=1.5em]
    \item \texttt{package.json}: Declares the package name, version, entry
          point, and peer dependencies on the bot runtime.
    \item \texttt{index.ts}: Exports a \texttt{BotPlugin} implementing the
          \texttt{setup(api)} method.
    \item \texttt{\_\_tests\_\_/}: Jest test suite that must achieve 100\%
          pass rate before registration.
\end{enumerate}

The \texttt{setup} method has access to the full \texttt{PluginAPI} surface:
tool registration, service registration, event hooks (\texttt{on('task:start')},
\texttt{on('task:end')}, \texttt{on('session:end')}), and skill registration.

\subsection{Cross-Component Worktree Workflow}
\label{sec:worktree-workflow}

For Tier 4 modifications, the full workflow is:

\begin{enumerate}[leftmargin=1.5em]
    \item \textbf{Isolate:} \texttt{git worktree add /tmp/hack-\$ID origin/main}
          in the target repository.
    \item \textbf{Modify:} Agent writes changes in \texttt{/tmp/hack-\$ID}.
          All edits are tracked by git.
    \item \textbf{Test:} Agent runs the component test suite within the worktree:
          \texttt{cd /tmp/hack-\$ID \&\& pnpm test} (or equivalent).
    \item \textbf{Push:} Agent creates a branch and pushes:
          \texttt{git checkout -b agent/hack-\$ID \&\& git push origin HEAD}.
    \item \textbf{PR:} Agent opens a pull request via \texttt{gh pr create}
          with a machine-generated description including the originating friction
          event, test results, and performance delta.
    \item \textbf{Review:} CI runs automatically. Human reviewer examines the
          diff and either approves or requests changes.
    \item \textbf{Cleanup:} \texttt{git worktree remove --force /tmp/hack-\$ID}
          regardless of PR outcome.
\end{enumerate}

This workflow ensures that the agent's productive session is never blocked on
PR review: the agent submits the PR and continues with the session; the harness
improvement takes effect in a subsequent session once merged and deployed.

\subsection{MCP Tool Development}
\label{sec:mcp-tools}

The MCP tool server~\cite{anthropic2024mcp} exposes tools via the Model Context
Protocol. An agent wishing to add a new MCP tool proceeds through Tier 4:

\begin{verbatim}
// New MCP tool skeleton (generated by agent in worktree)
export const newTool: Tool = {
  name: "tool_name",
  description: "...",
  inputSchema: { type: "object", properties: { ... } },
  handler: async (input) => {
    // implementation
    return { content: [{ type: "text", text: result }] };
  },
};
\end{verbatim}

The tool is registered by adding it to the appropriate tool index file, then
the change goes through the Tier 4 workflow. If merged, the new tool becomes
available to all agents using the shared MCP server on next deployment.

% ============================================================================
% 8. RISK ANALYSIS
% ============================================================================