@sunerpy/kiro-provider 3.2.7 → 3.2.8
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.
- package/README.md +165 -277
- package/dist/cli.js +52 -52
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,356 +2,244 @@
|
|
|
2
2
|
|
|
3
3
|
# kiro-provider
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use your AWS Kiro accounts from clients that speak OpenAI Responses or Anthropic Messages.
|
|
6
6
|
|
|
7
7
|
[](https://github.com/sunerpy/kiro-provider/actions/workflows/ci.yml)
|
|
8
8
|
[](https://github.com/sunerpy/kiro-provider/releases)
|
|
9
9
|
[](https://www.npmjs.com/package/@sunerpy/kiro-provider)
|
|
10
10
|
[](https://codecov.io/gh/sunerpy/kiro-provider)
|
|
11
11
|
[](./LICENSE)
|
|
12
|
-
[](https://bun.sh/)
|
|
13
12
|
|
|
14
|
-
[
|
|
13
|
+
[Quickstart](#quickstart) · [Clients](#use-it-with-an-agent) · [Compatibility](#compatibility-model) · [Documentation](#documentation)
|
|
15
14
|
|
|
16
15
|
[**English**](./README.md) · [简体中文](./docs/readme/README.zh-CN.md)
|
|
17
16
|
|
|
18
17
|
</div>
|
|
19
18
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- Complete signed Kiro envelopes use provider `kr1_...` replay tokens, AES-256-GCM storage, tenant/model/account/conversation/output binding, TTL/LRU cleanup, and account-locked replay. Native opaque tokens stay on CreateResponse and recover their owner from durable response records.
|
|
40
|
-
- Multi-account rotation with automatic token refresh and failover. Exhausted accounts are hard-excluded from model attempts, then automatically rejoin only after a bounded, deduplicated Kiro usage probe confirms a new quota window. A provider-owned maintenance loop also refreshes near-expiry tokens and stale usage while the service is idle.
|
|
41
|
-
- `kiro-provider login` and `accounts import` write directly to the provider-owned local authentication store. The former `auth_source: "opencode-shared"` compatibility mode was removed in 0.7.0; a configuration that still selects it fails at startup with migration instructions (import once, then use `local`).
|
|
42
|
-
- A single global `proxy_url` that, when set, routes all upstream egress (model requests, token refresh, quota probes, device-code login) through one HTTP(S) proxy.
|
|
43
|
-
- Ships as a self-contained compiled binary via `bun build --compile` — no runtime install required on the target machine.
|
|
44
|
-
|
|
45
|
-
## Protocol compatibility
|
|
46
|
-
|
|
47
|
-
V3 implements the core OpenAI Responses resource and makes every upstream
|
|
48
|
-
difference explicit:
|
|
49
|
-
|
|
50
|
-
- native JSON/SSE creation, instructions, function tools, supported effort and
|
|
51
|
-
token controls, and `previous_response_id` (exact native replay for affected Claude and Sol reasoning histories);
|
|
52
|
-
- automatic stateless fallback for `store:false`, max effort, provider-token
|
|
53
|
-
replay, custom grammar, unverified tool-bridge combinations, and Codex multi-agent items;
|
|
54
|
-
- tenant-isolated local response mirrors for retrieve, delete, input-items
|
|
55
|
-
pagination, and continuation;
|
|
56
|
-
- field-level OpenAI error envelopes for capabilities Kiro cannot preserve,
|
|
57
|
-
including Responses conversation objects, background execution, Structured
|
|
58
|
-
Outputs, hosted tools, remote file references, compact, and exact
|
|
59
|
-
input-token counting.
|
|
60
|
-
|
|
61
|
-
The old GenerateAssistantResponse `safe` mode remains fail-closed because
|
|
62
|
-
`additionalContext` did not preserve instruction content or priority, and the
|
|
63
|
-
account does not advertise the private `systemPrompt` feature. The default
|
|
64
|
-
`v3-auto` path instead uses KiroRuntime CreateResponse's native
|
|
65
|
-
`instructions` field.
|
|
66
|
-
|
|
67
|
-
`responses_fidelity_mode` defaults to `compatible` and reports request projection
|
|
68
|
-
losses in `X-Kiro-Compatibility`; `strict` rejects those semantics before generation.
|
|
69
|
-
`X-Kiro-Transport` distinguishes native, native-adapted, and stateless calls.
|
|
70
|
-
Native tool bridges are enabled only for verified model/region cells. Instruction
|
|
71
|
-
lifting stays experimental until its complete continuation gate passes. See the
|
|
72
|
-
[Responses fidelity validation](docs/audits/kiro-provider-responses-fidelity-2026-09-10.zh.md)
|
|
73
|
-
for history, reasoning, instruction-priority boundaries, and storage migration.
|
|
74
|
-
The [before/after report](docs/audits/kiro-provider-responses-before-after-2026-09-10.zh.md)
|
|
75
|
-
includes real OpenAI SDK, Codex, and Zuno results.
|
|
76
|
-
|
|
77
|
-
Usage preserves measured cache/read/write and reasoning sub-counts. When Kiro only
|
|
78
|
-
provides a context percentage and credits, compatible mode labels estimates and
|
|
79
|
-
unknown fields in `usage.metadata.kiro`; strict mode omits incomplete usage.
|
|
80
|
-
Context accounting does not multiply GPT's capped legacy percentage by its corrected
|
|
81
|
-
prompt budget. See [usage and context accounting](docs/RESPONSES_USAGE.md), including
|
|
82
|
-
the distinction between AI SDK 7's cumulative `usage` and `finalStep.usage`.
|
|
83
|
-
|
|
84
|
-
For the transport decision table, stored-response contract, data-retention
|
|
85
|
-
boundary, verified model controls, and current client evidence, see
|
|
86
|
-
[`docs/PROTOCOL_COMPATIBILITY.md`](docs/PROTOCOL_COMPATIBILITY.md) and the
|
|
87
|
-
[`docs/audits/`](docs/audits/README.md) records.
|
|
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.
|
|
88
38
|
|
|
89
39
|
## Install
|
|
90
40
|
|
|
91
|
-
|
|
41
|
+
Choose one command. The examples below use `kiro-provider`; if you run through
|
|
42
|
+
`bunx`, substitute `bunx @sunerpy/kiro-provider`.
|
|
92
43
|
|
|
93
|
-
###
|
|
44
|
+
### Bun
|
|
94
45
|
|
|
95
|
-
|
|
46
|
+
The npm package uses Bun APIs and does not run under Node.js or `npx`.
|
|
96
47
|
|
|
97
48
|
```bash
|
|
98
|
-
|
|
49
|
+
bun add -g @sunerpy/kiro-provider
|
|
50
|
+
kiro-provider --version
|
|
99
51
|
```
|
|
100
52
|
|
|
101
|
-
|
|
53
|
+
For a one-off run:
|
|
102
54
|
|
|
103
55
|
```bash
|
|
104
|
-
|
|
105
|
-
kiro-provider --help
|
|
56
|
+
bunx @sunerpy/kiro-provider --help
|
|
106
57
|
```
|
|
107
58
|
|
|
108
|
-
###
|
|
59
|
+
### Standalone binary
|
|
109
60
|
|
|
110
|
-
|
|
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.
|
|
111
64
|
|
|
112
|
-
|
|
65
|
+
Linux or macOS:
|
|
113
66
|
|
|
114
67
|
```bash
|
|
115
68
|
curl -fsSL https://raw.githubusercontent.com/sunerpy/kiro-provider/main/scripts/install.sh | sh
|
|
116
69
|
```
|
|
117
70
|
|
|
118
|
-
Windows
|
|
71
|
+
Windows PowerShell:
|
|
119
72
|
|
|
120
73
|
```powershell
|
|
121
74
|
irm https://raw.githubusercontent.com/sunerpy/kiro-provider/main/scripts/install.ps1 | iex
|
|
122
75
|
```
|
|
123
76
|
|
|
124
|
-
|
|
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.
|
|
125
80
|
|
|
126
|
-
|
|
127
|
-
curl -fsSL https://raw.githubusercontent.com/sunerpy/kiro-provider/main/scripts/install.sh | KIRO_PROVIDER_VERSION=3.0.0 sh
|
|
128
|
-
```
|
|
81
|
+
## Quickstart
|
|
129
82
|
|
|
130
|
-
|
|
131
|
-
|
|
83
|
+
### 1. Create the gateway config
|
|
84
|
+
|
|
85
|
+
Only `api_keys` is required. Use a private random value; this key authenticates
|
|
86
|
+
local clients to the gateway.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider"
|
|
90
|
+
cat > "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json" <<'EOF_CONFIG'
|
|
91
|
+
{
|
|
92
|
+
"api_keys": ["sk-replace-with-a-private-random-key"]
|
|
93
|
+
}
|
|
94
|
+
EOF_CONFIG
|
|
95
|
+
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json"
|
|
132
96
|
```
|
|
133
97
|
|
|
134
|
-
|
|
98
|
+
On Windows the default directory is `%APPDATA%\kiro-provider`. Pass
|
|
99
|
+
`--config <path>` to `login` and `serve` when using another file.
|
|
135
100
|
|
|
136
|
-
|
|
101
|
+
### 2. Sign in to Kiro
|
|
137
102
|
|
|
138
103
|
```bash
|
|
139
|
-
|
|
140
|
-
cd kiro-provider
|
|
141
|
-
bun install
|
|
142
|
-
bun run build:binary
|
|
143
|
-
./dist/kiro-provider --help
|
|
104
|
+
kiro-provider login
|
|
144
105
|
```
|
|
145
106
|
|
|
146
|
-
|
|
107
|
+
If you already used `opencode-kiro-auth`, copy those accounts into the
|
|
108
|
+
provider-owned store once:
|
|
147
109
|
|
|
148
110
|
```bash
|
|
149
|
-
|
|
150
|
-
bun run src/cli/bin.ts --help
|
|
111
|
+
kiro-provider accounts import
|
|
151
112
|
```
|
|
152
113
|
|
|
153
|
-
|
|
114
|
+
The import is not a live link. After it finishes, kiro-provider owns token and
|
|
115
|
+
usage refresh for its copy of the accounts.
|
|
154
116
|
|
|
155
|
-
|
|
117
|
+
### 3. Start the gateway
|
|
156
118
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider"
|
|
163
|
-
cat > "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json" <<'EOF'
|
|
164
|
-
{
|
|
165
|
-
"api_keys": ["sk-your-private-key"]
|
|
166
|
-
}
|
|
167
|
-
EOF
|
|
168
|
-
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/kiro-provider/config.json"
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
Replace `sk-your-private-key` with a private, random value (for example
|
|
172
|
-
`openssl rand -hex 24`). The complete
|
|
173
|
-
[`config.example.json`](config.example.json) in the repository and
|
|
174
|
-
[`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) describe every field.
|
|
175
|
-
|
|
176
|
-
**Windows locations.** On Windows the default config path is
|
|
177
|
-
`%APPDATA%\kiro-provider\config.json`, and `accounts.db`, the instance
|
|
178
|
-
lock, and the reasoning keyring live in that same directory (POSIX uses
|
|
179
|
-
`~/.config/kiro-provider` for all of them). Pass `--config <path>` to use a
|
|
180
|
-
different file.
|
|
181
|
-
|
|
182
|
-
2. **Populate the provider-owned authentication store.** If you previously
|
|
183
|
-
authenticated through OpenCode plus `opencode-kiro-auth`, import that
|
|
184
|
-
database once:
|
|
185
|
-
|
|
186
|
-
```bash
|
|
187
|
-
./dist/kiro-provider accounts import
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
The default source is `~/.config/opencode/kiro.db`; use `--from <path>` when
|
|
191
|
-
needed. This is a copy, not a live link: subsequent token and usage refreshes
|
|
192
|
-
are owned by kiro-provider. Alternatively, authenticate directly:
|
|
193
|
-
|
|
194
|
-
```bash
|
|
195
|
-
./dist/kiro-provider login
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
Avoid continuing to use the same imported refresh tokens from two
|
|
199
|
-
independently running authentication owners.
|
|
200
|
-
|
|
201
|
-
Inspect or refresh the provider-owned account pool at any time:
|
|
202
|
-
|
|
203
|
-
```bash
|
|
204
|
-
./dist/kiro-provider accounts list
|
|
205
|
-
./dist/kiro-provider accounts list --details
|
|
206
|
-
./dist/kiro-provider accounts refresh --all
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
3. **Start the gateway.**
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
./dist/kiro-provider serve
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
4. **Call the default Responses endpoint.**
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
curl -fsS http://127.0.0.1:8787/v1/models \
|
|
219
|
-
-H 'Authorization: Bearer sk-your-private-key'
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
```ts
|
|
223
|
-
import OpenAI from "openai";
|
|
224
|
-
|
|
225
|
-
const client = new OpenAI({
|
|
226
|
-
baseURL: "http://127.0.0.1:8787/v1",
|
|
227
|
-
apiKey: "sk-your-private-key",
|
|
228
|
-
});
|
|
229
|
-
|
|
230
|
-
const response = await client.responses.create({
|
|
231
|
-
model: "auto",
|
|
232
|
-
input: "Explain this repository.",
|
|
233
|
-
});
|
|
234
|
-
|
|
235
|
-
console.log(response.output_text);
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
OpenAI-compatible libraries that only implement Chat Completions require
|
|
239
|
-
`"enable_legacy_chat_completions": true` in the gateway config. For example,
|
|
240
|
-
with the [Vercel AI SDK](https://sdk.vercel.ai/) via
|
|
241
|
-
`@ai-sdk/openai-compatible`:
|
|
242
|
-
|
|
243
|
-
```ts
|
|
244
|
-
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
|
|
245
|
-
import { generateText } from "ai";
|
|
246
|
-
|
|
247
|
-
const kiro = createOpenAICompatible({
|
|
248
|
-
name: "kiro-provider",
|
|
249
|
-
baseURL: "http://127.0.0.1:8787/v1",
|
|
250
|
-
apiKey: "sk-your-private-key",
|
|
251
|
-
});
|
|
252
|
-
|
|
253
|
-
const { text } = await generateText({
|
|
254
|
-
model: kiro("auto"),
|
|
255
|
-
prompt: "Explain this repository.",
|
|
256
|
-
});
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
## Run as a background service
|
|
260
|
-
|
|
261
|
-
For an agent host, run one long-lived provider per OS user. Use a pinned
|
|
262
|
-
standalone binary, run authentication and the service as the same user, and
|
|
263
|
-
require both unauthenticated `/health` and authenticated `/ready` before
|
|
264
|
-
connecting clients. The default single-instance lock prevents a second process
|
|
265
|
-
from splitting account queues and session state.
|
|
266
|
-
|
|
267
|
-
The [background-service guide](docs/SERVICE.md) contains complete systemd user
|
|
268
|
-
service and Windows Scheduled Task examples, log locations, lifecycle commands,
|
|
269
|
-
health gates, and removal steps.
|
|
119
|
+
```bash
|
|
120
|
+
kiro-provider serve
|
|
121
|
+
```
|
|
270
122
|
|
|
271
|
-
|
|
123
|
+
The default address is `http://127.0.0.1:8787`. In another terminal, confirm
|
|
124
|
+
both process health and authenticated readiness:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
export KIRO_GATEWAY_API_KEY='sk-replace-with-a-private-random-key'
|
|
128
|
+
curl -fsS http://127.0.0.1:8787/health
|
|
129
|
+
curl -fsS http://127.0.0.1:8787/ready \
|
|
130
|
+
-H "Authorization: Bearer $KIRO_GATEWAY_API_KEY"
|
|
131
|
+
```
|
|
272
132
|
|
|
273
|
-
|
|
274
|
-
`KIRO_PROVIDER_*` environment variables and supported `serve` flags. Precedence
|
|
275
|
-
is **CLI flag > environment variable > JSON file > schema default**. Unknown
|
|
276
|
-
keys and invalid ranges fail at startup; an empty environment value is treated
|
|
277
|
-
as unset.
|
|
133
|
+
### 4. Send a Responses request
|
|
278
134
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
source of truth for every field, default, environment variable, timeout, proxy,
|
|
282
|
-
file location, and protocol switch. Do not copy provider-only fields such as
|
|
283
|
-
`responses_fidelity_mode` into a downstream client's request options.
|
|
135
|
+
```ts
|
|
136
|
+
import OpenAI from "openai";
|
|
284
137
|
|
|
285
|
-
|
|
138
|
+
const client = new OpenAI({
|
|
139
|
+
baseURL: "http://127.0.0.1:8787/v1",
|
|
140
|
+
apiKey: process.env.KIRO_GATEWAY_API_KEY,
|
|
141
|
+
});
|
|
286
142
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
- **Locked-down provider state.** `accounts.db` (and its WAL/SHM files) are created with mode `0600`; in default local mode it contains credentials, usage, health, session affinity, and encrypted replay state.
|
|
292
|
-
- **Authenticated reasoning replay.** The database stores token/fingerprint hashes and AES-256-GCM ciphertext, not raw `kr1_...` tokens. Missing active decryption keys fail startup.
|
|
293
|
-
- **No sensitive content in logs.** Gateway/account secrets, replay tokens, signatures, reasoning, and request prompt text are not logged; structured audit fields contain hashes and field names only. Don't commit a real config file, account database, keyring, or gateway key.
|
|
143
|
+
const response = await client.responses.create({
|
|
144
|
+
model: "auto",
|
|
145
|
+
input: "Reply with exactly: KIRO_OK",
|
|
146
|
+
});
|
|
294
147
|
|
|
295
|
-
|
|
148
|
+
console.log(response.output_text);
|
|
149
|
+
```
|
|
296
150
|
|
|
297
|
-
|
|
151
|
+
Model IDs come from the accounts currently ready in the local pool. Query
|
|
152
|
+
`GET /v1/models` rather than hard-coding a catalog copied from another account
|
|
153
|
+
or region.
|
|
298
154
|
|
|
299
|
-
Use
|
|
300
|
-
for Anthropic Messages clients. Enable `POST /v1/chat/completions` only for a
|
|
301
|
-
client that cannot use either primary surface.
|
|
155
|
+
## Use it with an agent
|
|
302
156
|
|
|
303
|
-
| Client |
|
|
157
|
+
| Client | API | Guide |
|
|
304
158
|
| --- | --- | --- |
|
|
305
|
-
| Zuno | OpenAI Responses | [
|
|
306
|
-
| Codex CLI | OpenAI Responses | [Isolated profile and
|
|
307
|
-
| Claude Code | Anthropic Messages | [Isolated `kiroclaude` profile and
|
|
308
|
-
| Other SDKs | Responses
|
|
309
|
-
|
|
310
|
-
The
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
159
|
+
| Zuno | OpenAI Responses | [Native provider configuration and session routing](docs/ZUNO.md) |
|
|
160
|
+
| Codex CLI | OpenAI Responses | [Isolated profile and compatibility checks](docs/CODEX.md) |
|
|
161
|
+
| Claude Code | Anthropic Messages | [Isolated `kiroclaude` profile and model selection](docs/CLAUDE_CODE.md) |
|
|
162
|
+
| Other SDKs | Responses or Messages | [Protocol compatibility](docs/PROTOCOL_COMPATIBILITY.md) |
|
|
163
|
+
|
|
164
|
+
The client guides use isolated profiles so the ordinary `codex` and `claude`
|
|
165
|
+
commands keep their existing providers and state. They also record the exact
|
|
166
|
+
client versions last tested. Treat those versions as dated evidence, not a
|
|
167
|
+
promise about future request shapes.
|
|
168
|
+
|
|
169
|
+
## Configuration
|
|
170
|
+
|
|
171
|
+
Configuration precedence is CLI flag, environment variable, JSON file, then
|
|
172
|
+
schema default. Unknown keys and invalid values fail at startup. Start from
|
|
173
|
+
[`config.example.json`](config.example.json), then use the
|
|
174
|
+
[configuration reference](docs/CONFIGURATION.md) for every field, environment
|
|
175
|
+
variable, timeout, file location, and protocol switch.
|
|
176
|
+
|
|
177
|
+
## Compatibility model
|
|
178
|
+
|
|
179
|
+
The default `protocol_projection_mode: "v3-auto"` keeps transport selection in
|
|
180
|
+
the gateway:
|
|
181
|
+
|
|
182
|
+
- ordinary Responses requests use KiroRuntime's native Responses operation;
|
|
183
|
+
- requests that need stateless-only semantics, including `store: false`, max
|
|
184
|
+
effort, provider reasoning replay, custom grammar, or collaboration items,
|
|
185
|
+
use the canonical stateless path;
|
|
186
|
+
- Anthropic Messages requests are projected directly into the Kiro contract,
|
|
187
|
+
with signed thinking replay kept opaque to the client;
|
|
188
|
+
- unsupported semantics are rejected with field-level errors.
|
|
189
|
+
|
|
190
|
+
This is not a promise of full OpenAI or Anthropic parity. Hosted tools,
|
|
191
|
+
background Responses, Responses conversation objects, Structured Outputs,
|
|
192
|
+
remote file references, exact input-token counting, and destructive context
|
|
193
|
+
edits are examples of features the gateway cannot currently preserve. The
|
|
194
|
+
[compatibility guide](docs/PROTOCOL_COMPATIBILITY.md) is the current contract;
|
|
195
|
+
the [audit index](docs/audits/README.md) contains dated probe evidence.
|
|
196
|
+
|
|
197
|
+
## State and security
|
|
198
|
+
|
|
199
|
+
- The server refuses to start without a non-empty `api_keys` entry and binds to
|
|
200
|
+
`127.0.0.1` by default.
|
|
201
|
+
- `auth_source: "local"` stores credentials and account state in the platform
|
|
202
|
+
config directory. The database and its WAL/SHM files are created owner-only;
|
|
203
|
+
keep the JSON config owner-only as well.
|
|
204
|
+
- A single-instance lock prevents two provider processes from splitting local
|
|
205
|
+
account queues and continuation state.
|
|
206
|
+
- Reasoning replay is encrypted with AES-256-GCM. Logs exclude credentials,
|
|
207
|
+
prompts, tool arguments, signatures, and raw reasoning.
|
|
208
|
+
- A configured `proxy_url` applies to model calls, login, token refresh, and
|
|
209
|
+
quota probes together.
|
|
210
|
+
|
|
211
|
+
Use only Kiro accounts you control. The project is not intended to share or
|
|
212
|
+
resell access or to bypass account-level usage limits.
|
|
329
213
|
|
|
330
214
|
## Documentation
|
|
331
215
|
|
|
332
|
-
[
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
[
|
|
216
|
+
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:
|
|
217
|
+
|
|
218
|
+
- [Configuration reference](docs/CONFIGURATION.md)
|
|
219
|
+
- [Background service](docs/SERVICE.md)
|
|
220
|
+
- [Troubleshooting](docs/TROUBLESHOOTING.md)
|
|
221
|
+
- [Responses usage and context accounting](docs/RESPONSES_USAGE.md)
|
|
222
|
+
- [Architecture](docs/ARCHITECTURE.md)
|
|
223
|
+
- [Audit and validation records](docs/audits/README.md)
|
|
224
|
+
- [Changelog](changelog/README.md)
|
|
225
|
+
|
|
226
|
+
Simplified Chinese versions are linked from the documentation index.
|
|
336
227
|
|
|
337
228
|
## Development
|
|
338
229
|
|
|
339
230
|
```bash
|
|
231
|
+
git clone https://github.com/sunerpy/kiro-provider.git
|
|
232
|
+
cd kiro-provider
|
|
340
233
|
bun install --frozen-lockfile
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
bun test
|
|
344
|
-
bun run build
|
|
234
|
+
make ci
|
|
235
|
+
make coverage-gate
|
|
345
236
|
bun run build:binary
|
|
346
|
-
bash scripts/security-check.sh # security regression suite (Linux, needs openssl/curl/ss)
|
|
347
237
|
```
|
|
348
238
|
|
|
349
|
-
`make ci` runs the
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
first with `bun install --frozen-lockfile`. `bun run scripts/smoke.ts --help` describes
|
|
354
|
-
the live end-to-end checks against a running gateway.
|
|
239
|
+
`make pre-ci` runs the full local pull-request gate. Coverage is enforced at
|
|
240
|
+
93% for both the repository-owned gate and Codecov; `codecov/project` and
|
|
241
|
+
`codecov/patch` are required merge checks. See [AGENTS.md](AGENTS.md) for the
|
|
242
|
+
repository's implementation, security, and release rules.
|
|
355
243
|
|
|
356
244
|
## License
|
|
357
245
|
|