@adaptiqai/opencode 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# AdaptiqAI for OpenCode and Kilo
 
-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.
+Your AdaptiqAI workspace in [OpenCode](https://opencode.ai) (1.x from 1.18.29,
+and 2.x) and in [Kilo](https://kilo.ai): its models, conversations that
+AdaptiqAI remembers, and your saved knowledge, in one plugin.
+
+## Install
+
+Add the plugin to the harness's config:
+
+| Harness | Config | Entry |
+|---|---|---|
+| OpenCode 1.x | `~/.config/opencode/opencode.json` | `"plugin": ["@adaptiqai/opencode"]` |
+| OpenCode 2.x | `~/.config/opencode/opencode.json` | `"plugins": ["@adaptiqai/opencode"]` |
+| Kilo | `~/.config/kilo/kilo.json` | `"plugin": ["@adaptiqai/opencode"]` |
+
+Then sign in: run `opencode auth login` (or `kilo auth login`, or `/connect`
+in the app) and choose **AdaptiqAI**:
+
+- **Sign in with your browser** opens the AdaptiqAI approval page. You sign in
+  (or create an account) and approve, and the harness picks it up by itself.
+- **AdaptiqAI API key** takes a key from the AdaptiqAI console.
+  `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).
+
+## What it does
+
+- **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.
+- **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.
+- **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.
+- **Tools for the agent:**
+  - `adaptiq_knowledge`: what this conversation uses; search, 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.
+
+  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.
+
+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:
+
+- 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
+disconnect this computer altogether, use Connected apps in the AdaptiqAI
+console.
+
+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.
+
+## 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 |
+| 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 |
+| 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
+OpenCode 1.x or Kilo, so the models go into the config. The config is read
+once as the harness starts (and again when its connect dialog reloads after a
+sign-in), so the plugin starts with the models it last listed.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `ADAPTIQAI_API_KEY` | none: the harness's own sign-in |
+| `ADAPTIQAI_API_BASE` | `https://api.adaptiqai.com` |
+| `ADAPTIQAI_CONSOLE_URL` | `https://memory.adaptiqai.com/memory` |
+
+The browser sign-in, the plugin's state and the last model list are kept in
+`adaptiqai/` in the harness's data folder (`~/.local/share/opencode` or
+`~/.local/share/kilo`, or under `XDG_DATA_HOME`), readable by you alone.
+OpenCode 2 shares OpenCode 1.x's data folder, so its copy is in
+`adaptiqai-2/` there.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @adaptiqai/opencode run build
+pnpm --filter @adaptiqai/opencode run test
+```
+
+To try it, put the package folder's absolute path in the config's `plugin`
+(or, for OpenCode 2, `plugins`) list.