docs: explain the opencode retry, view mode, and the troubleshooting paths

Documents what the preceding commits added, so it lands after them rather than
describing things that are not there yet.

The opencode caveat says the useful thing rather than the reassuring one: when
structured output is lost the change chips go with it, but the edit does not —
the files are already written. Thinking models reject the forced tool call, get
retried once without it, and are remembered for the rest of the process.
Troubleshooting covers the `tool_choice` error, a missing opencode binary,
missing credentials, and undo needing Git.

That section is duplicated verbatim into `apps/cli/README.md` rather than
linked, because npmjs.com renders that file on the package page and a relative
link there goes nowhere.

Also the `H` and `F` shortcut rows, and an "Edit and View" section for the frame
list, restacking and the minimap. And three entries in CONTRIBUTING's conscious
choices, which are the decisions most likely to be undone by someone who does
not know why: the minimap draws rectangles rather than thumbnails, frame reorder
publishes `z-index` rather than re-parenting, and a `feedback: "none"` draggable
needs `POINTER_ONLY` sensors.
This commit is contained in:
Nayan
2026-08-14 13:23:35 +05:30
parent 7dd09591ea
commit e20e80461f
3 changed files with 106 additions and 5 deletions
+26 -5
View File
@@ -196,11 +196,15 @@ Gaps handled explicitly rather than faked:
inlined in the prompt as it is for Codex.
- **`--model` wants `provider/model`.** A bare id cannot be resolved to a provider, so it is
dropped with a warning rather than silently ignored.
- **Structured output is a prompt convention, not a constrained decode.** The model emits its
JSON inside `<structuredoutput>` tags within ordinary prose, and opencode's own extractor
frequently fails to lift it back out. The adapter parses the tag itself and strips it from the
streamed transcript on the way past — including when the opening tag arrives split across two
deltas.
- **Structured output is fragile twice over.** On the wire, `format` is a *forced tool call* —
opencode registers an internal StructuredOutput tool and sets `toolChoice: "required"`, which
providers reject outright on thinking/reasoning models (opencode#15226, closed upstream). The
adapter classifies that rejection, retries the turn once without `format`, and remembers the
model. In the text, the JSON arrives inside `<structuredoutput>` tags within ordinary prose —
a convention the system prompt now carries too, so it survives `format` being dropped — and
opencode's own extractor frequently fails to lift it back out. The adapter parses the tag
itself and strips it from the streamed transcript on the way past — including when the
opening tag arrives split across two deltas.
The wire types are declared in `providers/opencode-wire.ts` rather than imported from the SDK:
the SDK's generated `Event` union omits `message.part.delta` entirely (237 of 313 events in a
@@ -389,6 +393,23 @@ Conscious engineering choices, not oversights:
- **Session persistence uses the SDK's own `persistSession`** plus Airship's `~/.airship/history`
bundles (which record each `sessionId`), so resume survives a daemon restart — without a custom
`SessionStore`. A `SessionStore` adapter (S3/Redis) is the path for multi-host hosted mode.
- **The minimap draws rectangles, not thumbnails.** Every frame is a live same-origin
`iframe` running a full instance of the user's app. There is no paint capture anywhere in
the overlay and no cheap way to add one — `FrameAgent` exposes DOM, not pixels — an
`iframe` cannot be duplicated, and cloning one would boot a ninth app against a cap of
eight. So `canvas/minimap.ts` positions plain `div`s, the way `chrome-layer.ts` draws
every other piece of canvas chrome.
- **Frame reorder publishes `z-index`; it never moves DOM nodes.** Moving an `iframe` in the
document tears down and rebuilds its browsing context, so the obvious implementation of
drag-to-restack would reload the app inside whichever frame you dragged, losing its route
and scroll position. `FrameManager.reorder` splices the array and `applyOrder` writes the
index as `z-index` instead; `frames.test.ts` asserts that no element moves.
- **A `feedback: "none"` draggable must be registered `POINTER_ONLY`.** dnd-kit's
`KeyboardSensor` needs `dragOperation.shape`, which only the Feedback plugin publishes —
so a "none" draggable starts a keyboard drag that no arrow key can move, and swallows the
Tab out of it. Nine of the overlay's draggables have no keyboard route for this reason;
where one is wanted it is a real command beside the drag, not a keyboard drag (see
`FramesPanel.moveBy`, and `num-field.ts`'s `stepBy` beside its scrub).
- **Deferred for now:** multi-element select, `startup()` pre-warm (a latency optimization that
requires threading a warm handle through each edit), and the Vite/Next plugin wrappers plus
hosted mode.
+52
View File
@@ -114,6 +114,30 @@ On the canvas:
| ⌘/ctrl-wheel, pinch | zoom at cursor |
| space-drag, middle-drag | pan |
| ⇧1 / ⇧2 / ⇧0 | fit / zoom to selection / 100% |
| `H` | hand tool (view mode) |
| `F` | add a frame |
## Edit and View
The two modes point the editor at different things, and the panels follow.
**Edit** is about an element: hover to highlight, click to select, and the agent panel and
inspector are open on either side of it.
**View** is about your frames. The page underneath is fully interactive — click through it,
fill in forms, scroll — so there is no element selection, and the two panels that depend on
one step aside. In their place the left panel lists every frame, and a minimap appears in
the bottom-right corner:
- Click a frame in the list to go to it without changing your zoom; double-click to zoom
to it. Rename it in place, and use `⋯` for its device size, rotate, duplicate and delete.
- The list is stacking order, front-most at the top. Drag a row anywhere along it — or
press ↑↓ on its handle — to restack frames that overlap on the canvas; up is forward.
- Drag the minimap's indicator and the canvas travels with it; press anywhere else on the
map to jump there. Pan far off your frames and it keeps pointing back at them.
Your panel arrangement is remembered per mode, so switching back returns the inspector
exactly as you left it.
## Inspector
@@ -149,6 +173,12 @@ Undo is Airship's, not the agent's. It keeps the previous version of every file
undo works on all three. One catch: `codex` and `opencode` get that previous version from Git,
so **undo needs your project to be a Git repo on those two**. Airship warns you at startup.
One more `opencode` quirk: the one-line summary and the follow-up suggestion chips come from a
JSON block the model is asked to append to its reply. A model that ignores the instruction
loses the chips and gets a plainer commit message — never the edit itself. Models with thinking
enabled reject opencode's own structured-output request outright; Airship detects that, retries
the turn without it, and remembers not to ask that model again.
### Authentication
Airship reuses whatever the chosen agent already has, and warns at startup if it finds nothing.
@@ -374,6 +404,28 @@ first one that answers:
With `--exec` it's the opposite: the port has to be *free*, since Airship is about to start your
dev server on it. It won't start one on a port that's already taken.
## Troubleshooting
**Every `opencode` turn fails with "Thinking mode does not support this tool_choice".**
The provider is rejecting the structured-output request opencode sends — it is implemented as a
forced tool call, which models with thinking/reasoning enabled refuse (opencode issue #15226,
closed upstream). Airship retries the turn without that request and remembers the model, so you
should see one warning row and a working edit. If it persists, pick a model without thinking
enabled, or disable thinking for your provider via `--opencode-config`.
**"No `opencode` binary found on PATH."**
The `opencode` CLI is a separate install (`brew install sst/tap/opencode`); Airship finds it on
PATH rather than bundling it.
**"No provider credentials found."**
Airship reuses the chosen agent's own login — see [Authentication](#authentication). For
`opencode` that means a provider key or `opencode auth login`; for `codex`, a `codex login` or
an API key; for `claude`, a `claude` login or `ANTHROPIC_API_KEY`.
**Undo does nothing, or diffs come back empty, on `codex` or `opencode`.**
Both reconstruct their diff baseline from Git, so the project must be a Git repository. Airship
warns about this at startup.
## Questions
Including the ones with unflattering answers.
+28
View File
@@ -151,6 +151,12 @@ Undo is Airship's, not the agent's. It keeps the previous version of every file
undo works on all three. One catch: `codex` and `opencode` get that previous version from Git,
so **undo needs your project to be a Git repo on those two**. Airship warns you at startup.
One more `opencode` quirk: the one-line summary and the follow-up suggestion chips come from a
JSON block the model is asked to append to its reply. A model that ignores the instruction
loses the chips and gets a plainer commit message — never the edit itself. Models with thinking
enabled reject opencode's own structured-output request outright; Airship detects that, retries
the turn without it, and remembers not to ask that model again.
### Authentication
Airship reuses whatever the chosen agent already has, and warns at startup if it finds nothing.
@@ -376,6 +382,28 @@ first one that answers:
With `--exec` it's the opposite: the port has to be *free*, since Airship is about to start your
dev server on it. It won't start one on a port that's already taken.
## Troubleshooting
**Every `opencode` turn fails with "Thinking mode does not support this tool_choice".**
The provider is rejecting the structured-output request opencode sends — it is implemented as a
forced tool call, which models with thinking/reasoning enabled refuse (opencode issue #15226,
closed upstream). Airship retries the turn without that request and remembers the model, so you
should see one warning row and a working edit. If it persists, pick a model without thinking
enabled, or disable thinking for your provider via `--opencode-config`.
**"No `opencode` binary found on PATH."**
The `opencode` CLI is a separate install (`brew install sst/tap/opencode`); Airship finds it on
PATH rather than bundling it.
**"No provider credentials found."**
Airship reuses the chosen agent's own login — see [Authentication](#authentication). For
`opencode` that means a provider key or `opencode auth login`; for `codex`, a `codex login` or
an API key; for `claude`, a `claude` login or `ANTHROPIC_API_KEY`.
**Undo does nothing, or diffs come back empty, on `codex` or `opencode`.**
Both reconstruct their diff baseline from Git, so the project must be a Git repository. Airship
warns about this at startup.
## Questions
Including the ones with unflattering answers.