From e20e80461fbb94c72c0fc0d7f18298ac471deb16 Mon Sep 17 00:00:00 2001 From: Nayan Date: Fri, 14 Aug 2026 13:23:35 +0530 Subject: [PATCH] docs: explain the opencode retry, view mode, and the troubleshooting paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CONTRIBUTING.md | 31 ++++++++++++++++++++++----- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++ apps/cli/README.md | 28 +++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fe5cc5..9101288 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 `` 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 `` 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. diff --git a/README.md b/README.md index 1e1f50c..f75866e 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/apps/cli/README.md b/apps/cli/README.md index 8aaf37e..9146a0f 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -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.