@adaptiqai/opencode 0.1.4 → 0.1.6

package/README.md

@@ -6,7 +6,13 @@ AdaptiqAI remembers, and your saved knowledge, in one plugin.
 
 ## Install
 
-Add the plugin to the harness's config:
+Set up from the AdaptiqAI console's **Connect to app**, the harness gets this
+plugin by itself, from the configuration that sign-in gives it. It runs on
+the console's own AdaptiqAI provider (`adaptiq/<model>`), and the plugin works
+on that provider's requests the same way it works on its own (see below). It
+adds its tools and `/adaptiq` beside it, but no second provider.
+
+To set it up by hand, add the plugin to the harness's config:
 
 | Harness | Config | Entry |
 |---|---|---|
@@ -23,86 +29,205 @@ in the app) and choose **AdaptiqAI**:
   `ADAPTIQAI_API_KEY` in the environment works too.
 
 Choose a model from the **AdaptiqAI** provider (`adaptiqai/<model>`). The list
-is the models in your workspace, each with its own output limit and
-thinking levels (OpenCode's variants).
-
-Set up from the AdaptiqAI console's **Connect to app** instead, the harness
-gets this plugin by itself, from the configuration that sign-in gives it, and
-the plugin takes that sign-in's key. The harness then runs on the console's
-own AdaptiqAI provider (`adaptiq/<model>`), and the plugin adds its tools and
-`/adaptiq` beside it, but no second provider.
+is the models in your workspace, each with its own output limit, thinking
+levels (OpenCode's variants) and price.
 
 ## What it does
 
+These hold on the plugin's own provider and on Connect to app's alike.
+
 - **A conversation is one AdaptiqAI session.** Every turn carries the
   harness's session id as `x-adaptiq-session-id`. AdaptiqAI keeps the
   conversation's memory, and the collections and conversations you attach to
-  it in the console reach the model.
+  it reach the model.
 - **The harness's own session headers are replaced.** OpenCode and Kilo put
   session headers of their own on every request, title calls too. OpenCode 2
   even puts the root conversation's id in a subagent's `X-Session-Id`. A turn
   goes out with only the plugin's header, a helper call with none.
-- **Helper calls leave nothing.** Titles, compaction and summaries run once,
-  marked ephemeral, and never become a conversation. So do Kilo's commit
-  messages and branch names, and any request the plugin cannot tell is a turn.
+- **Helper calls leave nothing.** Titles and summaries run once, marked
+  ephemeral, and never become a conversation. So do Kilo's commit messages
+  and branch names, and any request the plugin cannot tell is a turn.
+- **Private conversations stay private.** `/adaptiq private` (or the agent's
+  "continue without saving", on your word) stops saving the conversation's new
+  messages: its turns are read back and save nothing. `/adaptiq remember`
+  turns saving back on.
+- **A subagent names the conversation that started it**
+  (`X-Adaptiq-Parent-Session-Id`). One the conversation waits for is a
+  `helper`, folded under it in the console. In OpenCode 1.x and Kilo, one the
+  task tool starts in the background (an experimental option in both) is a
+  `track`, a line of work of its own, listed on its own. A fork you make is a
+  conversation of its own.
+- **Another model says where the memory is.** AdaptiqAI keeps a
+  conversation's memory on the model it ran on. Send a message on another
+  model and you are told once, per conversation and model: "This
+  conversation's memory is on Model A. Switch back: pick Model A in /models ·
+  Start fresh on Model B: /new". OpenCode 1.x and Kilo show it as a toast in
+  the terminal app, for any other model. OpenCode 2 has no notice a plugin can
+  give without a model turn, so there the model is told to say it, on
+  AdaptiqAI's models only.
 - **The harness never compacts an AdaptiqAI conversation by itself.**
   AdaptiqAI holds the conversation whole. The harness's own compaction would
   rewrite that history and make the engine compile the conversation again.
-  - The plugin leaves its models' context window unknown, which all three
-    harnesses read as "never compact automatically". Every other model keeps
-    the harness's compaction.
-  - Compacting on purpose (`/compact`) still works, once and ephemeral, but
-    an unknown window sizes it less well. OpenCode 1.x and Kilo keep no
-    recent messages word for word beside the summary, and Kilo 7.8.15 sums
-    up one message per request. OpenCode 2 sums up only as much as fits a
-    200k window, and its model list shows the window as 0.
-  - A request the gateway refuses as too large (HTTP 413) still makes the
-    harness compact.
-- **A subagent names the conversation that started it**
-  (`X-Adaptiq-Parent-Session-Id`, role `helper`), so the console folds it
-  under that conversation.
+  - In OpenCode 1.x and Kilo the plugin's models carry the card's window, so
+    the context meter shows the real share, and an input limit no
+    conversation reaches: their automatic compaction goes by that limit, not
+    by the window. OpenCode 2 compacts at 85% of the smaller of the two, so
+    its models keep the window unknown, which it reads as "never compact
+    automatically". Connect to app turns automatic compaction off in its
+    configuration.
+  - In OpenCode 1.x and Kilo, `/compact` is declined, and nothing is sent: the
+    harness shows "AdaptiqAI keeps the whole conversation in native memory, so
+    it never needs compacting. Nothing was removed." The history stays whole.
+  - OpenCode 2 lets no plugin decline a compaction, so `/compact` still runs
+    there, once and ephemeral.
+- **What AdaptiqAI answers is said in plain words.** A refusal shows the same
+  sentence as in every AdaptiqAI plugin: a busy model ("retries
+  automatically"), a conversation being prepared, an empty balance (with the
+  page to add funds), a full memory (with what to do), a sign-in to renew. The
+  harness retries exactly what that sentence says it retries, after the wait
+  AdaptiqAI asks for (Retry-After), and nothing else: a full memory is not
+  retried five times. `/adaptiq diagnostics` lists the latest ones.
+- **Notices the harness shows nowhere else** show as a toast in OpenCode 1.x
+  and Kilo's terminal app: a newer plugin is out, with the step that installs
+  it, and idle conversations were put to sleep to make room (nothing is
+  deleted).
+- **Prices.** The harness counts what a conversation costs from each model's
+  price per million tokens (read from memory and saved to memory as cache
+  reads and writes), on Connect's models too.
 - **Tools for the agent:**
-  - `adaptiq_knowledge`: what this conversation uses; search, use or stop a
-    collection.
+  - `adaptiq_knowledge`: what this conversation uses; find words, ids or names
+    in the text of its collections, with the exact lines as document:line;
+    search the library by name, use or stop a collection.
   - `adaptiq_memory`: how full the memory is; the saved collections; keep a
     conversation private.
   - `adaptiq_create_knowledge`: save material as a collection, only when you
-    ask.
+    ask, or when you say yes to the agent's offer, typed or through the
+    harness's question tool.
 
   In OpenCode 2 they are on the model's own tool list, not behind Code Mode.
-- **`/adaptiq`** asks the agent where this conversation's memory and
-  knowledge stand. OpenCode and Kilo give a plugin's command no way to answer
-  by itself, so it is a turn of the model and costs like one. That turn reads
-  the conversation and saves nothing: the question and its answer stay out of
-  the conversation's memory. Only what you type after `/adaptiq` counts as
-  your own words.
+- **A turn is told which ready collections its conversation reads**, so the
+  agent looks things up there with find. OpenCode 1.x and Kilo save the note
+  with your message, as a part you don't see, once and again when the
+  collections change (a conversation from before the harness started keeps
+  the note it has). OpenCode 2 keeps nothing a plugin adds, so each request
+  carries it in its system prompt.
+
+## The memory pill and the AdaptiqAI menu
 
-Signing out in the harness (`opencode auth logout`, or removing the
-credential in OpenCode 2) signs the plugin out too, and the plugin removes
-its own copy of the sign-in, refresh token and all:
+In the terminal app of OpenCode 1.x (from 1.18.29), Kilo and OpenCode 2, the
+plugin shows what DeepSeek Harness shows beside its message field:
+
+- **The memory pill** by the prompt: "Memory · 26.2k / 5M", "Preparing
+  memory" and "Waiting in line" while a request waits, a collection being
+  prepared, "Private", "+24.6k from memory" for a moment after a reply, and
+  a notice's button when one needs you ("Add funds to continue ›", "Sign in
+  to AdaptiqAI").
+- **A click on it**, `/adaptiq` or the command palette opens the AdaptiqAI
+  menu, with no model turn: Remember or Private, the knowledge used here
+  (one pick uses or stops a collection, or makes one available for this
+  model), an earlier conversation to read here, files added as a collection
+  (drag a file into the terminal, or type its path), Processed, Status,
+  Settings (workspace, models with their queues, memory, saving, links,
+  plugin, account) and an update with one pick.
+- **OpenCode 2** also shows, above the message field, where the
+  conversation's memory is while another model is picked, and the notices
+  it has no toast for.
+
+OpenCode 1.x and Kilo load this part from `tui.json` only, never from the
+config that names the plugin. The plugin creates the global `tui.json`
+(`~/.config/opencode/tui.json`, or `kilo`) naming itself, once, when there is
+none; it never changes one you have, and says once how to add the line
+instead: `"plugin": ["@adaptiqai/opencode"]`. OpenCode 2 loads it by itself.
+Kilo's VS Code panel has no place for it.
+
+## `/adaptiq`
+
+The same actions and words as in every AdaptiqAI plugin:
+
+```
+/adaptiq                 workspace, models and memory
+/adaptiq private         stop saving new messages of this conversation
+/adaptiq remember        save this conversation to memory again
+/adaptiq knowledge       knowledge used here, and what else you can use
+/adaptiq use <name>      use a collection or an earlier conversation here
+/adaptiq stop <name>     stop using it here (nothing is deleted)
+/adaptiq open            open this conversation in AdaptiqAI Knowledge
+/adaptiq diagnostics     a report you can send to support (no secrets)
+/adaptiq signout         forget the connection on this computer
+/adaptiq signin          how to sign in
+```
+
+The plugin answers it itself; the model takes no action.
+
+- **In the terminal app** (OpenCode 1.x, Kilo, OpenCode 2) the answer shows
+  in a dialog, with no model turn. In OpenCode 1.x and Kilo, typed with words
+  after it, `/adaptiq` is the harness's command, which always starts a turn:
+  the plugin shows the answer in the panel and stops the command, and the
+  harness logs one error line saying why.
+- **Without the panel**, OpenCode 2 shows the answer as a notice in the
+  conversation (the model reads it with your next message), and OpenCode 1.x
+  and Kilo (`run`, Kilo's VS Code panel) run a turn in which the model
+  repeats the plugin's answer. That turn reads the conversation and saves
+  nothing.
+
+**Signing in** happens in the harness: `opencode auth login` (or `kilo auth
+login`, `/connect` in the app, or Connect to app). The browser sign-in counts
+while the harness keeps its AdaptiqAI sign-in.
+
+**Signing out:** `/adaptiq signout` forgets the plugin's sign-in on this
+computer, refresh token and all, and says when the harness still has an
+AdaptiqAI key (its own, `ADAPTIQAI_API_KEY`, or Connect's); `opencode auth
+logout` (or `kilo auth logout`) removes that. Signing out in the harness signs
+the plugin out too:
 
 - OpenCode 2 tells the plugin at once.
 - `opencode auth logout` and `kilo auth logout` change only the harness's
   own file. The plugin removes its copy at the next request, or within five
   minutes while the harness runs, or when the harness next starts.
 
-The copy is removed from this computer, not revoked at AdaptiqAI: to
+The sign-in is removed from this computer, not revoked at AdaptiqAI: to
 disconnect this computer altogether, use Connected apps in the AdaptiqAI
 console.
 
+**Keys.** A harness can hold several AdaptiqAI keys: its own sign-in's key,
+the one Connect to app gave it, `ADAPTIQAI_API_KEY`. The tools try them in
+that order, `ADAPTIQAI_API_KEY` first, and a key AdaptiqAI refuses gives way to
+the next, so an old key never hides a working one.
+
 OpenCode 1.x and 2.x keep separate AdaptiqAI sign-ins, and so does the
 plugin: signing out of one leaves the other signed in.
 
+## Updates
+
+`/adaptiq` says when a newer plugin is out (the plugin reads the newest
+published version once a day), with the one step that installs it:
+
+- **In the terminal app**, "Update to …" in the AdaptiqAI menu installs it;
+  it runs from the next start. In OpenCode 1.x and Kilo that names the new
+  version in your global `opencode.json` and `tui.json`.
+- **OpenCode 1.x and Kilo** otherwise install the plugin once, into a folder
+  of their cache named by the plugin entry (Connect to app's is
+  `~/.cache/opencode/packages/@adaptiqai/opencode@>=0.1.3`, or `kilo`), and
+  never look for a newer version. Quit the harness, delete that folder and
+  start it again: it installs the newest version.
+- **OpenCode 2**: `opencode plugin update`, then restart OpenCode.
+
 ## How it fits each harness
 
 | | OpenCode 1.x and Kilo (`server()`) | OpenCode 2.x (`setup()`) |
 |---|---|---|
-| Provider and models | added to the config by the `config` hook | `provider.transform`, reloaded when the list changes |
+| Provider and models | added to the config by the `config` hook | `provider.transform`, reloaded when the list or the sign-in changes |
+| Connect to app's provider | its `fetch` set in the `config` hook; prices added to its models | the hooks act on it too; prices through `model.transform` |
 | Sign-in | `auth` methods; the plugin's own fetch signs each request | integration methods; OAuth `refresh` renews OpenCode's copy |
 | Turn or helper call | `chat.headers` marks it by agent (and Kilo's session ids) | `model.request` by request kind |
 | Session headers | replaced in the plugin's fetch | replaced in `model.request` |
 | Memory field | added in the plugin's fetch | added in `http.request` |
-| No automatic compaction | window left unknown (`limit.context: 0`) | the same |
+| What AdaptiqAI answers | read in the plugin's fetch | read in `http.response` |
+| Your words and the agent's offer | `chat.message`, and the message events | the history each request carries (`context`) |
+| `/adaptiq` | the panel's slash command; typed with words, `command.execute.before` answers in the panel and stops it; without a panel, a turn that repeats the answer | the panel's slash command with its words; without a panel, the command and a notice (`session.synthetic`) |
+| No automatic compaction | the card's window, `limit.input` of 9 billion; `/compact` declined | window left unknown |
+| Another model than the memory's | a toast, from `chat.message` | the panel's line above the message field; without one, the turn's first request tells the model (`context`) |
+| Memory pill and menu | `./tui` from `tui.json`: slot `session_prompt_right`, a keymap command, dialogs; talks over `tui.command.execute` events | `./tui` loaded with the plugin: slot `prompt.footer.status`, a keymap command, dialogs; talks over an RPC |
 | Tools | zod arguments, rebuilt from the core's JSON Schema | the core's JSON Schema, `codemode: false` |
 
 A provider that only the config knows never gets a plugin's model list in