@bogyie/opencode-kiro-plugin 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+Initial OpenCode Kiro provider plugin implementation.
+
+### Added
+
+- OpenCode server plugin entrypoint with `config`, `auth`, `provider`, and `tool` hooks.
+- Kiro provider config injection using `@ai-sdk/openai-compatible`.
+- Model resolver with normalization, aliases, hidden/manual models, disabled models, pass-through behavior, and configurable extra model presets.
+- Optional `modelDiscoveryCommand` support for refreshing model cache/provider metadata from user-configured CLI/API output.
+- Auth diagnostics for `KIRO_API_KEY`, OpenCode auth input, and `kiro-cli whoami`.
+- `kiro_status` diagnostic tool.
+- OpenAI-compatible request adapter for system prompts, chat history, multimodal data URL images/documents, tool specs, and tool results.
+- OpenAI-compatible generation options for temperature, token limit, and reasoning/thinking effort are preserved as best-effort model request fields in direct fetch mode.
+- CodeWhisperer metadata token usage is mapped to OpenAI-compatible non-streaming usage fields on a best-effort basis.
+- CodeWhisperer/Kiro transport with streaming text, tool-call deltas, configurable retry attempts, and request timeout.
+- CLI fallback using `kiro-cli chat --no-interactive`.
+- CLI fallback responses are wrapped as OpenAI-compatible SSE for streaming OpenCode calls and sanitized to remove terminal prompt/credits output.
+- CLI fallback child process timeout can be controlled with `requestTimeoutMs`.
+- Direct fetch backend now exposes `endpoint`, `profileArn`, `userAgent`, and `agentMode` plugin options.
+- ACP fallback using `kiro-cli acp` JSON-RPC stdio with initialize/session/model/prompt flow.
+- ACP streaming for `AgentMessageChunk`, basic `ToolCall` events, and embedded document resources.
+- ACP tool-call update handling now ignores progress/result-only updates that do not carry invocation payloads and deduplicates repeated tool calls by id in non-streaming responses.
+- ACP agent-origin request handling for permission requests, with default reject and `trustAllTools` allow mode.
+- ACP stdio client ignores non-JSON stdout log lines emitted by `kiro-cli acp --verbose` before JSON-RPC messages.
+- Clean build artifacts before packaging and add a built package import smoke check.
+- Structured error normalization for auth, quota/rate limit, upstream, network, unsupported backend, ACP, and timeout failures.
+- README, local OpenCode config example, implementation notes, license notes, and package metadata tests.
+
+### Notes
+
+- ACP tool progress/result parity and real Kiro CLI end-to-end validation are still in progress.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-kiro-plugin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# opencode-kiro-plugin
+
+OpenCode server plugin that registers Kiro as an OpenAI-compatible provider and adapts requests to Kiro backends.
+
+Status: early implementation. The CodeWhisperer streaming transport, CLI chat fallback, model resolver, multimodal request mapping, streaming text, and tool-call chunk mapping are implemented with unit tests. The ACP backend implements JSON-RPC stdio framing, initialize/session/model/prompt flow, streaming text from `AgentMessageChunk`, and basic `ToolCall` streaming; full ACP tool progress/result parity is still in progress.
+
+## Install
+
+After the package is published to npm, add it directly to your OpenCode config:
+
+```jsonc
+{
+  "plugin": ["@bogyie/opencode-kiro-plugin"],
+  "provider": {
+    "kiro": {
+      "models": {
+        "sonnet": {
+          "name": "Sonnet alias"
+        }
+      }
+    }
+  }
+}
+```
+
+For local development from this repository:
+
+```sh
+npm install
+npm run build
+```
+
+Then add the plugin to your OpenCode config. See [examples/opencode.jsonc](examples/opencode.jsonc).
+
+```jsonc
+{
+  "plugin": ["file:/absolute/path/to/opencode-kiro-plugin"],
+  "provider": {
+    "kiro": {
+      "models": {
+        "sonnet": {
+          "name": "Sonnet alias"
+        }
+      }
+    }
+  }
+}
+```
+
+## Auth
+
+The plugin resolves credentials in this order:
+
+1. `KIRO_API_KEY`
+2. OpenCode auth input for provider `kiro`
+3. `kiro-cli whoami` diagnostics for CLI session visibility
+
+Direct fetch mode requires an API key/token usable by the Kiro/CodeWhisperer client. `cli-chat` mode uses the official `kiro-cli chat --no-interactive` surface and depends on the local Kiro CLI login state.
+
+Use the `kiro_status` plugin tool to inspect provider id, backend, region, auth method, and fallback model preset count. Secrets are redacted in diagnostics.
+
+## Backend Modes
+
+Configure the backend through plugin options:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@bogyie/opencode-kiro-plugin",
+      {
+        "backend": "auto",
+        "region": "us-east-1",
+        "endpoint": "https://q.us-east-1.amazonaws.com",
+        "maxAttempts": 3,
+        "requestTimeoutMs": 120000,
+        "agentMode": "vibe"
+      }
+    ]
+  ]
+}
+```
+
+Supported values:
+
+- `auto`: use CodeWhisperer fetch transport when an API key is available; otherwise use CLI chat fallback.
+- `fetch`: require the direct Kiro/CodeWhisperer fetch path. If no usable auth is available, requests fail with a structured backend/auth error.
+- `cli-chat`: call `kiro-cli chat --no-interactive`. This is official and stable, but Kiro CLI does not currently expose a guaranteed per-request model flag.
+- `acp`: launch `kiro-cli acp`, initialize a session, optionally set the requested model, send the prompt, and collect `AgentMessageChunk` notifications until `TurnEnd`.
+
+`trustAllTools` affects both `cli-chat` and ACP permission handling. In ACP mode, permission requests are rejected by default and allowed only when `trustAllTools: true`.
+
+## Model Churn Handling
+
+The resolver intentionally avoids a hard whitelist. Fallback presets are used for OpenCode UI metadata and cache bootstrap only.
+
+Useful options:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@bogyie/opencode-kiro-plugin",
+      {
+        "modelCacheTtlSeconds": 21600,
+        "modelDiscovery": "auto",
+        "modelDiscoveryCommand": ["kiro-cli", "models", "--json"],
+        "modelAliases": {
+          "sonnet": "claude-sonnet-4.6",
+          "opus": "claude-opus-4.6"
+        },
+        "extraModels": {
+          "claude-opus-4-9": {
+            "name": "Claude Opus 4.9",
+            "limit": { "context": 1000000, "output": 64000 },
+            "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
+            "tool_call": true
+          }
+        },
+        "hiddenModels": {
+          "claude-sonnet-4.6-1m": "claude-sonnet-4.6-1m"
+        },
+        "disabledModels": ["old-model"],
+        "disableModelPassThrough": false
+      }
+    ]
+  ]
+}
+```
+
+Resolution order:
+
+1. Alias mapping
+2. Name normalization, for example `claude-sonnet-4-6` to `claude-sonnet-4.6`
+3. Disabled model check
+4. Dynamic cache hit
+5. Extra model preset cache hit
+6. Hidden/manual model mapping
+7. Optimistic pass-through unless disabled
+
+This keeps new Kiro model ids usable before the package is updated. Use `extraModels` when a new model should appear in OpenCode's model picker immediately. Set `disableModelPassThrough: true` only when you need strict model governance.
+
+`modelDiscoveryCommand` is optional and intentionally not guessed by default because Kiro CLI model-list flags may vary by version. When configured, stdout can be a JSON array, `{ "models": [...] }`, `{ "data": [...] }`, or one model id per line.
+
+## Troubleshooting
+
+- `UNSUPPORTED_BACKEND`: selected mode has no usable transport. Check `backend` and auth.
+- `KIRO_AUTH_ERROR`: login or API key is missing/invalid.
+- `KIRO_RATE_LIMIT`: upstream quota or rate limit was hit.
+- `KIRO_NETWORK_ERROR`: timeout or connectivity issue to Kiro/AWS endpoints.
+- `KIRO_ACP_TIMEOUT`: ACP did not send a `TurnEnd` notification before the prompt timeout.
+- `KIRO_ACP_PROCESS_ERROR` or `KIRO_ACP_PROCESS_EXITED`: `kiro-cli acp` could not start or exited while a request was pending.
+
+Direct fetch mode uses AWS SDK standard retry behavior. Tune `maxAttempts` and `requestTimeoutMs` if you need stricter failure boundaries in automation. Fetch mode also accepts `endpoint`, `profileArn`, `userAgent`, and `agentMode` for controlled environments. `cli-chat` uses `requestTimeoutMs` for the `kiro-cli chat --no-interactive` child process, and ACP uses it while waiting for `session/prompt` completion and `TurnEnd`.
+
+OpenAI-compatible `temperature`, `max_tokens`, `max_completion_tokens`, `reasoning_effort`, `reasoning.effort`, and `thinking.effort` are preserved for direct fetch mode through Kiro's `additionalModelRequestFields` path on a best-effort basis.
+
+For local checks:
+
+```sh
+npm test
+npm run typecheck
+npm run build
+```
+
+For real Kiro/OpenCode validation, use [docs/e2e-validation.md](docs/e2e-validation.md).
+
+## Release
+
+GitHub Release publishing drives npm publishing. To publish a new npm package:
+
+1. Set the repository secret `NPM_TOKEN` to an npm automation token with publish access to `@bogyie/opencode-kiro-plugin`.
+2. Update `package.json` and `package-lock.json` to the release version.
+3. Create and publish a GitHub Release whose tag matches the package version, for example `v0.1.0`.
+
+The `Publish npm package` workflow runs tests, typecheck, package smoke validation, `npm pack --dry-run`, and then `npm publish --provenance --access public`.
+
+## License And References
+
+This project is MIT licensed. See [LICENSE](LICENSE).
+
+Reference policy:
+
+- `tickernelz/opencode-kiro-auth` is MIT licensed and used as implementation reference material.
+- Kiro CLI/IDE licensing and AWS service terms are separate from this plugin license. Use the plugin only in compliance with the applicable Kiro/AWS terms.
+
+Research notes are kept in [docs](docs).

