Skip to content

Workbench foundations, query IDE, chat and a macOS test build - #1

Merged
jeffreyaven merged 66 commits into
mainfrom
m3-chat
Nov 20, 2026
Merged

jeffreyaven merged 66 commits into
mainfrom
m3-chat

Conversation

@jeffreyaven

@jeffreyaven jeffreyaven commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Draft, opened so that CI runs on the work so far. It is not a release.

What is in it

Everything built to date, which until now was only local:

  • Foundations: engine discovery and supervision, the pg wire query service, the provider explorer, the editor and the results grid.
  • Most of the query IDE: tabs, completion from provider metadata, the JSON cell viewer, history, export and "Copy as CLI".
  • Chat: the MCP client with approvals, the agent loop, the activity view, API key backends, and the GitHub Copilot CLI as a delegated agent.
  • The query library view.
  • A conversation that shows a turn as its answer, with charts and sortable result tables. See the section below.
  • The engine an installed app uses: the one it was installed with. See "Which engine the app starts" below.
  • CI: checks on Windows x64, Windows on Arm and macOS, and a job that builds a test build for macOS.

README.md has the architecture and the roadmap.

Conversation: answers, charts and tables

Added on 19 November, in the ten commits from 7553222 to cf7f595. Before this, a turn listed every tool call as a card, failed ones in red with the engine's error text, and a request for a plot came back as a chart made of text characters.

What changes for the operator:

  • A turn is shown as its answer. The calls the assistant made, with their SQL and results, are one list of steps above the answer. The list is open while the turn runs and folds away when it ends.
  • A call that failed is not listed, and its error text is drawn nowhere. The model still receives the engine's error untouched, corrects the statement and carries on. Each failed call is written to a log of the app's own, stackql_workbench_<UTC time>.log in <app data dir>/logs, apart from the engine's audit log. Help > Show Log File shows it. The Activity view still lists every statement with the engine's decision.
  • A result set is a table of every row: click a column to sort, and download it as CSV. The results pane of the editor sorts the same way.
  • A request for a chart is answered with a drawn one: bars, a line, an area, a pie or a scatter chart, in both themes, with a tooltip and the table of the same rows one click away.
  • When a turn ends, the line that heads its steps says what it used in tokens, as the provider counted it: 1 step 25,469 tokens in (12,631 cached), 158 out. The counts cover every call to the model in the turn and are never estimated. With the Copilot CLI they say how large a turn was, not what it cost, since that plan is billed by the request.

How a chart gets drawn: the model writes a fenced block of the language chart holding one JSON object that names a chart type and columns. The rows come from the most recent result set that has those columns. The webview reads the block as data and draws SVG with components in this repository. docs/charts.md has the format, the limits and the mark rules.

Choices made here that have not been reviewed yet:

  1. Charts are drawn in the webview from a block in the reply, not by a Rust plotting library behind a tool. A delegated agent is held to the engine's tools, so a host tool would not reach it, while a block in the reply works the same on both ways a turn runs. Drawing in the webview also keeps every colour a token, so charts follow the theme. There is no new dependency on either side.
  2. A call the operator was asked to approve stays in the steps whatever became of it, and shows why if it was approved and then failed. That outcome is the operator's own decision playing out, not a retry.
  3. Outside the steps, a turn shows the result sets of the statements the assistant ran in its last step, up to four. A first version showed only the last statement, and a real turn that ran two statements together showed that this hid the main one.
  4. A model is told how its work is shown, and how to ask for a chart, by one text in agent/guidance.rs. It is about presentation only. It says nothing about how a result is to be read, which stays the engine's, and a test holds it to that.

Which engine the app starts

Added on 19 November in eaaded3, for shipping the Workbench in the StackQL MSI and PKG. The app now defaults to the stackql it was installed with, since that pair is the one built and tested together. Only a path the operator sets under Settings comes before it.

  • Windows: stackql.exe in the folder of the Workbench executable, where the MSI puts it.
  • macOS: for an app that runs from a bundle, an engine inside the bundle beside the executable, and failing that /usr/local/bin/stackql, where the PKG puts the command.
  • STACKQL_BIN used to come before the engine beside the app and now comes after. When it is set and passed over, the status bar says so. A build from this repository has no installed engine, so there the variable is still tried first.

Neither installer has anything to configure for this. Two things to know when building them: under Program Files the provider cache goes to the app data directory, so a first run lists no providers, and on an Intel Mac the app cannot tell the PKG's /usr/local/bin/stackql from one linked there by a package manager.

What the installers take

Added on 19 November, from 1b8c4bf to c1b5565. CI now keeps what the MSI and the PKG are built from, on every run.

Artifact Holds
stackql-workbench-windows-x64 stackql-workbench.exe, the optimised build for x64, with its SHA-256
stackql-workbench-windows-arm64 stackql-workbench.exe, the optimised build for Arm, with its SHA-256
stackql-workbench-macos-universal-app the app bundle for Apple Silicon and Intel as a .tar.gz, with its SHA-256

Neither is signed for release. The StackQL release signs what it ships.

