kiro-tap 0.1.0__tar.gz

kiro_tap-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.traces/
+*.jsonl
+*.db
+.python-version
+uv.lock

kiro_tap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harllan He
+
+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.

kiro_tap-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: kiro-tap
+Version: 0.1.0
+Summary: Trace Kiro CLI and Kiro IDE API requests via a local forward proxy. Inspect system prompts, messages, tools, and token usage.
+Author: kiro-tap contributors
+License-Expression: MIT
+Keywords: kiro,kiro-cli,trace,proxy,api,llm,aws,codewhisperer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.9
+Requires-Dist: backports-zstd>=1.0; python_version < "3.14"
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Requires-Dist: pexpect>=4.9; extra == "dev"
+Requires-Dist: coverage>=7.6; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Dynamic: license-file
+
+# kiro-tap
+
+[![Python version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+`kiro-tap` 是 Kiro CLI 和 Kiro IDE 的本地代理与请求追踪工具。通过它运行 Kiro，即可实时捕获所有 API 请求：系统提示词、对话历史、工具定义、工具调用、流式响应和 Token 用量。
+
+支持 [Kiro CLI](https://kiro.dev)（`kiro-cli-chat`）和 [Kiro IDE](https://kiro.dev)。
+
+## 为什么用它
+
+- 👀 **看清真实上下文**：查看发往 Kiro API 的完整请求，包括系统提示、消息历史、工具定义、工具调用和响应内容
+- 🔎 **有据可查地调试**：对比相邻请求，精确定位哪条消息、哪个工具或哪个参数发生了变化
+- 📦 **一个可分享的文件**：每次运行生成本地 trace，可导出为自包含的 HTML 查看器，方便存档或分享
+- 🔒 **数据留在本机**：无需任何云端 Dashboard，常见认证 Header 在记录前自动脱敏
+- ⚡ **AWS Event Stream 原生支持**：正确解析 Kiro 使用的 AWS Event Stream 二进制帧协议，完整还原流式响应
+
+## 安装
+
+需要 Python 3.11+。
+
+```bash
+# 推荐
+uv tool install kiro-tap
+
+# 或使用 pip
+pip install kiro-tap
+```
+
+升级：`kiro-tap update`、`uv tool upgrade kiro-tap` 或 `pip install --upgrade kiro-tap`
+
+## 快速开始
+
+```bash
+# Kiro CLI（默认，实时 Dashboard 默认开启）
+kiro-tap
+
+# Kiro IDE
+kiro-tap --tap-client kiro-ide
+
+# 关闭实时 Dashboard
+kiro-tap --tap-no-live
+
+# 不自动打开浏览器
+kiro-tap --tap-no-open
+```
+
+## 工作原理
+
+```
+kiro-tap 启动本地正向代理
+    ↓
+注入 HTTPS_PROXY + SSL_CERT_FILE 到子进程环境
+    ↓
+启动 kiro-cli-chat（或 kiro）
+    ↓
+所有 HTTPS 流量经过本地代理 → TLS 终止 → 转发到 q.us-east-1.amazonaws.com
+    ↓
+AWS Event Stream 二进制帧解析 → 重建完整响应
+    ↓
+写入本地 SQLite trace 数据库
+    ↓
+实时推送到浏览器 Dashboard（SSE）
+```
+
+kiro-tap 使用**正向代理模式**（CONNECT + TLS 终止），因为 Kiro CLI 没有暴露 base URL 环境变量。代理会自动生成本地 CA 证书并注入到子进程，无需 sudo。
+
+## CLI 选项
+
+所有 `--tap-*` 之外的参数都会透传给 Kiro 客户端。
+
+```
+--tap-client CLIENT      要启动的客户端：kiro（默认）或 kiro-ide
+--tap-target URL         上游 API URL（默认：https://q.us-east-1.amazonaws.com）
+--tap-live               运行时开启实时 Dashboard（默认：开）
+--tap-no-live            关闭实时 Dashboard
+--tap-live-port PORT     实时 Dashboard 端口（默认：19528）
+--tap-no-open            不自动在浏览器中打开 Dashboard 或生成的 HTML
+--tap-output-dir DIR     旧版 trace 目录（默认：./.traces）
+--tap-port PORT          代理端口（默认：自动）
+--tap-host HOST          绑定地址（默认：127.0.0.1）
+--tap-no-launch          只启动代理，不启动客户端
+--tap-max-traces N       保留的最大 trace 会话数（默认：50，0 = 不限）
+--tap-store-stream-events 持久化原始 AWS Event Stream 帧数组（默认：关）
+--tap-no-update-check    禁用启动时的 PyPI 更新检查
+--tap-no-auto-update     检查更新但不自动下载
+--tap-trust-ca           在 macOS 用户登录钥匙串中信任本地 CA（无需 sudo）
+```
+
+## 子命令
+
+```bash
+# 浏览历史 trace
+kiro-tap dashboard
+
+# 将 JSONL trace 导出为 HTML / Markdown / JSON
+kiro-tap export .traces/session.jsonl -o trace.html
+
+# 升级 kiro-tap
+kiro-tap update
+
+# 在 macOS 钥匙串中信任本地 CA（正向代理模式需要）
+kiro-tap trust-ca
+```
+
+## 仅代理模式
+
+```bash
+# 只启动代理，在另一个终端手动启动 Kiro
+kiro-tap --tap-no-launch --tap-port 8080
+
+# 然后在另一个终端：
+HTTPS_PROXY=http://127.0.0.1:8080 SSL_CERT_FILE=~/.kiro-tap/ca.pem kiro-cli-chat
+```
+
+## Viewer 功能
+
+生成的 HTML 查看器（零外部依赖）支持：
+
+- **结构化 Diff**：对比相邻请求，查看消息、系统提示、工具的变化
+- **路径过滤**：按 API 端点过滤（如只看 `/generateAssistantResponse`）
+- **Token 用量**：输入 / 输出 / 缓存读取 / 缓存写入
+- **工具检查器**：可展开的工具卡片，含名称、描述和参数 schema
+- **全文搜索**：跨消息、工具、提示词和响应搜索
+- **深色模式**：跟随系统偏好
+- **键盘导航**：`j`/`k` 或方向键
+- **一键复制**：复制请求 JSON 或 cURL 命令
+- **多语言**：English、简体中文、日本語、한국어、Français、العربية、Deutsch、Русский
+
+## AWS Event Stream 解析
+
+Kiro API 使用 AWS Event Stream 二进制帧协议（非标准 SSE）。kiro-tap 实现了完整的帧解析器：
+
+- CRC32 校验（ISO-HDLC，与 AWS SDK 一致）
+- 所有 Header 值类型（bool、byte、short、int、long、bytes、string、timestamp、uuid）
+- 事件类型：`assistantResponseEvent`、`toolUseEvent`、`meteringEvent`、`contextUsageEvent`、`codeReferenceEvent`
+- 错误/异常消息类型
+
+## 许可证
+
+MIT

kiro_tap-0.1.0/README.md

@@ -0,0 +1,141 @@
+# kiro-tap
+
+[![Python version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+`kiro-tap` 是 Kiro CLI 和 Kiro IDE 的本地代理与请求追踪工具。通过它运行 Kiro，即可实时捕获所有 API 请求：系统提示词、对话历史、工具定义、工具调用、流式响应和 Token 用量。
+
+支持 [Kiro CLI](https://kiro.dev)（`kiro-cli-chat`）和 [Kiro IDE](https://kiro.dev)。
+
+## 为什么用它
+
+- 👀 **看清真实上下文**：查看发往 Kiro API 的完整请求，包括系统提示、消息历史、工具定义、工具调用和响应内容
+- 🔎 **有据可查地调试**：对比相邻请求，精确定位哪条消息、哪个工具或哪个参数发生了变化
+- 📦 **一个可分享的文件**：每次运行生成本地 trace，可导出为自包含的 HTML 查看器，方便存档或分享
+- 🔒 **数据留在本机**：无需任何云端 Dashboard，常见认证 Header 在记录前自动脱敏
+- ⚡ **AWS Event Stream 原生支持**：正确解析 Kiro 使用的 AWS Event Stream 二进制帧协议，完整还原流式响应
+
+## 安装
+
+需要 Python 3.11+。
+
+```bash
+# 推荐
+uv tool install kiro-tap
+
+# 或使用 pip
+pip install kiro-tap
+```
+
+升级：`kiro-tap update`、`uv tool upgrade kiro-tap` 或 `pip install --upgrade kiro-tap`
+
+## 快速开始
+
+```bash
+# Kiro CLI（默认，实时 Dashboard 默认开启）
+kiro-tap
+
+# Kiro IDE
+kiro-tap --tap-client kiro-ide
+
+# 关闭实时 Dashboard
+kiro-tap --tap-no-live
+
+# 不自动打开浏览器
+kiro-tap --tap-no-open
+```
+
+## 工作原理
+
+```
+kiro-tap 启动本地正向代理
+    ↓
+注入 HTTPS_PROXY + SSL_CERT_FILE 到子进程环境
+    ↓
+启动 kiro-cli-chat（或 kiro）
+    ↓
+所有 HTTPS 流量经过本地代理 → TLS 终止 → 转发到 q.us-east-1.amazonaws.com
+    ↓
+AWS Event Stream 二进制帧解析 → 重建完整响应
+    ↓
+写入本地 SQLite trace 数据库
+    ↓
+实时推送到浏览器 Dashboard（SSE）
+```
+
+kiro-tap 使用**正向代理模式**（CONNECT + TLS 终止），因为 Kiro CLI 没有暴露 base URL 环境变量。代理会自动生成本地 CA 证书并注入到子进程，无需 sudo。
+
+## CLI 选项
+
+所有 `--tap-*` 之外的参数都会透传给 Kiro 客户端。
+
+```
+--tap-client CLIENT      要启动的客户端：kiro（默认）或 kiro-ide
+--tap-target URL         上游 API URL（默认：https://q.us-east-1.amazonaws.com）
+--tap-live               运行时开启实时 Dashboard（默认：开）
+--tap-no-live            关闭实时 Dashboard
+--tap-live-port PORT     实时 Dashboard 端口（默认：19528）
+--tap-no-open            不自动在浏览器中打开 Dashboard 或生成的 HTML
+--tap-output-dir DIR     旧版 trace 目录（默认：./.traces）
+--tap-port PORT          代理端口（默认：自动）
+--tap-host HOST          绑定地址（默认：127.0.0.1）
+--tap-no-launch          只启动代理，不启动客户端
+--tap-max-traces N       保留的最大 trace 会话数（默认：50，0 = 不限）
+--tap-store-stream-events 持久化原始 AWS Event Stream 帧数组（默认：关）
+--tap-no-update-check    禁用启动时的 PyPI 更新检查
+--tap-no-auto-update     检查更新但不自动下载
+--tap-trust-ca           在 macOS 用户登录钥匙串中信任本地 CA（无需 sudo）
+```
+
+## 子命令
+
+```bash
+# 浏览历史 trace
+kiro-tap dashboard
+
+# 将 JSONL trace 导出为 HTML / Markdown / JSON
+kiro-tap export .traces/session.jsonl -o trace.html
+
+# 升级 kiro-tap
+kiro-tap update
+
+# 在 macOS 钥匙串中信任本地 CA（正向代理模式需要）
+kiro-tap trust-ca
+```
+
+## 仅代理模式
+
+```bash
+# 只启动代理，在另一个终端手动启动 Kiro
+kiro-tap --tap-no-launch --tap-port 8080
+
+# 然后在另一个终端：
+HTTPS_PROXY=http://127.0.0.1:8080 SSL_CERT_FILE=~/.kiro-tap/ca.pem kiro-cli-chat
+```
+
+## Viewer 功能
+
+生成的 HTML 查看器（零外部依赖）支持：
+
+- **结构化 Diff**：对比相邻请求，查看消息、系统提示、工具的变化
+- **路径过滤**：按 API 端点过滤（如只看 `/generateAssistantResponse`）
+- **Token 用量**：输入 / 输出 / 缓存读取 / 缓存写入
+- **工具检查器**：可展开的工具卡片，含名称、描述和参数 schema
+- **全文搜索**：跨消息、工具、提示词和响应搜索
+- **深色模式**：跟随系统偏好
+- **键盘导航**：`j`/`k` 或方向键
+- **一键复制**：复制请求 JSON 或 cURL 命令
+- **多语言**：English、简体中文、日本語、한국어、Français、العربية、Deutsch、Русский
+
+## AWS Event Stream 解析
+
+Kiro API 使用 AWS Event Stream 二进制帧协议（非标准 SSE）。kiro-tap 实现了完整的帧解析器：
+
+- CRC32 校验（ISO-HDLC，与 AWS SDK 一致）
+- 所有 Header 值类型（bool、byte、short、int、long、bytes、string、timestamp、uuid）
+- 事件类型：`assistantResponseEvent`、`toolUseEvent`、`meteringEvent`、`contextUsageEvent`、`codeReferenceEvent`
+- 错误/异常消息类型
+
+## 许可证
+
+MIT

kiro_tap-0.1.0/README_en.md

@@ -0,0 +1,143 @@
+# kiro-tap
+
+[![Python version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[中文文档](README.md)
+
+`kiro-tap` is a local proxy and trace viewer for Kiro CLI and Kiro IDE. Run Kiro through it to inspect real API traffic: system prompts, conversation history, tool schemas, tool calls, streaming responses, and token usage.
+
+Supports [Kiro CLI](https://kiro.dev) (`kiro-cli-chat`) and [Kiro IDE](https://kiro.dev).
+
+## Why use it
+
+- 👀 **See the exact context**: inspect every request sent to the Kiro API, including system prompts, message history, tool definitions, tool calls, and responses
+- 🔎 **Debug with evidence**: compare adjacent requests and pinpoint which message, tool, or parameter changed
+- 📦 **Share one portable artifact**: each run writes a local trace that can be exported to a self-contained HTML viewer for review or archiving
+- 🔒 **Keep traces on your machine**: no hosted dashboard required, and common auth headers are redacted before recording
+- ⚡ **Native AWS Event Stream support**: correctly parses Kiro's AWS Event Stream binary frame protocol and fully reconstructs streaming responses
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+# Recommended
+uv tool install kiro-tap
+
+# Or with pip
+pip install kiro-tap
+```
+
+Upgrade: `kiro-tap update`, `uv tool upgrade kiro-tap`, or `pip install --upgrade kiro-tap`
+
+## Quick Start
+
+```bash
+# Kiro CLI (default, live dashboard enabled by default)
+kiro-tap
+
+# Kiro IDE
+kiro-tap --tap-client kiro-ide
+
+# Disable live dashboard
+kiro-tap --tap-no-live
+
+# Don't auto-open browser
+kiro-tap --tap-no-open
+```
+
+## How it works
+
+```
+kiro-tap starts a local forward proxy
+    ↓
+Injects HTTPS_PROXY + SSL_CERT_FILE into the child process environment
+    ↓
+Launches kiro-cli-chat (or kiro)
+    ↓
+All HTTPS traffic → local proxy → TLS termination → forwarded to q.us-east-1.amazonaws.com
+    ↓
+AWS Event Stream binary frame parsing → full response reconstruction
+    ↓
+Written to local SQLite trace database
+    ↓
+Pushed to browser dashboard in real time (SSE)
+```
+
+kiro-tap uses **forward proxy mode** (CONNECT + TLS termination) because Kiro CLI does not expose a base URL environment variable. The proxy auto-generates a local CA certificate and injects it into the child process — no sudo required.
+
+## CLI Options
+
+All flags except `--tap-*` are forwarded to the selected Kiro client.
+
+```
+--tap-client CLIENT      Client to launch: kiro (default) or kiro-ide
+--tap-target URL         Upstream API URL (default: https://q.us-east-1.amazonaws.com)
+--tap-live               Start real-time dashboard while client runs (default: on)
+--tap-no-live            Disable the real-time dashboard
+--tap-live-port PORT     Port for the live dashboard (default: 19528)
+--tap-no-open            Don't auto-open dashboard or generated HTML in a browser
+--tap-output-dir DIR     Legacy trace directory (default: ./.traces)
+--tap-port PORT          Proxy port (default: auto)
+--tap-host HOST          Bind address (default: 127.0.0.1)
+--tap-no-launch          Only start the proxy, don't launch client
+--tap-max-traces N       Max trace sessions to keep (default: 50, 0 = unlimited)
+--tap-store-stream-events Persist raw AWS Event Stream frame arrays (default: off)
+--tap-no-update-check    Disable PyPI update check on startup
+--tap-no-auto-update     Check for updates but don't auto-download
+--tap-trust-ca           Trust local CA in macOS user login keychain (no sudo)
+```
+
+## Subcommands
+
+```bash
+# Browse trace history
+kiro-tap dashboard
+
+# Export a JSONL trace to HTML / Markdown / JSON
+kiro-tap export .traces/session.jsonl -o trace.html
+
+# Upgrade kiro-tap
+kiro-tap update
+
+# Trust local CA in macOS keychain (needed for forward proxy mode)
+kiro-tap trust-ca
+```
+
+## Proxy-only mode
+
+```bash
+# Start proxy only, launch Kiro manually in another terminal
+kiro-tap --tap-no-launch --tap-port 8080
+
+# Then in another terminal:
+HTTPS_PROXY=http://127.0.0.1:8080 SSL_CERT_FILE=~/.kiro-tap/ca.pem kiro-cli-chat
+```
+
+## Viewer Features
+
+The generated HTML viewer (zero external dependencies) supports:
+
+- **Structural diff** — compare consecutive requests to see exactly what changed: new/removed messages, system prompt diffs, character-level inline highlighting
+- **Path filtering** — filter by API endpoint (e.g. `/generateAssistantResponse` only)
+- **Token usage breakdown** — input / output / cache read / cache creation
+- **Tool inspector** — expandable cards with tool name, description, and parameter schema
+- **Search** — full-text search across messages, tools, prompts, and responses
+- **Dark mode** — toggle light/dark themes (respects system preference)
+- **Keyboard navigation** — `j`/`k` or arrow keys
+- **Copy helpers** — one-click copy of request JSON or cURL command
+- **i18n** — English, 简体中文, 日本語, 한국어, Français, العربية, Deutsch, Русский
+
+## AWS Event Stream Parsing
+
+The Kiro API uses the AWS Event Stream binary framing protocol (not standard SSE). kiro-tap implements a full frame parser:
+
+- CRC32 verification (ISO-HDLC, matching the AWS SDK)
+- All header value types (bool, byte, short, int, long, bytes, string, timestamp, uuid)
+- Event types: `assistantResponseEvent`, `toolUseEvent`, `meteringEvent`, `contextUsageEvent`, `codeReferenceEvent`
+- Error and exception message types
+
+## License
+
+MIT

kiro_tap-0.1.0/kiro_tap/__init__.py

@@ -0,0 +1,62 @@
+"""kiro-tap: Proxy to trace Kiro CLI and Kiro IDE API requests.
+
+A CLI tool that wraps Kiro CLI with a local forward proxy to intercept
+and record all API requests. Useful for studying Kiro's context engineering.
+"""
+
+from __future__ import annotations
+
+from kiro_tap.certs import CertificateAuthority, ensure_ca
+from kiro_tap.cli import (
+    __version__,
+    _build_update_command,
+    _detect_installer,
+    _version_tuple,
+    async_main,
+    dashboard_main,
+    main_entry,
+    parse_args,
+    parse_dashboard_args,
+    parse_trust_ca_args,
+    parse_update_args,
+    trust_ca_main,
+    update_main,
+)
+from kiro_tap.forward_proxy import ForwardProxyServer
+from kiro_tap.history import cleanup_trace_sessions, delete_trace_history, migrate_legacy_traces
+from kiro_tap.live import LiveViewerServer
+from kiro_tap.proxy import filter_headers
+from kiro_tap.aws_event_stream import AWSEventStreamReassembler
+from kiro_tap.trace import TraceWriter
+from kiro_tap.trace_store import get_trace_store, reset_trace_store, resolve_db_path
+from kiro_tap.viewer import _generate_html_viewer
+
+__all__ = [
+    "__version__",
+    "_build_update_command",
+    "_detect_installer",
+    "_version_tuple",
+    "main_entry",
+    "parse_args",
+    "parse_dashboard_args",
+    "parse_trust_ca_args",
+    "parse_update_args",
+    "trust_ca_main",
+    "update_main",
+    "async_main",
+    "dashboard_main",
+    "CertificateAuthority",
+    "ensure_ca",
+    "ForwardProxyServer",
+    "AWSEventStreamReassembler",
+    "TraceWriter",
+    "LiveViewerServer",
+    "filter_headers",
+    "_generate_html_viewer",
+    "cleanup_trace_sessions",
+    "delete_trace_history",
+    "migrate_legacy_traces",
+    "get_trace_store",
+    "reset_trace_store",
+    "resolve_db_path",
+]

kiro_tap-0.1.0/kiro_tap/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m kiro_tap`."""
+
+from kiro_tap.cli import main_entry
+
+main_entry()