@sunerpy/kiro-provider 3.7.3 → 3.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +137 -209
  2. package/dist/cli.js +150 -84
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  <div align="center">
2
2
 
3
+ <img src="./docs/site/public/kiro-provider-logo.svg" alt="" width="72" />
4
+
3
5
  # kiro-provider
4
6
 
5
- Use your AWS Kiro accounts from clients that speak OpenAI Responses or Anthropic Messages.
7
+ ### Use your AWS Kiro accounts from clients that speak OpenAI Responses or Anthropic Messages
6
8
 
7
9
  [![CI](https://github.com/sunerpy/kiro-provider/actions/workflows/ci.yml/badge.svg)](https://github.com/sunerpy/kiro-provider/actions/workflows/ci.yml)
8
10
  [![Release](https://img.shields.io/github/v/release/sunerpy/kiro-provider)](https://github.com/sunerpy/kiro-provider/releases)
@@ -10,57 +12,39 @@ Use your AWS Kiro accounts from clients that speak OpenAI Responses or Anthropic
10
12
  [![codecov](https://codecov.io/gh/sunerpy/kiro-provider/branch/main/graph/badge.svg)](https://codecov.io/gh/sunerpy/kiro-provider)
11
13
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
12
14
 
13
- [Quickstart](#quickstart) · [Clients](#use-it-with-an-agent) · [Compatibility](#compatibility-model) · [Documentation](#documentation)
15
+ [Website](https://firlab.app/kiro-provider/) · [Install](#install) · [Quick start](#quick-start) · [Clients](#use-it-with-an-agent) · [Documentation](#documentation)
14
16
 
15
17
  [**English**](./README.md) · [简体中文](./docs/readme/README.zh-CN.md)
16
18
 
17
19
  </div>
18
20
 
19
- ## What it does
20
-
21
- kiro-provider is a loopback HTTP gateway and credential owner. It signs in to
22
- Kiro, discovers the models available to each account, schedules requests across
23
- those accounts, and presents two client-facing APIs:
24
-
25
- | API | Route | Default |
26
- | ------------------------ | --------------------------------------------- | ------------------------------------------------------ |
27
- | OpenAI Responses | `POST /v1/responses` | Enabled |
28
- | Anthropic Messages | `POST /v1/messages` | Enabled |
29
- | Anthropic token estimate | `POST /v1/messages/count_tokens` | Enabled |
30
- | OpenAI Chat Completions | `POST /v1/chat/completions` | Disabled; opt in with `enable_legacy_chat_completions` |
31
- | Models and readiness | `GET /v1/models`, `GET /health`, `GET /ready` | Enabled |
32
-
33
- Responses also has local retrieve, delete, input-items, cancel, and continuation
34
- support. The gateway chooses a native KiroRuntime Responses call when it can
35
- preserve the request exactly. Otherwise it uses its stateless adapter. If
36
- neither path can preserve a requested feature, the request fails with a typed
37
- error instead of quietly losing fields.
21
+ ---
22
+
23
+ kiro-provider is a gateway you run on your own machine. It signs in to AWS Kiro, keeps the tokens of every account you
24
+ add, and serves those accounts through OpenAI Responses and Anthropic Messages, so Codex CLI, Claude Code, OpenCode,
25
+ Pi, Crush, Zuno and the official SDKs work with a base URL and a key.
26
+
27
+ ## Features
28
+
29
+ - **Two APIs, one gateway.** `POST /v1/responses` and `POST /v1/messages`, streaming and non-streaming, with tools,
30
+ images and reasoning effort. Chat Completions is available as an opt-in legacy route.
31
+ - **Direct sign-in.** Device-code login for AWS Builder ID and IAM Identity Center. kiro-provider discovers the Kiro
32
+ profile itself; Kiro CLI is not involved.
33
+ - **Many accounts, one endpoint.** Requests go to the least busy eligible account; tokens are renewed and usage is
34
+ refreshed in the background, and an exhausted account sits out until its quota resets.
35
+ - **Fails closed.** A field that cannot reach Kiro intact fails the request with a typed error that names it; nothing
36
+ is dropped quietly.
37
+ - **Conversations that survive.** Stored responses and encrypted reasoning replay let clients continue, switch model
38
+ or effort, and resume after a restart.
39
+ - **Web search, if you want it.** The hosted web search tool of both APIs, run by kiro-provider through your own
40
+ account. Off by default.
41
+ - **Verifiable releases.** Standalone binaries for Linux, macOS and Windows with `SHA256SUMS` and build attestations,
42
+ and a `self-update` that replaces the binary only after its checksum matches.
38
43
 
39
44
  ## Install
40
45
 
41
- Choose one command. The examples below use `kiro-provider`; if you run through
42
- `bunx`, substitute `bunx @sunerpy/kiro-provider`.
43
-
44
- ### Bun
45
-
46
- The npm package uses Bun APIs and does not run under Node.js or `npx`.
47
-
48
- ```bash
49
- bun add -g @sunerpy/kiro-provider
50
- kiro-provider --version
51
- ```
52
-
53
- For a one-off run:
54
-
55
- ```bash
56
- bunx @sunerpy/kiro-provider --help
57
- ```
58
-
59
- ### Standalone binary
60
-
61
- Each GitHub release contains binaries for Linux x64/arm64, macOS x64/arm64, and
62
- Windows x64. The installers verify the downloaded binary against the release's
63
- `SHA256SUMS` before placing it in `~/.local/bin` by default.
46
+ The install scripts download the release binary for your platform, verify it against the release's `SHA256SUMS`, and
47
+ place it in `~/.local/bin` (set `KIRO_PROVIDER_INSTALL_DIR` to change that).
64
48
 
65
49
  Linux or macOS:
66
50
 
@@ -74,202 +58,147 @@ Windows PowerShell:
74
58
  irm https://raw.githubusercontent.com/sunerpy/kiro-provider/main/scripts/install.ps1 | iex
75
59
  ```
76
60
 
77
- For a service install, set `KIRO_PROVIDER_VERSION` to a release version instead
78
- of following `latest`. See the [service guide](docs/SERVICE.md) for a pinned,
79
- long-lived setup.
80
-
81
- ### Check the version and upgrade
82
-
83
- `--version` prints the installed version only. Add `--check` to look up the
84
- newest GitHub release, and `--json` for machine-readable output.
85
-
86
- ```bash
87
- kiro-provider --version
88
- kiro-provider --version --check
89
- ```
90
-
91
- A standalone binary can replace itself. `self-update` downloads the release
92
- asset for this platform, verifies it against the release's `SHA256SUMS`, and
93
- only then swaps the binary in place; a digest mismatch leaves the installed
94
- copy untouched.
95
-
96
- ```bash
97
- kiro-provider self-update --check # report what would be installed
98
- kiro-provider self-update # ask, then replace
99
- kiro-provider self-update --yes # non-interactive
100
- kiro-provider self-update --tag 3.3.1 # pin a release, including a downgrade
101
- ```
102
-
103
- npm installs are upgraded with the package manager instead
104
- (`bun add -g @sunerpy/kiro-provider@latest`); `self-update` refuses them and
105
- says so. Both commands accept `--proxy <url>` and otherwise honour
106
- `KIRO_PROVIDER_PROXY_URL`, then `HTTPS_PROXY`/`HTTP_PROXY`; `--proxy ""` selects
107
- no proxy instead of falling through to those variables. Bun's `fetch` reads
108
- `HTTPS_PROXY`/`HTTP_PROXY` itself, so unset them for a fully direct connection.
109
- Replacing the binary needs write access to the install directory, not to the
110
- binary itself, so a hardened read-only install still updates. Neither command
111
- loads the gateway config, so a broken `config.json` cannot block an upgrade.
112
- Restart the service after updating a service install.
113
-
114
- ## Quickstart
115
-
116
- ### 1. Create the gateway config
117
-
118
- Only `api_keys` is required. Use a private random value; this key authenticates
119
- local clients to the gateway.
61
+ With [Bun](https://bun.sh); the npm package uses Bun's APIs and does not run under Node.js or `npx`:
120
62
 
121
63
  ```bash
122
- mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider"
123
- cat > "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json" <<'EOF_CONFIG'
124
- {
125
- "api_keys": ["sk-replace-with-a-private-random-key"]
126
- }
127
- EOF_CONFIG
128
- chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json"
64
+ bun add -g @sunerpy/kiro-provider
129
65
  ```
130
66
 
131
- On Windows the default directory is `%APPDATA%\kiro-provider`. Pass
132
- `--config <path>` to `login` and `serve` when using another file.
67
+ Set `KIRO_PROVIDER_VERSION` to pin a release, as a long-lived service should. The
68
+ [install guide](https://firlab.app/kiro-provider/guide/install) covers pinning, checking the build attestation,
69
+ building from source and uninstalling.
133
70
 
134
- ### 2. Sign in to Kiro
71
+ ## Quick start
135
72
 
136
- ```bash
137
- # AWS Builder ID / default device flow
138
- kiro-provider login
73
+ 1. Choose a key for your clients. The gateway refuses to start without one:
139
74
 
140
- # IAM Identity Center
141
- kiro-provider login \
142
- --start-url https://example.awsapps.com/start \
143
- --region us-east-1
144
- ```
75
+ ```bash
76
+ mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider"
77
+ cat > "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json" <<'EOF_CONFIG'
78
+ {
79
+ "api_keys": ["sk-replace-with-a-private-random-key"]
80
+ }
81
+ EOF_CONFIG
82
+ chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json"
83
+ ```
145
84
 
146
- Direct login discovers and persists the Kiro profile itself; it does not require
147
- Kiro CLI or any Kiro CLI state. If the identity has multiple profiles and the
148
- start URL does not select one uniquely, rerun with `--profile-arn <arn>`.
149
- The login/OIDC region and selected profile's runtime region may differ; the
150
- provider discovers across Kiro's current commercial profile control planes
151
- (`us-east-1` and `eu-central-1`) and stores both values separately.
85
+ On Windows the file is `%APPDATA%\kiro-provider\config.json`.
152
86
 
153
- If you already used `opencode-kiro-auth`, copy those accounts into the
154
- provider-owned store once:
87
+ 2. Sign in to Kiro. Add `--start-url <url> --region <region>` for IAM Identity Center, and `--profile-arn <arn>` when
88
+ the identity has several profiles:
155
89
 
156
- ```bash
157
- kiro-provider accounts import
158
- ```
90
+ ```bash
91
+ kiro-provider login
92
+ ```
159
93
 
160
- The import is not a live link. After it finishes, kiro-provider owns token and
161
- usage refresh for its copy of the accounts.
94
+ Accounts from `opencode-kiro-auth` can be copied once with `kiro-provider accounts import`.
162
95
 
163
- ### 3. Start the gateway
96
+ 3. Start the gateway and check that an account is ready:
164
97
 
165
- ```bash
166
- kiro-provider serve
167
- ```
98
+ ```bash
99
+ kiro-provider serve
100
+ ```
168
101
 
169
- The default address is `http://127.0.0.1:8787`. In another terminal, confirm
170
- both process health and authenticated readiness:
102
+ ```bash
103
+ export KIRO_GATEWAY_API_KEY='sk-replace-with-a-private-random-key'
104
+ curl -fsS http://127.0.0.1:8787/health
105
+ curl -fsS http://127.0.0.1:8787/ready -H "Authorization: Bearer $KIRO_GATEWAY_API_KEY"
106
+ ```
171
107
 
172
- ```bash
173
- export KIRO_GATEWAY_API_KEY='sk-replace-with-a-private-random-key'
174
- curl -fsS http://127.0.0.1:8787/health
175
- curl -fsS http://127.0.0.1:8787/ready \
176
- -H "Authorization: Bearer $KIRO_GATEWAY_API_KEY"
177
- ```
108
+ 4. Send a request:
178
109
 
179
- ### 4. Send a Responses request
110
+ ```ts
111
+ import OpenAI from "openai";
180
112
 
181
- ```ts
182
- import OpenAI from "openai";
113
+ const client = new OpenAI({
114
+ baseURL: "http://127.0.0.1:8787/v1",
115
+ apiKey: process.env.KIRO_GATEWAY_API_KEY,
116
+ });
183
117
 
184
- const client = new OpenAI({
185
- baseURL: "http://127.0.0.1:8787/v1",
186
- apiKey: process.env.KIRO_GATEWAY_API_KEY,
187
- });
118
+ const response = await client.responses.create({
119
+ model: "gpt-5.6-sol",
120
+ store: false,
121
+ input: "Reply with exactly: KIRO_OK",
122
+ });
188
123
 
189
- const response = await client.responses.create({
190
- model: "auto",
191
- input: "Reply with exactly: KIRO_OK",
192
- });
124
+ console.log(response.output_text);
125
+ ```
193
126
 
194
- console.log(response.output_text);
195
- ```
127
+ `store: false` sends the request through kiro-provider's own conversion, the way Codex CLI does. Without it the
128
+ request goes to Kiro's native Responses operation, which Kiro can refuse for an account with `403 access_denied`.
129
+ `GET /v1/models` lists the model names your accounts can use.
196
130
 
197
- Model IDs come from the accounts currently ready in the local pool. Query
198
- `GET /v1/models` rather than hard-coding a catalog copied from another account
199
- or region.
131
+ The [quick start](https://firlab.app/kiro-provider/guide/quick-start) on the website walks through each step, with
132
+ an Anthropic Messages request as well.
200
133
 
201
134
  ## Use it with an agent
202
135
 
203
136
  | Client | API | Guide |
204
137
  | ----------- | --------------------- | ----------------------------------------------------------------------------- |
205
- | Zuno | OpenAI Responses | [Native provider configuration and session routing](docs/ZUNO.md) |
206
- | Codex CLI | OpenAI Responses | [Isolated profile and compatibility checks](docs/CODEX.md) |
138
+ | Codex CLI | OpenAI Responses | [Isolated profile and model switching](docs/CODEX.md) |
207
139
  | Claude Code | Anthropic Messages | [Shared-state `kiroclaude` launcher and model selection](docs/CLAUDE_CODE.md) |
140
+ | OpenCode | Anthropic Messages | [A provider in `opencode.json`](docs/site/clients/opencode.md) |
141
+ | Pi | OpenAI Responses | [A provider in `models.json`, with thinking levels](docs/site/clients/pi.md) |
142
+ | Crush | Anthropic Messages | [A provider in `crush.json`](docs/site/clients/crush.md) |
143
+ | Zuno | OpenAI Responses | [Native provider configuration and session routing](docs/ZUNO.md) |
208
144
  | Other SDKs | Responses or Messages | [Protocol compatibility](docs/PROTOCOL_COMPATIBILITY.md) |
209
145
 
210
- For persistent `kirocodex` and `kiroclaude` commands with separate state, follow
211
- [the launcher examples](docs/CLIENT_LAUNCHERS.md). The repository's `kiroclaude`
212
- shares native Claude state by default and applies a process-local provider/model
213
- overlay; separate command names alone do not isolate history. The guides record the exact
214
- client versions last tested; treat them as dated evidence, not a promise about
215
- future request shapes.
146
+ For persistent `kirocodex` and `kiroclaude` commands with their own state, follow
147
+ [the launcher examples](docs/CLIENT_LAUNCHERS.md).
148
+
149
+ ## Compatibility
150
+
151
+ | Route | Default |
152
+ | ------------------------------------------------------------------- | ------------------------------------------------------ |
153
+ | `POST /v1/responses`, plus retrieve, delete, input items and cancel | Enabled |
154
+ | `POST /v1/messages`, `POST /v1/messages/count_tokens` (an estimate) | Enabled |
155
+ | `POST /v1/chat/completions` | Disabled; opt in with `enable_legacy_chat_completions` |
156
+ | `GET /v1/models`, `GET /health`, `GET /ready` | Enabled |
157
+
158
+ In the default `v3-auto` mode, a Responses request that Kiro's native Responses operation can preserve exactly goes
159
+ there; `store: false`, max effort, reasoning replay and the other stateless-only shapes use the provider's stateless
160
+ path, as do all Messages requests. Unsupported semantics, such as hosted tools other than web search, background
161
+ responses, conversation objects and arbitrary JSON Schema output, are rejected with field-level errors. This is not
162
+ a promise of full OpenAI or Anthropic parity: [protocol compatibility](docs/PROTOCOL_COMPATIBILITY.md) is the
163
+ current contract, and the [audit index](docs/audits/README.md) holds the dated probe evidence.
216
164
 
217
165
  ## Configuration
218
166
 
219
- Configuration precedence is CLI flag, environment variable, JSON file, then
220
- schema default. Unknown keys and invalid values fail at startup. Start from
221
- [`config.example.json`](config.example.json), then use the
222
- [configuration reference](docs/CONFIGURATION.md) for every field, environment
223
- variable, timeout, file location, and protocol switch.
224
-
225
- ## Compatibility model
226
-
227
- The default `protocol_projection_mode: "v3-auto"` keeps transport selection in
228
- the gateway:
229
-
230
- - ordinary Responses requests use KiroRuntime's native Responses operation;
231
- - requests that need stateless-only semantics, including `store: false`, max
232
- effort, provider reasoning replay, custom grammar, collaboration items, or the
233
- bounded local `single-string-object-v1` output profile, use the canonical
234
- stateless path;
235
- - Anthropic Messages requests are projected directly into the Kiro contract,
236
- with signed thinking replay kept opaque to the client;
237
- - unsupported semantics are rejected with field-level errors.
238
-
239
- This is not a promise of full OpenAI or Anthropic parity. The provider locally
240
- enforces only a bounded `single-string-object-v1` JSON Schema profile for
241
- one-shot text metadata requests: Responses `text.format` in compatible mode
242
- (Codex thread titles) and Anthropic Messages `output_config.format` regardless
243
- of `responses_fidelity_mode` (Claude Code session titles). Current tool
244
- declarations are preserved, but output calls are rejected with an explicit
245
- compatibility diagnostic. Arbitrary Structured Outputs, JSON mode, tool
246
- histories, continuations, and strict-fidelity Responses use remain fail-closed;
247
- this local envelope is not evidence that Kiro natively enforces JSON Schema. Hosted tools, background Responses,
248
- Responses conversation objects, remote file references, exact input-token
249
- counting, and destructive context edits are also outside the supported surface. The
250
- [compatibility guide](docs/PROTOCOL_COMPATIBILITY.md) is the current contract;
251
- the [audit index](docs/audits/README.md) contains dated probe evidence.
167
+ Configuration precedence is CLI flag, environment variable, JSON file, then schema default. Unknown keys and invalid
168
+ values fail at startup. Start from [`config.example.json`](config.example.json); the
169
+ [configuration reference](docs/CONFIGURATION.md) lists every field, environment variable, timeout, file location and
170
+ protocol switch.
252
171
 
253
172
  ## State and security
254
173
 
255
- - The server refuses to start without a non-empty `api_keys` entry and binds to
256
- `127.0.0.1` by default.
257
- - `auth_source: "local"` stores credentials and account state in the platform
258
- config directory. The database and its WAL/SHM files are created owner-only;
259
- keep the JSON config owner-only as well.
260
- - A single-instance lock prevents two provider processes from splitting local
261
- account capacity, branch ordering, and continuation state.
262
- - Reasoning replay is encrypted with AES-256-GCM. Logs exclude credentials,
263
- prompts, tool arguments, signatures, and raw reasoning.
264
- - A configured `proxy_url` applies to model calls, login, token refresh, and
265
- quota probes together.
266
-
267
- Use only Kiro accounts you control. The project is not intended to share or
268
- resell access or to bypass account-level usage limits.
174
+ - The server refuses to start without a non-empty `api_keys` entry and binds to `127.0.0.1` by default.
175
+ - Credentials and account state live in `accounts.db` in the platform config directory. The database and its WAL/SHM
176
+ files are created owner-only; keep the JSON config owner-only as well.
177
+ - A single-instance lock stops two gateways on one config directory from splitting account capacity and conversation
178
+ state.
179
+ - Reasoning replay is encrypted with AES-256-GCM. Logs exclude credentials, prompts, tool arguments, signatures and
180
+ raw reasoning.
181
+ - A configured `proxy_url` applies to model calls, login, token refresh and quota probes together.
182
+
183
+ Use only Kiro accounts you control. The project is not intended to share or resell access or to bypass account-level
184
+ usage limits.
185
+
186
+ ## Updates
187
+
188
+ ```bash
189
+ kiro-provider --version --check # look up the latest release
190
+ kiro-provider self-update # replace a standalone binary after verifying it
191
+ bun add -g @sunerpy/kiro-provider@latest
192
+ ```
193
+
194
+ `self-update` refuses npm installs and never reads the gateway config. Restart the gateway after updating it; the
195
+ [service guide](docs/SERVICE.md#upgrading-the-service-binary) has the sequence for systemd and the Windows scheduled
196
+ task.
269
197
 
270
198
  ## Documentation
271
199
 
272
- Browse the rendered documentation at [kiro-provider.firlab.app](https://kiro-provider.firlab.app/), use the [repository index](docs/README.md), or go directly to:
200
+ The website, [firlab.app/kiro-provider](https://firlab.app/kiro-provider/), has the guides in English and Chinese.
201
+ In this repository:
273
202
 
274
203
  - [Configuration reference](docs/CONFIGURATION.md)
275
204
  - [Background service](docs/SERVICE.md)
@@ -277,9 +206,9 @@ Browse the rendered documentation at [kiro-provider.firlab.app](https://kiro-pro
277
206
  - [Responses usage and context accounting](docs/RESPONSES_USAGE.md)
278
207
  - [Architecture](docs/ARCHITECTURE.md)
279
208
  - [Audit and validation records](docs/audits/README.md)
280
- - [Changelog](changelog/README.md)
209
+ - [Changelog](changelog/CHANGELOG-v3.x.md)
281
210
 
282
- Simplified Chinese versions are linked from the documentation index.
211
+ The [documentation index](docs/README.md) links every document and its Simplified Chinese version.
283
212
 
284
213
  ## Development
285
214
 
@@ -287,15 +216,14 @@ Simplified Chinese versions are linked from the documentation index.
287
216
  git clone https://github.com/sunerpy/kiro-provider.git
288
217
  cd kiro-provider
289
218
  bun install --frozen-lockfile
290
- make ci
219
+ make check
291
220
  make coverage-gate
292
221
  bun run build:binary
293
222
  ```
294
223
 
295
- `make pre-ci` runs the full local pull-request gate. Coverage is enforced at
296
- 93% for both the repository-owned gate and Codecov; `codecov/project` and
297
- `codecov/patch` are required merge checks. See [AGENTS.md](AGENTS.md) for the
298
- repository's implementation, security, and release rules.
224
+ `make pre-ci` runs the full local pull-request gate. Coverage is enforced at 93% for both the repository-owned gate
225
+ and Codecov; `codecov/project` and `codecov/patch` are required merge checks. See [AGENTS.md](AGENTS.md) for the
226
+ repository's implementation, security and release rules.
299
227
 
300
228
  ## License
301
229