@tetherto/mdk-ui-agent 0.0.0-stage → 0.12.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tether
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,310 @@
-# Temporary Holding Version
+# @tetherto/mdk-ui-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The operator agent chat, as a drop-in for any MDK UI shell. Talks to the agent
+app ([`@tetherto/mdk-app-agent`](../../../backend/apps/agent/README.md)) through the Gateway over SSE and renders its six-event
+contract as a conversation.
+
+## Install
+
+```tsx
+// App.tsx — mounted once, at the app root
+import { CoPilot } from '@tetherto/mdk-ui-agent'
+
+<CoPilot />
+```
+
+```tsx
+// main.tsx — alongside the devkit stylesheets
+import '@tetherto/mdk-ui-agent/styles.css'
+```
+
+That is the whole integration. The shell template ships with both lines already
+in place; delete them to remove it.
+
+The backend half is a stack concern: add [`@tetherto/mdk-app-agent`](../../../backend/apps/agent/README.md) to your
+`mdk.yaml` under `spec.apps` with `mount: /`, and point it at an MCP server for the fleet tools:
+
+```yaml
+spec:
+  apps:
+    - name: agent
+      package: "@tetherto/mdk-app-agent"
+      mount: /
+      config:
+        agent: { provider: { kind: qvac, model: qwen3-4b, baseURL: http://127.0.0.1:11500/v1 }, mcp: { url: http://127.0.0.1:3101/mcp } }
+```
+
+> [!IMPORTANT]
+> The panel calls `/agent/sessions…` at the Gateway root. The Gateway serves an app under `/apps/<name>` unless its entry sets
+> `mount`, so without `mount: /` every call answers `404`. `mdk onboard` writes `mount: /` for this app.
+
+Without the app the panel opens and reports that the agent is not configured. See
+[Running it all locally](#running-it-all-locally) for the whole chain from an
+empty machine.
+
+### Dev server
+
+The Gateway sends no CORS headers, and its stream route hijacks the reply so a
+CORS hook could not decorate it even if one existed. Proxy `/agent` to the
+Gateway, next to `/auth` and `/api`:
+
+```ts
+server: { proxy: { '/agent': gatewayUrl } }
+```
+
+In production, serve the built UI from the Gateway's `staticRootPath` so the
+calls stay same-origin.
+
+## Surface
+
+| Export             | What it is                                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `<CoPilot />`      | The docked overlay: a launcher in the corner that opens a 420×640 panel. Mount once at the app root.     |
+| `<ChatUIEntry />`  | The same conversation as a full-height page. Default export too, so it drops into a lazy route registry. |
+| `useAgentChat()`   | The one stateful hook — session, live turn, persistence. Everything below it is presentational.          |
+| `useConversations()` | Binds the conversation store to React. |
+| [`@tetherto/mdk-ui-agent/core`](./src/core/index.ts) | The headless half: contract types, SSE reader, transport, turn reducer, conversation store. No React — also reachable from the root package, since `.` re-exports everything here; the subpath just lets a consumer skip the components. |
+| [`@tetherto/mdk-ui-agent/panel`](./src/components/co-pilot-panel.tsx) | `CoPilotPanel`, for building your own launcher around the panel body. |
+
+All props are optional. Inside an `MdkProvider` the base URL and bearer token
+come from the provider's auth seam; outside one it falls back to relative URLs
+and no token — which is what a Gateway running without an identity layer serves
+anyway.
+
+Useful props: `title`, `status` (the line under the title), `toolLabels`,
+`placeholder`, `defaultOpen`, `position`, `idleTimeoutMs` /
+`approvalIdleTimeoutMs` / `firstEventIdleTimeoutMs`, which override the idle windows
+*Sockets that go quiet* describes.
+
+History is per browser, in `localStorage` — the Gateway keeps no transcripts. Two
+tabs on the same app share that key, and each merges the other's writes rather
+than overwriting them, since a lost transcript exists nowhere else.
+
+### Tool labels
+
+Tools come from whichever MCP server the agent is pointed at, so no tool name is
+hardcoded. Pass labels for the ones you know; anything else is humanized from its
+identifier (`summarize_site` → `Summarize site`).
+
+```tsx
+<CoPilot toolLabels={{ summarize_site: 'Site status', act_device: 'Send command' }} />
+```
+
+## What it handles for you
+
+The agent contract has sharp edges that are easy to miss when writing a client
+against it. These are handled here, and each is pinned by a test:
+
+- **One turn at a time.** A second message while a turn streams is a
+  `409 ERR_AGENT_TURN_ACTIVE`, and a turn *paused on an approval* still holds the
+  session busy. The composer stays disabled through both.
+- **Approvals expire.** An approval nobody answers is auto-rejected server-side
+  after `agent.approvalTimeoutMs` and the stream resumes on its own. The card
+  disappears when the turn moves on, not only when the operator clicks.
+- **Truncated streams.** The stream route hijacks the reply, so a failure after
+  the headers are sent just closes the socket — no `error` frame, no `done`. An
+  EOF with no terminal event is rendered as a failure rather than a turn that
+  never ends.
+- **Sockets that go quiet.** The Gateway sends no heartbeats, so a wedged agent or
+  a half-closed proxy looks exactly like a turn still thinking, and the panel
+  would stay busy until a reload. Silence past `STREAM_IDLE_TIMEOUT_MS` (30s) ends
+  the turn. How much silence is normal is not constant across a turn, so that
+  deadline applies *between* events only, and two phases get their own:
+  `APPROVAL_IDLE_TIMEOUT_MS` (5min) while an approval is outstanding, where
+  waiting on a human is the expected state, and `FIRST_EVENT_IDLE_TIMEOUT_MS`
+  (120s) before the first event, where the model is still routing and has emitted
+  nothing yet — a local thinking model measured 61s to its first event, so the
+  between-events limit would have abandoned a healthy turn. 120s is the
+  producer's own per-model-call budget, so the server always gives up first and
+  says why. Override all three per host with `idleTimeoutMs` /
+  `approvalIdleTimeoutMs` / `firstEventIdleTimeoutMs`.
+- **Stop.** A turn going visibly wrong is interrupted from the composer, and what
+  streamed is kept — marked as stopped early, so half an answer never reads back
+  as the whole one. A failed turn offers a retry rather than asking for the
+  question again.
+- **Unanswered tool calls.** A call the turn ended before hearing back from settles
+  as `interrupted`: the outcome is unknown, which is neither the tick nor the
+  error state, and a step left `running` would persist as a spinner that never
+  resolves.
+- **Two error body shapes.** The streaming route answers `{ statusCode, message }`
+  with no `error` key, unlike every other route.
+- **Stale sessions.** Sessions live in the Gateway's memory per process. A stored
+  id 404s after a restart; the transcript still reads back and the next message
+  mints a fresh session — and says so in the transcript, because the conversation
+  that came before it is context the agent no longer has.
+- **Leaked tool calls.** The agent's tool loop is prompt-based and classifies a
+  reply as a tool call from its first character being `{`. A model that fences its
+  JSON gets classified as prose, and the raw call reaches the operator as the
+  answer. That is detected and labelled instead of dumped.
+
+## Errors
+
+Five codes come from the Gateway route; three are synthesized locally by [`@tetherto/mdk-ui-agent/core`](./src/core/index.ts) when the
+transport itself misbehaves.
+
+| Code                          | Fires when                           | Fix                               |
+| ----------------------------- | ------------------------------------ | --------------------------------- |
+| `ERR_AGENT_UNAVAILABLE`       | `config.agent` is missing entirely, or the agent failed to construct (`503`) | An operator-facing failure — the Gateway wasn't configured or the agent couldn't start; check the app's own config |
+| `ERR_AGENT_SESSION_NOT_FOUND` | The session id doesn't exist — commonly because the Gateway restarted and its in-memory sessions were lost (`404`) | Start a new session; the transcript still reads back locally |
+| `ERR_AGENT_TURN_ACTIVE`       | A message or delete is sent to a session while its previous turn is still streaming or paused on an approval (`409`) | Wait for the current turn to finish, or decide its pending approval |
+| `ERR_AGENT_APPROVAL_NOT_FOUND` | An approval decision is sent for an id that doesn't exist for that session — already decided, or never existed (`404`) | Confirm the approval card is still the current one; a stale one is a decision arriving after the turn already moved on |
+| `ERR_AGENT_MESSAGE_TEXT_REQUIRED` | The message `text` sent to the Gateway is missing, not a string, or empty after trimming (`400`) | Don't send an empty message |
+| `ERR_AGENT_STREAM_IDLE`      | No event arrived within the idle window for the current phase (`STREAM_IDLE_TIMEOUT_MS` mid-turn, `FIRST_EVENT_IDLE_TIMEOUT_MS` before the first event, `APPROVAL_IDLE_TIMEOUT_MS` while an approval is outstanding) | Usually a wedged agent or a half-closed proxy; retry the turn |
+| `ERR_AGENT_STREAM_TRUNCATED` | The stream ended with no terminal event and no idle timeout fired — the socket closed on its own (a failure after the SSE headers were already sent, which arrives with no `error` frame and no `done`) | Retry the turn; what already streamed is kept |
+| `ERR_AGENT_STREAM_EMPTY`     | The Gateway answered the message request without a readable stream body at all | An environment gap (a `fetch` polyfill without streaming body support) rather than an agent failure; check the runtime |
+
+## Rendering
+
+Answers render as GitHub-flavoured Markdown once the turn finishes, and as plain
+text while it streams — a half-written fence breaks the parser and re-parsing on
+every token is wasted work. Raw HTML is deliberately not enabled, so untrusted
+model output cannot inject markup. Do not add `rehype-raw`.
+
+Everything `remark-gfm` can emit is styled — headings, quotes, rules, images,
+task lists, footnotes — because nothing constrains what the model answers with. A
+link out of the document opens in a new tab rather than navigating the host app
+away mid-conversation; an in-document fragment link (a footnote) stays in the
+panel. An answer wrapped entirely in a ```markdown fence, a common model quirk, is
+unwrapped rather than rendered as one code block. An answer long enough to bury
+the transcript collapses behind a toggle once the turn settles.
+
+Fenced code is highlighted for `json`, `bash` and `yaml`, coloured from the same
+`--mdk-agent-*` tokens as the rest of the panel rather than from a highlight.js
+theme. The grammar set is deliberately small: `rehype-highlight` would pull in
+lowlight's 37-grammar `common` set, which measured 179 kB raw / 55 kB gzip against
+the generated shell. Blocks carry a copy button where the Clipboard API is
+available — it needs a secure context, and a Gateway on a site LAN is served over
+plain http.
+
+The panel is code-split behind the launcher, so a collapsed co-pilot costs the
+host about 13 kB raw / 4.5 kB gzip; the transcript and its renderer arrive on
+open. Nothing may import [`components/co-pilot-panel`](./src/components/co-pilot-panel.tsx)
+statically from the root barrel — one static edge collapses the split for every consumer.
+
+## Naming
+
+`Co-pilot` is a placeholder pending a naming decision. Every user-visible string
+derives from `AGENT_NAME` in [`src/branding.ts`](./src/branding.ts), so the rename is a one-line
+change there; [`src/branding.test.ts`](./src/branding.test.ts) fails if a component hardcodes it.
+The CSS prefix (`mdk-agent-*`) and the storage key deliberately do not carry the name, so
+renaming breaks neither consumers' style overrides nor their stored history.
+
+Per deployment, pass `title` instead of editing the constant.
+
+## Styling
+
+SCSS compiled into `@layer mdk`, BEM `mdk-agent-*` classes over `--mdk-color-*`
+tokens. Every value indirects through a `--mdk-agent-*` variable, so the panel can
+be rethemed without forking the stylesheet:
+
+```css
+:root { --mdk-agent-accent: #22afff; --mdk-agent-panel-width: 480px; }
+```
+
+Components do not import their own `.scss` — every partial is reached from
+[`src/styles.scss`](./src/styles.scss), and `npm run check:styles` fails the build if one is not.
+
+## Demo
+
+[`ui/apps/catalog`](../../apps/catalog/README.md) → **Guides → Agent Co-pilot** drives all five states against a
+stand-in gateway, so it runs with no backend.
+
+## Running it all locally
+
+Four processes, in order. See the [operator agent guides](../../../docs/guides/agent/index.md) for the topology diagram and
+why order matters here: the agent connects to MCP once, when a session is created, so a panel opened before the tool
+server is up gets a session with no tools and answers from the model alone, with no error to tell you.
+
+### 1. A model
+
+Anything that speaks the OpenAI `/v1/chat/completions` API. QVAC is the
+supported path — see
+[serving the model](../../../docs/guides/agent/run-standalone.md#serve-the-model-with-qvac).
+Any other local server works too: the provider is pointed at a URL, not at a
+vendor.
+
+A 4B is the floor. The tool loop asks the model for JSON on demand, and below
+that size it does not reliably produce it.
+
+### 2. The fleet and its tools
+
+```bash
+cd examples/mvp-site
+npm run setup         # first time — NOT npm install
+npm run setup:config  # first time — writes config/devices.json and config/site.deploy.json
+npm start             # kernel + workers + its own gateway :3000 + MCP tools on :3101, under PM2
+```
+
+`npm install` alone leaves it unbootable. The repo is a root npm workspace, but
+`setup` also builds the UI toolkit ([`ui/`](../../README.md)) and installs [`examples/mvp-site/ui`](../../../examples/mvp-site/ui/package.json)
+— a plain root `npm install` does not do either of those; `setup` does all of
+that and takes a while.
+
+This is the same MCP server the agent CLI uses, exposing `summarize_site`,
+`count_devices`, `list_devices`, `get_device`, `rank_devices` and `act_device`.
+
+**Its gateway is not the agent gateway.** `mvp-site` serves a UI of its own on
+`:3000` and carries no agent app; step 3 is a separate stack that reaches
+across to the tool server on `:3101`. Nothing in the repo boots both halves
+together yet.
+
+### 3. A gateway carrying the agent app
+
+Mount [`@tetherto/mdk-app-agent`](../../../backend/apps/agent/README.md) at `/` behind its own Gateway, against the local model
+and MCP server this walkthrough already served. [Mounting the app](../../../docs/guides/agent/gateway-deployment.md#mount-the-app)
+shows the complete `mdk.yaml` and `mdk run`.
+
+### 4. The UI
+
+```bash
+cd <your-app>            # or examples/mdk-ui-shell-template
+npm install               # first time only; this project isn't a root workspace member
+VITE_GATEWAY_URL=http://127.0.0.1:3847 VITE_AUTH_BYPASS=true npm run dev
+```
+
+The `npm install` above only needs to cover this project's own dependencies. The `ui/` toolkit it imports via `file:` links
+(`react-devkit`, `ui-foundation`, `react-adapter`, this package) is already built by step 2's `npm run setup`, which chains
+`npm --prefix ../.. run build:ui` — no separate build step here.
+
+`<your-app>` can be [`examples/mdk-ui-shell-template`](../../../examples/mdk-ui-shell-template/README.md). Open `:3030` and the launcher is in the corner. `VITE_GATEWAY_URL` feeds the
+`/agent` proxy from [Dev server](#dev-server); leave `VITE_MDK_API_URL` empty so
+calls stay relative and go through it. `VITE_AUTH_BYPASS=true` skips the shell template's `/signin` gate, landing straight on
+the dashboard with a stub session, since this walkthrough has no OAuth backend to sign in against.
+
+### Checking it
+
+```text
+hey                  → a greeting, and no tool chip
+list the devices     → a chip, then the devices, one per line
+reboot <device-id>   → an approval card; nothing runs until you accept
+```
+
+A tool chip on the fleet questions is the thing to look for. If they answer
+without one, MCP was not up when the session was created — reload the page to
+mint a new one.
+
+Against `mvp-site` with the example `config/devices.json`, the fleet is 8 miners (5 Whatsminer, 3 Antminer), plus a
+powermeter and a pool, so "how many miners are there?" answers 8.
+
+Without the UI:
+
+```bash
+SESSION=$(curl -sX POST localhost:3847/agent/sessions -H 'content-type: application/json' -d '{}' | jq -r .sessionId)
+curl -N -X POST localhost:3847/agent/sessions/$SESSION/messages \
+  -H 'content-type: application/json' -d '{"text":"how many miners are there?"}'
+```
+
+### Rough edges worth knowing
+
+- **Sessions live in the gateway process.** Restart it and every stored session
+  404s; the panel notices and mints a fresh one on the next message, so the
+  transcript on screen outlives the conversation the model remembers.
+- **One turn at a time.** A second message while one streams is a `409`, and a
+  paused approval still counts as busy — which is why the composer stays
+  disabled while a card is up.
+- **Writes need approval**, and an unanswered card auto-rejects after
+  `approvalTimeoutMs` (120s by default). The stream then resumes on its own.
+- **No CORS, ever.** The stream route hijacks the reply, so the dev proxy in
+  step 4 is not optional if the UI is on another port.
+
+Walked end to end on 2026-08-14; the four steps above are what it took.

package/dist/branding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The product name, in one place.
+ *
+ * "Co-pilot" is a placeholder — it collides with GitHub Copilot and the final
+ * name has not been decided. Every user-visible string in the package derives
+ * from `AGENT_NAME` below, so renaming it is a one-line change here.
+ *
+ * Deliberately kept out of the identifiers: the package is `@tetherto/mdk-ui-agent`,
+ * the CSS classes are `mdk-agent-*`, and the storage key is `mdk-ui-agent:*`.
+ * None of those need to move when the name does. The exported component names
+ * (`CoPilot`, `CoPilotProps`, …) are the only remaining mention, and they are a
+ * mechanical rename plus a deprecated alias whenever the decision lands.
+ *
+ * Hosts that want a different name per deployment do not need to fork this:
+ * pass `title` to `CoPilot` / `ChatUIEntry`.
+ */
+export declare const AGENT_NAME = "Co-pilot";
+/** How the operator's own turns are labelled. */
+export declare const OPERATOR_NAME = "Operator";
+/**
+ * Accessible names and headings, derived so they stay consistent with
+ * {@link AGENT_NAME}.
+ */
+export declare const AGENT_LABELS: {
+    readonly name: "Co-pilot";
+    readonly operator: "Operator";
+    readonly open: `Open ${string}`;
+    readonly close: `Close ${string}`;
+    readonly composer: `Message the ${string}`;
+    readonly conversations: 'Conversations';
+    readonly newConversation: 'New conversation';
+    readonly backToConversation: 'Back to conversation';
+    readonly approvalRequired: 'Approval required';
+    readonly placeholder: 'Ask about your fleet...';
+};
+//# sourceMappingURL=branding.d.ts.map

package/dist/branding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branding.d.ts","sourceRoot":"","sources":["../src/branding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,UAAU,aAAa,CAAA;AAEpC,iDAAiD;AACjD,eAAO,MAAM,aAAa,aAAa,CAAA;AAIvC;;;GAGG;AACH,eAAO,MAAM,YAAY;aACvB,IAAI;aACJ,QAAQ;aACR,IAAI;aACJ,KAAK;aACL,QAAQ;aACR,aAAa,EAAE,eAAe;aAC9B,eAAe,EAAE,kBAAkB;aACnC,kBAAkB,EAAE,sBAAsB;aAC1C,gBAAgB,EAAE,mBAAmB;aACrC,WAAW,EAAE,yBAAyB;CAC9B,CAAA"}

package/dist/branding.js

@@ -0,0 +1,37 @@
+/**
+ * The product name, in one place.
+ *
+ * "Co-pilot" is a placeholder — it collides with GitHub Copilot and the final
+ * name has not been decided. Every user-visible string in the package derives
+ * from `AGENT_NAME` below, so renaming it is a one-line change here.
+ *
+ * Deliberately kept out of the identifiers: the package is `@tetherto/mdk-ui-agent`,
+ * the CSS classes are `mdk-agent-*`, and the storage key is `mdk-ui-agent:*`.
+ * None of those need to move when the name does. The exported component names
+ * (`CoPilot`, `CoPilotProps`, …) are the only remaining mention, and they are a
+ * mechanical rename plus a deprecated alias whenever the decision lands.
+ *
+ * Hosts that want a different name per deployment do not need to fork this:
+ * pass `title` to `CoPilot` / `ChatUIEntry`.
+ */
+export const AGENT_NAME = 'Co-pilot';
+/** How the operator's own turns are labelled. */
+export const OPERATOR_NAME = 'Operator';
+const lower = AGENT_NAME.toLowerCase();
+/**
+ * Accessible names and headings, derived so they stay consistent with
+ * {@link AGENT_NAME}.
+ */
+export const AGENT_LABELS = {
+    name: AGENT_NAME,
+    operator: OPERATOR_NAME,
+    open: `Open ${lower}`,
+    close: `Close ${lower}`,
+    composer: `Message the ${lower}`,
+    conversations: 'Conversations',
+    newConversation: 'New conversation',
+    backToConversation: 'Back to conversation',
+    approvalRequired: 'Approval required',
+    placeholder: 'Ask about your fleet...',
+};
+//# sourceMappingURL=branding.js.map

package/dist/branding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branding.js","sourceRoot":"","sources":["../src/branding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAA;AAEpC,iDAAiD;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAA;AAEvC,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,CAAA;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,QAAQ,KAAK,EAAE;IACrB,KAAK,EAAE,SAAS,KAAK,EAAE;IACvB,QAAQ,EAAE,eAAe,KAAK,EAAE;IAChC,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,kBAAkB;IACnC,kBAAkB,EAAE,sBAAsB;IAC1C,gBAAgB,EAAE,mBAAmB;IACrC,WAAW,EAAE,yBAAyB;CAC9B,CAAA"}

package/dist/components/approval-card.d.ts

@@ -0,0 +1,46 @@
+import type { JSX } from 'react';
+import type { ToolLabels } from '../core/tool-label';
+import type { PendingApproval } from '../core/turn';
+export type ApprovalRow = {
+    label: string;
+    value: string;
+};
+/**
+ * Flattens the tool args into the Action / Device / Command rows the design
+ * shows.
+ *
+ * Tools are supplied by whichever MCP server the operator points the agent at,
+ * so no argument name is guaranteed. The target is looked up across the names
+ * the reference tools use and everything else is listed as-is, which degrades to
+ * a plain key/value dump for an unknown tool rather than to nothing.
+ */
+export declare function describeApproval(approval: PendingApproval, labels?: ToolLabels): ApprovalRow[];
+/**
+ * The one-line "here is what you are about to allow", shown above the card.
+ *
+ * Synthesized rather than streamed: `pending_approval` arrives between a
+ * `tool_call` and its `tool_result`, and the model does not emit a single token
+ * until after the tool returns — so at the moment the operator is asked to
+ * decide, the agent has said nothing at all. The design shows a sentence there,
+ * and it has to be built from the call itself.
+ */
+export declare function describeApprovalIntent(approval: PendingApproval, labels?: ToolLabels): string;
+export type ApprovalCardProps = {
+    approval: PendingApproval;
+    toolLabels?: ToolLabels;
+    /** A decision has been sent; the stream has not resumed yet. */
+    pending?: boolean;
+    onDecide: (approved: boolean) => void;
+};
+/**
+ * The inline approval prompt. The stream is paused behind this.
+ *
+ * Rendered in the transcript rather than as a blocking modal, because it is not
+ * always the operator who resolves it: an approval left unanswered for
+ * `agent.approvalTimeoutMs` is auto-rejected server-side and the stream resumes
+ * on its own. The card must be able to disappear because the turn moved on — a
+ * modal that only closes on click would strand the operator on a dead prompt.
+ * Unmounting is driven by the reducer clearing `pendingApproval`.
+ */
+export declare const ApprovalCard: ({ approval, toolLabels, pending, onDecide, }: ApprovalCardProps) => JSX.Element;
+//# sourceMappingURL=approval-card.d.ts.map

package/dist/components/approval-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-card.d.ts","sourceRoot":"","sources":["../../src/components/approval-card.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAEhC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AA+BnD,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1D;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,EAAE,CAY9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAQ7F;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,eAAe,CAAA;IACzB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAA;CACtC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,iDAKtB,iBAAiB,KAAG,GAAG,CAAC,OAqC1B,CAAA"}