codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/claude-api/shared/error-codes.md

@@ -0,0 +1,205 @@
+# HTTP Error Codes Reference
+
+This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders.
+
+## Error Code Summary
+
+| Code | Error Type              | Retryable | Common Cause                         |
+| ---- | ----------------------- | --------- | ------------------------------------ |
+| 400  | `invalid_request_error` | No        | Invalid request format or parameters |
+| 401  | `authentication_error`  | No        | Invalid or missing API key           |
+| 403  | `permission_error`      | No        | API key lacks permission             |
+| 404  | `not_found_error`       | No        | Invalid endpoint or model ID         |
+| 413  | `request_too_large`     | No        | Request exceeds size limits          |
+| 429  | `rate_limit_error`      | Yes       | Too many requests                    |
+| 500  | `api_error`             | Yes       | Anthropic service issue              |
+| 529  | `overloaded_error`      | Yes       | API is temporarily overloaded        |
+
+## Detailed Error Information
+
+### 400 Bad Request
+
+**Causes:**
+
+- Malformed JSON in request body
+- Missing required parameters (`model`, `max_tokens`, `messages`)
+- Invalid parameter types (e.g., string where integer expected)
+- Empty messages array
+- Messages not alternating user/assistant
+
+**Example error:**
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "invalid_request_error",
+    "message": "messages: roles must alternate between \"user\" and \"assistant\""
+  }
+}
+```
+
+**Fix:** Validate request structure before sending. Check that:
+
+- `model` is a valid model ID
+- `max_tokens` is a positive integer
+- `messages` array is non-empty and alternates correctly
+
+---
+
+### 401 Unauthorized
+
+**Causes:**
+
+- Missing `x-api-key` header or `Authorization` header
+- Invalid API key format
+- Revoked or deleted API key
+
+**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly.
+
+---
+
+### 403 Forbidden
+
+**Causes:**
+
+- API key doesn't have access to the requested model
+- Organization-level restrictions
+- Attempting to access beta features without beta access
+
+**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
+
+---
+
+### 404 Not Found
+
+**Causes:**
+
+- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`)
+- Using deprecated model ID
+- Invalid API endpoint
+
+**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-6`).
+
+---
+
+### 413 Request Too Large
+
+**Causes:**
+
+- Request body exceeds maximum size
+- Too many tokens in input
+- Image data too large
+
+**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
+
+---
+
+### 400 Validation Errors
+
+Some 400 errors are specifically related to parameter validation:
+
+- `max_tokens` exceeds model's limit
+- Invalid `temperature` value (must be 0.0-1.0)
+- `budget_tokens` >= `max_tokens` in extended thinking
+- Invalid tool definition schema
+
+**Common mistake with extended thinking:**
+
+```
+# Wrong: budget_tokens must be < max_tokens
+thinking: budget_tokens=10000, max_tokens=1000  → Error!
+
+# Correct
+thinking: budget_tokens=10000, max_tokens=16000
+```
+
+---
+
+### 429 Rate Limited
+
+**Causes:**
+
+- Exceeded requests per minute (RPM)
+- Exceeded tokens per minute (TPM)
+- Exceeded tokens per day (TPD)
+
+**Headers to check:**
+
+- `retry-after`: Seconds to wait before retrying
+- `x-ratelimit-limit-*`: Your limits
+- `x-ratelimit-remaining-*`: Remaining quota
+
+**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples.
+
+---
+
+### 500 Internal Server Error
+
+**Causes:**
+
+- Temporary Anthropic service issue
+- Bug in API processing
+
+**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
+
+---
+
+### 529 Overloaded
+
+**Causes:**
+
+- High API demand
+- Service capacity reached
+
+**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
+
+---
+
+## Common Mistakes and Fixes
+
+| Mistake                         | Error            | Fix                                                     |
+| ------------------------------- | ---------------- | ------------------------------------------------------- |
+| `budget_tokens` >= `max_tokens` | 400              | Ensure `budget_tokens` < `max_tokens`                   |
+| Typo in model ID                | 404              | Use valid model ID like `claude-opus-4-6`               |
+| First message is `assistant`    | 400              | First message must be `user`                            |
+| Consecutive same-role messages  | 400              | Alternate `user` and `assistant`                        |
+| API key in code                 | 401 (leaked key) | Use environment variable                                |
+| Custom retry needs              | 429/5xx          | SDK retries automatically; customize with `max_retries` |
+
+## Typed Exceptions in SDKs
+
+**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:
+
+| HTTP Code | TypeScript Class                  | Python Class                      |
+| --------- | --------------------------------- | --------------------------------- |
+| 400       | `Anthropic.BadRequestError`       | `anthropic.BadRequestError`       |
+| 401       | `Anthropic.AuthenticationError`   | `anthropic.AuthenticationError`   |
+| 403       | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` |
+| 404       | `Anthropic.NotFoundError`         | `anthropic.NotFoundError`         |
+| 429       | `Anthropic.RateLimitError`        | `anthropic.RateLimitError`        |
+| 500+      | `Anthropic.InternalServerError`   | `anthropic.InternalServerError`   |
+| Any       | `Anthropic.APIError`              | `anthropic.APIError`              |
+
+```typescript
+// ✅ Correct: use typed exceptions
+try {
+  const response = await client.messages.create({...});
+} catch (error) {
+  if (error instanceof Anthropic.RateLimitError) {
+    // Handle rate limiting
+  } else if (error instanceof Anthropic.APIError) {
+    console.error(`API error ${error.status}:`, error.message);
+  }
+}
+
+// ❌ Wrong: don't check error messages with string matching
+try {
+  const response = await client.messages.create({...});
+} catch (error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
+}
+```
+
+All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`).

package/templates/.agent/skills/claude-api/shared/live-sources.md

@@ -0,0 +1,121 @@
+# Live Documentation Sources
+
+This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.
+
+## When to Use WebFetch
+
+- User explicitly asks for "latest" or "current" information
+- Cached data seems incorrect
+- User asks about features not covered in cached content
+- User needs specific API details or examples
+
+## Claude API Documentation URLs
+
+### Models & Pricing
+
+| Topic           | URL                                                                   | Extraction Prompt                                                               |
+| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" |
+| Pricing         | `https://platform.claude.com/docs/en/pricing.md`                      | "Extract current pricing per million tokens for input and output"               |
+
+### Core Features
+
+| Topic             | URL                                                                          | Extraction Prompt                                                                      |
+| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" |
+| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.6 usage examples"         |
+| Effort Parameter  | `https://platform.claude.com/docs/en/build-with-claude/effort.md`            | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking"        |
+| Tool Use          | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md`  | "Extract tool definition schema, tool_choice options, and handling tool results"       |
+| Streaming         | `https://platform.claude.com/docs/en/build-with-claude/streaming.md`         | "Extract streaming event types, SDK examples, and best practices"                      |
+| Prompt Caching    | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md`    | "Extract cache_control usage, pricing benefits, and implementation examples"           |
+
+### Media & Files
+
+| Topic       | URL                                                                    | Extraction Prompt                                                 |
+| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Vision      | `https://platform.claude.com/docs/en/build-with-claude/vision.md`      | "Extract supported image formats, size limits, and code examples" |
+| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples"         |
+
+### API Operations
+
+| Topic            | URL                                                                         | Extraction Prompt                                                                                       |
+| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results"                                  |
+| Files API        | `https://platform.claude.com/docs/en/build-with-claude/files.md`            | "Extract file upload, download, and referencing in messages, including supported types and beta header" |
+| Token Counting   | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md`   | "Extract token counting API usage and examples"                                                         |
+| Rate Limits      | `https://platform.claude.com/docs/en/api/rate-limits.md`                    | "Extract current rate limits by tier and model"                                                         |
+| Errors           | `https://platform.claude.com/docs/en/api/errors.md`                         | "Extract HTTP error codes, meanings, and retry guidance"                                                |
+
+### Tools
+
+| Topic          | URL                                                                                    | Extraction Prompt                                                                        |
+| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" |
+| Computer Use   | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md`        | "Extract computer use tool setup, capabilities, and implementation examples"             |
+
+### Advanced Features
+
+| Topic              | URL                                                                           | Extraction Prompt                                   |
+| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- |
+| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement"                           |
+| Compaction         | `https://platform.claude.com/docs/en/build-with-claude/compaction.md`         | "Extract compaction setup, trigger config, and streaming with compaction"             |
+| Citations          | `https://platform.claude.com/docs/en/build-with-claude/citations.md`          | "Extract citation format and implementation"        |
+| Context Windows    | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md`    | "Extract context window sizes and token management" |
+
+---
+
+## Claude API SDK Repositories
+
+| SDK        | URL                                                       | Description                    |
+| ---------- | --------------------------------------------------------- | ------------------------------ |
+| Python     | `https://github.com/anthropics/anthropic-sdk-python`     | `anthropic` pip package source |
+| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | `@anthropic-ai/sdk` npm source |
+| Java       | `https://github.com/anthropics/anthropic-sdk-java`       | `anthropic-java` Maven source  |
+| Go         | `https://github.com/anthropics/anthropic-sdk-go`         | Go module source               |
+| Ruby       | `https://github.com/anthropics/anthropic-sdk-ruby`       | `anthropic` gem source         |
+| C#         | `https://github.com/anthropics/anthropic-sdk-csharp`     | NuGet package source           |
+| PHP        | `https://github.com/anthropics/anthropic-sdk-php`        | Composer package source        |
+
+---
+
+## Agent SDK Documentation URLs
+
+### Core Documentation
+
+| Topic                | URL                                                         | Extraction Prompt                                               |
+| -------------------- | ----------------------------------------------------------- | --------------------------------------------------------------- |
+| Agent SDK Overview   | `https://platform.claude.com/docs/en/agent-sdk.md`          | "Extract the Agent SDK overview, key features, and use cases"   |
+| Agent SDK Python     | `https://github.com/anthropics/claude-agent-sdk-python`     | "Extract Python SDK installation, imports, and basic usage"     |
+| Agent SDK TypeScript | `https://github.com/anthropics/claude-agent-sdk-typescript` | "Extract TypeScript SDK installation, imports, and basic usage" |
+
+### SDK Reference (GitHub READMEs)
+
+| Topic          | URL                                                                                       | Extraction Prompt                                            |
+| -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Python SDK     | `https://raw.githubusercontent.com/anthropics/claude-agent-sdk-python/main/README.md`     | "Extract Python SDK API reference, classes, and methods"     |
+| TypeScript SDK | `https://raw.githubusercontent.com/anthropics/claude-agent-sdk-typescript/main/README.md` | "Extract TypeScript SDK API reference, types, and functions" |
+
+### npm/PyPI Packages
+
+| Package                             | URL                                                            | Description               |
+| ----------------------------------- | -------------------------------------------------------------- | ------------------------- |
+| claude-agent-sdk (Python)           | `https://pypi.org/project/claude-agent-sdk/`                   | Python package on PyPI    |
+| @anthropic-ai/claude-agent-sdk (TS) | `https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk` | TypeScript package on npm |
+
+### GitHub Repositories
+
+| Resource       | URL                                                         | Description                         |
+| -------------- | ----------------------------------------------------------- | ----------------------------------- |
+| Python SDK     | `https://github.com/anthropics/claude-agent-sdk-python`     | Python package source               |
+| TypeScript SDK | `https://github.com/anthropics/claude-agent-sdk-typescript` | TypeScript/Node.js package source   |
+| MCP Servers    | `https://github.com/modelcontextprotocol`                   | Official MCP server implementations |
+
+---
+
+## Fallback Strategy
+
+If WebFetch fails (network issues, URL changed):
+
+1. Use cached content from the language-specific files (note the cache date)
+2. Inform user the data may be outdated
+3. Suggest they check platform.claude.com or the GitHub repos directly

