Engel's Code Design Notebook

PR #3673 adds a built-in tool that consults a saved oracle LLM profile for a one-shot answer — stateless, no history, no tools, and the agent's own active model is never changed. Why it's not switch_llm and not a subagent, with a code-grounded mechanism trace.

The OpenHands docs PR that untangles the old "Agent Canvas = UI+backend blob" into four honest nouns after the repo migration: Canvas is the client, Agent Server (in the SDK repo) is the runtime, Automation Server schedules, and Sandbox Server is community-only. What moves where, page by page, grounded to the diff — plus the feline review.

The agent-server persists the whole agent config twice. The duplicate source of truth reverted a restored conversation's LLM config and doubled the trajectory secret leak. A source-grounded trace of where the copy is made, and the case for one owner.

The decision note: (a) exclude the agent from the stored record, (b) a minimal "base_state wins" patch, or (c) stop the stored record from being a create-request at all. Compared field by field, with the resume/reattach edge resolved — and why (c) wins.

The model writes sandboxed JS that orchestrates tool calls. What it needs, what the OpenHands SDK sends and parses today, and the two-sided gap that silently stops the loop. Combined show-me + teach-me, with a quiz.

Load tool schemas on demand to cut prompt tokens while preserving the cache. Why it's a clean greenfield add for the SDK's fat toolset. Combined show-me + teach-me, with a quiz.

Persistent socket + incremental inputs for ~40% faster tool-heavy rollouts — and the cheap previous_response_id Phase 0 the SDK can adopt today. Combined show-me + teach-me, with a quiz.

The model spawns subagents server-side — but the SDK already ships a portable client-side subagent system. A design decision, not just a gap: who orchestrates. Combined show-me + teach-me, with a quiz.

The primary channel — Baileys multi-device, a SQLite-backed poll loop, scopes and permissions, image/audio/document handling, and voice notes.

Socket Mode bridge — a real Slack app with thread tracking, access control, and guest rate limiting, now managed by the bridge loader.

How the Discord ingress receives messages and dispatches to the agent server via the shared bridge adapter.

A Cloudflare Worker GitHub App + @smolpaws mention poller — each issue/PR maps to one durable conversation, so pings in a thread resume the same context.

Design proposal: lift the primary channel out of the repo root into a standalone apps/whatsapp on the durable Message Relay — following the Slack pattern, starting as its own process, and losing none of the SQLite store, scopes, scheduler, or media. bead smolpaws-kxa · P0

Implementation record: a SmolPaws that runs inside the OpenHands UI — a three-pose avatar driven off live agent status, a “call the cat” button that opens a smolpaws-tagged conversation, and a local-environment identity injected via the agent-server system suffix. Where it lives, how big it is, and the decisions on record. epic smolpaws-08f · v1

The same cat as user stories: how you find it, click to call it, what the smolpaws:insider tag means and does, reading its mood from the three poses, what it knows the moment it wakes, and what starting realtime voice will feel like. Behavior only — with screenshots, and honest about what's shipped vs still design. epics smolpaws-08f · 3e1 · s9e

Design: the insider cat grows a job — a board that manages the user's conversations (dispatch, track, act), spoken to in realtime voice, shipped as an Agent Canvas Skin. Grounded in rbren's manager, the Skins PR #16232, and a working /v1/chat/completions that runs the whole agent as an LLM. epics smolpaws-08f · 3e1

The architecture decision the whole cutover rests on — keep the agent-server upstream-shaped and put durable channel intake and delivery in a small local coordinator. The Message Relay that Slack already uses and WhatsApp is moving to.

The living maintenance map behind the cutover: one canonical pin, bounded drift intervals, tests-first porting, and generated Python OpenAPI oracles keeping the new stack faithful to upstream.

The wire-by-wire migration map for hooking smolpaws to the new package — every symbol it imports, where it lands in the fresh transpile, and what's clean, renamed, to-port, or a deviation to decide. Plus the Aug 30 decisions: plain text now ends a turn, send_message becomes an SDK tool, and the running Slack path is already on the new transpile.

The RFC wants Read/Run/Admin roles for a shared Canvas — genuinely useful against remote callers. But agent-server = agent-sdk = the docker sandbox = the remote (cabin) = the local Mac: one nested runtime. So the root key that mints scoped tokens must arrive inside the sandbox where the agent's own bash runs. What roles fix, what stays (key sprawl across browsers/iPad), the config file the server reads, and the boundary that only an out-of-sandbox control plane could give. Source-grounded to the live agent-sdk.

How an Agent Server installs UI bundles and Canvas loads them as same-realm JavaScript: manifest, adapter, registry, lifecycle, and staged-update patterns—plus the security boundary that does not exist, the contracts already drifting, and the work required before this is honestly a platform.

A read-only review across thirteen subsystems found ten actionable ownership and state-model seams: backend-scoped settings and MCP health, order-independent events, durable form edits, source-driven workspace views, honest Home launch state, canonical wire types, and instance-safe embedding.

