kimaki 0.4.82 → 0.4.84

package/skills/npm-package/SKILL.md

@@ -152,6 +152,7 @@ Use Node ESM-compatible compiler settings:
     "declarationMap": true,
     "noEmit": false,
     "strict": true,
+    "noUncheckedIndexedAccess": true,
     "skipLibCheck": true,
     "useUnknownInCatchVariables": false
   },

package/skills/proxyman/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: proxyman
+description: >
+  Reverse-engineer HTTP APIs using Proxyman for macOS. Intercept, record, and export
+  network traffic from CLI tools and apps (Node.js, Python, Ruby, Go, curl).
+  Export as HAR (JSON) and analyze with jq. Use this skill when the user wants
+  to capture, inspect, or reverse-engineer HTTP traffic from macOS applications.
+---
+
+# proxyman — HTTP traffic capture and reverse-engineering
+
+Proxyman is a macOS proxy that intercepts HTTP/HTTPS traffic. Use it to
+reverse-engineer APIs: capture what an app sends, inspect headers and bodies,
+and build SDKs or integrations from the captured data.
+
+## Important
+
+**Always run `proxyman-cli --help` and `proxyman-cli <subcommand> --help`
+before using.** The help output is the source of truth for all commands and
+options. The CLI binary lives inside the app bundle:
+
+```
+/Applications/Proxyman.app/Contents/MacOS/proxyman-cli
+```
+
+**Proxyman GUI must be running** for the CLI to work. The CLI talks to the
+running app — it does not work standalone or headless.
+
+```bash
+open -a Proxyman
+```
+
+## Node.js, Python, Ruby, Go, curl do NOT use macOS system proxy
+
+This is critical. Even though Proxyman auto-configures macOS system proxy
+settings, **CLI tools and runtimes ignore them**. You must set env vars so
+traffic routes through Proxyman (default port 9090):
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:9090 \
+HTTP_PROXY=http://127.0.0.1:9090 \
+NODE_TLS_REJECT_UNAUTHORIZED=0 \
+  <your-command-here>
+```
+
+- `HTTPS_PROXY` / `HTTP_PROXY`: route traffic through Proxyman
+- `NODE_TLS_REJECT_UNAUTHORIZED=0`: accept Proxyman's SSL cert for Node.js apps
+- For Python: `REQUESTS_CA_BUNDLE` or `SSL_CERT_FILE` may be needed instead
+- For curl: use `--proxy http://127.0.0.1:9090 -k` or set the env vars
+
+Proxyman also has an "Automatic Setup" feature (Setup menu > Automatic Setup)
+that opens a pre-configured terminal with all env vars set. But for scripting
+and agent use, set the env vars explicitly as shown above.
+
+## CLI reference
+
+```
+proxyman-cli clear-session              Clear current captured traffic
+proxyman-cli export-log [options]       Export captured traffic to file
+proxyman-cli export [options]           Export debug tool rules (Map Local, etc)
+proxyman-cli import --input <file>      Import debug tool rules
+proxyman-cli proxy on|off               Toggle macOS system HTTP proxy
+proxyman-cli breakpoint enable|disable  Toggle Breakpoint tool
+proxyman-cli maplocal enable|disable    Toggle Map Local tool
+proxyman-cli scripting enable|disable   Toggle Scripting tool
+proxyman-cli install-root-cert <file>   Install custom root cert (requires sudo)
+```
+
+### export-log options
+
+```
+-m, --mode <mode>         all | domains (default: all)
+-o, --output <path>       Output file path (required)
+-d, --domains <domain>    Filter by domain (repeatable, only with -m domains)
+-f, --format <format>     proxymansession | har | raw (default: proxymansession)
+```
+
+**Always use `-f har`** for agent workflows. HAR is JSON and works with jq.
+
+### export-log timing bug
+
+The CLI can report "Exported Completed!" before the file is actually written.
+Add `sleep 3` after export-log before reading the file:
+
+```bash
+proxyman-cli export-log -m all -o capture.har -f har
+sleep 3
+jq '.log.entries | length' capture.har
+```
+
+## Reverse-engineering workflow
+
+This is the primary use case. Example: figuring out how Claude Code talks to
+the Anthropic API.
+
+```bash
+# 1. Make sure Proxyman is running
+open -a Proxyman
+
+# 2. Clear previous traffic
+proxyman-cli clear-session
+
+# 3. Run the target app through the proxy
+HTTPS_PROXY=http://127.0.0.1:9090 \
+HTTP_PROXY=http://127.0.0.1:9090 \
+NODE_TLS_REJECT_UNAUTHORIZED=0 \
+  claude -p "say hi" --max-turns 1
+
+# 4. Export captured traffic as HAR
+proxyman-cli export-log -m all -o capture.har -f har
+sleep 3
+
+# 5. Filter for the domain you care about
+jq '[.log.entries[] | select(.request.url | test("anthropic"))]' capture.har
+```
+
+## Analyzing HAR files with jq
+
+### List all domains and request counts
+
+```bash
+jq '[.log.entries[].request.url] | map(split("/")[2])
+  | group_by(.) | map({domain: .[0], count: length})
+  | sort_by(-.count)' capture.har
+```
+
+### Filter by domain
+
+```bash
+jq '.log.entries[] | select(.request.url | test("api.example.com"))' capture.har
+```
+
+### Request summary (method, url, status)
+
+```bash
+jq '[.log.entries[] | select(.request.url | test("api.example.com")) | {
+  method: .request.method,
+  url: .request.url,
+  status: .response.status
+}]' capture.har
+```
+
+### Full request details (headers + body)
+
+```bash
+jq '.log.entries[] | select(.request.url | test("v1/messages")) | {
+  url: .request.url,
+  method: .request.method,
+  status: .response.status,
+  request_headers: [.request.headers[] | {(.name): .value}] | add,
+  request_body: (.request.postData.text | fromjson? // .request.postData.text),
+  response_body: (.response.content.text | fromjson? // .response.content.text)
+}' capture.har
+```
+
+### Request body structure (without full content)
+
+Useful for large payloads — see the shape without the bulk:
+
+```bash
+jq '.log.entries[] | select(.request.url | test("v1/messages"))
+  | .request.postData.text | fromjson
+  | {model, max_tokens, stream,
+     system_count: (.system | length),
+     messages_count: (.messages | length),
+     tools_count: (.tools | length),
+     messages: [.messages[] | {role, content_type: (.content | type)}]
+  }' capture.har
+```
+
+### Extract specific headers
+
+```bash
+jq '.log.entries[] | select(.request.url | test("api.example.com"))
+  | {url: .request.url, auth: (.request.headers[] | select(.name == "authorization") | .value)}' capture.har
+```
+
+### Only failed requests
+
+```bash
+jq '[.log.entries[] | select(.response.status >= 400) | {
+  url: .request.url,
+  status: .response.status,
+  error: .response.content.text
+}]' capture.har
+```
+
+## Domain-filtered export
+
+If you only care about one domain, filter at export time to get a smaller file:
+
+```bash
+proxyman-cli export-log -m domains --domains 'api.anthropic.com' -o anthropic.har -f har
+```
+
+Multiple domains:
+
+```bash
+proxyman-cli export-log -m domains \
+  --domains 'api.anthropic.com' \
+  --domains 'mcp-proxy.anthropic.com' \
+  -o anthropic.har -f har
+```
+
+## SSL proxying
+
+Proxyman needs to decrypt HTTPS to see request/response bodies. For Node.js
+apps, `NODE_TLS_REJECT_UNAUTHORIZED=0` handles this. For system apps and
+browsers, install and trust the Proxyman root certificate:
+
+- Proxyman menu > Certificate > Install Certificate on this Mac
+- Or via CLI: `proxyman-cli install-root-cert <path-to-cert>`
+
+Without SSL proxying enabled for a domain, you'll see the connection but not
+the decrypted body content.