Both are built to need nothing from the system that has to be installed, and CI checks it.

  • Windows: the whole C runtime is linked into the executable. It used to ask Windows for seven Universal C runtime libraries. It now asks for 19 libraries that are all Windows itself. scripts/check-exe-imports.js reads the import tables and fails on a runtime library.
  • macOS: the app links only to system frameworks and libraries under /usr/lib, checked with otool.
  • The WebView2 page renderer is the one thing a Windows executable cannot carry. The app uses the one Windows has, which Microsoft says is included as part of Windows 11 and is on the vast majority of Windows 10 devices. Where none is found, the app shows a dialog with Microsoft's download address. The installers do not ship the runtime, so the binaries stay small. Where it is missing the MSI is to give the operator the option to install it, with Microsoft's bootstrapper. That is work in the stackql-windows-installer repository and is not done yet. A WebView2Runtime folder beside the app is still used when there is one.
  • The Mac app needs macOS 13 or later. The bundle declares that as its minimum, so an older macOS refuses to open it, and CI checks the declaration and what both architectures are built for. The pages need a renderer of that age, and on a Mac the renderer is the one macOS has.
  • The StackQL MSI is built for x64 and for arm64, so there is a Windows executable for each, built on a runner of that processor. The arm64 one is native, not the x64 one under emulation: Windows emulates x64 only from Windows 11, it could not be tried here, and the arm64 MSI ships an engine built for Arm. The import check also fails when an executable names the wrong processor.

A fix came with this: the engine is started again on a fresh port when it exits at once, which is what happens when something takes the port between it being chosen and bound. That was the cause of one failed check on Windows.

Workflow artifacts expire after 90 days. A build that ships should come from a tagged release, which this repository does not make yet.

The macOS test build

The Bundle (macOS, universal) job builds the app for Apple Silicon and Intel and keeps the disk image as the artifact stackql-workbench-macos-universal, on the run's summary page. The signature is ad hoc and nothing is notarised, so macOS has to be told to open it. The README section "Test build for macOS" says how.

What has been run

  • Windows 11: everything, against stackql v1.0.888. For the conversation work: lint, type check and 462 webview tests, and cargo fmt, clippy and the host tests (270 unit, 10 agent integration, 13 engine integration).
  • The conversation, the charts and the tables were driven in the built app on Windows in both themes, with a scripted model against the real engine: a declined approval, a call that failed and was not listed, each chart type, a chart that could not be drawn, sorting, and a CSV saved through the save dialog.
  • Two turns were run for real through the GitHub Copilot CLI 1.0.114 on claude-haiku-4.5. In the first the model wrote a chart block from the guidance on its first try. In the second three of its calls failed on the way: none was listed, and all three were in the log.
  • The token counts were checked against the Copilot CLI with one prompt to a probe, to see what the CLI sends, and one turn through the app, which showed the count on the steps line and in the log. The counts of the API key backends are read as their documentation describes and tested against stubs, not against the real services.
  • Which engine an installed app starts was run on Windows with a build of the app and a copy of stackql.exe in one folder, under six conditions: nothing set, STACKQL_BIN naming another engine, STACKQL_BIN pointing nowhere, a path in settings, both, and a path in settings that points nowhere. The folder was a writable one, so the data folder fallback under Program Files was not part of it. The macOS rule has unit tests only.
  • The page renderer was checked on Windows 11 with a build of the app in a folder of its own: the system's WebView2 with nothing beside it, the runtime in a WebView2Runtime folder when there was one, and the system's again when that folder held no runtime. The runtime in the folder was a copy of the installed one, not Microsoft's Fixed Version package. No machine without WebView2 was tried, and no freshly installed Windows 11. A machine without it was imitated by pointing the loader at an empty folder: the optimised build showed the dialog and exited.
  • macOS: the tests pass on the macOS runner in CI and the bundle job builds. The app has not been opened on a Mac, and no Mac older than macOS 13 was tried.
  • Windows on Arm: only in CI, on the windows-11-arm runner, against stackql v1.0.888 from the release's arm64 archive. Lint, the webview tests, clippy and the host tests pass there, the integration tests that start a real engine among them. The app has not been opened on an Arm machine, and the x64 executable was not tried under emulation.

Not run: Help > Show Log File has not been clicked, since it opens a window on the desktop. No API key backend has drawn a chart from a real model.

Generated with Claude Code

jeffreyaven and others added 30 commits November 18, 2026 08:30
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The engine MCP server writes stackql_mcp_server_*.log into its working directory, so those are ignored wherever they land.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Product name StackQL Workbench, binary stackql-workbench, identifier io.stackql.workbench. Lint, format, typecheck and test wiring for the webview and the host.

Dependencies beyond the stack table, with reasons: serde, serde_json and thiserror for typed IPC payloads and errors; futures-util to consume the pg wire row stream; windows-sys (Windows only) for the job object that ties engine processes to the app; vitest and jsdom for webview tests; eslint, typescript-eslint, eslint-plugin-react-hooks, eslint-config-prettier and prettier for the lint and format checks.

TypeScript is pinned to 6.0.x because typescript-eslint does not support 7 yet.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Adds the probe program and the findings. Simple protocol only, one statement per message, text values, no cancel, upstream failures surface as notices only with --pgsrv.debug.enable.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Discovery follows the documented resolution order and treats an explicit but wrong path as an error. The supervisor captures stderr and ties every child to the app: a kill-on-close job object on Windows, a process group plus a pipe watchdog on Unix. A test kills a stand-in app process and checks its child is gone.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
LocalConnection is the only Connection. It starts stackql srv on loopback with an explicit approot and --pgsrv.debug.enable, waits for SHOW VERSION, and watches for an unexpected exit. The query service uses the simple protocol, splits text into statements because srv runs only the first one in a message, counts rows itself, and reports only new notice text on the long-lived editor session. Explorer statements are built from validated, double-quoted identifiers.

