DEV Community: Antonio Zhu

db-semantic-mcp Gives AI Agents a Safe Semantic Map of Your Database

Antonio Zhu — Tue, 11 Aug 2026 00:38:27 +0000

AI agents are getting database access before they understand databases.

That is the wrong order.

A real production database is rarely self-explanatory. The important table is not always named orders. The customer table may be called t_bd_customer. A field may carry a business-critical status code that only makes sense if you know the system behind it. A warehouse may split raw operational data, cleaned dimensions, and aggregated facts across schemas with names like ods, dw, and staging. The schema is technically visible, but the meaning is not.

So I built db-semantic-mcp: a small MCP server that gives AI coding agents a safe semantic map of a database.

It exposes table names, column types, comments, sample rows, and LLM-powered schema search. It supports PostgreSQL and SQL Server. It works with MCP-compatible agent clients such as OpenCode, Claude Code, Cursor, and similar tools.

It deliberately does not execute SQL.

That boundary is the point.

The missing layer between agents and databases

Most database integrations for agents start with query execution. Give the model a connection string, add a SQL tool, maybe add a read-only role, and let it ask the database questions.

That can be useful. It is also a big first step.

Before an agent writes or runs a query, it needs to answer more basic questions:

Which tables are relevant?
What do these column names mean?
Which schema contains source data and which contains modeled data?
Is this field a business status, a foreign key, a soft-delete marker, or an internal implementation detail?
When a user says "inventory", "receivables", "customer", or "WIP", what tables should the agent inspect?

Those are not SQL execution questions. They are database understanding questions.

db-semantic-mcp focuses on that layer. It gives the agent enough structure to navigate the database without turning the database into a remote-control surface.

What it exposes

The server provides four MCP tools:

Tool	Purpose
`list_tables`	List database tables with schema names and table comments.
`describe_table`	Inspect columns, types, nullability, and column comments.
`sample_data`	Fetch a small number of example rows from a table.
`search_schema`	Search tables and columns semantically using an OpenAI-compatible LLM.

The first three tools are direct metadata and sampling operations. They let an agent inspect the database the way a developer would: list tables, open one table, look at columns, check a few rows.

The fourth tool is where the semantic layer matters.

search_schema combines a cached schema snapshot with an optional Markdown file that describes your business terms, naming conventions, and database design decisions. The model can then resolve natural-language requests such as:

customer receivables
WIP inventory
sales order
应收账款

into the tables and columns that are likely to matter.

This is especially useful for databases where the table names are technically consistent but not obvious to an agent. ERP databases, legacy SQL Server systems, and large warehouse schemas often fall into that category.

The semantic file is intentionally boring

There is no new ontology format to learn. There is no vector database to deploy. There is no separate catalog service.

You write a Markdown file.

For example:

# Database Semantic Context

## Naming Conventions

- `ods.*` tables contain raw operational data.
- `dw.*` tables contain modeled fact and dimension tables.
- `staging.*` tables are temporary ETL staging tables.

## Business Terms

| Business term | Table(s) |
| --- | --- |
| Customer | ods.bd_customer, dw.dim_customer |
| Inventory | dw.fact_inventory_snapshot |
| WIP / work in progress | dw.fact_wip_by_lot |

## Design Decisions

- Monetary amounts are stored in integer cents.
- `_modified_at` columns are incremental sync watermarks.
- Soft deletes use `doc_status = 'D'`.

That file is loaded into the schema search prompt. It is the bridge between the database's physical structure and the vocabulary developers or business users actually use.

The important design choice is that the semantic layer stays close to the team. It can live next to the project. It can be reviewed like documentation. It can be changed without re-indexing a vector store or migrating a metadata system.

Why no SQL execution?

Because the first safe primitive an agent needs is not always a query tool.

If an agent can execute arbitrary SQL, even read-only SQL, the safety problem becomes larger immediately. You need to think about permissions, row-level access, query cost, data exfiltration, audit logs, and prompt injection through data. Those problems are solvable, but they are not free.

db-semantic-mcp takes a narrower position: give the agent visibility into structure and meaning first.

That makes the tool useful in more conservative environments. A team may be comfortable exposing table metadata, comments, and a few sample rows to an agent long before it is comfortable giving the agent a general SQL execution surface. The server still connects to the database, so it should be configured carefully, but its product boundary is intentionally smaller.

The result is not a text-to-SQL platform. It is the layer before text-to-SQL. It helps the agent understand where it is.

Built for real databases, not demo schemas

The first implementation supported PostgreSQL. The current version also supports SQL Server through the same MCP interface.

The backend is selected from the DATABASE_URL scheme:

postgresql://user:pass@localhost:5432/mydb
sqlserver://user:pass@host:1433?database=mydb&encrypt=disable

That matters because a lot of valuable business data is not sitting in a neat Postgres app database. It is in SQL Server. It is in ERP systems. It is in databases with thousands of tables, inconsistent comments, historical naming conventions, and schemas that only a few people inside the company understand.

For those databases, db-semantic-mcp includes cache controls such as schema filters and table-prefix filters. If a SQL Server database contains thousands of tables but the useful business tables share prefixes like t_pur_, t_sal_, t_stk_, or t_bd_, the schema cache can focus on those areas.

This is not about making a toy database easier to query. It is about making messy real databases navigable by an agent without pretending they are clean.

How an agent uses it

Once registered with an MCP client, the workflow is simple.

An agent can start broad:

list_tables schema=dw

Then inspect a candidate table:

describe_table table=dw.fact_inventory_snapshot

Then look at a few rows:

sample_data table=dw.fact_inventory_snapshot limit=3

Or search semantically:

search_schema keyword="customer receivables"
search_schema keyword="应收账款"

The agent does not need to guess table names from memory. It does not need the user to paste schema dumps into every prompt. It can ask the database metadata server for the relevant context, then use that context in the coding task.

For example, if the task is to modify an ETL pipeline, add a reporting endpoint, or debug a data mapping issue, the agent can first discover the database shape instead of hallucinating it.

That is the value: better grounding before action.

Configuration shape

The server is configured through environment variables:

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
SEMANTIC_FILE=/path/to/SCHEMA.md
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

LLM_API_KEY is only required for semantic search. The metadata tools work without it.

An MCP client can register it as a local server:

{
  "mcp": {
    "db-semantic": {
      "type": "local",
      "command": "pg-semantic-mcp",
      "environment": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname",
        "SEMANTIC_FILE": "/path/to/SCHEMA.md",
        "LLM_API_KEY": "sk-..."
      }
    }
  }
}

The command name still uses pg-semantic-mcp for compatibility with the original PostgreSQL-only version. The package and repository now use the broader db-semantic-mcp name because the server supports multiple backends.

What this is good for

db-semantic-mcp is useful when an agent needs database context but should not start by executing SQL.

Good fits include:

AI coding agents working on backend services connected to PostgreSQL or SQL Server.
Data platform projects where table names and business concepts are not obvious.
ERP and legacy database exploration, especially when schemas are large.
Teams that want agent-assisted development without immediately exposing query execution.
Projects where a lightweight Markdown semantic layer is easier to maintain than a full data catalog.

It is not trying to replace a BI platform, a warehouse catalog, a governance product, or a complete text-to-SQL system.

It is a small missing primitive: let the agent understand the database before it acts on the database.

The broader direction

I think agent tooling is going to split into two categories.

Some tools will make agents more powerful. They will let agents execute, mutate, deploy, administer, and automate more of the system.

Other tools will make agents better grounded. They will expose state, constraints, readiness, history, metadata, and semantics in ways that reduce guessing.

db-semantic-mcp belongs to the second category.

It does not make the agent omnipotent. It gives the agent a map. In real engineering work, that is often the safer and more useful first step.

Project: github.com/chncaesar/db-semantic-mcp

OpenCode Session Framework Internals

Antonio Zhu — Mon, 10 Aug 2026 08:22:40 +0000

The easiest way to misunderstand an agent session is to treat it as a chat API call with a longer memory. Send a prompt, receive a response, append both to a transcript. That is enough for a demo. It is not enough for a coding agent.

I ran into this while reading a small fleet client that drives remote OpenCode instances. The client does very little on the surface: create or reuse a session, send a prompt, wait for the remote agent to become idle, then fetch recent messages. The interesting part is that none of those verbs mean exactly what they mean in a normal request-response API. A prompt does not equal a response. A timeout does not mean failure. A session is not just a transcript. Status is not derived from the last line of text.

That small client is a useful entry point because it exposes the shape of the real system. OpenCode's session design is not one function that calls a model. It is a framework for admitting work, serializing execution, projecting durable state, streaming observations, and letting clients recover when a long-running agent is still in flight.

Primary code references:

opencode-fleet/src/tools.ts
opencode-fleet/src/session.ts
opencode-fleet/src/node.ts
packages/opencode/src/server/routes/instance/httpapi/groups/session.ts
packages/opencode/src/server/routes/instance/httpapi/handlers/session.ts
packages/opencode/src/session/session.ts
packages/opencode/src/session/prompt.ts
packages/opencode/src/session/run-state.ts
packages/opencode/src/session/status.ts
packages/opencode/src/session/processor.ts
packages/opencode/src/server/routes/instance/httpapi/handlers/event.ts
packages/core/src/session.ts
packages/core/src/session/input.ts
packages/core/src/session/run-coordinator.ts
packages/core/src/session/runner/llm.ts
packages/core/src/event.ts
packages/core/src/session/projector.ts

The fleet client follows the desktop-compatible OpenCode API: /session, /session/:id/prompt_async, /session/:id/message, /session/status, and /event. The newer V2/core API exposes the same architectural direction more explicitly through /api/session, /api/session/:id/prompt, /api/session/active, /api/session/:id/event, and the durable SessionInput and SessionEvent pipeline. Both matter because together they show the transition from a working client protocol to a cleaner internal runtime model.

Key Takeaways

If you are building an agent runtime, design sessions as execution containers, not as chat transcripts. A real session framework has to preserve identity, admit work, run one continuation at a time, expose observable status, persist structured messages, and make interruption and recovery normal operations.

Separate session identity from prompt execution. A session can outlive any single prompt. It owns directory, project, agent, model, title, permissions, messages, parts, and runtime state.
Treat prompt submission as admission. The client should be able to submit work and return before the agent finishes. Completion is a separate observation problem.
Serialize execution per session. Multiple prompts may arrive while the agent is busy. The runtime needs a coordinator that runs at most one drain loop per session and coalesces follow-up work.
Expose status as runtime state. Busy, idle, and retry are not reliable if inferred from text. They should come from the execution layer or from an authoritative active-session set.
Use events as the observation boundary. Clients should not poll messages to guess what happened. They should subscribe to session and message events, then keep a local projection.
Persist messages as structured state. Text is only one part. Tool calls, tool results, reasoning, files, snapshots, errors, and step boundaries need identity and lifecycle.
Make timeout, interrupt, and reset distinct. Timeout means the caller stopped waiting. Interrupt asks the runtime to stop work. Reset discards a client-side binding or context. These are different operations.

The Minimal Client Contract

The fleet client is intentionally small. It exposes MCP tools such as fleet_create_session, fleet_send_message, fleet_get_session_status, fleet_get_session_messages, fleet_interrupt_session, and fleet_reset_session. Behind those tools, there are only two main classes.

SessionManager keeps an in-memory map from node name to active session ID. It lazily creates a session on first send, reuses the same session for future prompts, and recreates a session if the server returns 404. OpenCodeNode wraps the remote HTTP API and owns a persistent SSE subscriber that listens to /event.

The important flow is short:

fleet_send_message
-> SessionManager.send
-> get or create session
-> POST /session/:id/prompt_async
-> wait for session.status idle over SSE
-> GET /session/:id/message
-> extract assistant text or tool progress summary

That flow already contains several design choices worth copying.

First, the client binds one long-lived session per remote node. It does not create a fresh session for every prompt. That preserves working context and makes follow-up prompts meaningful.

Second, sending a prompt is asynchronous. OpenCodeNode.sendPromptAsync(...) posts a user message to /session/:id/prompt_async and returns after the server accepts it. The fleet client then waits for status separately. This is the right split. If the same request both submits work and waits for the entire agent loop to finish, the client has no clean way to distinguish "the server accepted my work but the agent is still running" from "the server never accepted my work."

Third, timeout is not treated as failure. SessionManager.send(...) catches TimeoutError, fetches partial messages, marks timedOut: true, and tells the caller the remote agent is likely still running. That is exactly the behavior an agent coordinator needs. In a coding-agent runtime, a slow task is often useful work, not a broken request.

Fourth, reset is guarded. fleet_reset_session checks status and refuses to reset a busy session. This is not just user-interface caution. Resetting while a remote agent is running loses the caller's handle to in-flight work. The agent may still write files, ask for permissions, or finish with output after the caller has thrown away the session ID. A framework should make that hard to do accidentally.

The fleet implementation is not the whole OpenCode session architecture. It is a client-side adaptation. But it shows what the server must provide: stable session IDs, async prompt admission, observable status, message history, interruption, and enough structured message parts to explain progress before final text exists.

Session Creation Is Identity, Not Execution

In the desktop-compatible API, the legacy route group defines POST /session as session.create. The handler eventually calls Session.create(...), which creates a session record with an ID, slug, project, directory, path, optional workspace, title, agent, model, permissions, token counters, and timestamps. It publishes session.created through the event bridge. Projectors then write that session into SQLite.

Nothing has run yet.

That distinction is easy to miss. A session is not "the model is working." A session is the durable container in which work may later happen. It represents a place in the filesystem, a selected agent and model, permission context, and a message history boundary.

The newer V2/core path makes the same idea clearer. SessionV2.Service.create(...) resolves the project for a location, creates a Session.Info, publishes a created event, and returns the stored session. Execution is not part of creation. The session starts idle.

