Engel's Code Design Notebook

126 Agent Server and SDK fix PRs, with current snapshot statuses. Read short summaries, filter by feature or status, and open each pull request.

The project’s verification and repair loop: map the behavior, reproduce a bug, prove a fix, and update the map. Start with the five-minute explainer, built from the ground up around one real bug, then explore the Agent Server, core SDK and OpenHands app work.

Agent Canvas has its own feature map and browser-driving CLI. See how agents use the real app, reproduce defects, and prove fixes with before/after evidence.

778 behaviors across 28 families, written as named mini scripts: Given, Do, Expect. Find a scenario or bug, see missing prerequisites and known failures, and open the exact CLI recipe.

A short film about the verify-agent-server skill and the evidence-backed feature map it keeps tied to the running server.

The tracked 118 issues posted by enyst and smolpaws since 5 October: 30 remain open, 16 have an active own-author PR, and 14 do not. Ten have no own-author implementation PR in any state. Every matched PR has its author and current state.

80 issues posted by enyst and smolpaws on October 4–11 are now closed by merged PRs: 64 by those accounts and 16 by others. Every issue links its closing PR and author; one partial tracker is labeled.

26 issues posted by enyst and smolpaws on October 4–11 remain open. 25 have an open PR and one does not. Each issue shows its open PR count, titles and authors, including drafts.

2 Keep candidates and 32 Close candidates, with links, titles, authors and reasons. Three heads changed since the previous snapshot, including #17970; their earlier assessments are historical. Ten merged and nine already closed submissions are separate.

38 issues from the earlier open list still lack an identified implementation PR by enyst or smolpaws. Thirteen left the list after closing or gaining an own-author PR. Current statuses are refreshed; the original October 4–11 closure tally is retained.

28 open PRs in five OpenHands repositories. See what each changes, its latest review, checks, and next step.

What the cf beta changes for Liberty Labs: prebuilt releases, local D1, credentials, and privacy checks. A source-linked assessment and a bounded trial before changing the deployment workflow.

57 live requests: issue triage, TOCTOU and supply-chain screening, personal relevance, and evidence sufficiency. Three reproducible typed examples.

137 desktop and mobile screenshots from OpenHands PR #17435's Tailwind theme migration and shadcn-lint trial. Real conversations, workspace edits, settings, and automation screens — with page-by-page coverage, observed defects, and explicit testing gaps.

Two verified approval contradictions, independent code checks, and a proposed OpenHands automation that scores reviews without confusing bad paperwork with bad code.

All 648 open issues across OpenHands, software-agent-sdk, and automation — clustered by demand and weighted by signal (comments × reactions), then split into two lenses: the whole community, and the wide community (non-maintainers). Routed to Engel's attention or relayed to other maintainers by passion-fit.

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.

A dated record of scheduled AI code reviews posted on behalf of Engel Nyst, with the reviewed pull request, commit, review, and summary.

Autonomous investigations by OpenHands, selected from public code and discussions.

A source-grounded look at Docker networking, Canvas-advertised service URLs, and the context an agent uses to reach host services, based on SDK PR #5164.

Learn the current @cloudflare/codemode package: code composition, sandbox boundaries, durable approval replay and saved scripts. Two interactive traces, five quiz questions, then a comparison with Xingyao Wang’s CodeAct paper.

People log in. Agents use keys. One DO bridge for desktop and browser Canvas, saved OAuth sign-in, safe restart recovery, and the existing admin key for agents. New-browser approval and loopback handling are explicit release checks.

Two broken profile paths, one proposed dispatch-time launch boundary, and the tools-and-secrets gate before OHE rollout. A visual reading of automation #600, with worked cases and the alternatives kept separate.

Design rules an agent can check and act on. Browse the work by area, with Previous / Next navigation and all54 Before/After films retained. 68 tracked proposals:65 merged,3 open. Fresh main:323 warnings /0 errors. Dialog constraints #19161 and scoped enforcement #19163 are merged; compact metadata #19166 removes 45 findings and is green with bot review requested. Each film keeps its Slack download and source evidence.

The agent saves notes and chooses when to call condense. Two sequence diagrams trace that reset and the separate emergency summarizer, with warning thresholds, configuration and the context each path leaves behind.

Graham Neubig's plan for turning OpenHands OSS work into an autonomous software factory: profile-scoped Docker workers, four independent automations (triage → develop → review → watchdog-merge), and complete setup and operation through Agent Canvas. A mirror of his document — required outcome, existing machinery, the PRs each change needs, review/release order, and validation against the Box and Airbnb clones.

A decision record, not a survey: what we chose to adopt from Lauren Tan's (@poteto) pstack — verification-as-infrastructure and her two verification-skill generators (now in .agents/skills/), a feature map + control-app CLI for the product surfaces, and the SDK's projection oracle left as its own lever. Includes how to use it and how it maps onto Graham Neubig's four software-factory bottlenecks.