Integration tests run against a real engine with the built-in provider only, and are skipped when no binary is found.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Three panes and a status bar over the typed host wrapper in src/host, the only module that imports Tauri. The explorer is a lazy tree built from metadata statements. The editor is one CodeMirror buffer with a StackQL dialect, and Ctrl+Enter or Cmd+Enter runs the selection or the whole buffer. The grid is virtualised, with a cell viewer that pretty-prints JSON and a messages tab for notices, errors and engine output.

A launcher runs Vitest from an upper-case drive letter, because Vitest fails on Windows when the working directory is spelled with a lower-case one.

Adds @lezer/highlight as a direct dependency for the highlight tags used by the editor theme. It was already installed as part of CodeMirror.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copying a name goes through a write-only host command built on arboard (text only, default features off), so it does not depend on webview focus or on how the platform webview treats the app origin.

The CI workflow runs format, lint, typecheck, tests and a debug build on windows-latest and macos-latest, with stackql installed so the integration tests are not skipped.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Running the supervisor tests on Linux showed the watchdog never signalled the process group: dash rejects 'kill -TERM -- -PGID'. The script now uses 'kill -s TERM -- -PGID', which dash and bash both accept. All supervisor and watchdog tests pass on Linux, including killing the parent with SIGKILL.

CLAUDE.md now reflects what M0 built: status, stack additions and version constraints, the real layout, the commands, and the srv behaviour found by the spike.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Provider nodes show the provider's own icon, resolved through the provider dictionary published by stackql.io. The host fetches and caches icons and hands them to the webview as data URLs, so the webview still makes no network calls. Icon paths from the dictionary are checked before use and only the dictionary host and stackql.io are contacted. A provider that cannot be resolved keeps the letter badge.

The app icon is now StackQL's favicon, generated from the 512px version in the stackql.io repository.

New dependencies: reqwest for HTTPS, with native-tls so the OS TLS stack and trust store are used and no extra build tools are needed on Windows; base64 for data URLs.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
stackql_preview and any other stackql_* provider are part of the engine and are not in the published dictionary. They now show StackQL's own icon, compiled in, instead of the letter badge.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The previous commit introduced a method named from_dictionary that takes self, which clippy rejects. No behaviour change.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ckends

The host runs the agent loop and owns the MCP client. The Connection trait gains the agent channel: LocalConnection starts stackql mcp over stdio through the supervisor, in the workspace safety mode, with its audit log under the app data directory. The engine classifies and gates statements. The host relays its approval prompts to the operator and never answers one itself.

InferenceBackend sits between the loop and a model. Backends: Gemini (generateContent), Anthropic (Messages API) and OpenAI-compatible (Chat Completions, which covers local inference). Each keeps the provider's reply and returns it untouched, so thought signatures and thinking blocks survive. API keys are read from the OS keychain and never reach settings, logs or the webview.

Upstream API failures reach the model as an empty result, so the host watches the MCP server's stderr during each tool call and adds a note for the model and the operator.

Tested without any API key: the backends against a local stub that records the request, and the loop against a real stackql mcp with a scripted model, covering tool calls, approval, decline, read_only refusal, stop and the audit log.

New dependencies: rmcp (the official Rust MCP SDK, client and async-rw transport only), keyring-core with windows-native-keyring-store and apple-native-keyring-store for the OS keychain. docs/spike-mcp.md records the MCP findings.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The chat pane shows each tool call the assistant makes, with the statement as SQL that can be opened in the editor. Row results appear in the same grid as editor results, marked as coming from the assistant. An approval prompt from the engine becomes a card showing the exact SQL, and nothing runs until the operator decides.

The activity pane merges the operator's statement history with the engine's agent audit log. Chat settings choose the backend, model and address and send the key to the OS keychain. With no backend the chat pane is hidden and the rest of the app is unchanged.

Verified in the running app against a local stand-in model: tool call, grid result, decline, approve, upstream failure note and the audit trail.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md and README.md now describe what exists: status and what has and has not been run, the real layout, the MCP server behaviour from the spike, the three backends and how they are built, and the engine-side questions the spikes raised.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…move it

The engine's --approot was fixed at <app data dir>/engine. It is now
resolved at each engine start, first hit wins:

1. the folder named in settings (new "Engine data folder" field)
2. .stackql beside the Workbench executable
3. <app data dir>/engine

The folder in settings is strict: a relative path, or one that cannot be
created or written to, stops the engine with a message that points at
Settings. The folder beside the executable falls through to the app data
folder when it cannot be written to, which is what happens for an app
installed under Program Files, and is skipped inside a macOS app bundle
because writing there breaks the bundle's signature. The settings pane
shows the folder in use, how it was chosen and the reason for a fallback.

The MCP server is started on the same folder as the running engine. The
audit log and statement history stay under the app data directory.

No new dependencies.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A method used to open into one flat list: required inputs, optional
inputs, then outputs. It now opens into two groups, Inputs and Outputs,
both collapsed until opened. Each group shows a count, and Inputs also
says how many are required. A group with nothing in it cannot be opened
and says "none".

The fields still come from one DESCRIBE METHOD EXTENDED. The groups carry
their members, so opening one makes no second request.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…s own

On Windows every child was put in one kill-on-close job. A process that
starts out in a job of its own cannot join a job that already has
members, and AssignProcessToJobObject fails with access denied. A
packaged app starts that way, and a program on PATH can be an app
execution alias for one. The GitHub Copilot CLI installed through the
Windows package manager is such an alias, and could not be started.

When the shared job will not take a child, the supervisor now creates an
empty kill-on-close job for that child alone, which the OS always allows,
and holds it for as long as the child runs. The rule is the same: the
process tree dies when the app's handle closes, whatever ends the app.
Closing the job when the child is stopped also ends anything the child
left running.

