@microboxlabs/miot-chat 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 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 the 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 the 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 any 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
+
+   Copyright 2026 Microbox Labs
+
+   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

@@ -0,0 +1,200 @@
+# @microboxlabs/miot-chat
+
+A Copilot-style agentic chat CLI for the `miot-harness` SSE streaming API. Lives at `turbo-repo/packages/miot-chat`.
+
+> Also reachable as `miot chat` from [`@microboxlabs/miot-cli`](../miot-cli) — the standalone bin and the `miot` subcommand share the same `runMiotChat()` library entry, so flag names, env vars, config files, and behavior are identical between the two.
+
+## Install
+
+```bash
+npm install -g @microboxlabs/miot-chat
+miot-chat --help
+
+# or run without installing
+npx @microboxlabs/miot-chat --help
+```
+
+If you already have `@microboxlabs/miot-cli` installed, `miot chat` works without a second install — the standalone bin and the `miot` subcommand share the same library entry.
+
+Inside the monorepo it's available as a workspace package. To use the built binary directly:
+
+```bash
+cd turbo-repo/packages/miot-chat
+npm run build
+node ./dist/cli.js --help
+```
+
+## Quick start
+
+```bash
+# 1. Install
+npm install -g @microboxlabs/miot-chat
+
+# 2. Log in through the browser (platform sign-in); saves token + org to ~/.miot-chat/config.json
+miot-chat login --base-url https://<platform-host>
+
+# 3. Ask — runs route through the platform's harness proxy for your organization
+miot-chat ask "what is the ETA status for today's deliveries?"
+```
+
+`<platform-host>` is the deployment you were given access to (there are several production environments, so there is no baked-in default — `--base-url` or `MIOT_CHAT_BASE_URL` is required).
+
+## Log in
+
+`miot-chat login` opens your platform's own sign-in page in the browser. After you sign in, the CLI receives a token plus your active organization and persists them as the default profile (`platform`) in `~/.miot-chat/config.json`. Subsequent `miot-chat ask` / TUI sessions use that profile automatically and route through `{baseUrl}/api/v1/orgs/{org}/harness`.
+
+```bash
+miot-chat login --base-url https://<platform-host>
+```
+
+| Flag | Effect |
+|---|---|
+| `--login-url <url>` | Override the platform CLI login handoff endpoint (default `{baseUrl}/app/cli/auth/login`) |
+| `--token-url <url>` | Override the token endpoint (default `{baseUrl}/app/api/cli/auth/token`) |
+| `--auth-url <url>`, `--client-id <id>`, `--audience <a>`, `--scope <s>` | Direct OAuth/PKCE mode against an authorization server instead of the platform handoff |
+| `--timeout <seconds>` | Login timeout (positive integer) |
+| `--no-open` | Print the login URL instead of opening the browser |
+
+In split-origin local dev (app and API on different ports) pass the endpoints explicitly:
+
+```bash
+miot-chat login --base-url http://localhost:8180 \
+  --login-url http://localhost:3050/app/cli/auth/login \
+  --token-url http://localhost:3050/app/api/cli/auth/token
+```
+
+If you previously logged in with `miot-cli`, `miot-chat` reuses that session from `~/.miotrc.json` as a fallback (baseUrl/token/org only) whenever no token is configured via flags, env, or the chat profile.
+
+## Other commands
+
+The CLI talks to `miot-harness` over the Phase A SSE surface (`POST /runs:start` + `GET /runs/{id}/stream`) — directly via `--base-url`, or through the platform harness proxy when an org is set (`--org`, `MIOT_CHAT_ORG`, or the org saved by `login`).
+
+```bash
+# Interactive TUI (default in a real terminal)
+miot-chat
+
+# One-shot against a local harness (no login needed)
+miot-chat ask "what's in stock?" --base-url http://localhost:8000 --tenant demo-tenant --mode canned
+
+# Resume — TUI mode opens the saved-sessions picker; piped stdin re-seeds the headless REPL
+miot-chat resume
+
+# Replay a past run offline
+miot-chat runs run_abc123
+
+# Help
+miot-chat --help
+```
+
+## Interactive TUI vs headless
+
+`miot-chat` mounts an Ink-based TUI when BOTH stdin AND stdout are TTYs and the `MIOT_CHAT_NO_TUI` env var is unset. Otherwise it falls back to a line-based REPL that reuses the existing renderer — handy for piped input (`echo "ping" | miot-chat`), CI smoke runs, and golden-output tests.
+
+| Mode | When | What it gives you |
+|---|---|---|
+| **TUI** | TTY in + TTY out, no override | Multi-line editor with cursor / paste / history, persistent header bar, slash palette, modal stack (context, resume, theme, runs, approval), markdown rendering for final answers, theme support |
+| **Headless** | piped stdin OR redirected stdout OR `MIOT_CHAT_NO_TUI=1` | Line-based prompt-per-newline, the legacy ANSI renderer, one-line status updates |
+
+Force headless explicitly:
+
+```bash
+MIOT_CHAT_NO_TUI=1 miot-chat --tenant demo-tenant
+```
+
+## TUI features
+
+- **Header bar**: tenant · user · conv (short id) · mode · baseUrl · profile · pending-approvals count. Warns in yellow on `mode=agentic` + non-`mintral` tenant.
+- **Multi-line input editor** with bracketed-paste support, cursor movement (arrows, ctrl-arrow word jumps, home/end), backspace + forward-delete, kill-line, and an in-memory history ring (200 entries, file-backed at `~/.miot-chat/history`). Up/Down arrows recall history when the buffer is empty; `Alt-Enter` adds a newline; plain `Enter` submits.
+- **Live transcript** with structured per-event items: tool start/complete collapse to one line with a spinner, freshness warnings show inline, routes/agent turns/plans dim in. Completed turns flush into Ink's `<Static>` so they live in terminal scrollback.
+- **Slash-command palette**: type `/` to filter commands by substring, Tab completes the unique match, Enter dispatches.
+- **Modals**: `/context`, `/resume`, `/theme`, `/runs`, and (behind `MIOT_CHAT_APPROVALS_UI=1`) `/approve`. Esc dismisses.
+- **Themes**: `dark` (default), `light`, `high-contrast` builtins, or your own token overrides via `~/.miot-chat/config.json` (see Configuration below). `/theme` opens a picker; `/theme <name>` jumps to it.
+- **Markdown rendering** for final assistant answers — headings, bold/italic, fenced code blocks, lists, and links render as Ink components.
+
+## Slash commands
+
+All slash commands work in the TUI palette. The headless REPL supports the legacy subset (`/exit`, `/reset`, `/mode`, `/tenant`, `/save`) for backwards compatibility.
+
+| Command | Where | Effect |
+|---|---|---|
+| `/help` | both | List every registered command |
+| `/exit` (or Ctrl-D) | both | Persist the session and exit |
+| `/clear` | both | Clear the on-screen transcript (conversation id kept) |
+| `/reset` | both | Mint a fresh `conversation_id` |
+| `/mode auto\|canned\|meta\|agentic` | both | Change dispatch mode |
+| `/tenant <id>` | both | Change tenant |
+| `/user <id>` | TUI | Change user id |
+| `/save <path>` | both | Dump `{conversation_id, transcript}` as JSON |
+| `/export <path>` | TUI | Write the transcript as markdown |
+| `/context` | TUI | Open a modal with the full session metadata |
+| `/whoami` | TUI | Print `user=… tenant=… conv=…` |
+| `/theme [name]` | TUI | Pick a color theme (modal); `/theme dark` jumps directly |
+| `/resume` | TUI | Pick a saved session from `~/.miot-chat/sessions/` |
+| `/runs` | TUI | Pick a run from the current session to replay |
+| `/approve <approve\|deny\|later> <id>` | TUI | Resolve a pending approval from the keyboard |
+
+`Ctrl-C` aborts the in-flight harness run and keeps the editor alive.
+
+## Configuration
+
+`~/.miot-chat/config.json` (file mode 0600):
+
+```json
+{
+  "defaultProfile": "local",
+  "profiles": {
+    "local":   { "baseUrl": "http://localhost:8000", "token": null, "tenantId": "demo-tenant", "userId": "demo-user" },
+    "staging": { "baseUrl": "https://...",           "token": null, "tenantId": "mintral",     "userId": "ops" }
+  },
+  "theme": "dark"
+}
+```
+
+The `theme` field is optional. Valid values:
+
+- A builtin name: `"dark"`, `"light"`, or `"high-contrast"`.
+- An object: `{ "name": "dark", "tokens": { "accent": "#ff0080", "prompt": "magenta" } }`. Token keys: `accent`, `assistant`, `user`, `dim`, `warn`, `err`, `ok`, `border`, `prompt`, `spinner`. Values are anything Ink's `<Text color>` accepts (named or hex). Invalid theme names degrade to `dark` with a one-line warning rendered above the transcript.
+
+Resolution precedence: CLI flag > env (`MIOT_CHAT_*`) > profile > defaults.
+
+Env vars:
+
+| Var | Effect |
+|---|---|
+| `MIOT_CHAT_BASE_URL` | Override `baseUrl` |
+| `MIOT_CHAT_TOKEN` | Override bearer token |
+| `MIOT_CHAT_TENANT_ID` | Override tenant |
+| `MIOT_CHAT_USER_ID` | Override user |
+| `MIOT_CHAT_MODE` | Override dispatch mode |
+| `MIOT_CHAT_ORG` | Override the organization slug (routes runs through the platform harness proxy) |
+| `MIOT_CHAT_PROFILE` | Pick a profile from the config file |
+| `MIOT_CHAT_DEBUG` | `1` streams full tool inputs and truncated outputs (tenant must be allow-listed) |
+| `MIOT_CHAT_NO_TUI` | `1` forces headless mode even in a TTY |
+| `MIOT_CHAT_APPROVALS_UI` | `1` enables the `approval.requested` modal (reply transport not yet wired) |
+| `NO_COLOR` | Disable ANSI output in the headless renderer |
+
+## Conversation memory
+
+Each session mints a fresh `conversation_id` (UUIDv4) and sends it on every turn. Phase 13's `ConversationStore` on the harness rehydrates prior turns server-side, so the CLI carries no per-turn state.
+
+- The **TUI** auto-persists each committed turn to `~/.miot-chat/sessions/<conv-id>.json` (mode 0600, atomic write). `/resume` lists the newest 10 and re-seeds the reducer via `LOAD_SESSION`. The 500-most-recent items are kept; older entries are summarized into a single `(elided N earlier items)` system row.
+- The **headless** REPL keeps using `~/.miot-chat/last-conversation` (single id) for the legacy `miot-chat resume` flow.
+
+## Develop
+
+```bash
+npm run build         # tsup
+npm test              # vitest
+npm run lint
+npm run check-types
+```
+
+## Design notes
+
+- Runtime deps: `commander` for arg parsing, `ink@^7` + `react@^19.2` for the TUI, `marked@^14` for the lexer used by `/export` and the assistant-turn renderer, and [`@microboxlabs/miot-harness-client`](../miot-harness-client) for the HTTP + SSE work. `readline`, `crypto.randomUUID`, `fetch`, and `ReadableStream` are native on Node ≥20.
+- HTTP + SSE live in the sibling library — this package owns the **interactive UX layer**. The same library powers the non-streaming `miot harness create` / `miot harness runs get` subcommands in [`miot-cli`](../miot-cli).
+- **Architecture (TUI):** a pure session reducer in `src/tui/session/reducer.ts` owns `meta`, `transcript`, `pendingApprovals`, and `currentRunId`. `STREAM_EVENT` delegates to `src/tui/transcript/project.ts`, which mirrors the field-precedence rules of the legacy `renderer.ts:statusFor` but produces typed `TranscriptItem`s. Components subscribe via `useSession` and render via Ink. The same projector is reused by `/export` markdown serialization and (eventually) the `/runs` replay panel.
+- **Architecture (headless):** unchanged from earlier phases — `src/repl/loop.ts` reads lines, calls `client.runs.create` + `client.runs.stream`, and pipes events through the original `(state, event) → {state, output}` renderer. Marked deprecated in the source; future work re-implements headless mode on top of `useSession`.
+- The library's SSE parser surfaces the harness `event: error` frame as a thrown `MiotHarnessApiError`. Both code paths catch and render it.
+- Terminal signal is `run.completed` / `run.failed`, not `answer.completed` (which the supervisor can emit more than once when a mode is denied and a fallback runs). The projector handles the dual-emit case by upserting the in-flight assistant item.
+- `approval.requested` events arrive from the harness, but no reply endpoint exists yet. The modal ships behind `MIOT_CHAT_APPROVALS_UI=1` and its resolve callback only records the decision locally — wiring will land when the harness exposes the reply transport.