This matters for agent framework design because the session ID becomes the join key for everything else:

user prompts
assistant messages
tool calls
permission requests
question requests
status events
snapshots and diffs
model and agent switches
compaction checkpoints
interrupt and reset operations

If session creation also starts execution, that boundary gets muddy. If a session is only a transcript row, it will not have enough identity to support tooling, permissions, status, or recovery. A good session object should answer: where is this agent working, what policy applies, what model and agent should subsequent turns use, and which durable history does this execution belong to?

Prompt Submission Is Admission

The desktop-compatible async endpoint is /session/:sessionID/prompt_async. Its handler requires the session, then forks promptSvc.prompt(...) into the server scope and immediately returns 204 No Content.

That means the HTTP response does not mean "the assistant finished." It means "the server accepted responsibility for starting the prompt work." The actual work continues in a fiber.

Inside SessionPrompt.prompt(...), OpenCode creates a user message, stores its parts, touches the session, applies any per-prompt tool permission overrides, and then calls loop(...) unless the prompt was marked noReply. The loop is the real execution path.

The V2/core API names the same boundary more explicitly. POST /api/session/:sessionID/prompt calls SessionV2.Service.prompt(...). That service verifies the session, resolves the prompt, chooses a message ID, and calls SessionInput.admit(...). Admission publishes session.next.prompt.admitted as a durable event. Only after the input is durably admitted does the service call execution.wake(sessionID).

This is the key design move: prompt submission becomes durable input admission plus execution wakeup.

That gives the runtime several properties that a direct "call the model now" design does not have.

The prompt has an identity before the model runs. The system can reject duplicate message IDs. It can record that a prompt entered the session even if execution starts slightly later. It can choose not to resume immediately. It can queue or steer inputs. It can replay durable input history into a projected message stream. It can recover from client disconnects because the prompt is not merely an in-memory function argument.

If you are building an agent runtime, this is one of the most important principles to copy. Do not make the user's prompt disappear into a model call. Admit it into the session first. Then schedule execution.

Execution Needs A Per-Session Coordinator

Once prompts can be admitted independently from execution, the runtime needs a rule for what happens when work arrives while the session is already busy.

OpenCode has two implementations that reveal the same idea.

In the desktop-compatible path, SessionRunState keeps a per-session Runner. The runner has states such as Idle, Running, Shell, and ShellThenRun. ensureRunning(...) starts work if idle. If a run is already active, it waits for that active run instead of starting a second one. If shell work is active, it can queue a run after the shell finishes. cancel(...) interrupts the current fiber and returns the runner to idle.

In V2/core, SessionRunCoordinator is smaller and more explicit. It maintains a map from session ID to active entry. wake(sessionID) starts a drain fiber if idle. If a fiber is already running, it sets pendingWake = true. When the active fiber settles successfully, the coordinator starts a successor if a wake was recorded. interrupt(sessionID) marks the entry as stopping, clears pending wake, and interrupts the owner fiber.

That gives OpenCode an important invariant:

one session -> at most one active drain loop

Different sessions can run concurrently. The same session cannot accidentally run two provider turns against the same history at the same time.

This is not an implementation detail. It is the difference between a predictable agent session and a race condition factory. Without a per-session coordinator, two prompts can read the same context, both call the model, both write assistant messages, and both execute tools against the filesystem. In a coding agent, that is dangerous. The second prompt may assume files are unchanged while the first prompt is editing them. Tool permissions and status become ambiguous. The UI cannot honestly say what the session is doing.

The right abstraction is not a mutex around the HTTP handler. It is a session execution coordinator. It should live at the runtime layer, below all clients, so desktop, TUI, MCP clients, scripts, and external tools all obey the same rule.

The Runner Is A Drain Loop, Not One Model Call

The execution loop itself is also larger than one model call.

In the desktop-compatible path, SessionPrompt.runLoop(...) repeatedly sets the session busy, loads compacted history, finds the latest user and assistant state, handles subtasks and compaction tasks, resolves the current agent and model, builds tools, assembles system instructions, converts stored messages into provider messages, and calls SessionProcessor.process(...). The processor consumes the provider stream and updates message parts as text, reasoning, tool calls, tool results, errors, and finish state arrive. If the model asked for tools, the loop continues so the tool results can be sent back to the model.

In V2/core, SessionRunner.run(...) follows the same conceptual shape. It checks pending steer or queue inputs. runTurnAttempt(...) promotes pending input into active context, prepares system context, resolves model and tools, builds an LLM.request(...), streams provider events, publishes structured session events, settles local tools, and continues if tool calls or new steering require another turn.

The naming matters. A good agent runtime does not have a completeChat(...) function. It has a drain loop. The loop drains admitted work until the session reaches a stable idle boundary.

That loop has to deal with continuation conditions:

the model requested tools
tools finished and their results need to be sent back
new steering arrived while a turn was active
queued input is waiting
compaction is required before another provider call
the provider failed before durable assistant output existed
the user denied permission and the loop should stop
the session was interrupted

If those conditions are bolted onto a single request handler, the handler becomes impossible to reason about. OpenCode keeps them inside session execution. Clients submit work, observe events, and interrupt if needed. They do not own the agent loop.

Status Should Come From Execution, Not Transcript Guessing

The fleet client originally has a tempting fallback: inspect messages and infer busy or idle by looking for step-finish parts after the last user message. That kind of fallback is useful for compatibility, but it should not be the primary status model.

OpenCode's desktop-compatible runtime has SessionStatus. It keeps an instance-local map of non-idle sessions. set(sessionID, { type: "busy" }) publishes a session.status event and stores the status. set(sessionID, { type: "idle" }) publishes both session.status and deprecated session.idle, then deletes the session from the map. A missing status means idle.

SessionRunState calls status.set(...busy...) when a runner becomes active and status.set(...idle...) when the runner returns to idle. SessionProcessor sets busy while processing provider streams and sets retry status during retry backoff. The server exposes the status map through GET /session/status, and it also streams session.status events through /event.

The V2/core API exposes the same concept as GET /api/session/active. It returns the set of foreground drains currently owned by this OpenCode process. If a session appears there, it is running. If it is absent, it is inactive.

The lesson is simple: status should come from the execution owner.

Message history is a projection of what happened. It is not the authority for what is currently happening. A session may be busy before the first assistant step appears. A provider may be retrying without writing new visible text. A tool may be running with no final assistant answer yet. A streamed text delta may arrive before the durable final text part. If a client has to scrape messages to infer status, the runtime has failed to expose a basic operational fact.

This is why opencode-fleet keeps a persistent SSE status stream and optimistically marks a session busy immediately after prompt_async returns. There is a race window between prompt admission and the first SSE event. A client that immediately checks status should not conclude "idle" just because the event has not arrived yet.

Events Are The Observation Boundary

OpenCode clients do not need to keep asking, "what changed?" They subscribe.

The desktop-compatible /event endpoint registers an eager listener against EventV2Bridge, filters events by instance directory and workspace, emits a synthetic server.connected, sends heartbeat events, and streams JSON payloads as SSE. The global event endpoint wraps the GlobalBus and carries cross-instance events. The newer server package exposes /api/event for all server events and /api/session/:sessionID/event for durable per-session events.

That gives the desktop app and external clients a common observation model. The app's server-session.ts applies events into a local Solid store. It updates session info on session.created and session.updated, status on session.status, messages on message.updated, parts on message.part.updated, deltas on message.part.delta, permissions on permission.asked, questions on question.asked, and so on. It also reconciles optimistic local messages with confirmed server events.

This local projection is not just for UI polish. It is a fundamental architecture choice. The server owns truth. Clients maintain projections.

That separation solves several problems.

It lets a client show progress before a final response exists. It lets a client reconnect and refresh from durable history when needed. It keeps streaming deltas separate from final durable values. It lets different clients observe the same session without embedding execution logic in each client. It gives external tools a debugging path: subscribe to events, then inspect messages and parts when something looks wrong.

If you build an agent runtime without an event boundary, every client becomes a partial runtime. The UI will poll messages. The CLI will invent a different status heuristic. External tools will guess when work is done. Eventually those guesses disagree.

Messages Are Structured Projections

The most visible artifact of a session is the conversation. But OpenCode does not treat the conversation as plain text.

In the desktop-compatible projection, session messages live as message rows and part rows. A user message can contain text, files, agents, and subtasks. An assistant message can contain text, reasoning, tool parts, step markers, snapshots, patches, retries, compaction parts, and errors. A tool part has a call ID, tool name, input, status, output, metadata, attachments, and timing.

That shape is why opencode-fleet can return useful partial output when a prompt times out. If the assistant has no text yet but tool calls are running, the client can summarize tool activity instead of returning an empty string. It can say the agent is busy and list the tools in progress.

V2/core pushes this further with durable session events and projected messages. SessionInput.admit(...) records prompt admission. SessionInput.promoteSteers(...) publishes session.next.prompted. createLLMEventPublisher(...) converts provider events into session events such as session.next.step.started, session.next.text.delta, session.next.text.ended, session.next.tool.called, session.next.tool.success, session.next.tool.failed, and session.next.step.ended. SessionProjector turns those events into queryable message rows.

This creates three useful layers:

Layer	Role
Durable events	What happened, in order, with session sequence numbers
Projected messages	Query-friendly session state for UI and clients
Client store	Local observable cache, including optimistic and streaming state

That layering is more work than appending text to an array. It is also what makes a coding-agent session debuggable. If a tool failed, you can find the tool call. If a provider streamed text and then failed, you can represent partial output and final error separately. If a permission request blocked execution, it has identity. If compaction changed the context boundary, it is a session event and a message part, not an invisible truncation.

The design principle is that the transcript is a projection, not the source of truth. The source of truth is the session's structured event and message state.

Interrupt Is Not Reset

Long-running agents need lifecycle controls. OpenCode exposes several, and the differences matter.

prompt_async starts work and returns immediately. session.status or /api/session/active tells a client whether work is still running. /session/:id/abort or /api/session/:id/interrupt asks the runtime to stop active execution. Fetching messages shows what has happened so far. Resetting a client binding merely means the client stops using that session ID for future sends.

These operations should not be collapsed.

The fleet client handles this well. On timeout, it does not reset. It tells the caller the agent is still running and recommends checking status, inspecting messages, waiting, or interrupting. fleet_interrupt_session sends an abort signal but does not delete the session or clear the binding. fleet_reset_session discards the cached session ID only after checking that the session is not busy.

That behavior reflects the server-side reality. In the desktop-compatible runtime, SessionRunState.cancel(...) interrupts active fibers and cancels related background jobs. The runner transitions back to idle and status events are emitted. In V2/core, SessionRunCoordinator.interrupt(...) marks the active entry as stopping, clears pending wake, and interrupts the owner fiber. The runner then settles interrupted tools and assistant state.

A reset cannot do that. Reset is a client-side context decision. Interrupt is an execution decision. Delete is a storage decision. Timeout is a waiting decision. If your framework uses one "cancel" or "reset" button for all four, users will eventually lose work or leave orphaned execution behind.

Compatibility Is A Shell Around The Runtime

One subtle part of OpenCode's current codebase is that it has both the desktop-compatible instance API and the newer V2/core API mounted in the same process. The route tree in packages/opencode/src/server/routes/instance/httpapi/server.ts provides legacy routes such as /session/:id/prompt_async and /event, while also mounting the newer @opencode-ai/server handlers for /api/session, /api/event, and related endpoints.

That can look confusing if you read only endpoint names. It makes more sense if you separate protocol compatibility from runtime architecture.

The legacy API exists because clients depend on it. The desktop UI, generated SDKs, compatibility wrappers, CLI paths, and external tools still speak that language. It has concepts such as promptAsync, message.part.delta, and session.status.

The V2/core architecture makes the internal model more explicit. Prompt admission is a durable event. Pending inputs live in SessionInputTable. Execution is coordinated through SessionExecution and SessionRunCoordinator. Session events can be replayed per aggregate. Projectors build structured message rows from durable events.

The lesson for agent-runtime builders is not "copy these exact endpoints." The lesson is to keep the compatibility shell thin. Let old clients keep their contract, but move the runtime toward clearer boundaries: admission, execution, events, projection, and observation.

If compatibility code owns the runtime model, every old endpoint shape becomes a permanent architectural constraint. If the runtime owns the model, compatibility handlers can translate.

What To Copy

If I were designing a session framework for a new coding agent, I would copy these pieces first.

Create sessions independently from prompts. A session should be a durable execution container with location, agent, model, permissions, title, timestamps, and identity. It should be useful before anything is running.

Admit prompts before running them. Give each prompt or user message an ID. Persist it or publish it durably. Only then wake execution. That makes retries, duplicate detection, queueing, and recovery possible.

Run one drain loop per session. Do not let every HTTP request or client call start its own model execution. A coordinator should own session execution and serialize work for that session while allowing other sessions to run concurrently.

Make status authoritative. Either expose a status map or an active execution set. Busy, idle, and retry should be runtime facts, not message-history guesses.

Stream events. Clients should subscribe to server events and maintain projections. Polling can exist as a fallback, but it should not be the core observation model.

Persist structured message parts. Text alone is not enough. Tool calls, tool results, reasoning, files, errors, snapshots, and step boundaries need their own identities and states.

Design lifecycle controls separately. Timeout, wait, interrupt, reset, delete, and fork are not the same operation. Give them separate APIs and make dangerous transitions explicit.

Keep compatibility outside the core. Endpoint names will change. SDK shapes will change. Desktop and CLI needs will differ. The runtime should be stable underneath those clients.

The Core Shape

The simplest useful mental model for an agent session is this:

Session identity
  -> admitted inputs
  -> per-session execution coordinator
  -> agent drain loop
  -> structured events
  -> projected messages
  -> client-side observable state