A test at the job level pins the OS rule this depends on.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Adds the first delegated agent: chat can run through the GitHub Copilot
CLI the operator already has installed and signed in to. The CLI runs the
model and is the MCP client. The host starts it under the supervisor,
drives it over the Agent Client Protocol, and shows what it does. The
host never sees or handles the CLI's sign-in.

What the host does, each point tested against Copilot CLI 1.0.113 and
recorded in docs/spike-acp.md:

- starts `copilot --acp` and speaks ACP version 1 over stdio
- names the engine's MCP server in a file passed with
  --additional-mcp-config, as `stackql`, because the CLI rejects a stdio
  server passed in session/new and then silently falls back to the
  operator's own configuration
- passes --available-tools with the engine's tool names, read from the
  engine, so the model has no shell, no file access and no other MCP
  server, and --allow-tool=stackql so the CLI does not prompt for each
  engine tool call
- passes the workspace safety mode to the engine as for other backends
- declines any session/request_permission and tells the operator
- sets the model with session/set_config_option when one is chosen, and
  can list the models with their usage multipliers without sending a
  prompt

The CLI does not relay MCP elicitation, so on this path the engine
refuses a statement that needs approval instead of asking. It fails
closed. The host puts no gate of its own in that place.

Shape of the change:

- agent/acp.rs: a small ACP client, JSON-RPC over a byte stream
- agent/delegate.rs: a session with an agent, and the mapping from its
  updates to the chat events the webview already understands
- agent/copilot.rs: the Copilot command line and how it is found
- Connection::open_delegate_channel: the connection starts the agent and
  tells it how to start the MCP server in a safety mode, so the runtime
  still never spawns a process
- new events: DelegateStarted, and AssistantDelta for text that arrives
  in pieces
- BackendKind::GithubCopilot, which has no key in the keychain

No new dependencies. The ACP client is written here because the part
needed is five methods, and every behaviour that matters was observed
against the real agent.

CLAUDE.md and README.md record the decision. They also describe the
chat-first layout, which lands in the next commit.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…lies

Chat is now the view the app opens in, in place of a side pane beside the
query IDE.

- A side menu leads to New Chat, the explorer (provider tree, editor and
  results) and activity, lists the current conversation under Chats, and
  has Settings at the bottom. It can be collapsed to icons.
- File, Edit and View menus repeat what the side menu and panes offer,
  with shortcuts: Ctrl+N new chat, Ctrl+1/2/3 for the views, Ctrl+B for
  the side menu, Ctrl+, for settings. They are drawn in the webview, so
  they are the same on both platforms and testable like the rest of the
  page.
- Sending a message with no model backend opens the model backend
  settings and keeps what was typed. Saving a backend there returns to
  the conversation. This replaces "chat is hidden until configured".
- The composer shows the backend and model, and the safety mode with
  what it means for the backend in use.
- Row results from the assistant are shown in the conversation, first
  rows only, with "Open in grid" for the full result.
- Replies are read as markdown: headings, lists, tables, emphasis, inline
  code. The reader builds a tree and never HTML, leaves snake_case names
  and SQL stars alone, and shows links without opening them.
- Text from a delegated agent appears as it is written.
- Model backend settings gain GitHub Copilot: an optional CLI location, a
  button that asks the CLI for its models, and a list that shows what a
  request to each costs against the plan.
- Every view stays mounted while another is shown, so the editor keeps
  its text and history and a running turn keeps its place.

The window close permission is added for File > Exit. Closing the window
ends the app the usual way, which stops the engine.

No new dependencies. The markdown reader is about 250 lines with tests,
which was preferred over a library for output that comes from a model.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The Inputs and Outputs groups split a method's fields on the engine's
param type. Only `output` was treated as an output, and everything else
as an input. The provider built into the engine marks what a method
returns as `response`, so those fields were listed under Inputs.

A field is now an input when its param type starts with `input`, and an
output otherwise. Found while checking the grouping in the release build
against the built-in provider.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… mode

The file that tells the Copilot CLI how to start the engine's MCP server
was written to one fixed path. Two instances of the app in different
safety modes could then overwrite it between one writing it and its CLI
reading it, and an agent could start in the other instance's mode.

The file name now includes the mode. Its content depends on nothing else
that differs between instances sharing a data folder. Found while running
two instances side by side for the force-kill check.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…e tree

The explorer no longer lists stackql_preview, the provider built into the
engine. It is hidden for now and may come back.

The name is in HIDDEN_PROVIDERS in query/explorer.rs and nowhere else, so
removing it there brings the provider back. Only the tree leaves it out.
SHOW PROVIDERS in the editor still shows what the engine says, and what
the engine tells a model is not filtered.

An engine with nothing installed now gives an empty tree with the hint
about REGISTRY PULL, where it used to show the built-in provider above
that hint.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ow to read an empty result

Decided by the maintainer: the engine's answer to a provider call that
returned nothing stays an empty, successful result on both channels. A
lookup of one thing that does not exist is an ordinary question, and "not
found" is its answer. The engine also reaches providers over more than
one protocol, so nothing may sort a provider's answer by HTTP status code.

The host and the UI had been wording this as a failure. They now pass the
provider's message on and do not rule on it:

- the results pane and the tool card say that nothing may have matched,
  or that the call may not have succeeded
- the note the host adds to a tool result for the model says the same
- looksLikeUpstreamFailure is now emptyWithNotice

