adaptiqai 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# adaptiqai
 
-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.
+One command that connects the AI app you use to [AdaptiqAI](https://adaptiqai.com),
+for a person at a terminal and for an agent running it unattended.
+
+```bash
+npx -y adaptiqai connect cline
+```
+
+It signs you in through your browser, sets the app up, sends one test request,
+and says how to start the app. You open one link, press Connect, and add a card
+or funds. Nothing else needs doing by hand, and there is no key to copy.
+
+| Command | |
+|---|---|
+| `npx -y adaptiqai connect <app>` | Sign in, set the app up, test it. Safe to run again. |
+| `npx -y adaptiqai status [app]` | Where each app stands. Uses no model. |
+| `npx -y adaptiqai disconnect <app>` | Take AdaptiqAI out of the app, and put back what it replaced. |
+
+`npx -y adaptiqai` on its own connects the one app it finds, or asks which.
+
+| App | Word | What it sets up | Start it with |
+|---|---|---|---|
+| Cline | `cline` | A provider of its own, in every Cline app on this computer | the app, or `cline` |
+| DeepSeek Harness | `deepseek` | AdaptiqAI's plugin, in its app or in the browser | the app, or `npx -y @deepseek-ai/dsh adaptiq` |
+| Codex | `codex` | A profile and a model catalog of its own, as Connect to app writes them. Plain `codex` stays as it was | `codex --profile adaptiq` |
+| Claude Code | `claude-code` | `adaptiq-claude`. Plain `claude` stays as it was | `adaptiq-claude` |
+| OpenCode | `opencode` | OpenCode's own sign-in | `opencode` |
+| Kilo Code | `kilo` | Kilo's own sign-in, which its extension reads too | `kilo`, or the extension |
+| Pi | `pi` | AdaptiqAI's package for Pi | `pi --provider adaptiqai --model <id>` |
+| Hermes Agent | `hermes` | AdaptiqAI's plugin, and a custom endpoint of its own | `hermes`, or the app |
+| OpenClaw | `openclaw` | AdaptiqAI's plugin, and the default model | `openclaw dashboard` |
+
+## For agents
+
+Without a terminal, the command is in agent mode by itself. It prints one JSON
+object per line, asks nothing, waits for nobody, and never starts or stops an
+app. In a terminal of your own, pass `--json --no-wait`.
+
+```bash
+npx -y adaptiqai connect cline --json --no-wait
+```
+
+Run it, read the last line, and do what it says. The same command goes on from
+wherever the last run ended, so a time limit on your tool cannot lose a sign-in.
+
+| Exit | Last event | What to do |
+|---|---|---|
+| 3 | `waiting` | Give the person `url` from the `sign_in` event (`say` has the words). Run the command again, with `--wait 90` to wait within your tool's limit. |
+| 4 | `insufficient_balance` | Give the person `add_funds_url`. An empty balance is a state, not a failure: run the command again once they have added a card or funds. |
+| 0 | `connected` | Tell the person how to start the app: `start`, and any `notes`. |
+| 1 | `error` | `code` and `message` say why. `app_not_installed` also has `install`. |
+| 2 | `error` or `choose_app` | Not understood. `choose_app` lists the apps found: say which. |
+
+The person presses Connect and adds funds in their own browser. Nobody else can.
+
+| Option | |
+|---|---|
+| `--model <id>` | The model to start on. By default the first running one, or the one the app has. |
+| `--no-wait` | Do not wait for the browser or for funds. On by itself without a terminal. |
+| `--wait <seconds>` | Wait this long for each. At a terminal, it waits ten minutes. |
+| `--no-open` | Do not open the link in a browser. |
+| `--json` | One JSON object per line. On by itself without a terminal. |
+
+`ADAPTIQAI_API_BASE` and `ADAPTIQAI_CONSOLE_URL` point the command at another
+AdaptiqAI, as they do for the plugins. Both must be https (plain http only to
+localhost), and the sign-in names that address, so a person sees where they
+sign in.
+
+## What it does to your computer
+
+- **A key is never printed, and never goes on a command line.** It reaches an
+  app in that app's own file, or on its stdin or in its environment for that
+  one command. All output goes through one place that takes keys out, and all
+  commands through one place that refuses a key among their arguments.
+- **The key lives in one place per app:** the app's own settings, or for Codex
+  and Claude Code a file of their own under `~/.config/adaptiq`. A file that
+  holds a key is readable by you alone. This command keeps no key itself. While
+  a sign-in waits it keeps the device code, readable by you alone, until the
+  app is set up; it is useless after ten minutes.
+- **An app's settings are merged, not replaced.** Other providers stay. A file
+  that cannot be read stops the run before anything is written.
+- **What changes is copied first,** to `~/.config/adaptiq/cli/backups`, without
+  any AdaptiqAI key: a copy left with one would outlive `disconnect`.
+- **A second run is safe.** A file that would not change is not touched, and an
+  app whose key still works is not signed in again.
+- **Nothing that runs is stopped without asking.** An agent gets a note to pass
+  on instead: it may be running inside that very app.
+- **The test request is ephemeral.** It makes no conversation, and costs next
+  to nothing.
+- **Compaction** goes off for every model in Cline, Pi, OpenClaw, OpenCode and
+  Kilo, which have no switch for one provider. `disconnect` puts it back. Codex
+  has no switch at all, so it compacts only once the 5M window is full.
+
+`disconnect` takes the key out of the app. The connection stays listed in the
+console until it is disconnected there, because a key can only be revoked from a
+signed-in browser. Unused, it ends by itself after 90 days.
+
+An app with a sign-in of its own (OpenCode, Kilo) keeps its key itself. This
+command runs the sign-in, so an agent's run can end while the person is in the
+browser, and hands the app the approved code.
+
+## Windows
+
+The command itself, Cline, Codex, Claude Code and Pi are written for Windows,
+and paths, shims and the key file have tests, but it has not been run on Windows
+yet. Windows has no `chmod`: a file is as private as your user folder. OpenCode
+and Kilo sign in through `sh`, which Git for Windows brings.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter adaptiqai run build
+pnpm --filter adaptiqai run test
+```
+
+`scripts/gateway_smoke.py` takes every app here through the whole way, as an
+agent does, in a throwaway home against the real gateway of a checkout of the
+knowledge app, under token billing, with a stand-in engine:
+
+```bash
+KNOWLEDGE_APP=<checkout> uv run --directory "$KNOWLEDGE_APP" python \
+  packages/cli/scripts/gateway_smoke.py [apps]
+```