package/skills/spiceflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spiceflow
-description: "Spiceflow is a super simple, fast, and type-safe API and React Server Components framework for TypeScript. Works on Node.js, Bun, and Cloudflare Workers. Use this skill whenever working with spiceflow to get the latest docs and API reference."
+description: 'Spiceflow is a super simple, fast, and type-safe API and React Server Components framework for TypeScript. Works on Node.js, Bun, and Cloudflare Workers. Use this skill whenever working with spiceflow to get the latest docs and API reference.'
 ---
 
 # Spiceflow

package/skills/usecomputer/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: usecomputer
+description: macOS desktop automation CLI for AI agents. Screenshot, click, type, scroll, drag with native Zig backend. Use this skill when automating desktop apps with computer use models (GPT-5.4, Claude). Covers coord-map workflow, system prompts for accurate clicking, and the screenshot-action loop.
+---
+
+# usecomputer
+
+macOS desktop automation CLI. Takes screenshots, clicks, types, scrolls, drags
+using native Quartz events through a Zig N-API module.
+
+## Install
+
+```bash
+npm install -g usecomputer
+```
+
+Requires macOS + Accessibility permission for your terminal app.
+
+## Core workflow: screenshot -> click -> screenshot
+
+Every computer use loop follows this pattern:
+
+1. Take a screenshot with `usecomputer screenshot`
+2. Send the screenshot to the model
+3. Model returns coordinates to click
+4. Click using the **exact coord-map** from step 1
+5. Take another screenshot and repeat
+
+```bash
+# 1. screenshot (always use --json to get coordMap)
+usecomputer screenshot ./tmp/screen.png --json
+
+# 2. model says "click at x=400 y=220"
+
+# 3. click using coord-map from screenshot output
+usecomputer click -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"
+
+# 4. validate before clicking (optional but recommended)
+usecomputer debug-point -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"
+```
+
+**CRITICAL: always pass `--coord-map` from the screenshot output to click.**
+Screenshots are scaled (longest edge <= 1568px). The coord-map maps
+screenshot-space pixels back to real screen coordinates. Without it, clicks
+land in wrong positions.
+
+## System prompt for accurate clicking
+
+When using GPT-5.4 or Claude for computer use, the system prompt / instructions
+matter for click accuracy. Keep instructions short and task-focused.
+
+### GPT-5.4 native computer tool
+
+Use `detail: "original"` on screenshot inputs. This is the single most
+important setting for click accuracy.
+
+```ts
+// sending screenshot back to the model
+{
+  type: "computer_call_output",
+  call_id: computerCall.call_id,
+  output: {
+    type: "computer_screenshot",
+    image_url: `data:image/png;base64,${screenshotBase64}`,
+    detail: "original",  // CRITICAL for click accuracy
+  },
+}
+```
+
+Recommended resolutions when downscaling: **1440x900** and **1600x900**.
+usecomputer already scales to max 1568px longest edge which is in this range.
+
+Avoid `detail: "high"` or `detail: "low"` for computer use tasks.
+
+### System prompt template (native computer tool)
+
+```
+You are controlling a desktop application through the built-in computer tool.
+Use the computer tool for all UI interaction.
+Use only the operator prompt as the source of truth.
+<task-specific instruction here>
+Reply briefly once the task is complete.
+```
+
+### System prompt template (code execution / Playwright REPL)
+
+```
+You are operating a persistent Playwright browser session.
+You must use the exec_js tool before you answer.
+The app is already open at {url}.
+Use only the operator prompt as the source of truth.
+<task-specific instruction here>
+Reply briefly once done.
+```
+
+### Key prompt patterns from OpenAI docs
+
+These XML blocks can be added to agent instructions for better reliability:
+
+```xml
+<tool_persistence_rules>
+- Use tools whenever they materially improve correctness.
+- Do not stop early when another tool call would improve completeness.
+- Keep calling tools until the task is complete and verification passes.
+- If a tool returns empty or partial results, retry with a different strategy.
+</tool_persistence_rules>
+```
+
+```xml
+<verification_loop>
+Before finalizing:
+- Check correctness: does the output satisfy every requirement?
+- Check formatting: does the output match the requested schema?
+- Check safety: if the next step has external side effects, ask permission.
+</verification_loop>
+```
+
+```xml
+<completeness_contract>
+- Treat the task as incomplete until all requested items are covered.
+- Keep an internal checklist of required deliverables.
+- If any item is blocked by missing data, mark it [blocked] and state what is missing.
+</completeness_contract>
+```
+
+## Commands reference
+
+### screenshot
+
+```bash
+usecomputer screenshot [path] --json
+usecomputer screenshot ./shot.png --display 0 --json
+usecomputer screenshot ./shot.png --region "100,100,800,600" --json
+usecomputer screenshot ./shot.png --window 12345 --json
+```
+
+JSON output includes `path`, `coordMap`, `hint`, `desktopIndex`, `imageWidth`,
+`imageHeight`. Always use `--json` and always pass the `coordMap` value to
+subsequent click/hover/drag commands.
+
+### click
+
+```bash
+usecomputer click -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"
+usecomputer click -x 400 -y 220 --button right --coord-map "..."
+usecomputer click -x 400 -y 220 --count 2 --coord-map "..."  # double click
+```
+
+`-x` and `-y` are **screenshot-space pixels** when using `--coord-map`.
+
+### debug-point
+
+Validate coordinates before clicking. Captures a screenshot and draws a red
+marker where the click would land:
+
+```bash
+usecomputer debug-point -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"
+usecomputer debug-point -x 400 -y 220 --coord-map "..." --json
+```
+
+Use this when clicks are landing in wrong positions. Send the output image
+to the model so it can see where the marker is and adjust.
+
+### type
+
+```bash
+usecomputer type "hello"
+usecomputer type "hello" --delay 20          # per-char delay ms
+cat file.txt | usecomputer type --stdin --chunk-size 4000 --chunk-delay 15
+```
+
+### press
+
+```bash
+usecomputer press "enter"
+usecomputer press "cmd+s"
+usecomputer press "cmd+shift+p"
+usecomputer press "down" --count 10 --delay 30
+```
+
+Modifier aliases: `cmd`/`command`/`meta`, `ctrl`/`control`, `alt`/`option`,
+`shift`, `fn`.
+
+### scroll
+
+```bash
+usecomputer scroll down 5
+usecomputer scroll up 3
+usecomputer scroll down 5 --at "400,300"   # scroll at specific position
+```
+
+### drag
+
+```bash
+usecomputer drag "100,200" "400,500"
+usecomputer drag "100,200" "400,500" --coord-map "..."
+usecomputer drag "100,200" "400,500" --duration 500
+```
+
+### mouse
+
+```bash
+usecomputer mouse position --json
+usecomputer mouse move -x 500 -y 500
+usecomputer mouse move -x 500 -y 500 --coord-map "..."
+usecomputer mouse down --button left
+usecomputer mouse up --button left
+```
+
+### hover
+
+```bash
+usecomputer hover -x 300 -y 200 --coord-map "..."
+```
+
+### display / desktop
+
+```bash
+usecomputer display list --json
+usecomputer desktop list --json
+usecomputer desktop list --windows --json
+```
+
+### clipboard
+
+```bash
+usecomputer clipboard get
+usecomputer clipboard set "copied text"
+```
+
+### window
+
+```bash
+usecomputer window list --json
+```
+
+## Library usage (Node.js)
+
+usecomputer exports all commands as functions:
+
+```ts
+import * as usecomputer from 'usecomputer'
+
+const screenshot = await usecomputer.screenshot({
+  path: './tmp/shot.png',
+  display: null,
+  window: null,
+  region: null,
+  annotate: null,
+})
+
+// map model coordinates to real screen coordinates
+const coordMap = usecomputer.parseCoordMapOrThrow(screenshot.coordMap)
+const point = usecomputer.mapPointFromCoordMap({
+  point: { x: 400, y: 220 },
+  coordMap,
+})
+
+await usecomputer.click({ point, button: 'left', count: 1 })
+```
+
+## OpenAI computer tool integration
+
+```ts
+import fs from 'node:fs'
+import * as usecomputer from 'usecomputer'
+
+async function captureScreenshot() {
+  const screenshot = await usecomputer.screenshot({
+    path: './tmp/computer-tool.png',
+    display: null, window: null, region: null, annotate: null,
+  })
+  return {
+    screenshot,
+    imageBase64: await fs.promises.readFile(screenshot.path, 'base64'),
+  }
+}
+
+async function executeAction(action, coordMapStr) {
+  const coordMap = usecomputer.parseCoordMapOrThrow(coordMapStr)
+  const mapPoint = (x, y) =>
+    usecomputer.mapPointFromCoordMap({ point: { x, y }, coordMap })
+
+  switch (action.type) {
+    case 'click':
+      await usecomputer.click({
+        point: mapPoint(action.x, action.y),
+        button: action.button ?? 'left',
+        count: 1,
+      })
+      break
+    case 'double_click':
+      await usecomputer.click({
+        point: mapPoint(action.x, action.y),
+        button: action.button ?? 'left',
+        count: 2,
+      })
+      break
+    case 'type':
+      await usecomputer.typeText({ text: action.text, delayMs: null })
+      break
+    case 'keypress':
+      await usecomputer.press({
+        key: action.keys.join('+'),
+        count: 1,
+        delayMs: null,
+      })
+      break
+    case 'scroll':
+      await usecomputer.scroll({
+        direction: action.scrollY < 0 ? 'up' : 'down',
+        amount: Math.abs(action.scrollY ?? 0),
+        at: typeof action.x === 'number'
+          ? mapPoint(action.x, action.y)
+          : null,
+      })
+      break
+  }
+}
+```
+
+## Troubleshooting click accuracy
+
+1. **Always pass `--coord-map`** from the screenshot that the model analyzed.
+   Without it, coordinates are treated as raw screen coordinates.
+
+2. **Use `debug-point`** to visually verify where a click will land before
+   sending the real click. Send the debug image back to the model.
+
+3. **Retina displays**: usecomputer handles scaling internally via coord-map.
+   But if you bypass coord-map and use raw pyautogui-style coordinates, you
+   need to account for display scaling yourself.
+
+4. **Model sees wrong resolution**: if the model returns coordinates outside
+   the screenshot dimensions, it may be hallucinating. Re-send the screenshot
+   with `detail: "original"` and remind it of the image dimensions.
+
+5. **Stale screenshots**: always take a fresh screenshot after each action.
+   The UI may have changed (menus opened, pages scrolled, dialogs appeared).

package/src/ai-tool-to-genai.ts

@@ -111,6 +111,7 @@ function jsonSchemaToGenAISchema(jsonSchema: JSONSchema7Definition): Schema {
   if (Array.isArray(jsonSchema.enum)) {
     schema.enum = jsonSchema.enum.map((x) => String(x))
   }
+
   if ('default' in jsonSchema) {
     schema.default = jsonSchema.default as unknown
   }

package/src/anthropic-auth-plugin.ts

@@ -1,6 +1,13 @@
 /**
  * Anthropic OAuth authentication plugin for OpenCode.
  *
+ * If you're copy-pasting this plugin into your OpenCode config folder,
+ * you need to install the runtime dependencies first:
+ *
+ *   cd ~/.config/opencode
+ *   bun init -y
+ *   bun add @openauthjs/openauth proper-lockfile
+ *
  * Handles two concerns:
  * 1. OAuth login + token refresh (PKCE flow against claude.ai)
  * 2. Request/response rewriting (tool names, system prompt, beta headers)