For a model the fix is instructions, not an error. One text,
empty_result_guidance!, is used for both the host's loop and a delegated
agent. It says what an empty result does and does not show, to check that
the provider is answering before reporting that it has none of something
or acting on something being absent, and that an empty result is never
proof that a change happened. It names no protocol and no status code,
and a test holds it to that.

CLAUDE.md records the decision under Empty results and takes the item off
the open questions. The two spike reports keep their findings and note
that their first suggestion, an error result, was decided against.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The previous commit added guidance for a model on reading empty results,
on top of a note the host had been appending to a tool result since the
chat milestone. Both rested on a finding that was wrong: that the
engine's MCP server hides provider failures from the model.

It does not. Checked against v1.0.888 with no provider credentials:

- a call that needs a sign-in comes back as a tool error,
  upstream http error: {"http_status": 401, "retryable": false}: ...
- a list for an owner that does not exist comes back as no rows, which is
  the intended answer to a lookup that finds nothing

The engine source says the same. Its MCP backend runs statements with
strict upstream errors and classifies them, and its instructions tell a
model how to read errors and empty results. The first finding came from
testing one lookup that found nothing and taking it for every failure.

The maintainer's direction is that this belongs in the engine's MCP
server and not here. So:

- the model guidance on empty results is removed from both prompts
- the host no longer adds a note to what the model receives. The model
  gets the server's rendering and nothing else
- the stderr line with what a provider answered is still shown to the
  operator beside the tool result, as a plain message and not a warning

CLAUDE.md states where this is handled and that no logic for it goes in
this app. The spike reports carry a dated correction with the second test
case, and no longer ask the engine for something it already does.

Nothing was changed in the stackql repository.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Measured against v1.0.888 with default flags: four independent
single-request statements sent together were answered in about the time
of one, in two runs of three. The third had one late answer that was not
explained.

Recorded because it decides whether sending independent statements
together is worth doing. The host's loop does not do it yet.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…time

With an API key backend the host ran the tool calls of a model reply one
after another, even when the model asked for several independent queries
in one go. One stackql MCP server runs calls at the same time, so that
was time spent waiting for nothing.

The calls of one reply now run together when the engine marks the tool
as not destructive. The engine publishes that on every tool as
destructiveHint: its query and discovery tools say false, and
run_mutation_query and run_lifecycle_operation say true. A tool marked
destructive, or one with no hint, or one the server does not have, runs
alone and in the model's order, so what follows a change sees the change.
The host takes the engine's word for this and reads nothing into the
statement. Results go back to the model in the order it asked.

What had to change with it:

- stopping a turn now reaches every call that is waiting, not one of them
- an approval prompt is shown on the tool call that sent the statement,
  matched by statement and tool, since more than one call can be running
  and more than one prompt can be open
- what a provider answered is read from the server's stderr, which cannot
  say which call a line belongs to. When calls overlap it is shown for
  none of them

Two integration tests against the real engine cover it: three independent
calls are all under way before the first finishes and answer in order,
and a mutation between two queries waits for the first and holds up the
second.

No new dependencies.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…agents

The Copilot CLI can hand part of a task to a subagent, through its task
tool. The backend had turned that off along with everything else that is
not an engine tool. It is now allowed, as a setting that is on by default.

Tested before building, with two prompts, and recorded in
docs/spike-acp.md:

- adding task to --available-tools brings back that tool and nothing
  else. A subagent asked to run a shell command and to write a file had
  no tool for either, raised no permission request and wrote nothing
- subagents use the same MCP server as the main agent, so the same
  engine and the same safety mode
- a subagent's tool calls and messages carry its id, and the CLI will
  name the subagent in an event when asked at the handshake
- two subagents started in one step ran at the same time
- a subagent can start subagents. The CLI stops that at depth four

What the host does:

- adds task to the tool list when the setting is on
- tells the agent in the first prompt when to use subagents: independent
  lookups across providers, services or resources, never a change, and
  no more than four at once
- shows the start of a subagent with its task, not its whole prompt, and
  marks each tool call with the subagent that made it
- keeps a subagent's own message text out of the conversation, since it
  arrives whole as the result of the call that started the subagent
- stops a turn that starts more than 12 subagents, and says why

The direction on when to split work is in this app and not in the
engine's instructions, because starting agents is the client's
capability.

Not measured: what subagents cost. The CLI picks their model, gpt-6-luna
when tested, and will not write usage in ACP mode.

No new dependencies.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…work

A real turn through the app showed the first version was not enough. Left
to choose, the model started subagents of the explore kind in background
mode. That kind has none of the engine's tools, and a background subagent
has to be read back with a tool the agent does not have under this tool
list. The subagents did nothing, the main agent did the lookups itself,
and the answer was right for the wrong reason.

The CLI has three kinds of subagent. Each was asked to run a shell
command, write a file and call an engine tool:

  general-purpose  no shell, no file write, engine tools, session's model
  task             no shell, no file write, engine tools, gpt-6-luna
  explore          no shell, no file write, no engine tools, gpt-6-luna

So the restriction to the engine holds for every kind, and two of them
are of use. The guidance on subagents now ends with advice from the
agent's profile: general-purpose, sync mode, started in one step so they
run together, and not the explore kind or background mode. The advice is
in the Copilot profile because it is about the Copilot CLI's task tool.

docs/spike-acp.md has the table and what happened in the turn that
showed the problem.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ests

A second real turn through the app showed that allowing subagents is safe
and not yet dependable.

Asked a question that spans two providers, with no mention of subagents,
the model did the two lookups itself and got a large result. The CLI
keeps a large tool result in a temporary file for the model to read, and
the model has no tool that reads files here. It then started a subagent
to count the result. That one could not read the file either and started
another, four deep, twice. Ten subagents ran, the turn took 108 seconds
and the count was wrong. The same question had earlier been answered
correctly in 27 seconds.