That shape is more complicated than a chat completion wrapper. But the complexity is paying for real product requirements: long-running work, tool execution, concurrent clients, interruption, retries, partial output, permissions, compaction, and debugging.

The mistake is to start with the provider API and build upward. Provider APIs know how to produce tokens and tool-call requests. They do not know what a session means in your product. They do not know how to serialize work per project directory. They do not know when a client timed out but the agent is still running. They do not know how your UI should reconcile optimistic messages with durable events. They do not know what it means to reset a remote worker safely.

The session framework owns those answers.

OpenCode's implementation is valuable because it exposes that boundary. The model call is inside the session runtime, not the other way around. Prompts are admitted before execution. Execution is coordinated per session. Status is published by the runner. Events are the observation surface. Messages are structured projections. Clients can be thin because the runtime has a real shape.

That is the design principle worth taking: build the session as the agent's operating context. The chat transcript is only one view of it.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

My OpenCode Database Was Mostly Empty Space

Antonio Zhu — Wed, 22 Jul 2026 07:47:16 +0000

OpenCode keeps a lot of useful history.

That is one of the reasons I like it. A coding-agent session is not just a chat transcript. It is a record of what I asked, what the agent did, which tools ran, what failed, what got fixed, and what context existed at the time. I have argued before that the agent session is becoming a log file. I still believe that.

Then I noticed the log file was getting large.

On one machine, ~/.local/share/opencode/opencode.db had grown past a gigabyte. That was not shocking by itself. I use OpenCode heavily. Long sessions produce many messages, tool results, shell outputs, file reads, and state transitions. A local database growing over time is expected.

What was surprising was what SQLite reported after looking inside the file: much of it was not live data anymore.

It was empty space.

The misleading part of deleting data

Most developers learn an intuitive model of storage that is only partly true.

If I delete rows from a database, I expect the database file to get smaller. If I archive old sessions, compact history, or remove records, I expect disk usage to fall. At the application level, that feels right: fewer records should mean fewer bytes.

SQLite does not normally work that way.

When rows are deleted, SQLite can reuse the freed pages for future writes, but it does not necessarily return those pages to the filesystem. The file can stay the same size while containing a growing internal pool of reusable pages. That pool is the freelist.

The important distinction is:

database file size != live data size

The file can be 1.3 GB while the live data is only 525 MB. The remaining 766 MB can be pages SQLite is keeping around for reuse. From SQLite's perspective, that space is available. From the filesystem's perspective, it is still occupied.

That is not corruption. It is not necessarily a bug in the data model. It is how SQLite behaves unless the database is configured and vacuumed in a way that returns free pages to the OS.

For a normal application database, this may not matter. For a local agent runtime that stores every tool-heavy session in one file, it becomes noticeable.

Why OpenCode makes this visible

Agent sessions are unusually good at producing large, bursty storage.

A normal chat app stores messages. A coding agent stores messages plus tool calls, tool results, shell output, file contents, structured parts, todos, events, and session metadata. A single task can contain a surprising amount of durable state.

OpenCode also has session compaction. Compaction is useful for model context management, but it is easy to confuse three different layers:

Layer	What changes
Model-visible context	Older conversation can be summarized behind a checkpoint.
Durable history	Original rows can still exist in the database.
SQLite file layout	Deleted or obsolete pages may remain inside the file as freelist space.

Compaction helps the model continue when context gets too large. It does not mean the database file shrinks. Even when rows are removed by some maintenance path, SQLite may keep the freed pages in the same file.

This is the kind of problem that is easy to misdiagnose if you only look at du -h opencode.db. A large file does not tell you how much live data exists. It only tells you how much disk the file currently occupies.

The first tool I wanted was not a cleaner. It was a measurement.

The useful number is freelist percentage

SQLite already exposes the numbers needed to understand the problem:

PRAGMA page_size;
PRAGMA page_count;
PRAGMA freelist_count;

From those values, the diagnosis is simple:

freelist_bytes = freelist_count * page_size
live_bytes = (page_count - freelist_count) * page_size
freelist_pct = freelist_count / page_count

That gives a more useful report than raw file size:

OpenCode Database Health Report
----------------------------------------------------------
  File size:     1.3 GB
  Page size:     4.0 KB
  Journal mode:  wal
  Auto-vacuum:   OFF (NONE)

Storage
----------------------------------------------------------
  Live data:     525 MB
  Freelist:      766 MB  (56% of file)
  -> VACUUM would reclaim ~766 MB
  -> Estimated result:  ~525 MB

This changes the conversation. The question is no longer "why is the database 1.3 GB?" The better question is "how much of this file is still live data?"

If the freelist is small, there is nothing urgent to do. If half the file is freelist pages, a cleanup can reclaim real disk space.

That became ocdbc: OpenCode Database Cleaner.

Why I did not want a clever cleaner

The dangerous version of this tool would delete sessions.

That is not what I wanted. I did not want a policy engine deciding which conversations were old, stale, low-value, or safe to remove. Agent sessions are evidence. They contain exactly the kind of messy operational detail I often need later: commands, errors, constraints, design decisions, failed attempts, and verification output.

So ocdbc has a narrower job.

It does two things:

ocdbc analyze
ocdbc vacuum

analyze is read-only. It reports database size, live data, freelist space, table sizes, session age distribution, and the largest messages.

vacuum does not decide what history should exist. It asks SQLite to rebuild the database file so unused pages can be returned to the filesystem. The goal is physical cleanup, not semantic deletion.

That boundary matters. A tool that deletes history needs product policy. A tool that reports freelist space and runs a safe SQLite maintenance sequence can stay much smaller.

The safety sequence matters

VACUUM sounds boring until you remember what file it is operating on.

This is the local database for an agent runtime. If OpenCode is running while the database is being rebuilt, I do not want to discover edge cases by corrupting my own session history. If the write-ahead log has committed data that has not been checkpointed into the main database file, I do not want to back up an incomplete view. If the database is already corrupt, I do not want the cleanup tool to make the failure harder to reason about.

So ocdbc vacuum is intentionally conservative.

The sequence is:

Refuse to run if fuser shows OpenCode still has the database open.
Checkpoint the WAL before copying the database.
Run PRAGMA integrity_check before making changes.
Create a timestamped backup.
Open the backup and verify its integrity too.
Set auto_vacuum = INCREMENTAL so future free pages can be reclaimed incrementally.
Run VACUUM to rebuild the file.
Re-enable WAL, because VACUUM can reset journal mode.
Run a final integrity check.

The order is the point.

Checkpoint before backup means the .db file contains committed WAL data before it is copied. Verifying the backup means the fallback is not just a file that happened to exist. Refusing to run while another process has the database open prevents a maintenance tool from racing the application it is trying to help.

There are override flags, but they are explicit:

ocdbc vacuum --force
ocdbc vacuum --skip-fuser --force
ocdbc vacuum --no-backup --force

The default path optimizes for not losing data.

A small tool is enough

The whole package is a single Python module with no runtime dependencies. Installation is intentionally uninteresting:

pip install ocdbc

Then:

ocdbc analyze

If the report shows significant freelist bloat, close OpenCode and run:

ocdbc vacuum

That is it.

The tool does not need a daemon. It does not need to understand model context. It does not need to parse sessions or judge which messages matter. It only needs to expose the maintenance operation I wanted OpenCode users to have available when the database file becomes misleadingly large.

That is the pattern I keep coming back to with agent tooling. The best tool is often not the most intelligent one. It is the one that gives the agent or developer a missing primitive with a tight safety boundary.

For readiness checks, that primitive was wait_for: poll a URL, port, or command until the condition is actually true.

For session review, that primitive was session_reflection: treat recent sessions as evidence instead of disposable scrollback.

For OpenCode database bloat, the primitive is ocdbc: show the difference between live data and empty pages, then run the boring SQLite cleanup correctly.

The broader lesson

AI-assisted development creates new kinds of local infrastructure.

The agent runtime is not just a prompt window. It has tools, permissions, sessions, transcripts, databases, plugins, logs, background state, and failure modes. Once that runtime becomes part of daily work, it needs the same boring maintenance primitives every other developer toolchain needs.

Sometimes the fix is not a better model.

Sometimes it is knowing that your 1.3 GB database contains 766 MB of empty pages, closing the app, checkpointing the WAL, verifying a backup, running VACUUM, and getting your disk space back.

That is not glamorous.

It is exactly the kind of boring tool I want more of.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

OpenCode Tool Calling Internals

Antonio Zhu — Mon, 20 Jul 2026 13:42:59 +0000

This document analyzes OpenCode's tool-calling implementation from the perspective of someone building an agent runtime. The goal is not only to explain how OpenCode happens to call tools today. The more useful question is: what design problems does a real coding-agent runtime have to solve once tool calling moves beyond a demo callback?

Primary code references:

packages/opencode/src/tool/tool.ts
packages/opencode/src/tool/registry.ts
packages/opencode/src/session/tools.ts
packages/opencode/src/session/prompt.ts
packages/opencode/src/session/processor.ts
packages/opencode/src/session/llm.ts
packages/opencode/src/session/llm/ai-sdk.ts
packages/opencode/src/session/llm/native-runtime.ts
packages/opencode/src/permission/index.ts

The conclusions below follow the normal OpenCode session tool path. MCP tools, plugin tools, and the experimental native LLM runtime are included where they reveal the underlying design.

Key Takeaways

If you are building an agent runtime, treat tool calling as a runtime subsystem, not as a provider feature. Provider function calling is only the provider-side way of delivering a tool request. The runtime still has to decide which tools exist, which tools are visible, whether execution is allowed, how progress is represented, how output is normalized, and how the session recovers when execution fails.

Keep an internal tool contract. Do not let OpenAI, Anthropic, AI SDK, MCP, or any one provider define the shape of your runtime tools. OpenCode uses Tool.Def as its internal contract and projects it outward later.
Build a tool catalog, not a static tool list. Tool visibility depends on the agent, model, provider, runtime flags, plugins, MCP clients, and permissions. A serious runtime recomputes the catalog for each turn.
Put permission gates inside execution. Prompt instructions and UI affordances are not enough. The dangerous action must block at the point where the tool would actually touch the filesystem, shell, network, or external server.
Persist tool calls as state. A tool call is not just text in the transcript. It has identity, input, progress, output, attachments, timing, error state, and cancellation behavior.
Normalize provider events before they reach the session layer. Providers and model runtimes disagree about streamed tool inputs, results, errors, and provider-executed calls. The session layer should consume one event vocabulary.
Design for debuggability from the start. Tool call IDs, session IDs, message IDs, permission events, plugin hooks, and durable message parts are not extras. They are what let you answer the basic question: what happened?

Why Tool Calling Needs A Runtime Layer

The smallest tool-calling demo looks simple. The model emits a function name and JSON arguments. The application looks up a local function, runs it, sends the result back, and the model continues.

That design collapses as soon as the agent becomes useful.

A coding agent does not merely call getWeather. It reads files, writes files, applies patches, spawns shell commands, lists project directories, asks questions, starts subtasks, calls MCP servers, and may return images or other attachments. Some tools are safe. Some need approval. Some are available only for certain models. Some are provided by plugins. Some should be hidden from an agent entirely. Some run long enough that the UI needs progress. Some are interrupted halfway through. Some produce outputs too large to fit into the next request.

At that point, provider function calling is not the system. It is only one input boundary. The real system is the layer that turns a model's request into a permissioned, observable, cancellable, durable operation inside an agent session.

OpenCode's implementation is useful because it draws that boundary clearly. Tools are not just callback functions passed to streamText(...). They pass through an internal contract, a registry, a session adapter, an LLM runtime adapter, and a session processor. That layering has cost, but it solves problems a direct callback design usually discovers too late.

How The Pieces Connect

The concrete implementation path is short enough to keep in your head.

SessionPrompt.runLoop(...) creates the assistant message for the current provider turn. Before calling the model, it asks SessionTools.resolve(...) to build the tool map for this exact agent, model, session, permission state, and runtime configuration. SessionTools.resolve(...) pulls tool definitions from ToolRegistry, adapts them into AI SDK-compatible tools, injects Tool.Context, and wires execution through plugin hooks and Permission.ask(...).

Then SessionProcessor.process(...) calls LLM.stream(...). The default runtime passes the prepared tools to AI SDK streamText(...). The native runtime uses a different adapter, but still calls back into the same OpenCode-owned tool execution shape. Runtime-specific stream events are converted into LLMEvent values. SessionProcessor consumes those events and persists text, reasoning, tool calls, tool results, errors, usage, and cleanup state as session message parts.

The spine is:

SessionPrompt.runLoop
-> SessionTools.resolve
-> ToolRegistry.tools
-> LLM.stream
-> LLMAISDK.toLLMEvents or native runtime events
-> SessionProcessor.handleEvent
-> Session.updatePart / Session.updateMessage

That path is also the debugging path. If a tool was missing, start at ToolRegistry.tools(...). If it was visible but executed with the wrong context, inspect SessionTools.resolve(...). If the provider emitted unexpected tool events, inspect the runtime adapter. If the UI shows the wrong state, inspect what SessionProcessor persisted.

Design Principle 1: Keep A Provider-Independent Tool Contract

OpenCode's internal contract lives in packages/opencode/src/tool/tool.ts. A tool definition has an ID, description, parameter schema, optional JSON Schema, execute function, and optional validation-error formatter. The important detail is that this is OpenCode's shape, not the provider's shape.

The parameter schema is an Effect schema. Before any tool implementation runs, the wrapper created by Tool.define(...) decodes unknown model input. If the model emits invalid arguments, OpenCode raises InvalidArgumentsError with a model-facing message that asks the model to rewrite the input. Only decoded input reaches the tool implementation.