A whole-repository, evidence-first review: fourteen explicit scopes and twenty provisional opportunities, independently reduced to five lean correctness and security findings. The carrying pattern is identity drift — one real operation gaining multiple keys or owners.

The living maintenance map: one canonical pin, bounded drift intervals, tests-first porting, generated Python OpenAPI oracles, SDK wire goldens, and clear policy for deviations and exclusions.

An area-by-area synthesis of v1.29.2 → v1.42.1: the Python prompt registry, the conversation tree, LLM provider connections, agent-server telemetry/plugins/gateway, and the public surface that was removed.

The architecture decision record for SmolPaws message reliability: keep the OpenHands agent-server upstream-shaped and put durable channel intake and delivery in a small local coordinator, borrowing Automation's table-as-queue mechanics and Hermes's per-session lane policy. Status: proposed.

Live test results: which OpenAI-compatible clients work with the agent-server's /v1/chat/completions endpoint. Curl, Python SDK, LibreChat, Open WebUI, Pipecat.

End-goal architecture for exposing the OpenHands agent-server as an OpenAI-compatible model endpoint.

Current warm-pool deferred-init flow, PR 400-style app-state DI, and a safer runtime-context pattern.

How JSON tool specs become SDK tools, WebSocket action events, acknowledgement observations, and persisted client-side execution hooks.

Issue #15298, verified: reference-only persistence, typed brokers, the real stdio MCP boundary, runtime-visible fallbacks, current-code seams, and a migration plan.

How automation definitions, cron and webhook triggers, tarball storage, dispatch, sandboxes, callbacks, and watchdog reconciliation fit together.

Responsibility map: SmolPaws core does not import it; Agent Canvas depends on its browser-safe agent-server clients. What to keep, what overlaps the transpiled SDK, and where the Work Coordinator must not couple.

How NousResearch's Hermes structures its multi-platform gateway, 28 platform adapters, and the OpenAI-compatible endpoint that turns an agent into an LLM.

Deep dive into the Hermes plugin system: how platforms, tools, and providers are registered with zero core code changes. Lessons for OpenHands agent-sdk extensibility.

Bot API 10.1 rich messages, streaming drafts, capability latching, approval flows, and notification volume control. The patterns worth adopting.

The current state of voice tech: STT, TTS, real-time conversation, and the two architectures for giving an agent a voice.

How executor's e2e harness records a test: Playwright video, asciicast terminal capture, a focus timeline derived from operations, watchable slow-mo, and an ffmpeg splice into one film.

How per-tool React visualizers plug into the conversation event renderer, plus a follow-up addon path for custom renderers.

PR #2911 map: separate guardrail LLM, ToolShield safety experiences, data flow, risk labels, bypass hardening, and review edges.

PR #4332 before/after: a model repeating the same failing tool call used to hit terminal STUCK at 3 tries — now it gets one corrective nudge and a self-correction window first, and only goes STUCK if it repeats once more.

Architecture review: monitorTurn and monitorConversationTurn run the same agent-server poll loop twice and have drifted. Deepen one, delete the other.

Interactive walkthrough of the smolpaws change that lets a group talk to the cat without an @mention — background, intuition, code, and a quiz to check you understood.

How a conversation call forks on getActiveBackend().kind — ConversationClient direct to the local agent-server vs callCloudProxy (direct app-host or proxied sandbox), and why pause differs from interrupt.

The wire-by-wire migration map — every symbol smolpaws imports from agent-sdk 0.10, where it lands in the fresh TS transpile (0.1), and what's clean / renamed / to-port / a deviation to decide. The hookup, not a rewrite.

Design comparison — the TS transpilation stores a keyring reference, the Python SDK stores an encrypted value on disk. The core difference, per-OS support, the Docker question, and whether the Fernet cipher can be dropped (feature request #3988).

Interactive study page: what in the current Canvas UI is cloud-specific, why it exists, where the code lives, and a quiz to check the model stuck.

Minimal OpenHands app_server slice for Agent Canvas: sandbox orchestration, sandbox-hosted agent-servers, WebSocket streaming, and gateway gaps in the current PRs.

Interactive lesson for PR #1561: background, intuition, code walkthrough, and a quiz on app API vs runtime proxy routing.

Before/after map of PR #1561: direct cloud app APIs are split from the remaining legacy runtime sandbox proxy calls.

Architecture of the extracted FastAPI bridge: session-key auth, app-conversation metadata, sandbox runtime proxying, WebSocket tunnels, and temporary settings compatibility.

Source-grounded history across local, Docker, remote, and Cloud backends: who owned profile state, why the last selection powered the next conversation, and where teams broke.

Current composer UX, four persistence options, and one invariant: an LLM selection applies to the conversation currently shown and is remembered for future conversations.

Why the split between raw Cloud LLM settings and agent-server profiles is tech debt, and how profiles become the shared user-facing contract.

Sortable reviewer activity dashboard — who reviews what across OpenHands repositories.

A daily newspaper of where I was pinged on GitHub — review requests and mentions first, the rest below. Regenerated each morning.