package/dist/acp-client.d.ts

@@ -0,0 +1,57 @@
+export type JsonRpcId = string | number;
+export interface JsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcSuccess {
+    readonly jsonrpc: "2.0";
+    readonly id: JsonRpcId;
+    readonly result: unknown;
+}
+export interface JsonRpcFailure {
+    readonly jsonrpc: "2.0";
+    readonly id: JsonRpcId;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: unknown;
+    };
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+export interface AcpConnection {
+    send(message: JsonRpcMessage): void | Promise<void>;
+    close?(): void;
+}
+export type AcpNotificationHandler = (message: JsonRpcNotification) => void;
+export type AcpRequestHandler = (message: JsonRpcRequest) => unknown | Promise<unknown>;
+export interface AcpJsonRpcClientOptions {
+    readonly onRequest?: AcpRequestHandler;
+}
+export declare function encodeJsonRpc(message: JsonRpcMessage): string;
+export declare function decodeJsonRpc(line: string): JsonRpcMessage;
+export declare function decodeJsonRpcLine(line: string): JsonRpcMessage | undefined;
+export declare class AcpJsonRpcClient {
+    #private;
+    constructor(connection: AcpConnection, options?: AcpJsonRpcClientOptions);
+    request(method: string, params?: unknown): Promise<unknown>;
+    receive(message: JsonRpcMessage): void;
+    rejectAll(error: unknown): void;
+    onNotification(handler: AcpNotificationHandler): () => void;
+    close(): void;
+}
+export interface AcpStdioClientOptions {
+    readonly command?: string;
+    readonly args?: ReadonlyArray<string>;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly requestHandler?: AcpRequestHandler;
+}
+export declare function createAcpStdioClient(options?: AcpStdioClientOptions): AcpJsonRpcClient;