package/templates/.agent/skills/claude-api/shared/models.md

@@ -0,0 +1,68 @@
+# Claude Model Catalog
+
+**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`.
+
+## Current Models (recommended)
+
+| Friendly Name     | Alias (use this)    | Full ID                       | Context        | Max Output | Status |
+|-------------------|---------------------|-------------------------------|----------------|------------|--------|
+| Claude Opus 4.6   | `claude-opus-4-6`   | —                             | 200K (1M beta) | 128K       | Active |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | -                             | 200K (1M beta) | 64K        | Active |
+| Claude Haiku 4.5  | `claude-haiku-4-5`  | `claude-haiku-4-5-20251001`   | 200K           | 64K        | Active |
+
+### Model Descriptions
+
+- **Claude Opus 4.6** — Our most intelligent model for building agents and coding. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window available in beta via `context-1m-2025-08-07` header.
+- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window available in beta via `context-1m-2025-08-07` header. 64K max output tokens.
+- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks.
+
+## Legacy Models (still active)
+
+| Friendly Name     | Alias (use this)    | Full ID                       | Status |
+|-------------------|---------------------|-------------------------------|--------|
+| Claude Opus 4.5   | `claude-opus-4-5`   | `claude-opus-4-5-20251101`    | Active |
+| Claude Opus 4.1   | `claude-opus-4-1`   | `claude-opus-4-1-20250805`    | Active |
+| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929`  | Active |
+| Claude Sonnet 4   | `claude-sonnet-4-0` | `claude-sonnet-4-20250514`    | Active |
+| Claude Opus 4     | `claude-opus-4-0`   | `claude-opus-4-20250514`      | Active |
+
+## Deprecated Models (retiring soon)
+
+| Friendly Name     | Alias (use this)    | Full ID                       | Status     |
+|-------------------|---------------------|-------------------------------|------------|
+| Claude Haiku 3    | —                   | `claude-3-haiku-20240307`     | Deprecated |
+
+## Retired Models (no longer available)
+
+| Friendly Name     | Full ID                       | Retired     |
+|-------------------|-------------------------------|-------------|
+| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219`  | Feb 19, 2026 |
+| Claude Haiku 3.5  | `claude-3-5-haiku-20241022`   | Feb 19, 2026 |
+| Claude Opus 3     | `claude-3-opus-20240229`      | Jan 5, 2026 |
+| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022`  | Oct 28, 2025 |
+| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620`  | Oct 28, 2025 |
+| Claude Sonnet 3   | `claude-3-sonnet-20240229`    | Jul 21, 2025 |
+| Claude 2.1        | `claude-2.1`                  | Jul 21, 2025 |
+| Claude 2.0        | `claude-2.0`                  | Jul 21, 2025 |
+
+## Resolving User Requests
+
+When a user asks for a model by name, use this table to find the correct model ID:
+
+| User says...                              | Use this model ID              |
+|-------------------------------------------|--------------------------------|
+| "opus", "most powerful"                   | `claude-opus-4-6`              |
+| "opus 4.6"                                | `claude-opus-4-6`              |
+| "opus 4.5"                                | `claude-opus-4-5`              |
+| "opus 4.1"                                | `claude-opus-4-1`              |
+| "opus 4", "opus 4.0"                      | `claude-opus-4-0`              |
+| "sonnet", "balanced"                      | `claude-sonnet-4-6`            |
+| "sonnet 4.6"                              | `claude-sonnet-4-6`            |
+| "sonnet 4.5"                              | `claude-sonnet-4-5`            |
+| "sonnet 4", "sonnet 4.0"                  | `claude-sonnet-4-0`            |
+| "sonnet 3.7"                              | Retired — suggest `claude-sonnet-4-5` |
+| "sonnet 3.5"                              | Retired — suggest `claude-sonnet-4-5` |
+| "haiku", "fast", "cheap"                  | `claude-haiku-4-5`             |
+| "haiku 4.5"                               | `claude-haiku-4-5`             |
+| "haiku 3.5"                               | Retired — suggest `claude-haiku-4-5` |
+| "haiku 3"                                 | Deprecated — suggest `claude-haiku-4-5` |