So what the model used subagents for was not the dividing of independent
work. It was a way out when stuck, and a stuck model costs more with the
task tool to hand than without it. That was claude-haiku-4.5. A larger
model was not tried.

Changes:

- subagents are off unless the operator turns them on, and the setting
  is marked experimental and says why
- a turn is stopped at the first subagent that starts a subagent of its
  own, with a notice. In every run where that happened, the subagent had
  been unable to do its job
- the cap of 12 subagents in a turn stays

docs/spike-acp.md records the turn. CLAUDE.md says not to turn subagents
on by default without testing this again.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
jeffreyaven and others added 26 commits November 18, 2026 20:15
The wordmark in the side menu was 13 px tall and easy to miss. It is
20 px tall now, 131 px wide, and its row is a little taller to hold it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A second job builds the app for macOS and keeps the disk image as the
workflow artifact stackql-workbench-macos-universal, so the app can be
tried on a Mac before there is any packaging.

- The build is universal, for Apple Silicon and Intel, so it does not
  matter which Mac the tester has.
- The signature is ad hoc, set with APPLE_SIGNING_IDENTITY for that step
  only. An Apple Silicon Mac runs no code without a signature. Nothing is
  notarised, and tauri.conf.json is unchanged, so this decides nothing
  about the signing identities.
- The job does not wait for the checks. Nothing has been run on macOS, so
  a failing test should still leave a build to try.
- One step checks the bundle: both architectures are in the executable
  and the signature verifies.

No new dependency in the app. The job uses actions/upload-artifact v7,
the current major version.

The README says how to open the build. CLAUDE.md records that the host
compiles and passes clippy for aarch64-apple-darwin, checked from
Windows, and that the workflow itself has not run yet.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The first CI run built the macOS disk image and failed both check jobs,
each for a reason of the runner's.

- Windows: the checkout converted every file to CRLF and the Prettier
  check failed on all of them. A .gitattributes now sets LF for text
  files on every platform. No tracked file changes because of it.
- macOS: the setup action installs stackql with Homebrew, which has
  v0.12.824, not the v1.0.888 release the tests were written against.
  Two agent tests failed on it. The check job now installs the release
  package on macOS, after checking its SHA-256.

The README tells a tester to install the engine from the release
package for the same reason. CLAUDE.md records what the first run
showed on the macOS runner.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CI passes on both runners as of 27451dc. On the macOS runner that is
lint, the 302 webview tests, clippy and 260 host tests against stackql
v1.0.888 from the release package, and the bundle job's checks.

The two agent tests that failed against Homebrew's v0.12.824 pass on the
same runner with v1.0.888, which settles what was open in the last
commit. The app itself has still not been opened on a Mac, and the
keychain store there is still unconfirmed.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A click on a column header sorts the rows by that column: ascending,
descending, then the order they arrived in. The engine sends every value
as text, so the order is worked out from the text: numbers by size, words
without regard to case and with the digits inside them by size, and empty
values last in either direction. Rows that compare equal keep the order
they arrived in.

The grid draws the rows it is given and whoever owns the rows sorts them,
so a cell reference and an export both mean the order on screen. The
results pane now exports in that order.

The grid can also widen its columns to fill the space it is in, until the
operator drags one. The result tables in the conversation use that.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The host now writes a log of its own: one file for each run of the app,
`stackql_workbench_<UTC time>.log` in `<app data dir>/logs`, one JSON
object on each line. It is apart from the engine's audit log, which the
engine writes to its own folder. The 20 newest files are kept.

A turn's events are watched on their way to the webview. A tool call that
the engine or the agent reports as failed is written with its tool, its
statement or arguments, and what came back. So are notices, the end of
each turn and a turn that failed. The engine coming up or failing to is
logged too. Nothing is judged here: a call is logged as failed when the
other side said so.

This is the record for failed calls once the conversation stops listing
them, which the next commits do. A record never holds an API key, an
environment value or what the operator typed to the assistant.

Help > Show Log File shows the current file in the file manager. The host
holds the path, and the webview names nothing.

No new dependency. Dates are worked out from the system clock by hand, to
avoid one for a file name and a timestamp.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A model is now told what the operator sees: its answer, with the calls it
made folded away as steps and the rows of its last statements as a table,
and that a failed call is not shown, so it corrects one and carries on
without describing the attempt. It is also told how to ask for a chart:
a fenced block of the language `chart` holding one JSON object that names
a chart type and columns.

The text is in one place, `agent/guidance.rs`, and both ways a turn runs
use it. The host's loop puts it in the system prompt, ahead of the
engine's guidance, which still ends the prompt untouched. A delegated
agent has its own system prompt, so it gets the text with the first
message.

This is about presentation, which is this app's to say because drawing is
this app's capability. It says nothing about how a result is to be read.
That stays the engine's, and a test holds the text to it.

Each tool call event now carries the step of the model that asked for it,
so that calls asked for together can be shown together. The host's loop
knows each step. A delegated agent does not say where a step ends, so the
calls that follow one of its messages count as one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A chart block is one JSON object that names a chart type and columns:
bar, line, area, pie, scatter or table. `lib/chart.ts` reads it as data
and refuses what it does not understand. The rows come from the block, or
from the most recent result set that has the columns it names.

Values are read out of the text the engine sends, also `1,234` and `45%`.
For a line, an area or a scatter chart, an x column of dates or numbers
is placed where it falls, so a month with no rows leaves a gap. A chart
never has more series than there are colours: past eight, the largest are
kept and the rest are added together. What was left out is said in a note
with the chart.