package/dist/acp-client.js

@@ -0,0 +1,171 @@
+import { KiroPluginError } from "./errors.js";
+import { spawn } from "node:child_process";
+export function encodeJsonRpc(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+export function decodeJsonRpc(line) {
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object" || parsed.jsonrpc !== "2.0") {
+        throw new KiroPluginError("Invalid JSON-RPC 2.0 message.", "KIRO_ACP_PROTOCOL_ERROR", 502);
+    }
+    return parsed;
+}
+export function decodeJsonRpcLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    return decodeJsonRpc(trimmed);
+}
+function hasId(message) {
+    return "id" in message;
+}
+function isNotification(message) {
+    return "method" in message && !("id" in message);
+}
+function isRequest(message) {
+    return "method" in message && "id" in message;
+}
+function hasError(message) {
+    return "error" in message;
+}
+export class AcpJsonRpcClient {
+    #nextId = 1;
+    #connection;
+    #onRequest;
+    #pending = new Map();
+    #notifications = new Set();
+    constructor(connection, options = {}) {
+        this.#connection = connection;
+        this.#onRequest = options.onRequest;
+    }
+    async request(method, params) {
+        const id = this.#nextId++;
+        const message = params === undefined ? { jsonrpc: "2.0", id, method } : { jsonrpc: "2.0", id, method, params };
+        const response = new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+        });
+        try {
+            await this.#connection.send(message);
+        }
+        catch (error) {
+            this.#pending.delete(id);
+            throw error;
+        }
+        return response;
+    }
+    receive(message) {
+        if (isNotification(message)) {
+            for (const handler of this.#notifications)
+                handler(message);
+            return;
+        }
+        if (isRequest(message)) {
+            void this.#handleRequest(message);
+            return;
+        }
+        if (!hasId(message))
+            return;
+        const pending = this.#pending.get(message.id);
+        if (!pending)
+            return;
+        this.#pending.delete(message.id);
+        if (hasError(message)) {
+            pending.reject(new KiroPluginError(message.error.message, "KIRO_ACP_ERROR", 502));
+            return;
+        }
+        pending.resolve(message.result);
+    }
+    async #handleRequest(message) {
+        try {
+            if (!this.#onRequest) {
+                await this.#connection.send({
+                    jsonrpc: "2.0",
+                    id: message.id,
+                    error: { code: -32601, message: `Method not found: ${message.method}` },
+                });
+                return;
+            }
+            const result = await this.#onRequest(message);
+            await this.#connection.send({
+                jsonrpc: "2.0",
+                id: message.id,
+                result: result ?? null,
+            });
+        }
+        catch (error) {
+            await this.#connection.send({
+                jsonrpc: "2.0",
+                id: message.id,
+                error: {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : "ACP request handler failed",
+                },
+            });
+        }
+    }
+    rejectAll(error) {
+        for (const pending of this.#pending.values()) {
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+    onNotification(handler) {
+        this.#notifications.add(handler);
+        return () => {
+            this.#notifications.delete(handler);
+        };
+    }
+    close() {
+        this.#connection.close?.();
+    }
+}
+export function createAcpStdioClient(options = {}) {
+    let client;
+    const child = spawn(options.command ?? "kiro-cli", [...(options.args ?? ["acp"])], {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const connection = {
+        send(message) {
+            if (!child.stdin?.writable) {
+                throw new KiroPluginError("ACP process stdin is not writable.", "KIRO_ACP_PROCESS_ERROR", 502);
+            }
+            child.stdin.write(encodeJsonRpc(message));
+        },
+        close() {
+            child.kill();
+        },
+    };
+    client = new AcpJsonRpcClient(connection, options.requestHandler ? { onRequest: options.requestHandler } : {});
+    let stdout = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+        for (;;) {
+            const index = stdout.indexOf("\n");
+            if (index < 0)
+                break;
+            const line = stdout.slice(0, index).trim();
+            stdout = stdout.slice(index + 1);
+            if (!line)
+                continue;
+            try {
+                const message = decodeJsonRpcLine(line);
+                if (message)
+                    client?.receive(message);
+            }
+            catch (error) {
+                client?.rejectAll(error);
+            }
+        }
+    });
+    child.on("error", (error) => {
+        client?.rejectAll(new KiroPluginError(error.message, "KIRO_ACP_PROCESS_ERROR", 502));
+    });
+    child.on("exit", (code, signal) => {
+        client?.rejectAll(new KiroPluginError(`ACP process exited${code === null ? "" : ` with code ${code}`}${signal ? ` and signal ${signal}` : ""}.`, "KIRO_ACP_PROCESS_EXITED", 502));
+    });
+    return client;
+}

package/dist/acp-transport.d.ts

@@ -0,0 +1,33 @@
+import { type AcpNotificationHandler } from "./acp-client.js";
+import type { KiroTransport } from "./fetch-adapter.js";
+import type { KiroGenerateRequest } from "./request-adapter.js";
+import type { KiroGenerateResponse, KiroStreamEvent } from "./response-adapter.js";
+export interface AcpSessionClient {
+    request(method: string, params?: unknown): Promise<unknown>;
+    onNotification(handler: AcpNotificationHandler): () => void;
+    close?(): void;
+}
+export interface KiroAcpTransportOptions {
+    readonly client?: AcpSessionClient;
+    readonly command?: string;
+    readonly args?: ReadonlyArray<string>;
+    readonly cwd?: string;
+    readonly promptTimeoutMs?: number;
+    readonly trustAllTools?: boolean;
+    readonly clientInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+}
+export declare function acpPermissionResponse(params: unknown, trustAllTools?: boolean): {
+    outcome: {
+        outcome: "selected";
+        optionId: string;
+    };
+};
+export declare class KiroAcpTransport implements KiroTransport {
+    #private;
+    constructor(options?: KiroAcpTransportOptions);
+    generate(request: KiroGenerateRequest): Promise<KiroGenerateResponse>;
+    stream(request: KiroGenerateRequest): AsyncIterable<KiroStreamEvent>;
+}