The CLI behind the verify-openhands skill (OpenHands PR #17961): isolated stacks, a browser that persists across commands, verbs for what screenshots miss, and an evidence ledger. Its commands, why an agent is better off with it than running the app directly, and how 36 parallel fix agents and their reviewers used it: 3,454 calls, 170 launches and 261 before/after screenshots.

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 former root process — Baileys multi-device, a SQLite-backed poll loop, scopes and permissions, media, and voice notes. Kept as architecture history; the standalone relay bridge now serves the primary channel on the shared server.

Socket Mode bridge paws — a standalone process on the durable Message Relay and the TypeScript agent-server, with thread tracking, access control, and guest rate limiting. The first channel on the new stack.

The legacy Discord adapter on the /turns runner, kept as history. The standalone relay rewrite has merged; a live check remains.

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.

The original design for agent-owned notes, staged warnings and a fresh context. Kept as design history; the implementation guide above explains the shipped mechanism.

The current TypeScript contract: shared role/scope configuration, saved profiles and private credentials, native provider APIs, safe switching, usage accounting, tests and the separate GitHub LLM environments. Source-verified September 16.

Main, OpenHands and Hunting moved to the normal shared server on September 17, preserving their conversations. Current storage paths and cutover verification, with the earlier iPad canary evidence kept separately.

One TypeScript OpenHands agent-server and standalone relay bridges. WhatsApp now uses the normal shared host; other ingress migrations remain separate. Process boundaries, dated deployment evidence and operational ownership.

The design that moved the primary channel out of the repo root into a standalone apps/whatsapp on the durable Message Relay — implemented on the shared relay runtime and promoted to normal operation on September 17. bead smolpaws-kxa · P0

A Cat beside your work: saved OpenHands conversations, normal tools and skills, and Voice that hands requests to the same agent. Current development behavior, checked 31 October.

Start or resume a Cat, move between Projects and chat, use Voice, inspect tool results, correct a request, and shorten context with /condense.

Historical design for a conversation-management board and voice companion. The separate Insider Cat page describes the current Canvas App and its saved OpenHands conversations.

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 now shared by the standalone Slack, WhatsApp and Discord implementations.

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.

Historical symbol inventory and August 30 decisions. Current contracts and provider guidance are linked from the maintenance page; current operational gates are in WhatsApp readiness.

PR #5758: previous-key decryption, safe re-encryption, and protection against overwriting secrets when a key is missing.

Extend the SmolPaws GitHub Worker with a separate hosted-agent module: Codex and Claude managed APIs, cron and D1 recovery, direct requests, and attributed replies.

What the external verifier checks, what its first Cloud run found, and what a regular contract check still needs. The Cloud automation is disabled.

How Codex applies repository instructions from the working directory while Claude rules can follow the path of each touched file, and where those trigger models differ.

Why a conversation resumed across Agent Server versions with 5,814 events intact but only its last 165 in context: the first new event was stamped as a hard tree root.

A focused before-and-after view of PR #4465’s FinishTool prompt change and structured task_outcome response, with FinishAction unchanged.

A comparison of Hermes’s MIT-licensed skill crystallization process with how SmolPaws consolidates its own memory.

How root AGENTS.md maps and package instructions work today, and how file-operation triggers could load the applicable nested instructions deterministically.

How SDK #3964 and Canvas #1583 add a typed path to capture, encrypt, persist, and reuse MCP credentials across local and cloud conversations.

OpenHands Automation’s single completion callback alongside SmolPaws’ durable per-message delivery queue, including where PR #4465’s TaskOutcome fits.

How OpenHands uses one structured outcome for agent-reported completion and system or harness failure, distinguished by a source field.

An explainer on what typescript-client does, who uses it, how it stays in sync with the Python SDK, and the proposed repository move.

Research comparisons, with sources and limits kept close to the claims.

A comparison of SWE-Milestone and SlopCodeBench: inherited regressions, structural erosion, session continuity, and what their numbers measure.

A low-fidelity chooser for Agent Server and Cloud backends, with the connection fields each path needs.

A testing strategy for the OpenHands Agent SDK when humans no longer read PRs: separately governed architectural contracts, independent REST/WS verification, stateful and mutation testing, and a recurring self-healing loop. The complete response, reproduced verbatim.

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: accepted and implemented as the Message Relay.

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.

The September 15 operating snapshot: three local jobs, six enabled Cloud jobs, two paused jobs, what each can change, recent results, and decisions still to make.

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.

June 2026 voice landscape, retained as historical background. Current Insider Cat Voice behavior and setup are documented with the App.

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 of the legacy /turns client: monitorTurn and monitorConversationTurn ran the same poll loop twice. Moot once the legacy runner retires; kept as history.

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.

Historical wire-by-wire migration map from agent-sdk 0.10 to the fresh transpile, kept for the Aug 30 decisions in its last section. Full ingress cutover remains tracked in the current readiness plan.

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.