`lib/chartLayout.ts` turns a model and a width into positions and paths:
round axis values, bars at most 24 pixels thick with the free end rounded
and a gap between neighbours, lines, areas, points and a ring.

The eight series colours are tokens, with a second set for the dark
theme. The first is a step of Classic Blue. The set was checked as a
whole in each theme for separation under colour-blindness, and a test
holds each colour to a floor against the surface.

No charting dependency: these are pure functions, and the components that
draw from them come next.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The conversation listed every tool call as a card, failed ones in red
with the engine's error text. A turn that took a few attempts read as a
page of errors with the answer at the bottom.

A turn is now shown as its answer. What the assistant did on the way is
one list of steps above it: each call with its SQL and result, and what
the assistant wrote before going on to another call. The list is open
while the turn runs and folds away when it ends.

A call that failed is not listed and its error text is drawn nowhere. The
model still gets the error exactly as the engine sent it, and the host
writes it to the app's log. Two things stay visible: a call the operator
was asked to approve, with its outcome, and a turn that failed as a
whole.

The result sets of the statements the assistant ran last are shown under
the steps as tables. A table holds every row the host sent, sorts by a
click on a column and saves as CSV through the save dialog.

A chart block in a reply is drawn: bars, lines, areas, points or a ring,
as SVG from this repository's own components, with a tooltip that reads
every series at the position under the pointer and the table of the same
rows one click away. A block that cannot be drawn is shown as the text it
is, with the reason. Nothing a model writes becomes markup.

The layout is worked out by pure functions in `lib/conversation.ts`.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`docs/charts.md` describes the chart block, where its rows come from, the
limits, the mark rules and the colours, how a turn is laid out, and what
the app's log holds.

`CLAUDE.md` and `README.md` are brought up to date: the status, what was
run and what was not, the stack table, the layout, where the log is, how
to build a copy that shares nothing with an installed one, and the UI
notes for the conversation.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The host already added up input and output tokens over the calls of a
turn. Two things made the numbers less than honest once they are shown.

A provider that caches the prompt reads much of the input from its cache,
and the count did not say so. Every backend now also reports the part of
the input that was read from the cache: Anthropic's
`cache_read_input_tokens`, Gemini's `cachedContentTokenCount`,
`prompt_tokens_details.cached_tokens` from an OpenAI-compatible server,
and the Copilot CLI's `cachedReadTokens`.

Gemini counts the model's thinking apart from its reply and bills it as
output. It was left out of the output count. It is now added, as is the
tool-use prompt count on the input side. The API's own total is the sum
of those parts.

A count a provider does not send stays unknown and is not turned into
zero. The end of a turn is written to the app's log with its counts.

What the Copilot CLI sends was observed with one prompt to a probe: the
answer to `session/prompt` carries `usage` for the whole turn. The test
for the delegated agent now uses that shape.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
When a turn ends, the line that heads its steps says what it used:
`6 steps  25,469 tokens in (12,631 cached), 158 out`. A turn with no
steps says it on a line of its own in the same place, above the answer.
It is small and to the side, because it is not part of the answer.

The counts are the provider's own, added up over every call to the model
in the turn. Nothing is estimated: a count that was not reported is left
out, and a provider that reports none leaves the line out. Hovering the
line says what the numbers are, and that each call to the model sends the
conversation so far again.

The host has sent these counts to the webview all along. The webview
dropped them.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`docs/spike-acp.md` gains what was observed on 19 November against the
Copilot CLI 1.0.114: the answer to a prompt carries the turn's token
counts, cached tokens are in the input count, and `usage_update` says how
full the context window is, which is a different number.

`docs/charts.md` says what the counts mean and where each backend's come
from. `CLAUDE.md` and `README.md` say where they are shown, what was run,
and that with Copilot the count is the size of a turn and not its cost.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The installers ship `stackql` with the Workbench, and that pair is the one
built and tested together. The app now takes it as the default. The one
thing that comes before it is a path the operator sets in Settings, which
can only be done after the install.

`STACKQL_BIN` used to come before the engine beside the app. It now comes
after. A variable can be older than the install, and it would swap the
engine without anyone having chosen that, or stop a fresh install from
starting if it pointed nowhere. When the variable is set and passed over,
the status says so and points at Settings. It is still strict when it is
the source: with no installed engine, a variable that points nowhere is an
error and not a reason to look further.

What "installed with the app" means follows how each installer lays the
pair out.

- Windows: `stackql.exe` in the folder of the Workbench executable, where
  the MSI puts it.
- macOS: for an app that runs from a bundle, an engine inside the bundle
  beside the executable, and failing that `/usr/local/bin/stackql`, where
  the PKG puts the command. The PKG puts none inside the bundle today.

A build from this repository has no engine beside it and, on macOS, is not
in a bundle, so there the variable is still the next thing tried.

On Windows this was run with a build of the app and a copy of the engine
in one folder: nothing set, the variable naming another engine, the
variable pointing nowhere, a path in settings, both, and a path in
settings that points nowhere. The macOS rule has unit tests only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`CLAUDE.md` gets the new order of the search, the decision behind it and
what "installed with the app" means on each platform, with what was run.
`README.md` says the same for whoever builds the MSI and the PKG: there
is nothing for an installer to configure, and under `Program Files` the
provider cache goes to the app data directory.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CI kept one thing to download, a Mac disk image for trying the app. The
StackQL installers need two others, and neither was there.