The execute function receives a Tool.Context containing the session ID, message ID, tool call ID, active agent, abort signal, prior messages, a metadata(...) updater, and an ask(...) permission hook. That context is the real API a tool author uses. A file-writing tool does not need to know how the TUI handles permission prompts. It only needs to call ctx.ask(...). A long-running tool does not need to know how session parts are stored. It only needs to call ctx.metadata(...).

The wrapper also enforces cross-cutting behavior. It validates arguments, records a Tool.execute span, applies output truncation when the tool has not already done so, and attaches common attributes such as tool.name, session.id, message.id, and tool.call_id.

The design lesson is simple: define the tool contract around your runtime's invariants. Provider schemas, AI SDK tools, MCP definitions, and plugin APIs should be projections or adapters. They should not be the source of truth.

Design Principle 2: Build A Runtime Tool Catalog

OpenCode's ToolRegistry is not just a map from names to functions. It is a catalog builder.

It starts with built-in tools such as read, glob, grep, edit, write, task, webfetch, todo, skill, shell, and apply_patch. It then scans configured directories for project tools under {tool,tools}/*.{js,ts} and loads plugin-provided tools from the plugin service. When a plugin provides a tool, the registry immediately wraps it in OpenCode's internal tool contract, so the rest of the runtime can treat it like a built-in tool.

The registry then filters and shapes that catalog for the current turn. For example, the web search tool is not always visible. OpenCode exposes it only when the selected provider supports it, or when runtime flags such as Exa or parallel search are enabled. Experimental tools appear only when flags allow them. GPT-family model handling can choose apply_patch and hide edit and write. The task tool also gets a dynamic description listing the subagents the current agent is allowed to call, so the model knows which subagent_type values are valid. Before any tool is exposed to the model, plugins also get a tool.definition hook that can adjust its description or schema.

This is also how OpenCode exposes subagent delegation. A subagent is not normally launched by a hidden scheduler. The model sees the task tool, reads the dynamically listed subagent_type options, and decides whether delegation is useful for the current turn. If it calls task, the runtime executes that tool and starts the selected subagent. In other words, delegation itself is modeled as tool calling.

Permissions also affect visibility. A broad deny rule can hide a tool before the model ever sees it. Edit-like tools are grouped under edit, while MCP resource tools are grouped under read. This avoids advertising tools that are already forbidden by policy.

The design lesson is that an agent's tool list is a runtime projection. It depends on who the agent is, what model is running, what session permissions apply, what plugins are installed, what external servers are connected, and what feature flags are enabled. If you make the tool list static, those concerns will leak into individual tools or into prompt text.

Design Principle 3: Put Permissions Inside Execution

OpenCode's permission boundary is not a sentence in the system prompt. It is an Effect that can block tool execution.

Tools call ctx.ask(...) with a permission name, path or resource patterns, metadata, and optional always patterns. The write tool asks for edit permission and includes a diff. The shell tool parses commands, resolves paths, asks for bash, and separately asks for external_directory when a command reaches outside the project boundary. Read-like tools ask for read over path patterns. MCP resource tools ask for read over mcp:server:uri patterns.

Permission.ask(...) checks three sources of authority: the agent's configured permission rules, any session-level permission overrides, and approvals granted earlier in the current runtime process when the user chose an "always allow" option. If every pattern is allowed, execution continues. If any pattern is denied, execution fails. If the runtime needs user input, it creates a pending request, publishes Permission.Event.Asked, and waits on a Deferred. When the client replies, Permission.reply(...) publishes Permission.Event.Replied and resolves or rejects the waiting tool.

This design matters because permission is enforced at the point of action. A model can ask for a shell command. The UI can render a prompt. But the shell command does not run until the permission service resolves. The approval path is part of execution, not decoration around it.

The design lesson is to make safety a blocking dependency of side effects. If permission is implemented only as model instruction, client UI, or precomputed filtering, eventually some tool path will bypass it.

Design Principle 4: Persist Tool Calls As State

A tool call is a long-lived operation, not a line of assistant text. It begins when the provider says the model wants a tool, but it may pass through streamed input, permission waiting, execution, progress updates, output truncation, attachment handling, cancellation, and failure cleanup before the model sees a result. If a runtime only stores the final tool result as transcript text, it loses the operation boundary.

That boundary matters. The UI needs to show that a tool is running before it finishes. A permission rejection needs to be different from a tool crash. A cancelled run needs to mark unfinished calls instead of leaving them as ghosts. A debug trace needs to answer which tool ran, with what input, under which assistant message, and what output or error it produced. None of that can be reliably reconstructed from prose.

Durability adds another benefit: interruption and restart become tractable. If tool calls are persisted as structured records, a runtime can inspect what was pending, running, completed, or failed after a crash or cancellation. That does not mean it should blindly re-execute tools after restart; tools may have side effects. It means the runtime has enough state to make an explicit recovery decision: retry only if safe, mark an abandoned call as interrupted, or rebuild the model-visible history with accurate completed results. Without durable tool state, restart logic has to infer too much from partially written text.

OpenCode handles this by persisting tool calls as assistant message parts. SessionProcessor owns the state machine. When the normalized event stream reports tool input or a tool call, the processor calls ensureToolCall(...). If this is the first event for a call ID, it creates a tool part with state pending. When the tool-call event arrives, the part becomes running and records the tool name, input, timing, and provider metadata. When a result arrives, completeToolCall(...) writes completed with output, metadata, title, attachments, and end time. When an error arrives, failToolCall(...) writes an error state.

The basic state model is:

pending
-> running
-> completed | error

There is also cleanup behavior. At the end of processing, unresolved tool calls are given a short chance to settle. Remaining calls are marked as interrupted errors with Tool execution aborted and metadata indicating interruption. This keeps the transcript from containing permanently running calls after cancellation or stream failure.

The exact state machine is small, but the design choice is large. Tool calls are durable operation records. Text is what the model reads later. State is what the runtime needs to render, cancel, inspect, retry, and debug the operation.

Design Principle 5: Normalize At Runtime Boundaries

An agent runtime has two unstable boundaries around tool calling. One boundary faces the model provider. The other faces tool implementations. Both are messy.

Providers do not all describe tool activity the same way. One runtime may stream tool input deltas. Another may report only a completed call. A provider may mark a call as provider-executed, surface a tool error as a stream event, or wrap usage and metadata in provider-specific fields. If those event shapes leak directly into session state, every downstream system has to understand provider quirks: UI rendering, debugging, retries, compaction, permissions, and persistence.

Tool outputs have the same problem from the other side. One tool may return a string. Another may return a structured object. An MCP tool may return text, an image, or a resource blob. A file-oriented tool may return attachments. A shell tool may return too much output. If the runtime lets every output shape flow straight into history, the next model request becomes unpredictable and the UI has no stable contract to render.

OpenCode handles the provider side with an event normalization seam. The default runtime path uses AI SDK streamText(...); the experimental native runtime lowers selected requests into @opencode-ai/llm. The session processor does not consume either runtime directly. Both paths converge on LLMEvent. For the AI SDK path, packages/opencode/src/session/llm/ai-sdk.ts converts fullStream events into OpenCode's event vocabulary: text deltas, reasoning events, step events, tool input events, tool calls, tool results, tool errors, provider errors, and finish events. The native runtime emits the same downstream vocabulary.

OpenCode handles the tool-output side with a normalized result shape: title, metadata, output text, and optional attachments. The tool wrapper applies output truncation unless the tool already reports truncation metadata. SessionTools.resolve(...) assigns IDs to attachments and binds them to the current session and assistant message. SessionProcessor can normalize image attachments before persisting the completed result. MCP resource helpers convert text, images, and resource content into explicit text output plus durable file attachments, while unsupported or oversized binary content is omitted with a visible explanation.

The design choice is not just convenience. It protects the rest of the runtime from two sources of drift: provider event drift and tool output drift. Once a provider stream has become LLMEvent, session persistence does not care whether the call came from AI SDK or the native runtime. Once a tool result has become OpenCode's output shape, the model, UI, and database do not care whether it came from a built-in tool, plugin tool, or MCP server.

The lesson for runtime builders is to normalize at every boundary where external variability enters. Do not let provider-specific event shapes or tool-specific output shapes become your session model. Convert them into runtime-owned contracts before they become history, UI state, or the next model input.

What OpenCode Gets Right

It separates internal tool semantics from provider mechanics. Tool.Def is the source of truth. AI SDK tools, MCP tools, plugin tools, and native runtime tools are adapters around that contract.

It makes tool visibility contextual. The runtime does not pretend every agent and every model have the same capabilities. The tool catalog is rebuilt for the current session turn.

It puts permission checks where side effects happen. Sensitive operations block inside execution, and the approval flow is represented as runtime events.

It persists tool lifecycle explicitly. A tool call has state, input, timing, output, metadata, attachments, and failure information. This is essential for UI, debugging, and recovery.

It creates a stable event seam between model runtimes and session state. AI SDK and native runtime differences are normalized before SessionProcessor handles them.

It leaves room for extension. Plugins and MCP servers can add tools without bypassing the same broad execution framework.

Where The Design Is Still Expensive

The cost of this design is complexity.

A tool call can pass through many layers: tool definition, registry projection, provider schema transformation, session adapter, permission gate, plugin hooks, LLM runtime, event normalization, and session processor persistence. When behavior is wrong, the bug may live in any one of those seams. A tool can be defined correctly but hidden by permissions. It can be visible but transformed into a provider schema the model handles poorly. It can execute successfully but return an output shape that is later truncated. It can be interrupted after the provider already emitted a partial event.

The design also relies on tools asking for the right permissions. The framework can block ctx.ask(...), but it cannot magically know which resources an opaque tool input will touch. The shell tool is the clearest example. A file tool receives a structured filePath, so it can ask for permission over that path directly. A shell tool receives an opaque command string. Before it can ask precise permissions, it has to parse that string, identify filesystem-related commands such as rm, cp, mv, mkdir, cat, or cd, extract path arguments, expand home and environment references, resolve relative paths against the working directory, and detect paths outside the project boundary. Only then can it ask for permissions such as bash or external_directory with meaningful patterns. Without that parsing step, the runtime would either approve every shell command too broadly or block useful commands too often.

Safety moves from a prompt problem to a tool implementation problem. That is better, but it is still work.

Provider behavior remains an input boundary. OpenCode normalizes provider events after it receives them, but it still depends on the provider or runtime to surface tool calls, results, errors, and cancellation in a usable way. The native runtime can reduce some provider coupling, but it does not remove the need for careful adapter design.

The design lesson is not that every agent runtime should copy OpenCode's exact files. The lesson is that once an agent can change a real project, tool calling becomes infrastructure. Infrastructure has seams, state, and failure modes.

The provider tells you what the model wants. The runtime is responsible for making that request safe, observable, and recoverable.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

OpenCode V2 Compaction Internals

Antonio Zhu — Fri, 17 Jul 2026 11:26:41 +0000

This document analyzes the OpenCode V2 compaction implementation. The conclusions are based on the V2/core code path in the OpenCode repository. When code, comments, and documentation disagree, this document follows the current code behavior.

Primary code references:

packages/core/src/session/compaction.ts
packages/core/src/session/runner/llm.ts
packages/core/src/session/history.ts
packages/core/src/session/context-epoch.ts
packages/core/src/session/runner/to-llm-message.ts
packages/core/src/session/message-updater.ts
packages/core/src/config/compaction.ts

This document only covers the V2/core compaction path. It does not cover the V1 compatibility /compact implementation or the DCP plugin's compress tool.

Key Takeaways

OpenCode V2 compaction is a durable checkpoint-and-retry mechanism, not a relevance-pruning system. It is a last-resort survival mechanism — avoid triggering it whenever possible.

Avoid compaction. Once triggered, all older context is compressed into a hardcoded 4_096-token summary. Details that do not fit are not recovered. The session survives, but its continuity depends entirely on what the summary captured.
Compaction is size-triggered, not relevance-triggered. It runs when the request estimate exceeds the context threshold — regardless of how important or irrelevant the conversation is. The system has no concept of message importance.
Three hardcoded limits control quality. Tool/shell output is truncated at 2_000 chars (TOOL_OUTPUT_MAX_CHARS), summary output is capped at 4_096 tokens (SUMMARY_OUTPUT_TOKENS), and neither is configurable. Only buffer and keep.tokens are exposed in the config schema.
History is never deleted, but old rows are no longer loaded. Old messages remain in durable storage. After compaction, future model requests start from the checkpoint and do not see older rows through normal provider calls.
Media content is not preserved in model-visible context after compaction. Images and videos from before the checkpoint are reduced to text metadata ([Attached image/png: screenshot.png]). The original binary data remains in durable history, but the model cannot see visual content from before the checkpoint through normal provider requests.
Compaction is safe but blunt. It never deletes history, never leaves a half-compacted session, and prevents infinite retry loops. But it makes no attempt to distinguish important facts from noise when summarizing older context.

Core Design

Long coding-agent sessions produce long conversation histories. Tool calls, tool results, shell outputs, file reads, and multi-turn reasoning accumulate. Eventually the full provider request exceeds the model's context limit. Deleting old messages would lose durable history. Compaction solves this with a checkpoint strategy: create a new message that represents older history, then let future runner attempts use that message as a starting boundary.

V2 compaction separates three layers that would otherwise be conflated:

Layer	What it is	What compaction does to it
Durable history	Full session record in `SessionMessageTable`	Not changed. Old rows remain.
Active history	The slice of messages loaded for a provider attempt	Shortened. Future loads start from the latest `type: "compaction"` checkpoint.
Model-visible context	What the model actually receives in a request	Replaced. Older context becomes `<summary>` + `<recent-context>` inside a `<conversation-checkpoint>` block.

This three-layer design is the key insight. Compaction does not shrink the database. It changes the default projection of history used to call the model, and it renders old context through a generated summary rather than replaying every old message.

How It Works

Trigger

Compaction has two trigger paths.

Automatic path. Before each normal assistant-response provider attempt, the session runner estimates the full provider request size and compares it against the current model's context window:

estimated_request_tokens > model_context_limit - max(output_tokens, compaction_buffer)

The default compaction buffer is 20_000 tokens. With a 128_000 token context window and default output limit, the threshold is approximately 108_000 tokens.

Recovery path. If the provider returns a context overflow error and the current turn has not yet produced durable assistant output or tool execution, OpenCode runs one recovery compaction and retries. This path handles cases where the local token estimate did not prevent a provider-side overflow. The overflow recovery path runs at most once to avoid looping.

Both paths eventually call the same implementation: compactAfterOverflow(...) in packages/core/src/session/compaction.ts.

Split History Into `head` And `recent`

Compaction divides active session history into two parts.

First, existing type: "compaction" messages are ignored. The remaining structured session messages are converted into plain text. The helper function is named serialize(...) in the code, but this is a text conversion step, not binary serialization:

user messages become [User]: ... plus attachment descriptions.
assistant text becomes [Assistant]: ....
assistant reasoning becomes [Assistant reasoning]: ... when reasoning text exists.
assistant tool calls become [Assistant tool call]: tool(input).
completed tool results become [Tool result]: ....
failed tool calls become [Tool error]: ....
system updates become [System update]: ....
synthetic context becomes [Synthetic context]: ....
shell messages become [Shell]: command + output.

Tool output and shell output are truncated to 2_000 characters. This limit is hardcoded as TOOL_OUTPUT_MAX_CHARS in packages/core/src/session/compaction.ts:14 and is not exposed through the compaction config schema. Binary and media content is not embedded as base64. Images, videos, and attachments are reduced to text metadata such as [Attached image/png: screenshot.png]. The compaction summary request is always text-only. A non-multimodal model can still run the summary request because it receives only text labels. However, it cannot infer visual or binary content unless that content was already described elsewhere in text.

The converted text is then split by walking backward from the latest message. The default recent-context budget is 8_000 tokens from DEFAULT_KEEP_TOKENS. Recent converted text within this budget is kept as recent. Older converted text becomes head.

The newly selected recent is not summarized in the same compaction run. It is stored directly in the checkpoint and later rendered as <recent-context>. The newly selected head is what gets summarized.

Generate The Summary

The summary prompt is built by buildPrompt(...). Its job is not just to shorten text. It tries to preserve the working state needed for a coding-agent session to continue.

When there is no previous checkpoint, the prompt starts with:

Create a new anchored summary from the conversation history.

When a previous checkpoint exists, the prompt asks the model to update the anchored summary rather than blindly stacking independent summaries:

Update the anchored summary below using the conversation history above.
Preserve still-true details, remove stale details, and merge in the new facts.

The prompt then includes a fixed Markdown template tuned for session recovery:

## Objective — what the user is trying to accomplish.
## Important Details — constraints, decisions, assumptions, exact context needed to continue.
## Work State — completed work, active work, blockers.
## Next Move — the next concrete action after retry.
## Relevant Files — file paths that would otherwise be easy to lose during summarization.

The prompt rules require the model to keep every section, use terse bullets, preserve exact paths/symbols/commands/errors/URLs/identifiers, and avoid mentioning that context was compacted. The last rule matters: the generated checkpoint should read like normal historical context, not an explanation of an internal maintenance operation.

The context passed into the summary is: previous checkpoint recent, when one exists, plus the newly selected head.

The summary request uses the same input.model as the current provider attempt, with no tools and a maximum of 4_096 output tokens. This limit is hardcoded as SUMMARY_OUTPUT_TOKENS in packages/core/src/session/compaction.ts:15 and is not exposed through the compaction config schema. Even if the model supports larger output, the cap is always 4_096. There is no separate specialist compaction model in the current V2 core path.

This is a significant constraint. A long session may have accumulated detailed information — file paths, commands, error messages, design decisions, constraints, test results — across many turns. All of that older context must be compressed into at most 4,096 output tokens of structured summary. If important details exceed what the summary model can fit, they are not preserved for future provider attempts. The session does not crash, but the model's working knowledge of old context can become incomplete.

Persist The Checkpoint

Before summary generation starts, OpenCode publishes SessionEvent.Compaction.Started. This event does not create a checkpoint message.

During generation, the implementation collects text delta chunks. If the stream reports a provider error, throws LLM.Error, or produces an empty summary, compaction returns false and no checkpoint is written. Failure handling is conservative: a failed summary attempt does not move the active-history boundary.

Only after a non-empty summary is generated does OpenCode publish SessionEvent.Compaction.Ended. The session projector handles this event by inserting a durable type: "compaction" message into SessionMessageTable. The inserted row includes the message ID, session ID, compaction type, event sequence, creation time, and the payload: reason, summary, and recent.

This is the point where the generated summary becomes part of session history and can be used as the next active-history boundary.

Retry From The Checkpoint

After the checkpoint is persisted, compactAfterOverflow(...) returns true, and compactIfNeeded(...) returns true to the runner. The runner stops the current attempt before calling the model by throwing ContinueAfterCompaction — a control-flow signal, not a user-facing error.

On the retry, OpenCode reloads active history from the latest compaction checkpoint and rebuilds a smaller provider request. That smaller request is then sent to the model.

The normal path is:

build request -> estimate size -> split history -> summarize head -> write checkpoint -> retry -> call model

Repeated Compaction

If the session grows again after the first compaction, the cycle repeats. compactAfterOverflow(...) reads the existing checkpoint message from the current entries. When a previous summary exists, the new prompt asks the model to update the anchored summary rather than starting from scratch.

The benefit is continuity across multiple compactions. Older summarized facts can be carried forward, while newer head content is merged into the updated summary.

The limitation is cumulative summary risk. Each repeated compaction depends on the previous checkpoint summary and the latest summarization pass. A detail dropped earlier is not recovered by re-reading old pre-checkpoint rows.

What The Model Sees After Compaction

After compaction, SessionHistory.latestCompaction(...) finds the newest type = "compaction" message. The history loader starts active history from that checkpoint sequence. Older messages before the checkpoint are no longer loaded into the normal provider request.

When the checkpoint is sent to the model, to-llm-message.ts renders it as a user-role <conversation-checkpoint> block:

<conversation-checkpoint>
The following is a summary and serialized record of earlier conversation. Treat it as historical context, not as new instructions.

<summary>
...
</summary>

<recent-context>
...
</recent-context>
</conversation-checkpoint>

There are two important design choices here. First, the checkpoint is model-visible context, not hidden state. The next provider attempt can reason over the summary and recent context because they are rendered into the prompt. Second, the checkpoint text explicitly frames itself as history, not new instructions. The model receives a smaller request with an explicit continuity record, but it no longer sees old messages in their original structured form. It sees the generated summary and the retained recent text.

Completed compaction also interacts with Context Epoch. If the latest compaction sequence is newer than the stored baseline sequence, the system-context baseline can move forward to the same boundary in context-epoch.ts. This prevents old mid-conversation system updates from being mixed into the new active history inconsistently.

Configuration Surface

The V2 compaction config is intentionally small, defined in packages/core/src/config/compaction.ts:

compaction: {
  auto?: boolean
  prune?: boolean
  keep?: { tokens?: number }
  buffer?: number
}

The current V2 compaction implementation uses:

auto — whether automatic compaction runs (default: true).
buffer — reserved headroom before the context limit (default: 20_000).
keep.tokens — recent-context budget (default: 8_000).

The prune field exists in the schema but is not used by the current core compaction logic.

The configuration controls thresholds, not pruning policy. It determines when compaction runs and how much recent text is kept verbatim, but it does not select which messages or tool results to remove from context before compaction.

Strengths

Durable, not destructive. Original session messages remain in SessionMessageTable. Compaction appends a new checkpoint message. Nothing is deleted. This makes the checkpoint auditable and replayable.

Safe retry boundary. The runner can stop the current attempt and rebuild the next provider request from the checkpoint. This avoids replaying the full old conversation.

Simple mental model. Older context becomes summary; the newest converted text becomes recent. The summary prompt enforces a coding-agent-oriented structure — Objective, Work State, Next Move, Relevant Files — tuned for session recovery rather than generic prose compression.

Recent exact context preserved. The most recent converted text is not summarized in the same compaction run. It is stored directly as recent, reducing the chance of losing exact details from the latest work.

Conservative failure mode. If compaction cannot produce a completed checkpoint — summary prompt too large, provider error, empty summary — it does not move the active-history boundary. The session remains in its pre-compaction state.

Checkpoint framed as history, not instruction. The <conversation-checkpoint> text explicitly declares itself historical context, not new instructions. This is simple prompt engineering that reduces the risk of the model misinterpreting the compacted summary as fresh user intent.

Small, predictable configuration surface. Only three fields control behavior in the current core path: auto, buffer, and keep.tokens. There are no complex pruning policies to tune or debug. The behavior is threshold-driven and easy to reason about.

Limitations

The summary output bottleneck — this is the most important weakness. The summary output limit is hardcoded at 4_096 tokens (SUMMARY_OUTPUT_TOKENS in packages/core/src/session/compaction.ts:15) and not configurable. A long coding session can span tens of thousands of tokens of tool outputs, file reads, error messages, design decisions, shell commands, and reasoning chains. All of that older context — everything except the most recent ~8_000 tokens — must be compressed into at most 4_096 tokens of structured summary.

This means any detail that does not fit into the summary is not automatically recovered from durable history during future provider requests. The model's working knowledge of old context becomes only what the summary captured. File paths can be dropped. Error messages can be paraphrased into uselessness. Design decisions can be collapsed to a bullet point. The session does not crash, but its continuity depends entirely on the quality of the 4k-token summary.

This is the fundamental reason to avoid triggering OpenCode V2 compaction whenever possible. Compaction is a survival mechanism, not an optimization.

Size-based trigger, not relevance-based. Compaction starts when the estimated provider request is too large, or after a provider-side context overflow. It does not run because a message is stale, duplicated, low-value, or off-topic. The system has no concept of message importance.

Coarse summarization of older context. Older converted text is summarized as a block. The implementation does not rank individual messages, tool results, command outputs, or file reads by relevance. It treats all pre-recent history as summarization material.

Shallow tool output handling. Large tool and shell outputs are truncated to 2_000 characters during text conversion. This limit is hardcoded (TOOL_OUTPUT_MAX_CHARS) and not configurable. A single important line in a large log file may be truncated away, while a verbose but low-value message may consume recent-context budget.

Media content is not visible to the model after compaction. Images, videos, and other binary attachments are reduced to text metadata such as MIME type and filename during text conversion. Once media falls behind the compaction boundary, future model requests see only the checkpoint text. The original binary data remains in durable history, but it is no longer part of model-visible context through normal provider requests.

Checkpoint is irreversible for active context. After compaction, future model requests normally depend on the checkpoint summary and recent context for older information. Mistakes, omissions, or distortions in the summary become the model's only working knowledge of old context.

No deterministic pruning. The config schema includes prune, but current V2 core compaction does not use it. The implementation is checkpoint summarization, not a policy engine for removing specific tool results, errors, or repeated file reads.

Claims The Current V2 Code Does Not Support

Based on the current V2/core code, do not claim that:

V2 supports user-selected manual compaction ranges.
V2 uses a hidden compaction agent.
V2 uses a separate smaller model for compaction.
V2 performs deterministic pruning of old tool results.
V2 keeps the last N turns.
V2 deletes historical messages.

The reliable claim is more specific: V2 automatically creates a summary checkpoint when a normal provider attempt is too large, or when provider overflow recovery succeeds before side effects.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

A ⭐ on GitHub means a lot!

My Agent Kept Writing sleep Loops. So I Gave It a Better Primitive

Antonio Zhu — Sat, 11 Jul 2026 02:19:09 +0000

I deployed a change, and the agent needed to confirm the new version was live before running a smoke test. So it wrote what agents always write in this situation:

for i in $(seq 1 40); do sleep 3; curl -s http://host/health && break; done

Then it read the output, saw the old version still serving, and declared the deploy done anyway — because the loop had exited on the first curl that returned anything, not the first one that returned the right thing. I had watched a variant of this play out a dozen times. The agent either polls too few times and gives up early, or hard-codes a sleep 120 and blocks the whole session on a fixed guess, or exits on a 200 that carries a stale body. Every time, it re-derives the same fragile loop from scratch, because there is nothing better sitting in its toolbox.

Why agents reach for sleep

An agent acts through the tools it has. Give it bash, and "wait until the server is ready" collapses into "sleep and hope," because a fixed sleep is the cheapest thing the shell offers. It has no primitive for readiness — no verb that means "keep checking this condition, on a sensible cadence, until it holds or you give up." So it fakes one, and the fake is worse in every dimension: it doesn't know how long to wait, it doesn't know what "ready" actually looks like, and when it fails it throws away everything it observed on the way down.

That last part is the real cost. A hand-rolled loop that times out tells you nothing. The agent is left to run another probe just to find out why the first forty failed — a human-speed round trip through the clipboard, which is exactly the distance I keep trying to shorten between an agent and the ground truth it can't see.

The primitive

So I wrote opencode-waitfor, a zero-dependency plugin that adds one tool, wait_for. You install it by adding one line to opencode.json:

{ "plugin": ["opencode-waitfor"] }

The tool infers what kind of target it's watching. A URL with a scheme gets polled over HTTP; a bare host:port gets a TCP connection check; anything else runs as a shell command. Three shapes of "is it up yet," one verb:

wait_for http://localhost:3000
wait_for localhost:5432 timeout 10
wait_for http://host/health expect { json_match: { status: ok, version: abc123 } }

That last one is the case that started this. After deploying commit abc123, the agent waits until /health reports that version — not any response, the correct one. The stale-body deploy I opened with simply cannot pass.

And when it does time out, it returns the last thing it saw: the final HTTP status and body, or the last command's exit code and output. The agent gets to diagnose from the failure it already has, instead of firing a fresh probe to reconstruct it.

I've written before that the job left to a human, when the agent writes more code than you can read, is standing at the boundary and shortening the distance to ground truth. Usually that's a manual act. Sometimes you can make it structural — hand the agent a primitive shaped like the thing it kept faking, and the bad behavior stops being something you prompt against and starts being something it can't easily do. A tool changes what an agent reaches for more reliably than any instruction telling it to reach for something else.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

Six Laws for Talking to AI

Antonio Zhu — Thu, 02 Jul 2026 01:15:10 +0000

I recently opened a SQLite file — the local session log from OpenCode, the AI coding tool I use every day. 192 sessions, 8,471 messages, 89 million input tokens. Total cost: \$518.

But cost per token is the wrong metric. I wanted to know: how much of what I said was wasted?

So I wrote some queries. I counted every message where I said "不对," "不行," "不是," "不不" — the Chinese equivalents of "no, wrong, not that, stop." I counted sessions where I forked the same conversation and started over. I looked at how many messages were shorter than ten characters. I had six sub-agents analyze the six longest sessions independently, pulling out every instance where I corrected the AI, repeated myself, or sent an instruction so vague the AI had to guess.

The number that stopped me: 60% of my sessions were forked from an older one. I was restarting more conversations than I was finishing. For every two user messages in my worst session, I started a new session.

The rest of this article is what I found. Six patterns. Six fixes. All measurable.

Data Snapshot

Metric	Value
Total sessions	192
Total messages	8,471 (7,109 AI, 1,366 me)
Sessions with a parent (forked)	115 (60%)
Explicit correction messages	67 (4.9% of my messages)
Messages mentioning push/commit	132
Primary model	deepseek-v4-pro (125 sessions)
Sessions above 100 messages	4 (capped at 164)

Four sessions hit triple-digit message counts. The longest — a deployment migration to a new server — ran 164 messages. I said "get my approval first" four times in that session alone. I said "use GitHub Actions, not manual commands" five times. No one else was in the room. I was repeating myself to a machine.

But that 60% fork rate cuts both ways, and I have to be honest about the other side of it. The human in me is lazy. I hate starting new sessions. A fresh session means I have to re-explain the project, re-establish the rules, re-load the mental model. So I don't. I cram unrelated tasks into one session until it becomes a junk drawer. Deployment config, CSS refactoring, database schema changes, and a React component all in the same thread. By message 80, the AI has no idea what we're working on anymore, and neither do I. The context window might technically hold 200K tokens, but attention is not a buffer — it's a spotlight, and my spotlight is painting six walls at once.

The 60% fork rate isn't a disciplined practice. It's a symptom. I fork when I'm frustrated, and I don't fork when I should. Both are failures of context discipline.

Law 1: The gap between knowing and writing is the whole cost.

Everyone knows AI forgets. The interesting question is not does it forget — it's how long do you wait before fixing it.

Across six sessions, I corrected the AI for the same rule violations 27 times before writing a single line to my config file. Not 27 times across months. 27 times where I already knew the pattern, already had the fix in my head, and just didn't stop to write it down.

Rule	Corrected in chat	Messages between first correction and AGENTS.md write
"Get my approval before acting"	4 times	43
"All operations must use GitHub Actions"	5 times	52
"Talk business concepts, not code"	4 times	54
"Remove project-specific details"	4 times	31

The server migration session is the cleanest example. I told the AI "get my approval before acting" on message 1. By message 48, it had forgotten. I said it again. At message 62, the AI pushed code without confirmation — I said it a third time, with profanity. At message 63, ten minutes later, it happened again. I finally wrote the rule to AGENTS.md around message 80.

The waste wasn't the 4 corrections. The waste was the 79 messages between "I know this should be a rule" and "this is now a rule."

Every person who uses AI coding tools knows that writing rules fixes things. The thing I didn't know until I counted: I average 36 messages between knowing and writing. I don't have a knowledge problem. I have an execution latency problem.

The fix: After every single correction, ask: does this rule apply to future sessions? If yes, write it now. Not after this task. Not after this session. Now. The cost of writing is ten seconds. The cost of not writing is the rest of the session.

Law 2: Assess the blast radius. Every time.

Six sessions. Four tirades. Every one followed the same script: I give an instruction involving modification or deletion. The AI starts changing files without telling me what. Something breaks that I didn't expect. I discover the damage and lose my temper.

Specifics: rewriting a website footer and deleting the social links in it. Deleting an entire RSS feed when I only asked to filter old articles. Manually running commands on a production server. Claiming a file exists when it doesn't.

My AGENTS.md already says push and deploy require explicit user confirmation. I wrote that after the server migration disaster. But the rule is too narrow. It only covers git. It doesn't cover rewrites, bulk replacements, folder restructures, or production commands — all of which share the same asymmetry: three seconds to break, thirty minutes to fix.

Here is the thing I missed: this is not a special AI rule. This is the same principle you apply before any production change with a blast radius larger than one file.

We don't let teammates push to production without a diff. We don't approve a database migration without reviewing which tables it touches. We don't run terraform apply without reading the plan first. The AI is no different — except that it's faster and has less judgment. An intern who can type at 10,000 WPM. The engineering discipline that keeps production safe is the same discipline that keeps an AI session from spiraling.

Before I started counting, I thought "ask the AI to confirm" was about trust. It's not. It's about blast radius. The AI proposed a change to my website footer. One file. What's the worst that could happen? The footer appears on every page. That's 100% of the site. One file, full blast radius. The AI doesn't understand that. You do.

The fix: Before any operation that touches more than one file or any file with a cross-cutting footprint, the AI must list every file it will touch and every change it will make. Then wait for confirmation. This is not a negotiation with a coworker. It's a pre-flight checklist. The same instinct that makes you read terraform plan output should make you read the AI's change list. Same discipline. Same muscle.

Law 3: Send the full spec. Not one sentence at a time.

My worst sessions all share a shape: I start with a rough idea, then refine it through seventeen messages. The AI follows each micro-adjustment, but the overhead of each round trip compounds fast.

Here is a real example, anonymized:

"I need a search feature."
"It should filter by name."
"Email too."
"Partial match, not exact."
"Show results in a dropdown."
"Debounce the input by 300ms."
"Start."

Seven messages. Here is the same spec as one message:

Search feature: typeahead dropdown. Filter by name and email, partial match.
Debounce input at 300ms. Show results below the search bar.

Two messages would have done it. I spent five extra messages hand-holding the specification because I hadn't completed it in my own head before typing.

This happened in every long session. The paywall discussion took 18 messages (cancel → no, restrict → wait, AI is paid too → defer). The server migration plan changed direction three times (fully migrate → partially migrate → open a new VM instead). None of these decisions were bad. But each mid-flight change of direction forced the AI to recompute context that had already been settled, which meant it forgot things discussed earlier — which meant I had to re-explain them.

The fix: Before sending a feature request, write the full spec in a text editor. Fields. Constraints. Edge cases. Interactions. Then send it once. The thirty seconds you spend typing to yourself are worth five rounds with the AI.

Law 4: An instruction under ten characters is a puzzle.

In my longest technical session — building a rules-checking tool — 72% of my messages were under fifty characters. 19% were under five characters.

Here is what I actually sent:

What I typed	What the AI had to guess
`change`	Change what? Code? Plan? Naming?
`clean up`	Clean which directory? Which files?
`do it.`	Do which option?
`symbolic link`	From where to where?
`check-rules`	Run the tool? Check a file? Create it?

Each two-word instruction cost one to three clarification rounds. The AI would propose options. I'd pick one. Total waste per instance: two to four messages. In a 74-message session, I estimate these cost me about fifteen rounds.

The interesting thing is that I knew exactly what I meant when I typed "change." The context was clear to me. The problem is that context lives in my brain, not in the chat. The AI can only act on what's in the text.

The fix: Before sending, ask: if someone read this instruction with zero prior context, could they execute it? If the answer is no, add a sentence. "change" becomes "Add input sanitization to the form submission handler." Same idea. Seven more words. Zero guessing rounds.

Law 5: A bug in file A is a bug in files B through Z.

A session where I was deploying multiple services taught me this. Each service had its own CI config file. Service A's deployment failed — missing a network setting. I pasted the error log. The AI fixed Service A.

Service B's deployment failed. Same error. Different file. I pasted the log. The AI fixed Service B.

Service C's deployment failed. Same error. I lost my patience. "You didn't listen," I said. "I told you to fix this."

The AI had never been told to fix all config files. It had been told to fix the one I pasted, twice. I was angry at the AI for doing exactly what I asked.

A similar thing happened in another project: a validation bug existed in both the frontend and backend. I fixed the backend, deployed, and the error came back. The frontend had the same logic, untouched.

The fix: After identifying a bug in one file, the next instruction should be: "Check all files in this category for the same issue." Not "fix this one." One sentence prevents the slow drip of identical errors.

Law 6: "This" and "all" are not the same thing. Say which.

I asked the AI to add input validation to a module. "Validate the email field," I said. The AI validated email — and only email. I meant all fields on the form. But I had said "this field." The AI took me literally.

Same thing with error handling: "add try-catch to this function" got me one function. I wanted it across the entire module. Three rounds to converge.

In both cases I had said "this" — this field, this function — when I meant "every field in the module," "every function that calls an external API." The AI applied the constraint to the one thing I named. I thought the context made my intent obvious. It didn't.

Another case: I told the AI to add rate limiting to one API endpoint, intending it as a pattern for the whole service. The AI added it to one endpoint. I said "no, all of them." Two rounds. If I had started with "add rate limiting to all endpoints," done in one.

The fix: If a constraint applies to more than one output, start with "all." If it applies to one, start with "this one." Explicit scope costs zero tokens and saves three corrections.

The Compounding Asset

None of these laws are about prompt engineering. They are about systematizing your own communication patterns. The real insight from 192 sessions is not that I needed better prompts. It's that I needed a process for not repeating myself.

AGENTS.md is not a file you write once. It's a muscle you exercise after every correction. The engineer who talks to AI for a hundred sessions and writes nothing down has the same information as session ten. The one who writes a rule after every correction has a compounding asset. Every new session starts with the accumulated wisdom of every previous correction. The AI catches up to your intent faster. You repeat yourself less. The sessions get shorter, the output higher quality, and the four-letter words drop to zero.

That's the asymptote worth chasing.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

I Reverse Engineered a Closed-Format App. Everything Was in SQLite.

Antonio Zhu — Fri, 26 Jun 2026 16:47:14 +0000

I had accumulated over two thousand notes in Youdao Cloud Note over several years. When I decided to move to Obsidian, the first thing I checked was the export feature. There wasn't one. No batch export, no single-note export, nothing in the Mac client.

So I went looking for the local data.

Where The Data Was

On macOS, Youdao Cloud Note stores its data here:

~/Library/Containers/ynote-desktop/Data/Library/Application Support/ynote-desktop/

Inside that directory, organized by account email, were three SQLite databases:

<account>.db         # note metadata, folder hierarchy
<account>-content.db # note content (old editor)
<account>-search.db  # search index

And a file/ directory with 16 subdirectories arranged by the first character of each file ID, holding the new editor's local files. Everything was unencrypted.

What The Database Contained

The main database had two critical tables:

note — the note catalog. Key columns: fileId (UUID), title, parentId (folder reference), orgEditorType (0 for the new block editor, 1 for the old plain editor), entryPath (path to the local file), createTime (Unix timestamp in seconds), and deleted (NULL meant not deleted).

note_book — the folder tree. Folders were not in note at all. They lived in a separate table with their own fileId and parentId fields, forming a tree you could traverse with BFS.

The content database held a contenttable with a content field, but the field was truncated to around 150 characters — just enough for search snippets. The real content for old-editor notes lived here too, with variable lengths.

Where the content actually was depended on which editor wrote the note:

orgEditorType	Editor	Content source
0	New (block editor)	`entryPath` → local file
1	Old (plain)	`contenttable.content`

The local files came in two formats: JSON (449 of them) and plain Markdown (1,832).

The JSON Block Tree

The new editor stored notes as a block tree in JSON. Each block followed this structure, with the actual keys being cryptic integers:

"6" → block type (p=paragraph, h=heading, co=code, t=table, im=image, l=list, q=quote, hr=divider)
"4" → properties (heading level, code language, image URL, etc.)
"5" → array of child blocks
"7" → inline text segments with "9" format markers (b=bold, i=italic, li=link, il=inline code, etc.)

Walking the "5" array recursively converted the entire tree to Markdown. The core renderer was under 200 lines.

Three Things That Wasted My Time

The __compress__ flag. Ten JSON files had "__compress__": true. I spent an hour trying to uncompress them with LZString before realizing the "5" array was still just a plain array — not a compressed string. The flag had been set but never used.

Deleted is NULL, not 0. Every note with deleted IS NULL had been a living note. WHERE deleted = 0 returned nothing. This is standard SQL but easy to miss when you're scanning thousands of rows for anomalies.

The timestamp is in seconds. 1484115955 is January 11, 2017. If you treat it as milliseconds and divide by 1000, you land in 1970. I did that once.

A Dead-End That Wasn't

The contenttable.content field was consistently 150 characters. This looked like a deliberate truncation to defeat extraction. But the actual content was never supposed to be in that column — the new editor stored everything in local files referenced by entryPath. The content column was just a search index. Once I followed the entryPath trail, I had the full text of every note.

What The Script Does

The whole thing is a single Python file. It connects to the three SQLite databases, walks the folder tree, maps every note to its content source, converts JSON blocks to Markdown when needed, and writes the output organized by folder.

git clone https://github.com/chncaesar/youdao-to-obsidian.git
cd youdao-to-obsidian
pip3 install beautifulsoup4
python3 youdao_migrate.py

The script auto-detects your account and data directory. Output goes to ~/Desktop/obsidian/ by default. Each note gets a .md file with YAML frontmatter preserving the original title, creation date, and source ID.

I also bundled a Claude Code Skill in the repo — drop it into ~/.claude/skills/ and saying "export my Youdao notes" triggers the whole pipeline without remembering flags.

What Came Out

The final export: 2,285 notes across 253 folders. Mixed Chinese, English, and code content with no encoding issues. Tables, code blocks, images, lists, and blockquotes all converted correctly from the JSON block tree. Some notes were empty bodies with attachments only, handled gracefully.

Open ~/Desktop/obsidian as an Obsidian vault and everything is there.

Why This Worked

The most interesting part of this project was not the parser or the block converter.

It was the realization that a closed-format application with no export feature had been storing all my data in plain, unencrypted SQLite files, with a documented-enough block structure that could be reverse-engineered in an afternoon.

Two thousand notes. Years of writing. The application offered no way to take them out. They were never locked in. I just hadn't looked.

GitHub: github.com/chncaesar/youdao-to-obsidian

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

I Don't Understand Embedded. I Was Still the Only One Who Could Ship It.

Antonio Zhu — Fri, 26 Jun 2026 07:25:23 +0000

The local test suite was green. Eleven of eleven. I told the agent we had test coverage, and I said commit and push. We shipped an SDK that had never once been compiled by the chip's real compiler.

I write backend systems. I do not write firmware. The project generates C code for a microcontroller, and the generated code had to compile inside CDK — the vendor's build environment — on a Windows machine, against a RISC-V cross-compiler, inside a packaging system I had never used. None of that existed on my Linux box. The eleven passing tests ran under host gcc — the compiler that builds programs for the machine they run on. The code that mattered needed a different compiler, for a different chip, in a place I couldn't reach. Two compilers, two worlds. My tests lived in the wrong one.

A day later the first error came back from the Windows machine. Then another. Then five more.

Seven shots

The errors arrived one at a time, and the agent answered each the same way: a confident "root cause:" and a fix pushed to the repo. A header file was missing. A type name was wrong — bugs no real compiler had ever touched. Then the SDK wasn't being compiled at all: an obscure manifest setting had been left out. Then the chip's pin names were wrong — the same pin called one thing in the SDK the agent wrote against, and another thing in the SDK CDK actually shipped. Then an entire driver file silently compiled to nothing, because the switch that turned it on lived in a generated file the compiler couldn't see. Then the same wall again, because the last fix had patched a symptom and the real problem was the architecture.

Seven rounds. Each one the agent called the root cause. Each one was real, and each one was only the outermost skin of the next.

What I want to point at is not the bugs. It is the shape of the loop. The agent fired a fix in about three seconds. Verifying it cost me minutes to hours: pull the code on Windows, run the full CDK build, read the error output, copy it back. The actual feedback loop, the one that touched ground truth, ran at human speed across two machines that could not talk to each other, with me manually shuttling errors between them. I had built an elaborate multi-agent workflow, and the real oracle in it was a person doing copy-paste.

Why it couldn't stop

A confident "root cause:" at every step is not a sign of convergence. It is a sign of nothing. The agent emitted the prose of certainty regardless of whether it was getting closer or flailing, and at one point the fix it proposed was to simply rip out the switch that had silenced the driver file, so the thing would compile — a hack I shut down with a flat "that's too dirty." Only after that did the real fix surface: let the driver be chosen by which file you compile in, not by a switch buried in a file the compiler never sees. A structural change, not another patch.

Here is the part worth sitting with. The agent never said the one true sentence: I cannot see the target. Every fix I am giving you is a guess. Stop pulling — go install the RISC-V toolchain, and then I'll be useful. It never said it because each guess cost the agent three seconds and cost me an afternoon, and the agent does not pay that bill. An agent that doesn't bear the cost of a wrong guess will always prefer firing one more shot over asking for the instrument that would let it aim. The economics are silent, and they run entirely against the person at the keyboard.

The briefing that wouldn't have helped

The obvious lesson is the disappointing one: I should have explained the new component's mechanics to the agent up front. Tell it how the build environment wants its manifest written, how it pulls components into a build, where it expects the pieces to sit. Brief the new role, wire it to the existing ones, and the seven rounds collapse to zero.

Except briefing the agent wouldn't have helped. The agent was not ignorant of CDK — it knew the build environment well enough to scaffold a component from scratch, write the manifest, lay out the search paths. At one point it explained, fluently and at length, how CDK resolves dependencies. The explanation was wrong, but it was not uninformed. The trap is exactly this: general knowledge of CDK is not the same as knowing how this version, wired to this version of the SDK, would actually behave when the build ran. The setting that had been left out, the manifest format, the pin names — those were facts about the runtime behavior of a target neither of us could observe. Its real knowledge ran right up to the edge of the part that bites, with no seam to mark where one ended and the other began.

Here is where an experienced embedded engineer would have done something the agent could not. The port layer was written against one copy of the chip's SDK; CDK shipped a different copy. To a veteran, "two sources of the same SDK" trips a reflex — same chip, two SDKs, the symbols will not match, go diff them now. It's not magic. Given the right prompt, a smart model can produce the same checklist. The gap is not capability, it's posture: an engineer's scar rewrites their default to suspicion; a model's default is confidence — it charges. Someone has to steer it. In that session nobody did, because neither of us knew there was a trap to steer toward. And the second reason is blunter, and it doesn't care how smart the model is: the second SDK wasn't in its context. It lived on the Windows machine. The agent never had both files. You cannot glance at a trap, or be prompted to look for one, that is sitting in another room.

So the question stops being "how do I brief the agent" and becomes "what does anyone do when the ground truth is unknown to everyone and lives on a machine I'll never see."

The scout

You don't translate the wall. You admit it's dark, and you send the cheapest possible probe to light it up once — before writing the design, before writing the code. The move I should have made on day one was to put the RISC-V compiler on my own machine and run a syntax-only pass over the generated code — compile it just far enough to surface errors, without building a real binary. Seconds, locally, instead of symbol mismatches arriving through someone's clipboard a week later. Not because it would tell me everything. Because it would drag a piece of that unreachable world into a place I could actually touch.

This does not abolish trial-and-error. Trial-and-error is how you explore the genuinely unknown; there is no version of this work where you think hard enough up front to skip it. What you get to choose is where you hit the wall, whose time you spend hitting it, and whether you hit it once or seven times. A scout doesn't avoid the dark. A scout pays the smallest price to make a piece of it known, and does it before committing the expedition.

Second act: what I actually built

Diagnosis without a fix is just another complaint about AI. So after the firmware finally linked, I went back and changed the distance between the agent and the truth it couldn't reach. Three changes, and they sit at three very different levels — it's worth being honest about which ones actually closed the gap and which ones only narrowed it.

Tear the wall down. The strongest fix was to make the code generator emit the CDK project file itself — the list of source files, the search paths, the memory layout, all of it. Two of the seven errors came from a human hand-configuring CDK and missing something. The fix wasn't to verify that configuration more carefully. It was to delete the manual step entirely, so there was nothing left to misconfigure. This is the move I'd never made in any earlier post: not adding a layer of verification, but removing the thing that needed verifying. When you can make a stretch of unknown terrain simply cease to exist, that beats any amount of careful scouting.

Raise a telescope — and admit where it points. I added a check that runs at generation time, doing a syntax-only pass over the core SDK code, wired into the test suite. It pulls the type-name and missing-value class of bug from "your clipboard, days later" to "a local test, seconds later." That is real. But it runs under host gcc — my machine's compiler — not the RISC-V one, and so the pin-name mismatches, the manifest setting, the switch the compiler couldn't see — none of those are catchable by it, because they live in a world host gcc can never enter. The telescope got closer. It is still not aimed at the mountain that actually matters. The probe that would close that boundary — the RISC-V compiler running the same syntax-only pass locally on every build — I still have not installed. I know exactly what it is. It is sitting on the ground next to me. That is the honest state of this system.

Draw a map for the next one. I wrote the hard-won facts down as rules: the manifest format, the missing setting, a table of which pin names differ. This froze the intelligence the seven shots cost me. These rules are loaded at the start of every session — they do take effect. But unlike the other two fixes, which are automated and need no further human attention, written rules depend on maintenance: someone has to keep them accurate, scope them correctly, and phrase them precisely enough that the next agent doesn't misinterpret them. It's the most human-dependent fix of the three.

What a harness actually is

I used to think the missing step in AI-assisted work was verification — check the behavior, check the spec, check for the same bug elsewhere. That's still true, and I've written it before. This time taught me the step underneath it.

An agent only thinks inside its context. That isn't a limitation you fix; it's the shape of the thing. It knew the build environment in general — enough to sound, and be, genuinely competent. What it could not know was how this specific target would behave when the build actually ran, and it could not feel the seam between the two. Its real knowledge ran right up to the edge of the part that bites. So it didn't say "I'm blind." It fired seven confident shots at a wall, and the confidence came from the knowledge that was real. The danger was never that it couldn't see. The danger was that it couldn't tell where its sight ended.

A person has to stand at that boundary and say the wall is dark. The person doesn't need to understand what's behind it — I didn't, and I still don't. What the person does is the one thing the agent structurally won't: bear the cost of being blind, and spend it deliberately on making the dark known. That is what a harness is. Not a test suite. A harness is the work of shortening the distance between an agent and a ground truth it will never walk toward on its own — because it doesn't know the truth is out there, and it doesn't pay the price of not knowing.

I can't write firmware. I couldn't brief the agent on a single thing about that chip. And I was still the only one who could ship it, because shipping it had nothing to do with understanding embedded development. It had to do with standing on the boundary, admitting it was dark, and dragging the far machine one step closer. When the agent writes more of the code than you can read, that is the job that's left. Not knowing the domain. Knowing which wall nobody has hit yet, and being willing to pay to hit it first.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

Your Agent Checked Everything. It Was Still Wrong.

Antonio Zhu — Mon, 22 Jun 2026 01:51:52 +0000

I have been running a multi-agent development workflow for months now — one model writes the design, another generates the code, a third reviews the implementation, and I approve the result. It works well most of the time. But recently, three failures went through this pipeline undetected, and they share a pattern I had not been able to articulate until all three were on the table.

They are not impressive bugs. The individual root causes are straightforward once you see them. What makes them worth writing about is what they reveal about the structure of this kind of failure — and what kind of verification could have caught them before they reached production.

Case 1: The retry loop that never fired

An ETL pipeline synced data from a third-party ERP API to a PostgreSQL warehouse. Every 5 to 15 minutes, it pulled incremental changes using a session-based authentication mechanism. The code had a standard retry loop: three attempts, exponential backoff, and a resetLogin() call on failure to re-authenticate before the next attempt. It had worked for weeks.

Then one afternoon, every sync job started failing with the same error: COPY from stdin failed: expected N values, got 1. The pipeline reported the error and retried. And retried. And kept failing, for hours, until someone noticed.

The retry loop existed in the code. resetLogin() existed in the code. Neither had ever triggered. The reason took some investigation. When the ERP session expired after roughly 8.5 hours, the API did not return a 401 or a 403 or any HTTP error. It returned an HTTP 200 with a body that decoded to [["error message"]] — a structurally valid JSON array containing one row with one column. The Go JSON decoder had no reason to produce an error. The retry condition checked if err != nil, found nothing, and moved on with what it believed was a single-row result set.

The fix was not to improve the retry logic. The fix was a background goroutine that proactively refreshes the session on a 4-hour ticker — a keepalive that renders the reactive recovery path irrelevant. The retry loop, the piece of the system that was supposed to handle this exact scenario, had been dead on arrival.

Case 2: The coordinates that never existed

A code generator in a desktop tool produced C source files for an embedded microcontroller. Given a visual UI design, it emitted header files with widget macro definitions, a context file with event dispatch functions, and resource indices mapping image addresses in external flash memory. Developers compiled the output into their firmware, flashed the chip, and saw something strange: dynamic text widgets rendering at position (0, 0) regardless of where they had been placed in the design.

The generated code compiled without warnings. The linker found all referenced symbols. No function returned an error. Everything looked complete. But the runtime widget table — a separate generated file that maps each widget's ID to its x, y, width, and height — had never been written. Nobody had called the method that produced it. The header file declared the widget struct type with x/y fields. The resource manifest carried coordinate information. The design document described the widget table format. The code generator simply never emitted it.

The generated output was reviewed for content correctness. The reviewer confirmed that the header macros pointed to the right resource addresses, that the event routing was correct, that the page definitions matched the design. All of that was true. Nobody asked: are we generating all the files we need to generate?

Case 3: Read the instructions, not the comment

I was integrating an SDK for a new microcontroller. The vendor had provided a zip file with the chip's SDK, and the directory structure looked right: startup file, linker scripts for the specific chip model, peripheral drivers for SPI, DMA, GPIO — everything I expected.

The startup.S file opened with a comment header:

; GCC for CSKY Embedded Processors

CSKY is a different embedded CPU architecture, not the one this chip used. The datasheet clearly stated the chip was RISC-V. But the SDK directory was named for this specific chip family, the subdirectories matched, and the startup file was sitting right where it belonged. The comment said one thing. The directory name said another. Which was correct?

Two facts resolved it. First, the vendor had accidentally delivered the SDK for a different chip in the same product family — one that used CSKY. The directory name was misleading. Second, when the correct SDK arrived, its startup.S had the same CSKY comment in the header, because the vendor had copied the template from a third-party toolchain and never cleaned it up. The actual instructions told a different story:

csrw    mtvec, a0        ; RISC-V: write machine trap vector
la      sp, g_top_irqstack
jal     main             ; RISC-V: jump-and-link to main

The simplest verification was a grep: grep -c "csrw\|mret" startup.S returned 3. It was RISC-V. The comment was a fossil.

Not an Intelligence Problem

All three agents in my workflow — the designer, the implementer, the reviewer — did something that, in isolation, was correct. The designer wrote a spec that matched the task. The implementer produced code that matched the spec. The reviewer confirmed the match. Every verification step passed. The system was consistent. It was consistently wrong.

This is not an intelligence problem. It is a boundary problem. The agent does exactly what it is asked to do, within the context it is given. No one told it where the context ends.

In Case 1, the context was "check if the HTTP call returned an error." No one said "also check whether the successful response actually contains data."

In Case 2, the context was "check if the generated files are correct." No one said "also check whether all required output files exist."

In Case 3, the context was "trust the SDK directory structure and documentation to be correct." No one said "verify the architecture claim against the actual instruction stream."

In every case, the agent performed a complete verification of what it understood to be the scope of the task. The scope was wrong. And that gap — between what the agent checks and what actually needs to be true — is the failure mode that an AI-assisted workflow is structurally blind to.

This is not a bug in the agent. It is a missing layer in the workflow. The agent will verify the things you tell it to verify. It will not independently discover new categories of things to verify. That discovery is still engineering.

What belongs on the checklist

Here is what they look like.

1. Semantic output validation: check what the success means, not just that it returned success.

An API call, a function return, a system call — each has a success path and a failure path. But some systems encode failure inside success. After every external call, ask: does the returned data look like data, or does it look like an error in disguise? Check the row count. Check the structure. Scan for error keywords. If the caller received 1 row when the expected number of columns is much larger, the data is already suspect regardless of what err says.

2. Output completeness: verify that all required artifacts exist, not just that the ones that exist are correct.

Code generation produces multiple files. Some are visible in the output directory. Some should be but are not. Before accepting a generation result, enumerate the expected output files and confirm each one exists as a non-empty file. Do not accept "the generated files look correct" as a substitute for "all generated files are present."

3. Ground-truth verification: for any technical claim that can be tested by a machine, test it by a machine.

Comments can lie. File names can lie. Directory structures can lie. The CPU architecture of a .S file is not whatever the header comment says — it is whatever instructions the assembler would emit. The format of a binary file is not whatever the README claims — it is whatever the bytes at specific offsets contain. Before any agent workflow makes a design decision based on a technical assumption, verify that assumption with a command that reads the artifact directly. Do not pass claims forward unchecked.

None of these three checkpoints is dramatic. Each is small enough to be added to a task definition or a review stage without substantially changing the workflow. Together, they cover the three failure modes I have now seen multiple times: undetected failure inside a successful response, missing output from a code generator, and a false claim repeated by a toolchain artifact.

The agent is not going to ask itself "what should I also verify?" That question — what else could be wrong even when everything I checked is right — is not something an agent can generate from within its own context. It has to come from outside. It has to be designed. When you set up a multi-agent workflow, you are not just designing a pipeline for code. You are designing the boundaries of what each agent will treat as ground truth. If you do not place verification checkpoints at those boundaries, no one will.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

AI Fixed The Bug. Then I Found Two More Just Like It.

Antonio Zhu — Sun, 21 Jun 2026 12:55:14 +0000

I reported a bug. AI fixed it. Three days later, the same bug appeared somewhere else. I reported it again, AI fixed it again, and two weeks after that a third instance surfaced — same root cause, different location, different symptom. At some point I realized the problem was not that AI kept making the mistake. The problem was that I kept treating each occurrence as a separate incident.

The Bug

Early in the project I had established a rule: all monetary values must be stored as integers representing cents. Never floating point, never doubles, always integers. The rule existed because floating-point arithmetic on money produces invisible precision errors that accumulate silently over time. It was documented. The codebase had utility functions for converting between display values and stored integers.

Despite all of this, the same mistake appeared three times across different parts of the codebase:

// first occurrence
final amount = double.tryParse(controller.text) ?? 0.0;

// second occurrence, different feature
final price = double.tryParse(priceInput.text);

// third occurrence, different feature again
final currentPrice = double.parse(apiResponse['price']);

Each time, AI had been asked to implement a new feature. Each time, it reached for double.tryParse because that is the natural way to parse a number from text input — it's what most Dart code does, and it's what the training data overwhelmingly shows. Each time, a code review caught the specific instance that was reported. And each time, nobody checked whether the same pattern existed elsewhere.

How AI Fixes Bugs

When you show AI a bug, it focuses on that bug. It reads the surrounding code, understands the problem, and proposes a fix — and the fix is usually correct for the code it looked at. What it does not do is search the rest of the project for other places where the same mistake might exist. This is not a failure of intelligence. It is a failure of scope. AI responds to what you show it, and it does not independently decide to audit your entire codebase for related patterns.

The difference becomes clear when you compare it to how an experienced engineer handles the same situation. Someone who has worked in a codebase for months develops an instinct for where the same patterns get repeated. When they fix a bug, they often think: I've seen this structure elsewhere, let me check those places too. That instinct comes from having written and read most of the code themselves. AI does not have this map. Every conversation starts fresh, and even if you have fixed the same mistake twice before in previous sessions, AI has no memory of having seen the pattern in your codebase. It does not know to be suspicious.

The Broader Pattern

The double.tryParse issue was one example, but the same dynamic played out several more times. After fixing a race condition in one part of the UI, I found two more places with the same structure. After fixing an error message that was leaking internal exception details to users, I found four more places doing the same thing. After fixing a database write operation that was missing an invalidation call before navigation, I found five more. Each time, AI fixed the reported instance correctly. Each time, the other instances were waiting quietly.

The reason this happens more with AI than it did when I wrote most of the code myself is straightforward. When I introduce a bug, I at least know roughly where that pattern appears, because I wrote it. With AI generating large blocks of implementation that I review but don't write line by line, the mental map is thinner. And AI will consistently apply the same habits across multiple features, because it is generating from the same set of assumptions and defaults — which means when it has a bad habit, that habit is likely distributed across every place it was asked to do something similar.

What Changed

After the third occurrence of the double.tryParse bug, I changed how I approach AI-assisted fixes. Now, before I show AI the specific fix, I do one step first: search the entire codebase for the pattern.

grep -r "double.tryParse" lib/
grep -r "double.parse" lib/

I make a list of every occurrence, then fix all of them in one pass. This sounds obvious, but in practice it is easy to skip when AI is handling the fix and everything feels handled. The reported instance gets resolved, the review looks clean, and the invisible copies wait for their turn to surface.

The Role That Has Not Changed

Code generation is increasingly handled by AI. Code review is increasingly assisted by AI. Architecture can increasingly be drafted by AI. But the role that seems to be not just surviving but becoming more important is the engineer who holds the global view — who knows what patterns are repeated and where, who knows what invariants must hold across the entire system, and who, when a bug appears in one place, asks whether the same mistake exists somewhere else.

AI does not have that view. It cannot. Every session starts fresh, and every conversation focuses on what was shown. The global view of your codebase lives in your head, and when AI is writing code faster than you can track, that global view is exactly what you need to protect. When you ask AI to fix a bug, the fix will likely be correct for the code you showed it. Before you accept that fix, take a minute and search for the same pattern. That question — where else could this be? — used to be instinctive. With AI writing more of the code, it needs to become deliberate.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

The Design Doc Was Wrong. AI Trusted It Anyway.

Antonio Zhu — Sun, 21 Jun 2026 12:54:18 +0000

I was building a new module for a side project, and the design document looked thorough. Claude had written it, I had reviewed it, and everything seemed reasonable. One section described how to calculate a derived value from two stored fields — both multiplied by 100 to preserve two decimal places — and gave the formula:

Result = fieldA × 100 × fieldB × 100 / 10000

The logic made sense on the surface. Both fields carried 100x precision, so the divisor cancels them out. DeepSeek implemented it. The review agent verified it. I approved it. Then I opened the simulator and saw a value that should have been 1,200 displayed as 120,000.

The Formula Was Wrong By A Factor Of 100

The correct divisor was 1,000,000, not 10,000. When you multiply two fields that are each inflated by 100x, the product is inflated by 10,000x — so you need to divide by 1,000,000 to get back to base units, not 10,000. The design document had gotten this wrong, and everything downstream had faithfully reproduced that mistake.

That part was easy to fix once I saw it. What I kept thinking about afterward was the process that had failed.

Three Systems Read The Same Wrong Formula

A human engineer reading that formula would probably do something instinctive: substitute real numbers. Two quantities, each stored as integer × 100. Say fieldA = 10000 and fieldB = 1200. Multiply: 12,000,000. Divide by 10,000: 1,200. But the expected result should be 12. That doesn't add up. The error surfaces in about five seconds, not through formal verification, just through the habit of running a quick sanity check before trusting a formula.

None of the three systems in my workflow did this. DeepSeek read the design document and implemented the formula exactly as written. The review agent checked whether the implementation matched the design and confirmed that it did. I read both and approved them. Every statement was technically correct. The document was the source of truth, the code faithfully implemented the document, and the review verified the match. Nobody ran the numbers.

The Assumption I Had Been Making

After I fixed the divisor, I started thinking about what had actually failed — and it wasn't the math. The math error was trivial once I looked at it carefully. What failed was a deeper assumption I had been making about how AI-assisted development works.

I had been treating design documents as verified artifacts. The workflow in my head was:

Design Document → AI Implementation → AI Review → Human Approval

The implicit assumption embedded in this workflow was that the design document itself was correct. If it wasn't, the whole chain would faithfully reproduce the error — which is exactly what happened.

Documents Are Not Inputs. They Are Claims.

A design document is not a verified fact. It is a claim made by whoever wrote it, and in this case that was Claude. Claude is very good at generating coherent, plausible-looking technical documentation. It is considerably less good at verifying whether the math embedded in that documentation is actually correct. I had been asking it to do both things at once — reason about architecture and verify arithmetic — without recognizing that it handles those two responsibilities very differently. It did the first well. It did the second poorly. And I hadn't thought to separate them.

The fix I've settled on is simple: any formula in a design document is treated as unverified until someone has substituted concrete numbers and checked the result by hand. Not because AI gets formulas wrong frequently, but because when it does, the error propagates cleanly and invisibly through every downstream step. The formula is wrong, the implementation is wrong, the review confirms the implementation matches the formula, and everything is consistent. Everything is wrong.

The Code Did Exactly What It Was Supposed To Do

Most bugs in AI-generated code are implementation bugs — a condition is inverted, a null check is missing, an edge case is unhandled. Those are failures where the code doesn't implement the intent correctly. This was different. The code implemented the intent perfectly. The intent was wrong. That category of error is much harder to catch with code review, because code review asks whether the code does what it's supposed to do. The answer here was yes. Nobody asked whether what it was supposed to do was actually correct.

That question — is the specification right, not just the implementation — is increasingly where I think human judgment matters most in an AI-assisted workflow. AI is getting quite good at turning specifications into working code. It is getting reasonably good at catching implementation bugs. But it tends to treat the specification itself as ground truth, which means the work of questioning whether the spec makes sense in the first place is still entirely yours. AI will implement whatever you give it, with increasing reliability. The question is whether what you gave it was right.

And right now, that part is still on you.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

DEV Community: Antonio Zhu

db-semantic-mcp Gives AI Agents a Safe Semantic Map of Your Database

The missing layer between agents and databases

What it exposes

The semantic file is intentionally boring

Why no SQL execution?

Built for real databases, not demo schemas

How an agent uses it

Configuration shape

What this is good for

The broader direction

OpenCode Session Framework Internals

Key Takeaways

The Minimal Client Contract

Session Creation Is Identity, Not Execution

Prompt Submission Is Admission

Execution Needs A Per-Session Coordinator

The Runner Is A Drain Loop, Not One Model Call

Status Should Come From Execution, Not Transcript Guessing

Events Are The Observation Boundary

Messages Are Structured Projections

Interrupt Is Not Reset

Compatibility Is A Shell Around The Runtime

What To Copy

The Core Shape

My OpenCode Database Was Mostly Empty Space

The misleading part of deleting data

Why OpenCode makes this visible

The useful number is freelist percentage

Why I did not want a clever cleaner

The safety sequence matters

A small tool is enough

The broader lesson

OpenCode Tool Calling Internals

Key Takeaways

Why Tool Calling Needs A Runtime Layer

How The Pieces Connect

Design Principle 1: Keep A Provider-Independent Tool Contract

Design Principle 2: Build A Runtime Tool Catalog

Design Principle 3: Put Permissions Inside Execution

Design Principle 4: Persist Tool Calls As State

Design Principle 5: Normalize At Runtime Boundaries

What OpenCode Gets Right

Where The Design Is Still Expensive

OpenCode V2 Compaction Internals

Key Takeaways

Core Design

How It Works

Trigger

Split History Into head And recent

Generate The Summary

Persist The Checkpoint

Retry From The Checkpoint

Repeated Compaction

What The Model Sees After Compaction

Configuration Surface

Strengths

Limitations

Claims The Current V2 Code Does Not Support

My Agent Kept Writing sleep Loops. So I Gave It a Better Primitive

Why agents reach for sleep

The primitive

Six Laws for Talking to AI

Data Snapshot

Law 1: The gap between knowing and writing is the whole cost.

Law 2: Assess the blast radius. Every time.

Law 3: Send the full spec. Not one sentence at a time.

Law 4: An instruction under ten characters is a puzzle.

Law 5: A bug in file A is a bug in files B through Z.

Law 6: "This" and "all" are not the same thing. Say which.

The Compounding Asset

I Reverse Engineered a Closed-Format App. Everything Was in SQLite.

Where The Data Was

What The Database Contained

The JSON Block Tree

Three Things That Wasted My Time

A Dead-End That Wasn't

What The Script Does

What Came Out

Why This Worked

Split History Into `head` And `recent`