- `stackql-workbench-windows-x64`: the optimised Windows executable, from
  a new job. Until now CI only made a debug build on Windows and kept
  nothing. The job checks that the executable needs no library beside it
  in the installer's folder.
- `stackql-workbench-macos-universal-app`: the Mac app bundle on its own,
  packed with tar so that the links and permissions inside it survive.

Each comes with its SHA-256. Neither is signed for release: the StackQL
release signs what it ships. The Mac app keeps the ad hoc signature it
needs to run at all.

These are workflow artifacts, which expire. How a build that ships is
tagged and released is still to be decided, and the notes say so.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The executable ships on its own, beside stackql.exe, and has to need
nothing from the system that could be missing. It was leaving the
Universal C runtime to Windows: Tauri's default links the Visual C++
runtime in and not that one. Its import tables listed seven
api-ms-win-crt libraries.

The build now passes +crt-static on Windows, and Tauri's own handling is
switched off in tauri.conf.json, because it would undo the flag for the
Universal C runtime. The executable then asks the system for 19
libraries, all of them Windows itself.

`scripts/check-exe-imports.js` reads the import tables of an executable
and fails on a runtime library. CI runs it on the optimised build, in
place of a search of the file for a few names. CI also checks with otool
that the Mac app links only to what is part of macOS.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The window is drawn by the WebView2 runtime, which the executable cannot
carry: it is a browser engine. Windows 11 has it built in and Windows 10
gets it with Edge, but it is still the system's to supply.

An installer that must rely on nothing from the system can now ship it.
When a `WebView2Runtime` folder with a runtime in it sits beside the
executable, the app uses that one and does not look at what the system
has. Otherwise it uses the system's, as before. The folder being there is
the whole switch, so one executable serves both kinds of install. A
folder with no runtime in it is ignored. Which runtime was used goes in
the log.

Run on Windows 11 with a copy of the installed runtime as the folder: the
renderer process ran from the folder beside the app, and from the
system's when the folder was absent or empty. Microsoft's Fixed Version
package was not downloaded.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The host chooses a free port and then gives it to the engine. Something
else can take the port in between, and the engine then exits at once with
exit code 0. That was reported as a failed start. It happened in CI,
where tests start engines side by side, as "The engine exited while
starting (exit code 0)".

The engine is now started again on a fresh port, up to three times,
before the start is called a failure. An engine that is running and does
not answer is not started again: another port would not make it answer.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`README.md` says what each binary asks the system for, how CI checks it,
and how an installer ships the WebView2 runtime beside the app when it
must rely on nothing the system has, with what that costs. `CLAUDE.md`
records the two build settings that go together, the renderer folder, the
retry on a fresh port, what was run, and the decision that is still open:
whether the MSI ships the runtime.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The maintainer said on 20 November 2026 that the binaries are to stay
small and run on most modern Windows and Mac machines. So the WebView2
runtime is not shipped, and the app uses the one Windows has.

`README.md` says what Microsoft states about where that runtime is, what
the app shows where it is missing, and how an MSI can check for it and
install it. `CLAUDE.md` records the decision, what was run, and two
questions that are now open: whether the MSI installs a missing runtime,
and the oldest macOS the app supports.

What was run: the optimised build, with the loader pointed at an empty
folder, showed Tauri's own dialog and exited when it was closed.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The maintainer decided on 20 November 2026 that the oldest macOS the app
supports is 13. `bundle.macOS.minimumSystemVersion` is `13.0`, so the
bundle declares it and an older macOS refuses to open the app. Until now
the bundle declared Tauri's default of 10.13. The pages need the WebKit
of Safari 16.4, and on a Mac the renderer is the one macOS has, so an
older macOS would have opened the app and drawn it wrongly.

CI checks that the bundle declares the version in `tauri.conf.json` and
that both architectures of the executable are built for it.

Also recorded, decided the same day: where the WebView2 runtime is
missing, the MSI gives the operator the option to install it. That work
is in the installer's repository. `README.md` has what it needs, with
the address of Microsoft's bootstrapper as it answered today.

A new open question: the StackQL MSI is built for x64 and arm64, and
this repository builds the Windows executable for x64 only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The StackQL MSI is built for x64 and for arm64, and this repository built
the Windows executable for x64 only. The maintainer said on 20 November
2026 to build a native arm64 executable if emulation would not do. It
would not: Windows emulates x64 only from Windows 11, there is no Arm
machine here to try it on, and the arm64 MSI ships an engine built for
Arm.

- The checks run on GitHub's `windows-11-arm` runner as well, against the
  engine from `stackql_windows_arm64.zip` of the release, checked against
  its SHA-256.
- The optimised build is made once for each processor, on a runner of
  that processor, and kept as `stackql-workbench-windows-x64` and
  `stackql-workbench-windows-arm64`.
- `scripts/check-exe-imports.js` says which processor an executable is
  built for and, with one named, fails on another. A build on the wrong
  toolchain would otherwise pass for the right one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The first run on GitHub's `windows-11-arm` runner passed: lint, the
webview tests, clippy and the host tests against the engine from the
release's arm64 archive, and the optimised build, which names arm64 as
its processor and asks the system for the same 19 libraries as the x64
one. The app has not been opened on an Arm machine, and the x64
executable was not tried under emulation.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@jeffreyaven
jeffreyaven marked this pull request as ready for review November 20, 2026 05:20
@jeffreyaven
jeffreyaven merged commit 8f5fd56 into main Nov 20, 2026
7 checks passed
@jeffreyaven
jeffreyaven deleted the m3-chat branch November 20, 2026 06:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant